@sigrun/tui 0.0.0-stage → 0.1.1

package/dist/blocks/content.js

@@ -0,0 +1,253 @@
+/**
+ * The simple content blocks (UI-blocks spec §5.3): `markdown`,
+ * `fields`, `stat`, `callout`, `diff`, `details`.
+ *
+ * - `markdown` rides pi-tui's `Markdown` (the same renderer as chat)
+ *   with the TuiTheme-mapped markdown theme.
+ * - `fields` aligns labels by display width.
+ * - `stat` is `label: value unit` plus an optional caption line (its
+ *   `sparkline` becomes a real drawing in Task 2).
+ * - `callout` leads with the tone marker (colour + the NO_COLOR
+ *   fallback), its body renders as markdown, and its actions render as
+ *   `[1] label` buttons with the confirm flow and the OSC 52 copy.
+ * - `diff` reuses the interaction diff renderer (blocks/diff.ts).
+ * - `details` is one collapsed JSON line (the TUI's existing details
+ *   primitive; a later task may add an expandable pretty view).
+ */
+import { Markdown, hyperlink, getCapabilities, visibleWidth } from "@earendil-works/pi-tui";
+import { formatValue } from "@sigrun/shared/blocks";
+import { bindRaw, bindText, bindTone } from "./context.js";
+import { truncate } from "./width.js";
+import { iconGlyph } from "./icons.js";
+import { toneFg, toneMarker } from "./tones.js";
+import { blockDiff, diffLines } from "./diff.js";
+import { Lines } from "./layout.js";
+import { copyToTerminal } from "../clipboard.js";
+/** The markdown theme rides the TuiTheme's token colours. */
+function markdownTheme(theme) {
+    return {
+        heading: (text) => theme.bold(theme.fg("accent")(text)),
+        link: theme.fg("accent"),
+        linkUrl: theme.dim,
+        code: theme.fg("code"),
+        codeBlock: theme.fg("code"),
+        codeBlockBorder: theme.fg("border"),
+        quote: theme.italic,
+        quoteBorder: theme.fg("border"),
+        hr: theme.fg("border"),
+        listBullet: theme.fg("accent"),
+        bold: theme.bold,
+        italic: theme.italic,
+        strikethrough: (text) => text,
+        underline: (text) => text,
+    };
+}
+/** `markdown`: the same renderer as chat. */
+export function renderMarkdown(block, ctx) {
+    return new Markdown(bindText(block.text, ctx), 0, 0, markdownTheme(ctx.theme));
+}
+/** Read `fields.rows` into label/value/tone/icon rows (each slot binds). */
+function fieldRows(block, ctx) {
+    const raw = bindRaw(block.rows, ctx);
+    if (!Array.isArray(raw))
+        return [];
+    const rows = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const record = entry;
+        const label = bindText(record.label, ctx);
+        const value = formatValue((bindRaw(record.value, ctx) ?? null), undefined, ctx.locale);
+        const tone = bindRaw(record.tone, ctx);
+        const icon = bindRaw(record.icon, ctx);
+        rows.push({
+            label,
+            value,
+            tone: tone === undefined ? undefined : bindTone(tone, ctx),
+            icon: icon === undefined ? undefined : icon,
+        });
+    }
+    return rows;
+}
+/** `fields`: `label: value` rows, labels aligned by display width. */
+export function renderFields(block, ctx) {
+    return new Lines(() => {
+        const rows = fieldRows(block, ctx);
+        const labelWidth = Math.max(0, ...rows.map((row) => visibleWidth(row.label)));
+        return rows.map((row) => {
+            const padded = row.label + " ".repeat(Math.max(0, labelWidth - visibleWidth(row.label)));
+            const text = row.tone === undefined ? row.value : toneFg(ctx.theme, row.tone)(row.value);
+            const glyph = row.icon === undefined ? "" : `${iconGlyph(row.icon, !ctx.unicode)} `;
+            return `${ctx.theme.dim(padded)}  ${glyph}${text}`;
+        });
+    });
+}
+/** `stat`: `label: value unit` plus an optional caption line. */
+export function renderStat(block, ctx) {
+    return new Lines((width) => {
+        const value = formatValue((bindRaw(block.value, ctx) ?? null), block.format, ctx.locale);
+        const unit = bindText(block.unit, ctx);
+        const text = unit === "" ? value : `${value} ${unit}`;
+        const tone = bindRaw(block.tone, ctx);
+        const toneName = tone === undefined ? undefined : bindTone(tone, ctx);
+        const icon = bindRaw(block.icon, ctx);
+        const label = bindText(block.label, ctx);
+        const head = typeof icon === "string" ? `${iconGlyph(icon, !ctx.unicode)} ${label}` : label;
+        const painted = toneName === undefined ? text : toneFg(ctx.theme, toneName)(text);
+        const out = [truncate(`${ctx.theme.dim(`${head}:`)} ${painted}`, width)];
+        const caption = bindText(block.caption, ctx);
+        if (caption !== "")
+            out.push(ctx.theme.dim(caption));
+        return out;
+    });
+}
+/** `details`: one collapsed JSON line. */
+export function renderDetails(block) {
+    return new Lines(() => [JSON.stringify(block.value)]);
+}
+/** `diff`: the interaction diff renderer (blocks/diff.ts). */
+export function renderDiff(block) {
+    return new Lines(() => diffLines(blockDiff(block)));
+}
+/** The actions a block offers: read access keeps the view-only kinds
+ * (§6.5 — copy/open/navigate never edit or answer; twin of the webui's
+ * `isViewOnly`). */
+export function visibleActions(actions, ctx) {
+    if (ctx.access === "read") {
+        return (actions ?? []).filter((button) => button.action.type === "copy" ||
+            button.action.type === "open" ||
+            button.action.type === "navigate");
+    }
+    return [...(actions ?? [])];
+}
+/** The URL schemes an `open` action may carry (§15: https/http/mailto). */
+const OPEN_SCHEMES = new Set(["https", "http", "mailto"]);
+/** Clean an `open` URL the way a browser would, then allowlist the scheme. */
+function openUrl(url) {
+    const cleaned = url
+        .replace(/[\t\n\r]/g, "")
+        .replace(/[\u0000-\u0020]+$/, "")
+        .replace(/^[\u0000-\u0020]+/, "");
+    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(cleaned)?.[1];
+    if (scheme === undefined)
+        return "";
+    return OPEN_SCHEMES.has(scheme.toLowerCase()) ? cleaned : "";
+}
+/** `open`: channel-local (§6.2 view-only) — print the URL as an OSC 8
+ * hyperlink when the terminal supports them, else as plain text. */
+function runOpen(button, action, ctx) {
+    const url = openUrl(action.url);
+    if (url === "")
+        return; // disallowed scheme: nothing opens, nothing dispatches
+    const terminal = ctx.terminal ?? { write: (data) => process.stdout.write(data) };
+    const label = bindText(button.label, ctx);
+    const shown = getCapabilities().hyperlinks
+        ? hyperlink(label, url)
+        : `${label} — ${url}`;
+    terminal.write(`${shown}\n`);
+}
+/** Run a button's action (copy/open resolve locally; the rest dispatch). */
+function runAction(button, ctx) {
+    const action = button.action;
+    if (action.type === "copy") {
+        const raw = bindRaw(action.text, ctx);
+        const text = typeof raw === "string" ? raw : "";
+        copyToTerminal(ctx.terminal ?? { write: (data) => process.stdout.write(data) }, text);
+        return;
+    }
+    if (action.type === "open") {
+        runOpen(button, action, ctx);
+        return;
+    }
+    ctx.dispatch(action, null);
+}
+/**
+ * `callout`: tone-marked title, wrapped markdown body, action buttons.
+ * `handleInput` picks a button by digit; a `confirm` action gates its
+ * dispatch behind a `y/N` prompt (anything but `y`/`Y` cancels and
+ * dispatches nothing).
+ */
+export class CalloutComponent {
+    #block;
+    #ctx;
+    #confirm;
+    constructor(block, ctx) {
+        this.#block = block;
+        this.#ctx = ctx;
+    }
+    render(width) {
+        const theme = this.#ctx.theme;
+        const tone = bindTone(this.#block.tone, this.#ctx);
+        const title = bindText(this.#block.title, this.#ctx);
+        const lines = [
+            truncate(`${toneFg(theme, tone)(toneMarker(tone, !this.#ctx.unicode))} ${title}`, width),
+        ];
+        const body = bindText(this.#block.body, this.#ctx);
+        if (body !== "") {
+            // The body is markdown (§5.3); ride the same renderer as chat.
+            lines.push(...new Markdown(body, 0, 0, markdownTheme(theme)).render(width));
+        }
+        if (this.#confirm !== undefined) {
+            const { confirm, action } = this.#confirm;
+            const label = confirm.confirmLabel ??
+                (action.type === "restart" ? "Restart" : "Confirm");
+            lines.push("");
+            lines.push(truncate(`${toneFg(theme, confirm.tone ?? "warn")(toneMarker(confirm.tone ?? "warn", !this.#ctx.unicode))} ${confirm.title}`, width));
+            if (confirm.body !== undefined && confirm.body !== "") {
+                lines.push(...new Markdown(confirm.body, 0, 0, markdownTheme(theme)).render(width));
+            }
+            lines.push(truncate(`${label}? y/N`, width));
+            return lines;
+        }
+        const actions = visibleActions(this.#block.actions, this.#ctx);
+        if (actions.length > 0) {
+            lines.push("");
+            lines.push(truncate(actions
+                .map((button, index) => `[${index + 1}] ${bindText(button.label, this.#ctx)}`)
+                .join("  "), width));
+        }
+        return lines;
+    }
+    handleInput(data) {
+        if (this.#confirm !== undefined) {
+            const { action } = this.#confirm;
+            this.#confirm = undefined;
+            if (data === "y" || data === "Y")
+                this.#ctx.dispatch(action, null);
+            return;
+        }
+        const actions = visibleActions(this.#block.actions, this.#ctx);
+        const button = actions[Number(data) - 1];
+        if (button === undefined)
+            return;
+        const action = button.action;
+        if ((action.type === "submit" || action.type === "restart") &&
+            action.confirm !== undefined) {
+            this.#confirm = { confirm: action.confirm, action };
+            return;
+        }
+        runAction(button, this.#ctx);
+    }
+    invalidate() {
+        // Stateless render; the confirm gate is the only mutable state.
+    }
+}
+/** Render a Task-1 content block by type; the caller routes unknowns. */
+export function renderContent(block, ctx) {
+    switch (block.type) {
+        case "markdown":
+            return renderMarkdown(block, ctx);
+        case "fields":
+            return renderFields(block, ctx);
+        case "stat":
+            return renderStat(block, ctx);
+        case "details":
+            return renderDetails(block);
+        case "diff":
+            return renderDiff(block);
+        case "callout":
+            return new CalloutComponent(block, ctx);
+        default:
+            return undefined;
+    }
+}

package/dist/blocks/context.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The block render context (UI-blocks U2 Task 1): everything a block
+ * component reads while rendering — the surface's data, the theme, the
+ * locale, the principal's access, the dispatch seam and the channel's
+ * view state — plus the binding/text resolution helpers every block
+ * renderer shares.
+ *
+ * `view` is the channel-owned view-state branch (spec §6.2): sort,
+ * filter, expansion, selection. Task 5 (forms) widened the seam with
+ * `setView` (the `/view/` writer a live form bound under `/view/` calls
+ * so sibling blocks reading `/view/...` bindings update — mirroring
+ * U1's `SurfaceActionsCtx.setView`) and `serverErrors` (a rejected
+ * action's `{error: {field}}` surfaces under that field, §5.6).
+ * `bindRaw` routes `/view/`-rooted pointers to `view.values` so EVERY
+ * block (not only the writing form) reads the branch.
+ */
+import type { Action, Binding, JsonObject, JsonValue, Tone } from "@sigrun/shared/blocks";
+import type { TuiTheme } from "../theme.js";
+/** The channel-owned view state a render reads (spec §6.2). */
+export interface ViewState {
+    /** Values written by view-only actions (live forms bound `/view/`). */
+    values: JsonObject;
+}
+/** The render context {@link renderBlock} threads to every component. */
+export interface BlockCtx {
+    /** The surface's confirmed data model (bindings resolve against it). */
+    data: JsonObject;
+    /** The current item, inside a collection's card template (`./` pointers). */
+    item?: JsonValue;
+    theme: TuiTheme;
+    locale: string;
+    /**
+     * Time zone for `Intl` time formats (chart axes, log timestamps);
+     * absent means the runtime's local zone. Tests pass `UTC` for
+     * byte-stable output (`formatValue`'s fourth argument).
+     */
+    timeZone?: string;
+    access: "read" | "write";
+    /**
+     * Whether the terminal renders Unicode glyphs (spec §10.2): false
+     * selects the ASCII fallbacks — `icons.ts` glyphs and `tones.ts`
+     * markers — so an ASCII terminal never shows mojibake.
+     */
+    unicode: boolean;
+    /** Route an action to the surface (view-only ones never reach this). */
+    dispatch(action: Action, payload: JsonValue): void;
+    view: ViewState;
+    /**
+     * Write the channel-owned `/view/` branch (spec §6.2): `path` is a
+     * JSON pointer under the branch (no leading `/view/` — the writer
+     * roots at the branch, as U1's `setView` does). A live form bound
+     * under `/view/` calls this after its 300 ms debounce; the write
+     * never reaches the server.
+     */
+    setView?(path: string, value: JsonValue): void;
+    /**
+     * Server-side field errors, keyed by field name (spec §5.6: a
+     * rejected action's `{error: {field}}` surfaces under that field).
+     */
+    readonly serverErrors?: Readonly<Record<string, string>>;
+    /** The host's edit-in-$EDITOR seam (longtext with `syntax: code`;
+     *  spec §5.6). The form calls it with the current text; it returns
+     *  the new text (the TUI suspends while the editor owns the
+     *  terminal, as the composer's vim flow does). */
+    openEditor?(text: string): {
+        ok: true;
+        text: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /** The surface's upload seam (§7.2): a file field hands the bytes
+     *  here after dispatching `onUpload`. Optional — without it the
+     *  bytes ride the dispatch payload as base64. */
+    uploadBytes?(field: string, name: string, bytes: Uint8Array): void;
+    /** The terminal copy writes to (OSC 52); defaults to process.stdout. */
+    terminal?: {
+        write(data: string): void;
+    };
+}
+/** Is `value` a binding (spec §4.2: `{ $: pointer }`)? */
+export declare function isBinding(value: unknown): value is Binding;
+/** Resolve a bindable of any shape to its raw JSON value (untyped).
+ *  A `/view/`-rooted pointer resolves against the channel-owned view
+ *  branch (spec §6.2 — the sibling-read half of the setView seam: a
+ *  block bound `{$: "/view/..."}` sees what a view-bound live form
+ *  wrote); everything else resolves against ctx.data. */
+export declare function bindRaw(value: unknown, ctx: BlockCtx): JsonValue | undefined;
+/** Resolve a bindable to text: empty string for missing or non-string values. */
+export declare function bindText(value: unknown, ctx: BlockCtx): string;
+/** Resolve a bindable tone: `neutral` when absent or not a tone name. */
+export declare function bindTone(value: unknown, ctx: BlockCtx): Tone;
+/** True when a block's `visibleAt` hides it at the rendered width class. */
+export declare function hiddenAtCompact(block: {
+    readonly visibleAt?: string;
+}, width: number): boolean;

package/dist/blocks/context.js

@@ -0,0 +1,65 @@
+/**
+ * The block render context (UI-blocks U2 Task 1): everything a block
+ * component reads while rendering — the surface's data, the theme, the
+ * locale, the principal's access, the dispatch seam and the channel's
+ * view state — plus the binding/text resolution helpers every block
+ * renderer shares.
+ *
+ * `view` is the channel-owned view-state branch (spec §6.2): sort,
+ * filter, expansion, selection. Task 5 (forms) widened the seam with
+ * `setView` (the `/view/` writer a live form bound under `/view/` calls
+ * so sibling blocks reading `/view/...` bindings update — mirroring
+ * U1's `SurfaceActionsCtx.setView`) and `serverErrors` (a rejected
+ * action's `{error: {field}}` surfaces under that field, §5.6).
+ * `bindRaw` routes `/view/`-rooted pointers to `view.values` so EVERY
+ * block (not only the writing form) reads the branch.
+ */
+import { resolvePointer } from "@sigrun/shared/blocks";
+/** Is `value` a binding (spec §4.2: `{ $: pointer }`)? */
+export function isBinding(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.$ === "string");
+}
+/** The tone names (the `bindTone` guard's set). */
+const TONES = new Set([
+    "neutral",
+    "accent",
+    "good",
+    "warn",
+    "bad",
+    "info",
+]);
+/** Resolve a bindable of any shape to its raw JSON value (untyped).
+ *  A `/view/`-rooted pointer resolves against the channel-owned view
+ *  branch (spec §6.2 — the sibling-read half of the setView seam: a
+ *  block bound `{$: "/view/..."}` sees what a view-bound live form
+ *  wrote); everything else resolves against ctx.data. */
+export function bindRaw(value, ctx) {
+    if (!isBinding(value))
+        return value;
+    if (value.$.startsWith("/view/") || value.$ === "/view") {
+        const pointer = value.$.replace(/^\/view\/?/, "/");
+        const resolved = resolvePointer(ctx.view.values, pointer);
+        if (resolved !== undefined)
+            return resolved;
+        return undefined;
+    }
+    return resolvePointer(ctx.data, value.$, ctx.item);
+}
+/** Resolve a bindable to text: empty string for missing or non-string values. */
+export function bindText(value, ctx) {
+    const resolved = bindRaw(value, ctx);
+    return typeof resolved === "string" ? resolved : "";
+}
+/** Resolve a bindable tone: `neutral` when absent or not a tone name. */
+export function bindTone(value, ctx) {
+    const resolved = bindRaw(value, ctx);
+    return TONES.has(typeof resolved === "string" ? resolved : "")
+        ? resolved
+        : "neutral";
+}
+/** True when a block's `visibleAt` hides it at the rendered width class. */
+export function hiddenAtCompact(block, width) {
+    return block.visibleAt === "atLeast:regular" && width < 80;
+}

package/dist/blocks/diff.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The interaction diff renderer, extracted (UI-blocks U2 Task 1): the
+ * prompt strip's before/after lines — `[diff] path` then `- `/`+ `
+ * prefixed lines — reused VERBATIM by the `diff` block so chat diffs
+ * and interaction diffs render identically.
+ *
+ * The extraction is byte-identical to the lines
+ * `InteractionPrompter.render` produced inline (tui/src/ui/interactions.ts);
+ * that component now calls {@link diffLines}.
+ */
+import type { DiffBlock } from "@sigrun/shared/blocks";
+/** The shape the interaction seam's diff primitive carries. */
+export interface InteractionDiff {
+    before: string;
+    after: string;
+    path?: string;
+}
+/** Render a diff as `[diff] path` plus `- `/`+ ` lines. */
+export declare function diffLines(diff: InteractionDiff): string[];
+/** The `diff` block's diff (same wire fields). */
+export declare function blockDiff(block: DiffBlock): InteractionDiff;

package/dist/blocks/diff.js

@@ -0,0 +1,25 @@
+/**
+ * The interaction diff renderer, extracted (UI-blocks U2 Task 1): the
+ * prompt strip's before/after lines — `[diff] path` then `- `/`+ `
+ * prefixed lines — reused VERBATIM by the `diff` block so chat diffs
+ * and interaction diffs render identically.
+ *
+ * The extraction is byte-identical to the lines
+ * `InteractionPrompter.render` produced inline (tui/src/ui/interactions.ts);
+ * that component now calls {@link diffLines}.
+ */
+/** Render a diff as `[diff] path` plus `- `/`+ ` lines. */
+export function diffLines(diff) {
+    const lines = [
+        diff.path === undefined ? "[diff]" : `[diff] ${diff.path}`,
+    ];
+    for (const line of diff.before.split("\n"))
+        lines.push(`- ${line}`);
+    for (const line of diff.after.split("\n"))
+        lines.push(`+ ${line}`);
+    return lines;
+}
+/** The `diff` block's diff (same wire fields). */
+export function blockDiff(block) {
+    return { before: block.before, after: block.after, path: block.path };
+}

package/dist/blocks/ext-transport.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The TUI's extension-surface transport (UI-blocks U3 Task 5): implements
+ * the shared `SurfaceTransport` contract over the U3 routes (spec §7.2)
+ * as the TUI's remote client. One transport = one surface instance
+ * (slug + id + params); the wire `k` (hashed instance key) keys the
+ * change-event routing in {@link ExtSurfaceHub}.
+ *
+ * Like the webui twin, every fetch carries `X-Sigrun-Stream` once the
+ * launcher hands the stream id in (the watcher entry's stream);
+ * `image()` rejects until U7 ships the route. The channel owns
+ * refreshMs cadence, the keepalive, and visibility gating (U2).
+ */
+import type { JsonObject, SurfaceTransport } from "@sigrun/shared/blocks";
+export interface ExtSurfaceTransportOptions {
+    /** The extension slug (the `/v1/ext/<slug>/` prefix segment). */
+    readonly slug: string;
+    /** The surface id within the extension. */
+    readonly id: string;
+    /** The instance params; absent → `{}` (the route's default). */
+    readonly params?: JsonObject;
+    /** The current `/v1/events` stream id (the watcher entry's stream). */
+    readonly streamId?: string;
+    /** The server's origin (the launcher that constructs the client owns it). */
+    readonly baseUrl: string;
+    readonly user?: string;
+    readonly token?: string;
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * The TUI's transport handle (U3 Task 5 fix round): the `SurfaceTransport`
+ * plus `setStreamId` — a `/v1/events` reconnect hands the OPEN view the
+ * new stream id without re-creating the transport (the next fetch
+ * carries it, re-registering the watcher entry, spec §7.3).
+ */
+export interface ExtSurfaceTransportHandle {
+    readonly transport: SurfaceTransport;
+    /** Update the watcher stream id (a reconnect's hello); subsequent
+     *  fetches carry the new id. */
+    setStreamId(streamId: string | undefined): void;
+}
+/**
+ * The wire `k` for one surface instance (spec §7.3), Node flavor:
+ * `sha256(slug + "\0" + id + "\0" + key)` hex. The TUI's transport
+ * computes it synchronously (the WebCrypto twin in `@sigrun/shared/
+ * blocks` is async — DOM-only).
+ */
+export declare function surfaceKeyHash(slug: string, id: string, key: string): string;
+/** The instance key for one transport's params (the default rule). */
+export declare function transportKey(options: ExtSurfaceTransportOptions): string;
+/** Create the TUI's extension-surface transport. */
+export declare function createExtSurfaceTransport(options: ExtSurfaceTransportOptions): ExtSurfaceTransportHandle;
+/**
+ * The change-event router (the launcher's dispatch seam): `attach`
+ * creates a transport whose `onChanged` subscribes into the hub under
+ * the instance's (slug, id, k); `dispatch` fans a `surface.changed`
+ * event out to the matching subscriptions only.
+ */
+export declare class ExtSurfaceHub {
+    #private;
+    /** Create a transport whose `onChanged` subscribes into this hub. */
+    attach(options: ExtSurfaceTransportOptions, keyHash: string): ExtSurfaceTransportHandle;
+    /** Fire every subscription matching the event's (slug, id, k). */
+    dispatch(event: {
+        readonly slug: string;
+        readonly id: string;
+        readonly k: string;
+        readonly rev: number;
+        readonly treeRev: number;
+    }): void;
+}