tui: the lifecycle — every way out is one road, Static, print, the clock and progress; step 5 complete

[shreeve]

PLAN step 5, both halves, reviewed cold and planned by three agents; every finding fixed and proven under a real job-controlled pty.

terminal.rip. One idempotent setup / teardown owns raw mode, bracketed paste, focus reports, the mouse modes, the kitty push and pop, the probes, the cursor, and the alternate screen (altScreen: true, ?1049h, frames absolute, left after the last frame). Every way out — quit, Ctrl-C, SIGINT / SIGTERM / SIGHUP (exit 128 + n), an uncaught error or unhandled rejection (exit 1), process.exit, beforeExit with a live app, a listener or frame that throws, a stdin whose raw mode cannot be set, a write that fails at close — takes the same road. The process handlers belong to the app's life: on at open (terminal only, ahead of the runtime's), off first at teardown, never touched by suspend or resume; a crash closes the app with its error (done rejects), removes our handlers, and leaves the error to the listeners after ours, once. A fuzz of keys, resizes, logs and suspends holds the terminal's modes to what the app believes after every step.

Suspend. Ctrl-Z is a default action of keydown (preventable): teardown, then SIGTSTP to the whole process group — what the tty driver does for a cooked ^Z — and only when the app reads the process's own stdin (a fake stream is not the terminal's job, so in-process tests take the same road without the signal). A stopped app holds the loop, so a timer-less app survives fg; on SIGCONT: setup, the origin asked again with the mouse, the kitty flag re-pushed only if it was pushed, pointer and parser reset, a whole repaint at the terminal's size. suspend(fn) is the same road without the signal. Keys left in the read that carried the ^Z are nobody's. Proven under test/terminal/ptyrun.py, a job-controlled pty shell checked in with the suite: ^Z stops the job leader (the bin/rip wrapper), %fg continues a key-driven app with no timer and it redraws whole and hears the next key, ^Z + SIGTERM + %fg exits 143 with the user's exit hook run, two stops and two continues exit 0. A stop signal to an orphaned process group is discarded by the kernel, so only such a shell can prove a stop; the earlier "for real" pin never did and is gone.

Output. Static paints each keyed child once, as its own rows at the terminal's width, written above the live frame and never again — a no-op on the alternate screen, written as it arrives off a terminal. print(text) and print.err write above the frame the same way; console output is captured by one node:console Console over two sinks, so every writing method (table, group, trace, assert, count, time*…) lands above the frame and the alternate screen replays it at leave. All three go through Screen.above: the frame's row moves down by the lines written, so a click after a log still lands on its row. clock(interval) is one shared timer per interval that runs only while a mounted component reads it and stops at close. screen.progress drives the terminal's own indicator (OSC 9;4), sent with the frame's write and cleared on every way out. Newline. renderToString answers the rows Static wrote and then the frame.

Off a terminal. No modes, no probes, no raw mode; the last frame is written once at exit, Static items as they arrive. Color depth is read once (screen.colors): NO_COLOR present and not empty is none; FORCE_COLOR 0 / false none, 1–3 that depth, true or empty 16; else by COLORTERM and TERM. Below full depth a color becomes the nearest of xterm's 256 by RGB distance (a color on the cube is sent as that point), and below that the nearest of xterm's 16 — a 256-entry table of xterm's own values, pinned at 33 points at both depths.

Held to Ink. 27 lifecycle titles held and 1 stated difference (test/terminal/SOURCE.md, recounted per file with sites and titles); 50 more paint cases in test/ink/static.rip (540 in the Ink suite, 521 of Ink's 632 titles); examples/log.rip is a build log — Static steps into the scrollback, a spinner on the clock, a progress bar, a print.

Also here: the Static cleanup reads its ref: cell directly (PR #402 made that sound) with a pin that a Static under a swapping if builds once; bin/rip maps a signal death to 128 + n.

Suites: test 129, text 49, layout 57, input 316, events 226, mouse 65, ink 540, yoga 543 (4 pinned), yoga-aspect 37, yoga-hand 53, fuzz 7, damage 6, terminal 78. The pty harness leaves no process behind (checked right after the suite and ten seconds later). bun run test:all: 29 lanes, 12,632 tests.