@crouton-kit/crouter 0.3.70 → 0.3.79

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

@@ -15,7 +15,30 @@ 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';
+import { matchesTerminalInput, resolveUserKeybindings, } from '../../keybindings/index.js';
+const BROWSE_NAV_ACTIONS = [
+    'crtr.browse.quit', 'crtr.browse.down', 'crtr.browse.up', 'crtr.browse.first', 'crtr.browse.last',
+    'crtr.browse.expand-or-child', 'crtr.browse.collapse-or-parent', 'crtr.browse.toggle-fold',
+    'crtr.browse.tab-next', 'crtr.browse.tab-previous', 'crtr.browse.tab.1', 'crtr.browse.tab.2',
+    'crtr.browse.tab.3', 'crtr.browse.tab.4', 'crtr.browse.tab.5', 'crtr.browse.close-subtree', 'crtr.browse.sort',
+    'crtr.browse.scope', 'crtr.browse.residents', 'crtr.browse.preview', 'crtr.browse.search',
+    'crtr.browse.revive-now', 'crtr.browse.focus',
+];
+const BROWSE_SEARCH_ACTIONS = [
+    'crtr.browse.search.cancel', 'crtr.browse.search.commit', 'crtr.browse.search.delete',
+    'crtr.browse.search.quit',
+];
+function firstMatching(bindings, ids, raw) {
+    return ids.find((id) => matchesTerminalInput(bindings, id, raw)) ?? null;
+}
+export function resolveBrowseNavAction(bindings, raw) {
+    return firstMatching(bindings, BROWSE_NAV_ACTIONS, raw);
+}
+export function resolveBrowseSearchAction(bindings, raw) {
+    return firstMatching(bindings, BROWSE_SEARCH_ACTIONS, raw);
+}
 // 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.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
@@ -23,10 +46,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
@@ -44,6 +67,7 @@ export function wireEventStreamRebuild(eventStream, rebuild) {
 export async function runBrowse(opts = {}) {
     const source = opts.source ?? localCanvasSource;
     const isRemote = source instanceof RemoteCanvasSource;
+    const bindings = resolveUserKeybindings();
     // No TTY → print the static forest and exit 0 (no raw mode).
     if (!process.stdin.isTTY) {
         process.stdout.write(await renderForestFromSource(source) + '\n');
@@ -103,6 +127,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 +225,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 +240,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 +272,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);
@@ -296,6 +333,13 @@ export async function runBrowse(opts = {}) {
             n.row.status = m.status; // real post-close status (done / canceled)
             n.row.streaming = false;
             n.row.viewed = false;
+            // A finalized node is no longer hanging and owes no answer — clear both so it
+            // actually LEAVES the Attention tab (asks>0 || hanging) and stops rendering the
+            // stale `⚠ down` rail. Without this, closing a faulted/asking node from the
+            // Attention tab looks like a no-op: the row was finalized in the db but its
+            // stale fault/ask kept it matching the tab, so it never disappeared.
+            n.row.hanging = null;
+            n.row.asks = 0;
         }
         // Keep the cursor at the same INDEX (the row that shifts up into the closed
         // slot), not pinned to the now-gone node — recompute() leaves state.cursor
@@ -375,7 +419,8 @@ export async function runBrowse(opts = {}) {
         });
     };
     const onKeySearch = (input, key) => {
-        if (key.escape) {
+        const action = resolveBrowseSearchAction(bindings, { input, ...key });
+        if (action === 'crtr.browse.search.cancel') {
             // Cancel the search: drop the query AND the relevance ranking it switched
             // on, returning to the tree. Synchronous: we're leaving search mode.
             state.search = false;
@@ -385,7 +430,7 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        if (key.return) {
+        if (action === 'crtr.browse.search.commit') {
             // Commit: keep the filter, drop search mode, land on the first match. Must
             // recompute synchronously first so the match index reflects the final query
             // even if a coalesced repaint is still pending.
@@ -397,17 +442,16 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        if (key.backspace) {
+        if (action === 'crtr.browse.search.delete') {
             state.query = state.query.slice(0, -1);
             scheduleSearchRepaint();
             return;
         }
-        // Any ctrl-combo: Ctrl+C quits; everything else is swallowed (never typed).
-        if (key.ctrl) {
-            if (input === 'c')
-                quit();
+        // Bound quit acts before text capture; other ctrl-combos are swallowed.
+        if (action === 'crtr.browse.search.quit')
+            quit();
+        if (key.ctrl)
             return;
-        }
         // Append every printable char in the chunk. Fast typing batches multiple
         // chars into one stdin read, so we must take them all (not just a length-1
         // chunk) or keystrokes get dropped. Filtering to >= ' ' strips control/escape
@@ -419,18 +463,114 @@ export async function runBrowse(opts = {}) {
             scheduleSearchRepaint();
         }
     };
-    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.
+    // 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;
         }
-        // Close-out confirm sub-state: a streaming node is awaiting y/n. Swallow every
-        // other key so the confirm is modal.
+        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) => {
+        const raw = { input, ...key };
+        const action = resolveBrowseNavAction(bindings, raw);
+        // Unbound ctrl-combos are swallowed so they never masquerade as printable commands.
+        if (key.ctrl && action === null)
+            return;
+        // Preserve an explicitly bound control-combo quit while the close confirmation is open.
+        // Other non-confirming input dismisses the modal without also running navigation actions.
+        if (state.pendingClose !== null && action === 'crtr.browse.quit' && key.ctrl)
+            quit();
         if (state.pendingClose !== null) {
-            if (input === 'y' || input === 'Y') {
+            if (matchesTerminalInput(bindings, 'crtr.browse.confirm-close', raw)) {
                 const target = state.pendingClose;
                 void doClose(target).then(() => scheduleFlush()).catch(() => scheduleFlush());
                 return;
@@ -441,32 +581,31 @@ export async function runBrowse(opts = {}) {
             return;
         }
         const row = curRow();
-        // Quit.
-        if (input === 'q' || key.escape)
+        // Quit and move.
+        if (action === 'crtr.browse.quit')
             quit();
-        // Move.
-        if (key.upArrow || input === 'k') {
+        if (action === 'crtr.browse.up') {
             state.cursor = Math.max(0, state.cursor - 1);
             scheduleFlush();
             return;
         }
-        if (key.downArrow || input === 'j') {
+        if (action === 'crtr.browse.down') {
             state.cursor = Math.max(0, Math.min(visible.length - 1, state.cursor + 1));
             scheduleFlush();
             return;
         }
-        if (input === 'g') {
+        if (action === 'crtr.browse.first') {
             state.cursor = 0;
             scheduleFlush();
             return;
         }
-        if (input === 'G') {
+        if (action === 'crtr.browse.last') {
             state.cursor = Math.max(0, visible.length - 1);
             scheduleFlush();
             return;
         }
         // Expand / descend.
-        if (key.rightArrow || input === 'l') {
+        if (action === 'crtr.browse.expand-or-child') {
             if (row !== undefined && row.hasChildren) {
                 if (!isExpanded(row.id)) {
                     state.collapsed.delete(row.id);
@@ -480,7 +619,7 @@ export async function runBrowse(opts = {}) {
             return;
         }
         // Collapse / ascend.
-        if (key.leftArrow || input === 'h') {
+        if (action === 'crtr.browse.collapse-or-parent') {
             if (row !== undefined && row.hasChildren && isExpanded(row.id)) {
                 state.collapsed.add(row.id);
                 recompute(row.id);
@@ -497,7 +636,7 @@ export async function runBrowse(opts = {}) {
             return;
         }
         // Toggle collapse.
-        if (input === ' ') {
+        if (action === 'crtr.browse.toggle-fold') {
             if (row !== undefined && row.hasChildren) {
                 if (isExpanded(row.id))
                     state.collapsed.add(row.id);
@@ -508,19 +647,20 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        // Tabs.
-        if (key.tab || input === ']') {
+        // Tabs. next/previous and tab.1–5 (including Pinned) all resolve through the
+        // catalog, so each numbered tab is user-remappable like any other binding.
+        if (action === 'crtr.browse.tab-next') {
             cycleTab(1);
             scheduleFlush();
             return;
         }
-        if (key.shiftTab || input === '[') {
+        if (action === 'crtr.browse.tab-previous') {
             cycleTab(-1);
             scheduleFlush();
             return;
         }
-        if (input >= '1' && input <= '4') {
-            const idx = Number(input) - 1;
+        if (action?.startsWith('crtr.browse.tab.')) {
+            const idx = Number(action.slice(-1)) - 1;
             if (idx < TABS.length) {
                 state.tab = TABS[idx];
                 state.cursor = 0;
@@ -533,7 +673,7 @@ export async function runBrowse(opts = {}) {
         // Close-out the selected node (+ its exclusive subtree). If anything in that
         // subtree is actively streaming, confirm first (y/n); otherwise close at once.
         // No-op against a remote canvas — mutations are disabled (footer says so).
-        if (input === 'x') {
+        if (action === 'crtr.browse.close-subtree') {
             if (isRemote)
                 return;
             if (row === undefined) {
@@ -549,29 +689,72 @@ export async function runBrowse(opts = {}) {
             return;
         }
         // Sort / scope / residents / preview.
-        if (input === 's') {
+        if (action === 'crtr.browse.sort') {
             cycleSort();
             scheduleFlush();
             return;
         }
-        if (input === 'c') {
+        if (action === 'crtr.browse.scope') {
             toggleScope();
             scheduleFlush();
             return;
         }
-        if (input === 'r') {
+        if (action === 'crtr.browse.residents') {
             toggleResidents();
             scheduleFlush();
             return;
         }
-        if (input === 'p') {
+        if (action === 'crtr.browse.preview') {
             state.preview = !state.preview;
             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 === '/') {
+        if (action === 'crtr.browse.search') {
             state.search = true;
             state.query = '';
             state.sort = 'relevance';
@@ -587,7 +770,7 @@ export async function runBrowse(opts = {}) {
         // --now` (browse goes through commands, never touching the runtime directly). 'k' is
         // vim-up here, so the kick is on SHIFT-K.
         // No-op against a remote canvas — mutations are disabled (footer says so).
-        if (input === 'K') {
+        if (action === 'crtr.browse.revive-now') {
             if (isRemote)
                 return;
             if (row !== undefined) {
@@ -600,7 +783,7 @@ export async function runBrowse(opts = {}) {
         }
         // Resume. No-op against a remote canvas — mutations/focus are disabled
         // (footer says so).
-        if (key.return) {
+        if (action === 'crtr.browse.focus') {
             if (isRemote)
                 return;
             if (row !== undefined)
@@ -664,8 +847,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. */