@vincemakes/kiso-tui 0.8.0 → 0.9.0

package/dist/ask-panel.js

@@ -197,7 +197,15 @@ export function askBlockRows(view, state, W, maxRows) {
         rows.push(...body);
     }
     rows.push(`${gutter}${p.dim}${askAffordance(state)}${p.reset}`);
-    rows.push(`${p.dim}└ ${p.reset}`);
+    // TUI2-R1.5 11 (VD-13), shared with the approval panel: a real bottom RULE, in the block's own edge
+    // vocabulary — the same box-drawing run its divider already uses —
+    // anchored at the gutter column. It used to be `\u2514 `: a two-cell stub
+    // floating at column 1, with no rule running from it and no corner
+    // above it to answer. Worse, `\u2514 ` is the cut-notice prefix everywhere
+    // else in the product, so a CAPPED panel emitted two elbow rows in a
+    // row meaning entirely different things. The rule reads as an edge,
+    // and the cut notice above it reads as a notice.
+    rows.push(`${p.dim}\u2514${"\u2500".repeat(Math.max(0, W - 1))}${p.reset}`);
     return rows;
 }
 /** The status row's right-hand hint — the phase's keys. */

package/dist/at-picker.d.ts

@@ -157,3 +157,7 @@ export declare function atPanelRows(state: {
     selected: number;
     capped: boolean;
 }, W: number): string[];
+/** TUI2-R1.5 ⑦(b) — the one-row dim header that turns a band into a
+ *  surface. Shared by the @ picker and the / menu so the two read the
+ *  same way. */
+export declare function bandHeader(label: string, W: number): string;

package/dist/at-picker.js

@@ -182,20 +182,41 @@ function splitPath(path) {
 export function atRow(match, selected, W) {
     const p = palette();
     const { dir, name } = splitPath(escapeTerminal(match.path));
-    const lead = selected ? `${p.rv}→ ${p.rvEnd}` : "  ";
     // the name's own matched positions, mapped out of the full path
     const marks = new Set(match.hit.filter((i) => i >= dir.length).map((i) => i - dir.length));
-    // room: W − the 2-cell lead − 1 separating space before the directory
-    const nameRoom = Math.max(1, W - 2 - (dir === "" ? 0 : visibleWidth(dir) + 1));
+    // TUI2-R1.5 ⑧ (VD-9): the directory rides NEXT TO the name it
+    // qualifies. It used to be right-aligned to the band's far edge, which
+    // on a 100-column terminal put `src/` some eighty columns from the
+    // `parser.ts` it belongs to: the eye had to cross the whole row to
+    // learn which parser.ts this was, and the column read as a second list.
+    // Adjacent and dim, it is what it always meant to be — a qualifier.
+    // the name is the flexible column and the qualifier gives way first: a
+    // narrow window keeps the thing being aimed at.
+    const room = Math.max(1, W - 2);
+    const suffix = dir === "" ? "" : widthCut(`  — ${dir}`, Math.max(0, room - 4));
+    const nameRoom = Math.max(1, room - visibleWidth(suffix));
     const shownName = widthCut(name, nameRoom);
     let painted = "";
     for (let i = 0; i < shownName.length; i += 1) {
         painted += marks.has(i) ? `${p.bold}${shownName[i]}${p.reset}` : shownName[i];
     }
-    if (dir === "")
-        return `${lead}${painted}`;
-    const pad = Math.max(1, W - 2 - visibleWidth(shownName) - visibleWidth(dir));
-    return `${lead}${painted}${" ".repeat(pad)}${p.dim}${dir}${p.reset}`;
+    const text = `${painted}${suffix === "" ? "" : `${p.dim}${suffix}${p.reset}`}`;
+    const width = visibleWidth(shownName) + visibleWidth(suffix);
+    if (!selected)
+        return `  ${text}`;
+    // TUI2-R1.5 ⑧ (VD-9): the selection is a FULL-ROW bar — the W16 chip
+    // mechanism, which the user chip and the turn fold already use. A
+    // two-cell `→ ` marker on the inverse band is one character of
+    // highlight in an eighty-column row, and the walkthrough could barely
+    // find it. The bar spans the row's whole width so the selection is
+    // visible from anywhere on the line. Mono discipline: reverse video,
+    // no new colours.
+    //
+    // The inner spans close with rvEnd (SGR 27), never SGR 0 — a reset
+    // inside the bar would punch a hole in it. `painted`'s bold marks and
+    // the dim suffix both end in SGR 0, so the bar is re-opened after each.
+    const inner = `${painted.replaceAll(p.reset, `${p.reset}${p.rv}`)}${suffix === "" ? "" : `${p.dim}${suffix}${p.reset}${p.rv}`}`;
+    return `${p.rv} ${inner}${" ".repeat(Math.max(0, W - width - 2))} ${p.rvEnd}`;
 }
 /**
  * KC3 §4 — the counter row: `(n/total)`, where n is the 1-based
@@ -220,9 +241,21 @@ export function atCounterRow(selected, total, capped, W) {
  */
 export function atPanelRows(state, W) {
     const { first, count } = atWindow(state.matches.length, state.selected);
-    const rows = [];
+    // TUI2-R1.5 ⑦(b) (VD-8): the band NAMES itself. It renders frameless
+    // directly above the composer, so with scrollback behind it there was
+    // nothing to say where the surface began — the rows read as more
+    // history. One dim row is enough to make it UI. Mono discipline: dim
+    // text, no rule, no colour.
+    const rows = [bandHeader("files", W)];
     for (let i = first; i < first + count; i += 1)
         rows.push(atRow(state.matches[i], i === state.selected, W));
     rows.push(atCounterRow(state.selected, state.matches.length, state.capped, W));
     return rows;
 }
+/** TUI2-R1.5 ⑦(b) — the one-row dim header that turns a band into a
+ *  surface. Shared by the @ picker and the / menu so the two read the
+ *  same way. */
+export function bandHeader(label, W) {
+    const p = palette();
+    return `${p.dim}${widthCut(label, Math.max(1, W))}${p.reset}`;
+}

package/dist/compositor.d.ts

@@ -109,6 +109,20 @@ export declare class Body {
      *  outcome. */
     toolVerdict(callId: string, decision: "approved" | "denied", decidedBy?: string, reason?: string): void;
     toolRunning(callId: string): void;
+    /**
+     * 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: string, text: string): void;
     toolSucceeded(callId: string): void;
     toolFailed(callId: string, error: string): void;
     toolResult(callId: string, result: {
@@ -152,7 +166,7 @@ export declare class Body {
      *  frame. The inactive path keeps the historical bytes (no resume —
      *  the pipe contract). */
     banner(version: string, extensionsText: string, resume?: ResumeMeta[]): void;
-    raw(lines: string[]): void;
+    raw(lines: string[], wrap?: "words"): void;
     /** The last COMPLETE thinking block, for /think. */
     lastThinking(): string | null;
     /** The last completed tool call, for /last. */
@@ -208,6 +222,8 @@ export declare class Body {
     bindInput(state: () => InputState, prompt: string): void;
     /** 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: () => boolean): void;
     bindMenu(state: () => {
         items: readonly MenuItem[];
         selected: number;
@@ -252,6 +268,9 @@ export declare class Dock {
      *  occupant (the panel replaces the live region + the input lead
      *  while up; the old ApprovalPrompt's question slot retires). */
     bindApproval(state: () => PanelState | null): void;
+    /** TUI2-R1 (D): bind the editor's keys-sheet flag — the slot read for
+     *  the ? overlay (the menu/picker binding pattern). */
+    bindSheet(state: () => boolean): void;
     bindInput(state: () => InputState, prompt: string): void;
     bindMenu(state: () => {
         items: readonly MenuItem[];

package/dist/compositor.js

@@ -48,9 +48,10 @@ import { leadWidth } from "./width.js"; // W23: the ONE width authority (the edi
 // 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 } from "./at-picker.js";
-import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, foldLine, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.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). */
@@ -118,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;
@@ -153,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;
     }
@@ -212,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
@@ -282,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");
@@ -492,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();
@@ -502,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. */
@@ -555,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}`)],
@@ -680,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;
     }
@@ -772,10 +833,20 @@ 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
@@ -861,7 +932,26 @@ 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).
@@ -940,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);
@@ -967,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
@@ -996,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) {
@@ -1024,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;
         }
@@ -1042,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);
@@ -1059,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
@@ -1134,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
@@ -1268,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
@@ -1295,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
@@ -1307,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
@@ -1331,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;
         }
@@ -1384,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 —
@@ -1605,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
@@ -1655,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}`];
+}

package/dist/editor.d.ts

@@ -60,6 +60,9 @@ export declare class Editor {
     bindQueue(state: () => readonly string[], pop: () => string | null): void;
     /** The whole buffer as text (the CLI's line()/clearLine()). */
     line(): string;
+    /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
+     *  read (bound like the menu and the picker). */
+    sheetOpen(): boolean;
     clearLine(): void;
     /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
      *  their legacy meaning (the CURSOR LINE's visible slice and the

package/dist/editor.js

@@ -42,6 +42,8 @@ export const MENU_ITEMS = [
     { name: "/think", desc: "show the last full thinking block" },
     { name: "/last", desc: "show the most recent tool call's input and output" },
     { name: "/status", desc: "show session id, event count, and context estimate" },
+    // TUI2-R1 (E): the rent-ledger attribution — where the context went
+    { name: "/context", desc: "show where the context went — the last request's rent ledger" },
     { name: "/help", desc: "print this list of commands" },
 ];
 /** KC1 §3 — the newline code point. Every source (paste, Ctrl+J, the
@@ -109,6 +111,12 @@ export class Editor {
     // coexist; the editor never interprets the key itself.
     #expandCbs = [];
     #onRender;
+    /** TUI2-R1 (D): the keys sheet — a static one-screen overlay opened by
+     *  `?` on an empty composer and closed by the next key, whatever it
+     *  is. Deliberately a BOOLEAN and not a panel: the panel machinery
+     *  exists for interactions (a lead, a status, a reducer, a stashed
+     *  buffer), and the sheet has no interaction to speak of. */
+    #sheetOpen = false;
     #menuOpen = false; // v3 §04: the slash-command menu
     #menuSel = 0;
     // KC3 §3 — the @ file picker. THREE fields and no more: the armed
@@ -194,6 +202,11 @@ export class Editor {
     line() {
         return String.fromCodePoint(...this.#chars);
     }
+    /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
+     *  read (bound like the menu and the picker). */
+    sheetOpen() {
+        return this.#sheetOpen;
+    }
     clearLine() {
         this.#chars = [];
         this.#cursor = 0;
@@ -510,6 +523,17 @@ export class Editor {
     feed(raw) {
         const text = this.#pending + this.#decoder.decode(raw, { stream: true });
         this.#pending = "";
+        // TUI2-R1 (D): the sheet is up — ANY key closes it, and the key
+        // that closed it is CONSUMED. The whole chunk goes, deliberately:
+        // an arrow key is three bytes, and closing on the first while
+        // letting `[A` fall through as literal text would be a sheet that
+        // types into your composer on the way out. A dismissal costs one
+        // keystroke; that is the entire contract.
+        if (this.#sheetOpen) {
+            this.#sheetOpen = false;
+            this.#onRender();
+            return;
+        }
         let i = 0;
         while (i < text.length) {
             const c = text[i];
@@ -752,6 +776,17 @@ export class Editor {
                     cb();
                 i += 1;
             }
+            else if (c === "?" && this.#composerIdle() && this.#chars.length === 0) {
+                // TUI2-R1 (D): `?` opens the keys sheet — but ONLY on an
+                // empty composer with nobody else holding the keys. Mid-text
+                // it is the question mark a human is typing, and #composerIdle
+                // already encodes "no panel, no menu, no picker, no browse".
+                // The precedence can only ever ADD: every state that used to
+                // insert a `?` still inserts one.
+                this.#sheetOpen = true;
+                this.#onRender();
+                i += 1;
+            }
             else if (c !== undefined && c < " ") {
                 i += 1; // other control — ignored
             }

package/dist/index.d.ts

@@ -7,12 +7,13 @@
  */
 export { Body, Dock, CURSOR_MARKER, type BodyOptions } from "./compositor.js";
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, type PanelArgs, type PanelFlavor, type PanelPhase, type PanelSel, type PanelState, type PanelVerdict, type PanelView, } from "./approval-panel.js";
-export { Container, foldLine, visibleWidth, SPINNER, type Component, type FrameCtx } from "./components.js";
+export { Container, foldLine, foldWords, visibleWidth, SPINNER, type Component, type FrameCtx } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, type MenuItem, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type PathResolver, type RecapStats, type ResumeMeta, type RenderInput, type RenderResult, type RunUsage, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
-export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus, type StatusMeter } from "./status.js";
+export { contextRows, contextUnavailableRows, type ContextLedger } from "./context-ledger.js";
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact } from "./strings.js";
 export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun, type AtItem, type AtMatch } from "./at-picker.js";
 export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type AskStep, } from "./ask-panel.js";
-export { extensionsBannerText, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";
+export { KEY_BINDINGS, PANEL_KEYS_ROW, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView, type BannerExtension, type KeyBinding } from "./strings.js";

package/dist/index.js

@@ -10,13 +10,16 @@ export { Body, Dock, CURSOR_MARKER } from "./compositor.js";
 // that replaces the running tool's live window while a human-chain
 // approval is pending (the shape authority is the committed preview).
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, } from "./approval-panel.js";
-export { Container, foldLine, visibleWidth, SPINNER } from "./components.js";
+export { Container, foldLine, foldWords, visibleWidth, SPINNER } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff } from "./diff.js";
 // KC2 §5: the status rows' formatters — the CLI keeps the state and the
 // repaint, the terminal layer owns what the row says.
-export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus } from "./status.js";
+// TUI2-R1 (E): /context's attribution rows — a pure function of the
+// counts the trace sidecar already records (the CLI reads, this renders).
+export { contextRows, contextUnavailableRows } from "./context-ledger.js";
 // KC3 §1 (the extraction): the human-facing strings — the prompt, the
 // project-trust listing/view/note, the uncertain execution's view. The
 // FLOW (who is asked, what a verdict means) stays in the cli.
@@ -30,4 +33,6 @@ export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow,
 export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, } from "./ask-panel.js";
 // KC3.5 §4: the interrupted-ask copy — the SAME uncertainty gate, said
 // honestly for a question nobody answered (the ① probe's surface).
-export { extensionsBannerText, helpRows, unansweredAskView } from "./strings.js";
+// TUI2-R1 (D): the keys sheet + THE key table — one source for the ?
+// overlay and /help's keys row.
+export { KEY_BINDINGS, PANEL_KEYS_ROW, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView } from "./strings.js";

package/dist/status.d.ts

@@ -33,6 +33,36 @@ export declare const STATUS_GLYPHS: readonly ["▖", "▘", "▝", "▗"];
  * because it is on screen exactly when the gesture is useful.
  */
 export declare function runningStatus(glyph: string, since: number, outTokens: number | null, ctxRatio: number): string;
+/**
+ * TUI2-R1 (E) — the idle row's meter: what the session has SPENT, next
+ * to what it has left.
+ *
+ * Both fields are optional and both are omitted when unknown, because
+ * the row's job is to be true rather than complete:
+ *
+ *   - `cacheHitPct` is cacheRead / (fresh + cacheRead) — the E2
+ *     denominator (the pinned sentence: it cannot exceed 100%). A
+ *     session with no usage yet has no cache hit rate, and an
+ *     unmeasured cache is NOT a 0% cache, so it renders nothing.
+ *   - `costUsd` is the CANONICAL cost, which is null whenever the
+ *     pricing table has no rate for the route. Null renders nothing.
+ *     No rate table, no number — kiso does not invent a price.
+ */
+export interface StatusMeter {
+    readonly cacheHitPct: number | null;
+    readonly costUsd: number | null;
+}
 /** The IDLE row: the approval tier as the CALLER names it, the /mode
- *  hint, the model driving the session, and the ctx estimate. */
-export declare function idleStatus(tier: string, model: string, ctxRatio: number): string;
+ *  hint, the model driving the session, the TUI2-R1 meter when there is
+ *  one, and the ctx estimate. Called without a meter — or with one that
+ *  knows nothing — the row is byte-identical to the pre-round row. */
+export declare function idleStatus(tier: string, model: string, ctxRatio: number, meter?: StatusMeter): string;
+/** TUI2-R1 (E) — the cache hit rate the status row shows, from the usage
+ *  the CLI already tracks. The denominator is the TOTAL the model was
+ *  given (fresh + cacheRead), which is the E2 ruling's own: cacheRead
+ *  over fresh alone once rendered 923%. No input at all → null, never a
+ *  zero. */
+export declare function cacheHitPct(usage: {
+    in: number | null;
+    cache: number | null;
+}): number | null;

package/dist/status.js

@@ -46,7 +46,28 @@ export function runningStatus(glyph, since, outTokens, ctxRatio) {
     return `${glyph} working ${seconds}s${out} · esc stop · alt+⏎ redirect · ctx left ~${ctxLeft(ctxRatio)}%`;
 }
 /** The IDLE row: the approval tier as the CALLER names it, the /mode
- *  hint, the model driving the session, and the ctx estimate. */
-export function idleStatus(tier, model, ctxRatio) {
-    return `▸ ${tier} · /mode to switch · ${model} · ctx left ~${ctxLeft(ctxRatio)}%`;
+ *  hint, the model driving the session, the TUI2-R1 meter when there is
+ *  one, and the ctx estimate. Called without a meter — or with one that
+ *  knows nothing — the row is byte-identical to the pre-round row. */
+export function idleStatus(tier, model, ctxRatio, meter) {
+    const parts = [`▸ ${tier}`, "/mode to switch", model];
+    if (meter?.cacheHitPct != null)
+        parts.push(`CH ${Math.round(meter.cacheHitPct)}%`);
+    if (meter?.costUsd != null)
+        parts.push(`$${meter.costUsd.toFixed(4)}`);
+    parts.push(`ctx left ~${ctxLeft(ctxRatio)}%`);
+    return parts.join(" · ");
+}
+/** TUI2-R1 (E) — the cache hit rate the status row shows, from the usage
+ *  the CLI already tracks. The denominator is the TOTAL the model was
+ *  given (fresh + cacheRead), which is the E2 ruling's own: cacheRead
+ *  over fresh alone once rendered 923%. No input at all → null, never a
+ *  zero. */
+export function cacheHitPct(usage) {
+    const fresh = usage.in;
+    const cached = usage.cache;
+    if (fresh === null || cached === null)
+        return null;
+    const total = fresh + cached;
+    return total > 0 ? (cached / total) * 100 : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "kiso tui — the pure terminal layer (cell renderer, dock, raw editor, diff, palette). Zero runtime dependencies: input is data, output is bytes.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,6 @@
   },
   "homepage": "https://github.com/vincemakes/kiso/tree/main/packages/tui#readme",
   "dependencies": {
-    "@vincemakes/kiso-tui-cells": "0.8.0"
+    "@vincemakes/kiso-tui-cells": "0.9.0"
   }
 }