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.
- 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 is bounded (1000 rows by default) and text only unless
asked:
scrollback_styles(true)on the builder retains cells too, soScreen::scrollback_cellkeeps a masked-password assertion alive after the line scrolls off, at a measured cost the knob's docs quote. Either wayScreen::locatesays 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 aresize: rows keep the width they were captured at, by decision (Terminal::resizesays 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, whichclearsends, and itsCSI ? 3 JandCSI 3:1 Jspellings) empty a terminal's scrollback, and termlens keeps the rows it had already retained. - A
resizethat 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: G0–G3 designation, SO/SI locking shifts, SS2/SS3
single shifts, and two sets translated.
ESC ( ) * + Psdesignations, theSO/SIlocking shifts, andESC 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/DECRCsave and restore this state with the cursor, in one slot per screen as xterm keeps it, and?1049h/lsave and restore it around the alternate screen. xterm's other cursor saves,CSI s/CSI uwithout parameters and?1048h/l, save and restore the sets too, but the backend moves no cursor for them, andunsupported()names them. Locking shifts remain G0/G1 only (LS2/LS3are not modelled). - Insert mode (
IRM,CSI 4 h) pushes the rest of the row right, as ncurses'sinschexpects on a terminal advertisingsmir;RISandDECSTRclear it, andScreen::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 (LNMand 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. AnOSCis 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.
containsandfindread 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, andScreen::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 columnsabcde漢fgreads asabcdeand漢fgthere. - Autowrap cannot be turned off.
CSI ? 7 l(DECAWM reset) is not modelled: text past the right margin still wraps, andunsupported()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) andCBT(CSI Z) all work, and a plain\thonours whatever stops are set rather than a fixed eight.RISrestores the every-eighth default (DECSTRkeeps 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. OnlyTBC 0andTBC 3are modelled; the rest of that family clears line tab stops, which this crate has no notion of.
wait_frameneeds the application to bracket its repaints in DEC 2026 synchronized updates, and only the last 8 completed frames are retained; everything else waits withwait_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), theOSC 4palette query,OSC 12,OSC 52reads, and the otherCSI … treports, such as11 tand19 t(18 t, the text-area size, is answered, and the pixel sizes14 tand16 tare 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 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 thedecodefeature — 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, andf=100(PNG) payloads are reported unsupported rather than decoded, since termlens carries no image codec. A kittyt=f,t=tort=stransmission 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 unknownt=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!nrepeat or a declared65535x65535would 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::Kittyterminal moves it for a placement whose size in cells is known: fromc=andr=, or from the pixel size andcell_size()— fora=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 withoutc=andr=, 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. AGraphics::Sixelterminal with acell_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. AGraphics::Noneterminal, 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, ord=Rover a range of ids, withoutp=— so ana=pafter 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: ana=pafter one is still sized from the payload log. A query is answeredOKwithout kitty's test load, so one whose data kitty could not load gets an error from kitty andOKhere. kitty also answers a transmission or a placement that names an image (i=orI=) withi=…;OK, unlessq=asks for quiet; termlens answers only queries, because thatOKreports that the image loaded, which it cannot know: it opens no file the program under test points at, and decodes only with thedecodefeature. 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 bothi=andI=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 unlessq=2silenced 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 everyOSC 8span with its target, itsid, and the text it wrapped, so "did it link the right place?" is assertable — but aCelldoes 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 is what the application last asked for, not what a terminal would infer. The cursor shape follows
DECSCUSRand is cleared by a hard reset (RIS); the window title is not, because in xterm the title is a window property thatRISdoes 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 onRIS. The keypad mode is not modelled. -
Two SGR style attributes are not modelled. Overline (
SGR 53) and double underline (SGR 21) do not reachStyle, sowith_styles()cannot distinguish those attributes from a plain cell. Blink reaches the ANSI, HTML and SVG renderings. The HTML one stops animating underprefers-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 2written wins, so a cell never reports both.
- 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: screen assertions yes, frame assertions no. The crate builds
and the whole suite runs on
windows-latestin CI, over ConPTY throughportable-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_frameandframe_timings(ConPTY closes a DEC 2026 bracket before the content it wrapped);GraphicsPayloadand everything undergraphics(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_modesandmouse_mode;focus_events(ConPTY turns 1004 on for itself); link ids (ConPTY assigns its own);Terminal::signal; the tab-stop extension aresizeperforms (ConPTY appliesResizePseudoConsoleon its own thread, so a program's output written right after a resize can be laid out at the old width — afterresize()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 istests/conpty_probe.rs, and thewindowsworkflow re-runs it on demand. Thewindows-latestleg is a required check. This is decision 1 of STABILITY.md. termlens inspecton 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 readsstill 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 forexamples/inspect.rs(#501).
- 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
readand release it after asserting — see the "instant-exit caveat" in DESIGN.md. - After
wait_exit,Dropsignals nothing (Unix).Dropstops 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 withsetsidif 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,findandmask_matchingfold both sides to NFC, which joins a base and a mark only where Unicode has a precomposed character (e+ U+0301 isé, socontains("e")misses it). Any other mark — U+0353, Thai and Devanagari vowel signs — stays a character of its own, socontains("q")is true on a screen showing onlyqwith 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::parsereads 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 thestyles: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.