@sigrun/tui 0.4.1 → 0.5.0

package/dist/ui/app.d.ts

@@ -0,0 +1,319 @@
+/**
+ * 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 { JsonObject } from "@sigrun/shared/blocks";
+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 { SettingsView } from "./settings.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;
+/**
+ * How long the restart-recovery poll waits for /readyz before giving up
+ * with a permanent error (U4 Task 2, spec §13.3). DUPLICATE of the
+ * webui's `RESTART_READYZ_DEADLINE_MS` (webui/src/App.tsx) by design:
+ * the tui package consumes only `@sigrun/shared` wire types (NodeNext,
+ * no codegen), and a shared-module move for one number is not worth the
+ * coupling — keep the two in sync by hand.
+ */
+export declare const RESTART_READYZ_DEADLINE_MS = 60000;
+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;
+    /**
+     * The restart-recovery poll cadence (U4 Task 2, spec §13.3): the
+     * `/readyz` probe interval after `restart()` — default 500 ms; the
+     * tests shorten it.
+     */
+    readonly restartPollMs?: number;
+    /**
+     * TEST SEAM (U4 Task 2 round-2): the restart-recovery deadline —
+     * how long the poll waits for /readyz before surfacing the stalled
+     * restart as a permanent error notice. Default
+     * {@link RESTART_READYZ_DEADLINE_MS}; the deadline test shortens it.
+     */
+    readonly restartDeadlineMs?: number;
+}
+/** The main column's swap slot (U4 Task 4 round-2): renders the
+ *  conversation pane, or the open settings view while one is up.
+ *  The launcher mounts this slot (in its ScrollView) so the swap is
+ *  visible — a settings view rendered only in `TuiApp.render`'s
+ *  fallback path never paints in the launcher's composition. */
+export declare class MainSlot implements Component {
+    #private;
+    constructor(child: Component);
+    /** Swap the rendered child (the conversation pane ↔ settings view). */
+    set(child: Component): void;
+    /** The current child (tests assert the swap). */
+    get current(): Component;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+}
+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 main column's slot: renders the conversation pane normally,
+     *  the open settings view while one is up (U4 Task 4 round-2 — the
+     *  settings view renders IN the body slot; the launcher's root
+     *  scrolls this slot, so a `#settingsView`-only render would paint
+     *  nothing and swallow keys). Exported for the launcher's mount. */
+    readonly mainContent: MainSlot;
+    /** 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 launcher's hello hook (U3 Task 5): the stream id feeds
+     *  future openExtView transports; an OPEN view's handle gets the
+     *  new id at once (its next fetch re-registers the watcher entry —
+     *  spec §7.3's reconnect rule; the webui twin remounts instead). */
+    setEventsStreamId(streamId: string): void;
+    /** The open extension view's identity (undefined = the conversation
+     *  pane is the main content). */
+    get extView(): {
+        readonly slug: string;
+        readonly id: string;
+    } | undefined;
+    /**
+     * Open an extension VIEW in the main pane (U3 Task 5, spec §7.1):
+     * the sidebar's view selection swaps the pane's content to the
+     * surface's transport. The block renderer is U2's; the app holds
+     * the transport + identity here so U2's mount is one prop pass.
+     */
+    openExtView(slug: string, id: string, params?: JsonObject): Promise<void>;
+    /**
+     * Open the settings view (U4 Task 4, spec §13.4): `/settings` mounts
+     * the SettingsView (the sections list + the search picker over the
+     * index); Esc closes it back to the conversation.
+     */
+    openSettings(): Promise<void>;
+    /** The open settings view (tests drive it). */
+    get settingsView(): SettingsView | undefined;
+    /**
+     * Close the open settings view (Esc). Returns true when one was open.
+     */
+    closeSettings(): boolean;
+    /**
+     * Close the open extension view (the Esc/back idiom): the pane
+     * returns to the conversation AND the surface's fetches stop — no
+     * cadence, no keepalive for a surface nobody is looking at (spec
+     * §7.3's stop-when-hidden rule; U2's cadence timer consults this).
+     * Returns true when a view was open (the key was consumed).
+     */
+    closeExtView(): boolean;
+    /** The app-level surface.changed dispatch (the launcher's
+     *  `watchEvents` onEvent routes events here). */
+    dispatchSurfaceChanged(event: {
+        slug: string;
+        id: string;
+        k: string;
+        rev: number;
+        treeRev: number;
+    }): void;
+    /** The chat member of `surface.changed` (U5 Task 4): fan the
+     *  conversation-scoped frame into the chat hub. */
+    dispatchChatSurfaceChanged(event: {
+        conversationId: number;
+        entryId: string;
+        rev: number;
+    }): void;
+    /** 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 admin restart surface (U4 Task 2, spec §13.3): POST
+     * `/v1/admin/restart`, show the "Restarting…" notice, and poll
+     * `/readyz` — when it answers, the supervisor brought the server
+     * back, so refresh the sidebar (the durable listing) and clear the
+     * notice. A rejected POST (403/409 — no restart began) renders the
+     * error and returns without touching state. Resolves once the
+     * recovery poll ends (recovered or disposed).
+     */
+    restart(): Promise<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;
+}