@north-light/crouter 0.3.197 → 0.3.199

package/dist/clients/inbox/tui/render.js

@@ -1,24 +1,42 @@
 import stringWidth from 'string-width';
 import { isResponseBearingSlot } from '../../../core/human/page-schema.js';
+import { answerCommentAnchorLabel, describePageAnswer } from '../../../core/human/answer.js';
 import { renderMarkdownBlockAwareLines } from '../../../core/termrender/termrender.js';
-import { anchorLabel, describeSlot, pageComplete, slotActions, slotAnswered, summarizeSlotResponse, tableMarkdown, terminalAnswerable } from './slots.js';
-import { RESET, BOLD, DIM, GREEN, YELLOW, CYAN, REVERSE, sanitize, singleLine, truncate, hline, hardWrap, centerHorizontal, clipLine, panLine, visibleWidth } from './ansi.js';
+import { commentAnchors, describeSlot, pageComplete, slotActions, slotAnswered, tableMarkdown, terminalAnswerable } from './slots.js';
+import { RESET, BOLD, DIM, GREEN, YELLOW, CYAN, REVERSE, sanitize, singleLine, truncate, hline, wrap, centerHorizontal, clipLine, panLine, visibleWidth } from './ansi.js';
 const PAN_STEP = 8;
 const mdLines = (md, maxW, paneW) => renderMarkdownBlockAwareLines(md, maxW, paneW);
-function proseLines(blocks, maxW, paneW) {
-    return blocks.flatMap((block, index) => [...(index > 0 ? [''] : []), ...mdLines(block, maxW, paneW)]);
+function pageAnswer(state) {
+    return describePageAnswer(state.manifest, Object.fromEntries(state.responses), { completedAt: '' });
+}
+function answerSlot(answer, slot) {
+    return slot.id === undefined ? undefined : answer.slots.find((candidate) => candidate.id === slot.id);
+}
+function answerSummary(slot) {
+    if (slot === undefined || slot.state === 'unanswered')
+        return 'unanswered';
+    if (slot.raw !== undefined)
+        return 'custom response';
+    const groups = slot.text !== undefined ? [slot.text.edited ? 'edited' : 'accepted'] : slot.groups.map((group) => group.picked.length === 0 ? 'none' : group.picked.map((item) => item.label).join(', '));
+    if (slot.freetext !== undefined)
+        groups.push(slot.freetext);
+    if (slot.comments.length > 0)
+        groups.push(`${slot.comments.length} comment${slot.comments.length === 1 ? '' : 's'}`);
+    return groups.join('; ') || 'answered';
+}
+function commentLabel(slot, anchor) {
+    return answerCommentAnchorLabel(slot, anchor);
 }
 export function renderOverview(state, cols, rows) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
     const lines = ['', `  ${BOLD}${CYAN}${sanitize(state.manifest.title)}${RESET}`];
     if (state.manifest.subtitle)
-        lines.push(`  ${DIM}${sanitize(state.manifest.subtitle)}${RESET}`);
-    lines.push(`  ${DIM}${hline(maxW)}${RESET}`, '');
-    if (state.manifest.dialect === 'html')
-        lines.push(`  ${DIM}rich page — open in Northlight${RESET}`, '');
-    else
-        for (const line of proseLines(state.overviewProse, maxW, Math.max(20, cols - 4)))
-            lines.push(`  ${line}`);
+        for (const line of wrap(sanitize(state.manifest.subtitle), maxW))
+            lines.push(`  ${DIM}${line}${RESET}`);
+    const hasBody = state.slots.length > 0;
+    if (hasBody)
+        lines.push(`  ${DIM}${hline(maxW)}${RESET}`, '');
+    const answer = pageAnswer(state);
     let priorStep = -1;
     for (let i = 0; i < state.slots.length; i++) {
         const slot = state.slots[i];
@@ -33,20 +51,66 @@ export function renderOverview(state, cols, rows) {
         const cursor = i === state.currentIndex ? `${CYAN}▸${RESET} ` : '  ';
         lines.push(`  ${cursor}${icon} ${truncate(singleLine(describeSlot(slot)), Math.max(10, cols - 16))}`);
         if (response !== undefined)
-            lines.push(`      ${DIM}${truncate(singleLine(summarizeSlotResponse(slot, response)), Math.max(10, cols - 10))}${RESET}`);
+            lines.push(`      ${DIM}${truncate(singleLine(answerSummary(answerSlot(answer, slot))), Math.max(10, cols - 10))}${RESET}`);
     }
-    if (state.slots.length === 0)
-        lines.push(`  ${DIM}No interactive slots${RESET}`);
-    lines.push('', `  ${DIM}${hline(maxW)}${RESET}`);
+    if (hasBody)
+        lines.push('');
+    lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
     const display = !state.manifest.slots.some(isResponseBearingSlot);
     lines.push(display ? `  ${DIM}q${RESET} dismiss` : `  ${DIM}enter${RESET} review  ${DIM}j/k${RESET} navigate  ${DIM}q${RESET} close`);
     return centeredWindow(lines, state, cols, rows, maxW + 2);
 }
+/** Wrap an input buffer and paint the cursor the way a terminal does: the
+ *  character under it is drawn in reverse video, occupying its own cell rather
+ *  than pushing the rest of the line across by one. Only past the end of a row
+ *  does the cursor need a cell of its own, and there it is a reversed space.
+ *  Wrapping runs over the plain buffer, so the rows here are exactly the rows
+ *  `verticalCursor` moves between. */
 export function renderInputBuffer(buffer, cursor, maxWidth) {
     const chars = [...buffer];
     const at = Math.max(0, Math.min(cursor, chars.length));
-    const withCaret = [...chars.slice(0, at), '\uE000', ...chars.slice(at)].join('');
-    return hardWrap(withCaret, maxWidth).map((line) => line.includes('\uE000') ? line.replace('\uE000', `${REVERSE} ${RESET}`) : line);
+    const rows = wrappedRowBounds(buffer, maxWidth);
+    let cursorRow = 0;
+    for (let i = 0; i < rows.length; i++)
+        if (rows[i].start <= at)
+            cursorRow = i;
+    const lines = rows.map((row, index) => {
+        if (index !== cursorRow)
+            return chars.slice(row.start, row.end).join('');
+        const head = chars.slice(row.start, at).join('');
+        const under = at < row.end ? chars[at] : ' ';
+        const tail = at < row.end ? chars.slice(at + 1, row.end).join('') : '';
+        return `${head}${REVERSE}${under}${RESET}${tail}`;
+    });
+    // A cursor past the end of an already-full row has no cell left on it, so it
+    // takes the first cell of the next row instead of overflowing the wrap width.
+    const last = rows[cursorRow];
+    if (at === last.end && stringWidth(chars.slice(last.start, last.end).join('')) >= maxWidth) {
+        lines[cursorRow] = chars.slice(last.start, last.end).join('');
+        lines.splice(cursorRow + 1, 0, `${REVERSE} ${RESET}`);
+    }
+    return lines;
+}
+/** Start of the word before the cursor (alt+left / readline alt-b). The one
+ *  implementation of word motion for every inbox input buffer. */
+export function wordLeftIndex(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.max(0, Math.min(cursor, chars.length));
+    while (i > 0 && /\s/.test(chars[i - 1]))
+        i--;
+    while (i > 0 && !/\s/.test(chars[i - 1]))
+        i--;
+    return i;
+}
+/** Just past the end of the word after the cursor (alt+right / readline alt-f). */
+export function wordRightIndex(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.max(0, Math.min(cursor, chars.length));
+    while (i < chars.length && /\s/.test(chars[i]))
+        i++;
+    while (i < chars.length && !/\s/.test(chars[i]))
+        i++;
+    return i;
 }
 export function wrappedRowBounds(buffer, width) {
     const chars = [...buffer];
@@ -107,13 +171,12 @@ function itemLines(state, cols) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
     const paneW = Math.max(20, cols - 4);
     const lines = ['', `  ${BOLD}${CYAN}[${state.currentIndex + 1}/${state.slots.length}]${RESET}  ${DIM}${sanitize(state.manifest.title)}${RESET}`, `  ${DIM}${hline(maxW)}${RESET}`, '', `  ${BOLD}${sanitize(describeSlot(slot))}${RESET}`];
-    // A single-slot page opens straight into item-review, so its leading prose has nowhere else to render.
-    const prose = state.slots.length === 1 ? [...state.overviewProse, ...(state.slotProse.get(0) ?? [])] : state.slotProse.get(state.currentIndex) ?? [];
-    if (state.manifest.dialect === 'html')
-        lines.push('', `  ${DIM}rich page — open in Northlight${RESET}`);
-    else
-        for (const line of proseLines(prose, maxW, paneW))
+    const body = slot.config.body;
+    if (typeof body === 'string' && body.length > 0) {
+        lines.push('');
+        for (const line of mdLines(body, maxW, paneW))
             lines.push(`  ${line}`);
+    }
     if (!terminalAnswerable(slot))
         lines.push('', `  ${DIM}${sanitize(slot.kind)} — cannot be answered in the terminal; open in Northlight${RESET}`);
     else if (slot.kind === 'chart') {
@@ -125,9 +188,9 @@ function itemLines(state, cols) {
         lines.push('');
         for (const line of mdLines(tableMarkdown(slot.config), maxW, paneW))
             lines.push(`  ${line}`);
-        const caption = slot.config.caption;
-        if (caption)
-            lines.push(`  ${DIM}${sanitize(caption)}${RESET}`);
+        const label = slot.config.label;
+        if (label)
+            lines.push(`  ${DIM}${sanitize(label)}${RESET}`);
     }
     else if (slot.kind === 'text') {
         const response = slot.id === undefined ? undefined : state.responses.get(slot.id);
@@ -138,7 +201,7 @@ function itemLines(state, cols) {
     }
     lines.push('', `  ${DIM}${hline(maxW)}${RESET}`);
     if (state.inputMode !== null) {
-        const label = state.inputMode.kind === 'comment' ? `Comment on ${anchorLabel(slot, state.inputMode.anchor ?? { kind: 'whole' })}` : state.inputMode.kind === 'text' ? 'Edit text' : 'Other response';
+        const label = state.inputMode.kind === 'comment' ? `Comment on ${commentLabel(slot, state.inputMode.anchor)}` : state.inputMode.kind === 'text' ? 'Edit text' : 'Other response';
         lines.push(`  ${BOLD}${label}${RESET}`);
         for (const line of renderInputBuffer(state.inputMode.buffer, state.inputMode.cursor, Math.max(10, maxW - 4)))
             lines.push(`  ${line}`);
@@ -152,7 +215,8 @@ function itemLines(state, cols) {
                 const mark = selected(state, slot, action.group, action.id) ? `${GREEN}✓${RESET}` : ' ';
                 lines.push(`  ${cursor} [${mark}] ${action.shortcut ? `[${action.shortcut}] ` : ''}${sanitize(action.label)}`);
                 if (action.description)
-                    lines.push(`        ${DIM}${sanitize(action.description)}${RESET}`);
+                    for (const line of wrap(sanitize(action.description), Math.max(10, maxW - 6)))
+                        lines.push(`        ${DIM}${line}${RESET}`);
             }
             else {
                 const key = action.kind === 'freetext' ? 'r' : action.kind === 'edit' ? 'e' : 'a';
@@ -160,10 +224,11 @@ function itemLines(state, cols) {
             }
         });
         for (const comment of responseComments(state, slot))
-            lines.push(`  ${DIM}attached: ${anchorLabel(slot, comment.anchor)} — ${sanitize(comment.text)}${RESET}`);
+            for (const line of wrap(`attached: ${commentLabel(slot, comment.anchor)} — ${sanitize(comment.text)}`, Math.max(10, maxW - 2)))
+                lines.push(`  ${DIM}${line}${RESET}`);
         if (state.hint)
             lines.push(`  ${YELLOW}${sanitize(state.hint)}${RESET}`);
-        lines.push(`  ${DIM}n/p next/previous  j/k actions  c comment  u/d scroll  h/l pan  q close${RESET}`);
+        lines.push(`  ${DIM}n/p next/previous  j/k actions${commentAnchors(slot).length > 0 ? '  c comment' : ''}  u/d scroll  h/l pan  q close${RESET}`);
     }
     const maxLine = Math.max(0, ...lines.map(visibleWidth));
     return { lines, maxW, maxH: Math.max(0, maxLine - Math.max(1, cols)) };
@@ -195,13 +260,13 @@ export function renderItemReview(state, cols, rows) {
 export function renderFinal(state, cols, rows) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
     const lines = ['', `  ${BOLD}${CYAN}${sanitize(state.manifest.title)} — Summary${RESET}`, `  ${DIM}${hline(maxW)}${RESET}`, ''];
-    for (const slot of state.slots) {
-        const response = slot.id === undefined ? undefined : state.responses.get(slot.id);
-        lines.push(`  ${slotAnswered(state, slot) ? `${GREEN}✓${RESET}` : isResponseBearingSlot(slot) ? `${YELLOW}○${RESET}` : `${DIM}·${RESET}`} ${BOLD}${sanitize(describeSlot(slot))}${RESET}  ${DIM}${sanitize(summarizeSlotResponse(slot, response))}${RESET}`);
+    const answer = pageAnswer(state);
+    for (const slot of answer.slots) {
+        const manifestSlot = state.manifest.slots.find((candidate) => candidate.id === slot.id);
+        const answered = manifestSlot !== undefined && slotAnswered(state, manifestSlot);
+        const mark = answered ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
+        lines.push(`  ${mark} ${BOLD}${sanitize(manifestSlot === undefined ? slot.kind : describeSlot(manifestSlot))}${RESET}  ${DIM}${sanitize(answerSummary(slot))}${RESET}`);
     }
-    if (state.manifest.dialect !== 'html')
-        for (const line of proseLines(state.finalProse, maxW, Math.max(20, cols - 4)))
-            lines.push(`  ${line}`);
     const complete = pageComplete(state);
     if (!complete) {
         lines.push('', `  ${YELLOW}Cannot submit yet.${RESET}`);

package/dist/clients/inbox/tui/slots.d.ts

@@ -1,4 +1,4 @@
-import type { CommentAnchor, PageManifest, PageSlot, SlotResponse, TableConfig } from '../../../core/human/page-schema.js';
+import type { CommentAnchor, PageManifest, PageSlot, TableConfig } from '../../../core/human/page-schema.js';
 import type { TuiState } from './types.js';
 export type SelectGroup = 'option' | 'card' | 'row' | 'column';
 export type ActionRow = {
@@ -20,13 +20,13 @@ export type ActionRow = {
     label: string;
 };
 export declare function describeSlot(slot: PageSlot): string;
-/** False when the slot's response cannot be authored here: an unvalidated product kind, or a source-backed cards slot whose cards the terminal never sees. */
+/** False when this component's response cannot be authored here: an unvalidated product kind, or a source-backed cards component whose cards the terminal never sees. */
 export declare function terminalAnswerable(slot: PageSlot): boolean;
 export declare function slotActions(slot: PageSlot): ActionRow[];
 export declare function tableMarkdown(config: TableConfig): string;
-export declare function summarizeSlotResponse(slot: PageSlot, response: SlotResponse | undefined): string;
 export declare function slotAnswered(state: TuiState, slot: PageSlot): boolean;
 export declare function pageComplete(state: Pick<TuiState, 'manifest' | 'responses'>): boolean;
 export declare function commentIdFor(anchor: CommentAnchor): string;
-export declare function anchorLabel(slot: PageSlot, anchor: CommentAnchor): string;
+/** The response-comment anchors this component may author: options take per-option, tables take rows only. */
+export declare function commentAnchors(slot: PageSlot): CommentAnchor[];
 export declare function awaitsResponse(manifest: PageManifest): boolean;

package/dist/clients/inbox/tui/slots.js

@@ -1,6 +1,9 @@
 import { isResponseBearingSlot, validatePageResponses, validatePartialPageResponses } from '../../../core/human/page-schema.js';
 const RESERVED = new Set(['c', 'r', 'e', 'a', 'n', 'p', 'q', 'j', 'k', 'u', 'd', ' ']);
 export function describeSlot(slot) {
+    const label = slot.config.label;
+    if (typeof label === 'string' && label !== '')
+        return label;
     if (slot.unvalidated === true)
         return slot.kind;
     if (slot.kind === 'options')
@@ -8,14 +11,14 @@ export function describeSlot(slot) {
     if (slot.kind === 'text')
         return 'Text';
     if (slot.kind === 'table')
-        return slot.config.caption ?? 'Table';
+        return 'Table';
     if (slot.kind === 'cards')
         return 'Cards';
     if (slot.kind === 'chart')
         return 'Chart';
     return slot.kind;
 }
-/** False when the slot's response cannot be authored here: an unvalidated product kind, or a source-backed cards slot whose cards the terminal never sees. */
+/** False when this component's response cannot be authored here: an unvalidated product kind, or a source-backed cards component whose cards the terminal never sees. */
 export function terminalAnswerable(slot) {
     if (slot.unvalidated === true)
         return false;
@@ -31,15 +34,16 @@ export function slotActions(slot) {
         const config = slot.config;
         rows = config.options.map((option) => ({ kind: 'select', group: 'option', id: option.id, label: option.label, ...(option.description === undefined ? {} : { description: option.description }), mode: config.mode }));
         if (config.allowFreetext === true)
-            rows.push({ kind: 'freetext', label: config.freetextLabel ?? 'Other' });
+            rows.push({ kind: 'freetext', label: config.freetextLabel ?? 'Something else' });
     }
     else if (slot.kind === 'cards') {
         const config = slot.config;
         rows = (config.cards ?? []).map((card) => ({ kind: 'select', group: 'card', id: card.id, label: card.subtitle === undefined ? card.title : `${card.title} — ${card.subtitle}`, ...(card.body === undefined ? {} : { description: card.body }), mode: config.mode }));
     }
     else if (slot.kind === 'text') {
-        if (slot.config.editable === true)
-            rows.push({ kind: 'edit', label: 'Edit' });
+        // Text is always a writing surface — the same contract the page kit presents. Accepting
+        // the draft as written is the other half of that answer, not a separate read-only mode.
+        rows.push({ kind: 'edit', label: 'Edit' });
         rows.push({ kind: 'accept', label: 'Accept as-is' });
     }
     else if (slot.kind === 'table') {
@@ -84,28 +88,6 @@ export function tableMarkdown(config) {
     const divider = `| ${config.columns.map((column) => column.align === 'right' ? '---:' : '---').join(' | ')} |`;
     return [header, divider, ...(config.rows ?? []).map((row) => `| ${config.columns.map((column) => escapeCell(row.cells[column.id], column.mono === true)).join(' | ')} |`)].join('\n');
 }
-export function summarizeSlotResponse(slot, response) {
-    if (response === undefined)
-        return isResponseBearingSlot(slot) ? 'unanswered' : 'display';
-    if (slot.kind === 'options') {
-        const r = response;
-        const labels = slot.config.options.filter((o) => r.selectedOptionIds.includes(o.id)).map((o) => o.label);
-        if ((r.freetext?.trim() ?? '') !== '')
-            labels.push(r.freetext.trim());
-        return labels.join(', ') || (r.comments.length > 0 ? `${r.comments.length} comment${r.comments.length === 1 ? '' : 's'}` : 'answered');
-    }
-    if (slot.kind === 'cards') {
-        const r = response;
-        return slot.config.cards?.filter((c) => r.selectedCardIds.includes(c.id)).map((c) => c.title).join(', ') || 'answered';
-    }
-    if (slot.kind === 'table') {
-        const r = response;
-        return `${r.selectedRowIds.length} row${r.selectedRowIds.length === 1 ? '' : 's'}, ${r.selectedColumnIds.length} column${r.selectedColumnIds.length === 1 ? '' : 's'}`;
-    }
-    if (slot.kind === 'text')
-        return response.edited ? 'edited' : 'accepted';
-    return 'answered';
-}
 export function slotAnswered(state, slot) {
     if (!terminalAnswerable(slot) || slot.id === undefined || !state.responses.has(slot.id))
         return false;
@@ -130,27 +112,20 @@ export function pageComplete(state) {
 }
 export function commentIdFor(anchor) {
     switch (anchor.kind) {
-        case 'whole': return 'whole';
         case 'option': return `option:${anchor.optionId}`;
-        case 'card': return `card:${anchor.cardId}`;
         case 'row': return `row:${anchor.rowId}`;
-        case 'column': return `column:${anchor.columnId}`;
-        case 'range': return `range:${anchor.start}:${anchor.end}`;
     }
 }
-export function anchorLabel(slot, anchor) {
-    if (anchor.kind === 'whole')
-        return describeSlot(slot);
-    if (anchor.kind === 'option')
-        return slot.config.options.find((x) => x.id === anchor.optionId)?.label ?? anchor.optionId;
-    if (anchor.kind === 'card')
-        return slot.config.cards?.find((x) => x.id === anchor.cardId)?.title ?? anchor.cardId;
-    if (anchor.kind === 'row')
-        return slot.config.rows?.find((x) => x.id === anchor.rowId)?.id ?? anchor.rowId;
-    if (anchor.kind === 'column')
-        return slot.config.columns.find((x) => x.id === anchor.columnId)?.label ?? anchor.columnId;
-    return anchor.quote;
+/** The response-comment anchors this component may author: options take per-option, tables take rows only. */
+export function commentAnchors(slot) {
+    if (!terminalAnswerable(slot))
+        return [];
+    if (slot.kind === 'options')
+        return slot.config.options.map((option) => ({ kind: 'option', optionId: option.id }));
+    if (slot.kind === 'table')
+        return (slot.config.rows ?? []).map((row) => ({ kind: 'row', rowId: row.id }));
+    return [];
 }
 export function awaitsResponse(manifest) {
-    return manifest.slots.some(isResponseBearingSlot);
+    return manifest.delivery.reply;
 }

package/dist/clients/inbox/tui/types.d.ts

@@ -1,12 +1,12 @@
 import type { Key } from './keys.js';
+import type { ProductPageComponents } from '../../../types.js';
 import type { CommentAnchor, PageManifest, PageResponses, PageSlot, SlotResponse } from '../../../core/human/page-schema.js';
-import type { PageSourceProjection } from '../../../core/human/page.js';
 export type Phase = 'overview' | 'item-review' | 'final';
 export type InputMode = null | {
     kind: 'comment';
     buffer: string;
     cursor: number;
-    anchor?: CommentAnchor;
+    anchor: CommentAnchor;
 } | {
     kind: 'freetext';
     buffer: string;
@@ -21,11 +21,8 @@ export interface TuiState {
     currentIndex: number;
     manifest: PageManifest;
     slots: PageSlot[];
-    overviewProse: string[];
-    slotProse: Map<number, string[]>;
-    finalProse: string[];
     responses: Map<string, SlotResponse>;
-    productKinds: string[];
+    productKinds: ProductPageComponents;
     inputMode: InputMode;
     selectedAction: number;
     bodyMode: 'question';
@@ -42,8 +39,7 @@ export interface TuiState {
 }
 export interface MountedPanelOpts {
     manifest: PageManifest;
-    projection: PageSourceProjection;
-    productKinds?: string[];
+    productKinds?: ProductPageComponents;
     initialResponses?: PageResponses | null;
     cols: number;
     rows: number;
@@ -58,9 +54,9 @@ export interface MountedPanel {
     render(): string[];
     handleResize(cols: number, rows: number): string[];
     unmount(): void;
-    loadPage(manifest: PageManifest, projection: PageSourceProjection, opts?: {
+    loadPage(manifest: PageManifest, opts?: {
         initialResponses?: PageResponses | null;
-        productKinds?: string[];
+        productKinds?: ProductPageComponents;
     }): void;
     canAcceptHostKeys(): boolean;
     atPageTop(): boolean;

package/dist/clients/inbox/tui.js

@@ -36,12 +36,12 @@ export function buildInboxLines(items, width, selectedIndex, height = Number.MAX
 }
 function buildItemLines(item, index, selectedIndex, contentWidth) {
     const kind = item.kind === 'page'
-        ? item.awaitsResponse === false ? 'display' : item.dialect === 'html' ? 'rich' : 'interactive'
+        ? item.awaitsResponse === false ? 'display' : 'rich'
         : item.kind;
     const icon = KIND_ICON[kind] ?? '·';
     // The inbox is a title-first triage surface. Origin details remain available
     // after opening a ticket, rather than consuming the list's scarce row width.
-    const age = formatTimeAgo(item.blockedSince);
+    const age = formatTimeAgo(item.kind === 'page' ? item.emittedAt : item.blockedSince);
     const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
     const titleWidth = Math.max(1, contentWidth - age.length - 6);
     const row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} ${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;

package/dist/commands/__tests__/human.test.js

@@ -1,16 +1,24 @@
-// Regression: a caller passing BOTH a positional AND piped stdin (e.g.
-// `crtr node new --kind x "title" < prompt.md`, or `crtr human ask -
-// <<EOF`) used to have the positional silently win, with the entire piped
-// body dropped on the floor. `-` must always mean "read stdin", and any
-// OTHER positional alongside genuinely piped, non-empty stdin must error
-// loudly rather than silently pick one.
-//
 // Run with: node --import tsx/esm --test 'src/commands/__tests__/human.test.ts'
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { Readable } from 'node:stream';
 import { parseArgv } from '../../core/command.js';
-import { humanAsk } from '../human/prompts.js';
+import { renderLeafArgv } from '../../core/help.js';
+import { componentDoc, renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
+import { humanComponents } from '../human/components.js';
+import { humanSend } from '../human/prompts.js';
+import { registerHuman } from '../human.js';
+import { pageHelpText } from '../human/shared.js';
+const nlThreadRegistration = {
+    kind: 'nl-thread',
+    description: 'message conversation with participants and metadata',
+    useWhen: 'use when the human needs to read a conversation - an email chain, a LinkedIn DM, an iMessage exchange - in message order, usually above whatever the page asks them to decide',
+    display: true,
+    doc: '`nl-thread` renders a conversation as bubbles down one column. Display only: it contributes nothing to the response.',
+};
 async function withPipedStdin(body, fn) {
     const original = process.stdin;
     const stdin = Readable.from([Buffer.from(body)]);
@@ -23,25 +31,111 @@ async function withPipedStdin(body, fn) {
         Object.defineProperty(process, 'stdin', { value: original, configurable: true });
     }
 }
-describe('human ask: positional vs piped stdin', () => {
-    test('`-` positional reads stdin instead of taking the literal value', async () => {
-        const body = 'Should we ship today?\nmulti-line brief\n';
-        const result = await withPipedStdin(body, () => parseArgv(humanAsk.help.params ?? [], ['-']));
-        assert.equal(result['question'], body);
-    });
-    test('positional + piped non-empty stdin → loud bad_invocation naming both sources', async () => {
-        await assert.rejects(() => withPipedStdin('piped body', () => parseArgv(humanAsk.help.params ?? [], ['Should we ship today?'])), (err) => {
+function withPageSurface(pageSurface, run) {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-human-help-'));
+    const originalHome = process.env['HOME'];
+    process.env['HOME'] = home;
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    writeFileSync(join(home, '.crouter', 'config.json'), JSON.stringify({ page_surface: pageSurface }));
+    try {
+        return run();
+    }
+    finally {
+        if (originalHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = originalHome;
+        rmSync(home, { recursive: true, force: true });
+    }
+}
+describe('human page input', () => {
+    test('stdin supplies the authored page document', async () => {
+        const document = 'export default () => <Page title="Question" />;\n';
+        const result = await withPipedStdin(document, () => parseArgv(humanSend.help.params ?? [], []));
+        assert.equal(result['document'], document);
+    });
+    test('empty stdin remains empty alongside --page', async () => {
+        const result = await withPipedStdin('', () => parseArgv(humanSend.help.params ?? [], ['--page', 'page.tsx']));
+        assert.equal(result['page'], 'page.tsx');
+        assert.equal(result['document'], '');
+    });
+    test('a positional document is rejected', async () => {
+        await assert.rejects(() => parseArgv(humanSend.help.params ?? [], ['page.tsx']), (err) => {
             assert.equal(err.code, 'bad_invocation');
-            assert.match(err.message, /positional/);
-            assert.match(err.message, /stdin/);
-            assert.match(err.message, /Should we ship today\?/);
-            assert.equal(err.details?.field, 'question');
-            assert.match(err.details?.next ?? '', /exactly one/);
+            assert.match(err.message, /takes no positional arguments/);
+            assert.match(err.details?.next ?? '', /schema/);
             return true;
         });
     });
-    test('positional with empty piped stdin (no TTY, no bytes) still uses the positional', async () => {
-        const result = await withPipedStdin('', () => parseArgv(humanAsk.help.params ?? [], ['Should we ship today?']));
-        assert.equal(result['question'], 'Should we ship today?');
+    test('send help keeps page authoring at the human branch and makes reply routing explicit', () => {
+        const rendered = renderLeafArgv(humanSend.help);
+        assert.match(rendered, /^human send: send a durable TSX or HTML page\./);
+        assert.match(rendered, /Page authoring: `crtr human -h`\./);
+        assert.doesNotMatch(rendered, /--no-reply|--reply/);
+        assert.match(rendered, /page_id/);
+        assert.match(rendered, /reply/);
+        assert.doesNotMatch(rendered, /human notify|run\.json|job_id/);
+    });
+});
+test('human help carries the page authoring model and follows the page-surface setting', () => {
+    withPageSurface(false, () => {
+        const human = registerHuman();
+        const help = pageHelpText(false);
+        assert.equal(human.rootEntry?.useWhen, help.rootUseWhen);
+        assert.ok(human.help.model?.includes(help.authoring));
+        assert.ok(human.help.model?.includes('`crtr human components`'));
+        assert.doesNotMatch(human.help.model ?? '', /doc check/);
+        assert.match(human.help.model ?? '', /\.html/);
+    });
+    withPageSurface(true, () => {
+        const human = registerHuman();
+        const help = pageHelpText(true);
+        assert.notEqual(help.authoring, pageHelpText(false).authoring);
+        assert.equal(human.rootEntry?.useWhen, help.rootUseWhen);
+        assert.ok(human.help.model?.includes(help.authoring));
+    });
+});
+// The gate itself, not its prose: a page-surface host must not carry the two
+// terminal-only surfaces, because a review ticket filed there reaches a person
+// who has no editor to open it in.
+test('page_surface removes the terminal-only human surfaces from the tree', () => {
+    const names = () => registerHuman().children.map((child) => child.name);
+    withPageSurface(false, () => {
+        assert.deepEqual(names(), ['components', 'send', 'review', 'feedback', 'show', 'cancel', 'list', 'resolve']);
+    });
+    withPageSurface(true, () => {
+        const children = names();
+        assert.deepEqual(children, ['components', 'send', 'feedback', 'cancel', 'list', 'resolve']);
+        const human = registerHuman();
+        assert.doesNotMatch(human.help.model ?? '', /`review`|`show`/);
+        assert.doesNotMatch(human.rootEntry?.useWhen ?? '', /review a document|live display/);
+    });
+});
+test('human components catalog and contracts teach product registrations', () => {
+    const legacyRegistration = { kind: 'product-card' };
+    const catalog = renderComponentCatalog([nlThreadRegistration, legacyRegistration]);
+    assert.match(catalog, /^<components count="\d+">\nStructural — /);
+    assert.match(catalog, /\n`Page` — /);
+    assert.match(catalog, /\n`NlThread` \(kind `nl-thread`\) — message conversation with participants and metadata\. Use when the human needs to read a conversation - an email chain, a LinkedIn DM, an iMessage exchange - in message order, usually above whatever the page asks them to decide\. Display-only\n/);
+    assert.match(catalog, /\n`ProductCard` \(kind `product-card`\) — product-registered\n<\/components>$/);
+    assert.doesNotMatch(catalog, /Props\n|Response rules/);
+    // A product component is addressed by the JSX tag page-catalog derives from its registered
+    // kind; the contract heading names the wire kind that tag maps to.
+    assert.equal(renderComponentContract('nl-thread', [nlThreadRegistration]), `\`<NlThread>\` — product-registered, wire kind \`nl-thread\`\n\n${nlThreadRegistration.doc}`);
+    assert.equal(renderComponentContract('ProductCard', [legacyRegistration]), "`<ProductCard>` — product-registered, wire kind `product-card`\n\nproduct-registered; config is passed through unvalidated (unvalidated: true) — see the product's own docs");
+});
+test('human components show resolves every registry name, families included', async () => {
+    const show = humanComponents.children.find((child) => child.name === 'show');
+    assert.ok(show !== undefined && show.kind === 'leaf');
+    const question = await show.run({ component: 'UserQuestion' });
+    assert.ok(question !== undefined);
+    assert.equal(question['contract'], componentDoc('UserQuestion')?.contract);
+    assert.match(String(question['contract']), /wire kind `options`/);
+    // A shadcn family member resolves to the family contract that documents it.
+    const cardHeader = await show.run({ component: 'CardHeader' });
+    assert.equal(cardHeader?.['contract'], componentDoc('Card')?.contract);
+    await assert.rejects(() => show.run({ component: 'crtr-options' }), (err) => {
+        assert.equal(err.code, 'unknown_component');
+        return true;
     });
 });

package/dist/commands/__tests__/node-message.test.js

@@ -0,0 +1,14 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { renderLeafArgv } from '../../core/help.js';
+import { nodeMessage } from '../node/message.js';
+test('node message send help documents the finalized-node re-task gate', () => {
+    const send = nodeMessage.children.find((child) => child.kind === 'leaf' && child.name === 'send');
+    if (send === undefined || send.kind !== 'leaf')
+        assert.fail('node message send leaf is missing');
+    const rendered = renderLeafArgv(send.help);
+    assert.match(rendered, /--reopen/);
+    assert.match(rendered, /Required to re-task a finalized target/);
+    assert.match(rendered, /clears a finalized target's finalization latch before delivery/);
+    assert.match(rendered, /Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted/);
+});

package/dist/commands/attention.js

@@ -1,6 +1,6 @@
 // `crtr canvas attention` — aggregate pending human tickets across the canvas.
 //
-// A pending "ticket" is any humanloop interaction awaiting a human: a page or
+// A pending "ticket" is any humanloop interaction awaiting the user: a page or
 // an anchored review. Each lives in its human bridge node
 // directory and is attributed through that bridge's parent relation. This
 // subtree surfaces a direct node projection; cwd is display metadata only.
@@ -93,7 +93,7 @@ const attentionCount = defineLeaf({
 const attentionList = defineLeaf({
     name: 'list',
     description: 'itemised list of cwds with pending human tickets',
-    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending tickets (asks, reviews, notifications), oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.',
+    whenToUse: 'finding which agents are blocked waiting on the user — an itemised list of the cwds with pending tickets (asks, reviews, notifications), oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.',
     help: {
         name: 'canvas attention list',
         summary: 'list nodes that asked pending human tickets',
@@ -213,11 +213,11 @@ const attentionMap = defineLeaf({
 export const attentionBranch = defineBranch({
     name: 'attention',
     description: 'count/list pending human tickets across the graph',
-    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending tickets (asks, reviews, notifications) or list the cwds that have them. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on the user, and where: count the pending tickets (asks, reviews, notifications) or list the cwds that have them. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
     help: {
         name: 'canvas attention',
         summary: 'aggregate pending human tickets across the canvas',
-        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised asking-node entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide. A ticket is any humanloop interaction awaiting a human: an ask, a review, or a notification.',
+        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised asking-node entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide. A ticket is any humanloop interaction awaiting the user: an ask, a review, or a notification.',
     },
     children: [attentionCount, attentionList, attentionMap],
 });