@north-light/api 0.3.580 → 0.3.587

package/dist/core/termrender/version.d.ts

@@ -0,0 +1 @@
+export declare const TERMRENDER_VERSION = "4.13.0";

package/dist/core/termrender/version.js

@@ -0,0 +1 @@
+export const TERMRENDER_VERSION = '4.13.0';

package/dist/core/timing.d.ts

@@ -0,0 +1,11 @@
+/** True when CRTR_TIMING is set — guard expensive marker payloads with this. */
+export declare function timingEnabled(): boolean;
+/** Label this process in the timing log (e.g. 'viewer', 'broker'). */
+export declare function timingProc(name: string): void;
+/**
+ * Record one phase marker. Columns:
+ *   `+`  ms since the shared cross-process origin (the whole front-door clock)
+ *   `Δ`  ms since the previous marker in THIS process
+ *   `up` ms since this process started (same sense as broker `duration_ms`)
+ */
+export declare function mark(phase: string, fields?: Record<string, unknown>): void;

package/dist/core/timing.js

@@ -0,0 +1,94 @@
+// timing.ts — CRTR_TIMING=1 cross-process phase markers for front-door latency.
+//
+// Why this exists: `node --cpu-prof` cannot see the front door, because opening
+// a node spans THREE processes — the `crtr` front-door process, the
+// `crtr surface attach` viewer it spawns, and the detached broker. A profile of
+// any one of them shows a fraction of the wall clock the user feels.
+//
+// So: hrtime-grade phase markers on ONE shared timeline. The first crtr process
+// to mark stamps `CRTR_TIMING_T0` (epoch ms, sub-ms precision) into its own env,
+// which every child it spawns inherits, so all three processes report offsets
+// from the same origin and the log reads as a single ordered timeline.
+//
+// The broker already emits `broker.startup.*` events carrying `duration_ms`
+// from its own process start (broker.ts / broker-cli.ts). This does NOT replace
+// or duplicate that shape — `mark()` mirrors the broker's `duration_ms` sense in
+// its `up=` column (ms since THIS process started), and adds the cross-process
+// `+` column the broker events cannot have.
+//
+// Off by default and effectively free when off: one env read, one comparison.
+// Output goes to stderr only — never stdout, which is the CLI's data contract.
+const FLAG = 'CRTR_TIMING';
+const ORIGIN = 'CRTR_TIMING_T0';
+/** Wall-clock epoch ms with sub-ms precision, comparable across processes. */
+function nowMs() {
+    return performance.timeOrigin + performance.now();
+}
+const enabled = (() => {
+    const v = process.env[FLAG];
+    return v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+})();
+// The shared origin. Inherited when a parent crtr process already stamped it;
+// otherwise this process is the origin and stamps its own env so the viewer and
+// broker it spawns (both spawned with `{...process.env}`) land on this timeline.
+const t0 = (() => {
+    if (!enabled)
+        return 0;
+    const inherited = Number(process.env[ORIGIN]);
+    if (Number.isFinite(inherited) && inherited > 0)
+        return inherited;
+    // This process is the origin — and its own start, not the moment timing.ts
+    // was evaluated, so module-graph load time is inside the first interval.
+    const own = performance.timeOrigin;
+    process.env[ORIGIN] = String(own);
+    return own;
+})();
+/** Short label for which of the three processes a marker came from. */
+const proc = (() => {
+    const explicit = process.env['CRTR_TIMING_PROC'];
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    // The attach viewer runs through the same cli entry as every other command;
+    // label it distinctly so a three-process timeline is readable at a glance.
+    if (process.argv[2] === 'surface' && process.argv[3] === 'attach')
+        return 'viewer';
+    return 'cli';
+})();
+let prev = 0;
+/** True when CRTR_TIMING is set — guard expensive marker payloads with this. */
+export function timingEnabled() {
+    return enabled;
+}
+/** Label this process in the timing log (e.g. 'viewer', 'broker'). */
+export function timingProc(name) {
+    if (!enabled)
+        return;
+    process.env['CRTR_TIMING_PROC'] = name;
+}
+/**
+ * Record one phase marker. Columns:
+ *   `+`  ms since the shared cross-process origin (the whole front-door clock)
+ *   `Δ`  ms since the previous marker in THIS process
+ *   `up` ms since this process started (same sense as broker `duration_ms`)
+ */
+export function mark(phase, fields) {
+    if (!enabled)
+        return;
+    const abs = nowMs();
+    const since = abs - t0;
+    const delta = prev === 0 ? since : abs - prev;
+    prev = abs;
+    const up = performance.now();
+    const tail = fields === undefined
+        ? ''
+        : ' ' +
+            Object.entries(fields)
+                .map(([k, v]) => `${k}=${String(v)}`)
+                .join(' ');
+    const name = process.env['CRTR_TIMING_PROC'] ?? proc;
+    const fmt = (n) => n.toFixed(1).padStart(8);
+    // `t=` is absolute epoch ms: the broker is spawned by crtrd, not by the
+    // front-door process, so it inherits no shared origin — the absolute stamp is
+    // what lets its markers be merged into the cli/viewer timeline after the fact.
+    process.stderr.write(`[timing] +${fmt(since)}ms Δ${fmt(delta)}ms up=${fmt(up)}ms t=${abs.toFixed(1)} ${name}/${process.pid} ${phase}${tail}\n`);
+}

package/dist/core/tui/draw.d.ts

@@ -0,0 +1,103 @@
+export declare const META_FG = "38;5;246";
+export declare const RECESSIVE_FG = "38;5;243";
+export interface Size {
+    cols: number;
+    rows: number;
+}
+export interface Rect {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+}
+export interface Style {
+    fg?: string;
+    bg?: string;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    reverse?: boolean;
+}
+export interface Span {
+    text: string;
+    style?: Style;
+}
+/** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
+ *  Guards styleSpan against a non-numeric value (a color name) producing a broken
+ *  escape sequence. */
+export declare function isSgrParams(v: string): boolean;
+/** Style one chunk of text. Hue (fg/bg) is gated on `color`; bold/dim/reverse
+ *  are not. After the styled text we return to `lineBase` (not a bare reset) so a
+ *  row-level background/dim persists across spans instead of bleeding or being
+ *  cleared. */
+export declare function styleSpan(text: string, style: Style | undefined, color: boolean, lineBase: string): string;
+/** Assemble styled spans into one line clipped to `width` visible cols. When
+ *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
+ *  background spans the full width. Always RESET-terminated so no color bleeds
+ *  into the next line. */
+export declare function assemble(spans: Span[], width: number, color: boolean, lineBase: string, fill: boolean): string;
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+export declare function clip(text: string, max: number): string;
+export interface ColorCaps {
+    /** Any hue (fg/bg color) allowed. */
+    color: boolean;
+    /** 256-color bg allowed — drives the subtle cursor-row background. */
+    color256: boolean;
+}
+/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
+ *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
+ *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
+export declare function detectColorCaps(stream?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): ColorCaps;
+/** One pre-styled list row (the view styles its own spans; `list` windows + the
+ *  cursor highlight are the host's job). An optional `right` group is flush-right
+ *  on the row (e.g. a timestamp) via spansRight; the left `spans` are clipped to
+ *  leave room for it, and the cursor-row highlight merges over both. */
+export interface ListItemRow {
+    spans: Span[];
+    right?: Span[];
+    /** Optional continuation lines drawn under `spans` as part of the SAME item
+     *  (e.g. a wrapped subtitle). They share the item's cursor highlight and the
+     *  item still counts as one cursor position; the list windows by screen rows. */
+    lines?: Span[][];
+}
+/** Adjusted scroll the view stores back so the cursor stays visible. */
+export interface ListResult {
+    scroll: number;
+}
+export interface Draw {
+    readonly size: Size;
+    readonly caps: ColorCaps;
+    /** Styled spans at an absolute cell, clipped to maxWidth (default → edge). */
+    spans(row: number, col: number, spans: Span[], maxWidth?: number): void;
+    /** Flush-right span placement (mirror of `spans`): the group's last visible
+     *  cell lands just before `rightCol` (i.e. start col = rightCol − visibleWidth,
+     *  rightCol exclusive). If the group exceeds `maxWidth` (default → the room left
+     *  of rightCol) the LEFT end is clipped with a leading `…`. */
+    spansRight(row: number, rightCol: number, spans: Span[], maxWidth?: number): void;
+    /** Convenience single span. */
+    text(row: number, col: number, text: string, style?: Style): void;
+    /** Dim horizontal rule across [fromCol,toCol) (default full width). */
+    hline(row: number, fromCol?: number, toCol?: number, ch?: string): void;
+    /** Dim vertical rule down column `col` across [fromRow,toRow) (default full
+     *  height). `ch` defaults to `│`; pass `|` as the ASCII fallback. */
+    vline(col: number, fromRow?: number, toRow?: number, ch?: string): void;
+    /** Single-line box border around rect (optional title in the top edge). */
+    box(rect: Rect, title?: string): void;
+    /** Split a rect into N columns by weights. */
+    columns(rect: Rect, weights: number[]): Rect[];
+    /** Scrollable list within rect: windows `items` to fit height, highlights the
+     *  cursor row (256-bg or reverse fallback, like browse). Returns adjusted
+     *  scroll so the cursor stays visible — the view stores it in state. */
+    list(rect: Rect, items: ListItemRow[], cursor: number, scroll: number): ListResult;
+}
+/** A live Draw plus the host-side serializer. */
+export interface DrawHandle {
+    draw: Draw;
+    /** Serialize the buffer to a full repaint frame (home + per-line clear + clear
+     *  below) — identical framing to browse's renderFrame. */
+    frame(): string;
+}
+/** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
+export declare function createDraw(size: Size, caps: ColorCaps): DrawHandle;

package/dist/core/tui/draw.js

@@ -0,0 +1,378 @@
+// draw.ts — the generic immediate-mode drawing surface shared by every crtr
+// raw-ANSI TUI (the `crtr view` host and `canvas browse`).
+//
+// The span/color primitives (Span, styleSpan, assemble, clip, ColorCaps,
+// detectColorCaps) are extracted verbatim-in-behavior from
+// canvas/browse/render.ts so there is ONE copy; browse imports them back.
+//
+// On top of those primitives this module adds the `Draw` factory: a line/cell
+// buffer covering the screen that a view fills via absolute-cell helpers
+// (spans/text/hline/box/columns/list). The host allocates one Draw per frame,
+// draws its chrome into it, hands the view a content Rect, then serializes the
+// buffer to a single repaint frame (`\x1b[H` + per-line `\x1b[K` + `\x1b[J`) —
+// exactly like browse's renderFrame does today.
+//
+// COLOR: hue (fg/bg) is gated on `caps.color`; structural SGR (bold/dim/reverse)
+// is always allowed. 256-color bg (the cursor-row highlight) additionally needs
+// `caps.color256`, falling back to reverse.
+// ── ANSI ────────────────────────────────────────────────────────────────────
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const REVERSE = `${ESC}7m`;
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+const ITALIC = `${ESC}3m`;
+// ── The recessive text ramp ────────────────────────────────────────────
+//
+// Two explicit greys for text that must sit BEHIND the primary content without
+// disappearing into it. Use these instead of the two things that look equivalent
+// and are not:
+//
+//   - basic-16 bright-black (`90`) resolves against the TERMINAL's palette, which
+//     a dark theme routinely sets within a hair of its own background;
+//   - SGR DIM (`2`) is a multiplier, so stacking it on an already-dark grey lands
+//     at mud — and stacking it on THESE would undo the contrast they encode.
+//
+// Never combine either with these. Ratios below are against the two planes a
+// raw-ANSI view can render on: a bare dark terminal and a themed popup card.
+export const META_FG = '38;5;246'; // 4.3–4.9:1 — metadata you actively scan
+export const RECESSIVE_FG = '38;5;243'; // 2.9–3.3:1 — deliberately behind, still read
+/** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
+ *  Guards styleSpan against a non-numeric value (a color name) producing a broken
+ *  escape sequence. */
+export function isSgrParams(v) {
+    return v.length > 0 && /^[0-9;]+$/.test(v);
+}
+/** Style one chunk of text. Hue (fg/bg) is gated on `color`; bold/dim/reverse
+ *  are not. After the styled text we return to `lineBase` (not a bare reset) so a
+ *  row-level background/dim persists across spans instead of bleeding or being
+ *  cleared. */
+export function styleSpan(text, style, color, lineBase) {
+    if (text === '')
+        return '';
+    let pre = '';
+    if (style?.dim)
+        pre += DIM;
+    if (style?.bold)
+        pre += BOLD;
+    if (style?.italic)
+        pre += ITALIC;
+    if (style?.reverse)
+        pre += REVERSE;
+    // fg is an SGR parameter string (e.g. '32' or '1;36'); bg is a 256-color index.
+    // Reject anything else so a bad value (e.g. a color NAME like 'green') degrades
+    // to no-color instead of emitting an invalid CSI that prints as literal garbage.
+    if (color && style?.fg && isSgrParams(style.fg))
+        pre += `${ESC}${style.fg}m`;
+    if (color && style?.bg && isSgrParams(style.bg))
+        pre += `${ESC}48;5;${style.bg}m`;
+    if (pre === '')
+        return text; // inherits lineBase / default
+    return `${pre}${text}${RESET}${lineBase}`;
+}
+/** Assemble styled spans into one line clipped to `width` visible cols. When
+ *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
+ *  background spans the full width. Always RESET-terminated so no color bleeds
+ *  into the next line. */
+export function assemble(spans, width, color, lineBase, fill) {
+    let used = 0;
+    let body = '';
+    for (const span of spans) {
+        if (used >= width)
+            break;
+        if (span.text === '')
+            continue;
+        let t = span.text;
+        const remaining = width - used;
+        let cut = false;
+        if (t.length > remaining) {
+            t = t.slice(0, Math.max(0, remaining - 1)) + '…';
+            cut = true;
+        }
+        body += styleSpan(t, span.style, color, lineBase);
+        used += t.length;
+        if (cut)
+            break;
+    }
+    if (fill && used < width)
+        body += ' '.repeat(width - used);
+    return lineBase === '' ? body : `${lineBase}${body}${RESET}`;
+}
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+export function clip(text, max) {
+    if (max <= 0)
+        return '';
+    return text.length <= max ? text : text.slice(0, Math.max(0, max - 1)) + '…';
+}
+/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
+ *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
+ *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
+export function detectColorCaps(stream = process.stdout, env = process.env) {
+    const term = env['TERM'] ?? '';
+    const color = stream.isTTY === true && !env['NO_COLOR'] && term !== 'dumb';
+    const colorTerm = env['COLORTERM'] ?? '';
+    const color256 = color && (/256|direct/i.test(term) || /truecolor|24bit/i.test(colorTerm));
+    return { color, color256 };
+}
+function mergeStyle(base, top) {
+    if (!top)
+        return base;
+    return {
+        fg: top.fg ?? base.fg,
+        bg: top.bg ?? base.bg,
+        bold: top.bold || base.bold,
+        dim: top.dim || base.dim,
+        italic: top.italic || base.italic,
+        reverse: top.reverse || base.reverse,
+    };
+}
+function sameStyle(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.fg === b.fg && a.bg === b.bg
+        && !!a.bold === !!b.bold && !!a.dim === !!b.dim && !!a.italic === !!b.italic && !!a.reverse === !!b.reverse;
+}
+/** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
+export function createDraw(size, caps) {
+    const cols = Math.max(1, size.cols);
+    const rows = Math.max(1, size.rows);
+    const grid = [];
+    for (let r = 0; r < rows; r++) {
+        const line = new Array(cols);
+        for (let c = 0; c < cols; c++)
+            line[c] = { ch: ' ', style: undefined };
+        grid.push(line);
+    }
+    /** Place spans starting at (row, col), clipped to `limit` visible cells; each
+     *  span's style optionally merged under `base` (the cursor-row highlight). */
+    const place = (row, col, spans, maxWidth, base) => {
+        if (row < 0 || row >= rows)
+            return;
+        const edge = cols - col;
+        const limit = Math.min(maxWidth ?? edge, edge);
+        if (limit <= 0)
+            return;
+        let x = col;
+        let drawn = 0;
+        for (const span of spans) {
+            if (drawn >= limit)
+                break;
+            const style = base ? mergeStyle(base, span.style) : span.style;
+            for (const ch of Array.from(span.text)) {
+                if (drawn >= limit)
+                    break;
+                if (x >= 0 && x < cols)
+                    grid[row][x] = { ch, style };
+                x++;
+                drawn++;
+            }
+        }
+    };
+    const fillStyle = (row, col, width, style) => {
+        if (row < 0 || row >= rows)
+            return;
+        const end = Math.min(cols, col + width);
+        for (let x = Math.max(0, col); x < end; x++)
+            grid[row][x] = { ch: ' ', style };
+    };
+    /** Visible (column) width of a span group — ANSI-free cell count. */
+    const spanWidth = (spans) => {
+        let n = 0;
+        for (const s of spans)
+            n += Array.from(s.text).length;
+        return n;
+    };
+    /** Flatten spans to per-cell {ch,style}, then re-group consecutive same-style
+     *  cells back into spans — used to left-clip a flush-right group. */
+    const regroup = (cells) => {
+        const out = [];
+        for (const c of cells) {
+            const last = out[out.length - 1];
+            if (last && sameStyle(last.style, c.style))
+                last.text += c.ch;
+            else
+                out.push({ text: c.ch, style: c.style });
+        }
+        return out;
+    };
+    /** Flush-right placement shared by draw.spansRight and the list right-group.
+     *  Lays `spans` so the group ends just before `rightCol` (exclusive); clips the
+     *  LEFT end with a leading `…` when the group exceeds the effective width.
+     *  `base` (the cursor-row highlight) merges under each cell, like `place`. */
+    const placeRight = (row, rightCol, spans, maxWidth, base) => {
+        if (row < 0 || row >= rows)
+            return;
+        const cap = Math.max(0, rightCol); // room available left of rightCol
+        const max = Math.min(maxWidth ?? cap, cap);
+        if (max <= 0)
+            return;
+        let cells = [];
+        for (const s of spans)
+            for (const ch of Array.from(s.text))
+                cells.push({ ch, style: s.style });
+        if (cells.length === 0)
+            return;
+        if (cells.length > max) {
+            const drop = cells.length - max + 1; // make room for the leading …
+            cells = cells.slice(drop);
+            cells.unshift({ ch: '…', style: cells[0]?.style });
+        }
+        const startCol = rightCol - cells.length;
+        place(row, startCol, regroup(cells), undefined, base);
+    };
+    const draw = {
+        size: { cols, rows },
+        caps,
+        spans(row, col, spans, maxWidth) {
+            place(row, col, spans, maxWidth);
+        },
+        spansRight(row, rightCol, spans, maxWidth) {
+            placeRight(row, rightCol, spans, maxWidth);
+        },
+        text(row, col, text, style) {
+            place(row, col, [{ text, style }], undefined);
+        },
+        hline(row, fromCol = 0, toCol = cols, ch = '─') {
+            if (row < 0 || row >= rows)
+                return;
+            const a = Math.max(0, Math.min(cols, fromCol));
+            const b = Math.max(0, Math.min(cols, toCol));
+            for (let x = a; x < b; x++)
+                grid[row][x] = { ch, style: { dim: true } };
+        },
+        vline(col, fromRow = 0, toRow = rows, ch = '│') {
+            if (col < 0 || col >= cols)
+                return;
+            const a = Math.max(0, Math.min(rows, fromRow));
+            const b = Math.max(0, Math.min(rows, toRow));
+            for (let r = a; r < b; r++)
+                grid[r][col] = { ch, style: { dim: true } };
+        },
+        box(rect, title) {
+            const { row, col, width, height } = rect;
+            if (width < 2 || height < 2)
+                return;
+            const bs = { dim: true };
+            const right = col + width - 1;
+            const bottom = row + height - 1;
+            const horiz = '─'.repeat(Math.max(0, width - 2));
+            place(row, col, [{ text: `┌${horiz}┐`, style: bs }], width);
+            place(bottom, col, [{ text: `└${horiz}┘`, style: bs }], width);
+            for (let r = row + 1; r < bottom; r++) {
+                place(r, col, [{ text: '│', style: bs }], 1);
+                place(r, right, [{ text: '│', style: bs }], 1);
+            }
+            if (title !== undefined && title !== '' && width > 4) {
+                place(row, col + 2, [{ text: ` ${title} ` }], width - 4);
+            }
+        },
+        columns(rect, weights) {
+            const n = weights.length;
+            if (n === 0)
+                return [];
+            const total = weights.reduce((a, b) => a + (b > 0 ? b : 0), 0) || 1;
+            const out = [];
+            let x = rect.col;
+            let used = 0;
+            for (let i = 0; i < n; i++) {
+                const isLast = i === n - 1;
+                const w = isLast
+                    ? Math.max(0, rect.width - used)
+                    : Math.max(0, Math.floor((rect.width * Math.max(0, weights[i])) / total));
+                out.push({ row: rect.row, col: x, width: w, height: rect.height });
+                x += w;
+                used += w;
+            }
+            return out;
+        },
+        list(rect, items, cursor, scroll) {
+            const height = Math.max(0, rect.height);
+            // An item may span several screen rows (its head plus any continuation
+            // lines), so scroll stays an ITEM index while windowing counts rows.
+            const rowsOf = (i) => 1 + (items[i]?.lines?.length ?? 0);
+            let sc = scroll;
+            if (sc < 0)
+                sc = 0;
+            if (sc > Math.max(0, items.length - 1))
+                sc = Math.max(0, items.length - 1);
+            if (height > 0) {
+                if (cursor < sc)
+                    sc = cursor;
+                // Scroll down until the cursor item's rows fit in the window (or it is
+                // the first item shown, in which case it is clipped rather than lost).
+                for (;;) {
+                    let used = 0;
+                    for (let i = sc; i <= cursor && i < items.length; i++)
+                        used += rowsOf(i);
+                    if (used <= height || sc >= cursor)
+                        break;
+                    sc++;
+                }
+            }
+            let rowIdx = rect.row;
+            const limit = rect.row + height;
+            for (let i = sc; i < items.length && rowIdx < limit; i++) {
+                const item = items[i];
+                const base = i === cursor
+                    ? (caps.color256 ? { bg: '236' } : { reverse: true })
+                    : undefined;
+                if (base)
+                    fillStyle(rowIdx, rect.col, rect.width, base);
+                if (item.right && item.right.length) {
+                    // Right-flush group (e.g. a timestamp); clip the left spans so they
+                    // never collide, and merge the cursor highlight over both.
+                    const rightWidth = spanWidth(item.right);
+                    const leftLimit = Math.max(0, rect.width - rightWidth - 1);
+                    place(rowIdx, rect.col, item.spans, leftLimit, base);
+                    placeRight(rowIdx, rect.col + rect.width, item.right, rightWidth, base);
+                }
+                else {
+                    place(rowIdx, rect.col, item.spans, rect.width, base);
+                }
+                rowIdx++;
+                for (const cont of item.lines ?? []) {
+                    if (rowIdx >= limit)
+                        break;
+                    if (base)
+                        fillStyle(rowIdx, rect.col, rect.width, base);
+                    place(rowIdx, rect.col, cont, rect.width, base);
+                    rowIdx++;
+                }
+            }
+            return { scroll: sc };
+        },
+    };
+    const serializeRow = (cells) => {
+        // Trim trailing plain blanks (clear-to-EOL covers them); keep styled tails
+        // (e.g. a cursor-row background fill) intact.
+        let last = -1;
+        for (let i = cells.length - 1; i >= 0; i--) {
+            const c = cells[i];
+            if (c.ch !== ' ' || c.style !== undefined) {
+                last = i;
+                break;
+            }
+        }
+        if (last < 0)
+            return '';
+        let out = '';
+        let i = 0;
+        while (i <= last) {
+            const style = cells[i].style;
+            let text = '';
+            while (i <= last && sameStyle(cells[i].style, style)) {
+                text += cells[i].ch;
+                i++;
+            }
+            out += styleSpan(text, style, caps.color, '');
+        }
+        return out;
+    };
+    const frame = () => {
+        const body = grid.map((cells) => `${serializeRow(cells)}${ESC}K`).join('\r\n');
+        return `${ESC}H${body}${ESC}J`;
+    };
+    return { draw, frame };
+}

package/dist/core/tui/fuzzy.d.ts

@@ -0,0 +1,9 @@
+/** Case-insensitive subsequence match: every char of `query` appears in `text`
+ *  in order (gaps allowed). Empty query matches everything. Substrings are a
+ *  subsequence, so this subsumes substring matching too. */
+export declare function fuzzyMatch(query: string, text: string): boolean;
+/** Indices in `text` consumed by a greedy left-to-right subsequence match of
+ *  `query` — the same walk as `fuzzyMatch`, but returning WHICH chars matched so
+ *  the renderer can highlight them. Empty set when `query` is empty OR does not
+ *  fully match (no partial highlights). */
+export declare function matchIndices(query: string, text: string): Set<number>;

package/dist/core/tui/fuzzy.js

@@ -0,0 +1,38 @@
+// Subsequence matching for TUI filters. One definition, shared by the canvas
+// browser and other fuzzy lists, so the two surfaces cannot drift apart.
+/** Case-insensitive subsequence match: every char of `query` appears in `text`
+ *  in order (gaps allowed). Empty query matches everything. Substrings are a
+ *  subsequence, so this subsumes substring matching too. */
+export function fuzzyMatch(query, text) {
+    if (query === '')
+        return true;
+    const q = query.toLowerCase();
+    const t = text.toLowerCase();
+    let qi = 0;
+    for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+        if (t[ti] === q[qi])
+            qi++;
+    }
+    return qi === q.length;
+}
+/** Indices in `text` consumed by a greedy left-to-right subsequence match of
+ *  `query` — the same walk as `fuzzyMatch`, but returning WHICH chars matched so
+ *  the renderer can highlight them. Empty set when `query` is empty OR does not
+ *  fully match (no partial highlights). */
+export function matchIndices(query, text) {
+    const out = new Set();
+    if (query === '')
+        return out;
+    const q = query.toLowerCase();
+    const t = text.toLowerCase();
+    let qi = 0;
+    for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+        if (t[ti] === q[qi]) {
+            out.add(ti);
+            qi++;
+        }
+    }
+    if (qi < q.length)
+        out.clear(); // no full match → no highlight
+    return out;
+}

package/dist/core/tui/markdown.d.ts

@@ -0,0 +1,17 @@
+import { type Span, type Style } from './draw.js';
+/** Parse inline markup left to right, recursing on delimited content with the
+ *  base style extended. Unclosed or implausible delimiters stay literal, which is
+ *  the right failure mode for a preview: never eat the user's text. */
+export declare function inlineSpans(src: string, base?: Style): Span[];
+/**
+ * Render `src` as markdown into at most `maxLines` span groups, each already
+ * wrapped to `width` visible columns.
+ *
+ * `spacing` inserts a blank line between blocks — true where the panel has room
+ * to breathe, false in a cramped one where every line counts. Consecutive list
+ * items never get one, so a tight list stays tight.
+ *
+ * `base` is the style every rendered run inherits (the caller's block style,
+ * e.g. the dim of a report body); markdown's own styles layer over it.
+ */
+export declare function renderMarkdownSpans(src: string, width: number, maxLines: number, spacing?: boolean, base?: Style): Span[][];