@vincemakes/kiso-tui 0.7.0 → 0.9.0

package/dist/ask-panel.d.ts

@@ -0,0 +1,95 @@
+/**
+ * KC3.5 — the ask view: the model asks the human a real question.
+ *
+ * The W21 approval panel generalizes rather than duplicates. An ask is a
+ * PanelView carrying `ask`, so it rides the EXISTING panel slot: the
+ * compositor's live region, the input row's lead, the status/affordance
+ * pair, and — the part that matters — the editor's buffer stash/restore
+ * and its key precedence (the panel owns the keys; the menu, the history
+ * walk and the @ picker never open under it).
+ *
+ * This module owns three things and nothing else:
+ *
+ *   1. the ROWS — the question, the ‹ n/m › counter, the numbered
+ *      options with their descriptions and selection marks, the
+ *      type-your-own line;
+ *   2. the pure REDUCER — a key plus a state gives the next state (and,
+ *      when the walk ends, the result). No I/O, no editor internals: the
+ *      editor feeds it keys and renders what comes back, which is what
+ *      makes the whole interaction unit-testable without a terminal;
+ *   3. the DISPATCHERS — panelBlockRows/panelLead/panelStatus/
+ *      panelAffordance re-exported with the ask branch folded in, so the
+ *      compositor and the editor change ONE import line between them and
+ *      the panel slot itself stays exactly as W21 built it.
+ *
+ * What is deliberately NOT here (the round's stop clauses): no partial
+ * answer durability (a crash re-presents the WHOLE call — per-toggle
+ * durability would need a new durable mechanism), no "chat about this"
+ * hand-off, no timeout and no countdown.
+ */
+import { type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type PanelPhase, type PanelSel, type PanelState, type PanelView } from "./approval-panel.js";
+/** The schema's own bounds — the registry refuses anything outside them
+ *  (extensions/ask validates; these are the numbers it validates to). */
+export declare const ASK_MAX_QUESTIONS = 4;
+export declare const ASK_MIN_OPTIONS = 2;
+export declare const ASK_MAX_OPTIONS = 4;
+export declare const ASK_HEADER_CAP = 12;
+/** The ask panel's opening state: nothing picked, the cursor on the
+ *  first option of the first question. */
+export declare function askStart(spec: AskSpec): AskRuntime;
+/** The decline's honest record: every question with its options, so the
+ *  model reads what it did NOT get an answer to (frame 4). The SAME
+ *  list whether the human pressed esc on question one or question four
+ *  — the round declines the CALL, never half of it. */
+export declare function askDeclineList(spec: AskSpec): string[];
+export declare function askDeclineAll(spec: AskSpec): AskResult;
+/** The answers collected so far, in the tool_result's own shapes: a
+ *  typed answer wins over the picks (the human typed it last), a
+ *  multi-select question yields `choices`, a single one `choice`. */
+export declare function askAnswers(spec: AskSpec, state: AskRuntime): AskAnswer[];
+/** The reducer's outcome: the next state, plus the RESULT when the walk
+ *  ended (the last question answered, or the decline). */
+export interface AskStep {
+    readonly state: AskRuntime;
+    readonly result?: AskResult;
+}
+/**
+ * The pure key reducer. `key` is a single logical key: a digit "1".."4",
+ * "space", "up"/"down", "left" (walk back), "enter", "t" (type your own),
+ * or "esc". The custom phase's TEXT is not routed here — the editor owns
+ * the buffer exactly as it does for the rule-input phase, and hands the
+ * committed line to `askCommitCustom`.
+ */
+export declare function askKey(spec: AskSpec, state: AskRuntime, key: string): AskStep;
+/** The typed answer commits: it becomes THE answer for this question
+ *  (clearing its picks) and the walk advances. An empty line is a
+ *  no-op back to the options — nothing is recorded. */
+export declare function askCommitCustom(spec: AskSpec, state: AskRuntime, text: string): AskStep;
+/** The ask block's rows — the question as the rule line, the header (or
+ *  the counter) as the title, the options as the body, and the
+ *  type-your-own line last. The shape is the W21 block's: gutter, rule,
+ *  title, divider, body, affordance, corner. */
+export declare function askBlockRows(view: PanelView, state: AskRuntime, W: number, maxRows: number): string[];
+/** The status row's right-hand hint — the phase's keys. */
+export declare function askAffordance(state: AskRuntime): string;
+/** The status row's left text — the ask's own line, with the walk. */
+export declare function askStatus(view: PanelView, state: AskRuntime): string;
+/** The input row's lead: the digit lead while picking, the typing lead
+ *  in the custom phase (the rule-input phase's shape, reused). */
+export declare function askLeadPlain(state: AskRuntime): string;
+export declare function panelBlockRows(view: PanelView, phase: PanelPhase, sel: PanelSel, W: number, maxRows: number, ask?: AskRuntime): string[];
+export declare function panelLead(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelLeadPlain(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelStatus(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelAffordance(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+/** The whole panel state in one call — the compositor's four reads share
+ *  one source, so an ask can never render half as an approval. */
+export declare const panelRowsOf: (s: PanelState, W: number, maxRows: number) => string[];
+export declare const panelLeadOf: (s: PanelState) => string;
+export declare const panelStatusOf: (s: PanelState) => string;
+export declare const panelAffordanceOf: (s: PanelState) => string;
+/** The ask's PanelView. The dock-less fallback question is HONEST: a
+ *  terminal without a panel cannot walk options, so it says the ask is
+ *  being declined rather than pretending y/n answered it. */
+export declare function askView(spec: AskSpec): PanelView;
+export type { AskAnswer, AskOption, AskQuestion, AskResult, AskRuntime, AskSpec };

package/dist/ask-panel.js

@@ -0,0 +1,276 @@
+/**
+ * KC3.5 — the ask view: the model asks the human a real question.
+ *
+ * The W21 approval panel generalizes rather than duplicates. An ask is a
+ * PanelView carrying `ask`, so it rides the EXISTING panel slot: the
+ * compositor's live region, the input row's lead, the status/affordance
+ * pair, and — the part that matters — the editor's buffer stash/restore
+ * and its key precedence (the panel owns the keys; the menu, the history
+ * walk and the @ picker never open under it).
+ *
+ * This module owns three things and nothing else:
+ *
+ *   1. the ROWS — the question, the ‹ n/m › counter, the numbered
+ *      options with their descriptions and selection marks, the
+ *      type-your-own line;
+ *   2. the pure REDUCER — a key plus a state gives the next state (and,
+ *      when the walk ends, the result). No I/O, no editor internals: the
+ *      editor feeds it keys and renders what comes back, which is what
+ *      makes the whole interaction unit-testable without a terminal;
+ *   3. the DISPATCHERS — panelBlockRows/panelLead/panelStatus/
+ *      panelAffordance re-exported with the ask branch folded in, so the
+ *      compositor and the editor change ONE import line between them and
+ *      the panel slot itself stays exactly as W21 built it.
+ *
+ * What is deliberately NOT here (the round's stop clauses): no partial
+ * answer durability (a crash re-presents the WHOLE call — per-toggle
+ * durability would need a new durable mechanism), no "chat about this"
+ * hand-off, no timeout and no countdown.
+ */
+import { panelAffordance as basePanelAffordance, panelBlockRows as basePanelBlockRows, panelLead as basePanelLead, panelLeadPlain as basePanelLeadPlain, panelStatus as basePanelStatus, } from "./approval-panel.js";
+import { cutLine } from "@vincemakes/kiso-tui-cells/components";
+import { escapeTerminal, palette } from "./render.js";
+/** The schema's own bounds — the registry refuses anything outside them
+ *  (extensions/ask validates; these are the numbers it validates to). */
+export const ASK_MAX_QUESTIONS = 4;
+export const ASK_MIN_OPTIONS = 2;
+export const ASK_MAX_OPTIONS = 4;
+export const ASK_HEADER_CAP = 12;
+/** The ask panel's opening state: nothing picked, the cursor on the
+ *  first option of the first question. */
+export function askStart(spec) {
+    return {
+        qIndex: 0,
+        cursor: 0,
+        picks: spec.questions.map(() => []),
+        custom: spec.questions.map(() => null),
+        phase: "options",
+    };
+}
+/** The decline's honest record: every question with its options, so the
+ *  model reads what it did NOT get an answer to (frame 4). The SAME
+ *  list whether the human pressed esc on question one or question four
+ *  — the round declines the CALL, never half of it. */
+export function askDeclineList(spec) {
+    return spec.questions.map((q) => `${q.question} (${q.options.map((o) => o.label).join(", ")})`);
+}
+export function askDeclineAll(spec) {
+    return { declined: askDeclineList(spec) };
+}
+/** The answers collected so far, in the tool_result's own shapes: a
+ *  typed answer wins over the picks (the human typed it last), a
+ *  multi-select question yields `choices`, a single one `choice`. */
+export function askAnswers(spec, state) {
+    return spec.questions.map((q, i) => {
+        const typed = state.custom[i];
+        if (typed !== null && typed !== undefined && typed !== "")
+            return { q: q.question, custom: typed };
+        const picked = (state.picks[i] ?? []).map((n) => q.options[n]?.label ?? "");
+        return q.multiSelect === true ? { q: q.question, choices: picked } : { q: q.question, choice: picked[0] ?? "" };
+    });
+}
+/** Whether the CURRENT question has something to submit — a pick or a
+ *  typed answer. Enter on an empty question is a no-op: the panel never
+ *  invents an answer, and never silently skips one. */
+function answered(state, i) {
+    const typed = state.custom[i];
+    return (state.picks[i] ?? []).length > 0 || (typed !== null && typed !== undefined && typed !== "");
+}
+/** Advance past the current question — the next one, or the end. */
+function advance(spec, state) {
+    const next = state.qIndex + 1;
+    if (next >= spec.questions.length)
+        return { state, result: { answers: askAnswers(spec, state) } };
+    return { state: { ...state, qIndex: next, cursor: 0, phase: "options" } };
+}
+function toggle(state, option, multi) {
+    const current = state.picks[state.qIndex] ?? [];
+    const next = multi
+        ? current.includes(option)
+            ? current.filter((n) => n !== option)
+            : [...current, option].sort((a, b) => a - b)
+        : [option];
+    const picks = state.picks.map((p, i) => (i === state.qIndex ? next : p));
+    // a pick supersedes a typed answer for the same question — one
+    // question, one answer, and the human's last gesture is the one.
+    const custom = state.custom.map((c, i) => (i === state.qIndex ? null : c));
+    return { ...state, picks, custom, cursor: option };
+}
+/**
+ * The pure key reducer. `key` is a single logical key: a digit "1".."4",
+ * "space", "up"/"down", "left" (walk back), "enter", "t" (type your own),
+ * or "esc". The custom phase's TEXT is not routed here — the editor owns
+ * the buffer exactly as it does for the rule-input phase, and hands the
+ * committed line to `askCommitCustom`.
+ */
+export function askKey(spec, state, key) {
+    const q = spec.questions[state.qIndex];
+    const multi = q.multiSelect === true;
+    if (state.phase === "custom") {
+        // esc backs out of the typing line; enter is the editor's (it
+        // carries the text and calls askCommitCustom).
+        if (key === "esc")
+            return { state: { ...state, phase: "options" } };
+        return { state };
+    }
+    if (key === "esc")
+        return { state, result: askDeclineAll(spec) };
+    if (key === "t")
+        return { state: { ...state, phase: "custom" } };
+    if (key === "left")
+        return { state: state.qIndex === 0 ? state : { ...state, qIndex: state.qIndex - 1, cursor: 0 } };
+    if (key === "up")
+        return { state: { ...state, cursor: Math.max(0, state.cursor - 1) } };
+    if (key === "down")
+        return { state: { ...state, cursor: Math.min(q.options.length - 1, state.cursor + 1) } };
+    if (key === "enter")
+        return answered(state, state.qIndex) ? advance(spec, state) : { state };
+    // SPACE selects at the cursor and NEVER commits — in either mode. It
+    // used to answer-and-advance a single-select question, which made a
+    // stray space (the most pressable key there is) an instant answer of
+    // whatever the cursor happened to be on. Enter and the digits are the
+    // only gestures that commit; space is how you point at something.
+    if (key === "space")
+        return { state: toggle(state, state.cursor, multi) };
+    const digit = Number.parseInt(key, 10);
+    if (Number.isInteger(digit) && digit >= 1 && digit <= q.options.length) {
+        const next = toggle(state, digit - 1, multi);
+        // single-select answers AND advances — the fast path a human
+        // expects; multi-select toggles and waits for enter.
+        return multi ? { state: next } : advance(spec, next);
+    }
+    return { state };
+}
+/** The typed answer commits: it becomes THE answer for this question
+ *  (clearing its picks) and the walk advances. An empty line is a
+ *  no-op back to the options — nothing is recorded. */
+export function askCommitCustom(spec, state, text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return { state: { ...state, phase: "options" } };
+    const custom = state.custom.map((c, i) => (i === state.qIndex ? trimmed : c));
+    const picks = state.picks.map((p, i) => (i === state.qIndex ? [] : p));
+    return advance(spec, { ...state, custom, picks, phase: "options" });
+}
+// ── the rows ─────────────────────────────────────────────────────────
+/** One option row: the number, the selection mark, the label, and the
+ *  description after an em dash. The row CUTS (never folds) — the
+ *  block's height is its row count, the W20 discipline. */
+function optionRow(o, n, picked, cursor, multi, W) {
+    const p = palette();
+    const mark = multi ? (picked ? "◉" : "◯") : picked ? "◉" : " ";
+    const head = `${cursor ? p.bold : ""} ${n} ${mark} ${escapeTerminal(o.label)}${p.reset}`;
+    const body = o.description === undefined ? "" : `${p.dim} — ${escapeTerminal(o.description)}${p.reset}`;
+    return cutLine(`${head}${body}`, Math.max(1, W - 2));
+}
+/** The ask block's rows — the question as the rule line, the header (or
+ *  the counter) as the title, the options as the body, and the
+ *  type-your-own line last. The shape is the W21 block's: gutter, rule,
+ *  title, divider, body, affordance, corner. */
+export function askBlockRows(view, state, W, maxRows) {
+    const p = palette();
+    const spec = view.ask;
+    const q = spec.questions[state.qIndex];
+    const multi = q.multiSelect === true;
+    const gutter = `${p.dim}│${p.reset} `;
+    const counter = spec.questions.length > 1 ? `${p.dim} ‹ ${state.qIndex + 1}/${spec.questions.length} ›${p.reset}` : "";
+    const rows = [];
+    rows.push(`${gutter}${cutLine(`${p.bold}${escapeTerminal(q.question)}${p.reset}${counter}`, Math.max(1, W - 2))}`);
+    const header = q.header === undefined ? "the question" : escapeTerminal(q.header.slice(0, ASK_HEADER_CAP));
+    rows.push(`${gutter}${cutLine(`${p.dim}${header}${p.reset}`, Math.max(1, W - 2))}`);
+    rows.push(cutLine(`${p.dim}─ ${multi ? "pick any — space toggles" : "pick one"} ─${p.reset}`, Math.max(1, W - 2)));
+    const picks = state.picks[state.qIndex] ?? [];
+    const body = q.options.map((o, i) => `${gutter}${optionRow(o, i + 1, picks.includes(i), state.cursor === i, multi, W)}`);
+    const typed = state.custom[state.qIndex];
+    body.push(`${gutter}${cutLine(typed === null || typed === undefined
+        ? `${p.dim} t   type your own answer${p.reset}`
+        : ` t ◉ ${escapeTerminal(typed)}`, Math.max(1, W - 2))}`);
+    // the bounded block: the options fold nothing and cut individually,
+    // so the cap drops whole rows with the W21 notice row.
+    const budget = Math.max(1, maxRows - 5);
+    if (body.length > budget) {
+        const kept = Math.max(0, budget - 1);
+        rows.push(...body.slice(0, kept));
+        rows.push(cutLine(`${p.dim}└ +${body.length - kept} more rows — the full question is in the event log${p.reset}`, Math.max(1, W - 2)));
+    }
+    else {
+        rows.push(...body);
+    }
+    rows.push(`${gutter}${p.dim}${askAffordance(state)}${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. */
+export function askAffordance(state) {
+    if (state.phase === "custom")
+        return "enter answers · esc backs out";
+    return state.qIndex > 0 ? "1-4 pick · t type · ← back · esc decline" : "1-4 pick · t type · esc decline";
+}
+/** The status row's left text — the ask's own line, with the walk. */
+export function askStatus(view, state) {
+    const total = view.ask.questions.length;
+    return total > 1 ? `▸ question ${state.qIndex + 1} of ${total}` : "▸ a question for you";
+}
+/** The input row's lead: the digit lead while picking, the typing lead
+ *  in the custom phase (the rule-input phase's shape, reused). */
+export function askLeadPlain(state) {
+    return state.phase === "custom" ? "your answer: " : "1-4> ";
+}
+// ── the dispatchers: the panel slot, with the ask branch folded in ────
+export function panelBlockRows(view, phase, sel, W, maxRows, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askBlockRows(view, ask, W, maxRows);
+    return basePanelBlockRows(view, phase, sel, W, maxRows);
+}
+export function panelLead(view, phase, sel, ask) {
+    const p = palette();
+    if (view.ask !== undefined && ask !== undefined)
+        return `${p.bold}${askLeadPlain(ask)}${p.reset}`;
+    return basePanelLead(view, phase, sel);
+}
+export function panelLeadPlain(view, phase, sel, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askLeadPlain(ask);
+    return basePanelLeadPlain(view, phase, sel);
+}
+export function panelStatus(view, phase, sel, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askStatus(view, ask);
+    return basePanelStatus(view, phase, sel);
+}
+export function panelAffordance(view, phase, sel, ask) {
+    if (view.ask !== undefined && ask !== undefined)
+        return askAffordance(ask);
+    return basePanelAffordance(view, phase, sel);
+}
+/** The whole panel state in one call — the compositor's four reads share
+ *  one source, so an ask can never render half as an approval. */
+export const panelRowsOf = (s, W, maxRows) => panelBlockRows(s.view, s.phase, s.sel, W, maxRows, s.ask);
+export const panelLeadOf = (s) => panelLead(s.view, s.phase, s.sel, s.ask);
+export const panelStatusOf = (s) => panelStatus(s.view, s.phase, s.sel, s.ask);
+export const panelAffordanceOf = (s) => panelAffordance(s.view, s.phase, s.sel, s.ask);
+// ── the view: what the human reads when the model asks ────────────────
+/** The ask's PanelView. The dock-less fallback question is HONEST: a
+ *  terminal without a panel cannot walk options, so it says the ask is
+ *  being declined rather than pretending y/n answered it. */
+export function askView(spec) {
+    const first = spec.questions[0];
+    return {
+        flavor: "simple",
+        name: "ask_user",
+        title: first.header ?? first.question,
+        speaker: "kiso",
+        statusText: "▸ a question for you",
+        args: { kind: "text", lines: askDeclineList(spec) },
+        fallbackQuestion: `⚠ ${escapeTerminal(first.question)} — this terminal cannot show the option panel; the question is declined `,
+        ask: spec,
+    };
+}

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

@@ -43,7 +43,7 @@
  * line-mode bytes byte-for-byte (the e2e guards them).
  */
 import { type MenuItem } from "./editor.js";
-import { type PanelState } from "./approval-panel.js";
+import type { PanelState } from "./approval-panel.js";
 import { type AtMatch } from "./at-picker.js";
 /** KC3 §4 — the @ picker's bound state (the editor's atState()). */
 export interface AtPanelState {
@@ -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[];