@crouton-kit/crouter 0.3.68 → 0.3.78

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

@@ -108,20 +108,38 @@ test('pruneNode: absent id is a no-op', () => {
     assert.equal(t.nodes.size, before);
 });
 // ── tab predicates ───────────────────────────────────────────────────────────
-test('tabPredicate: All / Live / Dormant / Flagged', () => {
-    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Flagged']);
+test('tabPredicate: All / Live / Dormant / Attention / Pinned', () => {
+    assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Attention', 'Pinned']);
     const active = ROWS[0]; // root1 active
     const idle = ROWS[1]; // child-a idle
     const done = ROWS[2]; // grand-x done
-    const flagged = ROWS[3]; // child-b active asks 2
+    const attention = ROWS[3]; // child-b active asks 2
     assert.equal(tabPredicate('All', done), true);
     assert.equal(tabPredicate('Live', active), true);
     assert.equal(tabPredicate('Live', idle), true);
     assert.equal(tabPredicate('Live', done), false);
     assert.equal(tabPredicate('Dormant', done), true);
     assert.equal(tabPredicate('Dormant', active), false);
-    assert.equal(tabPredicate('Flagged', flagged), true);
-    assert.equal(tabPredicate('Flagged', active), false);
+    // Attention = pending asks OR a fault.
+    assert.equal(tabPredicate('Attention', attention), true);
+    assert.equal(tabPredicate('Attention', active), false);
+    assert.equal(tabPredicate('Attention', { ...active, asks: 0, hanging: { kind: 'provider' } }), true);
+    // Pinned reads the isPinned arg, not the row.
+    assert.equal(tabPredicate('Pinned', active), false);
+    assert.equal(tabPredicate('Pinned', active, true), true);
+});
+// ── flatten: pins ────────────────────────────────────────────────────────────
+test('flatten: Pinned tab shows only pinned rows', () => {
+    const pinned = new Set(['child-c']);
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'Pinned', query: '', pinned });
+    // child-c is directly matched; root2 rides along as its ancestor (context).
+    const matched = v.filter((r) => r.matched).map((r) => r.id);
+    assert.deepEqual(matched, ['child-c']);
+});
+test('flatten: pinned rows float to the top in a flat sort', () => {
+    const pinned = new Set(['lonely']); // an idle straggler that would otherwise sort late
+    const v = flatten(tree(), { collapsed: new Set(), tab: 'All', query: '', sort: 'recency', pinned });
+    assert.equal(v[0].id, 'lonely');
 });
 // ── flatten: collapse / expand ───────────────────────────────────────────────
 const allCollapsed = () => new Set(['root1', 'child-a', 'root2']); // every node with children

package/dist/core/canvas/browse/__tests__/rebuild-coalescer.test.js

@@ -71,19 +71,36 @@ test('a burst of SSE-style triggers produces ONE round of remote requests, not N
             res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
         });
     });
-    await new Promise((r) => server.listen(0, '127.0.0.1', r));
-    const addr = server.address();
-    const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
-    const source = new RemoteCanvasSource(`http://127.0.0.1:${port}`, 'tok');
-    const rebuilder = createCoalescedRebuilder(async () => {
-        source.invalidate();
-        await source.listNodes(); // one round of remote requests, mirroring app.ts's rebuildSnapshot
-    }, 20);
-    for (let i = 0; i < 6; i++)
-        rebuilder.trigger();
-    await new Promise((r) => setTimeout(r, 80));
-    assert.equal(hits, 1, 'a burst of 6 SSE events must produce ONE round of remote requests, not 6');
-    await new Promise((r) => server.close(() => r()));
+    // The server MUST close in a `finally` — a listening TCP server keeps its
+    // process's event loop non-empty forever. Under `node --test`, every test
+    // file is its own child process; if an assertion in this test throws before
+    // the old inline `server.close()` at the end of the function ran, the
+    // server (and the process) never exited, wedging one `--test-concurrency`
+    // slot permanently and hanging the whole suite (see the CI-hang postmortem).
+    try {
+        await new Promise((r) => server.listen(0, '127.0.0.1', r));
+        const addr = server.address();
+        const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+        const source = new RemoteCanvasSource(`http://127.0.0.1:${port}`, 'tok');
+        const rebuilder = createCoalescedRebuilder(async () => {
+            source.invalidate();
+            await source.listNodes(); // one round of remote requests, mirroring app.ts's rebuildSnapshot
+        }, 20);
+        for (let i = 0; i < 6; i++)
+            rebuilder.trigger();
+        // Poll for the request to land instead of sleeping a fixed duration —
+        // deterministic under CI's variable CPU load, and doesn't slow down the
+        // common case (returns as soon as the debounce + request round trip land).
+        const deadline = Date.now() + 2000;
+        while (hits < 1 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 10));
+        }
+        assert.equal(hits, 1, 'a burst of 6 SSE events must produce ONE round of remote requests, not 6');
+    }
+    finally {
+        server.closeAllConnections();
+        await new Promise((r) => server.close(() => r()));
+    }
 });
 // Integration proof for browse/app.ts's ACTUAL wiring — not the coalescer
 // helper in isolation. Every test above instantiates `createCoalescedRebuilder`

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

@@ -37,6 +37,7 @@ function state(over = {}) {
         sort: 'tree',
         preview: false,
         residentsOnly: false,
+        pinned: new Set(),
         ...over,
     };
 }

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

@@ -15,6 +15,7 @@ import { RemoteCanvasSource } from '../remote-canvas-source.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
+import { loadPins, savePins } from './pins.js';
 import { createCoalescedRebuilder } from './rebuild-coalescer.js';
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
@@ -23,10 +24,10 @@ import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './re
 /** Viewport (body) height = total rows minus the header renderFrame draws (see
  *  render.ts headerHeight), the footer, and the preview panel when shown. Kept
  *  in lockstep with render.ts via the shared headerHeight/PREVIEW_HEIGHT. */
-function viewportHeight(rowsTotal, search, previewOn) {
+function viewportHeight(rowsTotal, inputLine, previewOn) {
     const rows = Math.max(8, rowsTotal);
     const previewH = previewOn ? PREVIEW_HEIGHT : 0;
-    return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
+    return Math.max(1, rows - headerHeight(inputLine) - 1 /* footer */ - previewH);
 }
 /** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
  *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
@@ -103,6 +104,14 @@ export async function runBrowse(opts = {}) {
         preview: true, // default ON (decision)
         residentsOnly: true, // default ON: hide one-shot workers (decision)
         pendingClose: null,
+        pinned: loadPins(),
+        help: false,
+        rename: false,
+        renameBuf: '',
+        renameTarget: null,
+        message: false,
+        messageBuf: '',
+        messageTarget: null,
     };
     let visible = [];
     // The DashboardRow ref the tree holds for a visible id. Enrichment mutates this
@@ -193,6 +202,7 @@ export async function runBrowse(opts = {}) {
             cwdScope: state.cwdScope,
             residentsOnly: state.residentsOnly,
             sort: state.sort,
+            pinned: state.pinned,
         });
         if (keepId !== undefined) {
             const idx = visible.findIndex((v) => v.id === keepId);
@@ -207,7 +217,8 @@ export async function runBrowse(opts = {}) {
     const flush = async () => {
         const size = getTerminalSize();
         const previewOn = state.preview && visible.length > 0;
-        const viewport = viewportHeight(size.rows, state.search, previewOn);
+        const inputMode = state.search || state.rename || state.message;
+        const viewport = viewportHeight(size.rows, inputMode, previewOn);
         // Keep the cursor inside the viewport window.
         if (state.cursor < state.scrollOffset)
             state.scrollOffset = state.cursor;
@@ -238,6 +249,9 @@ export async function runBrowse(opts = {}) {
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
             residentsOnly: state.residentsOnly, pendingClose: state.pendingClose,
+            pinned: state.pinned, help: state.help,
+            rename: state.rename, renameBuf: state.renameBuf,
+            message: state.message, messageBuf: state.messageBuf,
             readOnly: isRemote,
         }, size, caps);
         process.stdout.write(frame);
@@ -419,6 +433,102 @@ export async function runBrowse(opts = {}) {
             scheduleSearchRepaint();
         }
     };
+    // Recenter the cursor on the launching node (CRTR_NODE_ID), expanding its
+    // ancestors so it is actually visible. No-op outside a node or when it's filtered
+    // out of the current tab/scope. Same move the boot performs, on demand (`.`).
+    const recenterOnSelf = () => {
+        const selfId = process.env['CRTR_NODE_ID'];
+        if (selfId === undefined || selfId === '' || !tree.nodes.has(selfId))
+            return;
+        for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
+            state.collapsed.delete(p);
+        }
+        recompute(selfId);
+    };
+    // Toggle the pin on a node: mutate the in-memory set, persist best-effort, and
+    // recompute so it floats (flat sorts) / (dis)appears from the Pinned tab.
+    const togglePin = (id) => {
+        if (state.pinned.has(id))
+            state.pinned.delete(id);
+        else
+            state.pinned.add(id);
+        savePins(state.pinned);
+        recompute(id);
+    };
+    // Commit an inline rename: `crtr node config <id> --name <name>` (also renames a
+    // live viewer window), then reflect the new name into the snapshot in place.
+    const commitRename = () => {
+        const id = state.renameTarget;
+        const name = state.renameBuf.trim();
+        state.rename = false;
+        if (id !== null && name !== '') {
+            try {
+                execFileSync('crtr', ['node', 'config', id, '--name', name], { stdio: 'ignore' });
+            }
+            catch {
+                /* best-effort — a rename failure never wedges the picker */
+            }
+            const n = tree.nodes.get(id);
+            if (n !== undefined)
+                n.row.name = name;
+        }
+        recompute(state.renameTarget ?? undefined);
+        scheduleFlush();
+    };
+    // Commit an inline message: `crtr node msg --to <id> <body>` (immediate inbox
+    // delivery, best-effort revive if dormant). Fire-and-forget — browse stays put.
+    const commitMessage = () => {
+        const id = state.messageTarget;
+        const body = state.messageBuf.trim();
+        state.message = false;
+        if (id !== null && body !== '') {
+            try {
+                execFileSync('crtr', ['node', 'msg', '--to', id, body], { stdio: 'ignore' });
+            }
+            catch {
+                /* best-effort — delivery failure never wedges the picker */
+            }
+        }
+        scheduleFlush();
+    };
+    // Shared text-input keystroke handling for the rename/message sub-modes: Esc
+    // cancels, Enter commits, Backspace deletes, Ctrl+C quits, printable chars append.
+    const onKeyText = (input, key, get, set, commit, cancel) => {
+        if (key.escape) {
+            cancel();
+            return;
+        }
+        if (key.return) {
+            commit();
+            return;
+        }
+        if (key.backspace) {
+            set(get().slice(0, -1));
+            scheduleFlush();
+            return;
+        }
+        if (key.ctrl) {
+            if (input === 'c')
+                quit();
+            return;
+        }
+        const printable = [...input].filter((c) => c >= ' ').join('');
+        if (printable.length > 0) {
+            set(get() + printable);
+            scheduleFlush();
+        }
+    };
+    const onKeyRename = (input, key) => onKeyText(input, key, () => state.renameBuf, (s) => { state.renameBuf = s; }, commitRename, () => { state.rename = false; scheduleFlush(); });
+    const onKeyMessage = (input, key) => onKeyText(input, key, () => state.messageBuf, (s) => { state.messageBuf = s; }, commitMessage, () => { state.message = false; scheduleFlush(); });
+    // Help overlay: any key dismisses (Ctrl+C still quits outright).
+    const onKeyHelp = (input, key) => {
+        if (key.ctrl && input === 'c') {
+            quit();
+            return;
+        }
+        state.help = false;
+        scheduleFlush();
+    };
     const onKeyNav = (input, key) => {
         // Ctrl-combos first: only Ctrl+C is meaningful (quit); swallow the rest so
         // Ctrl+L / Ctrl+J / Ctrl+Q etc. don't masquerade as l/j/q commands.
@@ -519,7 +629,7 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        if (input >= '1' && input <= '4') {
+        if (input >= '1' && input <= '5') {
             const idx = Number(input) - 1;
             if (idx < TABS.length) {
                 state.tab = TABS[idx];
@@ -569,6 +679,49 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
+        // Help overlay.
+        if (input === '?') {
+            state.help = true;
+            scheduleFlush();
+            return;
+        }
+        // Pin / unpin (local, view-only — works against a remote canvas too).
+        if (input === 'f') {
+            if (row !== undefined)
+                togglePin(row.id);
+            scheduleFlush();
+            return;
+        }
+        // Recenter on the launching node.
+        if (input === '.') {
+            recenterOnSelf();
+            scheduleFlush();
+            return;
+        }
+        // Rename the node inline (mutation — no-op on a remote canvas).
+        if (input === 'R') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                state.rename = true;
+                state.renameTarget = row.id;
+                state.renameBuf = rowOf(row.id)?.name ?? '';
+            }
+            scheduleFlush();
+            return;
+        }
+        // Message the node without resuming it (mutation — no-op on a remote canvas).
+        if (input === 'm') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                state.message = true;
+                state.messageTarget = row.id;
+                state.messageBuf = '';
+            }
+            scheduleFlush();
+            return;
+        }
         // Search. Starting a search ranks by relevance (decision) so the best prompt/
         // name match floats to the top as you type.
         if (input === '/') {
@@ -664,8 +817,14 @@ export async function runBrowse(opts = {}) {
         const onData = (data) => {
             try {
                 const { input, key } = parseKeypress(data);
-                if (state.search)
+                if (state.help)
+                    onKeyHelp(input, key);
+                else if (state.search)
                     onKeySearch(input, key);
+                else if (state.rename)
+                    onKeyRename(input, key);
+                else if (state.message)
+                    onKeyMessage(input, key);
                 else
                     onKeyNav(input, key);
             }

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

@@ -1,6 +1,6 @@
 import type { DashboardRow } from '../render.js';
 import type { NodeStatus } from '../types.js';
-export type Tab = 'All' | 'Live' | 'Dormant' | 'Flagged';
+export type Tab = 'All' | 'Live' | 'Dormant' | 'Attention' | 'Pinned';
 export declare const TABS: readonly Tab[];
 /** How the visible rows are ordered.
  *    tree      — spanning-tree order, ancestors shown for context (the default).
@@ -11,11 +11,12 @@ export declare const TABS: readonly Tab[];
 export type SortMode = 'tree' | 'attention' | 'relevance' | 'recency';
 export declare const SORTS: readonly SortMode[];
 /** 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 declare function tabPredicate(tab: Tab, row: DashboardRow): boolean;
+ *    All       — every node.
+ *    Live      — active | idle.
+ *    Dormant   — done | dead | canceled.
+ *    Attention — needs a human: has pending asks OR is parked on a fault.
+ *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
+export declare function tabPredicate(tab: Tab, row: DashboardRow, isPinned?: boolean): boolean;
 export interface TreeNode {
     row: DashboardRow;
     depth: number;
@@ -138,6 +139,9 @@ export interface FlattenOpts {
     /** Ordering. `tree` keeps the spanning tree + ancestor context; `relevance` /
      *  `recency` produce a FLAT ranked list of directly-matched rows. */
     sort?: SortMode;
+    /** User-starred node ids (local, view-only). Gates the Pinned tab, and floats
+     *  pinned rows to the top of every FLAT sort mode. undefined = none pinned. */
+    pinned?: Set<string>;
 }
 /** Is this row inside the active cwd scope? No scope (null/undefined) = All dirs. */
 export declare function cwdMatch(scope: string | null | undefined, row: DashboardRow): boolean;

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

@@ -4,19 +4,21 @@
 // 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 TABS = ['All', 'Live', 'Dormant', 'Attention', 'Pinned'];
 export const SORTS = ['tree', 'attention', '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) {
+ *    All       — every node.
+ *    Live      — active | idle.
+ *    Dormant   — done | dead | canceled.
+ *    Attention — needs a human: has pending asks OR is parked on a fault.
+ *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
+export function tabPredicate(tab, row, isPinned = false) {
     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;
+        case 'Attention': return row.asks > 0 || row.hanging != null;
+        case 'Pinned': return isPinned;
     }
 }
 /** Sort rank for roots/stragglers — live first (active, then idle), dormant
@@ -383,7 +385,8 @@ export function lifecycleMatch(residentsOnly, row) {
  * always reachable.
  */
 export function flatten(tree, opts) {
-    const { collapsed, tab, query, cwdScope, residentsOnly, sort = 'tree' } = opts;
+    const { collapsed, tab, query, cwdScope, residentsOnly, sort = 'tree', pinned } = opts;
+    const isPinned = (id) => pinned?.has(id) === true;
     // 1. Directly-matched nodes: tab predicate AND cwd scope AND lifecycle AND query.
     //    `matched` honors the residents-only filter (drives top-level rows, ancestor
     //    context, force-expand, and the flat search results below). `matchedAll` is
@@ -394,7 +397,7 @@ export function flatten(tree, opts) {
     const matched = new Set();
     const matchedAll = new Set();
     for (const [id, node] of tree.nodes) {
-        if (tabPredicate(tab, node.row) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row)) {
+        if (tabPredicate(tab, node.row, isPinned(id)) && cwdMatch(cwdScope, node.row) && queryMatch(query, node.row)) {
             matchedAll.add(id);
             if (lifecycleMatch(residentsOnly, node.row))
                 matched.add(id);
@@ -407,21 +410,26 @@ export function flatten(tree, opts) {
         const ids = [...matched];
         const createdOf = (id) => tree.nodes.get(id)?.row.created ?? '';
         const byRecency = (a, b) => createdOf(b).localeCompare(createdOf(a));
+        // Pinned rows float above everything in every flat mode — "keep this at the
+        // top of my list" is the whole point of a pin. Ordering WITHIN each pin tier
+        // still follows the active sort.
+        const pinRank = (id) => (isPinned(id) ? 0 : 1);
         if (sort === 'attention') {
             // Tiered (attached/streaming/live first), newest-message-first within tier.
             const rowOf = (id) => tree.nodes.get(id).row;
-            ids.sort((a, b) => (attentionTier(rowOf(a)) - attentionTier(rowOf(b))) ||
+            ids.sort((a, b) => (pinRank(a) - pinRank(b)) ||
+                (attentionTier(rowOf(a)) - attentionTier(rowOf(b))) ||
                 (attentionMtime(rowOf(b)) - attentionMtime(rowOf(a))) ||
                 byRecency(a, b));
         }
         else if (sort === 'recency' || query === '') {
-            ids.sort(byRecency);
+            ids.sort((a, b) => (pinRank(a) - pinRank(b)) || byRecency(a, b));
         }
         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));
+            ids.sort((a, b) => (pinRank(a) - pinRank(b)) || (score.get(b) - score.get(a)) || byRecency(a, b));
         }
         return ids.map((id) => ({ id, depth: 0, hasChildren: false, collapsed: false, matched: true }));
     }

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

@@ -0,0 +1,4 @@
+/** Load the pinned-id set. Missing/garbage file → empty set (never throws). */
+export declare function loadPins(): Set<string>;
+/** Persist the pinned-id set. Best-effort — a write failure never wedges the TUI. */
+export declare function savePins(pins: Set<string>): void;

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

@@ -0,0 +1,29 @@
+// pins.ts — the durable per-user "pinned" set for the canvas browser.
+//
+// A pin is a LOCAL, view-only preference, NOT a canvas property: starring a node
+// keeps it at the top of YOUR navigator across sessions and machines, and it works
+// against a remote canvas too (you are pinning in your own view, mutating nothing
+// on the canvas). Stored as a flat id list at ~/.crouter/browse-pins.json so every
+// `canvas browse` invocation shares it regardless of cwd/scope. Read once at boot,
+// mutated in memory, written best-effort on each toggle.
+import { join } from 'node:path';
+import { userScopeRoot } from '../../scope.js';
+import { readJsonIfExists, atomicWriteJson } from '../../fs-utils.js';
+const PINS_FILE = 'browse-pins.json';
+function pinsPath() {
+    return join(userScopeRoot(), PINS_FILE);
+}
+/** Load the pinned-id set. Missing/garbage file → empty set (never throws). */
+export function loadPins() {
+    const raw = readJsonIfExists(pinsPath());
+    return new Set(Array.isArray(raw) ? raw.filter((x) => typeof x === 'string') : []);
+}
+/** Persist the pinned-id set. Best-effort — a write failure never wedges the TUI. */
+export function savePins(pins) {
+    try {
+        atomicWriteJson(pinsPath(), [...pins]);
+    }
+    catch {
+        /* best-effort: a pin that doesn't survive the session is a minor loss */
+    }
+}

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

@@ -6,7 +6,7 @@ export declare const PROMPT_LINES = 3;
 export declare const REPLY_LINES = 3;
 export declare const PREVIEW_BODY: number;
 export declare const PREVIEW_HEIGHT: number;
-export declare function headerHeight(search: boolean): number;
+export declare function headerHeight(inputLine: boolean): number;
 export interface RenderState {
     tree: Tree;
     visible: VisibleRow[];
@@ -25,6 +25,18 @@ export interface RenderState {
     /** Lifecycle filter: when true, `terminal` (one-shot worker) nodes are hidden
      *  — surfaced as a status-line cue. */
     residentsOnly: boolean;
+    /** User-starred node ids — drives the ★ row marker + the Pinned tab. */
+    pinned: Set<string>;
+    /** Inline rename input: when true, the header shows a rename prompt bound to
+     *  `renameBuf` and the footer becomes commit/cancel. */
+    rename?: boolean;
+    renameBuf?: string;
+    /** Inline message input: when true, the header shows a message prompt bound to
+     *  `messageBuf` (delivered via `crtr node msg`). */
+    message?: boolean;
+    messageBuf?: string;
+    /** When true, the whole body is replaced by the keybinding help overlay. */
+    help?: boolean;
     /** When set, a close-out (`x`) is awaiting y/n confirmation because the node (or
      *  a descendant) is actively streaming. Holds the node id being confirmed; the
      *  footer becomes the y/n prompt. null/undefined = no pending confirm. */