@sigrun/tui 0.1.0 → 0.2.0

package/dist/ui/ambient.js

@@ -1,301 +0,0 @@
-/**
- * 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

@@ -1,209 +0,0 @@
-/**
- * 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;
-}