@sigrun/tui 0.0.0-stage → 0.1.1

package/dist/launch.js

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+/**
+ * The TUI entry the CLI's default `launchTui` runs (Task 6): boot the
+ * pi-tui fullscreen alt-screen renderer (task C1b — the terminal scrollback
+ * is gone for the session; the app owns the viewport), mount the layout
+ * root, and resolve when the user exits (ctrl+c). The CLI's `run`
+ * lifecycle owns the shutdown from there — this promise resolving IS the
+ * exit signal. There is no main-screen fallback.
+ *
+ * As of build-and-webui Task 2 this file is ALSO the package's bin
+ * (`sigrun-tui` → `dist/launch.js`): the CLI no longer imports
+ * `launchTuiShell` in-process — it spawns this bin as a child process
+ * (`node <resolved dist/launch.js>`), passing the resolved server URL,
+ * user, and tui.json UI fields as `--flags`. Run standalone, the bin
+ * resolves them itself: `--server`/`SIGRUN_SERVER` (default
+ * `http://localhost:$SIGRUN_PORT` or 3000) and `--user`/`SIGRUN_USER`.
+ *
+ * Layout (task C1b): `tui.setLayoutRoot(new VStack([...]))` — the body row
+ * (`HStack`: the sidebar at basis 28, visible only at width ≥ 80, and the
+ * pane wrapped in the follow-end PRIMARY ScrollView growing to fill), then
+ * the interaction + ambient seam strips (basis "auto" — zero height when
+ * empty), the composer Editor (basis "auto"), and the status bar pinned to
+ * one line at the bottom (basis 1).
+ *
+ * Keybindings: BEFORE the screen is constructed, the alt-screen built-ins
+ * the action layer will own are disabled (search, search next/previous,
+ * previous/next prompt — the built-ins search raw lines and jump OSC 133
+ * marks sigrun never emits); pageUp/pageDown/ctrl+home/ctrl+end scrolling
+ * and the wheel stay. The shell's global input listener keeps ctrl+c
+ * (exit), ctrl+o (answer mode), and Esc (abort a live run); task C3's
+ * action layer reintroduces navigation — until then the composer is the
+ * focus and the mouse drives the sidebar.
+ *
+ * Test seams (the shell itself needs a real terminal): `screen` injects
+ * the screen constructor (tests assert TuiAltScreen's arguments), and
+ * `terminal`/`fetchFn` inject the terminal and boot fetch. Production
+ * callers pass none of them.
+ */
+import { getTerminalColorMode, HStack, KeybindingsManager, ProcessTerminal, ScrollView, setKeybindings, TUI_KEYBINDINGS, TuiAltScreen, VStack, } from "@earendil-works/pi-tui";
+import { isAccentName, isPaletteName, } from "@sigrun/shared/themes";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { SigrunClient, SigrunApiError } from "./api.js";
+import { watchEvents } from "./sse.js";
+import { createStandardKeymap } from "./keymaps/standard.js";
+import { createVimKeymap } from "./keymaps/vim.js";
+import { createEmacsKeymap } from "./keymaps/emacs.js";
+import { createTuiTheme } from "./theme.js";
+import { TuiApp } from "./ui/app.js";
+import { showHelp } from "./ui/help.js";
+import { StatusBar } from "./ui/status-bar.js";
+/** The sidebar's fixed column basis, and the width gate below which it hides. */
+const SIDEBAR_BASIS = 28;
+const SIDEBAR_MIN_WIDTH = 80;
+/**
+ * Install the shell's keybinding set (task C1b): the alt-screen built-ins
+ * for search and prompt jumps go dark — the action layer owns them (they
+ * must target turns and move focus; the built-ins search raw lines and
+ * jump OSC 133 marks sigrun never emits). Page/line/home/end scrolling
+ * and the wheel stay. Must run BEFORE the screen is constructed.
+ */
+function installKeybindings() {
+    setKeybindings(new KeybindingsManager(TUI_KEYBINDINGS, {
+        "tui.altScreen.search": [],
+        "tui.altScreen.searchNext": [],
+        "tui.altScreen.searchPrevious": [],
+        "tui.altScreen.previousPrompt": [],
+        "tui.altScreen.nextPrompt": [],
+    }));
+}
+/**
+ * The stream-health transition notices (fix wave F5): state-deduped, so a
+ * reconnect storm shows ONE "disconnected" and ONE "reconnected", never a
+ * pane full of retries. Exported for the unit test (the shell itself needs
+ * a real terminal).
+ */
+export function createStreamHealthNotices(notify) {
+    let down = false;
+    return {
+        onError() {
+            if (down)
+                return;
+            down = true;
+            notify("stream: disconnected");
+        },
+        onOpen() {
+            if (!down)
+                return;
+            down = false;
+            notify("stream: reconnected");
+        },
+    };
+}
+/**
+ * Run the shell against `baseUrl` until the user exits. Boot failures
+ * (the initial refresh rejecting) propagate — the CLI prints and exits 1.
+ */
+export async function launchTuiShell(options) {
+    const client = new SigrunClient({
+        baseUrl: options.baseUrl,
+        ...(options.user === undefined ? {} : { user: options.user }),
+        ...(options.token === undefined ? {} : { token: options.token }),
+        ...(options.fetchFn === undefined ? {} : { fetch: options.fetchFn }),
+    });
+    const terminal = options.terminal ?? new ProcessTerminal();
+    // The alt-screen screen consults the global keybindings at construction
+    // (its input listener), so the disables must be installed first.
+    installKeybindings();
+    const createScreen = options.screen ??
+        ((t, hw, log, opts) => new TuiAltScreen(t, hw, log, opts));
+    const tui = createScreen(terminal, false, undefined, {
+        mouse: true,
+        copyOnSelect: true,
+    });
+    const theme = createTuiTheme({
+        palette: options.palette ?? "polar-night",
+        accent: options.accent ?? "baltic-amber",
+        mode: options.mode ?? "dark",
+        colorMode: getTerminalColorMode(),
+    });
+    const app = new TuiApp(client, {
+        // The app needs pi-tui's TUI surface for the Editor + repaint
+        // pings; the constructed screen provides it.
+        // SAFETY: TuiAltScreen implements TUI's render/input surface (pi-tui's
+        // own TUI is exactly this shape); the seam type only narrows tests.
+        tui: tui,
+        watchOptions: {
+            baseUrl: options.baseUrl,
+            ...(options.user === undefined ? {} : { user: options.user }),
+            ...(options.token === undefined ? {} : { token: options.token }),
+        },
+        ...(options.editor === undefined ? {} : { editor: options.editor }),
+        theme,
+    });
+    // Fix wave F5: surface stream transport health as transition notices.
+    const streamHealth = createStreamHealthNotices((message) => app.pane.showNotice(message));
+    app.onWatchError = streamHealth.onError;
+    app.onWatchOpen = streamHealth.onOpen;
+    // The fullscreen layout root (task C1b): the app owns the components
+    // (TuiApp.render stays as the non-mounted fallback path); the launcher
+    // composes them here. The pane sits in the follow-end PRIMARY scroll
+    // view (the wheel + page keys target it); the status bar's mode chip
+    // rides the theme's accent background (StatusBar owns that styling).
+    const statusBar = new StatusBar({ theme });
+    // C3/C4/C5: the keymap comes from the tui.json `keymap` option
+    // (standard is the default). The vim `:` Tab completion merges the
+    // slash catalog — a shared array the keymap reads live, filled by the
+    // fetch below.
+    const vimCatalogNames = [];
+    const keymap = options.keymap === "vim"
+        ? createVimKeymap({ catalogNames: vimCatalogNames })
+        : options.keymap === "emacs"
+            ? createEmacsKeymap()
+            : createStandardKeymap();
+    // C5: the bar's hint cluster is the keymap's `hints(ctx)` — the app
+    // re-polls it on every focus change (and after each key below, so a
+    // vim mode change repaints too). Boot paints the composer-focused
+    // steady state.
+    app.hintsProvider = () => keymap.hints(app.keyContext());
+    statusBar.set({
+        mode: "attach",
+        conversation: "",
+        hints: keymap.hints({ focus: "composer", busy: false, autocompleteOpen: false, overlayOpen: false }),
+    });
+    // C3: the app flashes copy/configure/help/search through the bar.
+    app.setStatusBar(statusBar);
+    // C5: the `help` action opens the key reference overlay for the
+    // active keymap (the app owns the overlayOpen bookkeeping).
+    // SAFETY: same TuiAltScreen-as-TUI surface as the TuiApp seam above.
+    app.helpOverlay = (onClose) => showHelp(tui, keymap, { onClose });
+    if (keymap.name === "vim") {
+        statusBar.set({ ...statusBar.getState(), mode: keymap.modeLabel() ?? "attach" });
+        const vim = keymap;
+        // Post edit-in-vim the keymap follows the composer focus back to INSERT.
+        app.enterInsertMode = () => vim.enterInsertMode();
+        // The `:` Tab completion also completes the slash catalog (fire-and-
+        // forget: completion works on the vim table until the fetch lands).
+        void app
+            .slashCommandNames()
+            .then((names) => vimCatalogNames.push(...names))
+            .catch(() => { }); // a failed catalog fetch degrades completion only
+    }
+    const body = new HStack([
+        {
+            component: app.sidebar,
+            basis: SIDEBAR_BASIS,
+            visible: (viewport) => viewport.width >= SIDEBAR_MIN_WIDTH,
+        },
+        {
+            component: new ScrollView(app.pane, {
+                follow: "end",
+                primary: true,
+                overscroll: "chain",
+            }),
+            grow: 1,
+        },
+    ]);
+    const root = new VStack([
+        { component: body, grow: 1 },
+        { component: app.interactions, basis: "auto" },
+        { component: app.ambient, basis: "auto" },
+        { component: app.editor, basis: "auto" },
+        { component: statusBar, basis: 1 },
+    ]);
+    tui.setLayoutRoot(root);
+    await app.refresh();
+    // U3 Task 5: the sidebar's Views group loads with the conversations
+    // (one /v1/extensions GET per boot; failures fail quiet).
+    void app.sidebar.refreshViews().catch(() => { });
+    // The host events subscription (core hardening W3 Task 4, spec §7.4):
+    // ONE stream per process replaces the poll timers — `conversation.*`
+    // refetches the sidebar listing, `interaction.*` kicks the prompter,
+    // `ambient.changed` refetches the ambient chrome. A transport failure
+    // surfaces as a pane notice (the same posture as the conversation
+    // watcher's stream-health wiring); the events stream only NUDGES, so
+    // a dropped frame heals on the next event.
+    const unwatchEvents = watchEvents({
+        onEvent: (event) => {
+            if (event.type === "conversation.created" ||
+                event.type === "conversation.changed") {
+                void app.refresh().catch(() => { }); // a failed refetch fails quiet
+            }
+            else if (event.type === "interaction.pending" ||
+                event.type === "interaction.settled") {
+                app.interactions.kick();
+            }
+            else if (event.type === "ambient.changed") {
+                app.ambient.kick(event.conversationId);
+            }
+            else if (event.type === "surface.changed") {
+                // U3 Task 5: fan the surface event out to the open
+                // view's transport (the hub matches slug+id+k).
+                app.dispatchSurfaceChanged(event);
+            }
+        },
+        onError: (message) => app.pane.showNotice(message),
+        // U3 Task 5 (§7.3): the hello frame's streamId is the watcher
+        // entry's stream — open ext-view transports send it as
+        // X-Sigrun-Stream. A reconnect's new id re-registers on the
+        // next fetch.
+        onHello: (streamId) => app.setEventsStreamId(streamId),
+    }, {
+        baseUrl: options.baseUrl,
+        ...(options.user === undefined ? {} : { user: options.user }),
+        ...(options.token === undefined ? {} : { token: options.token }),
+    });
+    const done = new Promise((resolve) => {
+        app.onQuit = resolve;
+        tui.addInputListener((data) => {
+            // The seam prompts (answer mode, the search overlay) own their
+            // keys before the keymap sees them.
+            if (app.handleKeybinding(data)) {
+                return { consume: true };
+            }
+            // C3: the keymap decides — dispatch, consume, or pass through
+            // to the focused component (the composer owns the rest).
+            const result = keymap.handle(data, app.keyContext());
+            if (result === "pass")
+                return undefined;
+            if (result !== "consume")
+                void app.dispatch(result);
+            // C4: the vim keymap's mode chip + ":" command line repaint after
+            // each key (the app polls — the keymap owns the buffer).
+            if (keymap.name === "vim") {
+                const vim = keymap;
+                app.renderCommandLine(vim.getCommandLine(), vim.modeLabel());
+            }
+            // C5: a key may change the keymap's hint state (vim mode, focus
+            // via dispatch) — re-poll the hints after every handled key.
+            app.refreshHints();
+            return { consume: true };
+        });
+    });
+    tui.setFocus(app.editor);
+    tui.start();
+    try {
+        await done;
+    }
+    finally {
+        unwatchEvents();
+        app.dispose();
+        tui.stop();
+    }
+}
+/**
+ * The `sigrun-tui` bin's usage line (parse failures print it + the
+ * reason, exit 1).
+ */
+const TUI_USAGE_TEXT = `usage: sigrun-tui [--server <url>] [--user <name>]
+       [--palette <name>] [--accent <name>] [--mode dark|light]
+       [--keymap standard|vim|emacs] [--editor <command>]`;
+/** Every flag {@link parseTuiLaunchArgs} accepts, with its validator. */
+const TUI_FLAGS = {
+    "--server": (value) => (value === "" ? undefined : value),
+    "--user": (value) => (value === "" ? undefined : value),
+    "--palette": (value) => (isPaletteName(value) ? value : undefined),
+    "--accent": (value) => (isAccentName(value) ? value : undefined),
+    "--mode": (value) => value === "dark" || value === "light" ? value : undefined,
+    "--keymap": (value) => value === "standard" || value === "vim" || value === "emacs"
+        ? value
+        : undefined,
+    "--editor": (value) => (value === "" ? undefined : value),
+};
+/**
+ * Parse the bin's argv (post-`node` slices): every entry must be a known
+ * flag followed by a value. A validator returning `undefined` means the
+ * VALUE was malformed for that flag (not a parse-usage error) — it is
+ * reported naming the flag's expected form.
+ */
+export function parseTuiLaunchArgs(argv) {
+    const args = {};
+    let index = 0;
+    while (index < argv.length) {
+        const flag = argv[index];
+        const parse = TUI_FLAGS[flag];
+        if (parse === undefined) {
+            throw new Error(`unknown argument ${JSON.stringify(flag)}\n${TUI_USAGE_TEXT}`);
+        }
+        const raw = argv[index + 1];
+        if (raw === undefined || raw.startsWith("--")) {
+            throw new Error(`${flag} requires a value\n${TUI_USAGE_TEXT}`);
+        }
+        const value = parse(raw);
+        if (value === undefined) {
+            throw new Error(`${flag} does not accept ${JSON.stringify(raw)}\n${TUI_USAGE_TEXT}`);
+        }
+        // SAFETY: each TUI_FLAGS entry's validator only returns the value
+        // type its key names (the Record's value union is exactly the
+        // per-flag literal unions of TuiLaunchArgs).
+        args[flag.slice(2)] = value;
+        index += 2;
+    }
+    return args;
+}
+/**
+ * The standalone default server URL: `http://localhost:$SIGRUN_PORT`
+ * (3000 when unset). A malformed `SIGRUN_PORT` fails loud naming the
+ * variable — the same posture as the core CLI's port parsing.
+ */
+function defaultBaseUrl(env) {
+    const raw = env.SIGRUN_PORT;
+    let port = 3000;
+    if (raw !== undefined && raw !== "") {
+        port = Number(raw);
+        if (!Number.isInteger(port) || port <= 0) {
+            throw new Error(`SIGRUN_PORT must be a positive integer, got ${raw}`);
+        }
+    }
+    return `http://localhost:${port}`;
+}
+/**
+ * Resolve the bin's launch options from its parsed flags + environment
+ * (Task 7): server (`--server` > `SIGRUN_SERVER` > the localhost default),
+ * user (`--user` > `SIGRUN_USER`), token (`SIGRUN_TOKEN` ONLY — there is
+ * deliberately no `--token` flag; a credential never rides argv), and
+ * the tui.json UI fields the CLI threads through as flags.
+ */
+export function launchOptionsFrom(args, env) {
+    const token = env.SIGRUN_TOKEN?.trim();
+    return {
+        baseUrl: args.server ?? env.SIGRUN_SERVER ?? defaultBaseUrl(env),
+        ...(args.user === undefined && env.SIGRUN_USER === undefined
+            ? {}
+            : { user: (args.user ?? env.SIGRUN_USER) }),
+        ...(token === undefined || token === "" ? {} : { token }),
+        ...(args.palette === undefined ? {} : { palette: args.palette }),
+        ...(args.accent === undefined ? {} : { accent: args.accent }),
+        ...(args.mode === undefined ? {} : { mode: args.mode }),
+        ...(args.keymap === undefined ? {} : { keymap: args.keymap }),
+        ...(args.editor === undefined ? {} : { editor: args.editor }),
+    };
+}
+/**
+ * The dedicated startup-failure message for a server still in its
+ * unclaimed state (Task 7): a standalone `sigrun-tui` that hits the
+ * setup gate exits with the `sigrun attach` onboarding hint instead of
+ * a bare 403. Any other failure maps to `undefined` (the generic path).
+ */
+export function tuiStartupMessage(error) {
+    if (error instanceof SigrunApiError && error.status === 403) {
+        const body = error.body;
+        if (body?.error === "setup_required") {
+            return "server is not set up — run `sigrun attach` to onboard";
+        }
+    }
+    return undefined;
+}
+/**
+ * The bin's `main`: resolve the launch options (flags + env, see
+ * {@link launchOptionsFrom}) and run {@link launchTuiShell}. Returns the
+ * process exit code (0 clean; 1 on a usage error or a boot failure,
+ * with the message printed — the setup-gate failure carries its own
+ * `sigrun attach` onboarding hint).
+ */
+export async function tuiMain(argv = process.argv.slice(2), env = process.env, io = { error: (text) => console.error(text) }) {
+    let args;
+    try {
+        args = parseTuiLaunchArgs(argv);
+    }
+    catch (error) {
+        io.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    try {
+        await launchTuiShell(launchOptionsFrom(args, env));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const startup = tuiStartupMessage(error);
+        io.error(startup === undefined
+            ? message.startsWith("sigrun-tui:")
+                ? message
+                : `sigrun-tui: ${message}`
+            : `sigrun-tui: ${startup}`);
+        return 1;
+    }
+}
+// Script detection (the bin entry): only run main when node invoked THIS
+// file (dist/launch.js) — an import (tests, the old in-process path)
+// leaves it inert. npm bin entries are SYMLINKS (…/.bin/sigrun-tui → the
+// package's dist/launch.js): node realpaths the main module by default
+// (import.meta.url is the REAL path) while process.argv[1] keeps the
+// INVOKED path — the comparison must realpath the argv side, or a
+// .bin/npx invocation never matches and the bin exits 0 silently.
+/** Realpath argv[1], or undefined when it is not a file on disk (an
+ * argv[1] that doesn't exist can never be this module — e.g. exotic
+ * wrapper invocations). */
+function invokedEntryPath() {
+    if (process.argv[1] === undefined)
+        return undefined;
+    try {
+        return realpathSync(process.argv[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+const invokedEntry = invokedEntryPath();
+const invokedAsBin = invokedEntry !== undefined &&
+    import.meta.url === pathToFileURL(invokedEntry).href;
+if (invokedAsBin) {
+    void tuiMain().then((code) => {
+        process.exit(code);
+    });
+}

package/dist/sse.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The TUI's §5 conversation stream watcher (Task 4; delta frames in core
+ * hardening W3 Task 3, spec §7.3 ruling 11): a Node-side SSE client over
+ * `GET /v1/conversations/:id/stream` carrying `snapshot` and `delta` frames.
+ *
+ * This watcher is the TUI's delta folder: `snapshot` REPLACES the held view
+ * wholesale, `delta` folds into it via the shared `applyDelta`, and every
+ * accepted frame surfaces to the consumer as a FULL immutable
+ * `ConversationViewWire` revision — the consumer replaces, never
+ * accumulates. The server sends a fresh `snapshot` on EVERY connect, so a
+ * reconnect's snapshot SUBSUMES any frame missed while disconnected — no
+ * replay, no stale merge (Review Focus 1).
+ *
+ * Node 22 global fetch + manual frame parsing: `:` lines are comments,
+ * `data:` lines accumulate until a blank line dispatches the frame;
+ * multi-line `data:` joins with `\n`.
+ *
+ * Transport failures close the reader and reconnect with exponential
+ * backoff (base 250ms doubling, capped at 4s, ±30% jitter). Reconnects
+ * give up after 10 consecutive failures with ONE final `onError`; the
+ * counter resets on every successful open and at watch start. Transport
+ * failures (read error, mid-stream close) emit at most one `onError` per
+ * connection (a read failure and the ensuing close are the same failure);
+ * a non-OK status on (re)connect reports per attempt — it never opens a
+ * connection. A malformed frame reports
+ * `onError` and the stream STAYS OPEN — one bad frame must never kill the
+ * transport.
+ */
+import type { ConversationViewWire } from "./api.js";
+import type { HostEventWire } from "@sigrun/shared/views";
+export interface WatchHandlers {
+    /** A `snapshot` frame arrived (the full view on connect/re-attach). */
+    readonly onSnapshot?: (view: ConversationViewWire) => void;
+    /**
+     * A full revision arrived — either the connect snapshot or the fold of
+     * every `delta` since it. The view is ALWAYS a full immutable
+     * `ConversationViewWire`: replace, never accumulate.
+     */
+    readonly onView?: (view: ConversationViewWire) => void;
+    /**
+     * A failure: a malformed frame (stream stays open) or a transport
+     * error (a reconnect follows unless `unwatch` ran). Carries a
+     * human-readable description — fail loud, never silent.
+     */
+    readonly onError?: (message: string) => void;
+    /** The underlying connection (re)opened with an OK response. */
+    readonly onOpen?: () => void;
+}
+export interface WatchOptions {
+    /**
+     * The server's origin (e.g. `http://127.0.0.1:PORT`) — required; the
+     * TUI is a remote client.
+     */
+    readonly baseUrl: string;
+    /** `X-Sigrun-User` identity header (Task 2); omitted when absent/empty. */
+    readonly user?: string;
+    /**
+     * The bearer token (Task 7): `authorization: Bearer <token>` on the
+     * stream connect; omitted when absent/empty/whitespace.
+     */
+    readonly token?: string;
+    /** Backoff ladder base in ms (default 250; tests shrink it). */
+    readonly reconnectBaseMs?: number;
+    /** Backoff cap in ms (default 4000). */
+    readonly reconnectMaxMs?: number;
+    /** Injected for tests; defaults to the ambient `fetch`. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/** The watcher handle: `unwatch()` closes the stream, idempotent. */
+export type Unwatch = () => void;
+/**
+ * Watch one conversation's stream. Returns `unwatch()`. Reconnects on
+ * stream drop; a reconnect's fresh snapshot replaces state wholesale.
+ */
+export declare function watchConversation(conversationId: number, handlers: WatchHandlers, options: WatchOptions): Unwatch;
+/**
+ * The host events reader (core hardening W3 Task 4, spec §7.4): a
+ * Node-side SSE client over `GET /v1/events` carrying `HostEventWire`
+ * frames (`event: <type>` + single-line `data:` JSON). The TUI's launch
+ * wiring subscribes ONCE per process: `conversation.*` events refetch the
+ * conversation list, `interaction.*` kicks the prompter, `ambient.changed`
+ * refetches the ambient chrome — the old list/interaction/ambient poll
+ * timers are gone.
+ *
+ * Same transport discipline as `watchConversation`: backoff ladder
+ * (250ms doubling, 4s cap, ±30% jitter), one `onError` per failed
+ * connection, give up after 10 consecutive failures, malformed frames
+ * report + keep the stream open. There is no replay — a reconnect's
+ * first post-connect frame suffices because the handlers REFETCH (the
+ * list/interaction/ambient GETs), never merge.
+ */
+export interface EventsHandlers {
+    /** A host event arrived (already JSON-parsed). */
+    readonly onEvent: (event: HostEventWire) => void;
+    /**
+     * The hello frame's streamId (UI-blocks U3 Task 4, spec §7.3's W3
+     * amendment): fired on EVERY (re)connect — a reconnect's hello
+     * carries a NEW id, and the channel re-fetches every visible surface
+     * with it (re-registering the watcher entries). Surface fetches send
+     * the current id as `X-Sigrun-Stream`.
+     */
+    readonly onHello?: (streamId: string) => void;
+    /** A failure: malformed frame (stays open) or transport error (reconnects). */
+    readonly onError?: (message: string) => void;
+    /** The underlying connection (re)opened with an OK response. */
+    readonly onOpen?: () => void;
+}
+/** Subscribe to the global events stream. Returns the unsubscribe. */
+export declare function watchEvents(handlers: EventsHandlers, options: WatchOptions): Unwatch;