@north-light/crouter 0.3.154

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

@@ -0,0 +1,550 @@
+// 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 { STATUS_GLYPH, STATUS_COLOR, resolveNodeVisual, faultSummary } from '../status-glyph.js';
+import { TABS, matchIndices, promptText, previewSnippet } from './model.js';
+// Span/color primitives live in core/tui/draw.ts (one copy, shared with the
+// `crtr view` host). Re-export the color caps so browse's importers + tests keep
+// resolving them from this module.
+import { clip, assemble, detectColorCaps } from '../../tui/draw.js';
+export { detectColorCaps };
+// 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 + PROMPT_LINES (spawn/match) + REPLY_LINES (last reply)
+export const PROMPT_LINES = 3;
+export const REPLY_LINES = 3;
+export const PREVIEW_BODY = PROMPT_LINES + REPLY_LINES;
+export const PREVIEW_HEIGHT = PREVIEW_BODY + 2;
+//   header = title + tab bar + status line + column header + separator (+ input line)
+// `inputLine` is true whenever a text-input mode is open (search / rename / message)
+// — each adds one prompt row above the column header.
+export function headerHeight(inputLine) {
+    return 5 + (inputLine ? 1 : 0);
+}
+// ── Row table layout ──────────────────────────────────────────────────────────
+// A row is three zones: a fixed-width STATUS rail (glyph + word) on the left, the
+// flexible tree-indented NAME in the middle, and a flush-right METADATA cluster
+// (kind/mode · ctx · age · project) whose fixed-width segments align into clean
+// vertical columns down the right edge. Wide terminals widen the name; narrow ones
+// clip the name (and drop the cluster) first. The status WORD — not a lone glyph —
+// is the legible, NO_COLOR-safe state signal.
+const STATUS_W = 10; // glyph + ' ' + longest word ('active'/'cancel') + trailing gap
+const KM_W = 22; // kind/mode column
+const CTX_W = 6; // ctx tokens column
+const AGE_W = 5; // age column
+const PROJ_W = 16; // project (~basename) column, only across All dirs
+const COL_GAP = '  ';
+// ── 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_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 FG_MAGENTA = '35'; // pin star (distinct from the yellow ⚑ asks flag)
+// STATUS_GLYPH + STATUS_COLOR are imported from ../status-glyph.js (the shared
+// canvas-graph map). STATUS_COLOR there is NUMERIC SGR (e.g. 32) — wrap with
+// `sgr()` where a string ANSI code is needed (Span fg / template literals accept
+// the number directly).
+const FG = (code) => String(code);
+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;
+}
+/** 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;
+}
+// ── Styled spans ──────────────────────────────────────────────────────────────
+//
+// A row is built from styled spans, then assembled to a width-clipped line. This
+// lets each cell carry its own hue (status glyph, ctx tier, asks, match highlight)
+// while clipping by VISIBLE width — ANSI bytes don't count toward the column
+// budget. `fg` is hue (gated on `color`); `bold`/`dim` are structural (always).
+// Span / styleSpan / assemble now live in core/tui/draw.ts (imported above).
+/** 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, style: { dim: style.dim, bold: style.bold } }];
+    const out = [];
+    let buf = '';
+    let bufHi = false;
+    const flush = () => {
+        if (buf === '')
+            return;
+        if (bufHi)
+            out.push({ text: buf, style: { fg: FG_BRIGHT_CYAN, bold: true } });
+        else
+            out.push({ text: buf, style: { 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;
+}
+/** Visible (cell) width of a span group — ANSI-free, surrogate-safe. */
+function spansWidth(spans) {
+    let n = 0;
+    for (const s of spans)
+        n += [...s.text].length;
+    return n;
+}
+/** The status rail: a status WORD next to its glyph, both in the status hue, padded
+ *  to STATUS_W so the rail forms a clean left column. `live` (bright green) when the
+ *  node is genuinely mid-turn; otherwise the lifecycle word. The word is what makes
+ *  state legible at a glance and survives NO_COLOR (the glyph is the second cue). */
+function statusRail(r) {
+    const v = resolveNodeVisual(r.status, { streaming: r.streaming === true, hanging: r.hanging ?? null });
+    // Plain status keeps browse's own status WORD; overlays (hanging/⟳)
+    // carry their own word from resolveNodeVisual. A hanging kind label can exceed
+    // STATUS_W — acceptable: the rare, attention-demanding row gets a slightly
+    // wider rail (Math.max(1,…) keeps a gap), which draws the eye.
+    const word = v.word ?? ({ active: 'active', idle: 'idle', done: 'done', dead: 'dead', canceled: 'cancel' }[r.status] ?? r.status);
+    const fg = FG(v.color);
+    const text = `${v.glyph} ${word}`;
+    const pad = Math.max(1, STATUS_W - [...text].length);
+    return [
+        { text, style: { fg, bold: v.bold === true } },
+        { text: ' '.repeat(pad) },
+    ];
+}
+/** The flush-right metadata cluster as fixed-width segments, so kind/mode · ctx ·
+ *  age · project align into vertical columns down the right edge. `showCwd` adds the
+ *  project column (only meaningful across All dirs). */
+function metaCluster(r, now, showCwd) {
+    const ctxFg = ctxColorCode(r.ctx_tokens);
+    const out = [
+        { text: clipPad(`${r.kind}/${r.mode}`, KM_W), style: { fg: FG_GRAY } },
+        { text: COL_GAP },
+        { text: fmtCtx(r.ctx_tokens).padStart(CTX_W), style: { fg: ctxFg, dim: ctxFg === undefined } },
+        { text: COL_GAP },
+        { text: relAge(r.created, now).padStart(AGE_W), style: { dim: true } },
+    ];
+    if (showCwd) {
+        out.push({ text: COL_GAP }, { text: clipPad(`~${baseDir(r.cwd)}`, PROJ_W), style: { fg: FG_GRAY } });
+    }
+    return out;
+}
+/** Left-clip-pad: clip `s` to `w` cells then pad-end with spaces to exactly `w`. */
+function clipPad(s, w) {
+    return clip(s, w).padEnd(w);
+}
+/** Compose a row from a flexible LEFT zone and a fixed flush-right RIGHT cluster:
+ *  pad fills the gap so RIGHT hugs the edge; when the terminal is too narrow the
+ *  cluster is dropped rather than colliding with the name. The caller has already
+ *  clipped the name to fit. */
+function assembleRow(left, right, width, color, lineBase, fill) {
+    const leftW = spansWidth(left);
+    const rightW = spansWidth(right);
+    if (right.length === 0 || leftW + rightW + 1 > width) {
+        return assemble(left, width, color, lineBase, fill);
+    }
+    const pad = width - leftW - rightW;
+    return assemble([...left, { text: ' '.repeat(pad) }, ...right], width, color, lineBase, fill);
+}
+/** One table row: `<status rail>  <indent><collapse> <name> <flags>` ........ `<meta>`.
+ *  `showCwd` adds the project column (All-dirs view); `now` drives the age. */
+function rowLine(row, tree, width, isCursor, query, caps, showCwd, now, isPinned) {
+    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 terminal = r.status === 'done' || r.status === 'dead' || r.status === 'canceled';
+    // Left gutter (fixed slot): an eye when a viewer is ATTACHED — a scannable rail
+    // down the left edge of "what's on a screen right now". Blank otherwise.
+    const gutter = r.viewed === true
+        ? { text: '\uf06e ', style: { fg: FG_BRIGHT_CYAN, bold: true } }
+        : { text: '  ' };
+    // Inline attention flag that travels with the name (fault summary lives in the rail,
+    // attached lives in the gutter).
+    const flags = [];
+    if (r.asks > 0)
+        flags.push({ text: ` ⚑${r.asks}`, style: { fg: FG_BRIGHT_YELLOW, bold: true } }); // pending asks
+    // Hanging: the fault summary travels with the name (the ⚠ + kind
+    // label live in the rail). Dim yellow so it reads as secondary detail.
+    if (r.hanging != null)
+        flags.push({ text: ` · ${faultSummary(r.hanging, now)}`, style: { fg: FG_YELLOW, dim: true } });
+    // Pin marker travels just before the name so a starred node is scannable in any
+    // tab/sort. Magenta keeps it distinct from the yellow ⚑ asks flag.
+    const pinMark = isPinned ? [{ text: '★ ', style: { fg: FG_MAGENTA, bold: true } }] : [];
+    const status = statusRail(r);
+    const right = metaCluster(r, now, showCwd);
+    const treeLead = `${indent}${collapse} `;
+    // Clip the NAME (only) so gutter + status + tree + pin + name + flags + meta all
+    // fit; the cluster is dropped first (assembleRow) when even a 4-col name won't fit.
+    const fixed = spansWidth([gutter]) + spansWidth(status) + [...treeLead].length + spansWidth(pinMark) + spansWidth(flags);
+    const rightW = spansWidth(right);
+    const nameMax = Math.max(4, width - fixed - rightW - 1);
+    const nameStyle = { dim: !isCursor && terminal, bold: isCursor }; // dim terminal names; bold the cursor row
+    const left = [
+        gutter,
+        ...status,
+        { text: treeLead, style: { dim: true } },
+        ...pinMark,
+        ...nameSpans(clip(r.name, nameMax), query, nameStyle),
+        ...flags,
+    ];
+    // Row base: cursor → subtle bg (256) or reverse fallback (also !color); non-matched
+    // ancestor → whole-row dim for tree context.
+    let lineBase = '';
+    let fill = false;
+    if (isCursor) {
+        lineBase = caps.color256 ? CURSOR_BG : REVERSE;
+        fill = true;
+    }
+    else if (!row.matched) {
+        lineBase = DIM;
+    }
+    return assembleRow(left, right, width, caps.color, lineBase, fill);
+}
+/** The column-header row — dim labels aligned to the same zones the rows use, so
+ *  the metadata columns read as a table. */
+function columnHeaderLine(width, showCwd, caps) {
+    const left = [
+        { text: '  ' }, // viewer gutter (no label)
+        { text: 'STATUS'.padEnd(STATUS_W), style: { dim: true, bold: true } },
+        { text: 'NAME', style: { dim: true, bold: true } },
+    ];
+    const right = [
+        { text: 'KIND/MODE'.padEnd(KM_W), style: { dim: true, bold: true } },
+        { text: COL_GAP },
+        { text: 'CTX'.padStart(CTX_W), style: { dim: true, bold: true } },
+        { text: COL_GAP },
+        { text: 'AGE'.padStart(AGE_W), style: { dim: true, bold: true } },
+    ];
+    if (showCwd)
+        right.push({ text: COL_GAP }, { text: 'PROJECT'.padEnd(PROJ_W), style: { dim: true, bold: true } });
+    return assembleRow(left, right, width, caps.color, '', false);
+}
+/** The status line (always present): active profile/cwd scopes · 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 profile = state.profileScope === undefined ? 'all profiles' : 'current';
+    const scope = state.cwdScope === null ? 'all dirs' : baseDir(state.cwdScope);
+    const segs = [`${dim('profile')} ${profile}`, `${dim('scope')} ${scope}`, `${dim('sort')} ${state.sort}`];
+    if (state.residentsOnly)
+        segs.push(`${dim('show')} residents`);
+    if (!state.search && state.query !== '')
+        segs.push(`${dim('filter')} ${state.query}`);
+    return segs.join(dim('  ·  '));
+}
+/** One snippet line → a rendered string with the query-matched columns in bold
+ *  bright-cyan (mirrors the row name highlight). Unmatched text stays default. */
+function snippetLine(ln, width, caps) {
+    if (ln.hi.size === 0)
+        return assemble([{ text: ln.text }], width, caps.color, '', false);
+    const spans = [];
+    let buf = '';
+    let bufHi = false;
+    const flush = () => {
+        if (buf === '')
+            return;
+        spans.push(bufHi ? { text: buf, style: { fg: FG_BRIGHT_CYAN, bold: true } } : { text: buf });
+        buf = '';
+    };
+    for (let i = 0; i < ln.text.length; i++) {
+        const h = ln.hi.has(i);
+        if (h !== bufHi) {
+            flush();
+            bufHi = h;
+        }
+        buf += ln.text[i];
+    }
+    flush();
+    return assemble(spans, width, caps.color, '', false);
+}
+/** The bottom preview panel — exactly PREVIEW_HEIGHT lines: a separator, a meta
+ *  line (status · kind/mode · project · age · ctx · asks · fault/viewing), then
+ *  TWO blocks — the spawn prompt / query-match (PROMPT_LINES) and the node's LAST
+ *  assistant reply (REPLY_LINES, prefixed `↩`). Under a live query the prompt block
+ *  is WINDOWED to the matching prompt (anywhere in the conversation) with the match
+ *  highlighted; with no query it shows the spawn prompt from the start. Seeing both
+ *  ends — what it was asked and where it left off — answers "which one was this?".
+ *  Always full height so viewport math holds. */
+function previewPanel(r, width, caps, now, query) {
+    const out = [`${DIM}${'─'.repeat(width)}${RESET}`];
+    if (r === undefined) {
+        while (out.length < PREVIEW_HEIGHT)
+            out.push('');
+        return out;
+    }
+    const v = resolveNodeVisual(r.status, { streaming: r.streaming === true, hanging: r.hanging ?? null });
+    const glyph = caps.color
+        ? `${ESC}${v.color}m${v.glyph}${RESET}`
+        : v.glyph;
+    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}`);
+    if (r.hanging != null)
+        metaPieces.push(faultSummary(r.hanging, now));
+    if (r.streaming === true)
+        metaPieces.push('⟳');
+    if (r.viewed === true)
+        metaPieces.push('\uf06e viewing');
+    const metaText = clip(metaPieces.filter((p) => p !== '').join('  ·  '), Math.max(0, width - 2));
+    out.push(caps.color ? `${glyph} ${DIM}${metaText}${RESET}` : `${glyph} ${metaText}`);
+    // Block 1 — spawn prompt / query-match. With a query, window+highlight the
+    // matching prompt from the WHOLE conversation; otherwise the spawn prompt.
+    const sourceText = query !== '' ? promptText(r) : (r.goal ?? '');
+    const promptSnippet = previewSnippet(query, sourceText, width, PROMPT_LINES);
+    if (promptSnippet.length === 0) {
+        out.push(`${DIM}(no spawn prompt)${RESET}`);
+        for (let i = 1; i < PROMPT_LINES; i++)
+            out.push('');
+    }
+    else {
+        for (let i = 0; i < PROMPT_LINES; i++) {
+            const ln = promptSnippet[i];
+            out.push(ln === undefined ? '' : snippetLine(ln, width, caps));
+        }
+    }
+    // Block 2 — the node's LAST assistant reply, prefixed `↩` on its first line so
+    // the two blocks read apart. Wrapped to width-2 to leave room for the marker.
+    const replyMark = caps.color ? `${DIM}↩ ${RESET}` : '↩ ';
+    const replySnippet = previewSnippet('', r.lastAssistant ?? '', Math.max(1, width - 2), REPLY_LINES);
+    if (replySnippet.length === 0) {
+        out.push(`${replyMark}${DIM}(no reply yet)${RESET}`);
+        for (let i = 1; i < REPLY_LINES; i++)
+            out.push('');
+    }
+    else {
+        for (let i = 0; i < REPLY_LINES; i++) {
+            const ln = replySnippet[i];
+            const prefix = i === 0 ? replyMark : '  ';
+            out.push(ln === undefined ? (i === 0 ? `${replyMark}` : '') : `${prefix}${snippetLine(ln, Math.max(1, width - 2), caps)}`);
+        }
+    }
+    return out;
+}
+/** The keybinding help overlay — a full-screen cheatsheet that replaces the body
+ *  while `?` is held open. Grouped by intent so the whole key surface is legible in
+ *  one glance (the footer only ever advertises the common few). */
+const HELP_ROWS = [
+    ['Move', '↑/↓  j/k', 'up / down'],
+    ['', 'g / G', 'top / bottom'],
+    ['', '.', 'jump to this node (recenter)'],
+    ['Tree', '→/←  h/l', 'expand / collapse'],
+    ['', 'space', 'toggle fold'],
+    ['Tabs', 'Tab / 1-5', 'All · Live · Dormant · Attention · Pinned'],
+    ['Find', '/', 'fuzzy search (name · kind · id · prompts)'],
+    ['Pin', 'f', 'star / unstar — floats to top, Pinned tab'],
+    ['Open', '⏎  o', 'resume the node (closes navigator)'],
+    ['', 'O', 'resume, keep browsing (open in background)'],
+    ['Act', 'm', 'message the node (no resume)'],
+    ['', 'R', 'rename the node'],
+    ['', 'x', 'close-out node + subtree'],
+    ['', 'K', 'revive now (a hanging node)'],
+    ['View', 's', 'cycle sort (attention/tree/relevance/recency)'],
+    ['', 'c', 'toggle cwd scope'],
+    ['', 'P', 'toggle profile scope'],
+    ['', 'r', 'toggle residents-only'],
+    ['', 'p', 'toggle preview panel'],
+    ['Quit', 'q / Esc', ''],
+];
+function renderHelp(size, caps) {
+    const cols = Math.max(20, size.cols);
+    const rows = Math.max(8, size.rows);
+    const width = cols - 1;
+    const lines = [];
+    lines.push(`${BOLD}Canvas navigator — keys${RESET}`);
+    lines.push('');
+    const dim = (s) => `${DIM}${s}${RESET}`;
+    for (const [group, keys, desc] of HELP_ROWS) {
+        const g = group.padEnd(6);
+        const k = keys.padEnd(12);
+        const line = `  ${dim(g)}${BOLD}${k}${RESET}${desc === '' ? '' : `  ${dim(desc)}`}`;
+        lines.push(clip(line, width));
+    }
+    lines.push('');
+    lines.push(dim('  ? or any key to close'));
+    while (lines.length < rows - 1)
+        lines.push('');
+    const body = lines.map((l) => `${l}${ESC}K`).join('\r\n');
+    return `${ESC}H${body}${ESC}J`;
+}
+/**
+ * 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 }) {
+    if (state.help === true)
+        return renderHelp(size, caps);
+    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 inputMode = state.search || state.rename === true || state.message === true;
+    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 — the text-input prompt, only while a search / rename / message is open.
+    if (inputMode) {
+        const prefix = state.rename === true ? 'rename ▸' : state.message === true ? 'msg ▸' : '/';
+        const buf = state.rename === true ? (state.renameBuf ?? '') : state.message === true ? (state.messageBuf ?? '') : state.query;
+        const p = caps.color ? `${ESC}${FG_CYAN}m${prefix}${RESET}` : prefix;
+        lines.push(`${p} ${buf}▎`);
+    }
+    // column header (table labels) + separator.
+    const showCwd = state.cwdScope === null; // project column only matters across dirs
+    lines.push(columnHeaderLine(width, showCwd, caps));
+    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 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++) {
+            const vr = state.visible[i];
+            lines.push(rowLine(vr, state.tree, width, i === state.cursor, state.query, caps, showCwd, now, state.pinned.has(vr.id)));
+        }
+        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, state.query))
+            lines.push(l);
+    }
+    // footer — the y/n close-out confirm takes over when pending; else search / nav.
+    if (state.pendingClose !== null && state.pendingClose !== undefined) {
+        const node = state.tree.nodes.get(state.pendingClose);
+        const who = node !== undefined ? node.row.name : state.pendingClose;
+        const warn = `⚠ ${who} is ⟳ — close it (and its subtree) anyway?  y / n`;
+        lines.push(caps.color ? `${BOLD}${ESC}${FG_BRIGHT_YELLOW}m${clip(warn, width)}${RESET}` : `${REVERSE}${clip(warn, width)}${RESET}`);
+    }
+    else {
+        // When the cursor row has an active fault, lead the footer with the on-demand kick
+        // hint (K shells `node lifecycle revive <id> --now` — immediate revive instead of
+        // waiting for the daemon's retry schedule).
+        const selRow = state.visible[state.cursor];
+        const cursorRow = selRow !== undefined ? state.tree.nodes.get(selRow.id)?.row : undefined;
+        const hangingHint = cursorRow?.hanging != null ? 'K revive now  ' : '';
+        const footer = inputMode
+            ? '⏎ commit  Esc cancel  ⌫ delete'
+            : state.readOnly === true
+                ? '↑↓ move  →/← tree  / search  f pin  Tab tabs  ? more  q quit  — read-only remote canvas'
+                : `${hangingHint}↑↓ move  ⏎ resume  O bg  / search  f pin  m msg  x close  R rename  ? more  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`;
+}