Skip to content

Latest commit

 

History

History
305 lines (285 loc) · 19.1 KB

LIMITATIONS.md

File metadata and controls

305 lines (285 loc) · 19.1 KB

Known limitations

The user-facing list of what termlens does not model, does not render, or does not claim — each with the reason and, where one exists, the accessor that says so. docs/STABILITY.md §1 (Windows) and §3 (styled history) are the decisions behind two of these; docs/DESIGN.md has the mechanics. An entry here is a documented boundary, not a bug; a change to one is a CHANGELOG entry.

Grid and geometry

  • Terminal dimensions are 2–1000 cells per axis. At one column, a double-width character overflows the backend's arithmetic; at one row, a line that wraps does the same (a one-row terminal that scrolls by newline is fine). Larger grids are refused because every snapshot costs one entry per cell.

Scrollback

  • Scrollback is bounded (1000 rows by default) and text only unless asked: scrollback_styles(true) on the builder retains cells too, so Screen::scrollback_cell keeps a masked-password assertion alive after the line scrolls off, at a measured cost the knob's docs quote. Either way Screen::locate says which region — grid or history — holds a needle, and a history column is the row's as captured: history is not reflowed, so it does not survive a narrowing resize. Otherwise a scrolled-off row has no styles and no cell addressing — and is not reflowed by a resize: rows keep the width they were captured at, by decision (Terminal::resize says why). The visible grid stays the fully-featured surface. History also outlives what clears a terminal's own: RIS and ED 3 (CSI 3 J, which clear sends, and its CSI ? 3 J and CSI 3:1 J spellings) empty a terminal's scrollback, and termlens keeps the rows it had already retained.
  • A resize that arrives while the alternate screen is up and a read has left an escape sequence open is applied to the main screen behind it as vt100 applies it, and settled when the main screen is back: a taller screen there gains blank rows above the text, a row the resize pushed is read at the width the screen has by then, and a row it pulled back and pushed again keeps the text it was first copied with (#678, #684). Any other resize is settled as it is made. The main screen is brought on display for it with bytes, and bytes would cut the open sequence.

Character sets, modes and tab stops

  • Character sets: G0–G3 designation, SO/SI locking shifts, SS2/SS3 single shifts, and two sets translated. ESC ( ) * + Ps designations, the SO/SI locking shifts, and ESC N/ESC O (SS2/SS3, one character) are modelled; the DEC Special Graphics set (0) and the UK set (A, £ at #) are translated, and every other designation — the alternate ROMs, the other national sets — is acknowledged and reads as ASCII. DECSC/DECRC save and restore this state with the cursor, in one slot per screen as xterm keeps it, and ?1049h/l save and restore it around the alternate screen. xterm's other cursor saves, CSI s/CSI u without parameters and ?1048h/l, save and restore the sets too, but the backend moves no cursor for them, and unsupported() names them. Locking shifts remain G0/G1 only (LS2/LS3 are not modelled).
  • Insert mode (IRM, CSI 4 h) pushes the rest of the row right, as ncurses's insch expects on a terminal advertising smir; RIS and DECSTR clear it, and Screen::insert_mode() reports an application that left it on. A character that wraps pushes the next row right as well, as xterm does. One exception: the characters REP (CSI n b) repeats overwrite the row even in insert mode, where xterm inserts them. Other ANSI modes the backend drops (LNM and the rest) are not modelled — and say so: Screen::unsupported() lists every sequence the emulator did not implement, in the form ^[[20h, so a test can tell a plausible-looking wrong grid from a right one. An OSC is listed by the first 64 bytes of its content, ending in … where it was cut, so an iTerm2 inline image (OSC 1337 ; File=…) is named there, not kept.
  • A soft-wrapped line is two rows. contains and find read the grid row by row and do not span the wrap; Screen::row_wrapped(row) reports the backend's record of where a line wrapped, and Screen::logical_text() joins wrapped rows back together for the assertion that spans one. The backend records a wrap only where the last column held something: a wide character that does not fit in an empty last column moves to the next row unrecorded, so on six columns abcde漢fg reads as abcde and 漢fg there.
  • Autowrap cannot be turned off. CSI ? 7 l (DECAWM reset) is not modelled: text past the right margin still wraps, and unsupported() names the sequence. CSI ? 7 h, which every ncurses program sends, asks for what the emulator already does and is not named.
  • Tab stops are the application's to set. HTS (ESC H), TBC (CSI g, CSI 3 g), CHT (CSI I) and CBT (CSI Z) all work, and a plain \t honours whatever stops are set rather than a fixed eight. RIS restores the every-eighth default (DECSTR keeps the stops, as xterm's soft reset does), and a resize extends the set into its new columns with that pattern while leaving existing stops alone. Back-tab moves to the nearest stop strictly left of the cursor, as xterm does. Only TBC 0 and TBC 3 are modelled; the rest of that family clears line tab stops, which this crate has no notion of.

Waits, frames and queries

  • wait_frame needs the application to bracket its repaints in DEC 2026 synchronized updates, and only the last 8 completed frames are retained; everything else waits with wait_until, under the three rules in DESIGN.md §2.
  • Some questions stay deliberately unanswered — kitty's CSI ? u, DECRQSS, DA3, XTVERSION, XTSMGRAPHICS (CSI ? Pi ; Pa ; Pv S, which sixel programs ask once DA1 claims sixel), the OSC 4 palette query, OSC 12, OSC 52 reads, and the other CSI … t reports, such as 11 t and 19 t (18 t, the text-area size, is answered, and the pixel sizes 14 t and 16 t are once a cell size is declared) — because a guessed reply is worse than none. An application blocked on one is named in the next timeout rather than left to hang unexplained.

Graphics and hyperlinks

  • Graphics are captured, not rendered. termlens can tell an application that kitty or sixel is available (graphics(), cell_size()), collect what it then transmits, and — with the decode feature — decode a payload into pixels. It still draws none: an image never reaches the screen grid, so what a picture looks like composited over the text under it is not assertable, and f=100 (PNG) payloads are reported unsupported rather than decoded, since termlens carries no image codec. A kitty t=f, t=t or t=s transmission is captured and reported unsupported rather than decoded: its body is a path or a shared-memory name, not pixels, and termlens never opens what a program under test points at. An unknown t= is refused on the same ground. Retention is bounded (4 MiB by default, capture_graphics); past it a payload is counted and described but its bytes are dropped, and it says so rather than decoding a prefix of itself. Support stays opt-in, so by default an application that probes is truthfully told there is none. Decoding also refuses anything above 4096x4096: every size in a payload is chosen by the program under test, and a sixel !n repeat or a declared 65535x65535 would otherwise set the allocation directly.
  • The cursor moves past an image as the declared terminal moves it, and only as far as the escape says. A Graphics::Kitty terminal moves it for a placement whose size in cells is known: from c= and r=, or from the pixel size and cell_size() — for a=p, the pixel size of the newest transmission of that image id, or, for one that names its image by number (I=) alone, of the newest transmission with that number. A PNG (f=100) placed without c= and r=, a placement of an image whose transmission has left the payload log, or one that names neither an id nor a number, does not move it. Whether kitty would have loaded the image at all is not knowable here, so a placement is taken to succeed. Past the bottom of a scroll region the protocol leaves the cursor's position open ("undefined, and up to implementations"), and termlens follows kitty 0.49: the region scrolls by as many rows as the image's last row is past the margin, and the cursor stays on that row, below the margin, clamped to the screen — or to the region, under origin mode, when only the wrap to the next row took it past the margin. It does not follow kitty for a cursor that starts below the region: kitty scrolls the region then too, and termlens moves the cursor as line feeds would there, scrolling nothing. A Graphics::Sixel terminal with a cell_size() moves it to the image's last text row, as xterm does with sixel scrolling on. Sixel display mode (CSI ? 80 h), xterm's extra scroll for a trailing - on the bottom row, and its sixel-scrolls-right mode (CSI ? 8452 h) are not modelled. A Graphics::None terminal, the default, moves nothing: it ignores both escapes.
  • The kitty capture follows kitty's graphics.c (0.49) only as far as the escapes decide it. A delete frees an image here only by id — d=I, or d=R over a range of ids, without p= — so an a=p after one is not moved. A delete that frees an image because its last placement went (p=, or a delete by position, z-index, number or frame), a screen clear or hard reset (kitty then frees every image left without a placement), the alternate screen's separate image store and kitty's storage quota are not modelled, since termlens does not track placements: an a=p after one is still sized from the payload log. A query is answered OK without kitty's test load, so one whose data kitty could not load gets an error from kitty and OK here. kitty also answers a transmission or a placement that names an image (i= or I=) with i=…;OK, unless q= asks for quiet; termlens answers only queries, because that OK reports that the image loaded, which it cannot know: it opens no file the program under test points at, and decodes only with the decode feature. Such a command is named in the next timeout instead, as an unanswered query is — an upload at its last chunk, by its first — unless it asked for quiet (#680). Frames (a=f) and composes (a=c), which kitty answers too, are neither answered nor named. A command naming both i= and I= is refused by kitty whatever its action; termlens answers a query so, but still captures, counts and places a transmission or placement that does, and names it unless q=2 silenced kitty's error. An upload interrupted by a sixel or a hard reset is undefined — "the client must finish sending all chunks for a single image before sending any other graphics related escape codes" — and termlens drops it: the chunks still to come are a transmission of their own, and no reply to the upload is named. kitty 0.49 ignores the sixel and goes on with the upload, and after a reset its loader still names the image the reset removed, so it refuses the next transmission that carries its data. And chunks that break the protocol's rule that every chunk but the last is a multiple of four base64 characters are decoded joined, not one escape at a time as kitty decodes them (#637); a stream that keeps the rule decodes exactly as kitty decodes it.
  • Hyperlinks are captured, not attributed to cells. links() reports every OSC 8 span with its target, its id, and the text it wrapped, so "did it link the right place?" is assertable — but a Cell does not carry its link, so which cells sit inside a span is not, and a span whose label was later overwritten is still reported, because this is a record of what the application emitted rather than a property of the grid. Retention is bounded to the most recent 64 spans, and a label longer than the capture bound is reported as unknown rather than as a prefix.

Out-of-band state and styles

  • Out-of-band state is what the application last asked for, not what a terminal would infer. The cursor shape follows DECSCUSR and is cleared by a hard reset (RIS); the window title is not, because in xterm the title is a window property that RIS does not restore, and guessing either way would be the same error. DECSTR (soft reset) is xterm's: it resets cursor keys, the cursor's visibility and shape, the attributes, the character sets, insert mode, the scroll margins and origin mode (leaving the cursor where it was), and homes the saved cursor; it keeps bracketed paste, mouse tracking and its encoding, focus reporting, the tab stops and the alternate screen, which xterm resets only on RIS. The keypad mode is not modelled.

  • Two SGR style attributes are not modelled. Overline (SGR 53) and double underline (SGR 21) do not reach Style, so with_styles() cannot distinguish those attributes from a plain cell. Blink reaches the ANSI, HTML and SVG renderings. The HTML one stops animating under prefers-reduced-motion; the SVG one cannot, since SMIL is not reachable from CSS — take the HTML rendering if the motion has to stop.

    And bold and dim are one intensity state, not two: the last of SGR 1/SGR 2 written wins, so a cell never reports both.

The terminal input queue

  • A reply the terminal's own input queue cannot hold may not arrive. termlens no longer drops answers of its own accord, but the tty input queue is small (~1 KB on macOS; on Linux, about 13.8 KB in raw mode and 4 KB in canonical mode), so an application that asks thousands of questions without reading has to read as it asks — as it would against a real terminal. In raw mode, the mode of an application that reads its replies, a full queue blocks the write on both platforms, and the replies stuck behind it are counted and named in the next wait's error. Only a canonical-mode application on Linux loses replies silently: there the kernel discards what does not fit, so that loss is undetectable and goes unreported.

Windows

  • Windows: screen assertions yes, frame assertions no. The crate builds and the whole suite runs on windows-latest in CI, over ConPTY through portable-pty. ConPTY is not a passthrough — it renders the child's output into a screen of its own and re-emits that — so what termlens can honestly claim there is what survives the re-render: the grid (text, cells, styles, cursor, wide characters, box drawing, title, links by URL, clipboard, bracketed paste, cursor shape, bell, the alternate screen), resize, typed input, wait_until / wait_stable / snapshot_after, bin!. What it cannot claim, and documents as Unix-only: wait_frame and frame_timings (ConPTY closes a DEC 2026 bracket before the content it wrapped); GraphicsPayload and everything under graphics (kitty and sixel never arrive); the responder's outbound claims — Graphics, background_rgb, foreground_rgb, cell_size — since DA1, OSC 10/11, XTGETTCAP and DECRQM are answered by ConPTY itself and never reach termlens; mouse_modes and mouse_mode; focus_events (ConPTY turns 1004 on for itself); link ids (ConPTY assigns its own); Terminal::signal; the tab-stop extension a resize performs (ConPTY applies ResizePseudoConsole on its own thread, so a program's output written right after a resize can be laid out at the old width — after resize() on Windows, wait for the program's own repaint before asserting on layout — and its re-render never forwards the program's HT); and bytes that are not UTF-8 (Rust's console stdio refuses to write them). The tests for each are #[cfg_attr(windows, ignore = "…")] with the reason in the attribute; the probe that measured all of this is tests/conpty_probe.rs, and the windows workflow re-runs it on demand. The windows-latest leg is a required check. This is decision 1 of STABILITY.md.
  • termlens inspect on Windows learns of an exit from the reap, not the terminal. ConPTY never reports the terminal closing, so a program that has just exited ends inspect's wait by the silence window rather than an EOF, and inspect then gives the reap 2 s (500 ms elsewhere) before its trailer calls the program still running. A program whose exit status lands later than that after its last output reads still running (killed on exit), and a program that really is still running — any TUI — waits those 2 s before it is killed. The same holds for examples/inspect.rs (#501).

Process lifetime and Unicode

  • A child that writes and exits within its first milliseconds can lose output to the OS PTY teardown (macOS especially). Long-lived TUIs are unaffected; for run-and-exit programs, end the script with a read and release it after asserting — see the "instant-exit caveat" in DESIGN.md.
  • After wait_exit, Drop signals nothing (Unix). Drop stops the program's whole process group, a helper that ignores SIGHUP included, but only while the program is unreaped: once a wait has reaped it, or the kernel has (SIGCHLD ignored), the group's id may be another process's. A helper still running in the group then runs on. Stop it before the program exits, or have it leave the group with setsid if it is meant to outlive the terminal (#714).
  • Exotic grapheme clusters render as the vt100 crate renders them; the unicode-torture fixture pins the current behaviour.
  • Needle matching is NFC, then substring, not grapheme matching. contains, find and mask_matching fold both sides to NFC, which joins a base and a mark only where Unicode has a precomposed character (e + U+0301 is é, so contains("e") misses it). Any other mark — U+0353, Thai and Devanagari vowel signs — stays a character of its own, so contains("q") is true on a screen showing only q with U+0353 under it, and a mask covers that cell. A multi-row needle has to include such a mark wherever its row ends in one, so "q\nq" is not found over two of those rows (#726). Making the match grapheme-shaped would change which needles match, so it is left for a 0.12 candidate.
  • A saved text screen from before 0.11.7 can read a VS16 emoji a column too wide. Releases up to 0.11.6 drew ⚠️ and other emoji with a presentation selector (U+FE0F) one column wide; later ones draw two, and the text format does not say which wrote a file. Screen::parse reads a row two columns wide whenever it fits, so on an old row with room after the emoji every cell after it is one column right of where it was drawn, and the styles: spans and the cursor, which keep their columns, land one character left of what they marked (#723). The file still parses and renders back as written. The JSON twin (serde) holds the columns its writer drew; keep that where they matter.