@sigrun/tui 0.0.0-stage → 0.1.1

package/dist/blocks/form/list.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The list field (UI-blocks U2 Task 5, spec §5.6): a repeatable group —
+ * `item` describes the field of ONE entry; the value is an array of
+ * entry values. Add (`a` on the field), remove (`d`), and reorder (`u`
+ * up / `j` down) honour `min`/`max`. Entries edit inline through the
+ * item field's text editor (choice/other items stay text-shaped in v1 —
+ * noted in the module header of the form).
+ */
+import type { JsonValue, ListField } from "@sigrun/shared/blocks";
+/** The entries of a list value (never undefined). */
+export declare function listEntries(value: JsonValue): readonly JsonValue[];
+/** Can the list add an entry (`max`)? */
+export declare function listCanAdd(field: ListField, value: JsonValue): boolean;
+/** Can the list remove an entry (`min`)? */
+export declare function listCanRemove(field: ListField, value: JsonValue): boolean;
+/** Add an entry (the item field's empty value). */
+export declare function listAdd(value: JsonValue): JsonValue;
+/** Remove the entry at `index`. */
+export declare function listRemove(value: JsonValue, index: number): JsonValue;
+/** Move the entry at `index` by `delta` (reorder; clamped). */
+export declare function listMove(value: JsonValue, index: number, delta: number): JsonValue;
+/** Replace the entry at `index`. */
+export declare function listSet(value: JsonValue, index: number, entry: JsonValue): JsonValue;
+/** The per-field list state: the entry cursor. */
+export declare class ListFieldState {
+    cursor: number;
+}
+/** Render the entries (one editor line each) plus the hint row. */
+export declare function listLines(opts: {
+    field: ListField;
+    width: number;
+    value: JsonValue;
+    state: ListFieldState;
+    focused: boolean;
+    /** The rendered editor line of an entry (the form seeds caret state). */
+    entryLine(index: number, entry: JsonValue, focused: boolean): string;
+}): string[];

package/dist/blocks/form/list.js

@@ -0,0 +1,70 @@
+/**
+ * The list field (UI-blocks U2 Task 5, spec §5.6): a repeatable group —
+ * `item` describes the field of ONE entry; the value is an array of
+ * entry values. Add (`a` on the field), remove (`d`), and reorder (`u`
+ * up / `j` down) honour `min`/`max`. Entries edit inline through the
+ * item field's text editor (choice/other items stay text-shaped in v1 —
+ * noted in the module header of the form).
+ */
+import { truncate } from "../width.js";
+/** The entries of a list value (never undefined). */
+export function listEntries(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** Can the list add an entry (`max`)? */
+export function listCanAdd(field, value) {
+    return field.max === undefined || listEntries(value).length < field.max;
+}
+/** Can the list remove an entry (`min`)? */
+export function listCanRemove(field, value) {
+    return listEntries(value).length > (field.min ?? 0);
+}
+/** Add an entry (the item field's empty value). */
+export function listAdd(value) {
+    return [...listEntries(value), ""];
+}
+/** Remove the entry at `index`. */
+export function listRemove(value, index) {
+    return listEntries(value).filter((_, at) => at !== index);
+}
+/** Move the entry at `index` by `delta` (reorder; clamped). */
+export function listMove(value, index, delta) {
+    const entries = [...listEntries(value)];
+    const target = index + delta;
+    if (target < 0 || target >= entries.length)
+        return entries;
+    const [entry] = entries.splice(index, 1);
+    entries.splice(target, 0, entry);
+    return entries;
+}
+/** Replace the entry at `index`. */
+export function listSet(value, index, entry) {
+    return listEntries(value).map((current, at) => (at === index ? entry : current));
+}
+/** The per-field list state: the entry cursor. */
+export class ListFieldState {
+    cursor = 0;
+}
+/** Render the entries (one editor line each) plus the hint row. */
+export function listLines(opts) {
+    const { field, width, value, state, focused } = opts;
+    const entries = listEntries(value);
+    const lines = [];
+    entries.forEach((entry, index) => {
+        const cursor = focused && index === state.cursor ? "> " : "  ";
+        lines.push(truncate(`${cursor}${opts.entryLine(index, entry, focused && index === state.cursor)}`, width));
+    });
+    if (focused) {
+        const hints = [];
+        if (listCanAdd(field, value))
+            hints.push("a add");
+        if (entries.length > 0 && listCanRemove(field, value))
+            hints.push("d remove");
+        if (field.reorder === true && entries.length > 1)
+            hints.push("u/j move");
+        if (hints.length > 0) {
+            lines.push(truncate(`  ${hints.join(" · ")}`, width));
+        }
+    }
+    return lines;
+}

package/dist/blocks/form/values.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Form values plumbing (UI-blocks U2 Task 5, spec §5.6 — the port of
+ * U1's `form/values.ts`): the form reads its initial values from the
+ * bound object and tracks edits locally; these helpers flatten the
+ * field tree (sections nest fields), read a field's value out of the
+ * bound object, and validate a value against the shared field props
+ * (`required`, `min`/`max`, `minLength`/`maxLength`, `pattern`).
+ */
+import type { Field, FormBlock, JsonValue } from "@sigrun/shared/blocks";
+/** Whether a form child is a field (sections hold fields/blocks). */
+export declare function isFieldNode(node: unknown): node is Field;
+/** All fields of the form, depth-first through sections. */
+export declare function collectFields(block: FormBlock): readonly Field[];
+/** The initial value of a field from the bound object (missing →
+ *  a type-appropriate empty; a secret is write-only — the bound slot
+ *  carries the STATUS, never a value to echo back, §5.6/§15). */
+export declare function initialValue(field: Field, bound: Record<string, JsonValue>): JsonValue;
+/** Client validation (spec §5.6): the error message or null.
+ *  `label` names the field in the message. */
+export declare function validateField(field: Field, value: JsonValue, label: string): string | null;

package/dist/blocks/form/values.js

@@ -0,0 +1,104 @@
+/**
+ * Form values plumbing (UI-blocks U2 Task 5, spec §5.6 — the port of
+ * U1's `form/values.ts`): the form reads its initial values from the
+ * bound object and tracks edits locally; these helpers flatten the
+ * field tree (sections nest fields), read a field's value out of the
+ * bound object, and validate a value against the shared field props
+ * (`required`, `min`/`max`, `minLength`/`maxLength`, `pattern`).
+ */
+/** Whether a form child is a field (sections hold fields/blocks). */
+export function isFieldNode(node) {
+    return (typeof node === "object" &&
+        node !== null &&
+        typeof node.type === "string" &&
+        typeof node.name === "string");
+}
+/** All fields of the form, depth-first through sections. */
+export function collectFields(block) {
+    const out = [];
+    const walk = (children) => {
+        for (const child of children) {
+            if (isFieldNode(child))
+                out.push(child);
+            else if (typeof child === "object" &&
+                child !== null &&
+                child.type === "section") {
+                walk(child.children);
+            }
+        }
+    };
+    walk(block.children);
+    return out;
+}
+/** The initial value of a field from the bound object (missing →
+ *  a type-appropriate empty; a secret is write-only — the bound slot
+ *  carries the STATUS, never a value to echo back, §5.6/§15). */
+export function initialValue(field, bound) {
+    if (field.type === "secret")
+        return "";
+    const value = bound[field.name];
+    if (value !== undefined)
+        return value;
+    switch (field.type) {
+        case "toggle":
+            return false;
+        case "choice":
+            return field.multi === true ? [] : "";
+        case "list":
+            return [];
+        case "daterange":
+            return {};
+        default:
+            return "";
+    }
+}
+/** Client validation (spec §5.6): the error message or null.
+ *  `label` names the field in the message. */
+export function validateField(field, value, label) {
+    const empty = value === undefined ||
+        value === null ||
+        value === "" ||
+        (Array.isArray(value) && value.length === 0) ||
+        (typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0);
+    if (field.required === true && empty)
+        return `${label} is required`;
+    if (empty)
+        return null;
+    if (typeof value === "number") {
+        if (field.min !== undefined && value < field.min) {
+            return `${label} must be at least ${field.min}`;
+        }
+        if (field.max !== undefined && value > field.max) {
+            return `${label} must be at most ${field.max}`;
+        }
+    }
+    if (typeof value === "string") {
+        if (field.minLength !== undefined && value.length < field.minLength) {
+            return `${label} must be at least ${field.minLength} characters`;
+        }
+        if (field.maxLength !== undefined && value.length > field.maxLength) {
+            return `${label} must be at most ${field.maxLength} characters`;
+        }
+        if (field.pattern !== undefined && value !== "") {
+            let regex = null;
+            try {
+                regex = new RegExp(`^(?:${field.pattern})$`);
+            }
+            catch {
+                regex = null;
+            }
+            if (regex !== null && !regex.test(value)) {
+                return `${label} does not match ${field.pattern}`;
+            }
+        }
+    }
+    if (Array.isArray(value)) {
+        if (field.min !== undefined && value.length < field.min) {
+            return `${label} needs at least ${field.min} entries`;
+        }
+        if (field.max !== undefined && value.length > field.max) {
+            return `${label} allows at most ${field.max} entries`;
+        }
+    }
+    return null;
+}

package/dist/blocks/icons.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Named icons in the terminal (UI-blocks spec §10.2): each of the 49
+ * closed-set names maps to a Unicode glyph with an ASCII fallback. The
+ * ASCII form is used when the terminal can't be assumed to render the
+ * glyph (the plain/no-Unicode path, and tests that assert structure).
+ *
+ * Glyphs are chosen for terminal legibility over pictorial fidelity
+ * (a 1-cell glyph beats a 2-cell emoji that shifts the grid): mostly
+ * Miscellaneous Symbols and Dingbats, all narrow in standard terminals.
+ */
+import type { IconName } from "@sigrun/shared/blocks";
+/** The icon glyph for `name` (the ASCII fallback when the terminal
+ * lacks Unicode support — callers pass `!ctx.unicode`). */
+export declare function iconGlyph(name: IconName, ascii: boolean): string;

package/dist/blocks/icons.js

@@ -0,0 +1,74 @@
+/**
+ * Named icons in the terminal (UI-blocks spec §10.2): each of the 49
+ * closed-set names maps to a Unicode glyph with an ASCII fallback. The
+ * ASCII form is used when the terminal can't be assumed to render the
+ * glyph (the plain/no-Unicode path, and tests that assert structure).
+ *
+ * Glyphs are chosen for terminal legibility over pictorial fidelity
+ * (a 1-cell glyph beats a 2-cell emoji that shifts the grid): mostly
+ * Miscellaneous Symbols and Dingbats, all narrow in standard terminals.
+ */
+/** The Unicode glyph and its ASCII fallback, per icon name. */
+const GLYPHS = {
+    // navigation and actions
+    add: ["+", "+"],
+    edit: ["✎", "e"],
+    delete: ["✖", "x"],
+    refresh: ["↻", "r"],
+    search: ["⌕", "/"],
+    filter: ["▽", "f"],
+    share: ["⇱", "s"],
+    copy: ["⧉", "c"],
+    link: ["⚓", "l"],
+    external: ["↗", "^"],
+    more: ["⋯", "."],
+    check: ["✓", "v"],
+    close: ["✕", "x"],
+    drag: ["⠿", "#"],
+    // objects
+    file: ["▤", "f"],
+    folder: ["▸", ">"],
+    calendar: ["▦", "#"],
+    clock: ["◷", "o"],
+    user: ["◔", "u"],
+    users: ["◍", "U"],
+    tag: ["◇", "t"],
+    list: ["☰", "="],
+    board: ["▥", "|"],
+    chart: ["▄", "c"],
+    image: ["▣", "i"],
+    book: ["❑", "b"],
+    cart: ["▤", "C"],
+    home: ["⌂", "h"],
+    bell: ["⚑", "B"],
+    lock: ["▪", "L"],
+    key: ["◂", "K"],
+    // status
+    info: ["ℹ", "i"],
+    warn: ["▲", "!"],
+    error: ["✖", "!!"],
+    success: ["✓", "v"],
+    pending: ["◌", "-"],
+    running: ["▶", "R"],
+    // weather
+    sun: ["☀", "*"],
+    moon: ["☾", ")"],
+    cloud: ["☁", "o"],
+    "cloud-sun": ["⛅", "o*"],
+    "cloud-rain": ["☔", "or"],
+    "cloud-snow": ["❄", "os"],
+    "cloud-lightning": ["⚡", "ol"],
+    fog: ["≋", "~"],
+    wind: ["≈", "w"],
+    droplets: ["❍", "d"],
+    thermometer: ["▴", "T"],
+    umbrella: ["☂", "u"],
+};
+/** The icon glyph for `name` (the ASCII fallback when the terminal
+ * lacks Unicode support — callers pass `!ctx.unicode`). */
+export function iconGlyph(name, ascii) {
+    const pair = GLYPHS[name];
+    if (pair === undefined)
+        return ascii ? "?" : name;
+    return ascii ? pair[1] : pair[0];
+}

package/dist/blocks/image.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The `image` block (UI-blocks spec §11.3): pi-tui's `Image` when
+ * `getCapabilities().images` is kitty/iterm2 and the bytes arrived;
+ * `[image: <alt>]` otherwise (no protocol, a failed or refused fetch,
+ * a missing alt). Every non-PNG source is requested with `as=png`
+ * (the server-side conversion, ruling 17); TMUX handling is pi-tui's
+ * own (`terminal-image.js` turns images off under TMUX unless
+ * `PI_IMAGE_PROTOCOL` overrides) — this block adds no detection.
+ *
+ * The byte-fetch is an injectable seam ({@link FetchImageBytes}): the
+ * surface transport that resolves `asset:`/URL sources lands in
+ * Task 4; tests fake it. Images size to the block's width in cells,
+ * capped at 20 rows.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { ImageBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+/**
+ * Fetch the bytes for one image source. `asPng` asks the transport
+ * for the server-side PNG conversion (ruling 17); rejection or a
+ * throw renders the alt fallback.
+ */
+export type FetchImageBytes = (src: string, opts: {
+    asPng: boolean;
+}) => Promise<Uint8Array>;
+/** The extra options {@link renderImageBlock} takes (the seams). */
+export interface ImageOptions {
+    /** The byte transport; absent renders the alt (nothing to fetch with). */
+    fetchImage?: FetchImageBytes;
+}
+/** The fallback line for `alt` (`[image]` when the alt is missing). */
+export declare function imageFallbackLine(alt: string): string;
+/** `image`: fetch-then-render, with the alt as the standing fallback. */
+export declare class ImageComponent implements Component {
+    #private;
+    constructor(block: ImageBlock, ctx: BlockCtx, options?: ImageOptions);
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/blocks/image.js

@@ -0,0 +1,82 @@
+/**
+ * The `image` block (UI-blocks spec §11.3): pi-tui's `Image` when
+ * `getCapabilities().images` is kitty/iterm2 and the bytes arrived;
+ * `[image: <alt>]` otherwise (no protocol, a failed or refused fetch,
+ * a missing alt). Every non-PNG source is requested with `as=png`
+ * (the server-side conversion, ruling 17); TMUX handling is pi-tui's
+ * own (`terminal-image.js` turns images off under TMUX unless
+ * `PI_IMAGE_PROTOCOL` overrides) — this block adds no detection.
+ *
+ * The byte-fetch is an injectable seam ({@link FetchImageBytes}): the
+ * surface transport that resolves `asset:`/URL sources lands in
+ * Task 4; tests fake it. Images size to the block's width in cells,
+ * capped at 20 rows.
+ */
+import { getCapabilities, Image } from "@earendil-works/pi-tui";
+import { bindText } from "./context.js";
+import { truncate } from "./width.js";
+/** The row cap (spec §11.3). */
+const MAX_IMAGE_ROWS = 20;
+/** Does the source name a PNG already (extension or data URL)? */
+function isPng(src) {
+    if (src.startsWith("data:"))
+        return src.startsWith("data:image/png");
+    return /\.png($|[?#])/i.test(src);
+}
+/** The fallback line for `alt` (`[image]` when the alt is missing). */
+export function imageFallbackLine(alt) {
+    return alt === "" ? "[image]" : `[image: ${alt}]`;
+}
+/** `image`: fetch-then-render, with the alt as the standing fallback. */
+export class ImageComponent {
+    #block;
+    #ctx;
+    #options;
+    /** The fetched component once the bytes are in (one fetch ever). */
+    #image;
+    /** "idle" not started; "pending" renders [] while the fetch runs. */
+    #state = "idle";
+    constructor(block, ctx, options = {}) {
+        this.#block = block;
+        this.#ctx = ctx;
+        this.#options = options;
+    }
+    render(width) {
+        const alt = bindText(this.#block.alt, this.#ctx);
+        const protocol = getCapabilities().images;
+        const src = bindText(this.#block.src, this.#ctx);
+        const fetch = this.#options.fetchImage;
+        if (protocol !== "kitty" && protocol !== "iterm2") {
+            return [truncate(imageFallbackLine(alt), width)];
+        }
+        if (fetch === undefined || src === "") {
+            return [truncate(imageFallbackLine(alt), width)];
+        }
+        if (this.#state === "idle") {
+            this.#state = "pending";
+            void fetch(src, { asPng: !isPng(src) })
+                .then((bytes) => {
+                let binary = "";
+                for (const byte of bytes)
+                    binary += String.fromCharCode(byte);
+                this.#image = new Image(btoa(binary), "image/png", { fallbackColor: this.#ctx.theme.dim }, { maxWidthCells: width, maxHeightCells: MAX_IMAGE_ROWS });
+            })
+                .catch(() => {
+                this.#state = "failed";
+            });
+        }
+        if (this.#state === "failed") {
+            return [truncate(imageFallbackLine(alt), width)];
+        }
+        if (this.#image === undefined) {
+            // Bytes pending: render nothing until the fetch resolves
+            // (the host re-renders; a transient empty beats a flash of
+            // the fallback line).
+            return [];
+        }
+        return this.#image.render(width);
+    }
+    invalidate() {
+        this.#image?.invalidate();
+    }
+}

package/dist/blocks/layout.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The layout blocks (UI-blocks spec §5.2): `stack`, `columns`, `grid`,
+ * `section` as pi-tui components.
+ *
+ * Columns/grid honour the compact fallbacks (spec §12.3): `columns`
+ * stack when the minimums don't fit; `grid` runs
+ * `max(1, floor(width / minItemWidth))` columns so a compact pane gets
+ * one. Every line every block emits is clamped to the pane
+ * ({@link truncate} — Review Focus 2).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { ColumnsBlock, GridBlock, SectionBlock, StackBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+/**
+ * A component from a width-aware line builder. Each produced line is
+ * clamped to the render width (the invariant every block must keep).
+ */
+export declare class Lines implements Component {
+    #private;
+    constructor(build: (width: number) => string[]);
+    render(width: number): string[];
+    invalidate(): void;
+}
+/** Render `children` vertically with `gap` blank lines between. */
+export declare function renderStack(block: StackBlock, ctx: BlockCtx): Component;
+/** Render children side by side, stacking when the minimums don't fit. */
+export declare function renderColumns(block: ColumnsBlock, ctx: BlockCtx): Component;
+/** Render children in as many columns as `minItemWidth` allows. */
+export declare function renderGrid(block: GridBlock, ctx: BlockCtx): Component;
+/** Render a titled, optionally toned group of children. */
+export declare function renderSection(block: SectionBlock, ctx: BlockCtx): Component;

package/dist/blocks/layout.js

@@ -0,0 +1,155 @@
+/**
+ * The layout blocks (UI-blocks spec §5.2): `stack`, `columns`, `grid`,
+ * `section` as pi-tui components.
+ *
+ * Columns/grid honour the compact fallbacks (spec §12.3): `columns`
+ * stack when the minimums don't fit; `grid` runs
+ * `max(1, floor(width / minItemWidth))` columns so a compact pane gets
+ * one. Every line every block emits is clamped to the pane
+ * ({@link truncate} — Review Focus 2).
+ */
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { renderBlock } from "./render.js";
+import { bindText, bindTone } from "./context.js";
+import { SIZE_CELLS, pad, truncate } from "./width.js";
+import { toneFg, toneMarker } from "./tones.js";
+/** The blank line counts the `gap` tokens map to. */
+const GAP_LINES = { s: 0, m: 1, l: 2 };
+/** The section header rule character. */
+const RULE = "─";
+/**
+ * A component from a width-aware line builder. Each produced line is
+ * clamped to the render width (the invariant every block must keep).
+ */
+export class Lines {
+    #build;
+    constructor(build) {
+        this.#build = build;
+    }
+    render(width) {
+        return this.#build(width).map((line) => truncate(line, width));
+    }
+    invalidate() {
+        // Stateless render: lines re-assemble on the next render call.
+    }
+}
+/** Join child blocks vertically, a blank line between neighbours. */
+function stacked(children, ctx, width, gap) {
+    const out = [];
+    for (const child of children) {
+        const lines = renderBlock(child, ctx).render(width);
+        if (out.length > 0 && lines.length > 0) {
+            for (let i = 0; i < gap; i++)
+                out.push("");
+        }
+        out.push(...lines);
+    }
+    return out;
+}
+/** Render `children` vertically with `gap` blank lines between. */
+export function renderStack(block, ctx) {
+    return new Lines((width) => stacked(block.children, ctx, width, GAP_LINES[block.gap ?? "m"]));
+}
+/** Render children side by side, stacking when the minimums don't fit. */
+export function renderColumns(block, ctx) {
+    return new Lines((width) => {
+        const minimums = block.children.map((child) => child.minWidth === undefined ? SIZE_CELLS.s : SIZE_CELLS[child.minWidth]);
+        const total = minimums.reduce((a, b) => a + b, 0) + Math.max(0, block.children.length - 1);
+        // Compact fallback (spec §12.3): stack when the minimums don't fit.
+        if (width < total) {
+            return stacked(block.children.map((child) => child.block), ctx, width, 1);
+        }
+        // Side by side: render each child at a weighted slot, then zip
+        // the line arrays into rows (shorter columns pad with blanks).
+        const weights = block.children.map((child) => child.weight ?? 1);
+        const weightSum = weights.reduce((a, b) => a + b, 0);
+        const separators = block.children.length - 1;
+        const slots = weights.map((weight) => Math.max(1, Math.floor(((width - separators) * weight) / weightSum)));
+        const rendered = block.children.map((child, index) => renderBlock(child.block, ctx).render(slots[index]));
+        const height = Math.max(...rendered.map((lines) => lines.length));
+        const rows = [];
+        for (let row = 0; row < height; row++) {
+            rows.push(rendered
+                .map((lines, index) => pad(lines[row] ?? "", slots[index]))
+                .join(" "));
+        }
+        return rows;
+    });
+}
+/** Render children in as many columns as `minItemWidth` allows. */
+export function renderGrid(block, ctx) {
+    return new Lines((width) => {
+        const minItem = SIZE_CELLS[block.minItemWidth];
+        const columns = Math.max(1, Math.floor(width / minItem));
+        const columnWidth = Math.max(1, Math.floor((width - (columns - 1)) / columns));
+        // Slot each child by its span ("full" spans every column).
+        const rows = [];
+        let current = [];
+        let used = 0;
+        const flush = () => {
+            if (current.length > 0)
+                rows.push(current);
+            current = [];
+            used = 0;
+        };
+        for (const child of block.children) {
+            let span = 1;
+            if (child.span === "full")
+                span = columns;
+            else if (child.span !== undefined)
+                span = Math.min(child.span, columns);
+            if (used > 0 && used + span > columns)
+                flush();
+            current.push({
+                span,
+                lines: renderBlock(child.block, ctx).render(columnWidth * span + (span - 1)),
+            });
+            used += span;
+        }
+        flush();
+        // Zip each row's cells into lines (shorter cells pad with blanks).
+        const out = [];
+        for (const row of rows) {
+            const height = Math.max(...row.map((cell) => cell.lines.length));
+            const widths = row.map((cell) => columnWidth * cell.span + (cell.span - 1));
+            for (let line = 0; line < height; line++) {
+                out.push(row
+                    .map((cell, index) => pad(cell.lines[line] ?? "", widths[index]))
+                    .join(" "));
+            }
+        }
+        return out;
+    });
+}
+/** Render a titled, optionally toned group of children. */
+export function renderSection(block, ctx) {
+    return new Lines((width) => {
+        const title = bindText(block.title ?? "", ctx);
+        const subtitle = bindText(block.subtitle ?? "", ctx);
+        const out = [];
+        if (title !== "") {
+            if (block.tone !== undefined) {
+                const tone = bindTone(block.tone, ctx);
+                const head = `${toneFg(ctx.theme, tone)(toneMarker(tone, !ctx.unicode))} ${title}`;
+                const rule = RULE.repeat(Math.max(0, width - visibleWidth(head) - 1));
+                out.push(`${head} ${ctx.theme.dim(rule)}`);
+            }
+            else {
+                const rule = RULE.repeat(Math.max(0, width - visibleWidth(title) - 1));
+                out.push(`${title} ${ctx.theme.dim(rule)}`);
+            }
+        }
+        if (subtitle !== "")
+            out.push(ctx.theme.dim(subtitle));
+        // `collapsed` is the author's INITIAL state (§5.2): children stay
+        // hidden until a later task's toggle expands them.
+        const children = block.collapsed
+            ? []
+            : block.children.filter((child) => "name" in child === false);
+        const inner = width - 2;
+        const body = stacked(children, ctx, Math.max(1, inner), GAP_LINES.m);
+        for (const line of body)
+            out.push(line === "" ? "" : `  ${line}`);
+        return out;
+    });
+}

package/dist/blocks/log.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `log` block (UI-blocks spec §5.3): bound `{at?, level?, text}[]`
+ * lines in a block-local viewport of {@link LOG_VIEWPORT_ROWS} rows.
+ *
+ * With `follow` the viewport pins to the tail until the user scrolls
+ * up; scrolling back to the bottom re-arms the following (the
+ * transcript convention). Per-level tones default `error`→bad,
+ * `warn`→warn, `info`→neutral, `debug`→info (the muted token);
+ * `tones` overrides per level. `wrap` folds long lines instead of
+ * truncating them.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { LogBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+/** The viewport height in rows. */
+export declare const LOG_VIEWPORT_ROWS = 10;
+/** `log`: the follow-tail viewport. */
+export declare class LogComponent implements Component {
+    #private;
+    constructor(block: LogBlock, ctx: BlockCtx);
+    render(width: number): string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+}