@vincemakes/kiso-tui 0.7.0 → 0.8.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,268 @@
+/**
+ * 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}`);
+    rows.push(`${p.dim}└ ${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/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 {

package/dist/compositor.js

@@ -45,7 +45,9 @@
 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";
+// 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 { bannerLines, escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, toolTarget } from "./render.js";
@@ -657,7 +659,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;
@@ -704,7 +706,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
@@ -778,7 +780,7 @@ export class Body {
             // 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);
@@ -865,7 +867,7 @@ export class Body {
             // 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;
@@ -1224,7 +1226,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

package/dist/editor.d.ts

@@ -23,7 +23,7 @@
  */
 import { charWidth, displayWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
-import { type PanelState, type PanelVerdict, type PanelView } from "./approval-panel.js";
+import type { PanelState, PanelVerdict, PanelView } from "./approval-panel.js";
 import { type AtItem, type AtMatch } from "./at-picker.js";
 export declare const PROMPT = "\u258C ";
 export declare const PROMPT_WIDTH: number;

package/dist/editor.js

@@ -26,7 +26,9 @@ import { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 // authority) — re-exported so the editor's public surface is unchanged.
 export { charWidth, displayWidth, widthOf };
 import { palette } from "./render.js";
-import { panelLead } from "./approval-panel.js";
+// KC3.5: the panel-slot dispatchers — the ask branch folded into the
+// W21 lead/rows, so this file keeps ONE panel and one key owner.
+import { askCommitCustom, askKey, askStart, panelLead } from "./ask-panel.js";
 import { AT_VISIBLE, atFilter } from "./at-picker.js";
 // TUI v4 #16d: the input row is the blue brick + the edit area — the
 // "you>" text is gone (the brick IS the prompt; the pipe path's readline
@@ -439,6 +441,7 @@ export class Editor {
             view,
             phase: "options",
             sel: 0,
+            ask: view.ask === undefined ? null : askStart(view.ask),
             amend: "yes",
             onCommit,
             stash: { chars: this.#chars, cursor: this.#cursor, scroll: this.#scroll },
@@ -463,7 +466,7 @@ export class Editor {
         const panel = this.#panel;
         if (panel === null)
             return null;
-        return { view: panel.view, phase: panel.phase, sel: panel.sel };
+        return { view: panel.view, phase: panel.phase, sel: panel.sel, ...(panel.ask === null ? {} : { ask: panel.ask }) };
     }
     enter() {
         if (this.#entered)
@@ -493,7 +496,7 @@ export class Editor {
         // W21: the panel's lead owns the row while up (the brick returns
         // when the panel closes).
         const panel = this.#panel;
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : `${p.bold}${PROMPT}${p.reset}`;
+        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel, panel.ask ?? undefined) : `${p.bold}${PROMPT}${p.reset}`;
         // W23: the ONE width authority — leadWidth(lead), the ANSI-stripped
         // visible width (the styled panel lead / the styled brick measure
         // the same as their plain text — a lead can never measure
@@ -520,6 +523,45 @@ export class Editor {
                 // text); ctrl-c still rides the SIGINT handler (which
                 // cancels the panel).
                 const panel = this.#panel;
+                // KC3.5: an ASK panel routes its own keys — the digits pick
+                // (single-select advances, multi toggles), space toggles at
+                // the cursor, `t` opens the type-your-own line (the
+                // rule-input phase's shape: the buffer is the editor's, so
+                // only esc and enter are intercepted while typing), esc
+                // declines the whole call. Everything else falls through to
+                // the ordinary editing chain below.
+                if (panel.ask !== null) {
+                    const typing = panel.ask.phase === "custom";
+                    if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
+                        this.#askStep("esc");
+                        i += 1;
+                        continue;
+                    }
+                    if (c === "\x0d" || c === "\x0a") {
+                        this.#askStep(typing ? "commit" : "enter");
+                        i += 1;
+                        continue;
+                    }
+                    if (!typing && (c === " " || (c !== undefined && c >= "1" && c <= "4") || c === "t" || c === "T")) {
+                        this.#askStep(c === " " ? "space" : c === "T" ? "t" : c);
+                        i += 1;
+                        continue;
+                    }
+                    // an ask at rest swallows stray PRINTABLE keys — the panel
+                    // owns them, and a typed "/" or "@" must not arm the menu
+                    // or the picker underneath. Two things are never
+                    // swallowed: the CSI/SS3 introducer, because ←/↑/↓ are
+                    // the ask's own keys and the parser below routes them
+                    // (the T-Q1 red), and the CONTROL characters, because
+                    // ctrl-c must still reach the SIGINT handler that
+                    // cancels the panel — W21's own rule, and what the T-Q6
+                    // race red caught: an abort with the panel up did
+                    // nothing at all.
+                    if (!typing && c !== undefined && c >= " " && c !== "\x7f") {
+                        i += 1;
+                        continue;
+                    }
+                }
                 if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
                     this.#panelEsc();
                     i += 1;
@@ -760,7 +802,10 @@ export class Editor {
             // panel owns the keys while up (↑↓ do nothing — the panel has no
             // ↑↓ role).
             if (this.#panel !== null) {
-                /* the panel owns the keys */
+                // W21: the panel owns the keys. KC3.5: an ask uses ↑↓ for
+                // the option cursor (the approval panel still has no ↑↓ role).
+                if (this.#panel.ask !== null && this.#panel.ask.phase === "options")
+                    this.#askStep(final === "A" ? "up" : "down");
             }
             else if (this.#menuOpen) {
                 if (final === "A")
@@ -798,7 +843,12 @@ export class Editor {
             this.#onRender();
         }
         else if (final === "D") {
-            this.#move(-1);
+            // KC3.5: ← walks the ask BACK a question (the ‹ n/m › walk); at
+            // question one it stays put — esc is the decline, never ←.
+            if (this.#panel?.ask != null && this.#panel.ask.phase === "options")
+                this.#askStep("left");
+            else
+                this.#move(-1);
         }
         else if (final === "C") {
             this.#move(1);
@@ -913,6 +963,33 @@ export class Editor {
         else if (panel.sel === 3)
             this.#panelClose({ action: "deny", reason: "" });
     }
+    /**
+     * KC3.5 — one ask key: the pure reducer decides, this method applies.
+     * The buffer is cleared on every phase change so the type-your-own
+     * line starts empty and its text never leaks back into the options
+     * (the rule-input phase's own discipline). A step that produced a
+     * RESULT closes the panel with it — the stash/restore is the W21
+     * path, identical for an answer and for a decline.
+     */
+    #askStep(key) {
+        const panel = this.#panel;
+        if (panel === null || panel.ask === null)
+            return;
+        const spec = panel.view.ask;
+        const before = panel.ask.phase;
+        const step = key === "commit" ? askCommitCustom(spec, panel.ask, this.line()) : askKey(spec, panel.ask, key);
+        panel.ask = step.state;
+        if (step.state.phase !== before) {
+            this.#chars = [];
+            this.#cursor = 0;
+            this.#scroll = 0;
+        }
+        if (step.result !== undefined) {
+            this.#panelClose({ action: "answers", result: step.result });
+            return;
+        }
+        this.#onRender();
+    }
     #panelClose(verdict) {
         const panel = this.#panel;
         if (panel === null)
@@ -1162,7 +1239,7 @@ export class Editor {
         // W23: the ONE width authority — leadWidth(lead) — the cap follows
         // the lead the editor itself renders (the panel lead when the panel
         // owns the keys, the brick otherwise): maxW = W − walls − lead.
-        const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel) : PROMPT;
+        const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel, this.#panel.ask ?? undefined) : PROMPT;
         const leadW = leadWidth(lead);
         const maxW = Math.max(1, W - leadW - 4); // W6: the box's walls (2+2) — the visible line fits the box's inner width; the "…" rides inside
         // KC1: the scroll is the CURSOR LINE's own offset — a single-line

package/dist/index.d.ts

@@ -14,3 +14,5 @@ export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResu
 export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.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";

package/dist/index.js

@@ -24,3 +24,10 @@ export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrusted
 // KC3 §3/§5: the @ file picker's pure half — the subsequence filter, the
 // deterministic rank, and the ONE cap the CLI's file source shares.
 export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun } from "./at-picker.js";
+// KC3.5 (the ask round): the ask view — the panel machinery generalized.
+// The cli composes the view and hands the answers to the tool; the keys,
+// the rows and the walk are the terminal layer's.
+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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui",
-  "version": "0.7.0",
+  "version": "0.8.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.7.0"
+    "@vincemakes/kiso-tui-cells": "0.8.0"
   }
 }