@vincemakes/kiso-tui 0.24.5 → 0.26.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { Body, Dock, CURSOR_MARKER, type BodyOptions } from "./compositor.js";
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, PICK_MAX, modePickView, modelPickView, pickAffordance, pickBlockRows, pickLeadPlain, type PickOption, type PickResult, type PickRuntime, type PickSpec, type PanelArgs, type PanelFlavor, type PanelPhase, deletionRiskHint, SAFER_BACK, SAFER_DEGRADED, SAFER_DEGRADED_TRUNCATED, saferDegradedNote, type SaferAnswer, type SaferFailure, type SaferOption, type SaferRuntime, panelOptions, type PanelOption, type PanelOptionKind, type PanelState, type PanelVerdict, type PanelView, } from "./approval-panel.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, currentGround, setGround, 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 { bannerLines, COLOR_OFF, COLOR_ON, currentGround, setGround, 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 "./lines.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
 export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus, type StatusMeter } from "./status.js";
 export { contextRows, contextUnavailableRows, type ContextLedger } from "./context-ledger.js";

package/dist/index.js

@@ -15,7 +15,7 @@ export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWi
 PICK_MAX, modePickView, modelPickView, pickAffordance, pickBlockRows, pickLeadPlain, deletionRiskHint, SAFER_BACK, SAFER_DEGRADED, SAFER_DEGRADED_TRUNCATED, saferDegradedNote, panelOptions, } from "./approval-panel.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, currentGround, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
+export { bannerLines, COLOR_OFF, COLOR_ON, currentGround, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./lines.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.

package/dist/{render.js → lines.js}

@@ -165,9 +165,9 @@ export function renderStatusLine(turn, usage, ctxRatio, faux = false) {
         return null;
     return `[turn ${turn} · ${parts.join(" · ")}]`;
 }
-/** R3d — the per-tool terms of a settled turn, in the fold line's own
- *  vocabulary (ROLLUP_NOUN plurals, zero terms dropped). One wording for
- *  "what a run did", wherever it is said. */
+/** R3d — the per-tool terms of a settled turn (`read 4 files · ran 1
+ *  shell command`, zero terms dropped). One wording for "what a run
+ *  did", wherever it is said. */
 function recapWork(byTool) {
     let reads = 0;
     let edits = 0;

package/dist/panel-input.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The approval / ask / pick PANEL's input controller — S5 (finding C10).
+ *
+ * The editor parses BYTES and owns the composer buffer; this controller
+ * owns the panel's STATE and answers KEYS. One key is handled by at most
+ * one band, in an order the editor keeps in one place: the panel first,
+ * then the session picker, then the composer's own bands. What the
+ * panel may do to the composer is the `BandHost` surface and nothing
+ * else: it types its amend reason, its custom ask answer and its custom
+ * pick into the composer, stashes the composer at open, restores it at
+ * close — that is the whole coupling, and it is visible here.
+ *
+ * DECLARED MOVE (S5, 2026-09-06): every method below stood in editor.ts
+ * — `#panelMove` … `#panelClose`, `beginPanel`, `cancelPanel`,
+ * `panelState`, the panel block of `feed()`, the ↑↓/← branches of `#csi`
+ * and the mouse hit. The bodies are the same; only the buffer access
+ * goes through the host.
+ */
+import { type PanelState, type PanelVerdict, type PanelView, type SaferAnswer } from "./approval-panel.js";
+/** The composer's buffer, as a band puts it aside and gets it back. */
+export interface BufferStash {
+    readonly chars: number[];
+    readonly cursor: number;
+    readonly scroll: number;
+}
+/** The composer, as a band controller is allowed to see it. Every
+ *  entry is something a panel or the session picker does to the
+ *  editor; nothing a band needs is reached any other way. */
+export interface BandHost {
+    /** The buffer as text. */
+    line(): string;
+    /** The buffer with its paste capsules expanded — the text that would leave the editor. */
+    expandPastes(line: string): string;
+    /** Empty the buffer: chars, cursor, scroll and the ↑↓ goal column. */
+    clear(): void;
+    /** Type one code point at the cursor. */
+    insert(cp: number): void;
+    /** Insert the buffer's newline — a pasted line break while a band is up. */
+    newline(): void;
+    stash(): BufferStash;
+    restore(s: BufferStash): void;
+    reflow(): void;
+    render(): void;
+    syncMouse(): void;
+    /** A panel opening closes the composer's own bands: the menu, the queue-pop mode, the @ picker. */
+    closeBands(): void;
+    /** The Enter that closed a panel must not also submit the restored buffer. */
+    swallowNextEnter(): void;
+}
+/** A key the editor has already parsed. `enter.crlf` says the bytes
+ *  were CR LF, so a consumed Enter is two bytes in a paste. */
+export type BandKey = {
+    kind: "esc";
+} | {
+    kind: "enter";
+    crlf: boolean;
+} | {
+    kind: "tab";
+} | {
+    kind: "char";
+    ch: string;
+};
+/** The option rows' place on screen, as the compositor reported it (TUI2-R3v2 ②). */
+export interface PanelRowSpan {
+    readonly top: number;
+    readonly count: number;
+    readonly first?: number;
+}
+export declare class PanelInput {
+    #private;
+    private readonly host;
+    constructor(host: BandHost);
+    up(): boolean;
+    /** W21: open the approval panel. The current buffer is stashed
+     *  (restored at close — commit AND cancel), the panel takes the
+     *  keys and the input row's lead, the composer's own bands close. */
+    begin(view: PanelView, onCommit: (v: PanelVerdict) => void, opts?: {
+        safer?: () => Promise<SaferAnswer>;
+    }): void;
+    /** W21: cancel the panel — the SIGINT path's pair to begin. */
+    cancel(): void;
+    /** W21: the compositor's bound view — the phase/selection while the
+     *  panel is up, null otherwise. */
+    state(): PanelState | null;
+    /**
+     * A parsed key while the panel is up. Returns the bytes it consumed,
+     * or null when the key falls through to the composer — the amend
+     * reason, a custom ask answer and a custom pick are typed into the
+     * composer through the editor's ordinary path, and a control byte
+     * the panel does not claim (ctrl+c, ctrl+z) keeps its meaning.
+     *
+     * The order is the one `feed()` kept: the pick flavour's keys, then
+     * the ask flavour's, then the keys every flavour shares.
+     */
+    feed(key: BandKey, pasting: boolean): number | null;
+    /** ↑↓ while the panel is up: the flavour's own walk. True when the
+     *  panel owned the key (the caller renders); false when no panel is
+     *  up. A phase without a list (asking) swallows the key. */
+    arrow(dir: "up" | "down"): boolean;
+    /** ← while an ask's option row is up walks the ask; otherwise the key is the composer's. */
+    left(): boolean;
+    /** TUI2-R3v2 ②: a left-button press on the option rows the
+     *  compositor placed. Outside the list — inert. */
+    click(span: PanelRowSpan | null | undefined, row: number | undefined): void;
+}

package/dist/panel-input.js

@@ -0,0 +1,468 @@
+/**
+ * The approval / ask / pick PANEL's input controller — S5 (finding C10).
+ *
+ * The editor parses BYTES and owns the composer buffer; this controller
+ * owns the panel's STATE and answers KEYS. One key is handled by at most
+ * one band, in an order the editor keeps in one place: the panel first,
+ * then the session picker, then the composer's own bands. What the
+ * panel may do to the composer is the `BandHost` surface and nothing
+ * else: it types its amend reason, its custom ask answer and its custom
+ * pick into the composer, stashes the composer at open, restores it at
+ * close — that is the whole coupling, and it is visible here.
+ *
+ * DECLARED MOVE (S5, 2026-09-06): every method below stood in editor.ts
+ * — `#panelMove` … `#panelClose`, `beginPanel`, `cancelPanel`,
+ * `panelState`, the panel block of `feed()`, the ↑↓/← branches of `#csi`
+ * and the mouse hit. The bodies are the same; only the buffer access
+ * goes through the host.
+ */
+import { PICK_MAX, panelOptions, saferDegradedNote, } from "./approval-panel.js";
+import { askCommitCustom, askKey, askOnCustomRow, askStart } from "./ask-panel.js";
+export class PanelInput {
+    host;
+    // W21: the panel state machine — the approval/trust panel owns the
+    // interaction while up: the digit/y/n/esc/tab routing, the rule
+    // input, the tab-amend feedback, the phase/selection the compositor
+    // renders. The menu never opens while a panel is up; the pre-panel
+    // buffer is stashed at open and restored at close (commit AND
+    // cancel) — the panel's rule/feedback text never leaks into the
+    // user's next turn.
+    #panel = null;
+    /** TUI2-R3v2 ③: the safer ask's generation. A panel the human escaped
+     *  must not be resurrected by a promise nobody is waiting for. */
+    #saferToken = 0;
+    constructor(host) {
+        this.host = host;
+    }
+    up() {
+        return this.#panel !== null;
+    }
+    /** W21: open the approval panel. The current buffer is stashed
+     *  (restored at close — commit AND cancel), the panel takes the
+     *  keys and the input row's lead, the composer's own bands close. */
+    begin(view, onCommit, opts) {
+        this.#panel = {
+            view,
+            phase: "options",
+            cursor: 0,
+            note: null,
+            safer: opts?.safer,
+            saferRun: null,
+            ask: view.ask === undefined ? null : askStart(view.ask),
+            pick: view.pick === undefined ? null : { cursor: 0, phase: "options" },
+            onCommit,
+            stash: this.host.stash(),
+        };
+        this.host.clear();
+        this.host.closeBands();
+        this.host.syncMouse();
+        this.host.render();
+    }
+    /** W21: cancel the panel — the SIGINT path's pair to begin. */
+    cancel() {
+        this.#close({ action: "cancel" });
+    }
+    /** W21: the compositor's bound view — the phase/selection while the
+     *  panel is up, null otherwise. */
+    state() {
+        const panel = this.#panel;
+        if (panel === null)
+            return null;
+        return {
+            view: panel.view,
+            phase: panel.phase,
+            cursor: panel.cursor,
+            ...(panel.note === null ? {} : { note: panel.note }),
+            ...(panel.saferRun === null ? {} : { safer: panel.saferRun }),
+            ...(panel.ask === null ? {} : { ask: panel.ask }),
+            ...(panel.pick === null ? {} : { pick: panel.pick }),
+        };
+    }
+    /**
+     * A parsed key while the panel is up. Returns the bytes it consumed,
+     * or null when the key falls through to the composer — the amend
+     * reason, a custom ask answer and a custom pick are typed into the
+     * composer through the editor's ordinary path, and a control byte
+     * the panel does not claim (ctrl+c, ctrl+z) keeps its meaning.
+     *
+     * The order is the one `feed()` kept: the pick flavour's keys, then
+     * the ask flavour's, then the keys every flavour shares.
+     */
+    feed(key, pasting) {
+        const panel = this.#panel;
+        if (panel === null)
+            return null;
+        const enterBytes = key.kind === "enter" && key.crlf ? 2 : 1;
+        if (panel.pick !== null) {
+            const typing = panel.pick.phase === "custom";
+            if (key.kind === "esc") {
+                this.#pickPanelEsc();
+                return 1;
+            }
+            if (key.kind === "enter") {
+                if (pasting) {
+                    this.host.newline();
+                    return enterBytes;
+                }
+                this.#pickPanelEnter();
+                return 1;
+            }
+            if (key.kind === "char") {
+                const c = key.ch;
+                if (!typing && c >= "1" && c <= "9") {
+                    this.#pickPanelDigit(Number(c) - 1);
+                    return 1;
+                }
+                if (!typing && (c === "t" || c === "T") && panel.view.pick?.typeHint !== undefined) {
+                    panel.pick = { cursor: panel.pick.cursor, phase: "custom" };
+                    this.host.clear();
+                    this.host.render();
+                    return 1;
+                }
+                if (!typing && c >= " " && c !== "\x7f")
+                    return 1;
+            }
+        }
+        if (panel.ask !== null) {
+            const typing = panel.ask.phase === "custom";
+            if (key.kind === "esc") {
+                this.#askStep("esc");
+                return 1;
+            }
+            if (key.kind === "enter") {
+                if (pasting) {
+                    this.host.newline();
+                    return enterBytes;
+                }
+                this.#askStep(typing ? "commit" : "enter");
+                return 1;
+            }
+            if (key.kind === "char") {
+                const c = key.ch;
+                if (askOnCustomRow(panel.view.ask, panel.ask) && c >= " " && c !== "\x7f") {
+                    this.#askStep("type");
+                    this.host.insert(c.codePointAt(0));
+                    this.host.render();
+                    return 1;
+                }
+                if (!typing && (c === " " || (c >= "1" && c <= "4") || c === "t" || c === "T")) {
+                    this.#askStep(c === " " ? "space" : c === "T" ? "t" : c);
+                    return 1;
+                }
+                if (!typing && c >= " " && c !== "\x7f")
+                    return 1;
+            }
+        }
+        if (key.kind === "esc") {
+            this.#panelEsc();
+            return 1;
+        }
+        if (key.kind === "tab") {
+            if (panel.phase === "options")
+                this.#panelTab();
+            return 1;
+        }
+        if (key.kind === "enter") {
+            if (pasting) {
+                this.host.newline();
+                return enterBytes;
+            }
+            this.#panelEnter();
+            return 1;
+        }
+        const c = key.ch;
+        if (panel.phase === "safer" && c >= "1" && c <= "9") {
+            this.#saferConfirm(Number(c) - 1);
+            return 1;
+        }
+        if (panel.phase === "asking" && c >= " " && c !== "\x7f")
+            return 1;
+        if (panel.phase === "options" && panel.ask === null && panel.pick === null && c >= "1" && c <= "9") {
+            this.#panelConfirm(Number(c) - 1);
+            return 1;
+        }
+        const optionsPhase = panel.pick === null && // a pick has no yes and no no
+            panel.phase === "options" && // the amend line is prose
+            (panel.ask === null || panel.ask.phase === "options"); // and so is a typed ask answer
+        if (optionsPhase && panel.ask === null) {
+            if (c === "y" || c === "Y") {
+                this.#panelConfirm(0);
+                return 1;
+            }
+            if (c === "n" || c === "N") {
+                this.#panelConfirm(panelOptions(panel.view).length - 1);
+                return 1;
+            }
+        }
+        return null;
+    }
+    /** ↑↓ while the panel is up: the flavour's own walk. True when the
+     *  panel owned the key (the caller renders); false when no panel is
+     *  up. A phase without a list (asking) swallows the key. */
+    arrow(dir) {
+        const panel = this.#panel;
+        if (panel === null)
+            return false;
+        if (panel.pick !== null && panel.pick.phase === "options") {
+            const n = Math.min(panel.view.pick.options.length, PICK_MAX);
+            const cur = panel.pick.cursor;
+            panel.pick = { cursor: dir === "up" ? Math.max(0, cur - 1) : Math.min(Math.max(0, n - 1), cur + 1), phase: "options" };
+        }
+        else if (panel.ask !== null && panel.ask.phase === "options")
+            this.#askStep(dir);
+        else if (panel.phase === "safer")
+            this.#saferMove(dir === "up" ? -1 : 1);
+        else if (panel.phase !== "asking")
+            this.#panelMove(dir === "up" ? -1 : 1);
+        return true;
+    }
+    /** ← while an ask's option row is up walks the ask; otherwise the key is the composer's. */
+    left() {
+        const panel = this.#panel;
+        if (panel?.ask == null || panel.ask.phase !== "options")
+            return false;
+        this.#askStep("left");
+        return true;
+    }
+    /** TUI2-R3v2 ②: a left-button press on the option rows the
+     *  compositor placed. Outside the list — inert. */
+    click(span, row) {
+        const panel = this.#panel;
+        if (panel === null || (panel.phase !== "options" && panel.phase !== "safer"))
+            return;
+        if (span == null || row === undefined || !Number.isFinite(row))
+            return;
+        const offset = row - span.top;
+        if (offset < 0 || offset >= span.count)
+            return; // outside the list — inert
+        if (panel.phase === "safer")
+            this.#saferConfirm(offset);
+        else
+            this.#panelConfirm((span.first ?? 0) + offset);
+    }
+    // ---- W21 / TUI2-R3v2 ①: the panel state machine ----
+    /** ↑↓ — the bar walks the list and STOPS at both ends. A list that
+     *  wraps makes the fastest gesture (hold ↓ to reach the bottom) into
+     *  a gamble about where you landed, and the bottom option here is the
+     *  denial. */
+    #panelMove(delta) {
+        const panel = this.#panel;
+        if (panel === null || panel.phase !== "options")
+            return;
+        const n = panelOptions(panel.view).length;
+        panel.cursor = Math.max(0, Math.min(n - 1, panel.cursor + delta));
+        this.host.render();
+    }
+    #panelConfirm(index) {
+        const panel = this.#panel;
+        if (panel === null || panel.phase !== "options")
+            return;
+        const options = panelOptions(panel.view);
+        const option = options[index];
+        if (option === undefined)
+            return; // a digit past the list is inert
+        panel.cursor = index;
+        switch (option.kind) {
+            case "allow":
+                this.#close({ action: "allow", reason: "" });
+                return;
+            case "rule":
+                this.#close({ action: "allow-rule", rule: panel.view.name });
+                return;
+            case "safer":
+                this.#panelSafer();
+                return;
+            case "deny":
+                if (panel.view.flavor === "approval")
+                    this.#panelAmend();
+                else
+                    this.#close({ action: "deny", reason: "" });
+                return;
+        }
+    }
+    /** TUI2-R3v2 ③: ask the caller for safer options. The panel shows
+     *  "asking" until the answer lands; a generation token guards the
+     *  landing so an escaped panel is never resurrected by it. */
+    #panelSafer() {
+        const panel = this.#panel;
+        if (panel === null)
+            return;
+        const ask = panel.safer;
+        panel.phase = "asking";
+        panel.note = null;
+        this.host.render();
+        const token = ++this.#saferToken;
+        const settle = (answer) => {
+            if (this.#panel !== panel || token !== this.#saferToken)
+                return;
+            const options = Array.isArray(answer) ? answer : null;
+            if (options === null || options.length === 0) {
+                panel.phase = "options";
+                panel.note = saferDegradedNote(answer);
+                panel.cursor = 0;
+                this.host.render();
+                return;
+            }
+            panel.phase = "safer";
+            panel.saferRun = { options, cursor: 0 };
+            this.host.render();
+        };
+        if (ask === undefined) {
+            settle(null); // no provider bound — the button says so rather than lying
+            return;
+        }
+        void Promise.resolve()
+            .then(ask)
+            .then(settle)
+            .catch(() => settle(null));
+    }
+    #saferConfirm(index) {
+        const panel = this.#panel;
+        if (panel === null || panel.saferRun === null)
+            return;
+        const { options } = panel.saferRun;
+        if (index === options.length) {
+            panel.phase = "options";
+            panel.saferRun = null;
+            panel.cursor = 0;
+            this.host.render();
+            return;
+        }
+        const chosen = options[index];
+        if (chosen === undefined)
+            return; // past the list — inert
+        this.#close({ action: "deny", reason: `run this instead: ${chosen.command}` });
+    }
+    #saferMove(delta) {
+        const panel = this.#panel;
+        if (panel === null || panel.saferRun === null)
+            return;
+        const last = panel.saferRun.options.length; // + the way-back row
+        panel.saferRun = { options: panel.saferRun.options, cursor: Math.max(0, Math.min(last, panel.saferRun.cursor + delta)) };
+        this.host.render();
+    }
+    /** The amend phase: the composer becomes the denial's reason. */
+    #panelAmend() {
+        const panel = this.#panel;
+        if (panel === null)
+            return;
+        panel.phase = "amend";
+        this.host.clear();
+        this.host.render();
+    }
+    #panelTab() {
+        const panel = this.#panel;
+        if (panel === null || panel.view.flavor !== "approval")
+            return;
+        panel.cursor = panelOptions(panel.view).length - 1;
+        this.#panelAmend();
+    }
+    /** Esc walks BACK one phase before it cancels: a safer list or a
+     *  pending ask returns to the options, an amend line returns to the
+     *  options, and only the options phase itself cancels. */
+    #panelEsc() {
+        const panel = this.#panel;
+        if (panel === null)
+            return;
+        if (panel.phase === "safer" || panel.phase === "asking") {
+            this.#saferToken += 1;
+            panel.phase = "options";
+            panel.saferRun = null;
+            panel.cursor = 0;
+            this.host.render();
+            return;
+        }
+        if (panel.phase !== "options") {
+            panel.phase = "options";
+            this.host.clear();
+            this.host.render();
+            return;
+        }
+        this.#close({ action: "cancel" });
+    }
+    #panelEnter() {
+        const panel = this.#panel;
+        if (panel === null)
+            return;
+        if (panel.phase === "amend") {
+            this.#close({ action: "deny", reason: this.host.line() });
+            return;
+        }
+        if (panel.phase === "safer" && panel.saferRun !== null) {
+            this.#saferConfirm(panel.saferRun.cursor);
+            return;
+        }
+        if (panel.phase === "asking")
+            return; // nothing to confirm yet
+        this.#panelConfirm(panel.cursor);
+    }
+    /** KC3.5: one step of the ask's walk; a phase change empties the
+     *  composer (the custom answer's text field), a result closes. */
+    #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.host.expandPastes(this.host.line())) : askKey(spec, panel.ask, key);
+        panel.ask = step.state;
+        if (step.state.phase !== before)
+            this.host.clear();
+        if (step.result !== undefined) {
+            this.#close({ action: "answers", result: step.result });
+            return;
+        }
+        this.host.render();
+    }
+    #pickPanelDigit(index) {
+        const panel = this.#panel;
+        if (panel === null || panel.pick === null)
+            return;
+        if (index < 0 || index >= Math.min(panel.view.pick.options.length, PICK_MAX))
+            return;
+        panel.pick = { cursor: index, phase: "options" };
+        this.host.render();
+    }
+    #pickPanelEnter() {
+        const panel = this.#panel;
+        if (panel === null || panel.pick === null)
+            return;
+        if (panel.pick.phase === "custom") {
+            const line = this.host.line().trim();
+            if (line === "")
+                return;
+            this.#close({ action: "picked", result: { custom: line } });
+            return;
+        }
+        if (panel.view.pick.options.length === 0)
+            return; // nothing to take
+        this.#close({ action: "picked", result: { index: panel.pick.cursor } });
+    }
+    #pickPanelEsc() {
+        const panel = this.#panel;
+        if (panel === null || panel.pick === null)
+            return;
+        if (panel.pick.phase === "custom") {
+            panel.pick = { cursor: panel.pick.cursor, phase: "options" };
+            this.host.clear();
+            this.host.render();
+            return;
+        }
+        this.#close({ action: "cancel" });
+    }
+    /** Close: the state is cleared FIRST, the stashed composer comes
+     *  back, the Enter that closed the panel is swallowed, and only then
+     *  does the verdict reach the caller — so a caller that re-enters
+     *  (a second panel, a run that resumes) never sees the closing one. */
+    #close(verdict) {
+        const panel = this.#panel;
+        if (panel === null)
+            return;
+        this.#panel = null;
+        this.host.syncMouse();
+        this.host.swallowNextEnter();
+        this.host.restore(panel.stash);
+        this.host.render();
+        panel.onCommit(verdict);
+    }
+}

package/dist/pick-input.d.ts

@@ -0,0 +1,34 @@
+import type { BandHost } from "./panel-input.js";
+import { type SessionCardView, type SessionPickState } from "./session-picker.js";
+export declare class PickInput {
+    #private;
+    private readonly host;
+    constructor(host: Pick<BandHost, "line" | "clear" | "reflow" | "render" | "syncMouse">);
+    up(): boolean;
+    /** Open the picker on a bound card source. The composer is cleared
+     *  (the buffer becomes the filter query) and `onPick` receives the
+     *  chosen id — or null when the human leaves without picking, which
+     *  is a first-class outcome and not an error. */
+    begin(cards: () => readonly SessionCardView[], onPick: (id: string | null) => void): void;
+    /** The picker's state, derived: the full card list (the id column
+     *  measures over ALL of them, so the columns never jump), the
+     *  filtered matches, and the selection CLAMPED at read time — the
+     *  same correction discipline the @ picker uses, for the same
+     *  reason: narrowing can only ever shrink the list. */
+    state(): SessionPickState | null;
+    /** The band's height estimate: the header + the windowed rows (or
+     *  the one "no match" row) + the counter. */
+    rows(): number;
+    /** ↑↓: the selection walks the matches and stops at both ends. True
+     *  when the picker owned the key (the caller renders). */
+    arrow(dir: "up" | "down"): boolean;
+    /** Close and hand the verdict back. The callback fires AFTER the
+     *  state is cleared, so a caller that re-enters (a second picker, a
+     *  session that starts) never sees the closing picker's rows. */
+    close(id: string | null): void;
+    /** Enter takes the SELECTED session. An empty match set takes
+     *  nothing and leaves the picker up: a picker that invented a pick
+     *  when the query matched nothing would resume the wrong session,
+     *  which is the one failure this surface must never have. */
+    accept(): void;
+}