@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/core/canvas/browse/model.js

@@ -0,0 +1,258 @@
+// model.ts — pure, TTY-free logic for the canvas browser.
+//
+// Everything here is a pure function of its inputs (no db, no stdin, no ANSI) so
+// it is exhaustively unit-testable. The app layer (app.ts) wires the canvas data
+// access (dashboardRowsAll / listNodes / subscriptionsOf) into buildTree, then
+// drives flatten() on each keystroke.
+export const TABS = ['All', 'Live', 'Dormant', 'Flagged'];
+export const SORTS = ['tree', 'relevance', 'recency'];
+/** Does a node belong to this tab's slice?
+ *    All      — every node.
+ *    Live     — active | idle.
+ *    Dormant  — done | dead | canceled.
+ *    Flagged  — has > 0 pending human asks. */
+export function tabPredicate(tab, row) {
+    switch (tab) {
+        case 'All': return true;
+        case 'Live': return row.status === 'active' || row.status === 'idle';
+        case 'Dormant': return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+        case 'Flagged': return row.asks > 0;
+    }
+}
+/** Sort rank for roots/stragglers — live first (active, then idle), dormant
+ *  after. Mirrors render.ts / canvas-resume.ts statusRank. */
+export function statusRank(status) {
+    switch (status) {
+        case 'active': return 0;
+        case 'idle': return 1;
+        case 'done': return 2;
+        case 'canceled': return 3;
+        case 'dead': return 4;
+        default: return 5;
+    }
+}
+/**
+ * Build a spanning tree of the whole canvas.
+ *   - `rows`       — one DashboardRow per node (display text + status/asks).
+ *   - `rootIds`    — node ids whose `parent === null` (raw, unsorted).
+ *   - `childIdsOf` — a node's children = the nodes it subscribes to (its
+ *                    reports), in edge order. (= subscriptionsOf(id) node ids.)
+ *
+ * Roots are sorted live-first. The graph is walked DFS-preorder; the FIRST
+ * parent to reach a node owns it (cycle-/multi-parent-safe via `visited`). Any
+ * node never reached from a root (orphaned by a missing subscription edge) is
+ * appended as a depth-0 straggler so "All" is genuinely the whole canvas.
+ */
+export function buildTree(rows, rootIds, childIdsOf) {
+    const rowMap = new Map(rows.map((r) => [r.node_id, r]));
+    const nodes = new Map();
+    const orderedRoots = [];
+    const visited = new Set();
+    const rankOf = (id) => {
+        const r = rowMap.get(id);
+        return r !== undefined ? statusRank(r.status) : 99;
+    };
+    const walk = (id, depth, parentId) => {
+        if (visited.has(id))
+            return; // cycle, or already claimed by an earlier parent
+        const row = rowMap.get(id);
+        if (row === undefined)
+            return; // id in the graph but no row (missing meta)
+        visited.add(id);
+        const childIds = childIdsOf(id).filter((c) => rowMap.has(c) && !visited.has(c));
+        nodes.set(id, { row, depth, parentId, childIds });
+        for (const c of childIds)
+            walk(c, depth + 1, id);
+    };
+    const sortedRoots = [...rootIds].filter((id) => rowMap.has(id)).sort((a, b) => rankOf(a) - rankOf(b));
+    for (const r of sortedRoots) {
+        if (visited.has(r))
+            continue;
+        orderedRoots.push(r);
+        walk(r, 0, null);
+    }
+    // Stragglers: any row never reached from a declared root. Attach live-first as
+    // depth-0 pseudo-roots so the whole canvas stays reachable.
+    const stragglers = rows
+        .map((r) => r.node_id)
+        .filter((id) => !visited.has(id))
+        .sort((a, b) => rankOf(a) - rankOf(b));
+    for (const s of stragglers) {
+        if (visited.has(s))
+            continue;
+        orderedRoots.push(s);
+        walk(s, 0, null);
+    }
+    return { roots: orderedRoots, nodes };
+}
+// ---------------------------------------------------------------------------
+// Fuzzy match
+// ---------------------------------------------------------------------------
+/** 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;
+}
+function shortId(id) {
+    return id.slice(0, 8);
+}
+/** Does this row match the live query? Super-search spans name (which already
+ *  folds in the pi-generated description), kind, short-id, AND the spawn prompt
+ *  (`row.goal`). Empty query matches everything. */
+export function queryMatch(query, row) {
+    if (query === '')
+        return true;
+    return (fuzzyMatch(query, row.name) ||
+        fuzzyMatch(query, row.kind) ||
+        fuzzyMatch(query, shortId(row.node_id)) ||
+        (row.goal !== undefined && fuzzyMatch(query, row.goal)));
+}
+// ---------------------------------------------------------------------------
+// Relevance scoring (super-search)
+// ---------------------------------------------------------------------------
+/** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
+ *  exact > prefix > word-boundary substring > interior substring > subsequence.
+ *  An interior match decays slightly the later it starts so leading matches win. */
+export function fieldScore(query, text) {
+    if (query === '' || text === '')
+        return 0;
+    const q = query.toLowerCase();
+    const t = text.toLowerCase();
+    const idx = t.indexOf(q);
+    if (idx === 0)
+        return t.length === q.length ? 1 : 0.85; // exact | prefix
+    if (idx > 0) {
+        const prev = t[idx - 1] ?? '';
+        const boundary = /[\s_\-/.:]/.test(prev) ? 0.1 : 0; // word-boundary bonus
+        return 0.55 + boundary - Math.min(0.2, idx / 400); // interior, decays late
+    }
+    return fuzzyMatch(q, t) ? 0.2 : 0; // scattered subsequence
+}
+/** Per-field weights — name (handle + description) dominates, the spawn prompt
+ *  is the long-tail super-search field. */
+const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, goal: 1.5 };
+/** Weighted relevance of a row to the query across all searched fields. 0 means
+ *  no field matched (excluded from relevance results, same as `queryMatch`). */
+export function scoreRow(query, row) {
+    if (query === '')
+        return 0;
+    return (FIELD_WEIGHTS.name * fieldScore(query, row.name) +
+        FIELD_WEIGHTS.kind * fieldScore(query, row.kind) +
+        FIELD_WEIGHTS.id * fieldScore(query, shortId(row.node_id)) +
+        FIELD_WEIGHTS.goal * (row.goal !== undefined ? fieldScore(query, row.goal) : 0));
+}
+/** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
+export function cwdMatch(scope, row) {
+    return scope === null || scope === undefined || row.cwd === scope;
+}
+/**
+ * Flatten the tree to the ordered list of currently-visible rows.
+ *
+ * Inclusion: a node is shown when it directly matches (tab predicate AND query)
+ * — flagged `matched:true` — OR it is an ANCESTOR of a directly-matched node
+ * (shown for tree context, `matched:false`, dimmed by the renderer).
+ *
+ * Collapse: children are emitted only under an EXPANDED node. A node is expanded
+ * when it is not in `collapsed` — except under a non-empty query, where every
+ * ancestor-of-a-match is force-expanded regardless of `collapsed` so matches are
+ * always reachable.
+ */
+export function flatten(tree, opts) {
+    const { collapsed, tab, query, cwdScope, sort = 'tree' } = opts;
+    // 1. Directly-matched nodes: tab predicate AND cwd scope AND query.
+    const matched = new Set();
+    for (const [id, node] of tree.nodes) {
+        if (tabPredicate(tab, node.row) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row)) {
+            matched.add(id);
+        }
+    }
+    // FLAT ranked modes (relevance / recency): no tree, no ancestors — just the
+    // directly-matched rows in ranked order. Relevance falls back to recency when
+    // the query is empty (every score would be 0).
+    if (sort !== 'tree') {
+        const ids = [...matched];
+        const createdOf = (id) => tree.nodes.get(id)?.row.created ?? '';
+        const byRecency = (a, b) => createdOf(b).localeCompare(createdOf(a));
+        if (sort === 'recency' || query === '') {
+            ids.sort(byRecency);
+        }
+        else {
+            const score = new Map();
+            for (const id of ids)
+                score.set(id, scoreRow(query, tree.nodes.get(id).row));
+            ids.sort((a, b) => (score.get(b) - score.get(a)) || byRecency(a, b));
+        }
+        return ids.map((id) => ({ id, depth: 0, hasChildren: false, collapsed: false, matched: true }));
+    }
+    // 2. Ancestors of matches (for tree context + force-expand under query).
+    const ancestors = new Set();
+    for (const id of matched) {
+        let p = tree.nodes.get(id)?.parentId ?? null;
+        while (p !== null && !ancestors.has(p)) {
+            ancestors.add(p);
+            p = tree.nodes.get(p)?.parentId ?? null;
+        }
+    }
+    const included = (id) => matched.has(id) || ancestors.has(id);
+    const isExpanded = (id) => {
+        if (query !== '' && ancestors.has(id))
+            return true; // force-expand to reveal matches
+        return !collapsed.has(id);
+    };
+    // 3. Walk the tree in order, emitting included nodes and descending only into
+    //    expanded ones.
+    const out = [];
+    const walk = (id) => {
+        const node = tree.nodes.get(id);
+        if (node === undefined)
+            return;
+        if (included(id)) {
+            const hasChildren = node.childIds.length > 0;
+            out.push({
+                id,
+                depth: node.depth,
+                hasChildren,
+                collapsed: hasChildren && !isExpanded(id),
+                matched: matched.has(id),
+            });
+        }
+        if (isExpanded(id)) {
+            for (const c of node.childIds)
+                walk(c);
+        }
+    };
+    for (const r of tree.roots)
+        walk(r);
+    return out;
+}

package/dist/core/canvas/browse/render.d.ts

@@ -0,0 +1,41 @@
+import type { Tab, Tree, VisibleRow, SortMode } from './model.js';
+export declare const PREVIEW_BODY = 5;
+export declare const PREVIEW_HEIGHT: number;
+export declare function headerHeight(search: boolean): number;
+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;
+export interface RenderState {
+    tree: Tree;
+    visible: VisibleRow[];
+    tab: Tab;
+    cursor: number;
+    scrollOffset: number;
+    query: string;
+    search: boolean;
+    totalNodes: number;
+    /** Active cwd-scope filter; null = All dirs. Shown on the status line. */
+    cwdScope: string | null;
+    /** Active ordering — status line + (flat modes) row presentation. */
+    sort: SortMode;
+    /** Whether the bottom preview panel is drawn. */
+    preview: boolean;
+}
+/**
+ * Render the whole frame. Returns a single string that, written as-is, repaints
+ * the screen in place. `caps` gates all hue (defaults to a no-color frame so
+ * existing callers / non-TTY paths stay color-free).
+ */
+export declare function renderFrame(state: RenderState, size: {
+    cols: number;
+    rows: number;
+}, caps?: ColorCaps): string;

package/dist/core/canvas/browse/render.js

@@ -0,0 +1,387 @@
+// render.ts — pure frame rendering for the canvas browser.
+//
+// renderFrame(state, size, caps) → a full-screen string. The app writes it
+// verbatim on every keystroke. Redraw is flicker-free: home the cursor (\x1b[H),
+// clear each line to EOL (\x1b[K), and clear below the last line (\x1b[J) so a
+// shrunk frame leaves no stale rows. A full frame per keypress is fine for a
+// picker.
+//
+// COLOR is browse-only and *reinforces* the status glyphs (`● ○ ✓ ✗ ⊘`) which
+// stay the primary, color-free encoding (colorblind / light-bg / NO_COLOR safe).
+// Every hue (fg / bg color) is gated on `caps.color`; structural SGR (bold/dim/
+// reverse) is allowed always. See detectColorCaps() for the gate, and the
+// canvas-browse color spec for the rationale + palette.
+import { TABS, matchIndices } from './model.js';
+// Fixed chrome heights, shared with app.ts so its viewport math never drifts
+// from what renderFrame actually draws.
+//   header = title + tab bar + status line + separator (+ search input when searching)
+//   preview = separator + meta line + PREVIEW_BODY prompt lines
+export const PREVIEW_BODY = 5;
+export const PREVIEW_HEIGHT = PREVIEW_BODY + 2;
+export function headerHeight(search) {
+    return 4 + (search ? 1 : 0);
+}
+// ── ANSI ────────────────────────────────────────────────────────────────────
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const REVERSE = `${ESC}7m`;
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+const CURSOR_BG = `${ESC}48;5;236m`; // subtle dark-gray cursor-row bg (256-color)
+// Basic-16 ANSI fg codes used by the palette.
+const FG_GREEN = '32';
+const FG_YELLOW = '33';
+const FG_RED = '31';
+const FG_CYAN = '36';
+const FG_GRAY = '90'; // bright-black
+const FG_BRIGHT_YELLOW = '93';
+const FG_BRIGHT_CYAN = '96'; // query-match highlight (ties to the cyan search accent)
+const STATUS_GLYPH = {
+    active: '●',
+    idle: '○',
+    done: '✓',
+    dead: '✗',
+    canceled: '⊘',
+};
+/** The load-bearing color: glyph hue per status. Single source of truth, mirrors
+ *  STATUS_GLYPH. Reinforces the glyph everywhere it appears (rows + summary). */
+const STATUS_COLOR = {
+    active: FG_GREEN,
+    idle: FG_YELLOW,
+    done: FG_CYAN,
+    dead: FG_RED,
+    canceled: FG_GRAY,
+};
+/** 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 fmtCtx(tokens) {
+    if (tokens <= 0)
+        return '0k';
+    return `${Math.floor(tokens / 1000)}k`;
+}
+/** Tiered ctx-budget hue: dim under 50k, yellow 50–100k, red ≥100k. `undefined`
+ *  → dim (structural), so low budgets recede. */
+function ctxColorCode(tokens) {
+    if (tokens >= 100_000)
+        return FG_RED;
+    if (tokens >= 50_000)
+        return FG_YELLOW;
+    return undefined;
+}
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+function clip(text, max) {
+    if (max <= 0)
+        return '';
+    return text.length <= max ? text : text.slice(0, Math.max(0, max - 1)) + '…';
+}
+/** Compact relative age, e.g. `45s` `12m` `3h` `5d` `2w` `4mo`. Empty on a bad
+ *  timestamp. Drives the per-row recency cue + the preview meta line. */
+function relAge(created, now) {
+    const t = Date.parse(created);
+    if (Number.isNaN(t))
+        return '';
+    const s = Math.max(0, Math.floor((now - t) / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    const d = Math.floor(h / 24);
+    if (d < 7)
+        return `${d}d`;
+    const w = Math.floor(d / 7);
+    if (w < 5)
+        return `${w}w`;
+    return `${Math.floor(d / 30)}mo`;
+}
+/** Last path segment of a cwd — the project name shown as the All-dirs cue. */
+function baseDir(cwd) {
+    const parts = cwd.replace(/\/+$/, '').split('/');
+    return parts[parts.length - 1] || cwd;
+}
+/** Greedy word-wrap to `width` cols, capped at `maxLines` (last line clipped). */
+function wrap(text, width, maxLines) {
+    if (width <= 0 || maxLines <= 0)
+        return [];
+    const words = text.replace(/\s+/g, ' ').trim().split(' ');
+    const out = [];
+    let cur = '';
+    for (const w of words) {
+        const next = cur === '' ? w : `${cur} ${w}`;
+        if (next.length <= width) {
+            cur = next;
+            continue;
+        }
+        if (cur !== '')
+            out.push(cur);
+        cur = w;
+        if (out.length >= maxLines)
+            break;
+    }
+    if (out.length < maxLines && cur !== '')
+        out.push(cur);
+    return out.slice(0, maxLines).map((l) => clip(l, width));
+}
+/** Style one span. Hue is gated on `color`; bold/dim are not. After the span we
+ *  return to `lineBase` (not a bare reset) so a row-level background/dim persists
+ *  across the span instead of bleeding or being cleared. */
+function styleSpan(text, span, color, lineBase) {
+    if (text === '')
+        return '';
+    let pre = '';
+    if (span.dim)
+        pre += DIM;
+    if (span.bold)
+        pre += BOLD;
+    if (color && span.fg)
+        pre += `${ESC}${span.fg}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. */
+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, color, lineBase);
+        used += t.length;
+        if (cut)
+            break;
+    }
+    if (fill && used < width)
+        body += ' '.repeat(width - used);
+    return lineBase === '' ? body : `${lineBase}${body}${RESET}`;
+}
+/** Status tallies across the whole canvas, for the right-aligned header. Memoized
+ *  per tree — the snapshot is immutable for a browse session, so counting is done
+ *  once, not O(N) on every keystroke (the "massive canvas" target). */
+const summaryCache = new WeakMap();
+function statusCounts(tree) {
+    const cached = summaryCache.get(tree);
+    if (cached !== undefined)
+        return cached;
+    const counts = { active: 0, idle: 0, done: 0, dead: 0, canceled: 0 };
+    for (const node of tree.nodes.values())
+        counts[node.row.status]++;
+    const parts = [];
+    for (const s of ['active', 'idle', 'done', 'dead', 'canceled']) {
+        if (counts[s] > 0)
+            parts.push({ status: s, count: counts[s] });
+    }
+    summaryCache.set(tree, parts);
+    return parts;
+}
+function tabBar(active, color) {
+    return TABS.map((t) => {
+        if (t === active) {
+            // Keep the [ ] brackets in BOTH paths so the active tab reads without color.
+            return color ? `${BOLD}${ESC}${FG_CYAN}m[ ${t} ]${RESET}` : `${REVERSE}[ ${t} ]${RESET}`;
+        }
+        return color ? `${DIM}  ${t}  ${RESET}` : `  ${t}  `;
+    }).join('');
+}
+const EMPTY_HI = new Set();
+/** Name → spans, splitting out the query-matched chars (bold + bright-cyan) so
+ *  matches are scannable. Non-matched chars carry the row's name style (dim for
+ *  terminal status, bold on the cursor row). */
+function nameSpans(name, query, style) {
+    const hi = query === '' ? EMPTY_HI : matchIndices(query, name);
+    if (hi.size === 0)
+        return [{ text: name, dim: style.dim, bold: style.bold }];
+    const out = [];
+    let buf = '';
+    let bufHi = false;
+    const flush = () => {
+        if (buf === '')
+            return;
+        if (bufHi)
+            out.push({ text: buf, fg: FG_BRIGHT_CYAN, bold: true });
+        else
+            out.push({ text: buf, dim: style.dim, bold: style.bold });
+        buf = '';
+    };
+    for (let i = 0; i < name.length; i++) {
+        const h = hi.has(i);
+        if (h !== bufHi) {
+            flush();
+            bufHi = h;
+        }
+        buf += name[i];
+    }
+    flush();
+    return out;
+}
+/** One row line: `<indent><collapse> <glyph> <name> [kind/mode] ctx Nk age [~dir] [⚑n]`.
+ *  `showCwd` adds the project-name cue (All-dirs view); `now` drives the age. */
+function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
+    const node = tree.nodes.get(row.id);
+    if (node === undefined)
+        return '';
+    const r = node.row;
+    const indent = '  '.repeat(row.depth);
+    const collapse = !row.hasChildren ? ' ' : row.collapsed ? '▸' : '▾';
+    const glyph = STATUS_GLYPH[r.status] ?? '?';
+    const terminal = r.status === 'done' || r.status === 'dead' || r.status === 'canceled';
+    const ctxStr = fmtCtx(r.ctx_tokens);
+    const ctxFg = ctxColorCode(r.ctx_tokens);
+    const age = relAge(r.created, now);
+    // Name: bold on the cursor row; dim for terminal status (live names stay default).
+    const nameStyle = { dim: !isCursor && terminal, bold: isCursor };
+    const spans = [
+        { text: `${indent}${collapse} ` },
+        { text: glyph, fg: STATUS_COLOR[r.status] }, // load-bearing status hue
+        { text: ' ' },
+        ...nameSpans(r.name, query, nameStyle),
+        { text: ` [${r.kind}/${r.mode}]`, fg: FG_GRAY }, // recedes
+        { text: ' ctx ', dim: true },
+        { text: ctxStr, fg: ctxFg, dim: ctxFg === undefined }, // tiered budget cue
+    ];
+    if (age !== '')
+        spans.push({ text: ` ${age}`, dim: true }); // recency cue
+    if (showCwd)
+        spans.push({ text: ` ~${baseDir(r.cwd)}`, fg: FG_GRAY }); // project cue (All dirs)
+    if (r.asks > 0)
+        spans.push({ text: ` ⚑${r.asks}`, fg: FG_BRIGHT_YELLOW, bold: true }); // attention
+    // Row base: cursor → subtle bg (256) or reverse fallback (also covers !color);
+    // non-matched ancestor → whole-row dim for tree context (keep prior behavior).
+    let lineBase = '';
+    let fill = false;
+    if (isCursor) {
+        lineBase = caps.color256 ? CURSOR_BG : REVERSE;
+        fill = true;
+    }
+    else if (!row.matched) {
+        lineBase = DIM;
+    }
+    return assemble(spans, width, caps.color, lineBase, fill);
+}
+/** The status line (always present): active cwd scope · sort mode · committed
+ *  filter. The committed-filter indicator lives here now (not its own line) so a
+ *  filtered view always advertises its query without consuming a header row. */
+function statusLine(state) {
+    const dim = (s) => `${DIM}${s}${RESET}`;
+    const scope = state.cwdScope === null ? 'all dirs' : baseDir(state.cwdScope);
+    const segs = [`${dim('scope')} ${scope}`, `${dim('sort')} ${state.sort}`];
+    if (!state.search && state.query !== '')
+        segs.push(`${dim('filter')} ${state.query}`);
+    return segs.join(dim('  ·  '));
+}
+/** The bottom preview panel — exactly PREVIEW_HEIGHT lines: a separator, a meta
+ *  line (status · kind/mode · project · age · ctx · asks), then the selected
+ *  node's spawn prompt wrapped to PREVIEW_BODY lines. The "which one was this?"
+ *  answer — paired with super-search. Always full height so viewport math holds. */
+function previewPanel(r, width, caps, now) {
+    const out = [`${DIM}${'─'.repeat(width)}${RESET}`];
+    if (r === undefined) {
+        while (out.length < PREVIEW_HEIGHT)
+            out.push('');
+        return out;
+    }
+    const glyph = caps.color
+        ? `${ESC}${STATUS_COLOR[r.status]}m${STATUS_GLYPH[r.status]}${RESET}`
+        : (STATUS_GLYPH[r.status] ?? '?');
+    const metaPieces = [`${r.status} ${r.kind}/${r.mode}`, baseDir(r.cwd), relAge(r.created, now), `ctx ${fmtCtx(r.ctx_tokens)}`];
+    if (r.asks > 0)
+        metaPieces.push(`⚑${r.asks}`);
+    const metaText = clip(metaPieces.filter((p) => p !== '').join('  ·  '), Math.max(0, width - 2));
+    out.push(caps.color ? `${glyph} ${DIM}${metaText}${RESET}` : `${glyph} ${metaText}`);
+    const goalText = (r.goal ?? '').trim();
+    const body = goalText === '' ? [`${DIM}(no spawn prompt)${RESET}`] : wrap(goalText, width, PREVIEW_BODY);
+    for (let i = 0; i < PREVIEW_BODY; i++)
+        out.push(body[i] ?? '');
+    return out;
+}
+/**
+ * Render the whole frame. Returns a single string that, written as-is, repaints
+ * the screen in place. `caps` gates all hue (defaults to a no-color frame so
+ * existing callers / non-TTY paths stay color-free).
+ */
+export function renderFrame(state, size, caps = { color: false, color256: false }) {
+    const cols = Math.max(20, size.cols);
+    const rows = Math.max(8, size.rows);
+    const width = cols - 1; // leave the last column for \x1b[K
+    const now = Date.now();
+    const lines = [];
+    // line 1 — title + right-aligned status summary (each glyph in its status hue).
+    const title = `${BOLD}Canvas${RESET} — ${state.totalNodes} nodes`;
+    const titlePlainLen = `Canvas — ${state.totalNodes} nodes`.length;
+    const parts = statusCounts(state.tree);
+    const summaryPlain = parts.map((p) => `${STATUS_GLYPH[p.status]}${p.count}`).join(' ');
+    const summaryColored = caps.color
+        ? parts.map((p) => `${ESC}${STATUS_COLOR[p.status]}m${STATUS_GLYPH[p.status]}${RESET}${DIM}${p.count}${RESET}`).join(' ')
+        : `${DIM}${summaryPlain}${RESET}`;
+    const gap = width - titlePlainLen - summaryPlain.length;
+    lines.push(gap > 1 ? `${title}${' '.repeat(gap)}${summaryColored}` : title);
+    // line 2 — tab bar.
+    lines.push(tabBar(state.tab, caps.color));
+    // line 3 — status line (scope · sort · filter).
+    lines.push(statusLine(state));
+    // line 4 — search input, only while actively typing a search.
+    if (state.search) {
+        const slash = caps.color ? `${ESC}${FG_CYAN}m/${RESET}` : '/';
+        lines.push(`${slash} ${state.query}▎`);
+    }
+    // separator.
+    lines.push(`${DIM}${'─'.repeat(width)}${RESET}`);
+    // body — windowed visible rows, leaving room for the (optional) preview panel.
+    const head = lines.length; // === headerHeight(state.search)
+    const showCwd = state.cwdScope === null; // project cue only matters across dirs
+    const previewOn = state.preview && state.visible.length > 0;
+    const previewH = previewOn ? PREVIEW_HEIGHT : 0;
+    const viewport = Math.max(1, rows - head - 1 /* footer */ - previewH);
+    const start = state.scrollOffset;
+    const end = Math.min(state.visible.length, start + viewport);
+    if (state.visible.length === 0) {
+        lines.push(`${DIM}  (no nodes match this view)${RESET}`);
+        for (let i = 1; i < viewport; i++)
+            lines.push('');
+    }
+    else {
+        for (let i = start; i < end; i++) {
+            lines.push(rowLine(state.visible[i], state.tree, width, i === state.cursor, state.query, caps, showCwd, now));
+        }
+        for (let i = end - start; i < viewport; i++)
+            lines.push('');
+    }
+    // preview panel — the selected row's prompt + meta.
+    if (previewOn) {
+        const sel = state.visible[state.cursor];
+        const r = sel !== undefined ? state.tree.nodes.get(sel.id)?.row : undefined;
+        for (const l of previewPanel(r, width, caps, now))
+            lines.push(l);
+    }
+    // footer.
+    const footer = state.search
+        ? '⏎ commit  Esc cancel  ⌫ delete'
+        : '↑↓ move  →/← tree  ⏎ resume  Tab tabs  / search  s sort  c cwd  p preview  q quit';
+    lines.push(`${DIM}${clip(footer, width)}${RESET}`);
+    // Assemble: home, each line cleared to EOL, then clear below.
+    const body = lines.map((l) => `${l}${ESC}K`).join('\r\n');
+    return `${ESC}H${body}${ESC}J`;
+}