feat: fullscreen terminal UI for interactive sessions

[webmatze]

Interactive sessions on a real terminal now render through a fullscreen UI instead of plain print lines.

What it does

The transcript stays in the terminal's scrollback — copyable, searchable, no alternate screen — while the bottom of the screen carries a live region: streaming assistant text, running tools with spinner and elapsed time, a status bar (model, mode, tokens, cost) and the input line. Finished blocks are printed into the scrollback once and never redrawn.

• Enter submits, Esc clears the input, Up/Down walks prompt history, Ctrl+L redraws from scratch — in any state, including mid-turn and under a panel. Resizing the window redraws it too, once the drag has come to rest.
• While the agent works, Esc asks it to stop; a second press within two seconds exits.
• Approval, plan review and the hooks trust prompt are panels answered with a single key (y/n/a, Escape = refuse) — nothing reads from plain stdin any more.
• --no-tui falls back to the line renderer; --tui asks for the fullscreen one explicitly. It cannot conjure a terminal — raw mode needs stdin and stdout to be one — so where there is none it says why it is downgrading instead of doing so silently. Headless smith run stays plain, so its output remains scriptable.

Layout

file	role
src/smith/ui/terminal.cr	raw mode, size/SIGWINCH, key parsing (incl. bracketed paste)
src/smith/ui/style.cr	spans, styles, display width, wrap/truncate, palette
src/smith/ui/markdown.cr	markdown → styled lines
src/smith/ui/view_model.cr	the block types the UI draws
src/smith/ui/input_editor.cr	the prompt editor and its history
src/smith/ui/app.cr	the controller: block list, key loop, modals, drawing
src/smith/ui/renderer.cr	the third Output::Renderer — events → blocks
src/smith/ui/gates.cr	approver, plan gate and trust prompt as panels
src/smith/presentation.cr	the seam: renderer, gates and stray-line output, per mode
src/smith/ui/presentation.cr	the fullscreen half of it

The live region has to fit

The live region is redrawn in place, and that only works while it fits on the screen: cursor_up stops at the top row, so a region taller than the screen can never be walked back over — every tick pushed another copy of it into the scrollback. An approval modal stacked on top of a still-running tool block was the usual way to get there, which is why the spinner lines appeared to repeat instead of animating in place. Region lines are also truncated to the terminal width, since a wrapped line occupies two rows and puts the redraw out of step with the screen the same way.

So the region is clamped to the terminal height — but what gives way matters. Lines are assembled as pinned and droppable segments: the modal's question, its choices, the status bar and the prompt keep their rows; the blocks in flight and the modal's body give way behind a ⋮ N more lines above marker. Clamping by tail alone evicted the question first, leaving the user asked to approve an unnamed thing. Where even the pinned lines do not fit — a terminal a handful of rows tall — the question still keeps its row ahead of the keys that answer it.

TuiApprover wraps its summary to the real width instead of a hardcoded 200 columns and elides after 8 lines, so an edit/write call with a page-long payload cannot inflate the panel in the first place.

A resize is the one thing an in-place redraw cannot answer at all: the terminal re-wraps the screen underneath the region, so the rows clear_drawn! walks back over are not the rows it drew — it clears the wrong ones and leaves the old frame standing, which is why the window looked frozen until the next keystroke. It redraws from scratch instead, and waits for the drag to finish first: dragging an edge delivers a SIGWINCH per step, and repainting on each is both wasted work and visible flicker. Three quiet poll windows in a row count as the end of it. The flag is cleared the moment it is seen, because read_key reports Resized for as long as it is up — modal_sync, which runs its own key loop, never cleared it and spun at full tilt when a window was resized while the hooks trust prompt was on screen.

One seam instead of nine branches

The CLI asked if @interactive_tui in nine places — for the renderer, the approver, the trust prompt, the plan gate, the diagnostics IO, and three lines of stray text. It is one question about the same pair of answers, so it is asked once: Smith::Presentation holds what differs, PlainPresentation wraps whichever renderer the run asked for, UI::TuiPresentation wraps the app, and the CLI picks one before an interactive session starts.

What stays in the CLI is the part that was never presentation: whether to ask at all. --yes and a missing TTY still settle that first, and in the same order — the presentation only decides how the asking looks. The one remaining branch on the flag is which session loop runs, which is a fork rather than a variant.

Two things fell out of it: incidental text now goes to prompt_io like a question does, so a headless --json run with background jobs to stop no longer drops a line into the middle of the JSONL stream; and in plain mode that line gains the three-space indent every other incidental line has.

Tests

spec/smith/ui/support/screen.cr is a small grid terminal emulator (text, CR/LF, \e[A/B/G/H/J/K) that keeps what scrolled off the top — which is exactly what the in-place redraw must never produce. The regression specs replay a tall approval modal through it and assert the tool line reaches the scrollback exactly once, that no copy of the panel was ever pushed off the top, and that the question, the marker and the tail of the body appear in that order — down to a six-row terminal. spec/smith/presentation_spec.cr pins both halves of the seam: which gates each builds, and that neither stray text nor a question can reach stdout in JSON mode.

781 examples, 0 failures. crystal tool format --check clean.

🤖 Generated with Claude Code