@sigrun/tui 0.1.1 → 0.2.0

package/dist/sse.js

@@ -1,401 +0,0 @@
-/**
- * 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 { applyDelta } from "@sigrun/shared/view-delta";
-/** Parse a frame; `undefined` when the payload is not an object. */
-function parseFrame(data) {
-    let parsed;
-    try {
-        parsed = JSON.parse(data);
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return undefined;
-    }
-    return parsed;
-}
-/**
- * An incremental SSE frame parser: feed it chunks; it emits complete
- * frames (`{event, data}`). `:` lines are comments; `data:` accumulates
- * until a blank line; the field-name space after `:` is stripped once.
- */
-function createFrameParser(emit) {
-    let buffer = "";
-    let event = "";
-    let data = [];
-    function dispatchLine(line) {
-        if (line === "") {
-            if (data.length > 0) {
-                emit({ event, data: data.join("\n") });
-            }
-            event = "";
-            data = [];
-            return;
-        }
-        if (line.startsWith(":")) {
-            return; // a comment (the heartbeat `: ping`)
-        }
-        const colon = line.indexOf(":");
-        const field = colon === -1 ? line : line.slice(0, colon);
-        let value = colon === -1 ? "" : line.slice(colon + 1);
-        if (value.startsWith(" ")) {
-            value = value.slice(1);
-        }
-        if (field === "event") {
-            event = value;
-        }
-        else if (field === "data") {
-            data.push(value);
-        }
-        // `id:` (and unknown fields) are accepted and ignored — every frame
-        // is a full revision, so the revision cursor is never needed.
-    }
-    return (chunk) => {
-        buffer += chunk;
-        for (;;) {
-            const newline = buffer.indexOf("\n");
-            if (newline === -1)
-                return;
-            let line = buffer.slice(0, newline);
-            buffer = buffer.slice(newline + 1);
-            if (line.endsWith("\r")) {
-                line = line.slice(0, -1);
-            }
-            dispatchLine(line);
-        }
-    };
-}
-/**
- * Watch one conversation's stream. Returns `unwatch()`. Reconnects on
- * stream drop; a reconnect's fresh snapshot replaces state wholesale.
- */
-export function watchConversation(conversationId, handlers, options) {
-    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
-    const baseMs = options.reconnectBaseMs ?? 250;
-    const maxMs = options.reconnectMaxMs ?? 4_000;
-    /** Give up after this many consecutive failed reconnects. */
-    const maxAttempts = 10;
-    const user = options.user?.trim();
-    const token = options.token?.trim();
-    const headers = {
-        accept: "text/event-stream",
-        ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
-        ...(token === undefined || token === ""
-            ? {}
-            : { authorization: `Bearer ${token}` }),
-    };
-    const url = `${options.baseUrl}/v1/conversations/${conversationId}/stream`;
-    let closed = false;
-    let attempts = 0;
-    let timer;
-    let abort;
-    /** Per-attempt onError dedupe (fix wave A10); cleared on open. */
-    let reportedTransportError = false;
-    /**
-     * The held view: the last snapshot, folded with every accepted delta
-     * since. `undefined` before the first snapshot — a delta arriving then
-     * is malformed (there is nothing to fold into).
-     */
-    let currentView;
-    function scheduleReconnect() {
-        attempts += 1;
-        const base = Math.min(baseMs * 2 ** (attempts - 1), maxMs);
-        // ±30% jitter: correlated drops must not reconnect in lockstep.
-        const delay = base * (1 + (Math.random() * 0.6 - 0.3));
-        timer = setTimeout(() => {
-            timer = undefined;
-            void connect();
-        }, delay);
-    }
-    async function connect() {
-        if (closed)
-            return;
-        if (attempts >= maxAttempts) {
-            // Give up (fix wave A3): the 10th consecutive failure was just
-            // reported by its caller; emit ONE final notice and stop — no
-            // 11th fetch fires.
-            handlers.onError?.(`giving up after ${maxAttempts} failed reconnects`);
-            return;
-        }
-        const controller = new AbortController();
-        abort = controller;
-        let response;
-        try {
-            response = await fetchImpl(url, {
-                method: "GET",
-                headers,
-                signal: controller.signal,
-            });
-        }
-        catch (error) {
-            if (closed)
-                return;
-            handlers.onError?.(`conversation stream connect failed: ${error.message}`);
-            scheduleReconnect();
-            return;
-        }
-        if (!response.ok || response.body === null) {
-            if (closed)
-                return;
-            handlers.onError?.(`conversation stream responded with status ${response.status}`);
-            scheduleReconnect();
-            return;
-        }
-        attempts = 0;
-        // The open clears the per-attempt dedupe (fix wave A10): the next
-        // failed connection gets its own single onError.
-        reportedTransportError = false;
-        handlers.onOpen?.();
-        const parser = createFrameParser((frame) => {
-            if (closed)
-                return;
-            const parsed = parseFrame(frame.data);
-            if (parsed === undefined) {
-                handlers.onError?.(`malformed ${frame.event === "" ? "message" : frame.event} frame (not a view object)`);
-                return;
-            }
-            if (frame.event === "snapshot") {
-                // A fresh snapshot SUBSUMES anything missed — the fold re-bases
-                // on it wholesale; nothing here merges.
-                currentView = parsed;
-                handlers.onSnapshot?.(currentView);
-            }
-            else if (frame.event === "delta") {
-                if (currentView === undefined) {
-                    handlers.onError?.("malformed delta frame (arrived before any snapshot)");
-                    return;
-                }
-                // Fold, then surface the FULL revision: the consumer's contract
-                // stays "replace, never accumulate".
-                currentView = applyDelta(currentView, parsed);
-                handlers.onView?.(currentView);
-            }
-            else {
-                handlers.onError?.(`unknown stream event "${frame.event}"`);
-            }
-        });
-        const decoder = new TextDecoder();
-        try {
-            const reader = response.body.getReader();
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                parser(decoder.decode(value, { stream: true }));
-            }
-        }
-        catch (error) {
-            if (closed)
-                return;
-            // Dedupe (fix wave A10): a read failure and the close that
-            // follows it are ONE connection failure — one onError.
-            if (!reportedTransportError) {
-                reportedTransportError = true;
-                handlers.onError?.(`conversation stream read failed: ${error.message}`);
-            }
-        }
-        if (!closed) {
-            if (!reportedTransportError) {
-                reportedTransportError = true;
-                handlers.onError?.("conversation stream closed by the server");
-            }
-            scheduleReconnect();
-        }
-    }
-    void connect();
-    return () => {
-        if (closed)
-            return;
-        closed = true;
-        if (timer !== undefined) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-        abort?.abort();
-        abort = undefined;
-    };
-}
-/** Loose parse: the launch wiring only branches on `type`. */
-function parseEvent(data) {
-    let parsed;
-    try {
-        parsed = JSON.parse(data);
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof parsed !== "object" ||
-        parsed === null ||
-        Array.isArray(parsed) ||
-        typeof parsed.type !== "string") {
-        return undefined;
-    }
-    return parsed;
-}
-/** Subscribe to the global events stream. Returns the unsubscribe. */
-export function watchEvents(handlers, options) {
-    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
-    const baseMs = options.reconnectBaseMs ?? 250;
-    const maxMs = options.reconnectMaxMs ?? 4_000;
-    const maxAttempts = 10;
-    const user = options.user?.trim();
-    const token = options.token?.trim();
-    const headers = {
-        accept: "text/event-stream",
-        ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
-        ...(token === undefined || token === ""
-            ? {}
-            : { authorization: `Bearer ${token}` }),
-    };
-    const url = `${options.baseUrl}/v1/events`;
-    let closed = false;
-    let attempts = 0;
-    let timer;
-    let abort;
-    let reportedTransportError = false;
-    function scheduleReconnect() {
-        attempts += 1;
-        const base = Math.min(baseMs * 2 ** (attempts - 1), maxMs);
-        const delay = base * (1 + (Math.random() * 0.6 - 0.3));
-        timer = setTimeout(() => {
-            timer = undefined;
-            void connect();
-        }, delay);
-    }
-    async function connect() {
-        if (closed)
-            return;
-        if (attempts >= maxAttempts) {
-            handlers.onError?.(`events stream: giving up after ${maxAttempts} failed reconnects`);
-            return;
-        }
-        const controller = new AbortController();
-        abort = controller;
-        let response;
-        try {
-            response = await fetchImpl(url, {
-                method: "GET",
-                headers,
-                signal: controller.signal,
-            });
-        }
-        catch (error) {
-            if (closed)
-                return;
-            handlers.onError?.(`events stream connect failed: ${error.message}`);
-            scheduleReconnect();
-            return;
-        }
-        if (!response.ok || response.body === null) {
-            if (closed)
-                return;
-            handlers.onError?.(`events stream responded with status ${response.status}`);
-            scheduleReconnect();
-            return;
-        }
-        attempts = 0;
-        reportedTransportError = false;
-        handlers.onOpen?.();
-        const parser = createFrameParser((frame) => {
-            if (closed)
-                return;
-            // The hello frame (U3 Task 4) is connection-local: it names
-            // THIS stream for the watcher registry — surface fetches send
-            // the id as `X-Sigrun-Stream`; a NEW id (reconnect) re-fires
-            // so the channel re-registers. It never reaches onEvent (the
-            // launch wiring's switch would ignore it anyway — event types
-            // are an open set). Parsed loosely: the hello payload carries
-            // `streamId`, not a `type` member.
-            if (frame.event === "hello") {
-                let parsed;
-                try {
-                    parsed = JSON.parse(frame.data);
-                }
-                catch {
-                    handlers.onError?.("malformed hello frame (not JSON)");
-                    return;
-                }
-                // SAFETY: the JSON.parse output is unknown; the read below
-                // narrows `streamId` by typeof before use.
-                const streamId = parsed.streamId;
-                if (typeof streamId === "string") {
-                    handlers.onHello?.(streamId);
-                }
-                else {
-                    handlers.onError?.("malformed hello frame (no streamId)");
-                }
-                return;
-            }
-            const event = parseEvent(frame.data);
-            if (event === undefined) {
-                handlers.onError?.(`malformed ${frame.event === "" ? "message" : frame.event} frame (not an event object)`);
-                return;
-            }
-            handlers.onEvent(event);
-        });
-        const decoder = new TextDecoder();
-        try {
-            const reader = response.body.getReader();
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                parser(decoder.decode(value, { stream: true }));
-            }
-        }
-        catch (error) {
-            if (closed)
-                return;
-            if (!reportedTransportError) {
-                reportedTransportError = true;
-                handlers.onError?.(`events stream read failed: ${error.message}`);
-            }
-        }
-        if (!closed) {
-            if (!reportedTransportError) {
-                reportedTransportError = true;
-                handlers.onError?.("events stream closed by the server");
-            }
-            scheduleReconnect();
-        }
-    }
-    void connect();
-    return () => {
-        if (closed)
-            return;
-        closed = true;
-        if (timer !== undefined) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-        abort?.abort();
-        abort = undefined;
-    };
-}

package/dist/theme.d.ts

@@ -1,51 +0,0 @@
-/**
- * The TUI theme (Task C1, UI refresh): wraps the shared themes module's
- * palettes in pi-tui's color pipeline (parseColor → foregroundAnsi /
- * backgroundAnsi) so components style text through token names instead
- * of raw SGR sequences. The palette DATA lives in one place
- * (@sigrun/shared/themes, shared with the webui — zero duplication);
- * this module owns only the terminal mapping.
- *
- * Degradation: `colorMode` threads through foregroundAnsi/backgroundAnsi,
- * so a 256color terminal gets `38;5;N` (pi-tui's nearest-256 mapping)
- * instead of truecolor `38;2;r;g;b`. The launcher resolves the mode at
- * boot via `getTerminalColorMode()`; tests pass it explicitly.
- *
- * The `code` token is CSS `rgba(...)` (the shared data's overlay chip):
- * pi-tui's parseColor takes hex/`rgb()` only, so it is alpha-composited
- * over the mode's `bg` token here — the same visual the webui gets from
- * layering the overlay on the background.
- */
-import { type TerminalColorMode } from "@earendil-works/pi-tui";
-import { type AccentName, type ModeName, type PaletteName, type PaletteTokens } from "@sigrun/shared/themes";
-/** A palette token, the accent colour, or a state colour (warn/bad). */
-export type TuiToken = keyof PaletteTokens | "accent" | "warn" | "bad";
-/**
- * Terminal styling surface: token-named fg/bg plus the plain attribute
- * helpers. `fg`/`bg` return string wrappers so call sites compose
- * (`theme.fg("muted")(text)`) without holding SGR sequences.
- */
-export interface TuiTheme {
-    fg(token: TuiToken): (s: string) => string;
-    bg(token: TuiToken): (s: string) => string;
-    bold(s: string): string;
-    dim(s: string): string;
-    italic(s: string): string;
-}
-export interface TuiThemeOptions {
-    readonly palette: PaletteName;
-    readonly accent: AccentName;
-    readonly mode: ModeName;
-    readonly colorMode: TerminalColorMode;
-}
-/**
- * Build the theme. Precomputes each token's fg/bg SGR (pi-tui's cached
- * sequence idiom — `styleTextWithAnsi` without the dependency) and wraps
- * it in reset-terminated spans.
- */
-export declare function createTuiTheme(options: TuiThemeOptions): TuiTheme;
-/**
- * The no-colour fallback (tests, non-TTY sinks): every method is the
- * identity — the structure renders identically without SGR sequences.
- */
-export declare function plainTuiTheme(): TuiTheme;

package/dist/theme.js

@@ -1,119 +0,0 @@
-/**
- * The TUI theme (Task C1, UI refresh): wraps the shared themes module's
- * palettes in pi-tui's color pipeline (parseColor → foregroundAnsi /
- * backgroundAnsi) so components style text through token names instead
- * of raw SGR sequences. The palette DATA lives in one place
- * (@sigrun/shared/themes, shared with the webui — zero duplication);
- * this module owns only the terminal mapping.
- *
- * Degradation: `colorMode` threads through foregroundAnsi/backgroundAnsi,
- * so a 256color terminal gets `38;5;N` (pi-tui's nearest-256 mapping)
- * instead of truecolor `38;2;r;g;b`. The launcher resolves the mode at
- * boot via `getTerminalColorMode()`; tests pass it explicitly.
- *
- * The `code` token is CSS `rgba(...)` (the shared data's overlay chip):
- * pi-tui's parseColor takes hex/`rgb()` only, so it is alpha-composited
- * over the mode's `bg` token here — the same visual the webui gets from
- * layering the overlay on the background.
- */
-import { backgroundAnsi, foregroundAnsi, parseColor, } from "@earendil-works/pi-tui";
-import { ACCENTS, PALETTES, } from "@sigrun/shared/themes";
-const RESET = "\u001b[0m";
-const attr = (code, s) => `\u001b[${code}m${s}${RESET}`;
-/** Alpha-composite a CSS `rgba(r,g,b,a)` over an opaque base. */
-function compositeOver(rgba, base) {
-    const m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(rgba.replace(/\s/g, ""));
-    if (!m)
-        return base;
-    const [, rs, gs, bs, as = "1"] = m;
-    const [r, g, b, a] = [Number(rs), Number(gs), Number(bs), Number(as)];
-    const [br, bg, bb] = hexToRgb(base);
-    const mix = (fg, bgv) => Math.round(fg * a + bgv * (1 - a));
-    return rgbToHex(mix(r, br), mix(g, bg), mix(b, bb));
-}
-function hexToRgb(hex) {
-    const value = hex.replace("#", "");
-    return [
-        parseInt(value.slice(0, 2), 16),
-        parseInt(value.slice(2, 4), 16),
-        parseInt(value.slice(4, 6), 16),
-    ];
-}
-function rgbToHex(r, g, b) {
-    const two = (n) => n.toString(16).padStart(2, "0");
-    return `#${two(r)}${two(g)}${two(b)}`;
-}
-/**
- * The state colours (warnings + errors), defined per mode like the
- * webui's `--warn`/`--danger` (webui/src/app.css — they are NOT palette
- * members in either channel). The TUI's tone table (blocks/tones.ts)
- * paints `warn`/`bad` tones with them.
- */
-const STATE_COLORS = {
-    warn: { dark: "#d9a35a", light: "#8a6116" },
-    bad: { dark: "#e0707a", light: "#b3363f" },
-};
-/** Resolve a token to a parseable colour for the palette+mode. */
-function resolveToken(tokens, accentHex, mode, token) {
-    if (token === "accent")
-        return accentHex;
-    if (token === "warn" || token === "bad")
-        return STATE_COLORS[token][mode];
-    const value = tokens[token];
-    // `code` is the rgba overlay chip; composite over the mode's bg.
-    if (value.startsWith("rgba"))
-        return compositeOver(value, tokens.bg);
-    return value;
-}
-/**
- * Build the theme. Precomputes each token's fg/bg SGR (pi-tui's cached
- * sequence idiom — `styleTextWithAnsi` without the dependency) and wraps
- * it in reset-terminated spans.
- */
-export function createTuiTheme(options) {
-    const tokens = PALETTES[options.palette][options.mode];
-    const accentHex = ACCENTS[options.accent][options.mode];
-    const mode = options.colorMode;
-    const fgSequences = new Map();
-    const bgSequences = new Map();
-    for (const token of [
-        "bg",
-        "surface",
-        "surface2",
-        "border",
-        "text",
-        "muted",
-        "faint",
-        "ok",
-        "code",
-        "accent",
-        "warn",
-        "bad",
-    ]) {
-        const color = parseColor(resolveToken(tokens, accentHex, options.mode, token));
-        fgSequences.set(token, foregroundAnsi(color, mode));
-        bgSequences.set(token, backgroundAnsi(color, mode));
-    }
-    const span = (seq, s) => `${seq}${s}${RESET}`;
-    return {
-        fg: (token) => (s) => span(fgSequences.get(token) ?? "", s),
-        bg: (token) => (s) => span(bgSequences.get(token) ?? "", s),
-        bold: (s) => attr("1", s),
-        dim: (s) => attr("2", s),
-        italic: (s) => attr("3", s),
-    };
-}
-/**
- * The no-colour fallback (tests, non-TTY sinks): every method is the
- * identity — the structure renders identically without SGR sequences.
- */
-export function plainTuiTheme() {
-    const identity = (s) => s;
-    return {
-        fg: () => identity,
-        bg: () => identity,
-        bold: identity,
-        dim: identity,
-        italic: identity,
-    };
-}

package/dist/ui/ambient.d.ts

@@ -1,81 +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).
- */
-import type { Component } from "@earendil-works/pi-tui";
-import type { AmbientWire, SigrunClient } from "../api.js";
-export declare class AmbientChrome implements Component {
-    #private;
-    /** Rendered-state changes (the app requests a repaint). */
-    onChanged?: () => void;
-    constructor(client: SigrunClient);
-    /** The latest served surfaces (before the idle filter). */
-    get records(): readonly AmbientWire[];
-    /**
-     * 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: number | undefined): void;
-    /**
-     * 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: number): void;
-    /**
-     * The conversation's run state (the app feeds it from stream frames).
-     * `expires: "idle"` surfaces render only while busy.
-     */
-    setBusy(busy: boolean): void;
-    /** The statusline: the status records' summaries joined " · ". */
-    statusline(): string;
-    /** The footer zone: one summary line per footer record. */
-    footerLines(): readonly string[];
-    /** The panel zone: the full per-record rendering, blocks joined. */
-    panelLines(): readonly string[];
-    /** Detach (the app calls this on dispose): stale fetches never land. */
-    dispose(): void;
-    /** The chrome: panel blocks, then footer lines, then the statusline. */
-    render(_width: number): string[];
-    invalidate(): void;
-}