@sigrun/tui 0.4.1 → 0.5.0

package/dist/theme.js

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

@@ -0,0 +1,78 @@
+/**
+ * The ambient seam's TUI renderer (UI-blocks U6 Task 3, the parity
+ * rule): ambient surfaces placed in the TUI's chrome per the seam's
+ * `place` field, rendered FROM BLOCK TREES (placement `ambient`, spec
+ * §9.2):
+ *
+ * - `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: the body's `columns` block renders the
+ *   left/middle/right zones (three columns), above the statusline.
+ * - `panel` → the panel zone: the full tree rendering, above the footer.
+ *
+ * Genericity (the seam's whole point): the chrome renders blocks and
+ * knows NOTHING about what a surface means — no "todo", no "goal".
+ * `details` renders as one collapsed JSON line, never interpreted.
+ *
+ * Ambient bodies carry LITERAL content only (the 2026-10-24 ruling:
+ * the envelope has no data document, so validation rejects every
+ * binding outside a collection's item template), so the renderer's
+ * data document is EMPTY. Ambient surfaces are read-only
+ * (actions re-route through interaction records) — the render context's
+ * access is `read` and dispatch is a no-op.
+ *
+ * The envelope's `maxRows`/`overflow` budget applies to a panel's root
+ * literal-rows collection (Review Focus 3): `drop` folds the tail behind
+ * the collection's own quiet bucket ("N more"), `summarize` replaces
+ * the tail with a count line, `wrap` renders as authored.
+ *
+ * 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}). Fetch
+ * failures are QUIET (best-effort chrome).
+ *
+ * Expiry: `expires: "idle"` surfaces render only while the conversation
+ * has a live run ({@link setBusy}, driven by the stream's `steer.busy`).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { AmbientWire, SigrunClient } from "../api.js";
+import { type TuiTheme } from "../theme.js";
+export declare class AmbientChrome implements Component {
+    #private;
+    /** Rendered-state changes (the app requests a repaint). */
+    onChanged?: () => void;
+    constructor(client: SigrunClient, options?: {
+        theme?: TuiTheme;
+    });
+    /** 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' one-line bodies joined " · ".
+     *  `width` bounds each body's render (the app's frame width). */
+    statusline(width?: number): string;
+    /** The footer zone: one rendered line per footer record. */
+    footerLines(width?: number): readonly string[];
+    /** The panel zone: the full per-record tree rendering. */
+    panelLines(width?: number): 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;
+}

package/dist/ui/ambient.js

@@ -0,0 +1,264 @@
+/**
+ * The ambient seam's TUI renderer (UI-blocks U6 Task 3, the parity
+ * rule): ambient surfaces placed in the TUI's chrome per the seam's
+ * `place` field, rendered FROM BLOCK TREES (placement `ambient`, spec
+ * §9.2):
+ *
+ * - `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: the body's `columns` block renders the
+ *   left/middle/right zones (three columns), above the statusline.
+ * - `panel` → the panel zone: the full tree rendering, above the footer.
+ *
+ * Genericity (the seam's whole point): the chrome renders blocks and
+ * knows NOTHING about what a surface means — no "todo", no "goal".
+ * `details` renders as one collapsed JSON line, never interpreted.
+ *
+ * Ambient bodies carry LITERAL content only (the 2026-10-24 ruling:
+ * the envelope has no data document, so validation rejects every
+ * binding outside a collection's item template), so the renderer's
+ * data document is EMPTY. Ambient surfaces are read-only
+ * (actions re-route through interaction records) — the render context's
+ * access is `read` and dispatch is a no-op.
+ *
+ * The envelope's `maxRows`/`overflow` budget applies to a panel's root
+ * literal-rows collection (Review Focus 3): `drop` folds the tail behind
+ * the collection's own quiet bucket ("N more"), `summarize` replaces
+ * the tail with a count line, `wrap` renders as authored.
+ *
+ * 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}). Fetch
+ * failures are QUIET (best-effort chrome).
+ *
+ * Expiry: `expires: "idle"` surfaces render only while the conversation
+ * has a live run ({@link setBusy}, driven by the stream's `steer.busy`).
+ */
+import { renderBlock } from "../blocks/render.js";
+import { truncate } from "../blocks/width.js";
+import { plainTuiTheme } from "../theme.js";
+/** Ambient bodies never bind (the ruling): the data document is empty. */
+const EMPTY_DATA = {};
+/** The read-only ambient render context (surfaces take no answers; the
+ *  dispatch sink is a no-op). */
+function ambientCtx(theme) {
+    return {
+        data: EMPTY_DATA,
+        theme,
+        locale: "en",
+        access: "read",
+        unicode: true,
+        dispatch: () => { },
+        view: { values: {} },
+        setView: () => { },
+        serverErrors: {},
+    };
+}
+export class AmbientChrome {
+    #client;
+    #theme;
+    #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, options = {}) {
+        this.#client = client;
+        this.#theme = options.theme ?? plainTuiTheme();
+    }
+    /** 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' one-line bodies joined " · ".
+     *  `width` bounds each body's render (the app's frame width). */
+    statusline(width) {
+        return this.#visible("status")
+            .map((record) => this.#bodyText(record, width))
+            .filter((line) => line !== "")
+            .join(" · ");
+    }
+    /** The footer zone: one rendered line per footer record. */
+    footerLines(width) {
+        return this.#visible("footer").map((record) => this.#renderBody(record, width).join(" ").trim());
+    }
+    /** The panel zone: the full per-record tree rendering. */
+    panelLines(width) {
+        const lines = [];
+        for (const record of this.#visible("panel")) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push(`[${record.key}]${record.owner === "" ? "" : ` ${record.owner}`}`);
+            lines.push(...this.#renderBody(record, width));
+            if (record.details !== undefined) {
+                lines.push(`[details] ${JSON.stringify(record.details)}`);
+            }
+        }
+        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));
+    }
+    /** Render one record's body tree (budgeted per Review Focus 3). */
+    #renderBody(record, width) {
+        const body = record.body;
+        if (body === undefined)
+            return [];
+        const root = budgetTree(record, body.root);
+        // The chrome's own frame width bounds the render; a bare read
+        // (statusline/footerLines callers without a frame) falls back to
+        // the regular-class width.
+        return renderBlock(root, ambientCtx(this.#theme)).render(width ?? 120);
+    }
+    /** The one-line text of a status/footer body (a single markdown or a
+     *  columns of one-line blocks — §9.2's one-line rule). */
+    #bodyText(record, width) {
+        const body = record.body;
+        if (body === undefined)
+            return "";
+        return this.#renderBody(record, width).join(" ").trim();
+    }
+    /** 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(width), ...this.footerLines(width)];
+        const status = this.statusline(width);
+        if (status !== "")
+            lines.push(status);
+        // ANSI-aware clamp (Review fix): a raw UTF-16 slice cuts escape
+        // sequences and surrogate pairs mid-unit.
+        return lines.map((line) => truncate(line, width));
+    }
+    invalidate() {
+        // Stateless render: lines assemble from the current records.
+    }
+}
+/** A surface with no body tree and no details renders nothing. */
+function hasContent(record) {
+    return record.body !== undefined || record.details !== undefined;
+}
+/** The quiet fold for the drop overflow: mark the tail rows quiet so
+ *  the collection's own "N more" toggle carries them (the budget never
+ *  LOSES rows — the user can still unfold). A template WITHOUT a
+ *  `quiet` binding has no fold to ride (its isQuiet is always false),
+ *  so the budget falls back to truncating the tail behind a one-line
+ *  "<n> more" markdown row (Review fix — a quiet-less template's drop
+ *  overflow silently no-op'd). */
+function dropTail(collection, items, maxRows) {
+    // No quiet binding: truncate + count line (the fold has nothing to
+    // key on).
+    if (collection.item.quiet === undefined) {
+        const visible = items.slice(0, maxRows);
+        const dropped = items.length - visible.length;
+        // SAFETY: same block with a literal array swapped in (the ambient
+        // literal-rows shape the schema now admits).
+        const trimmed = { ...collection, items: [...visible] };
+        return {
+            type: "stack",
+            children: [trimmed, { type: "markdown", text: `${dropped} more` }],
+        };
+    }
+    const visible = items.slice(0, maxRows);
+    const tail = items.slice(maxRows).map((row) => {
+        if (typeof row === "object" && row !== null && !Array.isArray(row)) {
+            return { ...row, quiet: true };
+        }
+        return row;
+    });
+    // SAFETY: `items` is the same block with a literal array swapped in
+    // (the ambient literal-rows shape the schema now admits); every other
+    // prop is verbatim.
+    return { ...collection, items: [...visible, ...tail] };
+}
+/** Apply the panel row budget (Review Focus 3): only a root
+ *  literal-rows collection on a panel surface budgets; anything else
+ *  renders as authored. */
+function budgetTree(surface, root) {
+    if (surface.place !== "panel" || root.type !== "collection")
+        return root;
+    if (!Array.isArray(root.items))
+        return root; // bound elsewhere; ambient rejects these
+    const maxRows = surface.maxRows;
+    if (maxRows === undefined || root.items.length <= maxRows)
+        return root;
+    const dropped = root.items.length - maxRows;
+    if (surface.overflow === "summarize") {
+        // The count line: one markdown under the trimmed collection.
+        return {
+            type: "stack",
+            children: [
+                { ...root, items: root.items.slice(0, maxRows) },
+                { type: "markdown", text: `${dropped} rows` },
+            ],
+        };
+    }
+    if (surface.overflow === "wrap")
+        return root; // panels wrap rows — no fold
+    return dropTail(root, root.items, maxRows);
+}