@sigrun/tui 0.0.0-stage → 0.1.0

package/dist/ui/ambient.js

@@ -0,0 +1,301 @@
+/**
+ * The ambient seam's TUI renderer (Task 8 — the parity rule): ambient
+ * surfaces placed in the TUI's chrome per the seam's `place` field. Spec
+ * §8 leaves the place→chrome mapping to the builder; the TUI's mapping:
+ *
+ * - `status` → the statusline: one row, directly above the composer (the
+ *   last row of the app body). Multiple status records join with " · ".
+ * - `footer` → the footer zone: one summary line per record, above the
+ *   statusline.
+ * - `panel` → the panel zone: the full rendering (line, rows, gauge,
+ *   ledger), above the footer.
+ *
+ * Genericity (the seam's whole point): the chrome renders the closed
+ * primitives and knows NOTHING about what a surface means — no "todo",
+ * no "goal". `details` renders as one collapsed JSON line, never
+ * interpreted. The rendering mirrors the webui's AmbientPanel: rows are
+ * severity-sorted (0 severe .. 2 quiet, ties by id) with quiet rows
+ * folded into a "+N quiet" summary; metrics format via the record's
+ * `format` hint; gauges render label/phase/elapsed plus a text percent
+ * bar; ledgers render newest-first. Ambient surfaces are read-only (the
+ * seam routes actions through interaction records).
+ *
+ * Fetching (W3 Task 4 — the timer cadence is RETIRED): on conversation
+ * connect, and on `ambient.changed` host events for the live
+ * conversation (the app wires `watchEvents` to {@link kick}; an event
+ * for another conversation is ignored). A record's declared `refreshMs`
+ * no longer drives a poll — the extension that declares it owns its
+ * writes, and each write emits the event. Fetch failures are QUIET
+ * (best-effort chrome; stream transport health is reported separately by
+ * the watcher's error/open transition notices — the launcher's
+ * stream-health wiring).
+ *
+ * Expiry: `expires: "idle"` surfaces render only while the conversation
+ * has a live run ({@link setBusy}, driven by the stream's `steer.busy`);
+ * they disappear when the conversation goes idle and reappear on the next
+ * busy frame while the record is still served. `expires: "never"` records
+ * stay until the server stops serving them (replacement-state reads).
+ *
+ * Segments: a line's `segments` render as their texts joined with spaces
+ * in AUTHORED order — the segment `place` zones (left/middle/right) are
+ * ignored in the statusline join (the TUI chrome has no zone layout; the
+ * webui owns zoned placement).
+ */
+/** The gauge bar width (text cells). */
+const GAUGE_CELLS = 10;
+export class AmbientChrome {
+    #client;
+    #conversationId;
+    /** Monotonic per-conversation generation: stale fetches never land. */
+    #gen = 0;
+    /** The latest served surfaces, keyed by slot key (fetch order). */
+    #records = [];
+    /** Whether the conversation has a live run (stream `steer.busy`). */
+    #busy = false;
+    /** Rendered-state changes (the app requests a repaint). */
+    onChanged;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** The latest served surfaces (before the idle filter). */
+    get records() {
+        return this.#records;
+    }
+    /**
+     * Retarget the chrome: reset state and fetch immediately (the brief's
+     * "fetch on connect"). `undefined` clears the chrome. (W3 Task 4: no
+     * timer cadence — `ambient.changed` host events own the refreshes.)
+     */
+    setConversation(id) {
+        this.#gen += 1;
+        this.#conversationId = id;
+        this.#records = [];
+        if (id === undefined) {
+            this.#changed();
+            return;
+        }
+        void this.#refresh();
+    }
+    /**
+     * Refetch when an `ambient.changed` host event names the LIVE
+     * conversation (the app's events wiring calls this; other
+     * conversations' events are ignored).
+     */
+    kick(conversationId) {
+        if (conversationId !== this.#conversationId)
+            return;
+        void this.#refresh();
+    }
+    /**
+     * The conversation's run state (the app feeds it from stream frames).
+     * `expires: "idle"` surfaces render only while busy.
+     */
+    setBusy(busy) {
+        if (busy === this.#busy)
+            return;
+        this.#busy = busy;
+        this.#changed();
+    }
+    /** The statusline: the status records' summaries joined " · ". */
+    statusline() {
+        return this.#visible("status").map(summaryOf).join(" · ");
+    }
+    /** The footer zone: one summary line per footer record. */
+    footerLines() {
+        return this.#visible("footer").map(summaryOf);
+    }
+    /** The panel zone: the full per-record rendering, blocks joined. */
+    panelLines() {
+        const lines = [];
+        for (const record of this.#visible("panel")) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push(...panelBlock(record));
+        }
+        return lines;
+    }
+    /** Visible records in one place zone (fetch order preserved). */
+    #visible(place) {
+        return this.#records.filter((record) => record.place === place &&
+            (record.expires !== "idle" || this.#busy) &&
+            hasContent(record));
+    }
+    /** Generation-guarded fetch (quiet failures keep the last surfaces). */
+    async #refresh() {
+        const id = this.#conversationId;
+        const gen = this.#gen;
+        if (id === undefined)
+            return;
+        let list;
+        try {
+            list = await this.#client.getAmbient(id);
+        }
+        catch {
+            return; // quiet: keep the last surfaces
+        }
+        if (gen !== this.#gen)
+            return; // stale — a switch happened
+        this.#records = list.ambient;
+        this.#changed();
+    }
+    #changed() {
+        this.onChanged?.();
+    }
+    /** Detach (the app calls this on dispose): stale fetches never land. */
+    dispose() {
+        this.#gen += 1;
+    }
+    /** The chrome: panel blocks, then footer lines, then the statusline. */
+    render(_width) {
+        const lines = [...this.panelLines(), ...this.footerLines()];
+        const status = this.statusline();
+        if (status !== "")
+            lines.push(status);
+        return lines;
+    }
+    invalidate() {
+        // Stateless render: lines assemble from the current records.
+    }
+}
+// ─── Rendering helpers (the webui's AmbientPanel, mirrored in text) ─────
+/** A surface with no body primitives and no details renders nothing. */
+function hasContent(record) {
+    const body = record.body;
+    if (body === undefined)
+        return record.details !== undefined;
+    return (body.line !== undefined ||
+        (body.rows !== undefined && body.rows.length > 0) ||
+        body.gauge !== undefined ||
+        (body.ledger !== undefined && body.ledger.length > 0) ||
+        record.details !== undefined);
+}
+/** The one-line summary (status/footer zones). */
+function summaryOf(record) {
+    const body = record.body;
+    if (body?.line !== undefined)
+        return lineText(body.line);
+    if (body?.rows !== undefined && body.rows.length > 0) {
+        const visible = body.rows.filter((row) => row.quiet !== true);
+        if (visible.length === 0)
+            return record.key;
+        return `${record.key}: ${visible.map((row) => row.label).join(", ")}`;
+    }
+    if (body?.gauge !== undefined) {
+        const percent = body.gauge.percent === undefined ? "" : ` ${body.gauge.percent}%`;
+        return `${body.gauge.label}${percent}`;
+    }
+    if (body?.ledger !== undefined && body.ledger.length > 0) {
+        return body.ledger[body.ledger.length - 1]?.summary ?? record.key;
+    }
+    return `[${record.key}]`;
+}
+function lineText(line) {
+    if (line.segments !== undefined && line.segments.length > 0) {
+        return line.segments.map((segment) => segment.text).join(" ");
+    }
+    return line.text ?? "";
+}
+/** The full panel-zone rendering of one record. */
+function panelBlock(record) {
+    const body = record.body;
+    const lines = [];
+    lines.push(record.owner === "" ? `[${record.key}]` : `[${record.key}] ${record.owner}`);
+    if (body?.line !== undefined)
+        lines.push(lineText(body.line));
+    if (body?.rows !== undefined && body.rows.length > 0) {
+        lines.push(...rowLines(body.rows));
+    }
+    if (body?.gauge !== undefined) {
+        const gauge = body.gauge;
+        let header = gauge.label;
+        if (gauge.phase !== undefined)
+            header += ` · ${gauge.phase}`;
+        if (gauge.elapsedMs !== undefined) {
+            header += ` · ${(gauge.elapsedMs / 1000).toFixed(1)}s`;
+        }
+        lines.push(header);
+        if (gauge.percent !== undefined) {
+            const filled = Math.max(0, Math.min(GAUGE_CELLS, Math.round(gauge.percent / GAUGE_CELLS)));
+            lines.push(`[${"#".repeat(filled)}${"-".repeat(GAUGE_CELLS - filled)}] ${gauge.percent}%`);
+        }
+        if (gauge.checks !== undefined && gauge.checks.length > 0) {
+            lines.push(...rowLines(gauge.checks));
+        }
+        if (gauge.recentOutput !== undefined && gauge.recentOutput.length > 0) {
+            lines.push(...gauge.recentOutput.slice(-3));
+        }
+    }
+    if (body?.ledger !== undefined && body.ledger.length > 0) {
+        for (const entry of [...body.ledger].reverse()) {
+            const detail = entry.detail === undefined || entry.detail.length === 0
+                ? ""
+                : ` — ${entry.detail.join(" · ")}`;
+            lines.push(`${entry.kind} ${entry.summary}${detail}`);
+        }
+    }
+    if (record.details !== undefined) {
+        lines.push(`[details] ${JSON.stringify(record.details)}`);
+    }
+    return lines;
+}
+/** Rows: severity-sorted (ties by id), quiet folded into "+N quiet". */
+function rowLines(rows) {
+    const sorted = [...rows].sort((a, b) => {
+        const severityA = a.severity ?? 2;
+        const severityB = b.severity ?? 2;
+        if (severityA !== severityB)
+            return severityA - severityB;
+        return a.id < b.id ? -1 : 1;
+    });
+    const visible = sorted.filter((row) => row.quiet !== true);
+    const quietCount = sorted.length - visible.length;
+    const lines = visible.map(rowLine);
+    if (quietCount > 0)
+        lines.push(`+${quietCount} quiet`);
+    return lines;
+}
+function rowLine(row) {
+    const indent = "  ".repeat(row.depth ?? 0);
+    const glyph = row.status ?? "·";
+    let line = `${indent}${glyph} ${row.label}`;
+    if (row.spinnerLabel !== undefined)
+        line += ` ${row.spinnerLabel}`;
+    if (row.detail !== undefined)
+        line += ` — ${row.detail}`;
+    if (row.deps !== undefined && row.deps.length > 0) {
+        line += ` ⛓ ${row.deps.join(",")}`;
+    }
+    const metrics = metricsText(row.metrics);
+    if (metrics !== "")
+        line += ` ${metrics}`;
+    return line;
+}
+function metricsText(metrics) {
+    if (metrics === undefined)
+        return "";
+    const parts = [];
+    if (metrics.tokens !== undefined) {
+        parts.push(`tok ${formatMetric(metrics.tokens, metrics.format)}`);
+    }
+    if (metrics.cost !== undefined) {
+        parts.push(`$${metrics.cost.toFixed(4)}`);
+    }
+    if (metrics.total !== undefined) {
+        parts.push(`${metrics.completed ?? metrics.current ?? 0}/${metrics.total}`);
+    }
+    else if (metrics.current !== undefined) {
+        parts.push(`cur ${metrics.current}`);
+    }
+    return parts.join(" · ");
+}
+/** The webui's metric formatting (compact / usd / percent hints). */
+function formatMetric(value, format) {
+    if (format === "usd")
+        return `$${value.toFixed(4)}`;
+    if (format === "percent")
+        return `${Math.round(value * 100)}%`;
+    if (format === "compact" && Math.abs(value) >= 1000) {
+        return `${(value / 1000).toFixed(1)}k`;
+    }
+    return String(value);
+}

package/dist/ui/app.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The TUI shell (Task 6): sidebar left, conversation pane right, composer
+ * footer — pi's idiom over the Task 4 client layers.
+ *
+ * File naming (the controller's pick-one ruling): plain `.ts` — pi-tui is
+ * not React (components are `render(width): string[]` classes), so the
+ * plan's `app.tsx` alternative does not apply.
+ *
+ * Layout: {@link TuiApp} is a `VStack`: the body row (`HStack`: sidebar
+ * at a fixed basis, pane growing), then the interaction seam's prompt
+ * strip (Task 8 — the pending stack, answerable via ctrl+o + digits), then
+ * the ambient chrome (panel/footer/statusline zones by the record's
+ * `place`). Both strips collapse to zero height when empty. The composer
+ * is a pi-tui `Editor` the launcher mounts after the app on the TUI root —
+ * pi's idiom is `TuiMainScreen` (the terminal owns scrollback; chat content
+ * scrolls, the editor anchors the bottom as the last child). Viewport
+ * `VStack`/`ScrollView` layouts are alt-screen-only (pi-tui 1.3.0), so the
+ * footer composition lives in the launcher, not the app component.
+ *
+ * Wiring: the sidebar refreshes from `listConversations()`; selecting a
+ * conversation swaps the pane's `watchConversation` subscription (the old
+ * watch is closed before the new one opens); stream frames REPLACE the
+ * pane (the SSE contract — a snapshot subsumes missed frames); the
+ * composer submits fire-and-forget via `submit(id, text)` — the stream is
+ * the source of truth for the reply (spec §10's composer rule). The fork
+ * action (`forkActive`, driven by the `/fork` slash command; task C3's
+ * action layer reintroduces a keybinding) calls
+ * `forkConversation(id)` at the latest entry (the v1 default, spec §8),
+ * refreshes the sidebar, and switches to the fork.
+ *
+ * Composer behaviors (Task 7): the composer tracks the wire's `steer.busy`
+ * per frame; submitting while busy sends `whenBusy: "steer"`. Esc during a
+ * live run aborts (the binding rides the launcher's pre-editor global
+ * listener through {@link handleKeybinding} — pi-tui 1.3.0's `Editor` has
+ * no escape hook of its own). A `/`-prefixed line routes through the
+ * slash-command catalog (`getCommands()`, fetched once and cached by
+ * {@link SlashCatalog}); unknown commands render a clear error. The POST's
+ * immediate failure (4xx) and the abort outcomes render as pane
+ * error/notice lines — the pane keeps rendering the reply off the stream.
+ *
+ * Sidebar focus (fix wave F2): the sidebar is the switcher (spec §2), so it
+ * must be keyboard-reachable — ctrl+b toggles key routing between the
+ * composer and the conversation list; a selection (or a second ctrl+b)
+ * returns keys to the composer. Guarded actions (fix wave F1): every
+ * fire-and-forget mutation path (`+ new`, conversation select, ctrl+f
+ * fork) catches its rejection into a pane error line — a flaky remote must
+ * never crash the process on an unhandled rejection.
+ */
+import { Editor, type Component, type TUI } from "@earendil-works/pi-tui";
+import type { SigrunClient } from "../api.js";
+import { type Unwatch, type WatchHandlers, type WatchOptions } from "../sse.js";
+import type { TuiTheme } from "../theme.js";
+import type { Action, ActionHost, Focus } from "../actions.js";
+import { AmbientChrome } from "./ambient.js";
+import { ConversationPane } from "./conversation-pane.js";
+import { InteractionPrompter } from "./interactions.js";
+import { Sidebar } from "./sidebar.js";
+import type { StatusBar } from "./status-bar.js";
+/** The watch injection seam (tests stub it; the launcher uses the real one). */
+export type WatchFn = (conversationId: number, handlers: WatchHandlers, options: WatchOptions) => Unwatch;
+export interface TuiAppOptions {
+    /** The pi-tui instance (the Editor needs it for height-aware scrolling). */
+    readonly tui: TUI;
+    /** The stream watcher; defaults to Task 4's `watchConversation`. */
+    readonly watch?: WatchFn;
+    /** The watcher's transport options (baseUrl + user); defaults to none. */
+    readonly watchOptions?: WatchOptions;
+    /** The sidebar's fixed column basis (default 24). */
+    readonly sidebarWidth?: number;
+    /** The token theme (C1/C2); defaults to the plain identity fallback. */
+    readonly theme?: TuiTheme;
+    /** The tui.json `editor` field (C1; used when it names a vim binary). */
+    readonly editor?: string;
+    /** TEST SEAM: the vim resolution for edit-in-vim (C4). */
+    readonly resolveVim?: () => string | undefined;
+}
+export declare class TuiApp implements Component, ActionHost {
+    #private;
+    /** The sidebar (the app mounts it; tests drive it). */
+    readonly sidebar: Sidebar;
+    /** The conversation pane (the stream replaces its contents). */
+    readonly pane: ConversationPane;
+    /** The composer (the launcher mounts it after the app + focuses it). */
+    readonly editor: Editor;
+    /** The interaction seam's prompt strip (Task 8; zero height when empty). */
+    readonly interactions: InteractionPrompter;
+    /** The ambient seam's chrome zones (Task 8; zero height when empty). */
+    readonly ambient: AmbientChrome;
+    /** The quit sink: the launcher's exit resolution. */
+    onQuit: (() => void) | undefined;
+    constructor(client: SigrunClient, options: TuiAppOptions);
+    /** The active conversation id (undefined before the first refresh). */
+    get activeConversationId(): number | undefined;
+    /** The focused region (the action layer's routing state). */
+    get focus(): Focus;
+    /** A modal overlay (picker/search) owns the keys. */
+    get overlayOpen(): boolean;
+    /** The last frame's `steer.busy` (the keymap's abort gate). */
+    get busy(): boolean;
+    /**
+     * The launcher's sink: the status bar it mounted (flashes, help, and
+     * the search overlay render through it). `set` also snapshots the
+     * launcher's steady state so a flash can restore it.
+     */
+    setStatusBar(statusBar: StatusBar): void;
+    /**
+     * Refresh the sidebar listing. Boot selects the first conversation;
+     * later refreshes keep the current selection.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Swap the pane to `id`: close the old watch, open the new one. The
+     * composer is disabled for the swap's duration (review finding): a
+     * submission must never split from the pane it was typed against, so
+     * Enter cannot fire `onSubmit` mid-swap (pi-tui's `disableSubmit`
+     * gates the submit path).
+     */
+    selectConversation(id: number): Promise<void>;
+    /**
+     * Stream-error sink: the launcher wires this to the stream-health
+     * notices (fix wave F5 — "stream: disconnected" on the first failure,
+     * "stream: reconnected" on the next open). The generation guard above
+     * fences STALE watches' errors so they can't reach whatever is mounted
+     * here.
+     */
+    onWatchError?: (message: string) => void;
+    /**
+     * Stream-open sink (fix wave F5): fires on every (re)connect of the
+     * CURRENT watch — the recovery half of the launcher's stream-health
+     * notices. Generation-guarded like {@link onWatchError}.
+     */
+    onWatchOpen?: () => void;
+    /** Create a conversation (`+ new`), refresh the sidebar, select it. */
+    createAndSelect(): Promise<void>;
+    /**
+     * Fork the active conversation at the latest entry (the v1 default,
+     * spec §8), refresh the sidebar, and switch to the fork. No-op with no
+     * active conversation.
+     */
+    forkActive(): Promise<void>;
+    /**
+     * The launcher's global keybinding seam: ctrl+o enters the interaction
+     * seam's answer mode; Esc during a live run aborts it (the composer
+     * idiom — the launcher routes input through here before the editor sees
+     * it, so Esc while busy never reaches the editor). Returns true when the
+     * key was consumed. Task C1b removed ctrl+b (sidebar focus) and ctrl+f
+     * (fork): task C3's action layer reintroduces navigation — until then
+     * the mouse drives the sidebar and `/fork` carries the fork.
+     */
+    handleKeybinding(data: string): boolean;
+    /** Close the stream subscription + seam pollers (the launcher calls this on exit). */
+    dispose(): void;
+    /**
+     * The keymap's context: focus, busy, autocomplete, overlay. The
+     * composer's autocomplete state is internal to pi-tui's Editor (no
+     * public getter), so the flag is a projection — the composer is the
+     * default focus and the editor cancels autocomplete before any
+     * focus-leaving key the keymap would act on.
+     */
+    keyContext(): {
+        focus: Focus;
+        busy: boolean;
+        autocompleteOpen: boolean;
+        overlayOpen: boolean;
+    };
+    /** Run one action (the keymap's / pickers' / mouse's single seam). */
+    dispatch(action: Action): Promise<void>;
+    /**
+     * The launcher's keymap seam (C5 fix): the active keymap's
+     * `hints(ctx)` for the current {@link keyContext}. Wired once at
+     * launch; {@link refreshHints} re-polls it on every focus change
+     * (and the launcher re-polls after each key for vim mode changes).
+     */
+    hintsProvider: (() => readonly string[]) | undefined;
+    /**
+     * Re-poll the keymap's hints into the status bar's steady state.
+     * A transient flash or the search overlay owns the bar's right
+     * cluster until it restores the snapshot, so only the snapshot is
+     * updated while one is up (the restore paints the fresh hints).
+     */
+    refreshHints(): void;
+    /**
+     * The vim command line's command table (Task C4). A `/`-prefixed line
+     * (or any name outside the table) routes through the existing slash
+     * catalog — the table holds only the vim-native commands.
+     */
+    runCommand(line: string): Promise<void>;
+    /** The launcher's vim-keymap seam: re-enter INSERT after edit-in-vim. */
+    enterInsertMode: (() => void) | undefined;
+    /**
+     * The launcher's help-overlay seam (C5): opens the key reference for
+     * the active keymap; the callback fires when the overlay closes.
+     */
+    helpOverlay: ((onClose: () => void) => void) | undefined;
+    /**
+     * The slash catalog's command names (C3's picker source, cached) —
+     * the launcher feeds them to the vim `:` Tab completion.
+     */
+    slashCommandNames(): Promise<string[]>;
+    /**
+     * The vim keymap's status-bar seam (Task C4): the app polls the keymap
+     * after each key. `commandLine` set → the bar shows the `:` line;
+     * otherwise the steady state is restored with the keymap's mode chip
+     * in the `mode` segment.
+     */
+    renderCommandLine(commandLine: string | undefined, modeLabel: string | undefined): void;
+    render(width: number): string[];
+    invalidate(): void;
+}