All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
0.11.0 is the stability candidate: from that release no promised item changes incompatibly before 1.0. A change that must break one ships as a new candidate (0.12.0) with a migration table and restarts the observation window of the 1.0 readiness criteria; a patch release does not. 1.0 follows those criteria, not a date.
A breaking change is always listed under a Changed or Removed heading, in a bullet that begins Breaking: — the semver gate in CI reads that marker.
0.11.10 - 2026-11-17
- termlens builds on illumos.
waitidtakes its id asid_t, which isi32on illumos and Solaris where Linux and macOS haveu32, and the widening conversion the teardown used did not compile there ("the trait boundi32: From<u32>is not satisfied"). The pid is now converted with a checked conversion. illumos is not in CI: this was run by the contributor on an illumos machine, and the workspace cross-compiles forx86_64-unknown-illumoswith clippy clean. Solaris shares the type but does not build yet:nix 0.28, whichportable-pty 0.9depends on, does not compile for it. (#748)
0.11.9 - 2026-11-11
DECSTR(soft reset,CSI ! p) resets what xterm's soft reset resets and keeps what it keeps. It turned off mouse tracking and its encoding, focus reporting and bracketed paste and restored the default tab stops, all of which xterm resets only onRIS; and it left the attributes, the scroll margins, origin mode and the saved cursor alone, which xterm resets. Now those five stay as the application set them, text after the reset is plain, the margins and origin mode are cleared with the cursor left where it was, and aDECRCafter the reset returns to the top-left corner. A test that expectedDECSTRto end mouse, focus or bracketed-paste reporting or to restore the tab stops should expect them kept, as a real xterm keeps them, and have the application reset each mode itself or sendRIS. (#687)- A reset of any mouse tracking mode turns mouse reporting off, whichever
mode is in force, as xterm does and as
Screen::mouse_modesays. AfterCSI ? 1002 hand thenCSI ? 1000 l, orCSI ? 9 hand thenCSI ? 1000 l,mouse_mode()still named the mode that was set, andclick,dragandscrolltyped reports at an application a terminal would have sent none: the backend ends reporting only on a reset of the mode it holds. The protocol is now the tracking mode set last, and none after a reset of?9,?1000,?1002or?1003.mouse_modes()and theDECRQMreplies are unchanged: they report each mode the application set and has not itself reset. The refusal now says that a reset turns reporting off, where it said that nohwas seen. A test that readmouse_mode()or clicked after such a reset should expectMouseMode::NoneandError::Input, and an application that means to go on receiving reports has to set its mode again after the reset, as it must on xterm. (#693) unsupported()no longer lists the prefixed queries the responder answers or names in the timeout:CSI ? 6 n(answered), every otherCSI ? Ps nandCSI = Ps n,CSI = c(DA3),CSI > q(XTVERSION) andOSC 12 ; ?. They were listed beside the note that named them, so a sequence termlens handled was reported twice, once as one it did not, which the rustdoc ofScreen::unsupportedsays it is not. A test that pinnedunsupported()exactly after one of these should drop that entry; the query is in the timeout note, where it always was. (#691)- The timeout note names xterm's window reports it did not:
CSI 15 t(the screen's size in pixels),CSI 13 ; 2 tandCSI 14 ; 2 t. They are questions termlens does not answer, and an application blocked on one timed out with nothing naming it, whileunsupported()listed it as a sequence nobody honoured. And the note no longer namesCSI > Ps n, XTMODKEYS's "disable", which is a setting with no reply: it said the application was blocked waiting for an answer to it. A test that matched^[[15t,^[[13;2tor^[[14;2tinunsupported()should find it in the timeout's note instead, and one that expected^[[>4nin the note should find it inunsupported(), where it was listed already. (#692) unsupported()keeps anOSCto the first 64 bytes of its content, ending the entry in…where it was cut. Each unhandledOSCwas kept whole, so an iTerm2 inline image (OSC 1337 ; File=… : <base64>) left its payload in the list, as far as the 64 KiB the tracker lets through, once per image up to 32, in every snapshot. TwoOSCs that agree in their first 64 bytes are now one entry. A test that pinned a longerOSCentry exactly should expect^[], the first 64 bytes of its content and a…, or match the entry's start withstarts_with. (#695)- The timeout's note names the most recent unanswered query, and says it may be the cause unless output arrived after it. Past the eight shapes the record keeps, a program that sent eight unanswered queries, printed, then blocked on a ninth had the ninth hidden in "and 1 more", and the verdict came from the eight it had moved past: "probably not why this wait failed". And "and N more" counted queries, so a ninth sent five times was "and 5 more"; it counts distinct shapes now. A test that matched the note after more than eight distinct unanswered queries should expect the most recent named, first when it is the cause, and a smaller count. (#690)
- A mouse release keeps the modifier keys in the legacy, UTF-8 (
?1005) and urxvt (?1015) encodings, as xterm and Windows Terminal send it: button3plus the modifier bits.click_withanddragsent a bare3, so a ctrl+click under?1000was released asCSI Mand the byte 0x23 where xterm sends 0x33. SGR (?1006) always kept them. A test that reads the release bytes of a modified click or drag in one of those three encodings should expect the modifier bits on the release too:+4for shift,+8for alt,+16for ctrl. (#701) - A kitty placement that runs past the bottom of a scroll region leaves
the cursor where kitty 0.49 leaves it: on the image's last row, below the
margin, clamped to the screen, with the region scrolled by as many rows
as that row is past the margin. termlens moved it a line feed at a time,
so the region scrolled the same but the cursor stopped on the margin:
CSI 1;10 r, the cursor on row 7 anda=T,c=2,r=5left it on row 9 where kitty leaves it on row 11. The protocol leaves this position open;docs/LIMITATIONS.mdnow says termlens follows kitty, and that it does not where the cursor starts below the region, which kitty scrolls too. A test that placed an image past a scroll region's bottom and asserted where the next text lands should expect it that many rows lower, below the margin, and no lower than the screen's last row. (#697) - A kitty transmission or placement that names an image (
i=orI=) and does not ask for quiet is named in the next timeout, as an unanswered query is: kitty answers iti=…;OK, and termlens, which cannot know whether the image loaded, sends nothing, so an application waiting for that reply timed out with no note at all. A chunked upload is named at its last chunk, by its first, andq=1orq=2keeps one out of the note. Nothing is sent on the wire either way, and an upload cut by a sixel or a hard reset is still dropped, asdocs/LIMITATIONS.mdnow says of both. A test that matches a timeout's text after its application drew a kitty image withi=orI=should expectthe application queried the terminal (^[_G…), or have the application sendq=2. (#680) - A spawned program no longer inherits
COLUMNSorLINESfrom the test process, andtermlens inspect --inherit-envno longer passes the caller's (#709). curses andtputtake both over the terminal's own size, so a suite run from a shell that exported them had its program lay out at that shell's size rather than atsize()or--size, and keep it after a resize. Without them the program asks the PTY. Set with.env()or--env, either still reaches the program as given. A test that relied on an inheritedCOLUMNSorLINESshould set it with.env(), or size the terminal withsize()instead. Screen::diffandtermlens difftake a cell that holds only whitespace for the blank a terminal shows, whichever whitespace it is. The text format strips a row's trailing whitespace by Unicode's definition, so a no-break space (U+00A0) or an ideographic space (U+3000) an application drew there parses back as blank cells, and the diff of a screen against its own snapshot, or of a text save against its JSON twin, marked a blank against a blank andtermlens diffexited 1. A no-break space is now the same as a space or an erased cell in the same style, at the end of a row or inside one, and U+3000 with the second column it takes is the same as two.==onScreen, the text and the JSON are unchanged, and DESIGN §3 lists the case with what else the text does not carry. A test that useddiffto tell a no-break space from a space should comparecell(row, col).contents()instead. (#724)Screen::to_svgdraws its text on the 9×18 px grid its backgrounds are on. Each run was one<text>laid out at the font's own advance, about 8.4 px where a cell is 9 and 14 px where a wide character takes 18, so text drifted left of its highlights along a row, ten CJK characters covered fifteen columns, and in an 80-column box the right border sat near column 74 on rows drawn as one run and at column 79 on a row where a highlight started a new one. Every<text>now says how long it is,textLengthat 9 px a cell withlengthAdjust="spacingAndGlyphs", and a run is split where narrow cells meet wide ones, so a viewer that honours it (browsers, Inkscape) fits each glyph to its cells; a CJK glyph is stretched to its two columns. A test holding ato_svgsnapshot should re-accept it after checking that each<text>gained those two attributes and that a run which opens with blanks before wide characters now starts at the first wide one, its leading blanks left out as its trailing ones were. (#725)- A
wait_frametimeout after aresizenames the resize as what the application has not repainted since: "…has not completed a repaint since the resize to 30x6…", or "1 complete frame since the resize to 30x6, 2 in total" when it repainted and no frame matched. It read "since the frame this terminal last returned", with advice about "this input", though the resize had moved the frame cursor, no frame had been returned and nothing typed. Oncewait_framereturns a frame, the message is about that frame again. A test that matched "since the frame this terminal last returned" or "since the last one returned" on a timeout after a resize should match "since the resize to" instead. (#705) - On Unix, dropping a
Terminalstops the program's process group, not the program alone, and so doestermlens inspectwhen it kills a program still running at the end of its wait. A member that ignores SIGHUP, anohuped helper or a background job that traps it, kept running after the drop, attached to a PTY nobody held: the hang-up went to the child's pid, and the kernel's own, as the session leader exits, the member ignores. The group is now hung up, then killed once the child has exited or has outlived the hang-up's grace, and the child is reaped last, so the group's id is still the child's when it is signalled. Once the child is reaped, bywait_exitor by the kernel where SIGCHLD is ignored, nothing is signalled, as before;signalstill reaches the child alone. A test whose program leaves a helper running on purpose must have the helper leave the program's process group (setsid), or the drop now kills it. (#714) - Insert Line and Delete Line (
CSI L,CSI M) with the cursor inside the scroll region move the cursor to the start of its row and cancel a pending wrap, as xterm does (#686). The cursor kept its column, so text written after one began part-way along the row, and after a full row the next character wrapped onto the line the insert had just moved down. Outside the region both are still ignored and the cursor stays. A test that expected the cursor's column, or text written after one of them, where the application left it should expect column 0, as in xterm. - A resize that makes the screen taller moves the text down only by the
rows the history holds, as xterm does, and adds the rest of the new rows
below it (#684). It moved the text down by every row that had ever
scrolled off, and filled the top with blank rows the history did not
have: with
scrollback(0)a taller screen always opened blank rows above the text, and the cursor and a saved cursor moved down with it. The main screen behind the alternate one is resized the same way. A test that expected blank rows above the text after a taller resize, or a cursor row counted from them, should expect the text to stay where it was, moved down only by the rows that came back out of history. - A resize while the alternate screen is up is settled in the history at
once, as if the main screen were on display (#678). It was settled only
when the main screen came back: a row the resize pushed into history was
read at the width the screen had by then, a row pulled back and pushed
again cut to a narrower screen kept the text it was first copied with,
and a row the terminal's bounded history dropped meanwhile stayed in
scrollback_text(). A resize that arrives while a read has left an escape sequence open is still settled on the way back, asdocs/LIMITATIONS.mdsays. A test that read the history after resizing behind a full-screen application should expect what the same resizes give with the main screen up.
-
The character sets a cursor save keeps are kept per screen, as in xterm, and
?1049hand?1049lsave and restore them around the alternate screen. A line-drawing set designated by a full-screen application leaked onto the main screen after it left, soquitprinted there drew─┤␋├, and aDECRCon the main screen restored the sets the alternate screen had saved.CSI sandCSI uwithout parameters and?1048hand?1048lsave and restore the sets too; the backend still moves no cursor for them, andunsupported()still names them. (#685) -
A cursor position report (
CSI 6 n,CSI ? 6 n) under origin mode (DECOM) counts rows from the top margin, as xterm's does. It gave the absolute row, so an application that restored the position withCUP, which counts from the margin there, put the cursor as many rows too low as the margin was deep. (#689) -
SECURITY.mdcounts the eightunsafeblocks there are: 0.11.8 addedwaitid(2)(#630), andfcntl(2)andtcflush(2)in teardown (#628). A new gate,.github/scripts/check-unsafe-blocks.sh, fails CI when the count there and the blocks incrates/*/srcdisagree (#706). -
docs/RELEASING.mdstep 2 notes that release notes consist of the section plus the definitions it links (#658), and are unaffected by the compare definitions added at the foot (#722). -
Screen::parseandtermlens renderread a text snapshot 0.11.6 wrote and every later release refused (#683): a wide character a narrowing resize stranded without its second half, left before other text when the screen widened again and the program redrew after it. The row was read two columns per wide character and refused as wider than the header declares. A row that only fits with some wide characters at one column now reads with as many of them as it needs stranded, the leftmost first, as its JSON twin holds them. The file, written by the published 0.11.6, is in the compatibility corpus. -
The JSON reader checks a screen's rows and cells against its header while it reads them (#713). It read every row first, so the 1 GiB input bound did not bound memory: a 1x1 screen whose
cellsheld 67 million empty rows, 201 MB on disk, took 1.77 GB, andtermlens renderaborted with exit 134 under a memory cap. The first row or cell past the declared size is now refused at once, andrenderanddiffexit 2 naming it. The JSON format does not change. -
Leaving the alternate screen keeps the history right after a taller resize (#682), a regression in 0.11.8. When the terminal grew while the alternate screen was up, and the application left it (
?1049l,?47lor?1047l) in the same read as output that scrolled,scrollback_text()kept a row the resize had pulled back onto the grid and lost the row that scrolled off, by where the PTY split the read. The exit is now settled before the rest of the read, as the entry is since #622. -
An unterminated OSC string no longer grows the test process without bound (#694). termlens kept 64 KiB of it, but both of the emulator's parsers kept the whole body until a terminator came: a 64 MiB body raised peak memory by 129 MiB. The body past 64 KiB is now withheld from them, and the same body costs about 1 MiB. The title reads back as before, capped at 64 KiB; an unsupported OSC past the cap is reported with its first 64 KiB rather than whole, and one under it is unchanged.
-
A sixel that paints with a colour register it never defined decodes in the VT340's colours, as the VT340 draws it (#699). Registers 0 to 15 start with its colour map and the rest black, and drawing starts in register 15, its 80 % grey. Those pixels were transparent, so
~~decoded to a 2x0 image while the cursor moved past six rows of it. A pixel no sixel touched is still transparent. -
After the emulator panics,
resizereturns the storedError::Emulator, as every wait does, and touches neither the PTY nor the grid (#702). It calledset_sizeon the panicked emulator and returnedOk: the child was told the new size whilescreen()kept the old one, and a resize back was then skipped as a no-op. Typed input and mouse reports are encoded with the modes the emulator last reported before it panicked, rather than read from it. -
The DCO gate spares a commit whose committer is
[email protected]the sign-off-equals-author match only on the push run to main, which names the squash GitHub composed (#718). On a pull request it accepted anyone's sign-off on such a commit, and the committer is set locally. The rule holds for every commit in that push, not only its tip, since one push can carry several squashes. The one pull-request exemption left is Dependabot's own commit: Dependabot signs off asdependabot[bot] <[email protected]>, never as its author address, so it is let through when its author and its sign-off are both Dependabot's. -
tools/preflight.shruns each gate with an empty standard input. Each gate was given the rest of the gate list as its input, so a gate that read it took every later gate with it: they never ran, the totals counted only the gates before them, and the run passed. No gate in CONTRIBUTING §1 reads its input today. (#719) -
A GitHub Release's notes keep a wrapped line that starts with a link label and a colon, a regression in 0.11.8.
extract-changelog.shread every such line as a link definition, so the line went missing from its section's notes and stood in for the real definition in the notes of every other section linking that label. A definition is now taken only where CommonMark lets one start, and under a line of text the line is text. No line of this file has the shape, and every released section extracts byte for byte as before. (#717) -
docs/DESIGN.md§2 lists three rules for race-free waits, the number its heading, the README,docs/LIMITATIONS.mdand the rustdoc give. It listed four. The last was a note on rule 1 underwait_frameand is now written as one, and the two rustdoc sentences that cited "rule 4" name the note. (#721) -
AGENTS.mdlists the two commit rules CI enforces, the DCO sign-off and no AI attribution. It listed Conventional Commits with a subject under 72 characters as a third that "will fail CI", and no job checks either. The commit style stays, as a convention review holds, andCONTRIBUTING.md§4 says so too. Both files now say which subject lands onmain: a pull request of one commit lands under that commit's subject and one of several under its title, where they said the title always did. (#720) -
A sixel repeat with a count of zero or with none (
!0~,!~) repeats its sixel once, as xterm and Windows Terminal read it. It painted nothing and did not advance, so~!0~~decoded two pixels wide where it is three. (#698) -
A kitty control block is read whole, however long it is. Its keys were read from the first 128 bytes of the escape, so in a longer block a value that straddled byte 127 was cut short and every key after it was lost: a first chunk whose
m=1sat there ended the upload at once, and one image sent in two chunks was counted as two. A block that names every key of a transmission and its placement at long values is about 140 bytes. The block is now kept up to 256 KiB, the length at which kitty itself gives up on an escape that is still arriving. (#700) -
A kitty placement that names its image by number (
a=p,I=7) moves the cursor underGraphics::Kitty, as kitty moves it: byc=andr=, or sized from the newest transmission with that number. It never moved, since termlens looked only for an image id. Ani=0is no id, as in kitty: with a number beside it the number decides, and without one kitty places nothing, soa=p,i=0,c=2,r=3no longer moves the cursor by itsc=andr=. (#696) -
An empty APC (
ESC _ ESC \) after a kitty escape is not a kitty escape. It was counted as a kitty transmission of 0 bytes, sographics().kittycounted an image the application never sent, and in an upload it was taken as the last chunk. Whether an APC is kitty's was read off a buffer slot the previous escape had left itsGin. (#735) -
termlens diff - missing.snapreports the missing file at once, asdiff missing.snap -has since #651. With-on the left, standard input was read to its end before the right operand was opened, which at a terminal meant Ctrl-D. The operand that is not-is now opened and measured first, so one that is missing, is a directory or is past the 1 GiB bound is refused before standard input is read. The two screens are still read in argument order. (#715) -
termlens renderandtermlens diffread a saved screen behind a byte-order mark, and in UTF-16 (#716). Windows PowerShell 5.1's>writes whattermlens inspectprints as UTF-16LE behind a mark, andOut-File -Encoding utf8puts a UTF-8 mark in front, so the CLI could not read back its own output saved in the default Windows shell: the first was refused as not UTF-8 and the second as a bad header, JSON included. A UTF-8 mark is now dropped, and UTF-16 in either byte order is decoded behind its mark; without one the input is UTF-8 as before. The 1 GiB bound holds for the decoded text too, and UTF-16 that is cut short or holds a lone surrogate is refused as not valid UTF-16. -
A screen written to
TERMLENS_ARTIFACT_DIRnever replaces a file already there (#711). The<n>in<test>-<n>.screen.*counts per process, and<test>is the test's path inside its binary, so two test binaries with a failing test of the same name, or a test that cargo-nextest retried, both wrote<test>-1, and the report showed only the second screen. The file is now created exclusively, and a taken name moves<n>on. Names are unchanged when nothing collides. -
The report action escapes a carriage return in a file name as
, as it has escaped a newline since #648 (#708). It wrote the CR raw, and CommonMark ends a line at a lone CR, so\r\rin a snapshot's path ended the HTML block the name sits in and the rest of the name rendered as Markdown: a heading, emphasis or a link in the step summary. The name now renders as one line of text. -
The report action warns when its artifact directory is relative, and the docs say
TERMLENS_ARTIFACT_DIRmust be absolute (#712).cargo testruns each test binary in its own package's directory, so a relative value put each crate's screens in that crate's directory; the action looked for the value from the workspace root and said the failures left no screen behind. It now prints a warning annotation naming the value, and its summary says the path is relative instead of that no screen was left. The value is still searched as before, so a workflow that works today is unchanged. -
The report action keeps its step summary under GitHub's 1 MiB limit (#710). It appended every screen whole and never counted, and past the limit GitHub replaces the step's whole summary with an error, small entries included: three failing 250x80 coloured snapshots came to 720 KB, so five lost the report. The action now stops adding screens before the next would pass about 900 KiB and ends the summary with a line saying how many more there are. Every screen is still rendered into the artifact.
-
DESIGN §3,
Screen::parseand LIMITATIONS say what a text screen saved by 0.11.6 or earlier reads as when a row holds an emoji with a presentation selector (⚠️) and has room after it. Those releases drew the emoji one column wide, the text does not say so, and the reader lays it out two columns wide, as 0.11.7 writes it: every cell after it moves a column right, while thestyles:spans and the cursor keep their columns and land a character left of what they marked. The 0.11.7 entry said such a row "still reads", which is true of parsing and not of the picture. The corpus now holds a pair 0.11.6 wrote, with tests pinning that reading and its difference from the JSON twin. (#723) -
Screen::containsandScreen::finddescribe their matching as it is: NFC on both sides, then a substring search. They called it "grapheme-shaped", but NFC joins a mark to its base only where Unicode has a precomposed character, so a needle matches a base character under any other mark (contains("q")on a screen showingqwith U+0353 under it), and a multi-row needle must include the mark on a row that ends in one. Which needles match is unchanged; a doctest, a unit test and LIMITATIONS now say so. (#726) -
Query replies queued behind a blocked send stay under the 1 MiB reply bound until they are written themselves. The writer thread took every byte it wrote off the count of queued reply bytes, typed input included, so once an application read a 200,000-byte
send_strit had kept waiting, the count read 0 with 120,000 reply bytes still queued, and the bound let in as many bytes over 1 MiB as the test had typed. Each write now carries how many of its bytes are replies, and only those come off the count. (#704) -
The comment in
Terminal's drop on the order it closes its handles in states the constraint the code has. It said the writer had to close before the master because the reader thread polled the master while holding the PTY lifecycle lock. The reader reads with no lock held and takes that one only to close its own duplicate of the master, which a test now pins; the order that matters is that teardown is unblocked before the writer, whose drop writes, is closed. (#707) -
docs/DESIGN.md§1 anddocs/LIMITATIONS.mdno longer say that on Linux the replies an application never reads are lost without a count. That is canonical mode's behaviour, wheren_ttykeeps 4,095 bytes, about 680 replies, and discards the rest. In raw mode, the mode of an application that reads its replies, Linux blocks the write once about 2,300 replies (13.8 KB) are queued, as macOS blocks, and the next wait's error counts the replies stuck behind it, on Linux too. (#703) -
An SGR parameter written with a sub-parameter no longer sets or clears blink, conceal or strikethrough (#688).
CSI 9:1 mstruck the cell through, and5:1and8:0made it blink or concealed it, whileunsupported()listed the same sequence as dropped;25:1,28:0,29:1and0:1cleared an attribute the same way. xterm reads sub-parameters only on SGR 38 and 48, and the backend ignores such a group too, so the style is now left as it was.unsupported()also lists the sequences it had missed because every value in them was one of those parameters, such as^[[5:6m. -
An unterminated CSI no longer grows the test process without bound (#730). Both SGR rewriters held every byte of a CSI until its final byte, to see whether it was an SGR, so a 16 MiB run of parameter bytes raised peak memory by 48 MiB. A rewriter now holds at most 256 bytes of one: past that a CSI of plain parameters is held as the parser holds it, 32 values at most and each capped at 65535, and any other passes through as it comes. A long SGR draws what the same SGR written short draws.
0.11.8 - 2026-11-03
-
A
Graphics::Kittyterminal answers kitty'sa=qquery as kitty does (#639):ESC _Gi=<id>;OK ESC \for a query naming an image id, and nothing for one that names none (i=absent or 0, orI=alone) or asks for quiet (q=1suppresses anOK,q=2every reply). termlens used to answer all of theseOK, withi=0when there was no id, which put bytes into the input of an application that had asked for none. A query without an id is now named in the next timeout instead; a quiet one is not, since the application asked for silence. A test that read thei=0;OKreply should sendi=with a nonzero id, as kitty requires. -
A kitty
a=qquery naming both an image id and an image number is refused as kitty refuses it (#672): the reply echoes itsi=andI=(andp=, if it names one) withEINVAL:Must not specify both image id and image number, and onlyq=2silences it. It was answeredOK. A test that readOKthere should drop one of the two keys. -
A kitty query with its data in the escape is part of the upload in progress, as in kitty (#672): its data is the upload's next chunk. Without
m=1it is the last one, and the upload's image is counted and placed before the query is answeredOK. Withm=1kitty removes the image being loaded: no image comes of the upload, the query gets no reply (and is named in the next timeout), and the next chunk is refused — a query sent then is answeredEILSEQ. termlens used to leave the upload alone and answer the queryOKon its own. A test should finish an upload before it probes, as the protocol requires of the client. -
unsupported()is right about three more shapes (#625, #641). A window title with a;in it (OSC 2 ; make; test) is no longer listed: the title was always honoured, andtitle()reported it whole. An ANSI mode list that names insert mode with another mode (CSI 4;20 h) is listed, asCSI 20;4 halready was, since LNM is dropped either way. XTSMGRAPHICS (CSI ? Pi ; Pa ; Pv S) is no longer listed; it is a question now, named in the next timeout as LIMITATIONS promises for a program blocked on one. A test that pinsunsupported()exactly drops any^[]0;…,^[]2;…or^[[?…Sentry from its expected list and adds a mode list such as^[[4;20hwhere its application sends one. -
The urxvt mouse encoding (mode 1015) is honoured (#640). An application that enables it gets xterm's
CSI 32;5;3Mform, decimal and with no 222 limit, where it got the legacy bytes; DECRQM answers for 1015; and the last of 1005, 1006 and 1015 set is the one in force, as in xterm, so resetting the one in force returns to the legacy form. The error for a click past column 222 no longer says the application selected the legacy encoding; it names the extended ones that would reach that far. A test that read legacy reports from an application enabling 1015 reads the urxvt form instead. -
X10 mouse tracking (
CSI ? 9 h) reports what xterm reports (#642).click_withsends the button alone, without the modifier bits, andscrollandscroll_withreturnError::Input, since the mode reports no wheel. A test that scrolled under X10 expects that error, or has its application enable?1000instead. -
Insert mode (
CSI 4 h) reserves room a character at a time, at the cursor, so the screen no longer depends on where the PTY split the output (#624). A run that reached the right margin wrapped onto the next row over its text when it arrived in one read, and pushed that row right from its second character when it arrived in pieces; now the next row is pushed right from the first character, as xterm does, which removes the exceptiondocs/LIMITATIONS.mddocumented. An emoji-presentation selector that arrives in a read of its own reserves the column it widens the emoji into, where it used to overwrite the next character. A test that asserted the overwritten row should assert the pushed one. -
The plain output of
termlens diffends with one newline, not a blank line, and an unchanged-row count of one reads… 1 row unchanged(#652).ScreenDiff'sDisplayalready ended its last line, and the CLI printed a second newline after it; "no difference" and the coloured output were not affected. The library'sDisplaysays "1 row" too. A script that comparesdiff --color neveroutput byte for byte against a file saved from 0.11.7 or earlier should drop that file's final empty line and, where the count is one, thesofrows. -
A multi-row needle no longer matches in cells a previous match used, in
Screen::find_allandmask_matching(#670). The scan resumed on the row a match ended on and took any match starting there, so on four rows readinga,find_all("a\na")was three matches, each sharing a cell with the next, and the mask covered all of them, where the rustdoc said matches do not overlap. A match may still start on that row to the right of the last cell the previous one used, counted in grid columns, so onxxxa,axxxa,axxxthe needle is still found twice. A test that assertsfind_all(…).len()for such a needle expects the non-overlapping count,[(0, 0), (2, 0)]above rather than three, and a snapshot of such a mask shows the rows no match now covers unmasked.
-
The report action writes each screen into the step summary verbatim (#648). A screen with a row of three backticks closed the action's code block early, the rows after it rendered as Markdown, and every later entry came out inside out; the fence is now longer than any run of backticks in the text. File names are HTML-escaped in the summary, and a name holding a newline is one entry rather than two that name no file. Characters upload-artifact refuses in a path are replaced in the artifact's file names, so one odd name no longer fails the upload.
-
The CI snippet in the README, the action's README and the skill works in a matrix and with any directory (#654). It passes the artifact
name:per matrix leg, since upload-artifact refuses a second artifact of one name in a run and only one failing leg's screens were kept, and passesartifact-dir:, since the test step'senv:never reaches the action: the default worked only while the directory was$RUNNER_TEMP/termlens. -
The skill says
record().stop()refuses an application without DEC 2026 synchronized updates; it saidTerminal::record(), which cannot fail, and a?on it does not compile (#659). -
The README's decode and masking examples compile (#660):
decode()andRegex::newfail with errors of their own that?cannot turn into atermlens::Error. README's Rust blocks are now compiled in CI as the skill's are. -
A GitHub Release's notes carry the link definitions their section uses (#658). They sit at the foot of CHANGELOG.md, and the v0.11.0 notes showed
[`Unsupported`]in brackets, linked to nothing, as v0.11.1's did[Keep a Changelog]. -
A label quoted inside a code span or a fenced block no longer counts as a use, so release notes no longer end with definitions nothing in them links to (#674). Quoting the two above in this file was enough to append both to these notes, and the v0.11.1 notes gained today's
[Unreleased]compare link. A link whose text is code, as in 0.11.0, still counts. -
A kitty
a=pplacement takes its size from the newest transmission of its image id (#626). When that one declared no size, a PNG for instance, the size of an older transmission of the same id moved the cursor, though kitty replaces an image on retransmission. -
A kitty placement with a huge
c=,r=,s=orv=no longer panics the emulator in a debug build, or moves the cursor by a wrapped amount in a release one (#634). The cells are computed in 64 bits and saturate. -
A sixel past the capture bound keeps its declared size, and the cursor still moves past it by its full height (#635). Both were read off the retained data, so
capture_graphics(0)reportedsize() == Noneand left the cursor where the image started. They are now measured as the stream arrives, at no extra memory. -
A kitty placement (
a=p), animation (a=a) or compose (a=c) that arrives during a chunked upload is a payload of its own, and the upload goes on to its last chunk (#636). It used to be swallowed as the upload's next chunk, so the placement was lost and neither image decoded. A transmission from a file or shared memory (t=f,t=t,t=s) arriving mid-upload starts an image of its own, as kitty does. -
Kitty data whose chunks each end in base64 padding decodes (#637). kitty decodes every escape's payload on its own and the protocol allows a padded chunk, but
decode()read the joined body once and called it bad base64. -
A sixel that paints past its declared raster size decodes to everything it painted (#638), as xterm draws it: the larger of the declared and the painted extent on each axis, still within the 4096-pixel cap. It was cropped to the declared size.
-
A kitty
a=pof an image a delete freed no longer moves the cursor (#672). Afterd=Iof its id, ord=Rover a range that holds it, kitty has forgotten the image and refuses the placement; termlens sized it from the deleted image,c=andr=or not. A lower-case delete keeps the image, as in kitty. The deletes termlens cannot attribute are listed indocs/LIMITATIONS.md. -
Screen::parseandtermlens renderread two text snapshots earlier releases wrote and 0.11.7 refused (#643): a visible cursor one past the last column (cursor: 1,6on a 6-column screen), which releases up to 0.11.1 wrote after a write filled the last cell, and a wide character a narrowing resize stranded in the last column with no second half, which releases up to 0.11.6 wrote. The cursor reads onto the last cell, as the JSON reader already read it, and the stranded character reads as that cell, so the JSON twin's own text also parses again. Both files, written by the published releases, are in the compatibility corpus. -
Screen::rect_textandmask_rectclamp an open-ended range that starts past the edge, as they clamp an explicit one (#644).rect_text(12.., ..)on a 10-column screen panicked with "column range starts at 12 but ends at 10", a range the caller never wrote, so a pane read such asrect_text(split.., ..)panicked as soon as the terminal was narrowed belowsplit. A range written backwards still panics. -
Screen::to_htmldims a run's text and no longer its background (#645). The run's span carriedopacity:0.6, which faded a coloured background into the page, whileto_svgfaded only the text over a full-strength<rect>. The span now carries the foreground blended 60% over the background, the colour the SVG's text composites to, so the two renderings paint the same picture. -
Recording::to_asciicastplaces each frame's cursor (#646). An event repainted the grid and wrote nothing for the cursor, soasciinema playandaggdrew a visible cursor after the last row of every frame, even for a program that had hidden it. Each event now ends by moving the cursor to where the test saw it and showing or hiding it as it was. -
Screen::find,find_allandmask_matchingwith a needle that spans rows no longer slow down with the needle's height (#647). Every row was rebuilt for each candidate start row it was compared from, so on a 1000x1000 screen a 400-row needle took 565 ms wherecontainstook 5 ms. Each row is now built once per call and the whole rows in the middle of the needle are matched in one pass; the same search takes as long ascontainswhatever the needle's height. -
A
ScreenDiffbetween screens of different sizes prints each row clipped to the overlap it compares (#649). The wider screen's rows were printed whole under the note saying the rest is clipped, so the│separators left the marker line's columns and the after side's^sat under the wrong cells.termlens diff --colorclips the same way and no longer leaves painted blanks at the end of the after side. A wide character cut by the overlap's edge prints as one blank, and its cell is still marked. -
Every wait takes
Duration::MAXas "no deadline", per call or as the builder'stimeout(#629). Each one added the timeout to the current instant and panicked with "overflow when adding duration to instant"; the deadline is now the furthest instant the clock can represent. -
A send under a builder
timeoutof zero, or of a few microseconds, no longer fails while its bytes are delivered (#632). It waited for the writer thread's acknowledgement for exactly the deadline, which expired before that thread had run, and the error then said the application was not reading and the buffer was full. A send now waits at least a tenth of a second, and the error claims a full buffer only when a write into it is seen blocked; it reads "a write into it was still blocked after …" where it read "no progress in …". -
spawn("sub/prog")of a file in the working directory that cannot be executed, or is not there, fails with the reason the OS gave for that file, "cannot execute …/sub/prog: Permission denied (os error 13)" or "No such file or directory (os error 2)" (#631). It reported a PATH search, "No viable candidates found in PATH", the one place the file was never meant to be; the usual case is atarget/debug/appdownloaded as an artifact without its executable bit. A program a PATH entry provides under the same name is still found. -
In a test process that ignores SIGCHLD, a terminal drops at once instead of taking two seconds, and nothing is signalled after the child has gone (#630). The kernel reaps every child itself there, and teardown read the child it had already reaped as one still running: it sent SIGHUP and SIGKILL to a pid that could belong to another process by then, and waited out its whole reap grace.
wait_exitnow fails naming the cause ("…the kernel reaped it, because SIGCHLD is ignored…") where it gave a bare "No child processes", andsignalrefuses withError::Input, as it does for a child already waited for. -
Dropping a terminal returns when the application left more input unread than its terminal holds, which a raw-mode application that stops reading allows (#628). The PTY layer writes an end-of-file as its writer is dropped, and that write waited forever on the full queue, with the child already gone, while holding the lock every spawn in the test binary takes: the binary never exited. Teardown now makes the terminal's writes give up rather than wait and empties the queue nothing will read, so the writer thread stuck behind it ends too, instead of keeping the PTY open.
-
A spawn that fails closes the terminal it opened before it releases the PTY lifecycle lock (#633). It released the lock first, so on macOS the close could revoke a device another thread had just opened, the failure the lock exists to prevent; and a spawn that failed after opening the terminal but before starting the child could deadlock on the lock it held, instead of reporting why.
-
A cursor-position or size query is answered without building a snapshot (#618). Each reply copied the whole grid, history and graphics log to read two numbers, and 0.11.7 doubled that in debug builds, so 2000
CSI 6 nat 200x50 took 10 s to answer undercargo testand the replies left in bursts several seconds apart; a reader with an inter-byte timeout, like termlens-demo's, saw them stop. The same 2000 now take about 20 ms, and the reply is the one the snapshot gave. -
CSI ? 3 JandCSI 3:1 Jkeep the history termlens had retained, asCSI 3 Jdoes (#621). vt100 erases its saved lines for both, and the tracker missed them, so the emptied history read as rows pulled back onto the screen and the kept copy was popped. -
RIS turns focus reporting off and ends an open synchronized update (#623). After
ESC c,focus_instill typed^[[I, DECRQM answeredSetfor 1004 and 2026, and an update begun before the reset never ended, so every laterwait_stabletimed out. The half-drawn frame is dropped. -
A control character inside an escape sequence is carried out and the sequence goes on, as the parser that feeds the grid does (#627). The tracker dropped to plain text there, so
ESC CRbefore line-drawing text blanked the rest of the write, and the query inESC BEL [6nwent unanswered with its bell uncounted. The same holds inside a CSI. -
An emoji with a presentation selector (
⚠️,❤️) drawn into the bottom-right cell no longer panics the emulator when the row is redrawn (#619). vt100 0.18.1 moved the wrong cell to the new bottom row and left the emoji wide in the last column of the row above, where the next write over it panicked on the reader thread and the screen stopped advancing. termlens now moves the emoji itself, to the start of the new row, as xterm does. -
A resize round trip over a soft-wrapped line no longer makes the attribute shadow diverge from the grid (#620). Copying the rows a wider, shorter screen pushed into history widened them and cleared their wrap flags, in the primary grid only unless styled history was on, so the resize back pulled different rows into the two and a debug build panicked on the next snapshot; with both moved,
row_wrappedturned false andlogical_text()split the line. -
A history at its retention bound is copied a row at a time, as below it, rather than read again whole on every output. vt100's length stops changing at the bound, so termlens re-read the window, and that read cut every retained row to the screen's width at the moment, losing the text past it after a narrower resize, and cleared the wrap flag of a row a wider resize had left narrow. The rows vt100 drops off the front are counted instead. The count also settles a resize made while the alternate screen is up: a shorter screen that pushed a row, then a taller one that pulled it back, dropped the newest retained row from
scrollback_text()although vt100 still held it (#671). -
Rows that scroll off in the same read that switches to the alternate screen (
CSI ? 1049 h,? 47 h,? 1047 h) are inscrollback_text()while the alternate screen is up, and survive a reset before it comes down (#622). They were copied only once the main screen was back, and a RIS before that lost them for good. -
termlens renderandtermlens diffaccept--as the end of their options, asinspectdoes (#650), so a file whose name begins with-can be named:termlens render --text -- -x.snap. A-after--is still standard input. -
termlens diff missing.snap -reports the missing file at once (#651). Both operands were read before either result was looked at, sodifffirst waited for standard input to end, which at a terminal meant Ctrl-D. -
termlens renderandtermlens diffrefuse an input larger than 1 GiB with exit code 2 and a message saying so (#653). They read a whole file or stream into memory with no bound, sorender --text /dev/zerooryes | termlens render --text -grew until the allocator or the OOM killer stopped them. The largest screen termlens writes — 1000x1000 cells, each styled differently, as the pretty-printed JSON — is about 600 MB, so every saved screen an earlier release wrote still reads. A regular file past the bound is refused before it is read.
0.11.7 - 2026-10-27
- The terminal emulator is vt100 0.18.1, up from 0.16.2 (#608), which brings
the screen a test sees closer to xterm's in ways a snapshot can show. A
change of height moves rows as xterm does: a shorter screen drops the rows
below the cursor, then pushes rows off the top into history, and a taller
one pulls the newest back onto the grid. 0.16 cut rows off the bottom, so
after a shrink the line the cursor was on could vanish. A VS16
emoji-presentation sequence (
⚠️,❤️) is two columns wide, asunicode-widthand ratatui lay it out; it was one, which shifted the rest of the row against the application's own layout. HVP (CSI f) and HPA (CSI `) move the cursor, which they silently did not; ED 3 (CSI 3 J) empties the terminal's history, and termlens keeps the rows it had already retained, as it does across RIS; IL and DL with the cursor outside the scroll region do nothing, where they used to edit rows outside it. None of these is listed byunsupported()any more. The MSRV stays 1.85.
- Leaving the alternate screen no longer copies the whole retained history
a second time (#576). The alternate screen's grid has no history of its
own, and its empty one was read as the main screen's history emptied, so
every trip through a full-screen program repeated every scrolled-off row
in
scrollback_text(),full_text()and the styled history. - Narrowing the terminal through a wide character and then erasing that row no longer panics the emulator (#577); vt100 0.18 keeps the row consistent.
- REP (
CSI n b) repeats the last character drawn (#578). Thexterm-256colorterminfo termlens sets advertises it, and ncurses uses it for runs of one character outside a UTF-8 locale, so a horizontal line or a row of=drew as a single character. Under insert mode the repeated characters still overwrite rather than insert, asdocs/LIMITATIONS.mdsays. - An underline colour in the form crossterm writes it (
CSI 58;5;n m,CSI 58;2;r;g;b m) no longer reads as attributes (#579). The emulator took5for blink andnfor an attribute of its own, so a cell lost its style (58;5;0reset it) or turned bold (58;5;1); ratatui writes underline colours by default. The sequence is still listed byunsupported(), now as one parameter (^[[58:5:1m). - Text is measured in the columns the grid gives it (#580). Insert mode
reserved room for a run by its string width, so a ZWJ family, lam-alef or
a skin-toned emoji overwrote the characters after it instead of pushing
them right;
Screen::locatereported a history column thatscrollback_celldid not address; and thetermlens diffframe sat a column or two off on such rows. A saved screen holding an emoji the presentation selector widened (⚠️) reads back with the columns it was written at, and a row an earlier release wrote with one column for it still reads. CSI ? 7 h, which every ncurses program sends at startup, is no longer listed byunsupported()(#581). It asks for autowrap, the only behaviour the emulator has, so no ncurses application could passunsupported().is_empty().CSI ? 7 lis still listed: autowrap cannot be turned off, asdocs/LIMITATIONS.mdnow says.Screen::row_wrappedanddocs/LIMITATIONS.mdsay that a wide character which moved to the next row because it did not fit in an empty last column is not recorded as a wrap, sological_text()splits the line there (#585).- Dropping a
Terminalno longer holds the process-wide PTY lock while the child stops (#589). It sent SIGHUP and polled in portable-pty's fixed 50 ms steps under the lock, so a drop took 50 ms (200 ms when the child ignores SIGHUP), and every spawn in the test binary waited it out. The child is now stopped first, polled from 1 ms, and the lock is taken only to close the descriptors: measured, 1 ms per drop and no wait for a concurrent spawn. The responder threads' copies of the master now close under the lock too. Error::Writeat the deadline says what happens to the bytes (#590): the write is not withdrawn, the rest of it reaches the application if it reads again, and later input queues behind it. The message and the docs said the write "gave up", so a retry typed its input twice.- A query's reply is queued before the screen the query is drawn on can be seen (#591). A test that waited for that screen and typed could have its keystroke reach the application ahead of the reply: 11 runs in 9,600 at 32 threads, and none since.
- On Unix, a program named with a directory part, such as
target/debug/app, is found from the working directory, asstd::process::Commandfinds it (#592). OnlyPATHwas searched, so the spawn failed with "No viable candidates found in PATH", or underenv_clear()could not resolvePATHat all.PATHis still searched after. - On Windows, a reaped child is the terminal closing 500 ms after the reap, however short the waits that follow (#593). Each wait restarted that grace, so waits shorter than it never saw EOF, and a send to the dead child was not refused.
termlens inspectno longer leaves screens inTERMLENS_ARTIFACT_DIRfor a run that ended normally (#596). It takes the library'sEofandTimeoutas outcomes — a program that exits, one still running at the deadline — and the library records every error that carries a screen, soinspect truewrote a failure screen the report action then listed among the failing tests. The program under inspection still gets the variable when it inherits the environment. The library's documentation of the variable now says an expected error is recorded too.termlensno longer panics with exit code 101 (#594). A closed or full stderr (2>&1 | true,2>/dev/full) made every diagnostic and theinspecttrailer panic; the write is now checked, and a trailer that cannot be written is exit 2. Arguments are read withargs_os, so one that is not UTF-8 no longer panics: termlens's own options and operands are refused with exit 2, and the programinspectruns gets its arguments untouched. A--timeouttoo large to add to the clock is refused by name instead of panicking after the spawn, andrender --out ""says--out needs a PATH argumentas--out=already did (#451). Theinspectexample mirrors all of it,--helpunder| trueincluded.Screen::parseand the JSON reader refuse a saved screen whose declared size is past the 1000-per-axis limit a terminal has (#583), with anError::Parsethat names it. The grid was allocated from the header before any line was read, so a 31-byte file declaring65535x65535madetermlens rendertry to allocate 206 GB and abort. No termlens ever wrote a screen that large.- A coloured
termlens diffno longer takes time quadratic in the number of changed cells (#595). Painting checked each cell against the whole list of changed cells, so a full-screen change on a large terminal took seconds (8 s at 80,000 cells). The changed cells are now collected once. Screen::to_svgdraws an underlined or struck-through run of blanks, such as an empty form field, with its line (#586); it trimmed the run to nothing and dropped it. The trailing blanks of any underlined or struck-through run are now drawn with the line too, as into_html.to_svgandto_htmlalso write a character XML 1.0 forbids, a C0 control other than tab, LF and CR or U+FFFE/U+FFFF, as U+FFFD, so a window title holding\x01or a cell holding U+FFFF no longer makes an SVG no parser opens.- A terminal declared to speak kitty or sixel graphics (
graphics()) moves the cursor past an image it places, as that terminal does (#588): kitty to the placement's last row, one column past its right edge, wrapping and scrolling as kitty does, unlessC=1,U=1orP=says otherwise; xterm's sixel, given acell_size(), to the image's last text row. The cursor stayed where the image began, so text an application wrote after an image overwrote it, anddocs/DESIGN.mdclaimed neither protocol moves the cursor. The default,Graphics::None, still moves nothing: a terminal without the protocol ignores the escape. A kitty transmission that names no action is now reported asa=t, transmit only, the protocol's default; it was reported as an image placed. - A chunked kitty upload (
m=1) is no longer completed by an escape that cannot continue it (#587). A sixel sent mid-upload was built on top of it: one payload, a sixel carrying the kittys=,c=/r=,t=andi=, that decoded to a transparent 4x6 instead of the red it painted. A delete (a=d) was taken as the upload's last chunk, sokitty()counted an image anddeletes()missed the teardown; any other APC was taken as a chunk too, and afterRISthe next transmission completed the upload. Only a kitty escape continues an upload now: a delete aborts it, as the protocol requires, and is counted, and a sixel orRISabandons it. An abandoned upload is no image, and its bytes still count inbytes(). Screen::find,find_all,locate,mask_matchingand, withregex,matches,find_match,find_all_matchesandmask_matchesno longer take time quadratic in the size of the screen (#584), and neither doescontainsonce the first non-ASCII cell comes late. Every row a search visited re-read the whole grid to ask whether it was ASCII, so onefindon 1000x1000 took 3 s in a release build wherecontainstook 6 ms; it now takes 5 ms. Await_untilcallingfind, andwait_until_matches, paid that on every wake-up.- The JSON reader refuses a cell no termlens could have written (#582). A
saved screen whose cell held an escape sequence loaded, and
termlens render --text,--ansianddiffthen wrote it to the terminal: an OSC set the window title andESC [2Jcleared the screen. Refused now, in the grid and the styled history, naming the cell: a control character (C0, DEL or C1, asScreen::parserefuses it), printable ASCII after a cell's first character, an empty cell marked wide or an ASCII one with no U+FE0F after it, and a wide character's second column that holds text or follows none; and a screen of no columns or rows. A tracking-mode set keeps only its four mode bits, soMouseModes::lenanditeragree. No check refuses a file a termlens wrote: a keycap such as1️⃣, a cell whose width only this build's width tables dispute, and a wide character that vt100 0.16 left in the last column after a resize all still read. - The
reportaction writes its summary when the workspace holds a directoryfindcannot read, such as a root-owned cache or achmod 000test fixture (#597). The step used to stop there with exit 1 before writing anything. The CI snippets in the README, the action's README and the skill now setINSTA_UPDATE: newbesideTERMLENS_ARTIFACT_DIR: insta's default writes no.snap.newwhenCIis set, so on GitHub Actions a failing snapshot left the action nothing to show. Inline snapshots are not rendered, and the action's README and its "nothing found" summary now say so. - The README's resize recipe for ratatui users waits with
wait_untilinstead ofwait_frame(#600).wait_framewaits for DEC 2026 synchronized updates, which stock ratatui does not emit, so the recipe timed out for exactly the readers it addressed. The torn-frame row now says it applies to an application that does emit them.
0.11.6 - 2026-10-14
- On Unix, a program that exists but cannot be executed now fails
TerminalBuilder::spawnwith anError::Spawnthat says why, andtermlens inspectexits 2 with that message (#563). Typical causes are a missing#!interpreter, an interpreter that is not a program, a missing dynamic loader, and an argument list over the kernel's limit. The message names the interpreter, with any\rthat CRLF line endings left on it shown escaped.spawnused to returnOkwith a child already killed by SIGABRT (fatal runtime error: assertion failed: output.write(&bytes).is_ok()), which inspect showed asexited: killed by signal: Aborted. portable-pty closed the pipe std reports a failed exec through, so on Unix termlens now starts the child itself. Program resolution, the environment, the session and the signals are unchanged, and the child still inherits no descriptor besides its terminal. A working directory the child cannot enter is now named in the error. A few rare setups are still left to portable-pty, as before, anddocs/DESIGN.mdlists them. - The second writer termlens opens on the PTY master is close-on-exec. A process the test started while a terminal was alive inherited it before, which kept the master open in a process unrelated to the terminal.
- With
TERMset twice through.env, XTGETTCAP'sTNreply reports the later value, the one the child gets. It reported the first, so an application could get two answers to "which terminal is this?".
0.11.5 - 2026-10-07
- The documentation was reviewed against the code, and each correction was
checked by reading the code or running it:
README.mdand the skill recommendcargo install termlens-cli --locked, the dependency set a release is tested with (#552), andAGENTS.md's layout lists thetermlens-clicrate (#553).- The skill's rule 9 gives the true reason to return
termlens::Result: a failing test prints the error'sDebugform, screen included, asunwrap()would. §6 now reads that form as well asDisplay, and its unanswered-probe row links todocs/LIMITATIONS.md(#559). Rule 10, §6 and the mask row no longer say thatformat!("{:?}")equalsDisplay, that every error carries a screen, or thatmask_matchingmatches across a soft wrap (#562). - The rustdoc gains runnable examples for
Screen::mask_matching(#551) andScreenDiff::changed_rowsandstyle_changes(#560). On docs.rs,Unsupportedno longer showsClipboard's summary, andClipboardhas one of its own (#562). docs/DESIGN.md,CONTRIBUTING.md,docs/RELEASING.md,docs/LIMITATIONS.mdandSECURITY.mdnow match the code. They cover the two translated character sets andDECSCsaving the charset state, theSHELL=/bin/shpin underenv_clear, thetools/directory, and the release checklist's two ungated copies of the version (#558). They also cover the unbounded writer queue, whichCSI … treports are answered, and Dependabot's carve-out from the bot-identity rule (#562).
- A relative
TerminalBuilder::current_dir, and sotermlens inspect --cwd ./dir, runs a relative program path such as./myappinside that directory. The directory was applied twice — the program was looked up asdir/./myappfrom insidedir— and the child died of a Rust runtime abort it could not report (fatal runtime error: assertion failed: output.write(&bytes).is_ok()), which inspect showed asexited: killed by signal: Aborted. A relative directory is now taken from the test process's own, asstd::process::Commanddoes. An absolute directory, or a bare program name found onPATH, was never affected. termlens inspect --helpandexamples/inspect.rs --helpdescribe the wait and the environment as they are: the silence window starts only once the program has drawn something; the child also getsTERM=xterm-256colorandSHELL=/bin/sh; and--inherit-envstill replaces the caller'sTERMunless--env TERM=…sets it.--cwd's argument is calledDIRin the help and in its diagnostic, beside a paragraph about thePATHvariable, and the help says a relative program path is found inside it. The CLI README's--cwdexample ran a program from the wrong directory and is corrected.
0.11.4 - 2026-09-27
- The published
termlens-clino longer ships its tests (#519), as the library stopped shipping its own in 0.11.2 (#385). Its corpus test read../termlens/tests/compat, a directory outside the package, socargo teston the download failed for everyone; the rest drove a binary built from the workspace.src/and the README are unchanged. A new gate,check-package-contents.sh, fails CI if either crate shipstests/again. - The rustdoc gains runnable examples for
Key::encode(#511) andScreen::cell, whose coordinates are row first, the opposite ofScreen::size(#512), and an# Errorssection onScreen::parse(#510). Ten doctests stopped discarding theResultof thesendthat ends them (#513). SECURITY.mdcounts the threeunsafeblocks there are,File::from_raw_fdincluded, and says the lint enforces each block's#[allow]rather than the count (#520).docs/DESIGN.mdnames all seven_forwait twins (#507), says whatDECSTRresets instead of "not modelled at all", and countsvisual_bellsamong four cumulative counters (#508). CONTRIBUTING lists every jobrequired-greenneeds (#509), andtools/preflight.sh -hprints its usage instead of refusing the flag as misuse (#518).
termlens diff --helpandtermlens render --helpsay what exit code 2 means, as the top-level help does: bad arguments, or a file that is missing or not a saved screen, and forrenderan--outpath that cannot be written.diff --helpsaid only "a file could not be read", andrender --helpstated no exit codes at all (#514).- Every
--help—termlens inspect,diff,renderandexamples/inspect.rs— names the--flag=valuespelling their parsers have accepted since 0.11.2 (#515). - On Windows,
termlens inspectandexamples/inspect.rsgive a program 2 s after the wait ends to report its exit, up from 500 ms (#501). ConPTY never reports the terminal closing, so a program that has just exited ends the wait by the silence window instead, and a shell that took more than 800 ms from its last byte to its exit status was reportedstill running (killed on exit). A program that is still running, as a TUI is, now waits the extra 1.5 s before it is killed. Nothing changes on Unix.
0.11.3 - 2026-09-23
-
termlens renderrefuses a second format flag or a second--out, naming the conflict, printing its usage and exiting 2, instead of silently keeping the last one (#450).render --svg --html screen.snapasked for an SVG and got HTML at exit 0;--out first.txt --out second.txtwrote onlysecond.txtand said nothing. This is #364's defect in the other argument position, refused for its reason: in a script the two usually come from two variables, and the loser is the one somebody meant. A repeat of the same flag is refused too. Both spellings of--outcount, a refused render creates no file, and one format with one--outbehaves exactly as before. Neither form was ever documented — the usage has always read(--svg | --html | …) [--out PATH]— but a script that passed two saw exit 0 and now sees 2. -
The 1.0 readiness criteria are a section of
docs/STABILITY.md— "The 1.0 readiness criteria", the seven of #335 verbatim — instead of an issue (#472). #335 closed on 2026-09-16 while the candidate statement in the README, this file and STABILITY.md, and three places indocs/RELEASING.md, still cited it as the live record; all of them now link the section, which is where a criterion is recorded as met. -
skills/termlens/SKILL.md's reference tables:locatehas one row instead of two that disagreed, with its accessors and why there is norow()(#459);Screen::visual_bells()andTerminal::frame_timings()have rows (#460);.record_budget(cells)states its unit and its default, 2,000,000 cells (#476). §9b names everyrenderformat, not only SVG. -
CONTRIBUTING §3 states the rule the skill gives agents first — no
sleepas a wait — and names the suite's two sleeps as its exceptions, each with a comment where it sits saying why (#474). -
docs/LIMITATIONS.mdnames one more Unix-only assertion: 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; the stress run for this release caught the test that pins the rule doing exactly that, once in 300 Windows iterations. On Windows, wait for the program's own repaint afterresize()before asserting on layout.resizeitself is unchanged and still claimed there.
-
termlens inspect --helpdocuments--, the end-of-options marker it has always accepted (#453). It changes the outcome in exactly one case, a program whose name begins with-, which is the one case where a user could not discover it: the help they were pointed at did not have it.examples/inspect.rshas documented it since 0.9.0; the command now says the same thing, and a test tells a flag-shaped program name from an option by which failure comes back. -
examples/inspect.rs --helpsays what--ansidoes, in the command's words (#473). The two usage texts were each missing a line the other had. -
termlens-cli's crates.io description names every formatrenderwrites — SVG, HTML, ANSI, the text format and JSON — instead of the three that are not byte-promised (#458). The two it left out,--textand--json, are the durable ones another program can parse. The module documentation says the same. -
termlens --verboseandtermlens -vreport an unknown option, the same word every subcommand uses for a--prefixed token, instead of an unknown command (#475). The exit is still 2 and the hint is still--help.termlens nonesuchis unchanged, and so is a baretermlens -: every subcommand reads-as standard input, not as an option. -
termlens render --out -writes to stdout, the same stream every other-operand already is, instead of creating a file named-(#469). Both spellings (--out -and--out=-) do; a file named-is still./-. A failing render still creates nothing (#313). -
termlens inspect --ansi > filewrites a saved screen — the text format with itsstyles:block — instead of raw ANSI escapes thatdiffandrenderrefused as a control character (#478). On a terminal--ansistill paints.examples/inspect.rsmirrors the command, so it moves with it. -
termlens inspect > filewrites thewith_stylesrendering, so a colour-only change is a differencediffnames, instead of the plain text that made bold red and bold green compare as the same picture (#454).render --textalready wrote the block; the two text renderings now agree. At a terminalinspectprints exactly what it printed before — the block is what a saved screen needs, not what a person reading one does, andis_terminaltells the two apart. A golden an earlierinspectsaved has no block, sodiffagainst a new one names every styled cell as changed: save it again once, with this release. -
termlens diff --colorwith no WHEN after it says--color needs a WHEN argument, the diagnostic every other flag's missing value gets, instead of printing the rawSome("…")/Noneand quietly eating the operand that followed the flag; a WHEN that is none of the three words is named quoted and alone, in both spellings of the flag (#452). -
termlens inspectends its wait on whichever comes first — the program exits, or its output has been silent for--idle— instead of waiting the whole--timeoutand only then consulting--idle(#374). A TUI that never exits paid the full deadline on every run, however complete the screen already was: 6.07s for a screen done in 1ms in the issue's reproduction, 0.76s now. The exit codes are unchanged and the wait is still bounded by--timeout. A child that outlives the wait now has two trailers rather than one, because the wait can end two ways and only one of them is the deadline:--- still running (killed on exit) ---when the silence window or an EOF ended it, and the existing--- still running at the deadline (killed on exit) ---when the deadline did. Both are stripped from a saved screen, as is the single form every release up to 0.11.2 wrote.examples/inspect.rsmirrors the command, so it moves with it. A test that matchedstill running at the deadlineagainst a TUI that goes quiet now sees the first form; matchstill running, which both carry.The silence window starts at the program's first output, not at its spawn. As first written it started at the spawn, so a program slower than
--idleto print anything — a coldshunder ConPTY, a JVM, anything that works before it paints — came back as a blank screen at exit 0, killed as still running:sh -c 'sleep 1; echo late'showed nothing, where 0.11.2 showedlate. That was caught before release, by the Windows leg, where ConPTY makesshslow enough to trip it. A program that never paints and never exits still ends at--timeout, as it did in 0.11.2, and one that exits without painting (inspect true) is still instant. -
termlens render --out=with nothing after the=says--out needs a PATH argument, the diagnostic the spelled-out--outalready gave, instead of passing the empty path to the filesystem and reportingtermlens: : No such file or directory— a message naming neither the flag nor the file (#451). An unset variable is how the empty value usually arrives, and--out=was the only=-spelled flag that did not name itself when handed one.
0.11.2 - 2026-09-17
-
termlens render --jsonwrites the screen as the format-1 JSON document ofdocs/STABILITY.md, pretty-printed and newline-terminated like the corpus files (#373).renderanddiffread that document from the start and nothing produced one, so converting text to JSON took a Rust program; now the two promised saved-screen formats are interchangeable through the CLI, in both directions. -
termlens inspectaccepts the--flag=valuespelling of--size,--timeout,--idle,--cwdand--env, the formdiff --color=andrender --out=already took (#366).--env=A=bsplits on the first=only, soAis set tob, and a bad value keeps the diagnostic naming the flag the user typed.
-
The published crate no longer ships the integration suite (#385). 86 of its 109 files were tests that cannot run from the tarball at all: they spawn fixture binaries built from workspace siblings a package cannot carry, so inside the unpacked crate that build fails outright. The frozen
tests/compat/corpus went with them — it is release engineering evidence about this repository, not material a consumer can use.src/,examples/inspect.rsand the README are unchanged, and the doctests still run. -
termlens renderrefuses anything but one file operand, printing its usage and exiting 2, instead of silently rendering the last one (#364). With--outthe wrong screen was written and nothing printed to reveal it, and a stale path left on the line after an edit went unseen. Two operands were never a documented form — the usage has always said<a>— but a script that passed them saw exit 0 and now sees 2.
-
The
inspectexample now keepstermlens inspect's promised contract. It exits 2 when inspect itself cannot run, instead of 1; the--- exited: … ---trailer goes to stderr, instead of trailing the screen on stdout, soinspect … > filesaves a screentermlens diffandtermlens renderread back (#340); and--versionprints the CLI's onetermlens <version>line, instead ofinspect (termlens …). It also takes--cwd PATHlike the command it mirrors (#312). (#372) -
An SGR the attribute shadow keeps nothing from —
ESC[31m,ESC[7m,ESC[38;5;1m— is rewritten toESC[39minstead of the empty string. The ESC introducing the sequence also terminates an unterminated OSC or aborts a half-written CSI in the primary stream, and deleting it from the shadow's stream let that parser swallow the next printable character: a debug build panicked on the divergence, and a release build read blink, conceal or strikethrough from the wrong cell (#390). -
A kitty
t=f,t=tort=stransmission is refused bydecode()instead of having its body decoded as pixels (#402). The body of those three is a path or a shared-memory name, not image data, so a small declared size returned anOkbitmap holding the ASCII of/tmp, and a larger one blamed a short payload.kitty +kitten icatuses temp-file and shared-memory transmission by default, so this was the common path for a real image, not a synthetic one. An unknown medium is refused for the same reason.GraphicsPayload::transmission()reports which one it was, as a newGraphicsTransmission; termlens still never opens the path or the mapping. -
A kitty transmission declaring a width or a height of zero is refused as malformed instead of decoding to an empty bitmap (#404).
s=andv=are the pixel dimensions of a picture, so a zero contradicts the protocol; returningOkof a 0x0 bitmap madedecode()?succeed and the assertion after it silently see nothing. Sixel already declined this by falling back to the painted extent. -
Screen::parserejects a control character in a grid row instead of folding it into the cell before it:unicode_widthanswersNonefor anESC, a tab or aDELandSome(0)for a combining mark, and the parser read both as zero width, so the raw byte survived into every rendering. AnESCfrom a snapshot maderender --svgwrite a documentxmllintrefuses to open, andto_ansiclear the screen of the reader it was printed to; a combining mark still joins its cell as before (#376). -
Screen::diffframes a row of wide characters with│at the same display column on the text line and on the marker line. The row columns were padded with{:<width$}, which countschars, so a CJK or emoji row pushed the text line's│right of the marker line's; both now pad by display width (#380). -
Screen::unsupported()preserves parameterless CSI sequences in their written form instead of inserting a synthetic0parameter (#394). -
Screen::unsupported()reports the xterm title-stack operationsCSI 22 tandCSI 23 t, which were silently dropped (#393). The wholeCSI … tfamily was exempt from the record on the grounds that the responder handles it, but the responder only answers the three size reports and names five more in a timeout; push and pop are honoured by nobody. A program that brackets its run with them leftScreen::title()reporting the pushed-away title andunsupported()empty — the pairing the accessor exists to prevent. -
Screen::unsupported()reports the set forms ofOSC 4,OSC 10andOSC 11, which were silently dropped (#392). Those numbers were exempt from the record outright, but only their?queries are handled —10;?and11;?are answered,4;n;?is named in a timeout — while the same codes also set a palette, foreground or background colour, and a set is honoured by nobody. An application that repainted its palette got the wrong colours with nothing saying so. The query forms still do not appear in the record, andOSC 8andOSC 52remain exempt in every form. -
Screen::to_svgandScreen::to_htmlrender blink (SGR 5) instead of dropping it (#378). Every otherStyleattribute already reached all three renderings, so a blinking cell produced the very same SVG and HTML as a steady one — and blink is the attribute the shadow parser exists to recover, so the regression was invisible in exactly the artefact a reviewer looks at. The SVG gets an<animate>child on the blinking<text>; the HTML gets atermlens-blinkkeyframes rule in a<style>element inside the<pre>, written only when a run blinks, animating the glyph's colour so a dim blink keeps its dim and the background keeps painting. -
A cursor pending wrap at the right margin is reported on the last cell rather than one column past it (#401). vt100 parks it at
col == cols; no real terminal reports a column its own width does not have, and the snapshot format refuses one — so a program that filled its last row madetermlens inspectprint a screenrenderanddiffwould not read. The cursor-position report and a graphics placement at the margin were off by the same column. Tab stops still read the raw column, soHTSat the margin is dropped rather than clamped onto the last cell. -
The JSON reader clamps a cursor one column past the right edge onto the last cell, instead of reading a column the grid does not have (#375). The column bound was
>where the row bound beside it was>=, socol == colspassed validation, andtermlens render --textturned a JSON file it had accepted into a text file its own parser then refused. That column is the pending-wrap position a screen carries after a write fills the last row, and every release up to 0.11.1 wrote it — so refusing the file, the first fix considered, would have made JSON those releases saved unreadable, which the format promise indocs/STABILITY.mdforbids. Clamping reads it onto the cell #401 now reports it on; a cursor anywhere else off the grid is refused as before, andtests/compat/0.11.1/pending-wrap.json, written by the published 0.11.1, holds every later reader to it. -
A hard reset (
ESC c, RIS) no longer drops scrollback rows. The reset rebuilt the backend's screen and emptied its history while the high-water mark of rows already captured survived, so rows scrolling after it were compared against a stale mark and skipped — and which rows were lost depended on how the PTY chunked the writes (#391). Rows that scrolled before the reset are now taken before the reset reaches the screen, and the mark starts over afterwards. -
XTVERSION probes are named in unanswered-query timeout diagnostics (#403).
-
The 222-coordinate ceiling applies only to the legacy mouse encoding (#395).
CSI ?1005hexists precisely so a coordinate above 222 can be sent as a UTF-8 scalar, and termlens already encoded it correctly — the guard simply ran before the encoding was consulted. So a click on the right half of a wide terminal was refused against an application that had chosen 1005, and the refusal named an encoding the application had not selected. -
Screen::logical_text()keeps the blank rows above the first row with content, so on a screen with no wraps it isScreen::text()exactly — leading blanks and an all-blank screen included. A TUI that left its top row blank had every logical line shifted up, since trailing blank rows were kept and leading ones were not. (#377) -
A
Recorderdropped withoutstop()stops collecting frames (#396). An early return, a?or a panic betweenrecord()andstop()left the reader thread cloning a whole grid into the recorder on every repaint, filling its 2M-cell budget — about 200 MB once measured — for the life of the terminal, while the test that paid for it was whichever one ran longest afterwards. Dropping a recorder now deregisters it exactly asstopdoes. -
Terminal::resizeto the size the grid already has is a true no-op: noTIOCSWINSZ, noSIGWINCH, and the frame cursor stays where it was, so thewait_frameits rustdoc recommends still sees the frame the application last drew. The cursor used to advance although the application was never told, and the wait could only run out its deadline — the shape a parameterised layout test produces when its size list repeats one (#397). -
An asciicast export emits a v2 resize event whenever a frame's geometry differs from the one before it (#398). The header took its width and height from the first frame and nothing ever corrected them, so a recording spanning a
resizereplayed every later frame into a player told the terminal was still the original size —asciinema playandaggwrapped and clipped it. A responsive-layout bug is exactly the kind you attach a recording of, so it was the one recording that rendered wrong. -
The JSON
styleobject writes its eight attribute booleans in SGR order, as DESIGN §3 specifies.Styledeclaredreversebeforeblink— serde follows declaration order — so the emitted document put reverse (SGR 7) before blink (SGR 5) where the spec, the text format'sstyles:block and the ANSI rendering all put blink first. Serde reads by key, so every existing document still deserialises; only the emitted key order and theDebugorder moved, and a test pins the order now (#381). -
termlens diff --color alwaysprints the line saying a comparison of differently sized screens was partial (#365).colored()took exactly one header line and its prefix filter then dropped the overlap note, which starts with neither…norstyles:— so the note stood in a CI log and vanished at a terminal. The header is now passed through up to the first row, detected by the row shape, and a header line added later will survive the same way. Rows, the…line and thestyles:lines render as before, andno differencestill prints alone.
0.11.1 - 2026-09-16
-
Recording::duration()— how long a recording spans,Duration::ZEROwhen it holds no frame (#307). The span runs fromTerminal::recordto the end of the last complete frame, not the program's lifetime; it is theframes().last()arithmetic every caller was writing by hand. -
The asciicast header carries
timestamp,durationandtitle(#309). A.castattached to a bug report or a CI artifact now has a date and a name inasciinemaand in the web player, where before it had neither. The title is the command the terminal spawned; the timestamp is taken at export, and is omitted rather than written as0if the clock is set before the epoch. -
Screen::to_svggives the image an accessible name:role="img"on the root and a<title>first child readingtermlens screen, 80x24, with the application's ownScreen::titleafter it when one was set (#316). These files exist to be attached to a pull request, where an image with no accessible name is announced as nothing at all. The title is escaped with the same helper the text rows use. -
termlens diffandtermlens renderread-as standard input (#317). A saved screen most often arrives on a pipe, and-is the convention for that. Only one ofdiff's two operands may be-; both is a one-line diagnostic and exit 2, since stdin is read once. -
termlens render --out PATHwrites the rendering to a file instead of stdout, and creates nothing when the render fails (#313). A shell redirect cannot promise that:> file.svgtruncates before termlens runs, so a failed render leaves an empty image behind. -
termlens inspect --cwd PATHruns the program inPATH, whichTerminalBuilder::current_dircould already do and the command line could not (#312). A path that is not an existing directory is refused by name, in one line, with exit 2.
-
Every version heading in this file now links to its compare view, as Keep a Changelog specifies and this file's own header claimed (#319).
[Unreleased]compares the newest tag toHEAD. Release notes are unaffected:extract-changelog.shstops collecting at the definitions, so the notes for every published version are byte-identical to before. -
docs/DESIGN.md§3 now namesScreen::parseand says what a round trip through the text format preserves and what it does not (#305). The spec had never mentioned its own reader. -
The
reportaction writes each SVG and HTML rendering withrender --outinstead of a shell redirect, so a screen the CLI cannot read leaves no empty file in the uploaded artifact. Pin the action at the same tag as the CLI it installs ([email protected]); the flag is new in 0.11.1.
- Four
queries.rstests, and the class they belong to, no longer put a sub-second deadline on the wait that also had to cover the spawn (#360). On a loaded Windows runner ConPTY holds a child through its startup handshake for longer than 500 ms, and the stress workflow saw them time out with an empty grid. Test-only; nothing a consumer installs changed.
0.11.0 - 2026-09-11
-
Breaking:
Screen::unsupported()returns anUnsupportedview instead of&[Arc<str>], andScreen::unsupported_overflow()is removed — the view carries the count (#330). The one breaking change of the 0.11 stability candidate, and the last before 1.0.The old return type was the storage:
Arc<str>is how the screen keeps the list cheap to clone, and exposing the slice locked that representation into the public API for good. The ergonomics showed it — consumers wrote.iter().map(|q| &**q)to get at plain strings, and "nothing was dropped" took two calls. The view isCopy, borrows the screen, and compares equal to an array or slice of&strwhen the retained shapes match in order and nothing overflowed, so a pin is one line:assert_eq!(s.unsupported(), ["^[[59m"]);.0.10 0.11 s.unsupported().is_empty()unchanged (and now also false when shapes overflowed) s.unsupported().len()unchanged — the retained count, at most 32 s.unsupported().iter().map(|q| &**q)s.unsupported().iter()s.unsupported().iter().map(|q| q.to_string()).collect::<Vec<_>>()s.unsupported().iter().map(str::to_owned).collect::<Vec<_>>()s.unsupported().iter().any(|q| &**q == "^[[5m")s.unsupported().contains("^[[5m")&*s.unsupported()[0]s.unsupported().iter().next()s.unsupported_overflow()s.unsupported().overflow()assert!(s.unsupported().is_empty()); assert_eq!(s.unsupported_overflow(), 0);assert_eq!(s.unsupported(), []);orassert!(s.unsupported().is_empty())Debugprints["^[[59m"], or["^[[20h", …] (+8 more)when shapes overflowed.UnsupportedIteris the view'sIntoIteratortype.What the semver gate saw, forced to
patchagainst 0.10.3, in all three feature views:inherent_method_missing: Screen::unsupported_overflow. The changed return type ofunsupported()itself is not a lintcargo-semver-checks0.50.0 has, which is worth knowing about the gate: it catches a removed or gated item, not a re-typed one; the in-tree tests and every consumer's compile do. -
docs/STABILITY.mdnow states the contract the candidate freezes under (#328), and every sentence of it names the job or test that checks it or says that nothing does. Promised: the documented public API of every termlens-owned item in every supported feature configuration (semverandfeaturesjobs), the snapshot text format and the versioned JSON (the compatibility corpus), the CLI's commands, flags, exit codes and input formats (check-cli-contract.shagainst the tree and the published binary), the coordinate conventions, the platform list and the MSRV policy. Named as third-party boundaries, and nothing else delegated: theinstare-export and macro, theregex::Regexparameter type, the serde traits. Not promised: diagnostic prose, internal representation, the timing of the settle heuristics, the budgets' defaults, the renderers' exact bytes. The former "versioned with the feature's dependency" clause — which exempted termlens-owned items such asBitmap,find_matchand the JSON shape from termlens's own versioning — is gone. The README and this header carry the candidate statement in the same words, and.github/scripts/check-candidate-statement.shfails when one drifts. -
The release and contribution process for the candidate is written down (#334).
docs/RELEASING.md: what may break and how a break is declared (thebreakinglabel, the pasted diagnostics, the- **Breaking:**bullet), release candidates asv1.0.0-rc.Npre-releases, the stress workflow on the exact commit to be tagged, the corpus directory frozen at each release, and the semver baseline moved after publish.CONTRIBUTING.md§1 lists every new gate and §7 says the API is frozen. The skill describes 0.11: the stability statement, theUnsupportedview,cursor_visible(), the new accessors, and thatinspect's stdout is a saved screen.
-
A frozen saved-screen corpus (#327). Nothing pinned that a file written by 0.10.1 still parses: the insta snapshots are re-recorded when output changes, so a change to the header, the
styles:block or the JSON shape would have updated them and passed.crates/termlens/tests/compat/0.10.1/holds six shapes — plain text, every style token, a hidden cursor, wide and combining characters, a masked screen, and the style-blind text of a styled screen — each with its JSON twin, written by the published 0.10.1 through a registry dependency. A file there is never edited; a new version adds a directory.tests/compat.rsparses every text file and re-renders it byte for byte, reads every JSON twin as the same picture and re-serialises it to its own document, and the CLI suite renders each file withtermlens render --text. Editing a corpus file was observed to fail the test. -
The JSON a
Screenserialises to carries"format": 1(#329), first in the document.termlens diffandtermlens renderread that JSON back as a saved artifact, so it is a persisted format, not a wire between two copies of one version, and it now says which shape it is. A file written by 0.10 has no such field and reads as format 1, since that is what it is; a number this build does not know is refused with a message naming both numbers. The shape is specified indocs/DESIGN.md§3 beside the text format: field names, the cursor object, how a hidden cursor and wide/continuation cells are encoded, and that nothing aScreenholds is omitted. -
Screen::cursor_visible()(#331). The tuplecursor()returns is unchanged; the new accessor is for the assertion that readss.cursor().2today and says nothing at the call site. -
termlens::ScreenWithStylesis exported (#332).Screen::with_stylesreturned it, but the type lived in a private module and was not in the crate's re-export list — reachable but unnameable, so it could not be stored in a field or returned from a helper. A doctest names it from a consumer. -
Location::is_on_screen(),is_in_history()andcol()(#306), for the one-fact questionsScreen::locateis asked most — "still visible?" and "what column?" — without amatch. Deliberately norow(): a grid row and a history row are different things, and the rustdoc says so. -
ScreenDiff::changed_rows()andstyle_changes()(#308). The diff computed both and exposed neither, so a test that wanted "the highlight moved from row 1 to row 2 and nothing else changed" dedup'dcells()or matched a substring of the rendering. Both read fields already stored; the rendering is unchanged. -
ColorimplementsDisplay(#315), producing exactly thestyles:block token —4for an indexed colour,#1e1e2efor RGB, and the worddefaultfor [Color::Default], which the block never writes because a default-styled span is omitted. The block now uses it, so the two halves of the documented format — this andScreen::parse— sit together; every existing snapshot is unchanged. -
A semver gate on every pull request, forced and per feature view (#323). The only check was in
release.yml, on the tag, and it let the version number decide how much to check: a0.10 -> 0.11bump is inferred as a major release and every check is skipped, so a public function removed in the same PR as the bump passed. And--all-featurescannot see an item moved behind a feature — that view never loses the item — while Cargo calls exactly that a major change.ci.ymlnow runscargo-semver-checksagainst the last published release with the release type forced topatch, three times: default features, only explicit features, all features. A deliberate break carries thebreakingpull-request label and is recorded in this file as a- **Breakingbullet, which is what keepsmaingreen after the merge where no label exists; either declaration switches the run tomajor(minorstill fails a removed item on a 0.x crate — measured, and pinned).tools/semver-gate-selftest/holds three one-file model crates and a script that asserts the gate fails on a removed item and on a gated item, and passes the baseline against itself, so the gate was seen to fail before it was trusted to pass. The baseline is a literal inci.yml, moved after each publish (docs/RELEASING.md). -
The MSRV job compiles every feature configuration (#325). It ran
--all-targetsunder the default set only, sodecode,regexand the library'sserdecode had never met Rust 1.85 in CI while the README advertised one MSRV for the crate. Both ends of the feature axis compile at the floor today, without a bump.
-
termlens inspect … > filesaves a screendiffandrenderread (#340).inspectwas the only command that produced a screen and the only two that consumed one refused its output: the--- exited: … ---trailer went to stdout under the screen, so a redirect captured it andrenderexited 2 on line 26. Measured against the published 0.10.2; no flag suppressed it, and the workaround was aseda user had to invent. The trailer now goes to stderr — a human at a terminal still sees both — and stdout carries the screen alone. The CLI also drops exactly those three trailer shapes when they are the last line of a file, so a screen saved by a 0.10inspectreads too; a grid row that merely begins with---is content.docs/DESIGN.md§3 now says what a reader skips at each end of a file and thatScreen::parseskips neither..github/scripts/check-cli-contract.shasserts the round trip against the published binary on every release; run against the published 0.10.3 it fails on exactly this. -
The minimal library build is now actually tested (#324). Cargo unifies features across every package in one invocation, and
termlens-clidepends on the library withfeatures = ["serde"], socargo test --workspace --no-default-featurestested a library withserdeon. Thefeaturesjob selects the library alone for each reduced configuration and asserts the isolation (.github/scripts/check-feature-isolation.sh). It was not hypothetical:tests/record.rsusedserde_jsonunconditionally, andcargo test -p termlens --no-default-featuresdid not build until this release added it as a dev-dependency.
0.10.3 - 2026-09-10
-
Every link on the crates.io page pointed at a 404 (#341). The root README is shipped as this crate's readme (
readme = "../../README.md"), and crates.io rewrites a relative link against the crate's directory in the repository rather than the repository root — sodocs/DESIGN.mdbecame…/blob/HEAD/crates/termlens/docs/DESIGN.md, and all ten relative links on the 0.10.2 page were dead: the design, stability, limitations and backends documents, the skill, the changelog, contributing, security, both licences and the stress workflow.Nothing here could see it. The same file renders correctly on GitHub, where it really is at the root, so the bug existed only on the surface most new readers arrive at.
The links are absolute now, and
.github/scripts/check-readme-links.sh(inci.yml) refuses a relative one — and separately checks that every absolute target still exists in the repository, offline, which catches a renamed file that a link checker asking GitHub would miss.Fixed for future releases only: crates.io renders each version's readme as published, so the 0.10.2 page and earlier stay as they are.
0.10.2 - 2026-09-10
-
The published CLI is installed and held to its documented contract (#326).
install.ymlverifiedcargo add termlensand nevercargo install termlens-cli, so #310 —termlens inspect --versionexiting 2 — shipped in 0.10.0, shipped again in 0.10.1, and was found by a user of the published binary rather than by anything here.A
clijob installstermlens-clifrom crates.io on Linux and macOS — every run, never from a cache — and asserts every exit codetermlens --helpdocuments:--versionin all four positions returning the same string,inspectprinting a screen with its header and trailer,renderin all four formats, anddiffreturning 0 for the same picture, 1 for a different one and 2 for input it cannot read.The assertions live in
.github/scripts/check-cli-contract.shand take the binary to exercise, so the same script runs against a path build.ci.ymldoes exactly that on every pull request: the published check is the net, the tree check is the fast feedback. Re-introducing #310 locally was observed to fail it.
-
unsupported()no longer names the four SGR parameters the attribute shadow implements (#320).5/25(blink),9/29(strikethrough), and6/8/28with them are exactly whatemu/shadow.rsexists to recover: vt100 drops them, the shadow parser puts the attribute on the cell, and the tracker then reported the backend's gap under an accessor documented as naming the emulator's.The consequence was the one the accessor was added to prevent, inverted: a screen said
Style::blinkwas true andunsupported()said^[[5mhad been dropped, at the same instant — so a reader checking the list before trusting a blink or masked-password assertion concluded a correct assertion was unreliable, andassert!(screen.unsupported().is_empty())could never pass for an application that uses either attribute.Found by
termlens-demodriving a real ratatui application against the published 0.10.1, which is what the testing tier is for.What still gets named. An SGR with one parameter nobody models keeps the whole sequence:
^[[59m(underline colour) alone, and^[[5;59m, where blink is recovered and59is not. Dropping a mixed sequence because part of it is implemented would hide a real gap.The residue, measured rather than assumed.
^[[1;5;31mis still named although bold, red and blink all reach the cell —1and31are vt100's to implement, and this tracker knows what the shadow recovers, not what the backend does. Narrowing that needs vt100's own SGR surface enumerated, which is more than a patch should claim; a test records the behaviour so it is a documented edge rather than a surprise. -
termlens <subcommand> --versionis no longer an unknown option. The flag was handled only in the top-level dispatch, sotermlens inspect --versionexited 2 while-h/--helpworked in that position. All three subcommands now print the same version string as the top-level command. (#310)
0.10.1 - 2026-09-08
- The stress workflow runs on Windows too. It hunted flakes on Linux
and macOS only, which left the newest leg — required since 0.10 — as the
one whose liveness is synthesized rather than observed: Unix reads the
terminal-closed edge off the kernel (EOF on the master), while Windows
manufactures it from a reaped child plus a drain grace, and polling with
a grace window is the shape a one-in-N flake lives in.
fixtures' in-testcargo build -pis the other, on the one filesystem that refuses to relink a running.exe. Same five--test-threadsshards, different faults at the ends of the axis, and double the per-shard clock because a Windows iteration costs two to three times a Linux one. (#290)
-
An exported recording scrolled every frame up by one row.
Screen::to_ansiends every row with a newline, the bottom one included — right for a file, wrong for a repaint: replayed, that last linefeed sits on the last row and scrolls the picture away, soasciinemashowed a screen the test never saw.Recording::to_asciicastnow drops exactly that newline. The regression test replays each exported event into a terminal of the recorded size and compares every row against the frame it came from, rather than checking the event's shape. (#295) -
Screen::parsedeleted grid rows that read like a styles block. The split between grid and metadata was a search for astyles:marker, and a screen can contain that word: a snapshot of one came back blank. The header's row count now decides where the grid ends, which is unambiguous for anythingDisplaywrote. The one input that cannot be read both ways — a hand-trimmed grid that also carries a styles block — resolves as content and says so in the rustdoc, because a wrong row of text shows up in a diff and a silently dropped one does not. (#296) -
Screen::parserejected a combining mark after a wide character — its own format, for a cell the emulator stores correctly. A wide glyph advances two columns, so stepping one back lands on the continuation half, which holds no text; the mark now attaches to the leading cell that owns the glyph. (#297) -
A hidden cursor made a snapshot differ from itself. The text format records
cursor: hiddenwithout a position, so a parsed screen came back at0,0andScreenDiff::is_emptycompared the coordinates anyway — a difference with nothing visible behind it, on a screen state most TUIs are in. A hidden cursor draws nothing, so its position is no longer part of the picture, fordiffand forwait_stablealike; visibility, and a visible cursor's position, still are. (#298) -
Screen::parsepanicked on a non-ASCII hex colour.fg=#a€bcis six bytes, so the length check passed and slicing in pairs landed inside a character — an unwind out of the one function whose job is turning bad text intoError::Parse, and the CLI shares it. Every byte is now checked as an ASCII hex digit before any of them is read. (#299) -
mask_matchingleft a needle that spans rows fully visible. It is documented as matching "the wayfind_allmatches", andfind_allcrosses row boundaries — but the mask ran its matcher one row at a time, where a newline can never appear. It reported the match and masked nothing, which is precisely the failure a mask exists to prevent.find_alland the masks now share one multi-row engine, so they cannot disagree about what matched. (#300) -
A fixture announced it was ready before it could be resized.
form-echo(and the newratatui-app) drew their first frame — the one a test synchronizes on — before the firstevent::read(), and crossterm registers itsSIGWINCHlistener on that call. A resize landing in the gap was lost for good, since SIGWINCH's default disposition is ignore, andwait_framethen ran out a full deadline against an application that had simply never heard.resize-echoalready guarded against this; the other two now do the same. Found by the stress workflow on macOS at one thread. (#292) -
A query test raced its own fixture's pause.
a_query_the_app_moved_past_is_context_not_a_causespent one 400 ms budget on both of its waits — the one that must succeed and the one that must expire — while the fixture deliberately sleeps 200 ms before printing the marker the first one waits for. A spawn plus that pause on a loaded macOS runner at four threads exceeded the budget, and the test failed claiming the harness had blamed a probe it should not have. The short deadline now sits on the wait that must expire and nowhere else, the splitprobealready made. Found by the stress workflow's first run on the new three-OS matrix, at 1 in 5 iterations on that shard. (#290)
0.10.0 - 2026-09-08
-
Styled history, opt in:
TerminalBuilder::scrollback_styles(true)andScreen::scrollback_cell. A row lost every style the moment it scrolled off, so the masked-password assertion — the one v0.4 paid a second parser for — silently degraded to text the instant the screen filled. With the knob, the scrolled rows are retained as cells beside the text, the shadow parser keeps the same history and is read in lockstep so conceal, blink and strikethrough come along, and a snapshot still pays one refcount per retained row. Off by default, because the cost lands where a suite feels it — every read that scrolls captures cells, and a full history is re-read on each — and measured in the knob's rustdoc: about 90 ms against 40 ms for 20,000 lines. (#146) -
Screen::locate: where a needle is, on the grid or in history, as aLocationthat says which. The addressing half of the scrolled-off-text problem, honest about what history can promise: a history column is the row's display column as it was captured, not a grid coordinate, and does not survive a narrowing resize. (#147) -
Terminal::record(). Every complete frame from that moment on, timestamped, untilstop():Recording::frames()for asserting on the sequence of repaints an animation went through, andwrite_asciicast()for a fileasciinemaplays andaggturns into a GIF — each frame a full repaint throughto_ansi. Bounded byTerminalBuilder::record_budget(cells; default about a thousand 80x24 frames), oldest frames dropped and the drop reported; refuses, withwait_frame's diagnosis, an application that never emits synchronized updates, because a sampled recording is the torn-frame problem in a new hat. (#254) -
Screen::diff. Two screens that differed printed as two whole grids;a.diff(&b)renders only the rows that changed, side by side over a marker line under the changed columns, the size and cursor deltas, a count of unchanged rows and the style runs before → after.is_empty()andcells()for assertions;assert!(a.diff(&b).is_empty(), "{}", a.diff(&b))is the documented way to compare two screens outside insta. Await_frametimeout now shows the diff from the frame it last returned to the live screen. Plain text, so CI logs stay readable. An erased cell and a written space in the same style are one blank, not a difference. (#246) -
docs/STABILITY.md: what 1.0 means. Not a feature list — three decisions written down with the measurement that decided each: Windows (screen assertions yes, frame assertions no; the ConPTY probe), the emulator backend (vt100stays and so does the shadow parser;docs/BACKENDS.mdcompares it withalacritty_terminal, which drops blink and brings an event loop, andwezterm-term, which is not on crates.io), and styled history (a knob, off by default, 90 ms against 40 ms). Plus which public items the promise covers, which stay behind features, and which are heuristics.docs/RELEASING.mdrequires all three sections for a 1.0 tag. (#256, #150) -
termlens-cli: thetermlenscommand, andScreen::parse. Two saved screens could be compared only bycargo insta review, on the machine that ran the tests.cargo install termlens-cliprovidestermlens inspect(the example grown a command: a program in a PTY, its screen printed,--ansifor colour),termlens diff a b(the cell diff of two saved screens — an insta.snapwith or without its header, the block a wait error prints, aTERMLENS_ARTIFACT_DIRfile, or the JSON theserdefeature writes — coloured on a terminal, plain in a pipe, exit 1 when they differ) andtermlens render --svg|--html|--ansi|--text. The genuinely new piece is in the library:Screen::parsereads the snapshot text format of DESIGN §3 back,styles:block included, so the format round-trips —Screen::parse(&s.with_styles().to_string())renders to the same text and diffs empty againsts. A text that is not the format isError::Parse, naming the line. The CLI's own tests drive it through a PTY with termlens. (#255) -
TERMLENS_ARTIFACT_DIR, and thereportaction. A failing wait's screen reached the CI log and stopped there. With the variable set, every error that carries a screen also writes it to that directory —<test>-<n>.screen.jsonwith theserdefeature,.screen.txt(thewith_stylesrendering) without — andvyncint/termlens/.github/actions/report, run withif: failure(), renders those files and every.snap.new(with the diff against its.snap) into the pull request's step summary, SVG and HTML uploaded as an artifact. Off when unset; documented onError. This repository's owntestjob runs the action. (#251) -
fixtures/ratatui-appand its fidelity test. No fixture was a ratatui application, so the one check only a PTY harness can make for ratatui users was never made here. The fixture is a counter/list with every repaint in a DEC 2026 bracket,j/k/q, and a resize acknowledged on its status line;fixtures/ratatui-app/tests/fidelity.rsrenders the samedrawthrough the PTY and throughTestBackendand diffs the two cell by cell — cells and styles, at two sizes with a resize between. The README's comparison section now lists whatTestBackendstructurally cannot see, each with the termlens assertion that does. ratatui 0.30 needs Rust 1.88, so the fixture carries its ownrust-versionand the MSRV check excludes it; the library's floor is unchanged. (#252) -
Screen::to_ansi,to_svg,to_html. Three renderings a person can see — paste the ANSI into a terminal and the failure is on screen in colour; the SVG is self-contained for a bug report or a README; the HTML is a<pre>of<span style>s for a step summary or a PR comment. Pure functions of the cells and styles, no dependency, a wide character one glyph over two columns. (#248) -
A
serdefeature (off by default):Serialize/DeserializeonScreen,Cell,Style,Color,CursorShape,MouseMode,MouseModes,Link,Clipboardand the graphics types. AScreenis rows of cells, so a JSON snapshot diffs by row;Coloris a tagged enum ({"indexed": 1},{"rgb": [30, 30, 46]}) so nothing needs a parser on the way back; deserializing re-checks that every row holds exactlycolscells.insta::assert_json_snapshot!(t.screen())works. (#247) -
Screen::find_all. Every occurrence of a needle in reading order, from the same scanfindis the first element of — NFC-folded, trimmed per row, real columns across wide characters — so the two cannot drift. Non-overlapping, multi-row needles supported, aVec; the reasons for each are in the rustdoc. "This warning appears exactly once" and "click the second item" are writable without opting out of normalisation. (#264) -
A
regexfeature (off by default):Screen::matches,find_match,find_all_matches,mask_matches, andTerminal::wait_until_matches/_for, which returns the screen it matched on. Matching is per row over the row's text ascontainssees it, and the column reported is a cell column — the expect-style wait, pointed at a row of the rendered screen rather than at the byte stream. (#245) -
Grid-aware masks:
Screen::mask_rect,mask_matching,mask_cells. Each returns a newScreenwith cell contents replaced and the size, cursor, styles and wide-character structure kept, so a clock or a PID can be redacted without moving a column — which is what insta's text filters cannot do for a grid. A masked screen snapshots,finds and compares like any other, and itsstyles:block is unchanged, so a colour regression stays visible through the redaction. (#250) -
Screen::unsupported(): the sequences the emulator did not implement, so a plausible-looking wrong grid can be told from a right one. The backend reports every escape it cannot render and termlens installed the no-op callbacks and threw the list away. It is kept now — distinct shapes, first seen first, in the timeout messages' form (^[[20h), 32 kept and the rest counted inunsupported_overflow()— filtered to what termlens did not honour, since the character sets, tab stops, insert mode and every query the responder answers still reach the backend's callbacks. A request to resize the window is listed rather than obeyed;visual_bells()countsESC gseparately frombells(), since a flash is not a beep. (#266) -
Screen::row_wrapped()andScreen::logical_text(). A line long enough to wrap is two rows, and a needle spanning the wrap was found by nobody although a reader plainly saw it. The backend has always recorded which rows soft-wrapped and was never asked; each snapshot now carries the bit, andlogical_text()joins wrapped rows back together sological_text().contains("brown fox jumps")is true.containsandfindare unchanged and document the trap beside the scrollback one. The two sentences that said history could not be reflowed for lack of the record now give the true reason, cost. (#265) -
Windows. The crate builds and the whole suite runs on
windows-latestin CI, over ConPTY. Screen assertions work; the features ConPTY renders away —wait_frame, graphics, the responder's outbound claims, mouse modes, focus reporting, link ids — are documented as Unix-only in the README, with their tests marked so and the probe that measured them intests/conpty_probe.rs. Two things a Windows user would have hit first are fixed on the way:bin!refused an absoluteC:\…path as a bare program name, and a child that had exited was still "listening" — a pseudoconsole never reports EOF, so the reaped child now closes the terminal there. (#149) -
A skill for AI coding agents.
skills/termlens/SKILL.mdteaches an agent how to test a terminal program with termlens without the mistakes agents make on their own: nosleep,snapshot_afterfor whole-screen snapshots, the 2x2 geometry floor,bin!for hermetic spawns, the two coordinate orders,wait_frameonly for applications that emit synchronized updates (stock ratatui does not), and four copy-paste recipes — a CLI snapshot, a ratatui navigation flow, overriding defaults, targeted cell and style assertions. Every Rust block in it is compiled against the crate in CI, and the README shows the one-line install for Claude Code.
-
The
windows-latestleg is a required check. It ran non-required from #279 and held on every push tomainsince; a ConPTY surprise now blocks a merge, which is what claiming the platform indocs/STABILITY.mdmeans.windows.ymlstays as the on-demand report with the probe. (#280) -
assert_screen_snapshot!earns its name. It wasinsta::assert_snapshot!under another name. Given aTerminalit now settles the picture (wait_stable(100ms), orsnapshot_after(pred)withafter = pred) and snapshots with styles by default;styles = falseis text-only, the inline@""form still works, and aScreenargument still records the screen as it is. Built onsnapshot_after/wait_stable, so it adds no waiting logic of its own; its rustdoc is now the home of the race rules. The README's first example uses it and drops the rule-2 paragraph it no longer needs. The macro uses?, so the test returnsResult— which every test should. (#253) -
Screen::row_textrejects an out-of-bounds row instead of returning an ambiguous empty string. Callers with a potentially invalid index should bounds-check againstrows()first, or usecell(row, 0)and treatNoneas absent. (#260) -
Terminal::dragtakes four column-first coordinate arguments instead of two unlabelled tuples. This matches the other mouse methods and prevents a row-firstScreen::findresult from being passed through transposed. (#257) -
Styleis non-exhaustive so new terminal attributes can be added without another breaking change. Downstream struct literals should migrate toStyle::default()followed by assignments to relevant fields. (#259) -
The
inspectexample clears the child environment by default. It keepsPATHso bare program names work;--envadds selected values and--inherit-envrestores the previous behavior. (#263)
-
Insert mode (
CSI 4 h) is honoured.smir/rmirare in the terminfo entry every child is handed, and ncurses uses the mode forinsch; it was parsed and dropped, so an inserted character ate the rest of the line and a snapshot could bless the eaten tail. The flag lives in the sequence tracker beside the character sets; while it is set the emulator reserves room for each printable run with theICHthe backend does dispatch — in columns, so a wide character counts twice, and never past the right margin.RISandDECSTRclear it, andScreen::insert_mode()reports an application that left it on. (#261) -
Custom tab stops are honoured:
HTS,TBC,CHTandCBTdo what they say. Stops were fixed at every eighth column — the backend's hardcoded value — and all four escapes reached a dispatch table with no entry for them and vanished, thoughhts,tbcandcbtare all in the terminfo entry termlens hands every child. An application that laid a table out by setting its own stops and tabbing between them drew every column in the wrong place, and did it silently: the characters were all present, socontainsstill passed and only a column assertion or a whole-screen snapshot could catch it. The stop set now lives in the sequence tracker beside the character sets, and the emulator rewrites each motion as aCHAthe backend does dispatch. Plain\tis rewritten too, or the backend's eight and a custom stop would disagree the moment one was set.RISandDECSTRrestore the every-eighth default; a resize extends the set into its new columns with that same pattern and leaves the stops it already had alone.CBTis also whatShift-Tabsends, so an application echoing one now moves. (#262) -
docs.rs labels APIs gated by the
decodeandinstafeatures. Optional items no longer appear to be available in every build. (#258)
0.9.0 - 2026-09-05
-
Error::Emulator: an emulator panic is a diagnosis, not a timeout. The emulation runs on the reader thread, so a panic there propagated nowhere — the drain died, the screen froze, and every wait burned its full deadline reporting a predicate that could never come true. The reader now catches it, records it, and keeps draining (a stalled drain blocks the child writing into a full buffer);wait_until,wait_frameandwait_idlefail at once with the emulator's own message and the last screen taken before the failure. The emulator is never asked for a screen again — after a panic its state means nothing.wait_exitis deliberately unaffected: the child's exit status is still true. (#211) -
snapshot_afterandwait_stable: the whole-screen snapshot as one call, and a settle that output changing nothing cannot hold up.snapshot_after(pred)waits for the predicate, then for the picture to hold still for 100ms, and returns that screen — DESIGN §2's three rules for race-free waits without having to remember them.wait_stable(quiet)is the settle on its own, and differs fromwait_idlein what resets the clock: changes rather than bytes, so a bell, a cell rewritten with the glyph already in it or an answered query — outputwait_idlecan never see silence through — is invisible to it. Both have_fortwins, refuse to settle inside an open synchronized update, count stillness that predates the call, and return the screen they settled on. -
termlens::bin!("myapp")spawns one of your package's binaries under the harness defaults. Every integration test of a binary opened with the same five lines — a fixed 80x24 grid,env_clear(), a five-second deadline,spawn(env!("CARGO_BIN_EXE_myapp"))— so the chain has a name. Builder calls follow the name and override any default:termlens::bin!("myapp", size(120, 40), env("NO_COLOR", "1"))?. A misspelled binary is a compile error naming the variable, not a spawn failure at run time. -
Screen::mouse_modesreports every mouse tracking mode the application enabled, andDECRQManswers each one on its own evidence. The backend collapses?9/?1000/?1002/?1003into the one protocol a terminal reports in — right for the input path, and unchanged there — so it could not say which members of the group an application asked for: crossterm'sEnableMouseCapturesends three at once and only the last survived, a regression from any-motion to button-motion tracking (losing hover) was invisible, and aDECRQMprobe for any member but the last had to be answered "not recognized". The sequence tracker now keeps the requested set;mouse_mode()still reports the protocol. (#151) -
The fresh-install check verifies a
--no-default-featuresconsumer as well as adecodeone.install.ymlis the only job that builds termlens from outside this workspace, and it did so in one shape — the one the fewest real consumers use: of the three in-house ones, two declaredefault-features = false. Its matrix now runs both shapes on Ubuntu and macOS, the registry check demands thedecodefeature only on the leg that asks for it, and the no-defaults leg fails if the consumer's tree still resolvesinsta. (#238) -
The
inspectexample answers--help, and takes its deadline and silence window from flags.inspect --helpused to look for a program called--help, and both timings were hardcoded, so an application slower than five seconds to paint its first screen could not be inspected at all.--timeout SECONDS(default 5) and--idle MILLIS(default 300) now sit beside--size;--help/-hprint one usage text to stdout and exit 0, a missing program prints the same text to stderr and exits 1, and--versionnames the termlens version the example was built from. An unknown option is refused rather than spawned. (#229, #236)
-
The smallest terminal is 2x2, not 1x1. One column panics the emulator on a double-width character, and one row panics it on a line that wraps — on the reader thread, in both profiles, where the panic propagates nowhere: the grid froze, every later wait ran to its deadline against a plausible-looking screen, and
cargo testprintedtest result: okover a suite that had stopped testing anything.80x1is an ordinary shape, not an exotic one.spawnandresizenow refuse a dimension below 2 withError::Size, the way they already refused 0 — #49's "no path can reach the emulator with a zero" was satisfied exactly one value too low.2x8and2x2render both trigger shapes correctly, so the floor is the smallest guard that closes them. (#211) -
A child starts in the test process's working directory, not
$HOME. Withoutcurrent_dirthe PTY layer fell back to the home directory, so a relativespawn()path and a directory-sensitive program behaved unlike every other Rust process API — whilecurrent_dir's rustdoc promised the test runner's directory all along. The default is now whatstd::process::Commanddoes;current_dirstill overrides it. A test that relied on the old fallback should say.current_dir(std::env::home_dir())explicitly. (#215)
-
G2/G3 designation and SS2/SS3 single shifts are modelled, so a one-character line-drawing shift draws
┌rather thanl.ESC * 0/ESC + 0designate the DEC Special Graphics set into G2/G3, andESC N(SS2) /ESC O(SS3) invoke that set for exactly one character before the locking shift resumes. The designation was already consumed; the shift did nothing, so a mixed line of text and box-drawing showed the letter. A pending single shift is consumed by the next character — including a multi-byte UTF-8 one — and does not surviveRIS. Locking shifts remain G0/G1 only (SO/SI);LS2/LS3andDECSC/DECRCof charset state are still unmodelled. (#235) -
DECSC/DECRCsave and restore the character-set state. Save, jump, draw the frame, restore is how a full-screen application draws a border, and the restore lost the designation, so the border after it rendered aslqk— the failure #204 fixed, arriving through a different door.ESC 7now saves G0–G3 and the locking shift alongside the cursor the backend already saved,ESC 8restores them, a restore with nothing saved returns to ASCII as xterm does, andRISclears the slot so a restore cannot resurrect a designation from before the reset. (#232) -
DECSTR(soft reset,CSI ! p) is modelled. The polite reset a well-behaved TUI sends on startup and teardown parsed cleanly and did nothing, so text printed after it kept rendering in the character set the application had told the terminal to forget, whileRISgot this right. It now returns the character sets and theDECSCslot to power-on, the cursor shape to the terminal's default, and turns off cursor-key mode, bracketed paste, every mouse tracking mode and encoding, and focus reporting; the cursor becomes visible and the alternate screen is left alone, as specified. Attributes, margins, origin and insert modes and the keypad are not replayed — nothing onScreenobserves them — and the README says so. (#233) -
The UK character set is translated:
ESC ( Athen#draws£. The designation was parsed and then rendered as ASCII, so an application printing a price in the UK set showed#42on the grid, a test asserting£42failed against a correct application, and a snapshot that blessed#42kept passing. The set differs from ASCII in that one position, so that is the one byte translated; the alternate-ROM sets and the other national sets still read as ASCII, and the docs now say which sets are translated. (#234) -
findno longer matches the blank padding past the end of a row. Its single-row path searched the row padded out to the terminal width whilecontainssearched the trimmed text, sofind("Total: ")wasSomeon a screen whose row readTotal:— against the invariant both rustdocs state, that a needle is found precisely whencontainsis true. Both now trim trailing whitespace per row first; the trim treats a drawn trailing U+00A0/U+3000 as padding too, and both rustdocs say so. (#212) -
env_clear()no longer leaks the machine's login shell. The PTY layer fillsSHELLfrom the host when the variable is absent, so a child's supposedly hermetic environment differed between two machines with different shells.SHELL=/bin/shis now pinned underenv_clearthe wayTERMis, an explicit.env("SHELL", …)still wins, and a test asserts the whole environment rather than probing one name. (#221) -
A bare program name under
env_clear()is refused with the remedies. Clearing the environment removesPATH, sospawn("sh")could not resolve and failed with the PTY layer's "Unable to resolve the PATH", which named neither the cause nor a way out.spawnnow refuses it up front with anError::Spawnthat saysenv_clearremovedPATHand offers both fixes: an absolute path, or.env("PATH", …). (#222) -
A byte that is not UTF-8 shows as U+FFFD instead of vanishing. The backend drops both a byte it cannot decode and the U+FFFD its own parser substitutes for one, so a Latin-1
éin a file name left no trace on the grid and every column after it shifted left — a test asserting on the column of what followed passed against the wrong screen. Bytes are now decoded once on the reader thread: an invalid sequence becomes the replacement character a terminal shows (carried through the backend as a noncharacter it will draw, and restored in the snapshot), and a character split across two reads is carried rather than replaced.wait_idletreats a stream that stopped mid-character as not yet idle. (#217) -
A highlight over CJK or emoji is one span again. A wide character's continuation column carried no style, so
with_styles()rendered a bar overab汉cdas two spans with a hole andcell(row, col).style()on the second column reportedDefault— DESIGN §3 rule 5 andfind_by's rustdoc both promised the opposite. The snapshot now gives the continuation the leading cell's style, as a terminal paints it. (#218)
0.8.0 - 2026-08-29
-
DEC Special Graphics is translated, so an ncurses border reads as
┌───┐rather thanlqqqk.ESC ( 0selects the line-drawing set — it is whatsmacs/rmacsare on an xterm terminfo, so it is how every ncurses application and plenty that are not draw their frames — and the bytes used to reach the grid untranslated. That put the crate's own promise in the wrong: a user sees a box, and a test asserting a border was right failed against an application that was correct, while a snapshot that had blessedlqqqkwent on passing after the border broke. Thevt100backend drops the designation entirely, so termlens tracks the G0/G1 designations (ESC ( Ps/ESC ) Ps) and theSO/SIlocking shifts itself and hands both parsers the glyph a byte draws. Scope is stated rather than implied: only the DEC Special Graphics set is translated, other designations read as ASCII, G2/G3 and the single shifts are not modelled, and a hard reset (RIS) returns both sets to ASCII. -
Terminal::scroll_with, withScroll::ctrl()/alt()/shift()and aScrollChordtype.Ctrl-wheel is zoom andShift-wheel is horizontal scrolling in a large share of terminal applications, and neither could be sent:scrolltook a bare direction, so the binding most likely to be wired to the wrong handler was the one with no coverage. The modifier bits ride on the wheel's button code exactly as they do on a click, andscrollis now the unmodified case ofscroll_with, asclickis ofclick_with. The wheel gets a chord type of its own rather than a widerMouseChord, so a wheel direction cannot be handed toclick_with: a notch has no release, and the type keeps that from being a runtime surprise. -
ScreenimplementsPartialEqandEq. It was the only public value type without them, so "did anything change?" was written by comparingto_string()renderings — which is text only, and so passes two screens that differ in a highlight, a colour or a concealed field. Equality means the same observation: cells, cursor, size, and every piece of out-of-band state including the cumulativerepaintsandbellscounters, so two visually identical snapshots either side of a bell compare unequal because they are different moments. The doc says which comparison to reach for when "looks the same" is what is meant. -
A content wait that fails while rows have scrolled off says so. The most-copied line in these docs,
wait_until(|s| s.contains(..)), reads the visible grid, so text the application printed and then scrolled away in the same burst can never satisfy it — and the screen embedded in the timeout does not show the text either, so the failure read as "the app never printed it".Error::TimeoutandError::Eoffromwait_untilandwait_framenow say how many rows have scrolled off the top and point atScreen::full_text. The note is conditional, because the wait cannot know what an arbitrary closure was looking for; it is silent when nothing has scrolled.containsandfinddocument where they stop.
resizeis refused once the child has released the terminal, with the sameError::Writethatsendreturns, naming the child and its exit status. It used to succeed, and the snapshot then reported a geometry no application ever rendered at with the dead child's last frame clipped underneath it — the one operation on a departed child that silently mutated observable state. The final screen stays readable at the size the child exited with. A size that cannot work is stillError::Size, checked first.
-
Bitmap::coloursis linear in the pixel count, and its order is defined. It counted distinct colours with a scan of the distinct set per pixel — O(pixels × colours), 9 ms for 96x96 and extrapolating to seconds for a screenshot, in a test suite, where a wait that takes seven seconds looks like a hang. It now counts in one pass. Ties, which the old implementation happened to order by first appearance through a stable sort, are now ordered that way on purpose and the doc says so: a test asserting oncolours()[0]has one answer. -
wait_frameafterresizecould miss the repaint that answered it.resizesent theSIGWINCHfirst and took the frame cursor afterwards, so a fast application's acknowledging repaint could complete in that gap, be counted as a frame from before the resize, and never be offered — the wait then timed out reporting that the application had not repainted, while the live screen showed that it had. Found by the stress workflow at 16 threads, once in 25 runs. The grid is now resized and the cursor taken before the signal goes out, under one lock, so a frame drawn in answer to the resize is always newer than the cursor and always lands in a grid of the new size. -
resizedocuments the resize-then-type trap. A keystroke that reaches a crossterm application in the same instant as theSIGWINCHcan be lost: its event reader returns theResizeas soon as the poll reports the signal and abandons the input readiness delivered alongside, and the poll is edge-triggered, so the byte is not offered again until more input arrives. The stress workflow caught termlens's own suite doing exactly that — a resize followed at once byEschung the fixture about one run in forty. The test now waits for the application to acknowledge the resize, which is the advice the doc gives. -
resizedocuments what happens to history. Rows already in scrollback keep the width they were captured at and rows captured afterwards have the new width, sofull_text()after a narrowing resize can hold both geometries. That was true before and said nowhere a caller would meet it; it is now a recorded decision onresizeandscrollback_text, with the alternative — discarding history on resize — rejected in writing rather than by omission. -
Doc comments on
TerminalBuilder::size,spawnandresizenameError::Sizefor a rejected size, notError::Input. The links resolved, to the wrong variant, so following them gave amatcharm that never fires — andErroris#[non_exhaustive], so a wildcard elsewhere would have swallowed the mistake silently. -
Colon-form SGR colours now reach cell styles.
38:2::r:g:b,38:2:r:g:b, and indexed foreground and background colours are normalized before the backend parses them, matching their semicolon-form equivalents. -
Mouse
click/click_with/drag/scrollrefuse coordinates outside the current grid. A real terminal cannot produce an off-window mouse event; sending one was the same class of mistake as clicking with no tracking enabled. The error names the position and the grid size at the time of the call (so a post-resizerejection is obvious).dragchecks both endpoints only — the interpolated path cannot leave the rectangle they span. Separately, the SGR encoder no longer wraps or panics atu16::MAX: the 1-based+ 1is done inu32.
SECURITY.mdno longer claims the crate has nounsafe. It has two blocks, both FFI and both present since the features they serve landed:dup(2), which opens the responder thread's writer on the PTY master, andkill(2)behindTerminal::signal. Neither touches memory the child can influence and the parsing path has none, which is the claim that matters; the policy now says exactly that rather than something stronger and false.
0.7.0 - 2026-08-27
-
TerminalBuilder::envssets several child environment variables from an iterator of key-value pairs. Values keep their iteration and builder-call order, and remain explicit whenenv_cleardisables inherited variables. -
Screen::linksreports theOSC 8hyperlinks an application emitted. A hyperlink changes no cell — its label renders exactly as unlinked text would — so the URL existed nowhere a test could reach, and an assertion that a TUI linked an issue, a file or a doc page passed identically against an application that emitted no link at all, or linked the wrong target. Captured rather than answered, on the same grounds as theOSC 52clipboard: the only evidence otherwise available is the application's own visible output, which proves the code path ran and nothing about where it points.Each span reports its
uri, itsid(spans sharing one are one logical link), thelabelit wrapped, and whether the application everclosedit — an unterminated link is a real defect, because in a real terminal every character written afterwards joins it. Two bounds keep the capture honest: the log holds the most recent 64 spans and evicts oldest-first, so a TUI that redraws its links every frame still reports the current frame's; and a label past the capture bound is reported as unknown rather than as a prefix, since a prefix of the wrong length is a wrong answer. -
Screen::cursor_shapeandScreen::cursor_blinkreportDECSCUSR. A screen where the application asked for a bar and one where it never asked used to be the sameScreen. The shape is load-bearing behaviour rather than decoration — a modal editor switches to a bar for insert and back to a block for normal, and "the mode indicator says INSERT" and "the terminal was actually put into insert" are different claims. It also makes the restore assertable, which is the half that ships broken: a program that changes the cursor and never changes it back leaves the user's terminal wrong after exit, the same class of defectalternate_screen()already catches.Shape and blink are one
DECSCUSRparameter but two facts, so they are reported apart.CursorShape::Default— the application never sent the escape — is a third state and is reported as itself rather than folded intoBlock. -
Key::Insert, encodingESC [ 2 ~, and chording like its neighbours (Key::Insert.shift()→ESC [ 2 ; 2 ~). It was the2missing from a navigation run that already had3,5and6, so an application binding Insert could not be tested without hand-writing the escape.
-
KeyandSignalare now#[non_exhaustive]. This is breaking for downstream code thatmatches either without a wildcard arm; adding a_ => …fixes it, and equality and construction are unaffected.Worth doing now rather than later. Adding a variant to an exhaustive public enum is itself a breaking change, so every future key and every future signal would have cost a version of its own —
Keyhas no F13+ and no keypad, andSignalcarries seven of POSIX's thirty, missingSIGWINCHandSIGCONT, which are exactly what a terminal application reacts to. Both types are constructed far more often than matched (t.send(Key::Enter),t.signal(Signal::Int)), so the cost falls almost entirely on the crate and not on its users.#[non_exhaustive]is breaking to add, which makes the cheapest moment the earliest one.Coloris deliberately left exhaustive. Default, palette index and 24-bit RGB is the whole terminal colour model — there is no fourth variant waiting — andColoris the one enum here that downstream code really does match on.
-
A decoded image can no longer choose how much memory it allocates.
GraphicsPayload::decodetrusted four sizes that the program under test writes: kitty'ss=/v=, sixel's raster attributes, its!nrepeat count and its#ncolour-register index. A compressed kitty payload was also inflated with no output limit, and zlib reaches about 1000:1. Each turned a handful of bytes into a request for tens of gigabytes —!4294967295~is twelve bytes; a declared65535x65535is about twenty and asks for 17 GB before the pixel data is touched at all.Decoding is now bounded: no image above 4096x4096 (far beyond what a terminal can place, and 64 MiB of RGBA once built), sixel colour registers capped at 65536, and a compressed payload inflated only as far as its declared size needs. Refusals are a new
DecodeError::TooLargerather than a silent clamp —DecodeErroris#[non_exhaustive], so matching on it already required a wildcard.Present in every release before this one. It sits behind the off-by-default
decodefeature and is reached only when a test callsdecode(), so a suite that merely counts images was never exposed.SECURITY.mdnow enumerates these bounds with the rest.
-
A hard reset (
RIS,ESC c) returns the cursor shape to the terminal's default and closes any openOSC 8span.printf '\033c'is one of the ways a program hands the terminal back on exit, so reporting the lastDECSCUSRafter one claimed a shape the terminal no longer held — and it did so in exactly the casecursor_shapeexists to check. The window title, the clipboard, the bell count and the link log are deliberately left alone: the title is a window propertyRISdoes not restore in xterm, and the rest are records of what the application emitted rather than state the terminal still holds. -
The crate's doctests build with default features disabled. The bundled snapshot macro example is compiled only when its
instafeature exists, and CI now runscargo test --workspace --no-default-featuresso this supported configuration cannot silently rot again.
0.6.1 - 2026-08-23
-
spawnno longer fails when the machine is briefly out of PTY devices. On macOS a PTY is torn down withrevoke()and its device recycled, and a suite asking for devices faster than the kernel returns them getsENXIO— "Device not configured", which reads like a broken machine and is really a queue.cargo testruns one test per core by default, so this is what a sixteen-core Mac does with any suite of this shape; the failure was not exotic, it was Tuesday.openptyis now retried for about 1.6 seconds before giving up, releasing the PTY lifecycle lock between attempts — that lock is the one a teardown also takes, so waiting under it would have blocked the only work capable of freeing a device.Found by the stress workflow the first time it ran the suite at sixteen threads, on macOS; Linux had run the same suite twenty-five times over without noticing.
tests/concurrency.rsnow applies the same pressure on purpose — two dozen terminals at once, and eight rounds of open-and-recycle — so it is reproducible rather than a matter of which shard drew the short straw.
0.6.0 - 2026-08-21
What an application drew, as against how many bytes it spent drawing it.
Inline graphics were observable only as a count and a size: an image had gone out, and it had been about so big. Three things were wrong with that, and the first two were wrong rather than merely thin — the count was of escapes, not of images, so the kitty protocol's own 4096-byte chunking inflated it and a delete posed as a transmission.
GraphicsSeen::payloads— the transmissions themselves. EachGraphicsPayloadcarries its protocol, action, format, compression, image id, the pixel size and cell extent the application declared, the bytes it cost, the chunks it took, and the data itself. Placement is the one fact that lives in the grid rather than in the payload, soat()reports the cursor position at the terminator — the image's top-left corner for both protocols. An application that lays out in characters and draws in pixels can now be held to keeping the two in step, which is a failure nothing on screen shows: a picture that slides out from under its own labels leaves every cell exactly as it was.GraphicsSeen::deletes, counting kittya=d— images taken off the screen — apart from images transmitted.- The
decodefeature:GraphicsPayload::decodeandBitmap. Kittyf=24/f=32, zlib'd or not, and the sixel data stream decode into pixels, so an assertion can be about the picture rather than about its size. Off by default: it is the one thing here needing a dependency of its own (zlib), and every other fact about a payload stays free. Refusals name their reason —f=100(PNG) is unsupported rather than guessed, a delete carries no image, and a payload past the capture bound says so instead of decoding a prefix of itself into a plausible wrong picture. TerminalBuilder::capture_graphics, the retention budget: 4 MiB by default,0to keep counts and drop every byte. Bounded like scrollback, and the counters stay exact whatever the bound.- The
image-echofixture, which transmits a known image over kitty (compressed, plain, and chunked), over sixel, and with a delete after it.
- A chunked kitty transmission is one image, not one per escape. The
protocol caps a payload at 4096 bytes and continues with
m=1, so a 4.9 KB chart counted as two images and the continuations — which carry no control block — counted as pictures nothing could be said about. The chunks are joined before anything is counted. - A kitty delete is no longer counted as an image transmitted.
a=dcarries no picture. Every byte of it is still counted inbytes(): a delete is traffic.
GraphicsSeenisClonerather thanCopy, since it now carries the payload list. Existing code that reads a counter is unaffected; code that copied the value into two bindings needs aclone.
0.5.0 - 2026-08-20
What the harness could not observe, could not reach, and quietly got wrong.
Seventeen issues, every one verified against the published 0.4.2 before a line was written — four by reproductions that contradicted the report, and one of those by a reproduction that contradicted me. Three themes: behaviour a test could not see at all (repaints, bells, images, focus), applications that could not be driven down a path they probe for first, and accessors that answered confidently where they had nothing to say.
Two API changes are breaking, both in the direction of honesty:
send/send_str/paste return Result, and ExitStatus::code returns
Option.
-
send,send_strandpastereturnResult<()>and no longer panic. Every input call in the crate is now fallible, so a write that cannot be delivered is something a test can see, handle, or propagate with?— previously the only route from a failed write to the test was aborting it. Call sites grow a?; that is the whole migration. -
Typed input to a closed terminal is refused identically on Linux and macOS. It was not: a write to a master whose slave descriptors are all closed fails with
EIOon macOS and succeeds on Linux, queueing the bytes for a reader that no longer exists. The same keystroke was therefore an error on one CI runner and silently discarded on the other. Every sender now checks for a closed terminal before writing, so the answer is the same everywhere and no keystroke is lost quietly. -
A batch of startup probes is answered in full, and the reply queue is now bounded by memory rather than by queue slots — which took three attempts to get right, each one teaching what the invariant actually is. 200 queries asked back to back returned 173 answers; 400 returned 235; 1000 returned 285. The stated cause — the application had stopped reading — was wrong: the same 200 queries a millisecond apart were all answered, so nothing was blocked anywhere. The reader was enqueueing one entry per reply while the writer issued one
write(2)per entry, so it outran the writer and the 64-slot queue overflowed. Batching per read fixed that on a fast machine — but on a slow one an application's writes dribble out, the same 400 queries arrive in hundreds of small reads, and 64 slots ran out again at 235 of 400. Slots were never the thing worth bounding: the queue is now unbounded with a 1 MiB ceiling on undelivered reply bytes, so the reader can never block, a real application is never shorted, and a hostile one still cannot grow memory without limit. The writer coalesces whatever is queued into a single write. -
Undelivered replies are counted whether dropped or blocked mid-write, so a non-reading application is named in the wait error rather than producing a plain timeout. One diagnosis got weaker on Linux, and that is the price of the fix above. The note used to appear there because replies overflowed our queue — the same overflow that was losing a well-behaved application's answers. With that fixed, the replies reach the kernel, and the platforms diverge: a write into a full terminal input queue blocks on macOS, where the backlog stays visible and the count is exact, while Linux's
n_ttydiscards input once its 4 KB buffer is full — the write succeeds, the bytes are gone, and nothing distinguishes that from delivery. We cannot report what we were never told.docs/DESIGN.md§1 states the split; the trade is a diagnosis for a pathological application in exchange for a well-behaved one actually receiving its answers. -
dragreports one motion per cell crossed, on a straight interpolated path, instead of a single report at the destination. Seven cells crossed used to produce one motion event. Invisible to an application that only asks "where did it start, where is it now" — which is why it went unnoticed — and wrong for every application that does something along the path: a drawing surface painting each crossed cell, a selection highlighting incrementally, a drag that must cross a pane edge to register. The mode-aware refusals are unchanged:?1000still hears no motion at all, and X10 is still a typed error. -
A mouse action at a departed child names the child.
click,dragandscrollcheck liveness before the mouse-tracking mode, because a child that has exited necessarily never enabled tracking either — so the old order reported a missingCSI ?1000 hfor a terminal whose application was simply gone. The tracking-mode error is unchanged for a live application that really has not enabled it. -
ExitStatus::codereturnsOption<u32>,Nonewhen a signal killed the child. A signalled process has no exit status — POSIX gives one or the other — and the OS placeholder (1) that filled the slot madeassert_eq!(status.code(), 1)pass on aSIGTERMpath, which would keep passing if the application later started exiting 1 for a real reason.Displayno longer prints the invented(code 1)tail either. Mirrorsstd::process::ExitStatus::code. -
Screen::rect_textpanics on a backwards range instead of returning""or a bare"\n", and both axes now behave identically — they did not. It reads as "this pane is empty", a plausible assertion outcome, so a call with its arguments swapped passed for the wrong reason and kept passing. A panic rather than an error for the same reason&slice[3..0]panics: a backwards literal range is a mistake in the calling source, not a fact about the terminal. Out-of-range bounds are a different thing and stay clamped. -
An implausible terminal size is refused, at most 1000 per axis, with the limit named.
5000x5000used to spawn happily and then spend 16 seconds inside the first wait before timing out with a message about the predicate — a transposed.size()turned a sub-second test into a wedged one with no hint of why.resizeis held to the same limit. -
Screen::containsandScreen::findfold both sides to NFC, so a needle finds text the application normalized the other way. A terminal drawscaf\u{e9}andcafe\u{301}identically — and so do the failure output and the diff, which is what made the mismatch a trap rather than a limitation: an author types NFC (what editors produce) while text from a filesystem path, a git author name or macOS input is frequently NFD. Unconditional, and no escape hatch is needed because the raw form is never taken away:text,row_text,rect_text,cellandtitleall still return exactly the codepoints the application sent. One consequence worth knowing: matching is grapheme-shaped, so on a screen showingcaf\u{e9},contains("cafe")is now false — the screen does not showcafe.
Screen::repaints— how many synchronized updates the application has completed, as of this observation, on every snapshot including the frameswait_framereturns. It counts repaints, not changes, so a Begin/End pair that drew nothing still counts, which is exactly the property an amplification test needs: "one wheel notch produced four repaints" is invisible to every content predicate, because each intermediate frame shows correct content.Terminal::frame_timingsandFrameTiming— per-repaint wall-clock cost and printable-character count, so a suite can hold a performance line as well as a correctness one. A TUI's most common regression is not wrong output; it is a repaint that got slower or larger, and no content predicate sees either. Both ends of the span are stamped at the byte carrying the marker, not when the read arrived, so a burst delivered in one read is still timed per frame. The docs state what the span includes rather than leaving it to be assumed: it is measured through a PTY and covers the application's write pacing, so it is a trend to watch and not a render benchmark. Bounded at 512 repaints, independently of the eight frameswait_frameretains, since a timing is three words where a frame is a whole grid.Screen::bells— how many times the application rangBEL. The bell is often the only feedback a rejected input produces, so "an invalid key does nothing" and "an invalid key is refused with a bell" used to be the same screen. A count, not a flag, so twice differs from once; and only aBELin ground state counts, since the one terminating anOSCstring is punctuation and one inside a DCS-class string is payload.Screen::graphicsandGraphicsSeen— kitty (APC G … ST) and sixel (DCS q … ST) payloads transmitted, by protocol, with total bytes. The assertion this exists for is as often the negative one —assert!(s.graphics().is_empty()), "this must render as text in every terminal and never go out as an image" — sois_emptyis a method rather than something to spell out. Observing is not rendering and claims nothing: DA1 still declines both protocols.- The kitty graphics query is diagnosed.
APC _G…a=q…STwas swallowed whole — no answer and no mention in the timeout note, alone among the startup probes, becausestring_finalinspected only+q/$qand an APC matches neither. An application blocked on it now gets the same one-line diagnosis^[[?uand^[P+q…already got. Only an explicita=qcounts as a question: a transmission is an instruction, and treating one as a query would put "the application queried the terminal" into the next timeout of every application that draws. XTGETTCAPis answered — the last of the common startup probes with no reply. A capability termlens genuinely implements gets a truthfulDCS 1 + r <name>=<value> ST; anything else gets an explicitDCS 0 + r <name> ST, which is the half that turns a hang into a decision: the application learns the answer is no instead of waiting for one. The set isTN/name(whateverTERMthe child was actually given, so the two cannot disagree),Co/colors, and the cursor, home/end, delete, page and backspace keys — each the exact bytesKey::encodeemits, checked against the code that emits them rather than copied from a terminfo file. One reply per requested capability, because the status flag is per-reply and a mixed request cannot be answered in one frame without lying about half of it.TerminalBuilder::cell_size— pixels per character cell, which is the one number every layout decision in an image-drawing application rests on.CSI 16 tthen answersCSI 6 ; h ; w t,CSI 14 tanswers the window size in pixels, andTIOCGWINSZcarries the same geometry instead of contradicting it; aresizerecomputes all three. Opt-in: unset, the two reports stay unanswered and the ioctl reports zero pixels — which is what a real terminal reports when it has none, so the default is not a lie and no existing suite moves onto a pixel branch.TerminalBuilder::graphicsandGraphics— declare the inline-graphics support of the terminal being simulated.Graphics::Sixeladds4to the DA1 reply;Graphics::Kittyanswers thea=qcapability probe withAPC _G i=<id> ; OK ST, echoing the id the probe named. Default unchanged: nothing claimed. This is not the harness lying — it is the test author stating which terminal is simulated, the waybackground_rgbstates a background — and it matters because for an application that probes first the pixel path is not merely unasserted, it is unreachable: the code never runs, so nothing about it is testable.Terminal::send_after— wait, then send, so this write and the previous one land in separate reads. The remedy for theEscwire ambiguity when theEschas no observable effect to wait for: a vim-style TUI whereEscleaves insert mode silently andjthen moves down could not be driven at all, because sending them together is byte-identical toAlt+j. The delay is a named argument, not a hidden constant, andsend(Key::Esc)carries no default separation — most suites sendEscwith nothing behind it, and a hidden sleep would slow all of them for a hazard they do not have while making the tests that need it work for a reason invisible at the call site.Terminal::focus_in/Terminal::focus_outandScreen::focus_events— focus reporting (mode 1004). The unfocused branch of a UI was not merely unasserted, it was unreachable: no input existed that could enter it, so the code never ran. Mode-aware like every other input — refused with a typed error when the application never enabled 1004, exactly asclickis refused without mouse tracking.DECRQMnow answers for 1004 as well, since termlens tracks it exactly, which is the honesty rule's precondition; it previously reported "not recognized" even immediately after the application enabled it.Error::Write, carrying the screen at the moment of the failed write, the wayError::TimeoutandError::Eofalready do.Error::screen()returns it.Screenis 40 bytes instead of 80, with all out-of-band state behind oneArc. AScreenis embedded in everyError, so this shrinks everyResultin the crate, and a clone — taken on each wait evaluation — is now one refcount bump rather than a field-by-field copy.
- The README, crate docs and design notes describe 0.5. The README's
headline example now propagates the
Resultthatsendreturns — it is the first code anyone copies — its limitations section dropsXTGETTCAP(0.5 answers it) and gains the two bounds this release introduced: graphics are observed and offered but never rendered, and a reply the terminal's own input queue cannot hold may not arrive, undetectably so on Linux. The docs.rs landing page anddocs/DESIGN.md§6 gained the observability counters, focus events, per-cell drag motion andsend_after. SECURITY.md's resource bounds match the code again. The reply queue is a 1 MiB byte cap rather than "a fixed depth", and the note now says why a depth bounds the wrong thing: two earlier versions counted slots and both shorted a well-behaved application, while a byte bound leaves the queue unbounded so the drain can never block on it.- What a large grid costs, on
TerminalBuilder::size: a snapshot holds one entry per cell and is rebuilt on every state change, so the cost is O(cells) and shape-independent, while repeat reads of an unchanged screen are cached and free. The table gives release and debug figures, becausecargo testbuilds unoptimized by default and the two differ by 16-29x — the debug column is the one most suites actually see.
0.4.2 - 2026-08-19
The documentation set, brought up to what 0.4 actually does.
Two statements were wrong and the rest understated the crate by a release or two. No library code changed.
0.4.1 was tagged for exactly this content and never published: its
release run caught a latent race in this suite's own UTF-8 mouse test —
padding written after a click could be read by the script's exit guard
instead of by head, ending the child early so the next write failed
with EIO. Fixed before publishing, so the version on crates.io is the one
whose gates all passed.
- The README no longer contradicts itself about scrollback. Its
limitations section was still headed
(v0.3)and still opened with "No scrollback assertions" — sixty lines below the paragraph explaining that scrollback is retained, 1000 rows by default. Since the README is the crates.io front page, the first thing a reader learned about 0.4's headline feature was that it did not exist. The section now states the bounds that actually hold: history is capped, text only and unreflowed;wait_frameneeds the application to opt into DEC 2026 and retains eight frames; and the questions termlens declines to guess at are named. SECURITY.mdno longer claims the emulator runs with zero scrollback. That sentence was the whole memory-bound argument in the resource-exhaustion note, and 0.4 made it false — the emulator is constructed with the configured history length. Every bound a child's output can reach is listed in its place: history length, retained frames, the read buffer, theOSC 52capture cap, the reply queue, and the diagnostics set.
- The crate-level docs describe 0.4, not 0.2. The docs.rs landing page
never mentioned
wait_frame, retained scrollback, per-call deadlines or the clipboard accessor, so the crate's own front page understated it by two releases. It now names them, in the same breath as the guarantees that make them worth using. docs/DESIGN.md§2 records the per-call deadlines. The document that calls itself the contract for wait semantics had never mentioned the_forvariants. It also now records thewait_idletimeout that names an unfinished frame instead of reporting silence against a quiet terminal.docs/HANDOFF.mdis marked as the historical v0.1 record it is, rather than reading as a description of the project today — it described a private repository and an unfinished go-public checklist. The checklist keeps its original text, with the outcome recorded beneath it, including the one item resolved differently on purpose (required approvals stay at 0: a solo maintainer cannot approve their own pull request).- The announcement draft carried v0.1's limitations, two of which have
since shipped; it now describes 0.4, and no longer claims to be untracked
while sitting in the repository. The bug-report template no longer offers
0.1.0as its example version.
No library code changed in this release.
0.4.0 - 2026-08-18
What termlens could not do, and where it quietly did the wrong thing.
Three gaps each made a whole category of subject untestable, and four defects were found by adversarially probing the 0.3.0 release rather than by reading its source — two of them undercutting the frame guarantee that is this crate's headline.
wait_frameandwait_frame_forreturnResult<Screen>— the frame the predicate matched. Assert on that rather than on a laterscreen(), which can already be a newer state; the old shape let a test assert on one instant and read another. The dominantt.wait_frame(..)?;call form still compiles unchanged.wait_frameno longer offers a frame twice. Each call scans only frames newer than the one it last returned. A frame that satisfied a wait cannot satisfy the next, so N calls observe N distinct frames, a burst is observable in emission order (asking backwards now fails), andsend(key)followed bywait_frame(|s| s.contains(OLD_STATE))times out instead of passing on the superseded frame while the assertion after it reads the old screen. A frame completed before the call but never yet returned still matches, deliberately: a fast application must not be able to slip one past two waits.resizeadvances the cursor too — a frame drawn at the old size is not the repaint that answers the new one.Stylegained the public fieldsblink,concealandstrikethrough, so struct literals need updating (..Style::default()keeps working).with_styles()emits the new tokens in SGR order —bold dim italic underline blink reverse conceal strikethrough— which leaves an existing span's tokens unchanged unless the cell carries one of the three.- Scrollback is retained by default (1000 rows;
TerminalBuilder::scrollback(0)restores the old behaviour). Snapshots now carry history, which is invisible in the text rendering, so existing snapshot files stay valid.
- Scrollback retention. Content that scrolled off the top used to
cease to exist, which ruled out every application that hands finished
output back to the terminal — a pager, a log view, a TUI that commits
completed blocks into native scrollback and keeps a small live region.
TerminalBuilder::scrollback(rows)sizes the history, andScreengainedscrollback_rows,scrollback_textandfull_text— history followed by the visible screen, which is the assertion an author actually writes when the application moves content between regions as it runs. Two limits are stated rather than papered over: history is bounded, and resize does not reflow. It costs nothing where unused: the alternate screen accumulates no history at all. Style::conceal,blinkandstrikethrough.SGR 5/6,8and9reached nothing, so three renderings collapsed into one value. Conceal was not a missing nicety but a trap: a test asserting that a password field is masked passed against an application that printed the secret in clear, andwith_styles()could not break the tie either. That was the one failure mode in this crate where a green test certified the bug it was written to catch.OSC 52clipboard capture.Screen::clipboard()reports the most recent write — the decoded text and the target selections as the application named them — so "did it copy the right thing?" is answerable instead of resting on the application's own toast. An undecodable payload reportsNone, neverSome(""): bad base64, bytes that are not UTF-8 and a payload past the capture bound are all distinct from a real write of nothing. Clipboard reads stay named-but-unanswered.
- A stray
?2026lno longer publishes a phantom frame. The frame publisher fired on any End, whether or not a Begin was seen. The damaging case was not a false pass but a suppressed diagnosis: applications reset terminal modes defensively at startup and on crash, and such a string contains?2026l, so one stray End pushed the frame count off zero and replaced "the application never emitted a DEC 2026 synchronized update — usewait_until" with a count implying the predicate was at fault. A frame is now one completed update; a Begin/End pair that changed nothing still counts, because the count is of repaints rather than of changes. DECRQMno longer calls the mouse tracking modes "not recognized" when none is active. The old answer set was self-contradictory — claiming the SGR mouse encoding while denying the tracking modes those reports come from — and it closed a loop on itself: an application doing ordinary probe-then-enable detection concluded the terminal had no mouse, never enabled tracking, andclickthen refused, blaming it for a decision termlens caused. With nothing tracking, nothing was collapsed and every tracking mode is genuinely reset. The ambiguous case — probing1000while1002is active — stays "not recognized", since the backend keeps only the last of a group.wait_idletimeouts name an unfinished frame. An application stuck inside an open synchronized update is silent, so it used to time out "waiting for 100ms of output silence", which reads as nonsense next to a quiet terminal. The message now says the application is inside an unfinished DEC 2026 update and that the screen below is a half-painted frame.- Timeout messages from
wait_framecarry the reason as well as the count: when every frame has already been returned, the message says the application has not repainted rather than implying the predicate is wrong. Pluralization fixed while there.
- A snapshot may be a half-painted frame, including for an
application that brackets every repaint in DEC 2026 exactly as
intended:
wait_frameis frame-gated,screen()is not. Now stated onscreen, onwait_until's third rule, and indocs/DESIGN.md§2 with the three routes to a frame-consistent read — one per way of waiting. The behaviour is deliberate: substituting the newest complete frame would let await_untilpredicate match content the followingscreen()does not show, and a torn read is what you want when diagnosing an application hung mid-repaint. wait_idlewill not declare idleness while a synchronized update is open — it treats a begun-and-unfinished repaint the way it treats a half-received escape sequence. That is what makes the "settle before whole-screen snapshots" rule work, and it is now a stated guarantee rather than an implementation detail.
0.3.0 - 2026-08-17
The features the first real user's coverage study asked for, in the order it ranked them, plus the terminal-query work that lets capability-probing applications run against termlens unmodified.
ScrollgainedLeftandRightvariants and is now#[non_exhaustive]. Exhaustivematchon it needs a wildcard arm; marking it non-exhaustive means later additions won't break code again.
- Writes now respect the terminal's deadline.
send,send_str,paste,clickandscrollused to block indefinitely if the application stopped reading its input and the PTY buffer filled — the one place the crate's own "no unbounded waits" rule wasn't applied. They now fail at the deadline with the screen attached and a message naming the real cause, instead of hanging a CI job. - A fuller mouse API:
click_with(button, col, row)for middle and right buttons,drag(button, from, to), modifier chords (MouseButton::Left.ctrl(), mirroringKey::Right.ctrl()), and horizontal wheel viaScroll::Left/Scroll::Right. Everything stays mode-aware: encoded for the tracking mode and encoding the application enabled, and refused with a typed error when the mode cannot express the gesture — a drag under X10, which reports no release, is an error rather than a misleading half-gesture. - termlens answers
DECRQM("is private mode n set?"), so an application that probes before using synchronized output enables it against termlens —wait_frameworks against programs nobody modified for the harness. Replies are truthful or absent: modes whose state the emulator holds exactly report set/reset, everything else reports "not recognized" rather than a guess.DECRQSS,OSC 4palette reads andOSC 52clipboard reads are now recognized too, so an application blocked on one is named in the timeout instead of hanging silently. TerminalBuilder::foreground_rgbconfigures theOSC 10answer, which was hardcoded white. Applications that pick a theme by comparing foreground and background luminance can now be tested against both.- Every wait now takes a per-call deadline:
wait_frame_for,wait_idle_forandwait_exit_forjoinwait_until_for. One known-slow step no longer forces the builder timeout up for every other wait in the suite — which is what made a genuinely stuck application burn the long timeout on its first failure. Timeout errors report the deadline that actually applied. wait_frameretains the last 8 completed frames and evaluates them oldest first, so a burst of frames arriving in a single read is observable step by step — a progress counter ticking1,2,3in one write used to be visible only at3. The retention bound and its two consequences (a longer burst drops its oldest frames; a retained frame stays matchable, so a predicate satisfied earlier resolves at once) are documented onwait_frameand indocs/DESIGN.md§2.
0.2.1 - 2026-08-12
Correctness patch. Every entry below was found by probing the published 0.2.0 rather than reading the source, and each one is a case where the harness quietly did the wrong thing, panicked inside a dependency, or — in the worst of them — hung itself.
pastenow transforms the text the way a real terminal does, so what the application receives matches what a user pasting would produce. Line breaks become\r(the byte Enter sends; applications in raw mode never see\nfrom a terminal), and while bracketed paste is active, paste markers embedded in the text are removed — previously anESC[201~inside the text ended the paste early and the remainder arrived as ordinary key presses.send_strremains the untransformed path.
- The harness can no longer deadlock itself. Query replies were
written by the reader thread, so an application that emitted queries
faster than it read the answers filled the PTY's input queue, blocked
that write, and stopped the drain — after which the child blocked
writing and neither side could proceed. Reproduced in the default
configuration with no test input at all: the wait timed out with a
stale screen and then
Dropnever returned. Replies now go to a dedicated responder thread, so the drain never writes; undeliverable replies are counted and reported ("the application is not reading its input") instead of stalling anything.Drop's reap is bounded too — teardown must always terminate. - Mouse reports now follow the UTF-8 encoding (mode 1005) when the application selects it. The encoding was collapsed to "SGR or not", so a 1005 application received the legacy form — identical below column 95, and a bare non-UTF-8 byte past it, which such an application cannot decode.
- The unanswered-query diagnosis no longer misattributes unrelated
failures. It was recorded once and never cleared, so a single
deliberately-unanswered probe at startup (kitty's
CSI ? uis the common one) claimed to be the cause of every later timeout. A query is now only blamed while the application has produced no output since asking; otherwise it is reported as context. Every unanswered query is named rather than just the most recent, the set is bounded, andwait_frameand theEoferrors carry the note too — previouslywait_framewithheld it, which is the worst place for it to be missing, since an application blocked on a probe never reaches its first repaint. wait_frametimeouts embed the live screen, like every other wait. They previously embedded the last completed frame — which can be arbitrarily old — under a header saying "screen at timeout", so the one place a CI log is the only evidence showed the wrong screen. The count of observed frames is still in the message.- A zero terminal dimension is now a typed
Error::Inputfromspawnandresizeinstead of a panic inside the emulator. In release builds — the profile the stress workflow uses — it was worse than a panic: the arithmetic wrapped, both calls returnedOk, and the emulator panicked on the reader thread, silently killing the drain so every later snapshot was blank and a careless test went green. current_dirpointing at a path that is not an existing directory now fails the spawn instead of being silently ignored: the PTY layer falls back to the home directory, so a directory-sensitive test could pass against the wrong tree with no error anywhere.spawn("")now fails with a one-lineError::Spawnnaming the problem instead of surfacing the PTY layer's entirePATHsearch. Genuine "program not found" failures keep their underlying diagnosis.
0.2.0 - 2026-08-11
- The three rules for race-free waits — one predicate, wait on the last
thing painted, settle before whole-screen snapshots — and the resize
stale-frame trap are now documented where you'll meet them: on
wait_untilandresizein the rustdoc, and indocs/DESIGN.md§2 with the first real user's before/after failures. - Process ergonomics:
TerminalBuilder::current_dir(dir)runs the child in a chosen working directory (no morecd … && …through a shell);Terminal::pid()exposes the child's process id;Terminal::signal(Signal::Term)(Unix) delivers real signals so graceful-shutdown paths are testable — with a guard that refuses to signal an already-reaped pid, which the OS may have reused; andwait_until_for(pred, timeout)gives the one known-slow wait its own deadline instead of dragging the builder default up for every wait. - Three
Screenquery helpers, each earned by a documented pain in the first real user's test suite:rect_text(cols, rows)— the text inside a rectangle (any range expression, clamped to the screen), for asserting on one pane of a split layout;find_by(|cell| …)— the first cell matching a predicate, for "where did the highlight go"; andfindnow locates multi-row needles (find("one\ntwo")) with exactly the matching semanticscontainsalways had for them. - Out-of-band terminal state is readable from every
Screensnapshot:title()(tracked fromOSC 0/OSC 2by termlens itself — the emulator backend doesn't need to support it),alternate_screen(),bracketed_paste(),application_cursor(), andmouse_mode()(the new publicMouseModeenum, reporting the exact tracking mode the application enabled). State that previously could only be inferred from grid contents is now a plain assertion:wait_until(|s| s.alternate_screen()). None of it appears in the snapshot text format — existing snapshot files stay valid. - Cursor keys are mode-aware: while the application has DECCKM
(application cursor mode) set,
send(Key::Up)emits theESC O Aform a real terminal would — the emulator knows the mode.Key::encodestill documents the default-mode bytes, and theEsc-then-key wire ambiguity (identical to an Alt chord) is now documented onKey::Escwith the working idiom. Terminal::paste(text): pastes the way a terminal pastes — wrapped in bracketed-paste markers when the application enabled mode 2004 (onePasteevent, not a burst of key presses), plain bytes when it didn't.- Modifier chords over special keys:
Key::Right.ctrl(),Key::Up.shift(),Key::F(5).ctrl().shift()— the xterm CSI-modifier encodings, chainable, accepted by the sameTerminal::send. Character chords stayKey::Ctrl(c)/Key::Alt(c)(the builder methods say so loudly if you mix them up). Terminal::click(col, row)andTerminal::scroll(col, row, Scroll): typed mouse input, encoded exactly as the tracking mode and encoding the application enabled (SGR 1006 or the legacy byte form), with a press-only form for X10 mode. Clicking while the app never enabled mouse tracking is a typedError::Inputinstead of bytes the app would misparse.Screen::with_styles(): the plain snapshot rendering followed by a compactstyles:block (run-length spans per row, format specified indocs/DESIGN.md§3) — a highlight moving to another row or a color changing is now a visible snapshot diff. Plain snapshots stay text-only; this is the opt-in.- termlens now answers terminal queries (on by default): DSR cursor
position — exact as of the query byte — operating status, DA1/DA2
device attributes,
CSI 18 ttext-area size, andOSC 10/11color queries (TerminalBuilder::background_rgbconfigures the reported background). Capability-probing applications run instead of hanging. Recognized-but-unanswerable questions (XTGETTCAP, kittyCSI ? u, pixel-size reports, …) are named inside the next wait timeout error, turning a silent hang into a diagnosis;answer_queries(false)mutes the responder while keeping the diagnosis. Terminal::wait_frame(pred): evaluates the predicate only on complete frames for applications that bracket repaints in DEC 2026 synchronized updates — a torn, half-painted repaint is never observable. Apps that don't emit synchronized output get a timeout error that says so and points atwait_until.
wait_idleno longer resolves while a synchronized update is open: a begun-but-unfinished repaint is mid-update by definition.
0.1.1 - 2026-08-09
- Publishing runs exclusively through crates.io Trusted Publishing (short-lived OIDC tokens), bound to a tag-restricted GitHub environment; the repository stores no secrets at all.
- README install instructions now include
insta, which the snapshot examples use — copying the example verbatim previously failed on an unresolved import. - README comparison table links
teatestlike every other row (first external contribution). - CONTRIBUTING documents the fork-PR experience: the first-run approval gate and where commit-policy failures are explained when the courtesy comment cannot post.
0.1.0 - 2026-08-09
- Renamed the project from
termtesttotermlensbefore first publish: an active Go library of the same name occupies the identical niche (github.com/ActiveState/termtest), and the new name says what the crate actually does — assert on what is seen through the terminal.
- Initial implementation of the
termlenscrate: spawn any terminal program in a real PTY, drive it with typed key input, and assert or snapshot on the emulated screen grid. Terminal/TerminalBuilderwith strict environment control, size configuration, and a default deadline applied to everywait_*call.Screenvalue type with cell/row/cursor accessors and a deterministic textDisplayformat designed forinstasnapshots.Keyenum covering chars, control chords, alt chords, and xterm special keys (arrows, Home/End, PageUp/Down, F1–F12, Tab/BackTab, Delete, …).wait_until,wait_idle,wait_exit, andresize(TIOCSWINSZ + SIGWINCH) semantics; timeout errors embed the current screen dump.instacargo feature (default): re-exportsinstaand provides theassert_screen_snapshot!helper macro.- Deterministic PTY fixture apps (
hello-tui,form-echo,resize-echo,unicode-torture) used by the integration suite. inspectexample: run any command and print its rendered screen.ExitStatus::signal(): the terminating signal's name when the child died from a signal instead of exiting;Displaynow sayskilled by signal: … (code …)so harness-level kills are never mistaken for application exit codes. (ExitStatusisClonebut no longerCopy.)Screen'sDebugis now the compact header+text rendering: a failingResulttest prints a readable screen instead of a one-line cell dump.Screen::cols()andScreen::rows(): named size accessors, so nobody has to remember thatsize()is(cols, rows)while cells are addressed(row, col).
- Snapshots are cached per state generation:
Terminal::screen()on a quiescent terminal now costs anArcclone (~ns) instead of a full grid conversion (~16µs at 80×24), andwait_untilskips re-evaluating its predicate on wakes where nothing changed. Streaming throughput is unaffected (verified with interleaved A/B benchmarks).
- PTY lifecycle edges (open+spawn / kill+reap+close) are serialized behind
a process-wide lock: on macOS, a concurrent teardown's
revoke()could hit another thread's freshly recycled pty device and kill its child at birth. Found by the stress workflow; seedocs/DESIGN.md§2. - The PTY reader thread now attaches before the child is spawned, so a
program that writes and exits within its first millisecond meets a drain
that is already running. This narrows (but cannot fully close — see the
instant-exit caveat in
docs/DESIGN.md) an output-loss race in the OS pty teardown, found by the stress workflow at roughly 1 in 80 instant-exit spawns on macOS.