@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/config.js

@@ -1,6 +1,6 @@
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
 import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
 import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
@@ -10,7 +10,7 @@ import { profileRoot } from './profiles/manifest.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
-import { normalizePageComponents } from './human/page-catalog.js';
+import { mergePageComponentLayers, normalizePageComponents } from './human/page-catalog.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -266,6 +266,101 @@ function mergeSpawnEnv(raw, base = []) {
     }
     return { allow: [...new Set([...base, ...extra])] };
 }
+/** The one bare-command-name rule, shared by the read path (`normalizeBin`)
+ *  and the strict install gate (`invalidPluginBinReasons`): a name a shell can
+ *  invoke verbatim and a filesystem can hold as a single symlink entry — no
+ *  separator, no leading dot, no whitespace, no quoting ever required. */
+const BIN_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Bare names crouter owns on every node's PATH. A contribution may not take
+ *  one: shadowing the CLI a node drives its own canvas with breaks the runtime
+ *  contract rather than extending it. */
+const RESERVED_BIN_NAMES = new Set(['crtr', 'crtrd']);
+/** The one bare-command-name validator shared by `bin` and plugin `requires`.
+ *  `bin` alone reserves crouter's own commands; a plugin may require any safe
+ *  executable name because it does not contribute or shadow that command. */
+function bareCommandNameIssue(name, field) {
+    if (field === 'bin' && RESERVED_BIN_NAMES.has(name))
+        return `${field}.${name} is reserved by crouter — pick another bare command name`;
+    if (!BIN_NAME_PATTERN.test(name))
+        return `${field}.${name} is not a safe bare command name (expected ${BIN_NAME_PATTERN.source})`;
+    return undefined;
+}
+/** Validate raw `bin` declaration shape without touching the filesystem.
+ *  Install uses these findings as a hard gate for plugin manifests; scope
+ *  resolution reports them through `crtr sys doctor` and continues. */
+export function binDeclarationIssues(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{ name: 'bin', message: 'bin must be a JSON object mapping bare command name to a relative path' }];
+    }
+    const issues = [];
+    for (const [name, target] of Object.entries(raw)) {
+        const nameIssue = bareCommandNameIssue(name, 'bin');
+        if (nameIssue !== undefined)
+            issues.push({ name, message: nameIssue });
+        if (typeof target !== 'string' || target.trim() === '') {
+            issues.push({ name, message: `bin.${name} must be a non-empty relative path to an executable inside the contributor root` });
+        }
+    }
+    return issues;
+}
+/** Normalize one raw `bin` block (a scope `config.json`'s or a plugin
+ *  manifest's) to name → root-relative path. Invalid entries never become
+ *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
+export function normalizeBin(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, target] of Object.entries(raw)) {
+        if (bareCommandNameIssue(name, 'bin') !== undefined)
+            continue;
+        if (typeof target !== 'string' || target.trim() === '')
+            continue;
+        out[name] = target;
+    }
+    return out;
+}
+/** STRICT install-time validation for a plugin-declared `bin` block. Target
+ *  filesystem state is checked later by Doctor because it can change after
+ *  install. */
+export function invalidPluginBinReasons(raw) {
+    return binDeclarationIssues(raw).map((issue) => issue.message);
+}
+/** Normalize a plugin manifest's advisory executable requirements. Invalid
+ *  declarations stay out of the read path; source installs reject them through
+ *  `invalidPluginRequiresReasons`. */
+export function normalizeRequires(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, hint] of Object.entries(raw)) {
+        if (bareCommandNameIssue(name, 'requires') !== undefined)
+            continue;
+        if (typeof hint !== 'string' || hint.trim() === '' || /[\r\n]/.test(hint))
+            continue;
+        out[name] = hint;
+    }
+    return out;
+}
+/** STRICT install-time validation for a plugin's advisory `requires` block.
+ *  A missing executable is advisory; only malformed declarations fail install. */
+export function invalidPluginRequiresReasons(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['requires must be a JSON object mapping a bare executable name to a one-line install hint'];
+    }
+    const reasons = [];
+    for (const [name, hint] of Object.entries(raw)) {
+        const nameIssue = bareCommandNameIssue(name, 'requires');
+        if (nameIssue !== undefined)
+            reasons.push(nameIssue);
+        if (typeof hint !== 'string' || hint.trim() === '') {
+            reasons.push(`requires.${name} must be a non-empty one-line install hint`);
+        }
+        else if (/[\r\n]/.test(hint)) {
+            reasons.push(`requires.${name} must be a one-line install hint`);
+        }
+    }
+    return reasons;
+}
 /** Collect the valid `KindConfig` fields of one raw `kinds.<name>` entry —
  *  every field is optional here, `whenToUse` included; mistyped fields are
  *  dropped, never thrown (an invalid field in config.json must not break
@@ -341,6 +436,40 @@ function layerPluginKinds(scope, scopeRootPath, base) {
         out = mergeKinds(plugin.manifest.kinds, out);
     return out;
 }
+/** The ACTIVE page-component catalog every authoring, validation, daemon,
+ *  inbox, and TUI consumer resolves: the user scope's own `page_components`
+ *  entries plus the contributions of every ENABLED plugin installed under that
+ *  same root, plugin name-sorted for determinism (directory listing order is
+ *  filesystem-dependent). Installing, updating, or removing a plugin therefore
+ *  adds, changes, or retires its components with no config edit.
+ *
+ *  User scope only, deliberately: this catalog is read from the daemon, the
+ *  CLI, and the inbox TUI, whose ambient cwds differ, and a page slot whose
+ *  validity depended on which directory a process happened to start in would
+ *  validate in one surface and fail in another. `page_components` has always
+ *  been a user-scope block (`readConfig('user')`); its plugin channel keeps
+ *  that boundary.
+ *
+ *  Throws on a duplicate kind or derived JSX tag across sources, and on a
+ *  plugin whose block is malformed — matching the existing catalog validation
+ *  style, where a bad `page_components` block already fails config read rather
+ *  than silently dropping a component the product expects to be authorable.
+ *  Install-time validation (`invalidPageComponentsReasons`) is what keeps a
+ *  malformed block from ever reaching this path. */
+export function resolvePageComponents() {
+    const layers = [{ origin: 'config.json', components: readConfig('user').page_components }];
+    const root = scopeRoot('user');
+    if (root !== null) {
+        const plugins = listInstalledPluginsInRoot('user', root)
+            .filter((plugin) => plugin.enabled && plugin.manifest.page_components !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const plugin of plugins) {
+            const label = `plugin "${plugin.name}" page_components`;
+            layers.push({ origin: `plugin "${plugin.name}"`, components: normalizePageComponents(plugin.manifest.page_components, label) });
+        }
+    }
+    return mergePageComponentLayers(layers);
+}
 const KIND_CONFIG_KEYS = new Set(['whenToUse', 'model', 'orchestratorModel', 'tools', 'extensions', 'availableTo']);
 /** STRICT install-time validation for a plugin-declared `kinds` block —
  *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
@@ -479,9 +608,12 @@ function mergeConfig(partial) {
         ? [...defaults.working_gerunds]
         : normalizeWorkingGerunds(partial.working_gerunds);
     const whip_mode = typeof partial.whip_mode === 'boolean' ? partial.whip_mode : defaults.whip_mode;
-    const html_pages = typeof partial.html_pages === 'boolean' ? partial.html_pages : defaults.html_pages;
     const page_components = normalizePageComponents(partial.page_components);
+    const page_surface = typeof partial.page_surface === 'boolean' ? partial.page_surface : defaults.page_surface;
     const whip_messages = normalizeWhipMessages(partial.whip_messages);
+    const whip_message_mode = WHIP_MESSAGE_MODES.includes(partial.whip_message_mode)
+        ? partial.whip_message_mode
+        : defaults.whip_message_mode;
     const mouse_mode_default = MOUSE_MODE_DEFAULTS.includes(partial.mouse_mode_default)
         ? partial.mouse_mode_default
         : defaults.mouse_mode_default;
@@ -489,6 +621,7 @@ function mergeConfig(partial) {
     const condensed_history = CONDENSED_HISTORY_MODES.includes(partial.condensed_history)
         ? partial.condensed_history
         : defaults.condensed_history;
+    const bash_tool_purpose = typeof partial.bash_tool_purpose === 'boolean' ? partial.bash_tool_purpose : defaults.bash_tool_purpose;
     const fold_finished_tools = typeof partial.fold_finished_tools === 'boolean' ? partial.fold_finished_tools : defaults.fold_finished_tools;
     const summarize_tool_calls = typeof partial.summarize_tool_calls === 'boolean' ? partial.summarize_tool_calls : defaults.summarize_tool_calls;
     const detailed_tool_recaps = typeof partial.detailed_tool_recaps === 'boolean' ? partial.detailed_tool_recaps : defaults.detailed_tool_recaps;
@@ -500,7 +633,8 @@ function mergeConfig(partial) {
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, html_pages, page_components, whip_messages, mouse_mode_default, live_cycles, condensed_history, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    const bin = normalizeBin(partial.bin);
+    return { bin, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/help.d.ts

@@ -64,6 +64,9 @@ export interface StdinParam {
     name: string;
     required: boolean;
     constraint: string;
+    /** Whether one positional token may supply stdin instead of a pipe. Defaults
+     * to true for existing stdin-body leaves; false requires actual stdin. */
+    allowPositional?: boolean;
 }
 /** --context-file PATH: reads and JSON-parses the file at PATH. */
 export interface ContextFileParam {

package/dist/core/help.js

@@ -223,7 +223,7 @@ function paramDesc(p) {
     // flag
     const f = p;
     if (f.type === 'bool')
-        return `optional boolean. Presence means true. ${f.constraint}`.trim();
+        return `${req} boolean. Presence means true. ${f.constraint}`.trim();
     const dflt = f.default !== undefined ? ` Default: ${String(f.default)}.` : '';
     const choices = f.type === 'enum' && f.choices !== undefined
         ? ` One of: ${f.choices.join(', ')}.`

package/dist/core/human/__tests__/page-catalog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/human/__tests__/page-catalog.test.js

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { normalizePageComponents, pageComponentKinds } from '../page-catalog.js';
+test('page component registrations accept legacy names and documented objects', () => {
+    const components = normalizePageComponents([
+        'approval',
+        { kind: 'approval-card', description: 'Approval card', useWhen: 'Use for an approval.', doc: 'Product contract.', display: true },
+    ]);
+    assert.deepEqual(components, [
+        { kind: 'approval' },
+        { kind: 'approval-card', description: 'Approval card', useWhen: 'Use for an approval.', doc: 'Product contract.', display: true },
+    ]);
+    assert.deepEqual(pageComponentKinds(components), ['approval', 'approval-card']);
+    assert.throws(() => normalizePageComponents([{ kind: 'approval', display: 'yes' }]), /page_components\[0\]\.display must be a boolean/);
+    assert.throws(() => normalizePageComponents([{ kind: 'approval', unexpected: true }]), /unknown field\(s\): unexpected/);
+});
+test('page component registrations reserve derived built-in and product JSX tags', () => {
+    assert.throws(() => normalizePageComponents(['user-question']), /derives JSX tag "UserQuestion", which collides with a built-in page component/);
+    assert.throws(() => normalizePageComponents(['foo-bar', 'foo--bar']), /derives JSX tag "FooBar", which duplicates another product page component/);
+});

package/dist/core/human/__tests__/page-tickets.test.js

@@ -5,51 +5,74 @@ import { join } from 'node:path';
 import test from 'node:test';
 const home = mkdtempSync(join(tmpdir(), 'crtr-page-tickets-'));
 process.env['CRTR_HOME'] = home;
-const { atomicWriteJson, pageManifestPath, pagePath, progressPath, responsePath } = await import('../convention.js');
+const { atomicWriteJson, bindTicketReplyRoute, pageManifestPath, pagePath, progressPath, responsePath } = await import('../convention.js');
 const { claimTicket } = await import('../claim.js');
 const { scanInbox, scanPageHistory } = await import('../scan.js');
 const { ticketDir } = await import('../root.js');
-const { cancelTicket, completePage, readPageProgress, readPageTicket, readTicketResult, submitPage, takeoverAndCompletePage, writePageProgress, } = await import('../tickets.js');
+const { cancelTicket, completePage, readPageProgress, readPageTicket, preparePage, readTicketResult, submitPage, takeoverAndCompletePage, validatePageTicketResponses, writePageProgress, } = await import('../tickets.js');
 const sources = mkdtempSync(join(tmpdir(), 'crtr-page-sources-'));
 function sourceFile(name, body) {
     const path = join(sources, name);
     writeFileSync(path, body);
     return path;
 }
-const askPage = sourceFile('ask.md', `---
-title: Rollout scope
-subtitle: Pick tonight's rollout
-placement: inline
----
-
-Which rollout do you want?
-
-\`\`\`slot:options
-{"id": "rollout", "mode": "single", "options": [{"id": "canary", "label": "Canary first"}, {"id": "full", "label": "Full"}]}
-\`\`\`
+const askPage = sourceFile('ask.tsx', `export default function Rollout() {
+  return (
+    <Page title="Rollout scope" subtitle="Pick tonight\u2019s rollout">
+      <p>Which rollout do you want?</p>
+      <UserQuestion id="rollout" label="Rollout lane" body="Canary limits the blast radius." mode="single" options={[{ id: 'canary', label: 'Canary first' }, { id: 'full', label: 'Full' }]} />
+    </Page>
+  );
+}
+`);
+const displayPage = sourceFile('display.tsx', `export default function Nightly() {
+  return (
+    <Page title="Nightly report">
+      <h1>All green</h1>
+    </Page>
+  );
+}
 `);
-const displayPage = sourceFile('display.html', '<!doctype html><html><head><meta name="crtr-page-title" content="Nightly report"></head><body><h1>All green</h1></body></html>');
-function submit(id, source, dialect, blockedSince, nodeId = 'node-1') {
-    return submitPage({ dir: ticketDir(id), sourceFile: source, dialect, source: { nodeId, blockedSince } }).dir;
+function submit(id, source, emittedAt, nodeId = 'node-1', replyExpected = true) {
+    const dir = submitPage({ dir: ticketDir(id), sourceFile: source, source: { nodeId, emittedAt }, delivery: { placement: 'inline', inbox: replyExpected, reply: replyExpected } }).dir;
+    if (replyExpected)
+        bindTicketReplyRoute(dir, id);
+    return dir;
 }
-test('submitPage publishes the authored source, the derived manifest and the blockedSince stamp', () => {
-    const submitted = submitPage({ dir: ticketDir('ask'), sourceFile: askPage, dialect: 'md', source: { nodeId: 'node-1' } });
+test('submitPage publishes the authored source, the derived manifest and the emittedAt stamp', () => {
+    const submitted = submitPage({ dir: ticketDir('ask'), sourceFile: askPage, source: { nodeId: 'node-1' }, delivery: { placement: 'inline', inbox: true, reply: true } });
     assert.equal(submitted.kind, 'page');
     assert.equal(submitted.id, 'ask');
-    assert.equal(readFileSync(pagePath(submitted.dir, 'md'), 'utf8'), readFileSync(askPage, 'utf8'));
+    assert.equal(readFileSync(pagePath(submitted.dir), 'utf8'), readFileSync(askPage, 'utf8'));
     const manifest = JSON.parse(readFileSync(pageManifestPath(submitted.dir), 'utf8'));
-    assert.equal(manifest['schema'], 'crtr.page/v1');
-    assert.equal(manifest['document'], 'page.md');
-    assert.equal(manifest['placement'], 'inline');
+    assert.equal(manifest['schema'], 'crtr.page/v2');
+    assert.equal(manifest['document'], 'page.tsx');
+    assert.deepEqual(manifest['delivery'], { placement: 'inline', inbox: true, reply: true });
     const source = manifest['source'];
     assert.equal(source.nodeId, 'node-1');
-    assert.ok(Date.parse(source.blockedSince) > 0, 'submission stamps blockedSince');
-    assert.throws(() => submitPage({ dir: ticketDir('ask'), sourceFile: askPage, dialect: 'md' }), /already exists/);
+    assert.ok(Date.parse(source.emittedAt) > 0, 'submission stamps emittedAt');
+    // A ticket's request is replaceable in place — what `human send --replace`
+    // does. Republishing over the same directory revises the page and leaves one
+    // ticket behind, rather than refusing or raising a second one.
+    const stamp = { nodeId: 'node-replace', emittedAt: '2026-01-05T00:00:00.000Z' };
+    const first = submitPage({ dir: ticketDir('revisable'), sourceFile: askPage, source: stamp });
+    const revised = submitPage({ dir: ticketDir('revisable'), sourceFile: displayPage, source: stamp });
+    assert.equal(revised.id, first.id);
+    assert.equal(revised.manifest.title, 'Nightly report');
+    assert.equal(readFileSync(pagePath(revised.dir), 'utf8'), readFileSync(displayPage, 'utf8'));
+    assert.deepEqual(scanPageHistory('node-replace').map((entry) => entry.id), ['revisable'], 'a replaced page is one ticket, not two');
+    bindTicketReplyRoute(submitted.dir, 'ask');
     const listed = scanInbox().find((item) => item.id === 'ask');
     assert.equal(listed?.kind, 'page');
     assert.equal(listed?.kind === 'page' ? listed.awaitsResponse : undefined, true);
     assert.deepEqual(listed?.kind === 'page' ? listed.slotKinds : undefined, ['options']);
 });
+test('an HTML page derives a slotless manifest from declared metadata', () => {
+    const report = sourceFile('report.html', '<!doctype html><html><head><meta content="Summary" name="description"><title>Report</title></head><body>done</body></html>');
+    const prepared = preparePage({ sourceFile: report });
+    assert.equal(prepared.module, undefined);
+    assert.deepEqual(prepared.manifest, { schema: 'crtr.page/v2', dialect: 'html', title: 'Report', subtitle: 'Summary', delivery: { placement: 'inline', inbox: false, reply: false }, document: 'page.html', steps: 1, slots: [], source: prepared.manifest.source });
+});
 test('progress round-trips through validation and rejects malformed saved work', () => {
     const dir = ticketDir('ask');
     assert.equal(readPageProgress(dir), null, 'no progress file reads as null');
@@ -59,6 +82,11 @@ test('progress round-trips through validation and rejects malformed saved work',
     assert.throws(() => writePageProgress(dir, { unknown: { selectedOptionIds: [], comments: [] } }), /unknown/);
     atomicWriteJson(progressPath(dir), { kind: 'page', responses: { rollout: 'not an object' }, savedAt: new Date().toISOString() });
     assert.throws(() => readPageProgress(dir), /malformed/, 'malformed progress is an error, never silently discarded');
+    // Saved work can outlive the slot it answered, because the agent may replace
+    // the page under it. The stale entry is dropped on read so the ticket stays
+    // readable; every entry the current page still declares hydrates.
+    atomicWriteJson(progressPath(dir), { kind: 'page', responses: { rollout: { selectedOptionIds: ['canary'], comments: [] }, retired: { selectedOptionIds: ['gone'], comments: [] } }, savedAt: new Date().toISOString() });
+    assert.deepEqual(readPageProgress(dir), { rollout: { selectedOptionIds: ['canary'], comments: [] } });
     writePageProgress(dir, { rollout: { selectedOptionIds: ['canary'], comments: [] } });
 });
 test('readPageTicket derives pending, resolved and canceled state and carries the document', () => {
@@ -77,23 +105,29 @@ test('readPageTicket derives pending, resolved and canceled state and carries th
     assert.equal(written['schema'], 'crtr.page-response/v1');
     assert.equal(written['kind'], 'page');
     assert.deepEqual(written['responses'], { rollout: { selectedOptionIds: ['full'], comments: [] } });
-    assert.equal(written['summary'], 'rollout: Full');
+    assert.equal(written['summary'], 'Full');
     assert.equal(readTicketResult(dir)?.kind, 'page', 'the strict decoder accepts the page result');
     assert.equal(existsSync(progressPath(dir)), false, 'completion clears owned work');
     const resolved = readPageTicket(dir);
     assert.equal(resolved.state, 'resolved');
     assert.equal(resolved.progress, null);
     assert.equal(scanInbox().some((item) => item.id === 'ask'), false, 'a resolved page leaves the pending list');
-    const canceledDir = submit('canceled', askPage, 'md', '2026-01-03T00:00:00.000Z');
+    const canceledDir = submit('canceled', askPage, '2026-01-03T00:00:00.000Z');
     cancelTicket(canceledDir, { reason: 'no longer needed' });
     assert.equal(readPageTicket(canceledDir).state, 'canceled');
 });
-test('a display page acknowledges with the empty responses map', () => {
-    const dir = submit('display', displayPage, 'html', '2026-01-04T00:00:00.000Z');
+test('page scan derives response expectation from manifest delivery', () => {
+    const dir = submit('display', displayPage, '2026-01-04T00:00:00.000Z');
     const ticket = readPageTicket(dir);
-    assert.equal(ticket.manifest.dialect, 'html');
+    assert.equal(ticket.manifest.dialect, 'jsx');
     assert.equal(ticket.manifest.slots.length, 0);
-    assert.equal(scanInbox().find((item) => item.id === 'display')?.kind === 'page', true);
+    const display = scanInbox().find((item) => item.id === 'display');
+    assert.equal(display?.kind === 'page' ? display.awaitsResponse : undefined, true, 'a reply-bearing page waits even with no response-bearing slots');
+    const announcementDir = submit('announcement-with-options', askPage, '2026-01-04T00:00:01.000Z', 'node-1', false);
+    const announcement = scanInbox().find((item) => item.id === 'announcement-with-options');
+    assert.equal(announcement, undefined, 'a passive page stays out of the inbox');
+    assert.equal(readPageTicket(announcementDir).state, 'passive');
+    assert.throws(() => takeoverAndCompletePage(announcementDir, {}, { host: 'crtrd', pid: process.pid }), /page_has_no_response_lifecycle/);
     const acknowledged = takeoverAndCompletePage(dir, {}, { host: 'crtrd', pid: process.pid });
     assert.equal(acknowledged.won, true);
     const written = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
@@ -102,11 +136,11 @@ test('a display page acknowledges with the empty responses map', () => {
     assert.equal(written['summary'], '');
 });
 test('scanPageHistory returns every page of one node, oldest first, regardless of terminal file', () => {
-    submit('older', askPage, 'md', '2026-01-01T00:00:00.000Z');
-    submit('other-node', askPage, 'md', '2026-01-02T00:00:00.000Z', 'node-2');
+    submit('older', askPage, '2026-01-01T00:00:00.000Z');
+    submit('other-node', askPage, '2026-01-02T00:00:00.000Z', 'node-2');
     const history = scanPageHistory('node-1');
-    assert.deepEqual(history.map((entry) => entry.id), ['older', 'canceled', 'display', 'ask']);
-    assert.deepEqual(history.map((entry) => entry.state), ['pending', 'canceled', 'resolved', 'resolved']);
+    assert.deepEqual(history.map((entry) => entry.id), ['older', 'canceled', 'display', 'announcement-with-options', 'ask']);
+    assert.deepEqual(history.map((entry) => entry.state), ['pending', 'canceled', 'resolved', 'passive', 'resolved']);
     assert.deepEqual(scanPageHistory('node-2').map((entry) => entry.id), ['other-node']);
     assert.deepEqual(scanPageHistory('node-missing'), []);
 });

package/dist/core/human/__tests__/page.test.js

@@ -1,97 +1,51 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
 import test from 'node:test';
-import { derivePageManifest, parsePageSource } from '../page.js';
-import { isResponseBearingSlot, validatePageResponses, validatePartialPageResponses } from '../page-schema.js';
-function withSource(name, source, run) {
-    const dir = mkdtempSync(join(tmpdir(), 'crtr-page-test-'));
-    try {
-        const path = join(dir, name);
-        writeFileSync(path, source);
-        run(path);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
+import { derivePageManifestFromDocument } from '../page.js';
+import { isResponseBearingSlot, validatePageManifest, validatePageResponses, validatePartialPageResponses } from '../page-schema.js';
+const OPTIONS = '<UserQuestion id="choice" label="Choose an option" body="One of these ships tonight." mode="single" options={[{ id: "yes", label: "Yes" }]} />';
+function page(body, props = 'title="Test"') {
+    return `export default function Page_() {\n  return (\n    <Page ${props}>\n      ${body}\n    </Page>\n  );\n}\n`;
 }
-const htmlHead = '<!doctype html><html><head><meta name="crtr-page-title" content="Test"></head><body>';
-const htmlTail = '</body></html>';
-const optionsScript = '<script type="application/json">{"mode":"single","options":[{"id":"yes","label":"Yes"}]}</script>';
-function deriveHtml(body, head = htmlHead) {
-    let manifest;
-    withSource('input.html', `${head}${body}${htmlTail}`, (path) => { manifest = derivePageManifest(path, 'html'); });
-    return manifest;
-}
-function expectHtmlError(body, pattern, head = htmlHead) {
-    withSource('input.html', `${head}${body}${htmlTail}`, (path) => assert.throws(() => derivePageManifest(path, 'html'), pattern));
-}
-test('md dialect derives a normalized manifest and preserves top-level slot scanning', () => {
-    const source = `---
-title: Rollout
-subtitle: Choose carefully
-placement: inline
----
-
-Before.
-
-\`\`\`\`markdown
-\`\`\`slot:text
-{"id":"nested","initialText":"not a slot"}
-\`\`\`
-\`\`\`\`
-
-\`\`\`slot:table
-{"columns":[{"id":"day","label":"Day"}],"rows":[{"id":"r1","cells":{"day":"Mon"}}]}
-\`\`\`
-
-\`\`\`slot:options
-{"id":"rollout","mode":"single","options":[{"id":"yes","label":"Yes"}]}
-\`\`\`
-`;
-    withSource('input.md', source, (path) => {
-        const manifest = derivePageManifest(path, 'md');
-        // A display-only table's schema defaults must survive the manifest→source round trip.
-        assert.deepEqual(parsePageSource(source, manifest).at(-1), { kind: 'slot', slotIndex: 1 });
-        assert.equal(manifest.title, 'Rollout');
-        assert.equal(manifest.subtitle, 'Choose carefully');
-        assert.equal(manifest.placement, 'inline');
-        assert.equal(manifest.document, 'page.md');
-        assert.equal(manifest.steps, 1);
-        assert.deepEqual(manifest.slots.map(({ id, kind, step }) => ({ id, kind, step })), [{ id: undefined, kind: 'table', step: 0 }, { id: 'rollout', kind: 'options', step: 0 }]);
-    });
-});
-test('html dialect derives document-order slots and wrapper steps', () => {
-    const body = `<crtr-pages><crtr-page><section><crtr-options id="choice">${optionsScript}</crtr-options></section></crtr-page><crtr-page><crtr-chart><script type="application/json">{"kind":"bar","x":"day","y":[{"field":"count"}]}</script></crtr-chart></crtr-page></crtr-pages>`;
-    const manifest = deriveHtml(body, '<!doctype html><html placement="inline"><head><meta name="crtr-page-title" content="HTML"><meta name="crtr-page-subtitle" content="Two steps"><meta name="crtr-page-placement" content="inline"></head><body>');
-    assert.equal(manifest.title, 'HTML');
-    assert.equal(manifest.placement, 'inline');
+test('jsx pages derive page props, steps, and document-order slots', () => {
+    const manifest = derivePageManifestFromDocument(page(`<Step>${OPTIONS}</Step>\n      <Step><Chart kind="bar" x="day" y={[{ field: "count" }]} /></Step>`, 'title="JSX" subtitle="Two steps"'));
+    assert.equal(manifest.title, 'JSX');
+    assert.equal(manifest.subtitle, 'Two steps');
+    assert.deepEqual(manifest.delivery, { placement: 'inline', inbox: false, reply: false });
     assert.equal(manifest.steps, 2);
-    assert.deepEqual(manifest.slots.map(({ kind, step }) => ({ kind, step })), [{ kind: 'options', step: 0 }, { kind: 'chart', step: 1 }]);
+    assert.deepEqual(manifest.slots.map(({ kind, step, id }) => ({ kind, step, id })), [
+        { kind: 'options', step: 0, id: 'choice' },
+        { kind: 'chart', step: 1, id: undefined },
+    ]);
+});
+test('a page without steps is one step, and a slot config computed at render time still reaches the manifest', () => {
+    const manifest = derivePageManifestFromDocument(page('<UserText id="note" label="Add a note" initialText="" />'));
+    assert.equal(manifest.steps, 1);
+    assert.deepEqual(manifest.slots, [{ id: 'note', kind: 'text', step: 0, config: { label: 'Add a note', initialText: '' } }]);
+    // The manifest is harvested by rendering the page, so mapped data, helper components,
+    // and hook state are all present; handlers are dropped because a manifest is JSON.
+    const computed = derivePageManifestFromDocument(`const ROWS = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }];
+function Pick({ rows }) { return <UserQuestion id="picks" label="Pick" body="Rows come from data." mode="single" options={rows.map((r) => ({ id: r.id, label: r.label }))} onSelect={() => 1} />; }
+export default function Computed() { const [title] = React.useState('Computed'); return <Page title={title}><Pick rows={ROWS} /></Page>; }
+`);
+    assert.equal(computed.title, 'Computed');
+    assert.deepEqual(computed.slots, [{ id: 'picks', kind: 'options', step: 0, config: { label: 'Pick', body: 'Rows come from data.', mode: 'single', options: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }] } }]);
+});
+test('a page that cannot render is rejected with the reason', () => {
+    assert.throws(() => derivePageManifestFromDocument(page(OPTIONS, 'title=""')), /nonempty title prop/);
+    assert.throws(() => derivePageManifestFromDocument(page(OPTIONS, 'title="T" placement="drawer"')), /placement is not authored/);
+    assert.throws(() => derivePageManifestFromDocument('function Page_() { return <Page title="T" />; }\n'), /must `export default` a component function/);
+    assert.throws(() => derivePageManifestFromDocument('export default function Page_() { return (<><Page title="A" /><Page title="B" /></>); }'), /exactly one is allowed/);
+    assert.throws(() => derivePageManifestFromDocument('export default () => <Page title="T"><Mystery /></Page>;'), /Mystery is not defined/);
+    assert.throws(() => derivePageManifestFromDocument('export default async () => <Page title="T" />;'), /async/);
 });
-test('html wrapper rejects multiple crtr-pages', () => expectHtmlError('<crtr-pages><crtr-page></crtr-page></crtr-pages><crtr-pages><crtr-page></crtr-page></crtr-pages>', /more than one <crtr-pages>/));
-test('html wrapper rejects crtr-page outside crtr-pages', () => expectHtmlError('<crtr-page></crtr-page>', /<crtr-page> outside <crtr-pages>/));
-test('html wrapper rejects empty crtr-pages', () => expectHtmlError('<crtr-pages></crtr-pages>', /empty <crtr-pages>/));
-test('html wrapper rejects a response-bearing element outside a step with the fix', () => expectHtmlError(`<crtr-options id="choice">${optionsScript}</crtr-options>`, /response-bearing element <crtr-options>[\s\S]*<crtr-pages><crtr-page>…<\/crtr-page><\/crtr-pages>/));
-test('html wrapper rejects nested crtr-pages', () => expectHtmlError('<crtr-pages><crtr-page><crtr-pages><crtr-page></crtr-page></crtr-pages></crtr-page></crtr-pages>', /nested <crtr-pages>/));
-test('md front matter names unknown, empty-title, and placement errors', () => {
-    for (const [source, pattern] of [
-        ['---\ntitle: T\nother: no\n---\n', /unknown page front matter key "other"/],
-        ['---\ntitle:   \n---\n', /title is required and must be nonempty/],
-        ['---\ntitle: T\nplacement: sidebar\n---\n', /placement must be exactly inline or panel/],
-    ])
-        withSource('input.md', source, (path) => assert.throws(() => derivePageManifest(path, 'md'), pattern));
+test('module plumbing is rejected with the in-scope teaching', () => {
+    const importing = `import React from 'react';\n${page(OPTIONS)}`;
+    assert.throws(() => derivePageManifestFromDocument(importing), /page source uses import: .*already in scope/s);
+    const requiring = `const x = require('./data.json');\n${page(OPTIONS)}`;
+    assert.throws(() => derivePageManifestFromDocument(requiring), /page source uses require\(\)/);
 });
-test('html metadata enforces cardinality, known names, and placement content', () => {
-    const duplicateTitle = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-title" content="B"></head><body>';
-    const duplicateSubtitle = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-subtitle" content="A"><meta name="crtr-page-subtitle" content="B"></head><body>';
-    const unknown = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-extra" content="x"></head><body>';
-    const badPlacement = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-placement" content="drawer"></head><body>';
-    expectHtmlError('', /Expected exactly one <meta name="crtr-page-title">, found 2/, duplicateTitle);
-    expectHtmlError('', /Expected at most one <meta name="crtr-page-subtitle">, found 2/, duplicateSubtitle);
-    expectHtmlError('', /unknown page metadata element <meta name="crtr-page-extra">/, unknown);
-    expectHtmlError('', /content must be exactly inline or panel/, badPlacement);
+test('a page that does not compile is reported with its location', () => {
+    assert.throws(() => derivePageManifestFromDocument('export default function Page_() { return (<Page title="Broken">; }'), /page does not compile: .*page\.tsx:\d+:\d+/s);
 });
 test('the response-bearing predicate handles table selection and catalog edges', () => {
     const slot = (kind, config, unvalidated) => ({ kind, step: 0, config, ...(unvalidated ? { unvalidated } : {}) });
@@ -100,40 +54,27 @@ test('the response-bearing predicate handles table selection and catalog edges',
     assert.equal(isResponseBearingSlot(slot('chart', { kind: 'bar', x: 'x', y: [{ field: 'y' }] })), false);
     assert.equal(isResponseBearingSlot(slot('product-kind', {}, true)), true);
 });
+test('product components are authored under their PascalCase tag', () => {
+    const displayComponent = [{ kind: 'nl-thread', display: true }];
+    const manifest = derivePageManifestFromDocument(page('<NlThread messages={[]} />'), displayComponent);
+    assert.deepEqual(manifest.slots, [{ kind: 'nl-thread', step: 0, config: { messages: [] }, unvalidated: true, display: true }]);
+    assert.deepEqual(validatePageManifest(manifest).slots, manifest.slots);
+    assert.equal(isResponseBearingSlot(manifest.slots[0]), false);
+    assert.throws(() => derivePageManifestFromDocument(page('<ProductInput />'), [{ kind: 'product-input' }]), /product slot kind "product-input" at slot #0 requires an id prop/);
+});
+test('a question requires its label and body at authoring time', () => {
+    assert.throws(() => derivePageManifestFromDocument(page('<UserQuestion id="choice" body="Context." mode="single" options={[{ id: "yes", label: "Yes" }]} />')), /slot "choice" \(options\): label is required/);
+    assert.throws(() => derivePageManifestFromDocument(page('<UserQuestion id="choice" label="Choose" mode="single" options={[{ id: "yes", label: "Yes" }]} />')), /slot "choice" \(options\): body is required/);
+});
+test('multi-response pages require a label on every response-bearing slot', () => {
+    assert.throws(() => derivePageManifestFromDocument(page(`<UserText id="first" initialText="" />\n      <UserText id="note" label="Add a note" initialText="" />`)), /response-bearing slot "first" requires a nonempty config\.label/);
+    assert.throws(() => derivePageManifestFromDocument(page(`${OPTIONS}\n      <UserTable id="table" label="Pick a row" columns={[{ id: "name", label: "Name" }]} rows={[{ id: "one", cells: { name: "One" } }]} rowSelect="single" caption="old" />`)), /invalid config for slot "table"/);
+});
 test('final and partial response validation share slot-addressed rules', () => {
-    const manifest = deriveHtml(`<crtr-pages><crtr-page><crtr-options id="choice">${optionsScript}</crtr-options><crtr-text id="note"><script type="application/json">{"initialText":""}</script></crtr-text></crtr-page></crtr-pages>`);
+    const manifest = derivePageManifestFromDocument(page(`${OPTIONS}\n      <UserText id="note" label="Add a note" initialText="" />`));
     assert.deepEqual(validatePartialPageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] } }), { choice: { selectedOptionIds: ['yes'], comments: [] } });
     assert.throws(() => validatePageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] } }), /missing response-bearing slot id "note"/);
-    assert.deepEqual(validatePageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] }, note: { text: '', edited: false, comments: [] } }), { choice: { selectedOptionIds: ['yes'], comments: [] }, note: { text: '', edited: false, comments: [] } });
+    assert.deepEqual(validatePageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] }, note: { text: '', edited: false } }), { choice: { selectedOptionIds: ['yes'], comments: [] }, note: { text: '', edited: false } });
     assert.throws(() => validatePartialPageResponses(manifest, { choice: { selectedOptionIds: ['maybe'], comments: [] } }), /unknown option id "maybe"/);
     assert.throws(() => validatePartialPageResponses(manifest, { extra: {} }), /unknown or non-response-bearing slot id "extra"/);
 });
-test('PageSourceProjection associates leading, interstitial, and trailing prose', () => {
-    const source = `---
-title: Projection
----
-Leading prose.
-
-\`\`\`slot:text
-{"id":"first","initialText":""}
-\`\`\`
-
-Interstitial prose.
-
-\`\`\`slot:text
-{"id":"second","initialText":""}
-\`\`\`
-
-Trailing prose.
-`;
-    withSource('input.md', source, (path) => {
-        const manifest = derivePageManifest(path, 'md');
-        assert.deepEqual(parsePageSource(source, manifest), [
-            { kind: 'prose', markdown: 'Leading prose.' },
-            { kind: 'slot', slotIndex: 0 },
-            { kind: 'prose', markdown: 'Interstitial prose.' },
-            { kind: 'slot', slotIndex: 1 },
-            { kind: 'prose', markdown: 'Trailing prose.' },
-        ]);
-    });
-});