@sigrun/tui 0.4.1 → 0.5.0

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,91 @@
+/**
+ * The interaction seam's TUI renderer (UI-blocks U6 Task 3, the parity
+ * rule): the pending-interaction stack rendered FROM BLOCK TREES — each
+ * record's body is a root `form` (placement `interaction`, spec §9.1)
+ * rendered through the shared renderer against a
+ * {@link createInteractionTransport}: the record IS the surface (the
+ * tree is the load, the form's submit POSTs `{values}` to the ONE
+ * generic answer route — ruling 20). The strip sits between the
+ * conversation pane and the composer, where the answer keys live.
+ *
+ * Genericity (the seam's whole point): the renderer renders the tree
+ * and knows NOTHING about kinds. `details` renders as one collapsed
+ * JSON line, never interpreted.
+ *
+ * Answering: ctrl+o ARMS the prompt (the app routes it via
+ * {@link TuiApp.handleKeybinding}; ctrl+a is the editor's
+ * cursorLineStart, so the prompt uses ctrl+o); while armed, keys route
+ * to the rendered form (choice rows take digits 1-9 as a direct pick —
+ * the medium-appropriate accelerator — plus the form's own keys; a
+ * multi-question form's stepper advances with Tab, reviews, and submits
+ * ONCE with Enter). 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.
+ *
+ * Expiry mid-stepper (Review Focus 2): a submit that lands on an
+ * already-settled record (404 not_pending) refetches the record through
+ * {@link SigrunClient.getInteraction}, renders its settled status, and
+ * keeps the typed values visible but read-only (the form's state
+ * survives — the tree never changed).
+ *
+ * Refetch triggers (W3 Task 4 — the 2s poll interval is RETIRED): kicks
+ * arrive on each stream frame and on `interaction.*` host events. Kicks
+ * coalesce (one fetch in flight, one queued). Poll failures are QUIET —
+ * the prompt keeps its last state; answer failures (user-initiated) are
+ * LOUD via {@link onError}.
+ */
+import { type Component } from "@earendil-works/pi-tui";
+import type { InteractionWire, SigrunClient } from "../api.js";
+import { SurfaceState } from "../blocks/surface.js";
+import { type TuiTheme } from "../theme.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, options?: {
+        theme?: TuiTheme;
+    });
+    /** The latest pending list (top of stack first). */
+    get pending(): readonly InteractionWire[];
+    /** Whether keys are captured for answering. */
+    get answerMode(): boolean;
+    /** The live surface's state (tests drive non-submit dispatches
+     *  through it). */
+    get surface(): SurfaceState | undefined;
+    /**
+     * 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 carries a
+     * block-tree body to answer. 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, its block tree, the answer affordance, and a stack
+     * count.
+     */
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/ui/interactions.js

@@ -0,0 +1,477 @@
+/**
+ * The interaction seam's TUI renderer (UI-blocks U6 Task 3, the parity
+ * rule): the pending-interaction stack rendered FROM BLOCK TREES — each
+ * record's body is a root `form` (placement `interaction`, spec §9.1)
+ * rendered through the shared renderer against a
+ * {@link createInteractionTransport}: the record IS the surface (the
+ * tree is the load, the form's submit POSTs `{values}` to the ONE
+ * generic answer route — ruling 20). The strip sits between the
+ * conversation pane and the composer, where the answer keys live.
+ *
+ * Genericity (the seam's whole point): the renderer renders the tree
+ * and knows NOTHING about kinds. `details` renders as one collapsed
+ * JSON line, never interpreted.
+ *
+ * Answering: ctrl+o ARMS the prompt (the app routes it via
+ * {@link TuiApp.handleKeybinding}; ctrl+a is the editor's
+ * cursorLineStart, so the prompt uses ctrl+o); while armed, keys route
+ * to the rendered form (choice rows take digits 1-9 as a direct pick —
+ * the medium-appropriate accelerator — plus the form's own keys; a
+ * multi-question form's stepper advances with Tab, reviews, and submits
+ * ONCE with Enter). 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.
+ *
+ * Expiry mid-stepper (Review Focus 2): a submit that lands on an
+ * already-settled record (404 not_pending) refetches the record through
+ * {@link SigrunClient.getInteraction}, renders its settled status, and
+ * keeps the typed values visible but read-only (the form's state
+ * survives — the tree never changed).
+ *
+ * Refetch triggers (W3 Task 4 — the 2s poll interval is RETIRED): kicks
+ * arrive on each stream frame and on `interaction.*` host events. Kicks
+ * coalesce (one fetch in flight, one queued). Poll failures are QUIET —
+ * the prompt keeps its last state; answer failures (user-initiated) are
+ * LOUD via {@link onError}.
+ */
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { createInteractionTransport } from "../blocks/interaction-transport.js";
+import { SurfaceState } from "../blocks/surface.js";
+import { SurfaceView } from "../blocks/surface-view.js";
+import { plainTuiTheme } from "../theme.js";
+import { describeCommandError } from "./composer.js";
+/** The answer-mode direct-pick keys: digits 1-9. */
+const DIGIT = /^[1-9]$/;
+/** The record-as-surface data document: the form binds `/values`, so
+ *  the document is `{values}` — a settled record's stored answer seeds
+ *  the read-only render (spec §6.5; secret fields render write-only
+ *  regardless). */
+function recordData(record) {
+    if (record.answer === undefined)
+        return {};
+    return { values: { ...record.answer.values } };
+}
+export class InteractionPrompter {
+    #client;
+    #theme;
+    #conversationId;
+    /** Monotonic per-conversation generation: stale fetches never land. */
+    #gen = 0;
+    #pending = [];
+    #answerMode = false;
+    /**
+     * The record answer mode is ARMED ON. Pinned at beginAnswer: a poll can
+     * replace the top of the stack at any time (the record settled via the
+     * webui, the extension resolved it, it expired), and a key pressed for
+     * the prompt the user READ must never answer the prompt that replaced
+     * it. Any top-identity change exits answer mode instead.
+     */
+    #answerCallId;
+    /**
+     * The rendered surface of the TOP record (rebuilt when the top's
+     * identity changes; NOT rebuilt on a mere list refresh of the same
+     * record — the form's typed state must survive a poll, Review Focus
+     * 2's "typed values stay visible").
+     */
+    #surface;
+    /** Coalescing poll state: one fetch in flight, at most one queued. */
+    #inFlight = false;
+    #queued = false;
+    /** Answer failures (user-initiated — loud). The app routes to the pane. */
+    onError;
+    /** Rendered-state changes (the app requests a repaint). */
+    onChanged;
+    constructor(client, options = {}) {
+        this.#client = client;
+        // No-color default (the shell pins structure; styling rides the
+        // app's theme when the host passes one).
+        this.#theme = options.theme ?? plainTuiTheme();
+    }
+    /** The latest pending list (top of stack first). */
+    get pending() {
+        return this.#pending;
+    }
+    /** Whether keys are captured for answering. */
+    get answerMode() {
+        return this.#answerMode;
+    }
+    /** The live surface's state (tests drive non-submit dispatches
+     *  through it). */
+    get surface() {
+        return this.#surface?.state;
+    }
+    /**
+     * 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) {
+        this.#gen += 1;
+        this.#conversationId = id;
+        this.#pending = [];
+        this.#surface?.state.dispose();
+        this.#surface = undefined;
+        this.#exitAnswer();
+        // A fetch from the OLD conversation may still be in flight (or stuck);
+        // its result is fenced by the generation guard, so its promise is
+        // orphaned — the new conversation must not queue behind it.
+        this.#inFlight = false;
+        this.#queued = false;
+        if (id === undefined) {
+            this.#changed();
+            return;
+        }
+        void this.#refresh();
+    }
+    /** Coalesced poll (the app's stream frames call this). */
+    kick() {
+        void this.#refresh();
+    }
+    /**
+     * kick(), awaited. Production polls are fire-and-forget; tests need to
+     * await the poll's settle to assert the state after it.
+     */
+    async kickAndWait() {
+        await this.#refresh();
+    }
+    /**
+     * Enter answer mode — only when the top pending item carries a
+     * block-tree body to answer. Returns whether the mode was entered (the
+     * caller consumes the key only then).
+     */
+    beginAnswer() {
+        const top = this.#pending[0];
+        if (top === undefined || top.body === undefined)
+            return false;
+        this.#ensureSurface(top);
+        this.#answerMode = true;
+        // Pin the target: keys answer THIS record or nothing.
+        this.#answerCallId = top.callId;
+        this.#changed();
+        return true;
+    }
+    /**
+     * 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) {
+        const top = this.#pending[0];
+        if (!this.#answerMode || top === undefined) {
+            this.#exitAnswer();
+            return false;
+        }
+        // Target-pin check: if a poll replaced the armed record, the keys
+        // the user is pressing belong to a prompt they never saw — exit
+        // answer mode and let the key pass through unanswered.
+        if (this.#answerCallId !== top.callId) {
+            this.#exitAnswer();
+            this.#changed();
+            return false;
+        }
+        if (matchesKey(data, Key.escape)) {
+            this.#exitAnswer();
+            this.#changed();
+            return true;
+        }
+        this.#ensureSurface(top);
+        if (this.#surface === undefined) {
+            this.#exitAnswer();
+            return false;
+        }
+        // A digit aims at the top record's choice field — the
+        // one-question gate's direct pick (1-9 answers immediately).
+        // Everything else — arrows, Tab, Enter, typed text — is the
+        // form's own key language. The shortcut only fires on a
+        // ONE-question gate (no stepper): a multi-question stepper's
+        // digits belong to the form's per-step choice editing.
+        if (DIGIT.test(data)) {
+            const body = top.body;
+            const choice = body === undefined ? undefined : firstChoice(body);
+            const stepper = body !== undefined &&
+                body.root.type === "form" &&
+                stepperSections(body.root, true) !== null;
+            if (choice !== undefined && !stepper) {
+                const index = Number(data) - 1;
+                const option = Array.isArray(choice.options)
+                    ? choice.options[index]
+                    : undefined;
+                if (option !== undefined) {
+                    const form = formComponent(this.#surface);
+                    if (form !== undefined) {
+                        if (choice.multi === true) {
+                            // Multi: toggle into the form's value; Enter (the
+                            // form's key) submits the accumulated set.
+                            const current = form.fieldValue(choice.name);
+                            const set = new Set(Array.isArray(current) ? current : []);
+                            if (set.has(option.id)) {
+                                set.delete(option.id);
+                            }
+                            else {
+                                set.add(option.id);
+                            }
+                            form.setFieldValue(choice.name, [...set]);
+                            this.#changed();
+                            return true;
+                        }
+                        form.setFieldValue(choice.name, option.id);
+                        // Single-choice: the pick IS the answer — submit at
+                        // once (the one-question gate's direct pick). The name
+                        // must match the form's onSubmit action (custom actions
+                        // like "decide" gate the transport's submit).
+                        this.#surface.state.dispatch({ type: "submit", name: this.#surface.submitAction }, { values: { ...(form.values ?? {}) } });
+                        return true;
+                    }
+                }
+                // No matching option: the digit still belongs to the prompt.
+                return true;
+            }
+            // A stepper's digits route to the form (its stepper owns the
+            // per-step choice editing).
+            if (choice !== undefined) {
+                this.#surface.view.handleInput(data);
+                return true;
+            }
+            return true;
+        }
+        this.#surface.view.handleInput(data);
+        return true;
+    }
+    /** Build (or keep) the top record's surface pair. A mid-edit settle
+     *  swap (Review Focus 2) reuses the same callId: the settled envelope
+     *  flips access to read; the tree is unchanged so the typed values
+     *  stay on screen. */
+    #ensureSurface(record) {
+        const existing = this.#surface;
+        if (existing !== undefined && existing.record.callId === record.callId) {
+            // A settled envelope (the mid-edit settle swap) sticks: the
+            // pending poll re-serves the record as pending, and the
+            // settled render must not revert to write access.
+            if (existing.settled !== undefined)
+                return;
+            const access = record.status === "pending" ? "write" : "read";
+            if (existing.access === access)
+                return;
+            this.#surface = { ...existing, record, access };
+            return;
+        }
+        const access = record.status === "pending" ? "write" : "read";
+        const conversationId = this.#conversationId;
+        if (conversationId === undefined || record.body === undefined)
+            return;
+        const root = record.body.root;
+        const submitAction = root.type === "form" ? (root.onSubmit ?? "submit") : "submit";
+        const transport = createInteractionTransport({
+            client: this.#client,
+            conversationId,
+            callId: record.callId,
+            tree: record.body,
+            data: recordData(record),
+            access,
+            submitAction,
+            onAnswered: () => {
+                // The settle lands via the next list poll (the server drops
+                // answered records from pending).
+                this.#exitAnswer();
+                void this.#refresh();
+            },
+            onSettledElsewhere: (_message, cause) => {
+                // The settle raced the user's submit (expiry, another channel,
+                // the extension): refetch the record and render it settled —
+                // the typed values stay visible, read-only (Review Focus 2).
+                const id = this.#conversationId;
+                if (id === undefined) {
+                    this.onError?.(describeCommandError("answer", cause));
+                    return;
+                }
+                this.#client.getInteraction(id, record.callId).then((fresh) => {
+                    // Swap ONLY the record the user was working on; a
+                    // conversation switch since the submit discards it.
+                    if (this.#surface?.record.callId !== record.callId)
+                        return;
+                    // Only a genuinely settled record swaps in — a still-
+                    // pending refetch (a 400, a network blip) must NOT wedge
+                    // the card read-only: report the failure and stay
+                    // writable (Review fix).
+                    if (fresh.status === "pending") {
+                        this.onError?.(describeCommandError("answer", cause));
+                        this.#changed();
+                        return;
+                    }
+                    this.#surface = this.#surface === undefined
+                        ? undefined
+                        : {
+                            ...this.#surface,
+                            settled: fresh,
+                            access: "read",
+                        };
+                    // Flip the LIVE surface's access so the read-only
+                    // render takes effect immediately (the transport's
+                    // access was captured at load).
+                    this.#surface?.state.setAccess("read");
+                    this.#exitAnswer();
+                    this.#changed();
+                }, () => {
+                    this.onError?.(describeCommandError("answer", cause));
+                });
+            },
+        });
+        const state = new SurfaceState(transport);
+        const view = new SurfaceView(state, {
+            theme: this.#theme,
+            unicode: true,
+            options: { interaction: true },
+        });
+        this.#surface = { record, state, view, access, submitAction };
+        // The record's tree is static, so the load resolves within a
+        // microtask; the repaint lands via the change subscription.
+        state.onChange(() => this.#changed());
+        void state.load();
+    }
+    #exitAnswer() {
+        this.#answerMode = false;
+        this.#answerCallId = undefined;
+    }
+    /** Generation-guarded, coalesced fetch of the pending list. */
+    async #refresh() {
+        const id = this.#conversationId;
+        const gen = this.#gen;
+        if (id === undefined)
+            return;
+        if (this.#inFlight) {
+            this.#queued = true;
+            return;
+        }
+        this.#inFlight = true;
+        try {
+            do {
+                this.#queued = false;
+                let list;
+                try {
+                    list = await this.#client.listInteractions(id);
+                }
+                catch {
+                    // Quiet poll failure: keep the last pending list.
+                    continue;
+                }
+                if (gen !== this.#gen)
+                    return; // stale — a switch happened
+                // The route serves pending-only; the filter is belt for races.
+                this.#pending = list.interactions.filter((record) => record.status === "pending");
+                // The armed record left the top of the stack (settled via
+                // another channel, resolved by its extension, expired — or
+                // simply reordered): the user's armed keys belong to a prompt
+                // they are no longer looking at. Exit answer mode rather than
+                // risk answering a record they never saw.
+                if (this.#answerMode &&
+                    this.#pending[0]?.callId !== this.#answerCallId) {
+                    this.#exitAnswer();
+                }
+                // A top-identity change rebuilds the surface; a same-record
+                // refresh keeps it (typed values survive the poll).
+                const top = this.#pending[0];
+                if (top === undefined) {
+                    this.#surface?.state.dispose();
+                    this.#surface = undefined;
+                }
+                else if (this.#surface?.record.callId !== top.callId) {
+                    this.#surface?.state.dispose();
+                    this.#surface = undefined;
+                    // Build eagerly (not at render) so the async load settles
+                    // with the poll's flush — a strip that waits a frame for
+                    // "loading…" reads as a flicker.
+                    this.#ensureSurface(top);
+                }
+                this.#changed();
+            } while (this.#queued && gen === this.#gen);
+        }
+        finally {
+            if (gen === this.#gen)
+                this.#inFlight = false;
+        }
+    }
+    #changed() {
+        this.onChanged?.();
+    }
+    /** Detach (the app calls this on dispose): stale fetches never land. */
+    dispose() {
+        this.#gen += 1;
+    }
+    /**
+     * The prompt strip: nothing when no item is pending; otherwise the top
+     * item's header, its block tree, the answer affordance, and a stack
+     * count.
+     */
+    render(width) {
+        const top = this.#pending[0];
+        if (top === undefined)
+            return [];
+        const lines = [];
+        const shown = this.#surface?.settled ?? top;
+        const suffix = this.#answerMode
+            ? " — answering"
+            : shown.status === "pending"
+                ? ""
+                : ` — ${shown.status}`;
+        lines.push(`[interaction] ${shown.kind}${suffix}`);
+        if (top.body !== undefined) {
+            this.#ensureSurface(top);
+            if (this.#surface !== undefined) {
+                lines.push(...this.#surface.view.render(width));
+            }
+        }
+        if (top.details !== undefined) {
+            lines.push(`[details] ${JSON.stringify(top.details)}`);
+        }
+        if (this.#pending.length > 1) {
+            lines.push(`+${this.#pending.length - 1} more pending`);
+        }
+        if (top.body !== undefined) {
+            lines.push(this.#answerMode
+                ? "1-9 answer · Tab next · esc cancel"
+                : "ctrl+o to answer");
+        }
+        return lines;
+    }
+    invalidate() {
+        this.#surface?.view.invalidate();
+    }
+}
+import { stepperSections } from "../blocks/form/form.js";
+/** The form's first choice field (the digit accelerator's target), or
+ *  undefined when the form holds none. */
+function firstChoice(tree) {
+    const root = tree.root;
+    if (root.type !== "form")
+        return undefined;
+    const walk = (children) => {
+        for (const child of children) {
+            if (typeof child !== "object" || child === null)
+                continue;
+            const record = child;
+            if (record.type === "choice" && typeof record.name === "string") {
+                // SAFETY: the type/name guard above is the choice field's
+                // identifying shape (the tree passed placement validation).
+                return record;
+            }
+            if (record.type === "section" && Array.isArray(record.children)) {
+                const found = walk(record.children);
+                if (found !== undefined)
+                    return found;
+            }
+        }
+        return undefined;
+    };
+    return walk(root.children);
+}
+/** The wrapped form component, when the surface's root is a form. */
+function formComponent(surface) {
+    const inner = surface.view.inner;
+    if (inner === undefined)
+        return undefined;
+    if (!("setFieldValue" in inner))
+        return undefined;
+    // SAFETY: the WidthGated wrapper forwards the form introspection
+    // (the render seam's forwarding contract).
+    return inner;
+}

package/dist/ui/picker.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The picker overlay (Task C3, UI refresh): a centred `showOverlay` box —
+ * a title line, a one-line fuzzy filter, and a `SelectList`. Typing
+ * re-filters (pi-tui's `fuzzyFilter` over label + detail), Enter picks,
+ * Esc closes, and a mouse click picks (SelectList's own mouse handling).
+ *
+ * Conversation/model/command pickers are built by the app from the
+ * sidebar tree, `listModels()`, and the slash catalog respectively.
+ */
+import { type TUI } from "@earendil-works/pi-tui";
+import type { TuiTheme } from "../theme.js";
+export interface PickerItem<T> {
+    readonly label: string;
+    readonly detail?: string;
+    readonly value: T;
+}
+export interface PickerOptions<T> {
+    readonly title: string;
+    readonly onPick: (value: T) => void;
+    /** Fires on close (pick OR cancel) so the app can clear overlayOpen. */
+    readonly onClose?: () => void;
+    /** The token theme; defaults to plain identity styling. */
+    readonly theme?: TuiTheme;
+}
+/** Open a centred picker overlay; Enter/click picks, Esc closes. */
+export declare function openPicker<T>(tui: TUI, items: readonly PickerItem<T>[], options: PickerOptions<T>): void;