@sigrun/tui 0.0.0-stage → 0.1.1

package/dist/ui/interactions.js

@@ -0,0 +1,330 @@
+/**
+ * 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 { Key, matchesKey } from "@earendil-works/pi-tui";
+import { diffLines } from "../blocks/diff.js";
+import { describeCommandError } from "./composer.js";
+/** The answer-mode option pick keys: digits 1-9. */
+const DIGIT = /^[1-9]$/;
+export class InteractionPrompter {
+    #client;
+    #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 digit keyed for
+     * the prompt the user READ must never answer the prompt that replaced
+     * it. Any top-identity change exits answer mode instead.
+     */
+    #answerCallId;
+    /** The multi-select working set (option ids), pre-seeded recommended. */
+    #selected = new Set();
+    /** 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) {
+        this.#client = client;
+    }
+    /** The latest pending list (top of stack first). */
+    get pending() {
+        return this.#pending;
+    }
+    /** Whether digit/enter/esc keys are captured for answering. */
+    get answerMode() {
+        return this.#answerMode;
+    }
+    /**
+     * 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.#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 is option-
+     * answerable. Returns whether the mode was entered (the caller consumes
+     * the key only then).
+     */
+    beginAnswer() {
+        const top = this.#pending[0];
+        const options = top?.body?.options ?? [];
+        if (top === undefined || options.length === 0)
+            return false;
+        this.#answerMode = true;
+        // Pin the target: keys answer THIS record or nothing.
+        this.#answerCallId = top.callId;
+        // The webui's pre-selection rule: recommended options start selected.
+        this.#selected = new Set(options.filter((o) => o.recommended === true).map((o) => o.id));
+        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];
+        const options = top?.body?.options ?? [];
+        if (!this.#answerMode || top === undefined || options.length === 0) {
+            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;
+        }
+        const multi = isMulti(top);
+        if (matchesKey(data, Key.enter)) {
+            if (multi && this.#selected.size > 0) {
+                this.#submit(top, [...this.#selected]);
+            }
+            return true;
+        }
+        if (DIGIT.test(data)) {
+            const index = Number(data) - 1;
+            const option = options[index];
+            if (option !== undefined) {
+                if (multi) {
+                    const next = new Set(this.#selected);
+                    if (next.has(option.id)) {
+                        next.delete(option.id);
+                    }
+                    else {
+                        next.add(option.id);
+                    }
+                    this.#selected = next;
+                    this.#changed();
+                }
+                else {
+                    this.#submit(top, [option.id]);
+                }
+            }
+            // In-range or not, digits belong to the prompt in answer mode.
+            return true;
+        }
+        return false;
+    }
+    /** Fire-and-forget answer; the next list poll reflects the settle. */
+    #submit(record, ids) {
+        const id = this.#conversationId;
+        if (id === undefined)
+            return;
+        // Belt to the handleKey pin check: never POST for a record the
+        // answer keys were not armed on.
+        if (this.#answerCallId !== record.callId)
+            return;
+        this.#exitAnswer();
+        this.#changed();
+        const answer = { ids };
+        this.#client.answerInteraction(id, record.callId, answer).then(() => {
+            void this.#refresh();
+        }, (error) => {
+            this.onError?.(describeCommandError("answer", error));
+            void this.#refresh();
+        });
+    }
+    #exitAnswer() {
+        this.#answerMode = false;
+        this.#answerCallId = undefined;
+        this.#selected = new Set();
+    }
+    /** 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();
+                }
+                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, body primitives, answer affordance, and a stack count.
+     */
+    render(_width) {
+        const top = this.#pending[0];
+        if (top === undefined)
+            return [];
+        const body = top.body;
+        const options = body?.options ?? [];
+        const fields = body?.fields ?? [];
+        const multi = isMulti(top);
+        const lines = [];
+        lines.push(this.#answerMode
+            ? `[interaction] ${top.kind} — answering`
+            : `[interaction] ${top.kind}`);
+        if (body?.text !== undefined) {
+            for (const line of body.text.split("\n"))
+                lines.push(line);
+        }
+        if (body?.diff !== undefined) {
+            lines.push(...diffLines(body.diff));
+        }
+        for (const [index, option] of options.entries()) {
+            const marker = this.#answerMode && multi
+                ? this.#selected.has(option.id)
+                    ? "[x] "
+                    : "[ ] "
+                : "";
+            const recommended = option.recommended === true ? " (recommended)" : "";
+            const description = option.description === undefined ? "" : ` — ${option.description}`;
+            lines.push(`  ${marker}${index + 1}. ${option.label}${recommended}${description}`);
+        }
+        for (const field of fields) {
+            const label = field.label ?? field.name;
+            const required = field.required === true ? " required" : "";
+            lines.push(`  - ${label} (${field.type})${required}`);
+        }
+        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 (options.length > 0) {
+            if (this.#answerMode) {
+                lines.push(multi
+                    ? "1-9 toggle · enter submit · esc cancel"
+                    : "1-9 answer · esc cancel");
+            }
+            else {
+                lines.push("ctrl+o to answer");
+            }
+        }
+        else if (fields.length > 0) {
+            lines.push("needs form input — answer in the webui");
+        }
+        return lines;
+    }
+    invalidate() {
+        // Stateless render: lines assemble from the current pending list.
+    }
+}
+/** The webui's multi-select reading: `details.multi === true`. */
+function isMulti(record) {
+    return (record.details?.multi === true);
+}

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;

package/dist/ui/picker.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { fuzzyFilter, Key, matchesKey, SelectList, } from "@earendil-works/pi-tui";
+const MAX_VISIBLE = 10;
+function plainSelectListTheme() {
+    const identity = (text) => text;
+    return {
+        selectedPrefix: identity,
+        selectedText: identity,
+        description: identity,
+        scrollInfo: identity,
+        noMatch: identity,
+    };
+}
+class Picker {
+    #items;
+    #options;
+    #selectTheme;
+    #muted;
+    #query = "";
+    #filtered;
+    #list;
+    #overlay;
+    constructor(items, options) {
+        this.#items = items;
+        this.#options = options;
+        const theme = options.theme;
+        this.#selectTheme =
+            theme === undefined
+                ? plainSelectListTheme()
+                : {
+                    selectedPrefix: (text) => theme.fg("accent")(text),
+                    selectedText: (text) => theme.bold(text),
+                    description: (text) => theme.fg("muted")(text),
+                    scrollInfo: (text) => theme.fg("muted")(text),
+                    noMatch: (text) => theme.fg("muted")(text),
+                };
+        this.#muted =
+            theme === undefined ? (text) => text : (text) => theme.fg("muted")(text);
+        this.#filtered = items;
+        this.#list = this.#buildList();
+    }
+    /** The overlay handle is installed by {@link openPicker} after show. */
+    setOverlay(overlay) {
+        this.#overlay = overlay;
+    }
+    #buildList() {
+        const list = new SelectList(this.#filtered.map((item, index) => ({
+            value: String(index),
+            label: item.label,
+            ...(item.detail === undefined ? {} : { description: item.detail }),
+        })), MAX_VISIBLE, this.#selectTheme);
+        list.onSelect = (item) => {
+            const picked = this.#filtered[Number(item.value)];
+            if (picked === undefined)
+                return;
+            this.#close();
+            this.#options.onPick(picked.value);
+        };
+        list.onCancel = () => this.#close();
+        return list;
+    }
+    #close() {
+        this.#overlay?.hide();
+        this.#options.onClose?.();
+    }
+    #refilter() {
+        const filtered = this.#query === ""
+            ? this.#items
+            : fuzzyFilter([...this.#items], this.#query, (item) => item.detail === undefined ? item.label : `${item.label} ${item.detail}`);
+        this.#filtered = filtered;
+        this.#list = this.#buildList();
+    }
+    handleInput(data) {
+        // C-g is the emacs cancel: close like Esc (the emacs keymap passes it
+        // through while an overlay owns the keys).
+        if (data === "\x07") {
+            this.#close();
+            return;
+        }
+        if (matchesKey(data, Key.backspace) || matchesKey(data, "backspace")) {
+            if (this.#query !== "") {
+                this.#query = this.#query.slice(0, -1);
+                this.#refilter();
+            }
+            return;
+        }
+        // One printable character extends the filter; everything else
+        // (arrows, Enter, Esc, mouse) is the list's own input.
+        if (data.length === 1 && data >= " ") {
+            this.#query += data;
+            this.#refilter();
+            return;
+        }
+        this.#list.handleInput(data);
+    }
+    render(width) {
+        return [
+            this.#muted(this.#options.title),
+            this.#muted(`filter: ${this.#query}`),
+            ...this.#list.render(width),
+        ];
+    }
+    /** The click is additive: delegate to the list under the filter rows. */
+    handleMouse(event) {
+        if (event.y < 2)
+            return { handled: true };
+        return this.#list.handleMouse({ ...event, y: event.y - 2 });
+    }
+    invalidate() {
+        this.#list.invalidate();
+    }
+}
+/** Open a centred picker overlay; Enter/click picks, Esc closes. */
+export function openPicker(tui, items, options) {
+    const picker = new Picker(items, options);
+    const overlay = tui.showOverlay(picker, {
+        anchor: "center",
+        width: "60%",
+        maxHeight: "60%",
+    });
+    picker.setOverlay(overlay);
+}

package/dist/ui/sidebar.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The sidebar (Task 6; restyled in C2, UI refresh): the conversation
+ * TREE — rows come from B1's `buildConversationTree` (fork children
+ * indent two spaces + `↳ `), names are single-line via B1's
+ * `displayName` + pi-tui's `truncateToWidth`, ages right-align via B1's
+ * `formatAge`, and the active row highlights accent-fg + bold. Archived
+ * conversations stay hidden (the tree's `includeArchived: false`; the
+ * server has no delete, archive is the hide). `+ New conversation` is
+ * always the last row.
+ *
+ * The listing itself carries every field the rows need (`name`,
+ * `archived`, `pinned`, `parent`, `lastActivityAt` ride
+ * `ConversationSummary` — A1), so {@link refresh} makes ONE request: no
+ * per-row meta fetch. The app re-refreshes on a 10 s poll (an unref'd
+ * `setInterval` the launcher clears on dispose).
+ *
+ * Keyboard-first (mouse is additive): `cursor` / `moveCursor` /
+ * `confirm()` are the C3 action layer's seam; a click on a row selects
+ * it (`MouseRegion` per row). Selection reports to {@link onSelect}: a
+ * conversation id, or `"new"` for the `+ New conversation` row
+ * (creation is the app's job — the sidebar never calls
+ * createConversation itself).
+ */
+import { type Component } from "@earendil-works/pi-tui";
+import { type TuiTheme } from "../theme.js";
+import type { SigrunClient } from "../api.js";
+/** The sidebar selection: a conversation id, the `+ new` action, or an
+ *  extension VIEW (UI-blocks U3 Task 5 — the app opens it in the main
+ *  pane). */
+export type SidebarSelection = number | "new" | {
+    readonly view: {
+        readonly slug: string;
+        readonly id: string;
+    };
+};
+/** One display row: a conversation, or the trailing `+ New` action. */
+interface SidebarRow {
+    /** The conversation id; -1 for the `+ New conversation` action row. */
+    readonly id: number;
+    /** The display name (displayName — unnamed → "New conversation"). */
+    readonly name: string;
+    /** The tree depth (fork children render indented). */
+    readonly depth: number;
+    /** The right-aligned age column ("" when never used). */
+    readonly age: string;
+    /** Whether this row is the active conversation. */
+    readonly active: boolean;
+}
+export interface SidebarOptions {
+    /** The token theme; defaults to the plain (identity) fallback. */
+    readonly theme?: TuiTheme;
+    /** The clock seam for age rendering (tests pin it). */
+    readonly now?: () => Date;
+}
+export declare class Sidebar implements Component {
+    #private;
+    /** Selection callback: the conversation id, or `"new"` for `+ new`. */
+    onSelect?: (selection: SidebarSelection) => void;
+    constructor(client: SigrunClient, options?: SidebarOptions);
+    /** The conversation rows, in display order (the app's boot default
+     * reads `rows[0]`); the trailing `+ New conversation` action row is
+     * NOT part of this list — it renders last via {@link #newRow}. */
+    get rows(): readonly SidebarRow[];
+    /** The cursor's row index (0-based over {@link rows}). */
+    get cursor(): number;
+    /**
+     * Re-fetch the listing and rebuild the rows from the tree (summary
+     * fields only — no per-row meta fetch). The cursor follows its
+     * conversation when it still exists.
+     */
+    refresh(): Promise<void>;
+    /**
+     * The extension views (U3 Task 5): refetch `GET /v1/extensions` and
+     * rebuild the VIEWS group (one row per declared view surface, in
+     * declaration order, status "ok" only). Panels live in the side pane,
+     * not here. Failures keep the last good list (a flaky server must
+     * never blank the sidebar).
+     */
+    refreshViews(): Promise<void>;
+    /** The extension view rows (the app's openExtView reads them). */
+    get views(): readonly {
+        slug: string;
+        id: string;
+        title: string;
+    }[];
+    /** Select the Nth extension view (the action layer's seam). */
+    confirmView(index: number): void;
+    /** Mark the active conversation (accent fg + bold); pass `undefined` to clear. */
+    setActive(id: number | undefined): void;
+    /** Move the cursor by `delta` rows, clamped to the list. */
+    moveCursor(delta: number): void;
+    /** Select the cursor's row (Enter — the action layer's seam). */
+    confirm(): void;
+    /** The keyboard seam: arrows move, Enter confirms (pre-C3 minimal). */
+    handleInput(data: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+}
+export {};