thurbox: Skill for Claude Code

Thurbox render-loop performance

Working reference indexed by AGENTS.md. The rationale behind these decisions is owned by the docs under docs/; a change that invalidates what this says updates it in the same PR.

Performance (render loop)

Nothing on the loop waits on a network (ADR-P7/P12 for connecting, ADR-P24 for a connection already open). The trap ADR-P24 closes is that an open link can go bad without failing: it carries nothing, no ssh keepalive fires, and a round trip that is sub-millisecond when healthy becomes COMMAND_TIMEOUT plus a reconnect plus another COMMAND_TIMEOUT. So a command issued from the loop is either detached (send_command_detached, for one whose answer no frame reads — the pane resize behind a paint) or bounded (ctrl_command_within, for one the loop must have an answer to — the passthrough gate's is_dead), and the bound covers the control lock too, not just the answer. Reproduced by the wedged-link scenarios in tests/tui_e2e.rs; see the thurbox-testing skill for how the stand-in ssh builds the byte relay a local tmux does not have.

The loop is demand-driven: it paints when something changed or when the 250 ms forced-redraw floor (FORCE_REDRAW_INTERVAL) elapses, never on every iteration. There are two floors between paints, because typing has to feel instant and watching a log scroll does not: MIN_FRAME_INTERVAL (16 ms) when a person did something — a key, a resize, a worker result they asked for, tracked by input_dirty, which is set with dirty through the one App::note_input and never alone — and OUTPUT_FRAME_INTERVAL (33 ms) when the only thing owing a frame is agent output. Applying the tight floor to both made a chatty agent drive 60 paints a second to show 30 lines; the split is worth 30% of the loaded cost (ADR-P17). A keystroke's echo is on neither floor (ADR-P28): a key sent to a terminal owes an echo (EchoWait), the loop sleeps in poll(2) on the terminal and on the backend::output_wake self-pipe (poked only by that pane's reader) until it comes, holds the key's own frame for it (ECHO_HOLD), and paints it at once as the last full frame with only that surface repainted (paint_echo_frame) — rapid keys queue successive output sequences rather than replacing one pending wait; one such frame per key, and declined whenever anything is drawn over the panes. What marks the screen dirty: any input, a resize, a reload, a worker result, and new agent output — Terminals::visible_output_generation sums only the surfaces painted last frame, so visible output is responsive while hidden output owes no frame. The all-pane output_generation still invalidates content search (ADR-P29). It sums each pane's output_seq, bumped after the parse, never the millisecond last_output_at: that stamp was stored before the parse and cannot tell two chunks in one millisecond apart. What does not: background housekeeping. A command answering Command::is_housekeeping() (the 5-second deleted-session sweep or a Codex status reset after delivered input) is dispatched to a worker with no in-flight record, so it reaches neither thurbox.commands, nor the message band, nor the animation clock — recorded like a command someone pressed, the sweep reserved a band row and gave it back every five seconds, and a band row appearing is a reflow (ADR-P22). A reflow — the arrangement placing a slot at a new rect, so a column opened or closed — additionally forces one full repaint: the cell diff is only correct while ratatui and the terminal agree on a glyph's width, and where they cannot (a flag, an emoji presentation sequence) the pane that closed leaves characters behind. kernel::paint::normalize_ambiguous_width strips the one such disagreement that is strippable — U+FE0F — from every painted cell, panes and vt100 surfaces alike, and kernel::paint::force_full_repaint covers the rest by marking every cell of the reflowed frame as one the diff must print. It is deliberately not Terminal::clear: erasing flushes a blank screen and leaves the repaint to the next flush, so every pane toggle blinked the whole interface.