@north-light/crouter 0.3.198 → 0.3.199

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

@@ -2,17 +2,12 @@ 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 { renderHtmlProseAsMarkdown } from '../../../core/human/html-markdown.js';
-import { describeSlot, pageComplete, slotActions, slotAnswered, 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, dialect) {
-    const rendered = blocks.map((block) => dialect === 'html' ? renderHtmlProseAsMarkdown(block) : block).filter((block) => block.trim() !== '');
-    return rendered.flatMap((block, index) => [...(index > 0 ? [''] : []), ...mdLines(block, maxW, paneW)]);
-}
 function pageAnswer(state) {
-    return describePageAnswer(state.manifest, Object.fromEntries(state.responses), { completedAt: '', productKinds: state.productKinds });
+    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);
@@ -36,10 +31,11 @@ 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}`, '');
-    for (const line of proseLines(state.overviewProse, maxW, Math.max(20, cols - 4), state.manifest.dialect))
-        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++) {
@@ -57,18 +53,64 @@ export function renderOverview(state, cols, rows) {
         if (response !== undefined)
             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];
@@ -129,10 +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) ?? [];
-    for (const line of proseLines(prose, maxW, paneW, state.manifest.dialect))
-        lines.push(`  ${line}`);
+    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') {
@@ -157,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 ${commentLabel(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}`);
@@ -171,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';
@@ -179,10 +224,11 @@ function itemLines(state, cols) {
             }
         });
         for (const comment of responseComments(state, slot))
-            lines.push(`  ${DIM}attached: ${commentLabel(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)) };
@@ -221,8 +267,6 @@ export function renderFinal(state, cols, rows) {
         const mark = answered ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
         lines.push(`  ${mark} ${BOLD}${sanitize(manifestSlot === undefined ? slot.kind : describeSlot(manifestSlot))}${RESET}  ${DIM}${sanitize(answerSummary(slot))}${RESET}`);
     }
-    for (const line of proseLines(state.finalProse, maxW, Math.max(20, cols - 4), state.manifest.dialect))
-        lines.push(`  ${line}`);
     const complete = pageComplete(state);
     if (!complete) {
         lines.push('', `  ${YELLOW}Cannot submit yet.${RESET}`);

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

@@ -20,11 +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 slotAnswered(state: TuiState, slot: PageSlot): boolean;
 export declare function pageComplete(state: Pick<TuiState, 'manifest' | 'responses'>): boolean;
 export declare function commentIdFor(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

@@ -18,7 +18,7 @@ export function describeSlot(slot) {
         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;
@@ -34,18 +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') {
-        const config = slot.config;
-        // Text is a writing surface unless the author explicitly made it review-only, and a
-        // one-line field is an input by definition — the same contract the page kit presents.
-        if (config.singleLine === true || config.editable !== false)
-            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') {
@@ -114,14 +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}`;
     }
 }
+/** 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,13 +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;
@@ -22,9 +21,6 @@ export interface TuiState {
     currentIndex: number;
     manifest: PageManifest;
     slots: PageSlot[];
-    overviewProse: string[];
-    slotProse: Map<number, string[]>;
-    finalProse: string[];
     responses: Map<string, SlotResponse>;
     productKinds: ProductPageComponents;
     inputMode: InputMode;
@@ -43,7 +39,6 @@ export interface TuiState {
 }
 export interface MountedPanelOpts {
     manifest: PageManifest;
-    projection: PageSourceProjection;
     productKinds?: ProductPageComponents;
     initialResponses?: PageResponses | null;
     cols: number;
@@ -59,7 +54,7 @@ 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?: ProductPageComponents;
     }): void;

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

@@ -7,9 +7,9 @@ import { join } from 'node:path';
 import { Readable } from 'node:stream';
 import { parseArgv } from '../../core/command.js';
 import { renderLeafArgv } from '../../core/help.js';
-import { renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
-import { humanHtml } from '../human/html.js';
-import { humanAsk, humanNotify } from '../human/prompts.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 = {
@@ -17,62 +17,7 @@ const nlThreadRegistration = {
     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: your own messages on the right in the accent, the other party on the left, consecutive messages from one sender grouped under a single avatar.',
-        '',
-        'Display only: it contributes nothing to the response, stays readable and expandable on a resolved page, and does not require a slot `id`.',
-        '',
-        '## Config',
-        '',
-        '| field | type | required | meaning |',
-        '| --- | --- | --- | --- |',
-        '| `label` | string | no | the heading above the thread - what this conversation is, in your own words |',
-        '| `platform` | string | no | where it happened (`email`, `linkedin`, `imessage`, `slack`); shown as a small chip |',
-        '| `messages` | message[] | no | the conversation, oldest first; an empty or absent list renders "No messages in this thread." |',
-        '| `participants` | participant[] | no | display identities, joined to messages by handle |',
-        '| `collapsedByDefault` | boolean | no | open on the last 3 messages, the rest behind a "Show N earlier messages" control |',
-        '',
-        'Unknown config properties are rejected: the slot then renders an unavailable notice naming the offending key.',
-        '',
-        '### message',
-        '',
-        '| field | type | required | meaning |',
-        '| --- | --- | --- | --- |',
-        '| `sender` | string | yes | `self` is the viewer, `them` the unnamed other party; any other value is a named sender |',
-        '| `body` | string | yes | plain text; authored newlines are preserved, markdown is NOT rendered |',
-        '| `senderName` | string | no | display name for this message, winning over the participant roster |',
-        '| `senderHandle` | string | no | the raw address - phone, email, profile id - joined against `participants` |',
-        '| `timestamp` | string | no | ISO 8601; a clock within today, date + time before that. Anything unparseable is shown verbatim |',
-        '',
-        '### participant',
-        '',
-        '| field | type | required | meaning |',
-        '| --- | --- | --- | --- |',
-        '| `handle` | string | yes | matches the `senderHandle` on a message |',
-        '| `name` | string | no | display name for every message from that handle |',
-        '| `avatarDataUrl` | string | no | a `data:image/...` URL ONLY. A page never fetches, so an http(s) avatar is rejected - omit it and initials are drawn instead |',
-        '',
-        'There is no `source` field and no artifact reference: messages are always inline in the config.',
-        '',
-        '## Example',
-        '',
-        '```html',
-        '<crtr-slot kind="nl-thread" slot-id="conversation">',
-        '  <script type="application/json">',
-        '  {',
-        '    "label": "Your thread with Dana Whitfield",',
-        '    "platform": "linkedin",',
-        '    "collapsedByDefault": true,',
-        '    "participants": [{ "handle": "dana-whitfield", "name": "Dana Whitfield" }],',
-        '    "messages": [',
-        '      { "sender": "them", "senderHandle": "dana-whitfield", "timestamp": "2026-03-02T15:04:00Z", "body": "Saw the launch, congrats." },',
-        '      { "sender": "self", "timestamp": "2026-03-02T16:20:00Z", "body": "Thank you! Want a walkthrough next week?" }',
-        '    ]',
-        '  }',
-        '  </script>',
-        '</crtr-slot>',
-        '```',
-    ].join('\n'),
+    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;
@@ -86,12 +31,12 @@ async function withPipedStdin(body, fn) {
         Object.defineProperty(process, 'stdin', { value: original, configurable: true });
     }
 }
-function withHtmlSurface(htmlSurface, run) {
+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({ html_surface: htmlSurface }));
+    writeFileSync(join(home, '.crouter', 'config.json'), JSON.stringify({ page_surface: pageSurface }));
     try {
         return run();
     }
@@ -105,80 +50,92 @@ function withHtmlSurface(htmlSurface, run) {
 }
 describe('human page input', () => {
     test('stdin supplies the authored page document', async () => {
-        const document = '<!doctype html><html><head><meta name="crtr-page-title" content="Question"></head><body></body></html>';
-        const result = await withPipedStdin(document, () => parseArgv(humanAsk.help.params ?? [], []));
+        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(humanAsk.help.params ?? [], ['--page', 'page.html']));
-        assert.equal(result['page'], 'page.html');
+        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(humanAsk.help.params ?? [], ['page.html']), (err) => {
+        await assert.rejects(() => parseArgv(humanSend.help.params ?? [], ['page.tsx']), (err) => {
             assert.equal(err.code, 'bad_invocation');
             assert.match(err.message, /takes no positional arguments/);
             assert.match(err.details?.next ?? '', /schema/);
             return true;
         });
     });
-    test('ask and notify help keep page authoring at the human branch', () => {
-        const expected = (name, summary, output, effects) => `human ${name}: ${summary}.\n\nPage authoring: \`crtr human -h\`.\n\nInput\n  stdin        optional. Page bytes from stdin. Provide exactly one of stdin or --page PATH.\n  --page PAGE  path, optional. Write the page to \`$CRTR_CONTEXT_DIR/pages/<name>.html\`; pass that path. Provide exactly one of --page or stdin.\n\nOutput (fields carried in the rendered result)\n${output}\n\nEffects\n${effects}`;
-        assert.equal(renderLeafArgv(humanAsk.help), expected('ask', "submit a decision ticket to crouter's inbox; returns a job handle immediately", '  job_id     string. Node id of this human interaction. Its answer is pushed to your inbox when the human responds.\n  dir        string. Interaction directory holding page.html, page.json, run.json, and response.json.\n  follow_up  string. A non-blocking status peek; the answer arrives via your inbox.', '  Creates a kind:"human" node under you and enqueues a page in the human inbox.\n  Returns immediately; nothing opens on screen. The human answers from their inbox on their own time.'));
-        assert.equal(renderLeafArgv(humanNotify.help), expected('notify', 'enqueue a fire-and-forget acknowledgement in the human inbox; creates no job', '  queued  boolean. Always true — the notify page is durable inbox state the human acknowledges from the inbox.\n  dir     string. Interaction directory holding page.html, page.json, and run.json.', '  Enqueues a durable display page in the human inbox. Creates no node; nothing opens on screen.'));
+    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 pins HTML prompting to the html_surface setting', () => {
-    const originalAuthoring = 'Write one complete HTML document to `$CRTR_CONTEXT_DIR/pages/<name>.html`. Its `<head>` has required `<meta name="crtr-page-title" content="…">`, optional `<meta name="crtr-page-subtitle" content="…">`, and optional `<meta name="crtr-page-placement" content="inline|panel">` (default `panel`); interactive or multi-step pages need one `<crtr-pages>` wrapper with `<crtr-page>` steps, and each component config is its first `<script type="application/json">` child. Display-only pages are first-class: a page with no questions is a legitimate, encouraged way to show structured UI with `notify --page`.';
-    const originalRootUseWhen = 'when a person must decide, review a document with you, or receive a live display.';
-    const htmlAuthoring = 'Use inline HTML pages as the default way to put structured or interactive content in front of the human; the environment renders web content, so a page is not a special occasion. Write one complete HTML document to `$CRTR_CONTEXT_DIR/pages/<name>.html`. Its `<head>` has required `<meta name="crtr-page-title" content="…">`, optional `<meta name="crtr-page-subtitle" content="…">`, and optional `<meta name="crtr-page-placement" content="inline|panel">` (default `panel`); interactive or multi-step pages need one `<crtr-pages>` wrapper with `<crtr-page>` steps, and each component config is its first `<script type="application/json">` child. Display-only pages are first-class: a page with no questions is a legitimate, encouraged way to show structured UI with `notify --page`.';
-    const htmlRootUseWhen = 'when a person must decide, review a document with you, or receive a live display; use inline HTML pages by default for structured or interactive content because the environment renders web content.';
-    withHtmlSurface(false, () => {
+test('human help carries the page authoring model and follows the page-surface setting', () => {
+    withPageSurface(false, () => {
         const human = registerHuman();
-        assert.equal(pageHelpText(false).authoring, originalAuthoring);
-        assert.equal(human.rootEntry?.useWhen, originalRootUseWhen);
-        assert.ok(human.help.model?.includes(originalAuthoring));
+        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/);
     });
-    withHtmlSurface(true, () => {
+    withPageSurface(true, () => {
         const human = registerHuman();
-        assert.equal(pageHelpText(true).authoring, htmlAuthoring);
-        assert.equal(human.rootEntry?.useWhen, htmlRootUseWhen);
-        assert.ok(human.help.model?.includes(htmlAuthoring));
+        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));
     });
 });
-test('human html catalog and contracts teach product registrations', () => {
+// 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="9">\n`<crtr-pages>`/);
-    assert.match(catalog, /\n`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`product-card`\nproduct-registered\n<\/components>$/);
-    assert.doesNotMatch(catalog, /Config JSON|Response rules/);
-    assert.equal(renderComponentContract('nl-thread', [nlThreadRegistration]), `\`nl-thread\`\n\n${nlThreadRegistration.doc}`);
-    assert.equal(renderComponentContract('product-card', [legacyRegistration]), "`product-card`\n\nproduct-registered; config is passed through unvalidated (unvalidated: true) — see the product's own docs");
+    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 html show options output is byte-stable', async () => {
-    const show = humanHtml.children.find((child) => child.name === 'show');
+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 result = await show.run({ kind: 'options' });
-    assert.ok(result !== undefined);
-    assert.equal(show.render?.(result), `\`<crtr-options>\`
-
-Response-bearing. The response is \`{selectedOptionIds:string[], comments:Comment[], freetext?:string}\`.
-
-Element contract
-- Put the JSON config in the first direct \`<script type="application/json">\` child of the component element. It must contain one JSON object.
-- \`id\` must match \`^[A-Za-z0-9_-]{1,64}$\`, be unique across the page when present, and is required only for response-bearing components. Display-only components do not need an id.
-- When a page has two or more response-bearing components, every one needs a nonempty \`config.label\`.
-- Config objects and every documented nested object reject unknown fields.
-
-Config JSON
-- \`options\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string}\`.
-- \`mode\` — required: \`single\` or \`multi\`.
-- \`label?:string\` — slot label; required by the multi-response page rule.
-- \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` — optional free-text affordance fields.
-
-Response rules
-- \`selectedOptionIds\` contains unique known option ids. A \`single\` response has at most one selected id and requires exactly one selection or nonempty allowed \`freetext\`; a \`multi\` response requires a selection, comment, or nonempty allowed \`freetext\`.
-- \`freetext\` is accepted only when \`allowFreetext:true\`.
-- Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\`. Every response carries \`comments\` as an array. \`Anchor\` is one of \`{kind:"whole"}\`, \`{kind:"option",optionId:string}\`, \`{kind:"row",rowId:string}\`, \`{kind:"column",columnId:string}\`, \`{kind:"card",cardId:string}\`, or \`{kind:"range",start:nonnegative integer,end:nonnegative integer >= start,quote:string}\`; each component accepts only the anchors named below. Options accept only \`whole\` and \`option\` anchors; \`optionId\` must name a configured option.`);
+    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],
 });

package/dist/commands/canvas-snapshot.js

@@ -15,7 +15,7 @@ export const canvasSnapshotLeaf = defineLeaf({
             { name: 'subscriptions', type: 'object', required: true, constraint: 'Authoritative subscribes_to adjacency map: each node id maps to its publisher/child node ids in edge order.' },
         ],
         outputKind: 'object',
-        effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and human ask counts.'],
+        effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and pending human-reply counts.'],
         // Machine-readable dump for the browser canvas, not for an agent/human to
         // glance at — collapse it in the attach viewer by default.
         preview: { suppressOutput: true },

package/dist/commands/canvas.js

@@ -43,7 +43,7 @@ export function registerCanvas() {
         help: {
             name: 'canvas',
             summary: 'observe and supervise the whole agent graph',
-            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches remote-capable read commands such as `node inspect` onto a configured target or back to local.',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending replies from the user across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches remote-capable read commands such as `node inspect` onto a configured target or back to local.',
         },
         children: [dashboardLeaf, canvasSnapshotLeaf, canvasRosterLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf, canvasConfigBranch, canvasUseLeaf],
     });