@cruxy/cli 1.2.1 → 1.4.0

package/dist/tui/renderer.js

@@ -0,0 +1,1121 @@
+import { resolveTheme } from "../theme/index.js";
+import { createStreamPrinter } from "../cli/stream-print.js";
+import { createFrame } from "../components/frame.js";
+import { renderActionPreview } from "../render/diff.js";
+import { createStreamHighlighter, } from "../render/highlight.js";
+import { reflow } from "../render/layout.js";
+import { createFrameClock, spinnerGlyph, } from "../render/motion.js";
+import { planChecklist } from "../render/plan-view.js";
+import { testResultLines } from "../render/test-view.js";
+import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "../render/state.js";
+import { budgetColumns, bodyRows, composeScreen, droppedForWidth, fitOverlay, overlayRows, scrollNotice, scrollWindow, stackPanels, CLOSABLE_PANELS, } from "./layout.js";
+import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
+import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
+/**
+ * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
+ * only one that owns the whole screen rather than a single managed line.
+ *
+ * It is built from the pieces that already existed, not alongside them:
+ * `components/frame.ts` paints and erases the transient region (and reflows it
+ * on resize), `render/layout.ts` does every ANSI-aware width measurement,
+ * `render/state.ts` composes the live-state line, `render/highlight.ts` styles
+ * fenced code, `render/motion.ts` supplies the one frame clock. This class adds
+ * geometry (via `tui/layout.ts`) and a scrollback buffer — nothing else.
+ *
+ * Two deliberate differences from `TtyRenderer`:
+ *
+ * 1. **Committed content is buffered, not written through.** A full-screen
+ *    layout cannot let text land wherever the cursor happens to be, so `write`
+ *    /`note`/`preview` append to a logical-line buffer that the main column
+ *    renders as a tail view. The buffer holds UNWRAPPED lines and wraps at paint
+ *    time, so a resize rewraps history instead of leaving it ragged.
+ * 2. **Paints are coalesced.** A repaint is the whole screen, so doing one per
+ *    streamed delta would be by far the most expensive thing in the loop.
+ *    Paints are marked dirty and flushed at most every {@link PAINT_INTERVAL_MS},
+ *    which keeps streaming smooth without a redraw per token.
+ */
+/** Coalescing window for repaints (~30fps). */
+export const PAINT_INTERVAL_MS = 33;
+/**
+ * How often a selected view that reports itself {@link ViewSource.live} gets
+ * repainted with no other event to prompt it (P7 track 5).
+ *
+ * 2fps, not 30: this exists so a background job's log tail advances while the
+ * foreground sits idle at the prompt, and a log line arriving half a second
+ * late is imperceptible where a full-screen redraw thirty times a second for
+ * the duration of a long job is not free. The pulse only runs while such a view
+ * is the one on screen.
+ */
+export const VIEW_PULSE_MS = 500;
+/** Logical lines of scrollback kept in memory. Older lines roll off. */
+export const SCROLLBACK_LINES = 1_000;
+/** Lines a Page Up/Down keeps in common across the jump, so context survives. */
+export const SCROLL_PAGE_OVERLAP = 2;
+export class TuiRenderer {
+    caps;
+    theme;
+    out;
+    frame;
+    /** Committed conversation content, UNWRAPPED — wrapped fresh at each paint. */
+    buffer = [];
+    /** The streamed line still being assembled (no newline seen yet). */
+    partial = "";
+    print;
+    highlighter;
+    wroteInSegment = false;
+    rawStatus = null;
+    phase = null;
+    progressState = null;
+    /** The executing plan (P3), drawn as a live checklist pinned under `main`. */
+    planSteps = null;
+    phaseStartedAt = 0;
+    toolStart = null;
+    displaced = null;
+    /** The input line the app owns; painted, never edited, here. */
+    inputLine = "";
+    /** Modal rows drawn over the body (P5 track 1); null → no overlay is up. */
+    overlay = null;
+    /** Panels the user has open. `main` is a column, not a panel, and always paints. */
+    open = new Set(CLOSABLE_PANELS);
+    /**
+     * Display lines the main column is scrolled back from the live tail (P7
+     * track 1). `0` is the home position and the default, and at `0` this
+     * renderer composes exactly what it composed before scrolling existed.
+     */
+    scrollOffset = 0;
+    /** Registered main-pane views (P7 track 2); conversation is not among them. */
+    views = [];
+    /** Which view owns the main column. Always a real id — see {@link setView}. */
+    selectedView = CONVERSATION_VIEW;
+    /** Whether the sidebar nav holds the keyboard rather than the input line. */
+    sidebarFocused = false;
+    /** Working-tree state for the git panel (P4 track 2); absent → panel unwired. */
+    git;
+    /** Context-budget reading for the context panel (P4 track 3); absent → unwired. */
+    context;
+    /**
+     * The configured model/tier as known at construction — the renderer is built
+     * before the session exists, so this covers the window before {@link attachModel}
+     * and every caller that never attaches one.
+     */
+    initialModel;
+    /** The session's live model choice (P6 track 1); absent → `initialModel` stands. */
+    model;
+    unsubscribeModel = null;
+    /** What the gateway last said served a request (P4 track 4). */
+    served;
+    /** Host tool versions for the tools panel (P4 track 5); absent → unwired. */
+    tools;
+    /** Rail panels the last paint had no vertical room for (honest reporting). */
+    railDropped = [];
+    clock;
+    unsubscribeFrame = null;
+    unsubscribeResize = null;
+    paintTimer = null;
+    /** The self-changing-view pulse (P7 track 5); null when nothing needs one. */
+    viewPulseTimer = null;
+    lastPaintAt = 0;
+    dirty = false;
+    closed = false;
+    /** Header context (model / cwd), supplied by the app at construction. */
+    headerRight = "";
+    /** Provider name for the composed header (P4 track 4). */
+    provider = "";
+    /**
+     * Saved sessions shown in the sidebar (P2), and which one is running.
+     *
+     * Populated only by {@link setSessions}, never at construction. The running
+     * session has to be listed, and its meta line does not exist until the
+     * session log is open — which happens after the renderer is built. A
+     * constructor argument could therefore only ever carry the list from BEFORE
+     * this run, i.e. a sidebar missing the very session the user is in.
+     */
+    sessions = [];
+    activeSessionId;
+    constructor(caps, out, opts = {}) {
+        this.caps = caps;
+        this.out = out;
+        this.theme = resolveTheme(caps);
+        this.highlighter = createStreamHighlighter(this.theme);
+        this.print = this.newPrinter();
+        this.headerRight = opts.headerRight ?? "";
+        this.git = opts.git;
+        this.provider = opts.provider ?? "";
+        this.initialModel = opts.model;
+        this.tools = opts.tools;
+        this.buffer = mainWelcome(this.theme, "/help for commands · /exit to quit");
+        this.frame = createFrame((text) => this.out.write(text), caps);
+        // The single shared clock (U.10): an inert clock under reduced motion, so
+        // the spinner is drawn once statically and no timer is ever scheduled.
+        this.clock = createFrameClock(caps.spinner);
+        // Reflow on resize. The frame reflows its own rows, but the TUI must also
+        // RECOMPUTE geometry (column budget, body height, rewrapped history), so it
+        // repaints from the view model rather than relying on the frame's reflow.
+        this.unsubscribeResize = caps.onResize?.(() => this.paintNow()) ?? null;
+    }
+    // ── panels ────────────────────────────────────────────────────────────────
+    /** Panels currently open (a copy — the set is the renderer's own state). */
+    panels() {
+        return new Set(this.open);
+    }
+    /** Show or hide a closable panel. Returns whether it changed. */
+    setPanelOpen(id, open) {
+        const had = this.open.has(id);
+        if (had === open)
+            return false;
+        if (open)
+            this.open.add(id);
+        else
+            this.open.delete(id);
+        this.schedulePaint();
+        return true;
+    }
+    /** Columns open but not currently paintable at this WIDTH (honest reporting). */
+    droppedColumns() {
+        return droppedForWidth(budgetColumns(this.viewportWidth(), this.open), this.open);
+    }
+    /**
+     * Rail panels the current HEIGHT cannot show — the vertical counterpart to
+     * {@link droppedColumns}. Read from the last composed view model rather than
+     * recomputed, so it can never disagree with what was actually painted.
+     */
+    droppedRailPanels() {
+        // Compose against current geometry so a caller asking BEFORE the next paint
+        // (the `/open` acknowledgement does) gets the answer for the screen it is
+        // about to see, not the previous one.
+        this.viewModel(this.viewportWidth(), this.caps.height);
+        return this.railDropped;
+    }
+    /**
+     * Attach the context gauge (P4 track 3). Set after construction because the
+     * gauge reads the SESSION's history, and the session is built after the
+     * renderer — the renderer is one of its constructor arguments.
+     */
+    attachContext(gauge) {
+        this.context = gauge;
+        gauge.sample();
+        this.schedulePaint();
+    }
+    /**
+     * Adopt the session's live model choice (P6 track 1). Set after construction
+     * for the same reason the context gauge is: the choice belongs to the session,
+     * and the session is built with this renderer as one of its arguments.
+     *
+     * THE SUBSCRIPTION IS THE POINT, not the read. A change has to drop
+     * {@link served} as well, and that is not housekeeping — it is the invariant
+     * #184 was about. `served` is what the gateway said it ran LAST time; the
+     * moment the choice moves, that tier describes a request made under a setting
+     * that no longer applies. Left standing it would put `mira` in the panel and
+     * on the status line while the header, the panel's own configured value, and
+     * every subsequent request all say `kavi`. Clearing it makes the panel say
+     * "not resolved yet", which is the true statement: nothing has been served
+     * under the new choice, and the next turn will say what was.
+     */
+    attachModel(model) {
+        this.unsubscribeModel?.();
+        this.model = model;
+        this.unsubscribeModel = model.onChange(() => {
+            if (this.closed)
+                return;
+            this.served = undefined;
+            this.schedulePaint();
+        });
+        this.schedulePaint();
+    }
+    /** The configured model/tier, live when a session choice is attached. */
+    configuredModel() {
+        return this.model?.current() ?? this.initialModel;
+    }
+    /**
+     * Begin the tool probes, at the first paint that actually SHOWS the panel
+     * (P4 track 5) — never at startup, and never at all if the user keeps
+     * `tools` closed. `start` is memoized, so calling it on every frame spawns
+     * nothing after the first; the repaint callback is what lets each row appear
+     * as its own probe lands rather than all at once at the end.
+     */
+    startTools(tools) {
+        tools.start(() => {
+            if (!this.closed)
+                this.schedulePaint();
+        });
+        return tools;
+    }
+    // ── views (P7 track 2) ────────────────────────────────────────────────────
+    /**
+     * Register the main-pane views. Set after construction for the same reason
+     * the context gauge is: a view reads session-scoped state, and the session is
+     * built with this renderer as one of its arguments.
+     *
+     * Re-attaching replaces the set. If the selected view is not in the new set
+     * the selection falls back to the conversation rather than pointing at
+     * nothing — an unresolvable id would paint an empty main column with no way
+     * for the user to tell a missing view from a broken one.
+     */
+    attachViews(sources) {
+        if (this.closed)
+            return;
+        this.views = [...sources];
+        if (this.selectedView !== CONVERSATION_VIEW &&
+            !this.views.some((v) => v.id === this.selectedView)) {
+            this.selectedView = CONVERSATION_VIEW;
+        }
+        this.schedulePaint();
+    }
+    /** The registered views, conversation excluded (it is built in). */
+    viewSources() {
+        return this.views;
+    }
+    /** Which view owns the main column. */
+    view() {
+        return this.selectedView;
+    }
+    /**
+     * The tier the gateway last said actually served a request, or undefined
+     * before the first answer (P4 track 4).
+     *
+     * Published so the Overview view can report the same tier the model panel and
+     * the status line do. `SessionStatus.servedTier` has existed and been rendered
+     * since P6 track 4 with nothing ever supplying it — this renderer was the only
+     * object that knew the value, and it had no way to hand it over.
+     */
+    servedTier() {
+        return this.served?.tier;
+    }
+    /**
+     * Select a view. Returns false for an unknown id — the caller reports it,
+     * rather than this silently selecting something the user did not ask for.
+     *
+     * THE SCROLL POSITION RESETS. Offsets are display-line counts into whatever
+     * content is in the pane, and two views share no coordinate system: carrying
+     * one across would land at an arbitrary place in the other. One offset that
+     * always means "into what you are looking at" is simpler to reason about than
+     * per-view bookkeeping, and cheaper to be right about.
+     */
+    setView(id) {
+        if (this.closed)
+            return false;
+        if (id !== CONVERSATION_VIEW && !this.views.some((v) => v.id === id)) {
+            return false;
+        }
+        if (this.selectedView === id)
+            return true;
+        this.selectedView = id;
+        this.scrollOffset = 0;
+        this.schedulePaint();
+        return true;
+    }
+    /** Move `steps` around the view ring and select what lands. */
+    cycleView(steps) {
+        const next = cycleView(this.selectedView, this.views, steps);
+        this.setView(next);
+        return next;
+    }
+    /**
+     * Give the sidebar nav the keyboard, or take it back. Returns false when
+     * focus could not move, which is how the caller learns to say why.
+     *
+     * Refused while the sidebar is not on screen — closed by the user, or dropped
+     * by the width budget. Focus you cannot see is the worst kind: the arrow keys
+     * would quietly change meaning with nothing on screen accounting for it.
+     */
+    focusSidebar(focused) {
+        if (this.closed)
+            return false;
+        if (focused && !this.sidebarVisible())
+            return false;
+        if (this.sidebarFocused === focused)
+            return false;
+        this.sidebarFocused = focused;
+        this.schedulePaint();
+        return true;
+    }
+    /** Whether the sidebar nav currently holds the keyboard. */
+    sidebarHasFocus() {
+        return this.sidebarFocused;
+    }
+    /** Open AND wide enough to paint — the same test `/open` reports against. */
+    sidebarVisible() {
+        if (!this.open.has("sidebar"))
+            return false;
+        return budgetColumns(this.viewportWidth(), this.open).sidebar > 0;
+    }
+    // ── scrollback (P7 track 1) ───────────────────────────────────────────────
+    /**
+     * Scroll the main column by `delta` display lines — positive is BACK, into
+     * history; negative is forward, toward the live tail. Returns whether the
+     * position actually moved, so a caller can leave a key unhandled (and let
+     * something else claim it) rather than swallowing a no-op.
+     *
+     * Only the lower bound is applied here. The upper one needs the wrapped line
+     * count at the current width, which is composed per paint — so `viewModel`
+     * clamps and writes the real value back. Pressing Page Up at the top of a
+     * short buffer therefore reports movement once and then stops, instead of
+     * silently banking offset that Page Down would have to unwind.
+     */
+    scrollBy(delta) {
+        if (this.closed)
+            return false;
+        const next = Math.max(0, this.scrollOffset + delta);
+        if (next === this.scrollOffset)
+            return false;
+        this.scrollOffset = next;
+        this.schedulePaint();
+        return true;
+    }
+    /**
+     * Scroll by one screenful, keeping {@link SCROLL_PAGE_OVERLAP} lines of
+     * context across the jump. A page that turns cleanly loses the sentence
+     * straddling the boundary, and in a conversation that is usually the one
+     * being read.
+     */
+    scrollPage(direction) {
+        const page = Math.max(1, bodyRows(this.caps.height) - SCROLL_PAGE_OVERLAP);
+        return this.scrollBy(direction * page);
+    }
+    /** Return to the live tail. Returns false when already there. */
+    scrollToLive() {
+        if (this.closed || this.scrollOffset === 0)
+            return false;
+        this.scrollOffset = 0;
+        this.schedulePaint();
+        return true;
+    }
+    /** Whether the main column is showing history rather than the live tail. */
+    isScrolledBack() {
+        return this.scrollOffset > 0;
+    }
+    // ── app-owned surfaces ────────────────────────────────────────────────────
+    /**
+     * Replace the sidebar's session list (P2). Called once the session log is
+     * open, so the running session is itself listed; a live refresh later (P3)
+     * is the same call.
+     */
+    setSessions(sessions, activeSessionId) {
+        if (this.closed)
+            return;
+        this.sessions = sessions;
+        this.activeSessionId = activeSessionId;
+        this.schedulePaint();
+    }
+    /** Set the input line's rendered text (prompt + buffer + caret). */
+    setInput(line) {
+        if (this.closed)
+            return;
+        this.inputLine = line;
+        this.schedulePaint();
+    }
+    // ── overlay (P5 track 1) ──────────────────────────────────────────────────
+    /**
+     * Paint modal rows inside the viewport, or clear them with `null`.
+     *
+     * This is the seam every keyed, framed interaction sits on — the approval
+     * prompt, the command palette, any future picker. It exists because the two
+     * alternatives are both broken: a component that opens its own
+     * `components/frame.ts` writes ANSI cursor control to stderr into rows THIS
+     * renderer owns and repaints over, and the pre-P5 answer to that — clearing
+     * the entire shell for the duration — meant the user answered a question with
+     * the conversation it was about wiped off the screen.
+     *
+     * Rows come out of the body (see `layout.ts`), never out of the column width
+     * budget, so the conversation stays visible behind the drawer and what
+     * `/open` reports as dropped-for-width does not change while a modal is up.
+     */
+    setOverlay(lines) {
+        if (this.closed)
+            return;
+        // Reference equality is not enough — callers repaint from a fresh array
+        // every keystroke — but an unchanged overlay must not schedule a paint, or
+        // a picker's no-op key (an arrow at the end of the list) costs a frame.
+        if (sameLines(this.overlay, lines))
+            return;
+        this.overlay = lines;
+        this.schedulePaint();
+    }
+    /**
+     * How many rows an overlay may use at the current height — published so a
+     * caller composes within the drawer rather than discovering `fitOverlay`'s
+     * safety net. Falls to 0 on a terminal with no room at all, which callers
+     * must read as "do not open a modal here".
+     */
+    overlayRows() {
+        return overlayRows(this.caps.height);
+    }
+    /**
+     * Usable width for an overlay row — the full viewport, since a drawer spans
+     * the grid rather than sitting in a column. The frame reserves its trailing
+     * column here exactly as it does for every other row.
+     */
+    overlayWidth() {
+        return this.viewportWidth();
+    }
+    /** Append an app-authored line to the conversation (help text, command replies). */
+    println(line = "") {
+        if (this.closed)
+            return;
+        this.pushLines([line]);
+        this.schedulePaint();
+    }
+    // ── StreamRenderer ────────────────────────────────────────────────────────
+    beginTurn() {
+        this.highlighter = createStreamHighlighter(this.theme);
+        this.print = this.newPrinter();
+        this.wroteInSegment = false;
+    }
+    write(delta) {
+        if (this.closed)
+            return;
+        this.print(delta);
+    }
+    endSegment() {
+        if (this.closed)
+            return;
+        this.commit(this.highlighter.flush());
+        if (this.wroteInSegment) {
+            this.flushPartial();
+            this.wroteInSegment = false;
+            this.schedulePaint();
+        }
+    }
+    note(text) {
+        if (this.closed)
+            return;
+        this.flushPartial();
+        this.pushLines([this.theme.muted(text)]);
+        this.schedulePaint();
+    }
+    preview(preview) {
+        if (this.closed)
+            return;
+        // Rendered at the MAIN column's width, not the terminal's — a preview that
+        // assumed full width would be re-wrapped into a ragged block by the column.
+        // The line cap is the column's HEIGHT for the same reason (P3): a block
+        // collapsing at a fixed 40 either overflows a short pane or hides rows a
+        // tall one could have shown. One screenful is the honest budget — the
+        // scrollback keeps what the collapse marker accounts for.
+        const block = renderActionPreview(preview, this.theme, this.mainWidth(), bodyRows(this.caps.height));
+        if (!block)
+            return;
+        this.flushPartial();
+        this.pushLines(block.split("\n"));
+        this.schedulePaint();
+    }
+    status(text) {
+        if (this.closed)
+            return;
+        this.rawStatus = text;
+        this.schedulePaint();
+    }
+    setPhase(phase) {
+        if (this.closed)
+            return;
+        if (phase?.kind === "awaiting-approval") {
+            if (this.phase?.kind !== "awaiting-approval") {
+                this.displaced = { phase: this.phase, startedAt: this.phaseStartedAt };
+            }
+        }
+        else {
+            this.displaced = null;
+        }
+        const before = phaseIdentity(this.phase);
+        this.phase = phase;
+        if (phaseIdentity(phase) !== before)
+            this.phaseStartedAt = Date.now();
+        this.syncClock();
+        this.schedulePaint();
+    }
+    progress(state) {
+        if (this.closed)
+            return;
+        this.progressState = state;
+        this.schedulePaint();
+    }
+    /**
+     * Set (or clear) the live plan checklist (P3). Unlike every other committed
+     * surface here this does NOT append to the scrollback buffer: the list is
+     * re-sent in full on every status change, so buffering it would stack one
+     * near-identical copy of the plan per step. It is live state, composed fresh
+     * at each paint by {@link viewModel} — which is also what makes a resize
+     * rewindow it for free.
+     */
+    setPlan(steps) {
+        if (this.closed)
+            return;
+        // Clearing commits ONE final copy to the scrollback. Without this the
+        // checklist would simply vanish when the run ends and the TUI would keep no
+        // record of it at all — the append-only renderers get theirs from having
+        // committed each transition as it happened, which is exactly what this
+        // renderer does not do.
+        if (steps === null) {
+            if (this.planSteps !== null && this.planSteps.length > 0) {
+                this.flushPartial();
+                this.pushLines(planChecklist(this.planSteps, this.theme));
+            }
+            this.planSteps = null;
+            this.schedulePaint();
+            return;
+        }
+        this.planSteps = steps.map((s) => ({ ...s }));
+        this.schedulePaint();
+    }
+    /**
+     * Committed to the scrollback at the MAIN column's width — a block sized for
+     * the whole terminal would be re-wrapped into a ragged one by the column,
+     * same reasoning as `preview`.
+     */
+    testResult(report) {
+        if (this.closed)
+            return;
+        this.flushPartial();
+        this.pushLines(testResultLines(report, this.theme, this.mainWidth()));
+        this.schedulePaint();
+    }
+    toolLifecycle(event) {
+        if (this.closed)
+            return;
+        if (event.event === "start") {
+            this.toolStart = { label: event.label, at: Date.now() };
+            this.setPhase({ kind: "calling-tool", label: event.label });
+            return;
+        }
+        const started = this.toolStart?.label === event.label ? this.toolStart : null;
+        this.toolStart = null;
+        if (this.phase?.kind === "calling-tool") {
+            this.phase = null;
+            this.syncClock();
+        }
+        // Measured start→end, never animated — honest under reduced motion too.
+        const elapsed = started === null ? 0 : Date.now() - started.at;
+        const suffix = elapsed >= ELAPSED_AFTER_MS ? ` (${formatElapsed(elapsed)})` : "";
+        const mark = event.ok ? this.theme.glyph.success : this.theme.glyph.failure;
+        this.note(`${mark} ${event.label}${suffix}`);
+        // A finished tool may have written files. Invalidate on EVERY tool rather
+        // than guessing which ones mutate: the cache coalesces, so over-calling is
+        // free, while under-calling leaves the panel quietly wrong.
+        this.refreshGit();
+        // The history just grew by a tool_use/tool_result pair, so the context
+        // reading is stale. Cheap here; ruinous on the paint path — see the gauge.
+        this.context?.sample();
+    }
+    /**
+     * Adopt the tier the gateway says actually served the request (P4 track 4).
+     *
+     * Repainted rather than committed: this is standing state, not an event. It
+     * is re-sent on every request, so the panel and header always describe the
+     * MOST RECENT one — which is what matters when a budget downgrade changes the
+     * tier mid-session and the earlier value would otherwise stick.
+     */
+    servedRouting(routing) {
+        if (this.closed)
+            return;
+        const unchanged = this.served?.tier === routing.tier && this.served?.mode === routing.mode;
+        if (unchanged)
+            return;
+        this.served = routing;
+        this.schedulePaint();
+    }
+    promptResolved() {
+        if (this.closed)
+            return;
+        if (this.phase?.kind !== "awaiting-approval")
+            return;
+        const displaced = this.displaced;
+        this.displaced = null;
+        this.phase = displaced?.phase ?? null;
+        this.phaseStartedAt = displaced?.startedAt ?? Date.now();
+        this.syncClock();
+        this.schedulePaint();
+    }
+    endTurn() {
+        if (this.closed)
+            return;
+        this.commit(this.highlighter.flush());
+        this.flushPartial();
+        this.phase = null;
+        this.rawStatus = null;
+        this.displaced = null;
+        this.syncClock();
+        // Sampled BEFORE the paint, so the turn's final frame already shows the
+        // history it just finished adding to rather than the previous turn's.
+        this.context?.sample();
+        this.paintNow();
+        this.refreshGit();
+        this.refreshViews();
+    }
+    /**
+     * Re-probe the working tree, off the paint path, and repaint when it lands.
+     *
+     * Deliberately not awaited: a turn must never wait on `git status`, and a
+     * probe that fails or times out has to leave the UI exactly as it was. The
+     * cache coalesces concurrent calls, so the ten invalidations a file-writing
+     * turn produces cost one probe.
+     */
+    refreshGit() {
+        const git = this.git;
+        if (git === undefined || this.closed)
+            return;
+        git.invalidate();
+        void git.refresh().then(() => {
+            if (this.closed)
+                return;
+            this.schedulePaint();
+        });
+    }
+    /**
+     * Let each view re-probe what it reads (P7 track 3), on the same post-turn
+     * trigger and under the same rules as the rail's git cache: not awaited, and
+     * a failure leaves the pane as it was.
+     *
+     * EVERY view refreshes, not just the selected one. A probe exists so that
+     * SELECTING a view shows something true immediately; refreshing only the
+     * visible one would mean every switch lands on a stale pane and then flickers
+     * — which is the "checking…" state the tri-state was added to be honest
+     * about, shown at the one moment it is avoidable.
+     */
+    refreshViews() {
+        if (this.closed)
+            return;
+        for (const source of this.views) {
+            const refresh = source.refresh;
+            if (refresh === undefined)
+                continue;
+            void Promise.resolve(refresh.call(source))
+                .then(() => {
+                if (!this.closed)
+                    this.schedulePaint();
+            })
+                // A view that cannot re-probe keeps its last value; it must never take
+                // the shell down with an unhandled rejection.
+                .catch(() => { });
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.stopFrames();
+        if (this.paintTimer !== null) {
+            clearTimeout(this.paintTimer);
+            this.paintTimer = null;
+        }
+        if (this.viewPulseTimer !== null) {
+            clearTimeout(this.viewPulseTimer);
+            this.viewPulseTimer = null;
+        }
+        this.unsubscribeResize?.();
+        this.unsubscribeResize = null;
+        this.unsubscribeModel?.();
+        this.unsubscribeModel = null;
+        // Erase the whole shell: after the TUI exits the terminal holds zero
+        // leftover bytes from it, exactly like a resolved component frame.
+        this.frame.clear();
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    newPrinter() {
+        return createStreamPrinter((text) => {
+            this.commit(this.highlighter.push(text));
+        });
+    }
+    /** Fold streamed text into the buffer, splitting on newlines. */
+    commit(text) {
+        if (text === "")
+            return;
+        this.rawStatus = null;
+        this.wroteInSegment = true;
+        const parts = (this.partial + text).split("\n");
+        this.partial = parts.pop() ?? "";
+        if (parts.length > 0)
+            this.pushLines(parts);
+        this.schedulePaint();
+    }
+    /** Commit the in-flight partial line, if any. */
+    flushPartial() {
+        if (this.partial === "")
+            return;
+        this.pushLines([this.partial]);
+        this.partial = "";
+    }
+    pushLines(lines) {
+        // Hold the scrolled view still (P7 track 1). The offset is measured from
+        // the END of the document, so appending would otherwise slide the content
+        // up under the reader by exactly the number of lines that arrived — the
+        // failure this compensation exists to prevent, and the reason scrollback is
+        // worth having DURING a stream rather than only after one.
+        //
+        // Counted in DISPLAY lines, at the width the window is composed at, because
+        // that is the unit the offset is in. Skipped entirely at the live tail,
+        // where following the newest output is the whole point.
+        // Only while the conversation is the thing being scrolled. A view's offset
+        // indexes ITS lines, so nudging it because the conversation grew behind the
+        // pane would scroll a document that did not change.
+        if (this.scrollOffset > 0 && this.selectedView === CONVERSATION_VIEW) {
+            const cols = this.mainWidth();
+            let added = 0;
+            for (const line of lines) {
+                added += line === "" ? 1 : reflow(line, cols).length;
+            }
+            this.scrollOffset += added;
+        }
+        this.buffer.push(...lines);
+        if (this.buffer.length > SCROLLBACK_LINES) {
+            this.buffer = this.buffer.slice(this.buffer.length - SCROLLBACK_LINES);
+        }
+    }
+    /** Inner width the frame accepts without truncating (it reserves one column). */
+    viewportWidth() {
+        return Math.max(1, this.caps.width - 1);
+    }
+    mainWidth() {
+        return budgetColumns(this.viewportWidth(), this.open).main;
+    }
+    /**
+     * Subscribe to the frame clock only while something is actually animating —
+     * a live phase. Idle (or reduced motion) leaves no timer running at all.
+     */
+    syncClock() {
+        const wants = this.clock.enabled &&
+            this.phase !== null &&
+            this.phase.kind !== "awaiting-approval";
+        if (wants && this.unsubscribeFrame === null) {
+            this.unsubscribeFrame = this.clock.subscribe(() => this.paintNow());
+        }
+        else if (!wants) {
+            this.stopFrames();
+        }
+    }
+    stopFrames() {
+        if (this.unsubscribeFrame !== null) {
+            this.unsubscribeFrame();
+            this.unsubscribeFrame = null;
+        }
+    }
+    /**
+     * Mark the screen dirty and paint on the next coalescing tick. Streaming a
+     * turn can call this hundreds of times a second; at most one paint per
+     * {@link PAINT_INTERVAL_MS} results.
+     */
+    schedulePaint() {
+        if (this.closed)
+            return;
+        this.dirty = true;
+        if (this.paintTimer !== null)
+            return;
+        const since = Date.now() - this.lastPaintAt;
+        if (since >= PAINT_INTERVAL_MS) {
+            this.paintNow();
+            return;
+        }
+        this.paintTimer = setTimeout(() => {
+            this.paintTimer = null;
+            if (this.dirty)
+                this.paintNow();
+        }, PAINT_INTERVAL_MS - since);
+        // Never hold the process open for a pending repaint.
+        this.paintTimer.unref?.();
+    }
+    /** Compose and paint immediately. */
+    paintNow() {
+        if (this.closed)
+            return;
+        this.dirty = false;
+        this.lastPaintAt = Date.now();
+        // An approval prompt used to yield the ENTIRE shell here, the way
+        // `TtyRenderer` hides its one live line. That was never what this renderer
+        // wanted — it was the only defence available while the prompt wrote to
+        // stderr, whose bytes would land inside the frame's rows and be erased by
+        // the next repaint. The cost was that you approved a change with the
+        // conversation it was about wiped off the screen.
+        //
+        // P5 track 2 moves the prompt onto the overlay seam, so it is composed INTO
+        // this paint rather than written around it, and the shell keeps painting
+        // underneath. `awaiting-approval` still displaces the phase (see
+        // `setPhase`/`promptResolved`) and still stops the clock — a spinner has
+        // nothing to say while the turn is blocked on a human — but it no longer
+        // blanks anything.
+        const width = this.viewportWidth();
+        const height = this.caps.height;
+        this.frame.render(composeScreen(this.viewModel(width, height), width, height, this.open, this.theme));
+        this.armViewPulse();
+    }
+    /**
+     * Keep repainting a selected view that says its content is moving on its own
+     * (P7 track 5) — a background job appending to its log while the foreground
+     * waits at the prompt.
+     *
+     * Armed from `paintNow` rather than from an event, because the condition it
+     * watches has no event: the pulse paints, that paint re-arms, and the chain
+     * ends by itself the moment the view stops being selected or stops being live.
+     * Nothing else in this class needs to know the pulse exists.
+     */
+    armViewPulse() {
+        if (this.viewPulseTimer !== null || this.closed)
+            return;
+        const active = this.views.find((v) => v.id === this.selectedView);
+        // `live` is optional and false by default: every view whose content only
+        // moves when a turn, a key or a `refresh` moved it already repaints.
+        if (active?.live?.() !== true)
+            return;
+        this.viewPulseTimer = setTimeout(() => {
+            this.viewPulseTimer = null;
+            if (!this.closed)
+                this.schedulePaint();
+        }, VIEW_PULSE_MS);
+        // Never hold the process open for a pulse — the same rule as `paintTimer`.
+        // A pending repaint must not be why `cruxy` fails to exit.
+        this.viewPulseTimer.unref?.();
+    }
+    /** The live-state line, composed by the shared U.4 mapping. */
+    /**
+     * True when the model panel is actually on screen — open AND its column
+     * survived the width budget. `droppedForWidth` is the same check `/open` uses
+     * to tell a user their panel will not fit, so "visible" means one thing in
+     * this file.
+     */
+    modelPanelVisible(width) {
+        if (this.configuredModel() === undefined || !this.open.has("model")) {
+            return false;
+        }
+        return !droppedForWidth(budgetColumns(width, this.open), this.open).includes("rail");
+    }
+    /**
+     * The phase as the STATUS LINE should say it — which is not always the phase
+     * the loop published.
+     *
+     * Since P4 track 4 there are two places a tier can appear at once, and they
+     * are sourced differently. `phase.tier` is `routed?.tier`: what this run's
+     * client-side router (C.30) ASKED for, fixed before `provider.stream` opens.
+     * The model panel shows what the gateway said actually SERVED the request.
+     * Those disagree exactly when it matters — `auto` resolving to a real tier,
+     * or a budget downgrade to one nobody selected — so a single screen could
+     * assert `kavi` on the status line and `mira` in the rail, with nothing to
+     * say which was true.
+     *
+     * Two tiers contradicting each other in one viewport is worse than either
+     * being absent, so:
+     *
+     *  - MODEL PANEL VISIBLE → the status line drops the tier entirely. The panel
+     *    is the better surface for it: it is persistent, it has room to say HOW
+     *    the tier was chosen, and it is never truncated away. One surface owns
+     *    the claim.
+     *  - MODEL PANEL NOT VISIBLE (closed, or its column dropped for width) → the
+     *    status line keeps the tier, because otherwise nothing would show it —
+     *    but it prefers the SERVED tier over the asked-for one, so what it shows
+     *    is the same fact the panel would have shown.
+     *
+     * This only removes text from the line, so `fitStatusLine`'s degradation
+     * order (phase > progress prefix > elapsed) is untouched: the tier was baked
+     * into the phase text, i.e. into the element that survives longest, which is
+     * the last place a redundant or contradictory value belongs.
+     */
+    statusPhase(width) {
+        const phase = this.phase;
+        if (phase === null || phase.kind !== "thinking")
+            return phase;
+        if (this.modelPanelVisible(width)) {
+            // Rebuilt rather than destructured, so the fields kept are stated rather
+            // than implied: only the tier goes, the token counts stay.
+            return phase.tokens === undefined
+                ? { kind: "thinking" }
+                : { kind: "thinking", tokens: phase.tokens };
+        }
+        const tier = this.served?.tier ?? phase.tier;
+        return tier === undefined ? phase : { ...phase, tier };
+    }
+    statusLine(width) {
+        if (this.rawStatus !== null)
+            return this.rawStatus;
+        if (this.phase === null && this.progressState === null)
+            return "";
+        const elapsed = this.phase !== null && this.caps.spinner
+            ? Date.now() - this.phaseStartedAt
+            : undefined;
+        const glyph = spinnerGlyph(this.clock.frame, this.theme.glyph, this.caps.spinner && this.phase !== null);
+        const room = Math.max(1, width - 2);
+        const line = fitStatusLine(this.progressState, this.statusPhase(width), elapsed, this.theme.glyph, room);
+        return line === "" ? "" : `${glyph} ${line}`;
+    }
+    viewModel(width, height) {
+        // An overlay borrows rows from the columns (P5 track 1). Resolved BEFORE
+        // anything is composed, because every block below is fitted to the row
+        // budget — the rail especially, which `stackPanels` packs to an exact
+        // height and which `fitBlock`'s tail rule would otherwise decapitate.
+        const drawer = fitOverlay(this.overlay ?? [], overlayRows(height));
+        const rows = Math.max(1, bodyRows(height) - drawer.length);
+        const columns = budgetColumns(width, this.open);
+        const mainCols = columns.main;
+        // Focus cannot outlive the thing holding it (P7 track 2). `/close sidebar`
+        // and a narrowing terminal both take the nav off screen, and either would
+        // otherwise leave the arrow keys silently rebound to a column that is not
+        // there. Dropped here rather than in the two call sites because this is
+        // where "on screen" is actually decided.
+        if (this.sidebarFocused &&
+            (!this.open.has("sidebar") || columns.sidebar === 0)) {
+            this.sidebarFocused = false;
+        }
+        const scrolled = this.scrollOffset > 0;
+        // A registered view owns the main column outright (P7 track 2). Its lines
+        // are recomposed every paint from its own state — this class never learns
+        // what they mean — and none of the conversation machinery below applies:
+        // there is no partial line to hold back, no plan to pin, and no append to
+        // compensate for, because a view does not accumulate.
+        const active = this.selectedView === CONVERSATION_VIEW
+            ? undefined
+            : this.views.find((v) => v.id === this.selectedView);
+        // AT THE LIVE TAIL, wrap only the tail we could possibly show. Rewrapping
+        // 1,000 lines on every frame would be the one genuinely hot cost in this
+        // path, and this is the path every streaming frame takes.
+        //
+        // SCROLLED BACK, wrap the whole retained buffer instead. The offset is in
+        // display lines and it has to be clamped against the real total, which a
+        // slice cannot supply — and a conservative bound would stop short of the
+        // oldest line, making content unreachable rather than merely slow. The cost
+        // is bounded by SCROLLBACK_LINES and only paid while a human is reading
+        // history, which is not a hot path.
+        //
+        // Skipped entirely while a view owns the pane: the conversation keeps
+        // accumulating behind it, but composing what nobody is looking at would
+        // make every other view pay the conversation's cost.
+        const source = active !== undefined
+            ? []
+            : scrolled
+                ? this.buffer
+                : this.buffer.slice(Math.max(0, this.buffer.length - rows * 4));
+        // The streaming partial line belongs to the LIVE view only. While scrolled
+        // it is excluded, which is what makes the offset arithmetic exact: the
+        // document then changes only through `pushLines`, which compensates. It is
+        // also the honest reading — scrollback is committed output, and a line still
+        // being written is not committed.
+        const live = active !== undefined || scrolled || this.partial === ""
+            ? []
+            : [this.partial];
+        const wrapped = [];
+        for (const line of [...source, ...live]) {
+            if (line === "") {
+                wrapped.push("");
+                continue;
+            }
+            wrapped.push(...reflow(line, mainCols));
+        }
+        // The plan checklist is PINNED under the conversation (P3). `main` is a
+        // tail view — `fitBlock` keeps its last `rows` lines — so appending is what
+        // makes the checklist survive a long conversation while the oldest
+        // scrollback rolls off the top. No reservation arithmetic is needed; the
+        // cap below is what stops a 40-step plan from evicting the conversation
+        // entirely, and `planChecklist` windows around the running step and says
+        // how many it hid.
+        //
+        // Pinned to the LIVE tail, not to the column: while scrolled back it is
+        // absent, for the same reason the partial line is. It is re-rendered from
+        // mutable state on every paint rather than committed to the buffer, so
+        // leaving it in a scrolled view would let it change length underneath a
+        // reader and shift the history they are holding still.
+        const plan = active !== undefined ||
+            scrolled ||
+            this.planSteps === null ||
+            this.planSteps.length === 0
+            ? []
+            : planChecklist(this.planSteps, this.theme, Math.max(2, Math.floor(rows / 2)), mainCols);
+        // The rail is a STACK of fixed panels, not a feed: it is composed to the
+        // exact row budget here (dropping whole panels and counting them) rather
+        // than handed to `fitBlock`, whose tail rule would silently eat the top
+        // panel. `composeScreen` still pads it, which is now a no-op on height.
+        // A pure field read of the cache — never a probe. See `git-status.ts`.
+        // What the model panel and the header both describe. The configured value
+        // is known from the start, so neither is ever blank before the first turn.
+        const configured = this.configuredModel();
+        const model = configured === undefined
+            ? undefined
+            : {
+                configured,
+                ...(this.served === undefined ? {} : { served: this.served }),
+            };
+        // Probing starts at the first paint that actually SHOWS the panel — never
+        // at startup, and never at all while the user keeps `tools` closed.
+        const toolRows = this.tools === undefined || !this.open.has("tools")
+            ? undefined
+            : this.startTools(this.tools).current();
+        // Composed fresh each paint from the panels' own typed state. There is no
+        // stored blob to merge over: every panel owns its source, so a key can only
+        // appear here by being derived below.
+        const railState = {
+            ...(model === undefined
+                ? {}
+                : { model: modelPanelLines(this.theme, model) }),
+            ...(this.context === undefined
+                ? {}
+                : { context: contextPanelLines(this.theme, this.context.current()) }),
+            ...(this.git === undefined
+                ? {}
+                : { git: gitPanelLines(this.theme, this.git.current()) }),
+            ...(toolRows === undefined
+                ? {}
+                : { tools: toolsPanelLines(this.theme, toolRows) }),
+        };
+        const stacked = stackPanels(railBlocks(this.theme, railState, this.open), rows, this.theme);
+        this.railDropped = stacked.dropped;
+        // Window the conversation (P7 track 1). At the live tail this is the tail
+        // view `fitBlock` already produced — `scrollWindow` agrees with it
+        // line-for-line at offset 0 — so the default path is unchanged and the
+        // notice costs nothing. Scrolled back, one row goes to the notice, which is
+        // why the window is asked for `rows - 1`.
+        //
+        // The clamp is written back because only this pass knows the wrapped total;
+        // `scrollBy` bounds the keypress from below and leaves the ceiling here.
+        // The one place the two content sources meet. Everything downstream —
+        // windowing, the notice, `fitBlock` — treats them identically, which is
+        // what "a view is just lines" has to mean to be worth anything.
+        //
+        // A view's lines are reflowed here rather than trusted at `mainCols`: the
+        // contract asks a view to lay out to the width it is given, and reflow makes
+        // that a courtesy rather than a rule it can break the grid by ignoring.
+        const body = active !== undefined
+            ? active
+                .lines(this.theme, mainCols)
+                .flatMap((line) => (line === "" ? [""] : reflow(line, mainCols)))
+            : plan.length === 0
+                ? wrapped
+                : [...wrapped, "", ...plan];
+        let main = body;
+        if (scrolled) {
+            const win = scrollWindow(body, Math.max(1, rows - 1), this.scrollOffset);
+            this.scrollOffset = win.offset;
+            // The clamp can land on 0 — a resize that grew the pane past the content,
+            // or scrollback that rolled off underneath the offset. That is the live
+            // view again, and it must not keep a notice claiming lines below it.
+            main =
+                win.offset === 0
+                    ? body
+                    : [...win.lines, scrollNotice(win.hiddenBelow, this.theme)];
+        }
+        return {
+            headerLeft: "cruxy",
+            // Recomposed each paint, so a served tier that arrives (or changes under
+            // a budget downgrade) reaches the header. P1 set this once at
+            // construction, which is why a run routed to `kavi` read `auto` forever.
+            headerRight: model === undefined
+                ? this.headerRight
+                : headerModel(this.theme, this.provider, model),
+            // Nav first, then the session list P2 put here. Two blocks rather than
+            // one because they answer different questions — "where am I" and "what
+            // else have I run" — and because the sessions list is destined to become
+            // a view of its own, at which point this reduces to the nav.
+            sidebar: [
+                ...navLines(this.theme, this.views, this.selectedView, this.sidebarFocused),
+                "",
+                ...sidebarLines(this.theme, this.sessions, this.activeSessionId),
+            ],
+            main,
+            rail: stacked.lines,
+            status: this.statusLine(width),
+            input: this.inputLine,
+            overlay: drawer,
+        };
+    }
+}
+/** Row-wise equality for overlay content — `null` and `[]` both mean "no drawer". */
+function sameLines(a, b) {
+    if (a === b)
+        return true;
+    const left = a ?? [];
+    const right = b ?? [];
+    return (left.length === right.length && left.every((line, i) => line === right[i]));
+}