@vincemakes/kiso-tui 0.7.0 → 0.9.0

package/dist/compositor.js

@@ -45,10 +45,13 @@
 import { truncateDiff } from "./diff.js";
 import { displayWidth } from "./editor.js";
 import { leadWidth } from "./width.js"; // W23: the ONE width authority (the editor, #inputRow, and editCol share it)
-import { panelAffordance, panelBlockRows, panelLead, panelStatus } from "./approval-panel.js";
-import { atPanelRows } from "./at-picker.js";
-import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, foldLine, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.js";
+// KC3.5: the panel-slot reads come from the DISPATCHERS — one source
+// for four reads, so an ask can never render half as an approval.
+import { panelAffordanceOf, panelLeadOf, panelRowsOf, panelStatusOf } from "./ask-panel.js";
+import { atPanelRows, bandHeader } from "./at-picker.js";
+import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, exploreCounts, exploreRows, foldLine, isExploreTool, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.js";
 import { bannerLines, escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, toolTarget } from "./render.js";
+import { keysSheetRows } from "./strings.js";
 /** The cursor marker — an APC private sequence the focus component
  *  embeds at the edit position; the compositor strips it and moves
  *  relatively (it never reaches the terminal). */
@@ -116,6 +119,15 @@ export class Body {
     // panel is up it replaces the live region, owns the input lead, and
     // derives the status row (the CLI's painting status yields).
     #panelState = null;
+    /** TUI2-R1 (D): the keys sheet's slot read — the editor's boolean.
+     *  Unbound, the sheet cannot render and every frame is byte-identical
+     *  to before the round. */
+    #sheetState = null;
+    /** TUI2-R1.5 7(a): the sheet's previous up/down state — a transition
+     *  in either direction takes the full-redraw path. */
+    #sheetWasUp = false;
+    /** This frame is an overlay open or close — it must not scroll. */
+    #overlayFrame = false;
     #inputState = () => ({ line: "", cursor: 0 });
     #inputPrompt = "";
     #menuState = null;
@@ -151,6 +163,7 @@ export class Body {
         if (dockBindings.at !== null)
             this.#atState = dockBindings.at;
         this.#panelState = dockBindings.panel;
+        this.#sheetState = dockBindings.sheet;
         if (dockBindings.queue !== null)
             this.#queueState = dockBindings.queue;
     }
@@ -210,6 +223,19 @@ export class Body {
             this.#write(`→ ${escapeTerminal(name)}(${escapeTerminal(JSON.stringify(input).slice(0, 200))})\n`);
             return;
         }
+        // TUI2-R1.5 ① (VD-1): the tool's start CLOSES an open text block —
+        // the inactive path above has always done this; the active path
+        // forgot, and the consequence was structural. textAppend only ever
+        // grows the LAST cell, so a text block with a tool cell after it can
+        // never receive another byte: it is finished in fact while its
+        // `done` flag says otherwise. The commit loop takes leading DONE
+        // cells, so that one stale flag parked the whole rest of the turn
+        // behind it — every tool cell then reached the screen through the
+        // FORCE-commit path, which by design bypasses the fold-hold. That is
+        // why the walkthrough saw nine individual rows: not a fold that
+        // declined to form, a fold that was never consulted.
+        this.#closeOpenThinking();
+        this.#closeOpenText();
         // W12: the cell carries the delegate's child roles from the FULL
         // input — the display summary is sliced at 60 chars (unparseable);
         // the roles are the only running-state data the parent holds (there
@@ -280,6 +306,30 @@ export class Body {
         }
         this.#mark();
     }
+    /**
+     * TUI2-R1 (C) — the RUNNING call's observed output.
+     *
+     * The CLI tails the shell tool's progress sidecar and hands what it
+     * read to the cell. Deliberately narrow: only a cell that is still
+     * RUNNING accepts it, so an observation can never overwrite a real
+     * result, and an unchanged read costs no frame at all (a poller
+     * fires far more often than the output changes).
+     *
+     * This adds no event and no durable state. The text lands in the
+     * cell's live rendering and is replaced wholesale by the tool's own
+     * result at settle — which is the only text anything else ever reads.
+     */
+    toolProgress(callId, text) {
+        if (!this.#isActive())
+            return; // the pipe path has no live region
+        const cell = this.#toolCell(callId);
+        if (cell === null || cell.kind !== "tool" || cell.state !== "running" || cell.done)
+            return;
+        if (cell.resultText === text)
+            return;
+        cell.resultText = text;
+        this.#mark();
+    }
     toolSucceeded(callId) {
         if (!this.#isActive())
             this.#write("  ok\n");
@@ -490,7 +540,7 @@ export class Body {
         this.#cells.push({ kind: "banner", version, extensionsText, resume, done: true });
         this.#mark();
     }
-    raw(lines) {
+    raw(lines, wrap) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
             this.#closeOpenText();
@@ -500,7 +550,7 @@ export class Body {
         }
         this.#closeOpenThinking();
         this.#closeOpenText();
-        this.#cells.push({ kind: "raw", lines, done: true });
+        this.#cells.push({ kind: "raw", lines, done: true, ...(wrap === undefined ? {} : { wrap }) });
         this.#mark();
     }
     /** The last COMPLETE thinking block, for /think. */
@@ -553,8 +603,16 @@ export class Body {
             // land as NEW content, history is never rewritten, ADR-0046).
             const turnsBack = this.#cells.slice(idx + 1).filter((c) => c.kind === "user").length;
             const p = palette();
+            const back = `${turnsBack} ${turnsBack === 1 ? "turn" : "turns"} back`;
+            // TUI2-R1 (B): an EXPLORATION head lists per TOOL — the counts
+            // the row showed, then one row per tool with its subjects. The
+            // header keeps W15's shape; only the subject changes.
+            if (cell.rolled.parts !== undefined) {
+                const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`explored ${exploreCounts(cell.rolled.parts)}`)} · ${back}`;
+                return { kind: "appended", lines: [header, ...exploreRows(cell.rolled.parts, this.#opts.width())] };
+            }
             const noun = ROLLUP_NOUN[cell.name] ?? "calls";
-            const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`${cell.name.replace("_file", "")} ${cell.rolled.count} ${noun}`)} · ${turnsBack} ${turnsBack === 1 ? "turn" : "turns"} back`;
+            const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`${cell.name.replace("_file", "")} ${cell.rolled.count} ${noun}`)} · ${back}`;
             return {
                 kind: "appended",
                 lines: [header, ...cell.rolled.targets.map((t) => `  ${p.dim}└ ${escapeTerminal(t)}${p.reset}`)],
@@ -657,7 +715,7 @@ export class Body {
     #statusSource() {
         const panel = this.#panelState?.() ?? null;
         if (panel !== null)
-            return { status: panelStatus(panel.view, panel.phase, panel.sel), hint: panelAffordance(panel.view, panel.phase, panel.sel) };
+            return { status: panelStatusOf(panel), hint: panelAffordanceOf(panel) };
         // W22: while turns wait in the queue, the right hint shows the
         // count — the chips below carry the lines themselves.
         const queued = this.#queueState?.().length ?? 0;
@@ -678,6 +736,11 @@ export class Body {
     }
     /** Bind the editor's slash-command menu state — the MenuSelect slot
      *  occupant (the menu replaces the editor's view while open). */
+    /** TUI2-R1 (D): bind the editor's keys-sheet flag. */
+    bindSheet(state) {
+        this.#sheetState = state;
+        this.#mark();
+    }
     bindMenu(state) {
         this.#menuState = state;
     }
@@ -704,7 +767,7 @@ export class Body {
         // + 1 — the SAME formula the marker embeds at (the panel lead when
         // the panel owns the row; the old prompt-only math desynced the
         // panel rows' edit column; leadWidth is the ONE authority)
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : this.#inputPrompt;
+        const lead = panel !== null ? panelLeadOf(panel) : this.#inputPrompt;
         return 3 + leadWidth(lead) + st.cursor;
     }
     /** The old dock's redraw — the editor's onRender target: mark + the
@@ -770,15 +833,25 @@ export class Body {
      *  screen rows), threaded against the previous sibling's OWN rows. */
     liveCount() {
         const panel = this.#panelState?.() ?? null;
+        const sheet = this.#sheetState?.() === true;
         const queueRows = this.#queueRows(this.#opts.width(), this.#opts.height());
         // KC1 §6: the composer's extra rows are chrome too — the scalar
         // counts them exactly like the menu/queue bands (N = 1 ⇒ +0)
         const inputExtra = this.#inputRows(this.#opts.width(), this.#opts.height(), this.#menuRows(this.#opts.width()).length, queueRows.length).rows.length - 1;
+        // TUI2-R1 (D): the sheet occupies the live region, exactly like the
+        // panel — the scalar must say so, or the cap arithmetic disagrees
+        // with the screen.
+        if (sheet) {
+            return (keysSheetRows(this.#opts.width()).slice(0, Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
+                CHROME_ROWS +
+                inputExtra +
+                queueRows.length);
+        }
         if (panel !== null) {
             // W21: the panel's own rows (the cap is exact — the scalar
             // reflects the screen). W22: the queue chips occupy their
             // own band — the panel's cap shrinks by their rows.
-            return (panelBlockRows(panel.view, panel.phase, panel.sel, this.#opts.width(), Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
+            return (panelRowsOf(panel, this.#opts.width(), Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
                 CHROME_ROWS +
                 inputExtra +
                 queueRows.length);
@@ -859,13 +932,32 @@ export class Body {
         const chromeRows = CHROME_ROWS + inputExtra + menuRows.length + queueRows.length;
         let liveLines = [];
         const panel = this.#panelState?.() ?? null;
-        if (panel !== null) {
+        // TUI2-R1.5 ⑦(a) (VD-8): the sheet is an OVERLAY, and the frame it
+        // opens on — and the one it closes on — take the full-redraw path.
+        // The sheet REPLACES the live region, so on an idle composer (where
+        // the live region is empty) opening it GROWS the model by its own
+        // height; the frame's skip grows with it and the difference is paid
+        // in real LFs — rows scrolled permanently into the terminal's
+        // scrollback, which closing cannot undo, because the scrollback is
+        // not ours to rewrite. Measured: three rows per open on a full
+        // screen. The overlay below displaces content on screen instead.
+        const sheetUp = this.#sheetState?.() === true;
+        this.#overlayFrame = sheetUp || this.#sheetWasUp;
+        this.#sheetWasUp = sheetUp;
+        if (sheetUp) {
+            // TUI2-R1 (D): the sheet REPLACES the live region — the same
+            // slot the panel uses, for the same reason (it is what the
+            // human is reading right now). It cannot coexist with a panel:
+            // the editor only opens it from an idle composer.
+            liveLines = keysSheetRows(W).slice(0, Math.max(1, H - 4 - inputExtra - queueRows.length));
+        }
+        else if (panel !== null) {
             // W21: the panel REPLACES the running tool's live window — the
             // bounded block, capped at H−4 (the panel IS the live region;
             // the W11 blank would separate it from the frozen content).
             // The cap is exact, so the force-commit loop never fires. W22:
             // the queue band sits below the panel — the cap shrinks by it.
-            liveLines = panelBlockRows(panel.view, panel.phase, panel.sel, W, Math.max(1, H - 4 - inputExtra - queueRows.length));
+            liveLines = panelRowsOf(panel, W, Math.max(1, H - 4 - inputExtra - queueRows.length));
         }
         else {
             let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
@@ -938,14 +1030,17 @@ export class Body {
     #commitCell(i, W, ctx) {
         const cell = this.#cells[i];
         const lines = this.#foldOrRollup(cell, i, W, ctx);
-        // W15: a tool cell whose last committed row carried the "ctrl+r"
-        // affordance (the renderer cut "└ … ctrl+r") joins the expand
-        // history — the detection is the renderer's OWN output, so the
-        // read's "/last"-only cut note never lands here.
+        // W15: a tool cell whose committed rows carried the "ctrl+r"
+        // affordance joins the expand history — the detection is the
+        // renderer's OWN output, so the read's "/last"-only cut note never
+        // lands here. TUI2-R1 (A/B): the affordance is no longer only the
+        // renderer cut's "└ … ctrl+r" — the self-naming head suffix and
+        // the exploration row carry it on the HEAD row, and a promise the
+        // key does not answer would be the one thing worse than silence.
         // unshift: the cells commit oldest-first, so the NEWEST cut lands
         // at the front — the expand pointer's "newest back" walk starts
         // where the user's last key press would aim.
-        if (cell.kind === "tool" && /└ .*ctrl\+r/.test(lines[lines.length - 1] ?? ""))
+        if (cell.kind === "tool" && lines.some((l) => l.includes("ctrl+r")))
             this.#collapsed.unshift(i);
         this.#lineCache[i] = lines;
         const placed = bodySpacing(i > 0 ? this.#lineCache[i - 1] : null, lines);
@@ -965,7 +1060,51 @@ export class Body {
         const turn = cell.turn >= 0 ? this.#turns[cell.turn] : undefined;
         if (turn === undefined || turn !== this.#turns[this.#turns.length - 1])
             return false;
-        return !turn.ended && !turn.hasText;
+        if (!turn.ended && !turn.hasText)
+            return true;
+        // the turn's END releases every hold — the settle is where the run
+        // is decided, and a held cell at settle would never commit at all.
+        if (turn.ended)
+            return false;
+        return this.#growingRun(i);
+    }
+    /** TUI2-R1.5 ① (VD-1) — the explore-run hold. W14's hold covers the
+     *  QUIET turn only, and the model's own narration ("let me look at the
+     *  parser area") sets hasText before the first read even starts: from
+     *  there each completion committed in its OWN frame, the head committed
+     *  alone, and `members.every(done)` — the fold's gate — could never be
+     *  true again. Every real session therefore degraded to one row per
+     *  call while the unit suite, which feeds the burst synchronously,
+     *  stayed green (the walkthrough's frame s1-06).
+     *
+     *  The hold is the smallest honest fix: a DONE explore cell whose run
+     *  can still GROW does not commit yet — its committed form is not
+     *  decided until the run is closed. The run closes at the first
+     *  non-explore cell (the model's next word, an edit, a shell) or at the
+     *  turn's end, and the whole run then commits in ONE frame, which is
+     *  exactly the shape the fold was written for.
+     *
+     *  The force-commit path never consults this (see #held's callers): the
+     *  screen's hard cap still wins, so the screen never sticks — a run
+     *  under real screen pressure degrades mid-turn, and the rows it
+     *  already froze stay frozen (history is never rewritten, ADR-0046). */
+    #growingRun(i) {
+        const cell = this.#cells[i];
+        if (cell.kind !== "tool" || !isExploreTool(cell.name))
+            return false;
+        // the run is still growing while NOTHING but explore cells follow —
+        // the turn-less noise cells (permission raws, ⚠ notices) are
+        // transparent here for the same reason the run scan sees through
+        // them: the streaming execution interleaves them between the calls.
+        for (let j = i + 1; j < this.#cells.length; j += 1) {
+            const next = this.#cells[j];
+            if (next.kind === "raw" || next.kind === "notice")
+                continue;
+            if (next.kind === "tool" && isExploreTool(next.name))
+                continue;
+            return false; // a non-explore cell closed the run — commit now
+        }
+        return true;
     }
     /** W14/W13 — the release-time decision at a commit, BEFORE the cell's
      *  own render: the folded-turn fold first (a QUIET turn — ended, no
@@ -994,26 +1133,38 @@ export class Body {
                 return [];
             }
         }
-        if (cell.kind !== "tool" || ROLLUP_NOUN[cell.name] === undefined)
+        if (cell.kind !== "tool" || !isExploreTool(cell.name))
             return cellComponent(cell).render(W, ctx);
-        // the maximal same-name run around i — forward/backward scans over
+        // TUI2-R1 (B): the run is over the READ-ONLY SET, not one name —
+        // a model exploring mixes read/list/search, and the same-name scan
+        // split every real burst into fragments. Writes, edits, shells and
+        // extension tools still break the run at the first one.
+        // the maximal read-only run around i — forward/backward scans over
         // the cells. The turn-less noise cells (the permission raws, the ⚠
         // notices) are TRANSPARENT: the streaming execution (loop.ts launch)
         // interleaves them BETWEEN the calls of one burst, so the run must
         // see through them. It never crosses a user/text/thinking cell —
         // those separate turns and contexts.
+        // TUI2-R1.5 ① (VD-1): the backward scan stops at the cells this
+        // FRAME is committing. A cell committed in an earlier frame is
+        // frozen — its rows are on the screen and in the scrollback — so it
+        // can never become the head of a rollup now, and a run that
+        // force-committed its first rows mid-turn must not have the rest
+        // silently absorbed into a summary that was computed without them.
+        // The degraded head keeps its individual row; the rest of the run
+        // rolls on its own.
         let s = i;
         let head = i;
-        while (s > 0) {
+        while (s > this.#committedAtFrameStart) {
             const prev = this.#cells[s - 1];
             if (prev.kind === "raw" || prev.kind === "notice") {
                 s -= 1;
                 continue;
             }
-            if (prev.kind !== "tool" || prev.name !== cell.name)
+            if (prev.kind !== "tool" || !isExploreTool(prev.name))
                 break;
             s -= 1;
-            head = s; // a same-name tool precedes — it is the group's head
+            head = s; // a read-only tool precedes — it is the group's head
         }
         let e = i;
         while (e + 1 < this.#cells.length) {
@@ -1022,7 +1173,7 @@ export class Body {
                 e += 1;
                 continue;
             }
-            if (next.kind !== "tool" || next.name !== cell.name)
+            if (next.kind !== "tool" || !isExploreTool(next.name))
                 break;
             e += 1;
         }
@@ -1040,13 +1191,18 @@ export class Body {
             this.#rolledHeads.add(head);
             let total = 0;
             const targets = [];
+            // TUI2-R1 (B): the per-tool parts, in first-call order — the
+            // exploration row's counts and its expanded list both read them.
+            // A search's subject is the PATTERN it looked for (quoted); a
+            // read's or a list's is the path it named.
+            const parts = [];
             for (const m of members) {
                 // the lines count, excluding the tool's OWN truncation note
                 // (read_file's "… N more lines") — the per-cell meta's rule
                 const noteAt = m.resultText.lastIndexOf("\n… ");
                 const shown = noteAt >= 0 ? m.resultText.slice(0, noteAt) : m.resultText;
-                const parts = shown.split("\n");
-                total += parts[parts.length - 1] === "" ? parts.length - 1 : parts.length;
+                const rows = shown.split("\n");
+                total += rows[rows.length - 1] === "" ? rows.length - 1 : rows.length;
                 let input = {};
                 try {
                     input = JSON.parse(m.inputFull);
@@ -1057,11 +1213,19 @@ export class Body {
                 }
                 const target = toolTarget(m.name, input);
                 targets.push(target.split("/").pop() ?? target);
+                const subject = m.name === "search_text" ? `"${String(input.pattern ?? "")}"` : target;
+                const part = parts.find((x) => x.name === m.name);
+                if (part === undefined)
+                    parts.push({ name: m.name, subjects: [subject] });
+                else
+                    part.subjects.push(subject);
             }
             const first = members[0];
             const last = members[members.length - 1];
             const elapsed = first.startedAt !== null && last.doneAt !== null ? ((last.doneAt - first.startedAt) / 1000).toFixed(1) : "?";
-            cell.rolled = { count: members.length, lines: total, elapsed, targets };
+            // TUI2-R1 (B): `parts` rides ONLY a mixed run — a single-name
+            // run keeps W13's row, byte for byte (the generalization adds).
+            cell.rolled = { count: members.length, lines: total, elapsed, targets, ...(parts.length > 1 ? { parts } : {}) };
             return cellComponent(cell).render(W, ctx);
         }
         // a MEMBER of an already-rolled run → [] (its rows live in the
@@ -1132,7 +1296,11 @@ export class Body {
         if (menu === null || menu === undefined || menu.items.length === 0)
             return [];
         const p = palette();
-        const rows = [];
+        // TUI2-R1.5 ⑦(b) (VD-8): the band NAMES itself, the same way the @
+        // picker's does. Both render frameless directly above the composer,
+        // so with scrollback behind them there was nothing to say where the
+        // surface began — the rows read as more history.
+        const rows = [bandHeader("commands", W)];
         for (let i = 0; i < menu.items.length; i += 1) {
             const item = menu.items[i];
             const text = i === menu.selected
@@ -1224,7 +1392,7 @@ export class Body {
         // the lead — the panel's phase lead when the panel owns the row
         // (1-3> / the rule input's "2 Yes, don't ask again for " / the
         // amend "feedback (deny): "), the bound prompt otherwise
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : this.#inputPrompt;
+        const lead = panel !== null ? panelLeadOf(panel) : this.#inputPrompt;
         const leadW = leadWidth(lead);
         // a LEGACY one-row provider (the old {line, cursor} shape) keeps
         // working: its single line is the composer's single row
@@ -1266,6 +1434,7 @@ export class Body {
      *  EVERY row is idempotent: N consecutive resizes end with the same
      *  screen as a single jump to the same size. */
     #drawFull(out, W, H, liveTop, liveLines, queueRows, menuRows, editor) {
+        const overlay = this.#overlayFrame;
         const inputExtra = editor.rows.length - 1; // KC1: the composer's rows above the retired single input row
         const committed = this.#committedLinesThisFrame;
         // 0. the FROZEN rows — the re-folded committed content (re-flowed
@@ -1293,7 +1462,15 @@ export class Body {
         // window (the committed share + the live + the chrome), r
         // monotone, every row 1..H re-painted (the V6-1 every-row rule).
         const all = [...frozen, ...committed, ...liveLines];
-        const skip = Math.max(0, all.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
+        // TUI2-R1.5 7(a) (VD-8): while the sheet is up the window does NOT
+        // move. skip is frozen at its pre-open value and #lastSkip is left
+        // alone, so no LF is emitted and nothing enters the scrollback; the
+        // march below is clamped to the window instead, which makes the
+        // sheet displace content ON SCREEN. Closing takes the full-redraw
+        // path with the same #lastSkip and every displaced row comes back.
+        const skip = overlay
+            ? this.#lastSkip
+            : Math.max(0, all.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
         // A8b (the shrink-trigger's completion): the rows that LEAVE the
         // window scroll into the terminal's scrollback — the LF mechanism
         // (the steady path's own). Only the rows the paint re-covers (the
@@ -1305,7 +1482,7 @@ export class Body {
         // shrink EVERY frame) loses the scrolled-away turns from the
         // terminal's scrollback entirely (finding #A8b — the queued-flood
         // content loss).
-        if (skip > 0) {
+        if (skip > 0 && !overlay) {
             const leaving = Math.max(0, skip - this.#lastSkip);
             // A8b (the fresh leaving share): a leaving row whose old-screen
             // copy is stale — the committed-this-frame lines (their old rows
@@ -1329,9 +1506,16 @@ export class Body {
             for (let i = 0; i < skip; i += 1)
                 out.push("\n");
         }
-        this.#lastSkip = skip;
+        if (!overlay)
+            this.#lastSkip = skip;
         let r = 1;
-        for (const line of all.slice(skip)) {
+        // the window's content rows: everything above the chrome. With the
+        // overlay up `all` can exceed it, and the rows that give way are the
+        // OLDEST on screen — they are still in the model and come back on
+        // the close.
+        const contentRows = Math.max(0, H - CHROME_ROWS - inputExtra - queueRows.length - menuRows.length);
+        const march = all.slice(skip);
+        for (const line of march.length > contentRows ? march.slice(march.length - contentRows) : march) {
             out.push(`\x1b[${r};1H\x1b[0K${this.#checked(line, W)}`);
             r += 1;
         }
@@ -1382,8 +1566,12 @@ export class Body {
         // frozenCount, so the lines at [frozenCount..skip−1] are the fresh
         // leaving share (their old-screen copies are stale).
         const frozenCount = this.#committedLines - committed.length;
-        const skip = Math.max(0, this.#committedLines + liveLines.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
-        const leaving = Math.max(0, skip - this.#lastSkip);
+        // TUI2-R1.5 7(a): an overlay frame never moves the window (see
+        // #drawFull) — the sheet's rows displace content on screen instead
+        // of pushing it into the scrollback.
+        const overlay = this.#overlayFrame;
+        const skip = overlay ? this.#lastSkip : Math.max(0, this.#committedLines + liveLines.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
+        const leaving = overlay ? 0 : Math.max(0, skip - this.#lastSkip);
         // the jump to the bottom row H, then N real LFs scroll the screen
         // exactly N rows — ONE per committed line (the bookkeeping; the
         // stale 1B anchor jumped to H−1 and the N LFs scrolled only N−1 —
@@ -1603,6 +1791,15 @@ export class Dock {
         }
         compositorRef.bindApproval(state);
     }
+    /** TUI2-R1 (D): bind the editor's keys-sheet flag — the slot read for
+     *  the ? overlay (the menu/picker binding pattern). */
+    bindSheet(state) {
+        if (compositorRef === null) {
+            dockBindings.sheet = state;
+            return;
+        }
+        compositorRef.bindSheet(state);
+    }
     bindInput(state, prompt) {
         if (compositorRef === null) {
             dockBindings.state = state; // the live buffer — order-agnostic
@@ -1653,4 +1850,4 @@ let compositorRef = null;
  *  — the old snapshot froze `menu` at bindInput time and the slash-
  *  command menu silently never bound in the real CLI (the e2e gates
  *  bind the Body directly and could not see it). */
-const dockBindings = { state: null, prompt: "", menu: null, at: null, panel: null, queue: null };
+const dockBindings = { state: null, prompt: "", menu: null, at: null, panel: null, sheet: null, queue: null };

package/dist/context-ledger.d.ts

@@ -0,0 +1,66 @@
+/**
+ * TUI2-R1 (E) — /context's attribution rows.
+ *
+ * The question "where did my context go?" has had an answer since E3:
+ * the trace sidecar's rent ledger records, per request, exactly what
+ * each static surface costs, and the context manifest records what the
+ * conversation costs. Until now that answer was only readable by
+ * someone willing to parse JSONL.
+ *
+ * This module is the presentation half and nothing else — a pure
+ * function from counts to rows, with no idea where the counts came
+ * from. That matters for the purity gate: the trace surface is an
+ * OBSERVATION surface (ADR-0051 §6), correctness never reads it, and
+ * keeping the reader in the CLI and the renderer here means this module
+ * cannot accidentally become a second correctness path.
+ *
+ * Every number is a count the ledger already carries. Nothing here
+ * estimates, projects, or predicts.
+ */
+/** The counts one request's ledger yields, already grouped by surface.
+ *  Estimated tokens throughout (the rent ledger's own chars/4 convention
+ *  — R6), because that is the unit the ledger records. */
+export interface ContextLedger {
+    /** The model's context window, as the session is configured. */
+    readonly window: number;
+    /** system:base + every system:ext:* append EXCEPT skills. */
+    readonly systemPrompt: number;
+    /** system:base alone — the detail behind the row. */
+    readonly systemBase: number;
+    /** how many extensions appended (the detail's count). */
+    readonly appends: number;
+    /** the sum of the tool:* lines. */
+    readonly toolTable: number;
+    readonly tools: number;
+    /** system:ext:skills — broken out because it is an INDEX of content
+     *  rather than an instruction, and it grows with the workspace rather
+     *  than with the build. 0 when the extension is not loaded. */
+    readonly skillsIndex: number;
+    /** how many skills the index lists — 0 when the caller cannot know
+     *  (the rent ledger records surfaces, never their contents). */
+    readonly skills: number;
+    /** the per-request skeleton (the `envelope` rent line). */
+    readonly envelope: number;
+    /** the context manifest's turn segments — the conversation itself. */
+    readonly messages: number;
+    readonly turns: number;
+}
+/**
+ * The rows: the header, the bar, one row per surface that EXISTS, and
+ * the free remainder.
+ *
+ * An absent surface is an absent row — the rent ledger's own R9 rule
+ * ("not paid = no rent"), carried into the display: a session with no
+ * skills extension should not read a "skills index 0" row, because the
+ * zero would look like a measurement rather than an absence.
+ *
+ * The columns are fixed so the numbers line up as a column of numbers;
+ * the detail text rides after them, dim, and is cut by the caller's
+ * width if it must be.
+ */
+export declare function contextRows(ledger: ContextLedger): string[];
+/** TUI2-R1 (E) — the honest fallback. The ledger is written PER REQUEST:
+ *  a session that has not called the model yet has no sidecar, and the
+ *  right thing to show is that fact and the one step that produces one.
+ *  Never an empty bar — an empty bar reads as "measured zero". */
+export declare function contextUnavailableRows(reason: string): string[];

package/dist/context-ledger.js

@@ -0,0 +1,87 @@
+/**
+ * TUI2-R1 (E) — /context's attribution rows.
+ *
+ * The question "where did my context go?" has had an answer since E3:
+ * the trace sidecar's rent ledger records, per request, exactly what
+ * each static surface costs, and the context manifest records what the
+ * conversation costs. Until now that answer was only readable by
+ * someone willing to parse JSONL.
+ *
+ * This module is the presentation half and nothing else — a pure
+ * function from counts to rows, with no idea where the counts came
+ * from. That matters for the purity gate: the trace surface is an
+ * OBSERVATION surface (ADR-0051 §6), correctness never reads it, and
+ * keeping the reader in the CLI and the renderer here means this module
+ * cannot accidentally become a second correctness path.
+ *
+ * Every number is a count the ledger already carries. Nothing here
+ * estimates, projects, or predicts.
+ */
+import { palette } from "./render.js";
+const BAR_CELLS = 12;
+/** k-units for the ledger's columns: 25700 → 25.7k, 300 → 300, 11 → 11.
+ *
+ *  TUI2-R1.5 ⑤ (VD-15): the floor was 100, which put `11`, `0.3k` and
+ *  `25.7k` in one right-aligned column — two unit systems stacked, and
+ *  the reader has to switch between them row by row to compare. The
+ *  repo already had a k-formatter with a 1000 floor (render.ts's kUnit,
+ *  which the status row and every settled card use); this now agrees
+ *  with it, so /context speaks the same number language as the rest of
+ *  the product. It still differs from kUnit in never having a null to
+ *  report — every ledger figure is a measured count. */
+function k(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k` : String(Math.round(n));
+}
+/**
+ * The rows: the header, the bar, one row per surface that EXISTS, and
+ * the free remainder.
+ *
+ * An absent surface is an absent row — the rent ledger's own R9 rule
+ * ("not paid = no rent"), carried into the display: a session with no
+ * skills extension should not read a "skills index 0" row, because the
+ * zero would look like a measurement rather than an absence.
+ *
+ * The columns are fixed so the numbers line up as a column of numbers;
+ * the detail text rides after them, dim, and is cut by the caller's
+ * width if it must be.
+ */
+export function contextRows(ledger) {
+    const p = palette();
+    const used = ledger.systemPrompt + ledger.toolTable + ledger.skillsIndex + ledger.envelope + ledger.messages;
+    const free = Math.max(0, ledger.window - used);
+    const ratio = ledger.window > 0 ? Math.min(1, used / ledger.window) : 1;
+    const filled = Math.max(0, Math.min(BAR_CELLS, Math.round(ratio * BAR_CELLS)));
+    const rows = [
+        `${p.bold}context — ${k(used)} / ${k(ledger.window)} tokens (${Math.round(ratio * 100)}%)${p.reset}`,
+        `${p.bold}${"▰".repeat(filled)}${p.reset}${p.dim}${"▱".repeat(BAR_CELLS - filled)}${p.reset}`,
+    ];
+    /** One surface row: the label at 14 columns, the count right-aligned
+     *  at 5, then the dim detail. */
+    const row = (label, value, detail) => `  ${p.bold}▰${p.reset} ${label.padEnd(14)}${p.bold}${k(value).padStart(5)}${p.reset}${detail === "" ? "" : `  ${p.dim}${detail}${p.reset}`}`;
+    if (ledger.systemPrompt > 0) {
+        rows.push(row("system prompt", ledger.systemPrompt, `(base ${k(ledger.systemBase)}${ledger.appends > 0 ? ` + ${ledger.appends} extension append${ledger.appends === 1 ? "" : "s"}` : ""})`));
+    }
+    if (ledger.toolTable > 0)
+        rows.push(row("tool table", ledger.toolTable, `${ledger.tools} tool${ledger.tools === 1 ? "" : "s"}`));
+    if (ledger.skillsIndex > 0) {
+        // the skill COUNT is not in the ledger (rent records surfaces, not
+        // their contents) — a caller that knows it passes it, and a caller
+        // that does not gets the honest half of the sentence rather than a
+        // fabricated number.
+        rows.push(row("skills index", ledger.skillsIndex, `${ledger.skills > 0 ? `${ledger.skills} skill${ledger.skills === 1 ? "" : "s"}, ` : ""}tier-1 lines only`));
+    }
+    if (ledger.envelope > 0)
+        rows.push(row("envelope", ledger.envelope, ""));
+    if (ledger.messages > 0)
+        rows.push(row("messages", ledger.messages, `${ledger.turns} turn${ledger.turns === 1 ? "" : "s"}`));
+    rows.push(`  ${p.dim}▱ ${"free".padEnd(14)}${k(free).padStart(5)}${p.reset}`);
+    return rows;
+}
+/** TUI2-R1 (E) — the honest fallback. The ledger is written PER REQUEST:
+ *  a session that has not called the model yet has no sidecar, and the
+ *  right thing to show is that fact and the one step that produces one.
+ *  Never an empty bar — an empty bar reads as "measured zero". */
+export function contextUnavailableRows(reason) {
+    const p = palette();
+    return [`${p.bold}context — no ledger yet${p.reset}`, `  ${p.dim}${reason}${p.reset}`];
+}