@sigrun/tui 0.0.0-stage → 0.1.1

package/dist/ui/conversation-pane.js

@@ -0,0 +1,463 @@
+/**
+ * The conversation pane (Task 6; restyled in C2, UI refresh): renders a
+ * `ConversationViewWire`'s entries as TURNS (B1's `groupTurns`) instead
+ * of raw entries — a user turn is the accent `▎` bar on every line, an
+ * assistant turn is prose plus ONE collapsible activity line
+ * (`▸ Thinking · 2 tools`; `▾` when open) that unfolds into the thinking
+ * text and `✓ tool  preview` rows (`✗` error, `·` no result yet — the
+ * wire carries no per-tool running marker, so `·` covers pending too).
+ * `pi.compaction` renders the centred `── context compacted ──` divider. The `[tool]`/`[thinking]` tags of
+ * the entry-era pane are gone.
+ *
+ * Task 2c: an EXPANDED input (`/skill:name`, a prompt template) is one
+ * entry (`sigrun.user.expanded`, `data {typed, command}`, the expanded
+ * text on `model`) that groups as a USER turn — the body is the TYPED
+ * command with a dim `▸ expanded from /name` chip line that folds the
+ * full admitted text open/closed (closed by default).
+ *
+ * Focus (the C3 action layer's seam): `focusIndex` names the focused
+ * turn (`undefined` = none — the ScrollView follows the end), the
+ * focused turn's FIRST line carries the `surface2` background and a `›`
+ * gutter marker; `lineRangeOf` reports the turn's line offsets from the
+ * last render for `ScrollView.scrollTo`; `textOf`/`entryIdOf` are the
+ * copy payload and wire identity of a turn.
+ *
+ * Mouse (additive — the pane is fully keyboard-usable): each activity
+ * line is a `MouseRegion` whose left click toggles the fold; a click on
+ * a turn's body sets the focus to that turn.
+ *
+ * The SSE contract (Task 4): every snapshot/frame is a FULL revision, so
+ * {@link showView} REPLACES the rendered state wholesale. Folds and
+ * focus are keyed by turn INDEX within the latest view — a replacement
+ * re-derives the turns and keeps the index-based state (the action
+ * layer owns re-targeting when the structure shifts).
+ *
+ * Unknown entry kinds render a fail-visible fallback naming the kind
+ * (the webui's rule — a new server-side kind must never vanish silently).
+ *
+ * Error/notice lines (Task 7): the composer surfaces its immediate
+ * failures as `[error]`/`[notice]` rows. They are NOT stream state, so
+ * {@link showView}'s wholesale replacement preserves them (fix wave F4:
+ * the shell discards them on every conversation swap via
+ * {@link ConversationPane.clearNotices}).
+ */
+import { Container, Markdown, MouseRegion, Text, } from "@earendil-works/pi-tui";
+import { activityLabel, expandedUserEntry, groupTurns, } from "@sigrun/shared/turns";
+import { plainTuiTheme } from "../theme.js";
+/**
+ * The message's text: string content as-is, or its text blocks joined
+ * with a blank line (the webui `messageText` rule, mirrored).
+ */
+function messageText(message) {
+    const content = message.content;
+    if (typeof content === "string")
+        return content;
+    if (content === undefined)
+        return "";
+    return content
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n\n");
+}
+/** The message's non-text/non-thinking parts (uploads), as path markers. */
+function attachmentMarkers(message) {
+    const content = message.content;
+    if (typeof content === "string" || content === undefined)
+        return [];
+    return content
+        .filter((block) => block.type !== "text" && block.type !== "thinking")
+        .map((block) => `[${block.type ?? "part"}: ${block.path ?? "?"}]`);
+}
+/** A turn's fallback body (an `other` kind's text), if any. */
+function entryText(entry) {
+    return (entry.model ?? [])
+        .map((message) => messageText(message))
+        .filter((part) => part !== "")
+        .join(" ");
+}
+/** A user entry's model-facing text (message texts + upload markers) — the
+ *  plain-turn body, and the EXPANDED text an expanded turn's chip reveals. */
+function userModelText(entry) {
+    const parts = (entry.model ?? []).flatMap((message) => [
+        messageText(message),
+        ...attachmentMarkers(message),
+    ]);
+    return parts.filter((part) => part !== "").join("\n");
+}
+/** The markdown theme rides the TuiTheme's token colours. */
+function markdownTheme(theme) {
+    return {
+        heading: (text) => theme.bold(theme.fg("accent")(text)),
+        link: theme.fg("accent"),
+        linkUrl: theme.dim,
+        code: theme.fg("code"),
+        codeBlock: theme.fg("code"),
+        codeBlockBorder: theme.fg("border"),
+        quote: theme.italic,
+        quoteBorder: theme.fg("border"),
+        hr: theme.fg("border"),
+        listBullet: theme.fg("accent"),
+        bold: theme.bold,
+        italic: theme.italic,
+        strikethrough: (text) => text,
+        underline: (text) => text,
+    };
+}
+/** Pad/centre the compaction divider to the render width. */
+function compactionLine(theme) {
+    return new (class {
+        render(width) {
+            const label = "── context compacted ──";
+            const pad = Math.max(0, Math.floor((width - label.length) / 2));
+            return [theme.dim(`${" ".repeat(pad)}${label}`)];
+        }
+        invalidate() { }
+    })();
+}
+function noticeComponent(notice) {
+    return new Text(`[${notice.kind}] ${notice.text}`, 0, 0);
+}
+/** The notice backlog cap (fix wave A5 — most recent win). */
+const MAX_NOTICES = 10;
+/**
+ * A one-line render slot whose text is painted by the owner each frame
+ * (pi-tui's `Text` drops whitespace-only text and caches by content —
+ * neither fits a line whose text changes under a `MouseRegion`).
+ */
+class RenderSlot {
+    paint = () => "";
+    render(width) {
+        return [this.paint(width)];
+    }
+    invalidate() { }
+}
+/** The blank separator between turns. */
+const TURN_GAP = 1;
+export class ConversationPane {
+    #container = new Container();
+    #theme;
+    #markdownTheme;
+    #notices = [];
+    /** The notices' mounted components, aligned with `#notices`. */
+    #noticeComponents = [];
+    #turns = [];
+    #focus;
+    /** Fold state by turn index (assistant turns only fold). */
+    #open = new Set();
+    /** Line spans from the last render, aligned with `#turns`. */
+    #ranges = [];
+    /** The mounted turn records, aligned with `#turns`. */
+    #mounted = [];
+    constructor(options) {
+        this.#theme = options?.theme ?? plainTuiTheme();
+        this.#markdownTheme = markdownTheme(this.#theme);
+    }
+    /** The current view's turns (B1 grouping), in render order. */
+    turns() {
+        return this.#turns;
+    }
+    /** The focused turn index; `undefined` = none (follow the end). */
+    get focusIndex() {
+        return this.#focus;
+    }
+    /** Focus a turn (or clear with `undefined`); repaints the marker. */
+    setFocus(index) {
+        if (index !== undefined && (index < 0 || index >= this.#turns.length)) {
+            return;
+        }
+        if (index === this.#focus)
+            return;
+        this.#focus = index;
+        this.#container.invalidate();
+    }
+    /** Open/close an assistant turn's activity fold — or an expanded user
+     *  turn's chip disclosure (Task 2c: the full admitted text hides behind
+     *  the `expanded from /name` line, same fold state, same seam). */
+    toggleFold(index) {
+        const turn = this.#turns[index];
+        if (turn === undefined)
+            return;
+        const foldable = turn.kind === "assistant" ||
+            (turn.kind === "user" && expandedUserEntry(turn.entry) !== undefined);
+        if (!foldable)
+            return;
+        if (this.#open.has(index)) {
+            this.#open.delete(index);
+        }
+        else {
+            this.#open.add(index);
+        }
+        this.#rebuild();
+    }
+    /**
+     * The turn's line offsets from the last render (for
+     * `ScrollView.scrollTo`): `start` is the turn's first line, `end` the
+     * first line after it. Undefined before a render or out of range.
+     */
+    lineRangeOf(index) {
+        return this.#ranges[index];
+    }
+    /** The turn's markdown source (the copy payload). */
+    textOf(index) {
+        const turn = this.#turns[index];
+        if (turn === undefined)
+            return "";
+        switch (turn.kind) {
+            case "user": {
+                // An expanded turn copies the TYPED command (what the user
+                // wrote — re-submitting it re-expands server-side).
+                const expanded = expandedUserEntry(turn.entry);
+                if (expanded !== undefined)
+                    return expanded.typed;
+                return userModelText(turn.entry);
+            }
+            case "assistant":
+                return turn.text;
+            case "other":
+                return entryText(turn.entry);
+        }
+    }
+    /** The turn's wire identity: the user entry id / assistant lastEntryId. */
+    entryIdOf(index) {
+        const turn = this.#turns[index];
+        if (turn === undefined)
+            return -1;
+        switch (turn.kind) {
+            case "user":
+                return turn.entry.id;
+            case "assistant":
+                return turn.lastEntryId;
+            case "other":
+                return turn.entry.id;
+        }
+    }
+    /**
+     * Replace the pane with the projection of `wire` (the SSE rule: a full
+     * revision replaces; a reconnect's snapshot subsumes missed frames).
+     * Composer notices are not stream state: they re-render after the
+     * turns.
+     */
+    showView(wire) {
+        this.#turns = groupTurns(wire.entries);
+        if (this.#focus !== undefined && this.#focus >= this.#turns.length) {
+            this.#focus = undefined;
+        }
+        this.#rebuild();
+    }
+    /** Append an `[error]` line (a failed composer action's surface). */
+    showError(text) {
+        this.#appendNotice({ kind: "error", text });
+    }
+    /** Append a `[notice]` line (an outcome, e.g. an abort that settled). */
+    showNotice(text) {
+        this.#appendNotice({ kind: "notice", text });
+    }
+    /**
+     * Discard all composer-surfaced lines (fix wave F4): the shell calls
+     * this on every conversation swap so a stale error never renders in
+     * the new conversation.
+     */
+    clearNotices() {
+        if (this.#notices.length === 0)
+            return;
+        this.#notices.length = 0;
+        for (const component of this.#noticeComponents.splice(0)) {
+            this.#container.removeChild(component);
+        }
+        this.#container.invalidate();
+    }
+    #appendNotice(notice) {
+        this.#notices.push(notice);
+        const component = noticeComponent(notice);
+        this.#noticeComponents.push(component);
+        this.#container.addChild(component);
+        while (this.#notices.length > MAX_NOTICES) {
+            this.#notices.shift();
+            const oldest = this.#noticeComponents.shift();
+            if (oldest === undefined)
+                break;
+            this.#container.removeChild(oldest);
+        }
+        this.#container.invalidate();
+    }
+    /** Rebuild the container from the current turns + folds + notices. */
+    #rebuild() {
+        this.#container.clear();
+        this.#noticeComponents.length = 0;
+        this.#mounted = this.#turns.map((turn, index) => this.#mountTurn(turn, index));
+        for (const mounted of this.#mounted) {
+            for (const component of mounted.components) {
+                this.#container.addChild(component);
+            }
+            this.#container.addChild(new RenderSlot()); // turn gap
+        }
+        for (const notice of this.#notices) {
+            const component = noticeComponent(notice);
+            this.#noticeComponents.push(component);
+            this.#container.addChild(component);
+        }
+        this.#container.invalidate();
+    }
+    /** Project one turn into its components (mouse regions included). */
+    #mountTurn(turn, index) {
+        const components = [];
+        const focusThis = () => {
+            this.setFocus(index);
+            return { handled: true };
+        };
+        const body = (component) => new MouseRegion(component, (event) => event.type === "click" && event.button === "left"
+            ? focusThis()
+            : undefined);
+        switch (turn.kind) {
+            case "user": {
+                const expanded = expandedUserEntry(turn.entry);
+                if (expanded !== undefined) {
+                    // The expanded turn (Task 2c): the TYPED command is the body
+                    // (the accent bar still marks it a user turn); a dim chip line
+                    // folds the full admitted text — closed by default, or
+                    // `/skill:greet hej` would dump the whole skill body.
+                    components.push(body(new Markdown(expanded.typed, 0, 0, this.#markdownTheme)));
+                    const slot = new RenderSlot();
+                    slot.paint = () => this.#theme.dim(`${this.#open.has(index) ? "▾" : "▸"} expanded from /${expanded.command ?? "…"}`);
+                    components.push(new MouseRegion(slot, (event) => {
+                        if (event.type === "click" && event.button === "left") {
+                            this.toggleFold(index);
+                            return { handled: true };
+                        }
+                        return undefined;
+                    }));
+                    if (this.#open.has(index)) {
+                        for (const line of userModelText(turn.entry).split("\n")) {
+                            components.push(new Text(this.#theme.dim(line), 0, 0));
+                        }
+                    }
+                    break;
+                }
+                const text = this.textOf(index);
+                if (text !== "") {
+                    components.push(body(new Markdown(text, 0, 0, this.#markdownTheme)));
+                }
+                break;
+            }
+            case "assistant": {
+                if (turn.text.trim() !== "") {
+                    components.push(body(new Markdown(turn.text, 0, 0, this.#markdownTheme)));
+                }
+                const label = activityLabel(turn);
+                if (label !== "") {
+                    // The slot renders one line; the fold marker + label are
+                    // painted per frame (the fold state changes after mount, and
+                    // a Text's content cache would pin the stale marker).
+                    const slot = new RenderSlot();
+                    slot.paint = () => this.#theme.dim(`${this.#open.has(index) ? "▾" : "▸"} ${label}`);
+                    components.push(new MouseRegion(slot, (event) => {
+                        if (event.type === "click" && event.button === "left") {
+                            this.toggleFold(index);
+                            return { handled: true };
+                        }
+                        return undefined;
+                    }));
+                    if (this.#open.has(index)) {
+                        for (const thinking of turn.thinking) {
+                            if (thinking.trim() === "")
+                                continue;
+                            components.push(new Text(this.#theme.dim(this.#theme.italic(thinking)), 0, 0));
+                        }
+                        for (const tool of turn.tools) {
+                            const glyph = tool.isError
+                                ? "✗"
+                                : tool.resultEntryId === undefined
+                                    ? "·"
+                                    : "✓";
+                            const preview = tool.preview === "" ? "" : `  ${tool.preview}`;
+                            const row = `${glyph} ${tool.name}${preview}`;
+                            components.push(new Text(tool.isError ? this.#theme.fg("muted")(row) : row, 0, 0));
+                        }
+                    }
+                }
+                break;
+            }
+            case "other": {
+                if (turn.entry.kind === "pi.compaction") {
+                    components.push(compactionLine(this.#theme));
+                    break;
+                }
+                const text = entryText(turn.entry);
+                if (turn.entry.kind === "pi.system") {
+                    if (text !== "")
+                        components.push(new Text(text, 0, 0));
+                }
+                else {
+                    // Fail visible (the webui rule): name the kind plus any text.
+                    const suffix = text === "" ? "" : ` — ${text}`;
+                    components.push(new Text(`unsupported entry kind: ${turn.entry.kind}${suffix}`, 0, 0));
+                }
+                break;
+            }
+        }
+        return { start: 0, end: 0, components, heights: [] };
+    }
+    render(width) {
+        const lines = this.#container.render(width);
+        this.#recordRanges(lines, width);
+        return this.#decorate(lines, width);
+    }
+    /**
+     * Record each turn's line span from the render: every turn is followed
+     * by one blank gap line (see `#rebuild`), so heights + TURN_GAP walk
+     * the offsets deterministically.
+     */
+    #recordRanges(_lines, width) {
+        const ranges = [];
+        let offset = 0;
+        for (const [index, mounted] of this.#mounted.entries()) {
+            let height = 0;
+            mounted.heights.length = 0;
+            for (const component of mounted.components) {
+                const componentHeight = component.render(width).length;
+                mounted.heights.push(componentHeight);
+                height += componentHeight;
+            }
+            mounted.start = offset;
+            mounted.end = offset + height;
+            ranges.push({ start: mounted.start, end: mounted.end });
+            offset += height + TURN_GAP;
+        }
+        this.#ranges = ranges;
+    }
+    /**
+     * Apply the focus + user-bar chrome: the focused turn's FIRST line
+     * gets the `surface2` background and the `›` gutter marker; every line
+     * of a user turn carries the accent `▎` bar. The two are independent —
+     * a focused user turn's first line composes `› ▎ …` on surface2.
+     */
+    #decorate(lines, width) {
+        const out = [...lines];
+        for (const [index, mounted] of this.#mounted.entries()) {
+            const turn = this.#turns[index];
+            if (turn === undefined)
+                continue;
+            const focused = index === this.#focus;
+            const bar = turn.kind === "user"
+                ? `${this.#theme.fg("accent")("▎")} `
+                : "";
+            for (let line = mounted.start; line < mounted.end; line++) {
+                const original = out[line] ?? "";
+                if (line === mounted.start && focused) {
+                    const marked = `› ${bar}${original}`;
+                    out[line] = this.#theme.bg("surface2")(marked + " ".repeat(Math.max(0, width - marked.length)));
+                }
+                else if (turn.kind === "user") {
+                    out[line] = `${bar}${original}`;
+                }
+                else if (focused) {
+                    out[line] = `  ${original}`;
+                }
+            }
+        }
+        return out;
+    }
+    invalidate() {
+        this.#container.invalidate();
+    }
+}

package/dist/ui/help.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The key reference overlay (Task C5, UI refresh): `showHelp` mounts a
+ * centred overlay listing the active keymap's `describe()` table in two
+ * columns. Esc, `q`, or the keymap's own help key (`?` standard, `C-h`
+ * emacs, `g?` vim — a two-key sequence, matched via a pending-`g` flag)
+ * closes it. Built on the same `showOverlay` mechanism as C3's picker.
+ */
+import { type TUI } from "@earendil-works/pi-tui";
+import type { Keymap } from "../keymaps/types.js";
+export interface HelpOptions {
+    /** Fires on close so the app can clear its overlayOpen flag. */
+    readonly onClose?: () => void;
+}
+/** Open the key reference overlay for `keymap`; Esc/q/help-key closes. */
+export declare function showHelp(tui: TUI, keymap: Keymap, options?: HelpOptions): void;

package/dist/ui/help.js

@@ -0,0 +1,80 @@
+/**
+ * The key reference overlay (Task C5, UI refresh): `showHelp` mounts a
+ * centred overlay listing the active keymap's `describe()` table in two
+ * columns. Esc, `q`, or the keymap's own help key (`?` standard, `C-h`
+ * emacs, `g?` vim — a two-key sequence, matched via a pending-`g` flag)
+ * closes it. Built on the same `showOverlay` mechanism as C3's picker.
+ */
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+/** The keymap's own help key doubles as a close key (undefined = none). */
+function helpKey(keymap) {
+    if (keymap.name === "standard")
+        return "?";
+    if (keymap.name === "emacs")
+        return "\x08"; // C-h
+    if (keymap.name === "vim")
+        return "g?"; // the g-prefix chord (? stays search)
+    return undefined;
+}
+class HelpOverlay {
+    #rows;
+    #helpKey;
+    #options;
+    #overlay;
+    /** Set after a bare "g" while #helpKey is "g?" (the vim close chord). */
+    #pendingG = false;
+    constructor(keymap, options) {
+        this.#rows = keymap.describe();
+        this.#helpKey = helpKey(keymap);
+        this.#options = options;
+    }
+    /** The overlay handle is installed by {@link showHelp} after show. */
+    setOverlay(overlay) {
+        this.#overlay = overlay;
+    }
+    #close() {
+        this.#overlay?.hide();
+        this.#options.onClose?.();
+    }
+    handleInput(data) {
+        const helpClose = this.#helpKey === "g?"
+            ? this.#pendingG && data === "?"
+            : this.#helpKey !== undefined && data === this.#helpKey;
+        this.#pendingG = this.#helpKey === "g?" && data === "g";
+        if (matchesKey(data, Key.escape) || data === "q" || helpClose) {
+            this.#close();
+        }
+        // Every other key is consumed: the overlay is modal.
+    }
+    render(width) {
+        const half = Math.ceil(this.#rows.length / 2);
+        // The left column's field width: its longest "keys  action" pair.
+        const leftWidth = Math.min(Math.max(...this.#rows
+            .slice(0, half)
+            .map((row) => row.keys.length + 2 + row.action.length)) + 4, Math.floor(width / 2));
+        const lines = ["key reference (esc or q closes)"];
+        for (let i = 0; i < half; i++) {
+            const left = this.#rows[i];
+            const right = this.#rows[i + half];
+            const leftText = `${left.keys}  ${left.action}`;
+            if (right === undefined) {
+                lines.push(leftText);
+            }
+            else {
+                lines.push(`${leftText.padEnd(leftWidth)}${right.keys}  ${right.action}`);
+            }
+        }
+        return lines;
+    }
+    invalidate() { }
+}
+/** Open the key reference overlay for `keymap`; Esc/q/help-key closes. */
+export function showHelp(tui, keymap, options = {}) {
+    const help = new HelpOverlay(keymap, options);
+    const overlay = tui.showOverlay(help, {
+        anchor: "center",
+        width: "70%",
+        maxHeight: "70%",
+    });
+    help.setOverlay(overlay);
+}

package/dist/ui/interactions.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The interaction seam's TUI renderer (Task 8 — the parity rule): the
+ * pending-interaction stack rendered as an answerable prompt strip
+ * between the conversation pane and the composer (spec §3.2: "a visible
+ * prompt in the conversation pane" — the TUI's medium-appropriate form is
+ * a strip directly above the composer, where the answer keys live).
+ *
+ * Genericity (the seam's whole point): this component renders the closed
+ * primitives (text / options / fields / diff) and the envelope, and knows
+ * NOTHING about kinds — there is no gate-specific concept here. `details` renders as
+ * one collapsed JSON line, never interpreted (the single read is the
+ * webui-parity `details.multi === true` multi-select flag).
+ *
+ * Answering: ctrl+o enters answer mode (the app routes it via
+ * {@link TuiApp.handleKeybinding}; ctrl+a is the editor's cursorLineStart,
+ * so the prompt uses ctrl+o). Digits 1-9 pick options — single-choice
+ * answers immediately; multi (`details.multi`) toggles and enter submits
+ * the accumulated set; esc exits. Answer mode PINS the record it was
+ * armed on: if a poll replaces the top of the stack before the user keys
+ * an answer, the mode exits instead of answering a record the user never
+ * saw. The answer POSTs through the ONE generic route
+ * (`answerInteraction`); the record clears when the next list poll
+ * reflects the settle (the server drops answered records from pending).
+ *
+ * Medium limits (the parity rule's documented exceptions):
+ * - Form `fields` render read-only with a "answer in the webui" hint —
+ *   the TUI's composer is the conversation's text input; capturing it for
+ *   form values would collide with submission routing. v1 answers
+ *   option-based prompts only.
+ * - Option `tone` is a color/severity hint; the shell pins a no-color
+ *   theme (styling is a later task), so tone is not rendered.
+ *
+ * Refetch triggers (W3 Task 4 — the 2s poll interval is RETIRED): kicks
+ * arrive on each stream frame (a revision may change the pending set) and
+ * on `interaction.*` host events (the app wires `watchEvents`'s
+ * `interaction.pending`/`interaction.settled` to {@link kick}). Kicks
+ * coalesce (one fetch in flight, one queued). Poll failures are
+ * QUIET — the prompt keeps its last state; stream transport health is
+ * reported separately by the watcher's error/open transition notices
+ * (the launcher's stream-health wiring). Answer failures (user-initiated)
+ * are LOUD via {@link onError} (the app routes them to the pane's
+ * `[error]` line).
+ */
+import { type Component } from "@earendil-works/pi-tui";
+import type { InteractionWire, SigrunClient } from "../api.js";
+export declare class InteractionPrompter implements Component {
+    #private;
+    /** Answer failures (user-initiated — loud). The app routes to the pane. */
+    onError?: (message: string) => void;
+    /** Rendered-state changes (the app requests a repaint). */
+    onChanged?: () => void;
+    constructor(client: SigrunClient);
+    /** The latest pending list (top of stack first). */
+    get pending(): readonly InteractionWire[];
+    /** Whether digit/enter/esc keys are captured for answering. */
+    get answerMode(): boolean;
+    /**
+     * Retarget the prompter: reset state and fetch immediately.
+     * `undefined` clears the prompt. (W3 Task 4: no poll interval —
+     * stream frames and `interaction.*` host events own the refreshes.)
+     */
+    setConversation(id: number | undefined): void;
+    /** Coalesced poll (the app's stream frames call this). */
+    kick(): void;
+    /**
+     * kick(), awaited. Production polls are fire-and-forget; tests need to
+     * await the poll's settle to assert the state after it.
+     */
+    kickAndWait(): Promise<void>;
+    /**
+     * Enter answer mode — only when the top pending item is option-
+     * answerable. Returns whether the mode was entered (the caller consumes
+     * the key only then).
+     */
+    beginAnswer(): boolean;
+    /**
+     * Route one key while in answer mode. Returns true when consumed.
+     * Unrelated keys pass through (the seam never blocks — the user can
+     * keep typing while a prompt waits).
+     */
+    handleKey(data: string): boolean;
+    /** Detach (the app calls this on dispose): stale fetches never land. */
+    dispose(): void;
+    /**
+     * The prompt strip: nothing when no item is pending; otherwise the top
+     * item's header, body primitives, answer affordance, and a stack count.
+     */
+    render(_width: number): string[];
+    invalidate(): void;
+}