@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/human/feedback.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export declare const PAGE_FEEDBACK_SCHEMA: "crtr.page-feedback/v1";
+export declare function pageFeedbackPath(dir: string): string;
+declare const pageFeedbackCommentSchema: z.ZodObject<{
+    id: z.ZodString;
+    quote: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    note: z.ZodString;
+    status: z.ZodEnum<{
+        open: "open";
+        resolved: "resolved";
+    }>;
+    createdAt: z.ZodString;
+    resolvedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const pageFeedbackSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"crtr.page-feedback/v1">;
+    companionNodeId: z.ZodOptional<z.ZodString>;
+    firstCommentedSha256: z.ZodOptional<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        quote: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        note: z.ZodString;
+        status: z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>;
+        createdAt: z.ZodString;
+        resolvedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PageFeedbackComment = z.infer<typeof pageFeedbackCommentSchema>;
+export type PageFeedback = z.infer<typeof pageFeedbackSchema>;
+/** Read a ticket's feedback comments; a ticket without any has an empty record. */
+export declare function readPageFeedback(dir: string): PageFeedback;
+export interface CreatePageFeedbackCommentInput {
+    quote: string;
+    context?: string;
+    note: string;
+    /** Bound as the ticket's companion when none is recorded yet. An already
+     * recorded companion wins; the first writer's companion stays the target. */
+    companionNodeId?: string;
+    /** Recorded with the companion binding; ignored once one is recorded. */
+    firstCommentedSha256?: string;
+}
+export interface PageFeedbackMutation {
+    comment: PageFeedbackComment;
+    feedback: PageFeedback;
+}
+/** Append one open feedback comment under the ticket lock. */
+export declare function createPageFeedbackComment(dir: string, input: CreatePageFeedbackCommentInput): PageFeedbackMutation;
+export declare class PageTicketTerminalError extends Error {
+    constructor();
+}
+export declare class UnknownPageFeedbackCommentError extends Error {
+    constructor(commentId: string);
+}
+export declare class PageFeedbackCommentAlreadyResolvedError extends Error {
+    constructor(commentId: string);
+}
+/** Mark one open comment resolved under the ticket lock. Terminal: a resolved
+ * comment never reopens; a renewed concern is a new comment. */
+export declare function resolvePageFeedbackComment(dir: string, commentId: string): PageFeedbackMutation;
+export {};

package/dist/core/human/feedback.js

@@ -0,0 +1,116 @@
+// Page feedback comments — ticket-attached notes on highlighted page content.
+// Feedback is about the agent's WORK, never part of the page answer: it lives
+// in its own file beside the page, delivers immediately to the ticket's
+// companion conversation, and reaches the response the sender reads at settle
+// only as the unresolved-item addendum. A sent comment is immutable — it is
+// either open or resolved, and only the companion resolves it. The file name
+// is `feedback-comments.json` — `feedback.json` is the review subsystem's
+// output file and must not be shadowed.
+import { existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { atomicWriteJson } from './convention.js';
+import { withTicketLock } from './claim.js';
+import { pageTicketState } from './tickets.js';
+export const PAGE_FEEDBACK_SCHEMA = 'crtr.page-feedback/v1';
+export function pageFeedbackPath(dir) { return `${dir}/feedback-comments.json`; }
+const pageFeedbackCommentSchema = z.object({
+    id: z.string().min(1),
+    /** The highlighted text the note is about; for a chart, its title. */
+    quote: z.string().min(1),
+    /** Surrounding text that locates the quote on the page. */
+    context: z.string().optional(),
+    note: z.string().min(1),
+    /** Open until the companion has dealt with it; resolution is terminal. */
+    status: z.enum(['open', 'resolved']),
+    createdAt: z.string().datetime({ offset: true }),
+    resolvedAt: z.string().datetime({ offset: true }).optional(),
+}).strict();
+const pageFeedbackSchema = z.object({
+    schema: z.literal(PAGE_FEEDBACK_SCHEMA),
+    /** The ticket-bound companion conversation every comment delivers to;
+     * recorded by the first comment and never replaced. */
+    companionNodeId: z.string().min(1).optional(),
+    /** Hex sha256 of the page document at first comment, for the settle-time
+     * change notice to the sender. */
+    firstCommentedSha256: z.string().min(1).optional(),
+    comments: z.array(pageFeedbackCommentSchema),
+}).strict();
+function emptyFeedback() {
+    return { schema: PAGE_FEEDBACK_SCHEMA, comments: [] };
+}
+/** Read a ticket's feedback comments; a ticket without any has an empty record. */
+export function readPageFeedback(dir) {
+    const path = pageFeedbackPath(dir);
+    if (!existsSync(path))
+        return emptyFeedback();
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`page feedback is not valid JSON: ${path}`);
+    }
+    const parsed = pageFeedbackSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`page feedback is malformed: ${path}`);
+    return parsed.data;
+}
+/** Append one open feedback comment under the ticket lock. */
+export function createPageFeedbackComment(dir, input) {
+    return withTicketLock(dir, () => {
+        requirePendingTicket(dir);
+        const feedback = readPageFeedback(dir);
+        if (feedback.companionNodeId === undefined && input.companionNodeId !== undefined) {
+            feedback.companionNodeId = input.companionNodeId;
+            if (input.firstCommentedSha256 !== undefined)
+                feedback.firstCommentedSha256 = input.firstCommentedSha256;
+        }
+        const comment = {
+            id: randomUUID(),
+            quote: input.quote,
+            ...(input.context === undefined ? {} : { context: input.context }),
+            note: input.note,
+            status: 'open',
+            createdAt: new Date().toISOString(),
+        };
+        feedback.comments.push(comment);
+        atomicWriteJson(pageFeedbackPath(dir), feedback);
+        return { comment, feedback };
+    });
+}
+export class PageTicketTerminalError extends Error {
+    constructor() { super('ticket already has a terminal outcome'); }
+}
+/** Settlement commits its terminal outcome under this same ticket lock, so an
+ * in-lock pending check is the race-free gate: no feedback mutation may land
+ * after the first ticket-ending action, however long the caller's own
+ * pre-lock work (a companion fork await) took. */
+function requirePendingTicket(dir) {
+    const state = pageTicketState(dir);
+    if (state === 'resolved' || state === 'canceled')
+        throw new PageTicketTerminalError();
+}
+export class UnknownPageFeedbackCommentError extends Error {
+    constructor(commentId) { super(`no feedback comment ${commentId} on this ticket`); }
+}
+export class PageFeedbackCommentAlreadyResolvedError extends Error {
+    constructor(commentId) { super(`feedback comment ${commentId} is already resolved`); }
+}
+/** Mark one open comment resolved under the ticket lock. Terminal: a resolved
+ * comment never reopens; a renewed concern is a new comment. */
+export function resolvePageFeedbackComment(dir, commentId) {
+    return withTicketLock(dir, () => {
+        requirePendingTicket(dir);
+        const feedback = readPageFeedback(dir);
+        const comment = feedback.comments.find((entry) => entry.id === commentId);
+        if (comment === undefined)
+            throw new UnknownPageFeedbackCommentError(commentId);
+        if (comment.status === 'resolved')
+            throw new PageFeedbackCommentAlreadyResolvedError(commentId);
+        comment.status = 'resolved';
+        comment.resolvedAt = new Date().toISOString();
+        atomicWriteJson(pageFeedbackPath(dir), feedback);
+        return { comment, feedback };
+    });
+}

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

@@ -1,6 +1,57 @@
-/** The page slot kinds crtr validates and renders itself. */
+import type { PageComponentRegistration, ProductPageComponents } from '../../types.js';
+/** The page component kinds crtr validates and renders itself. */
 export declare const BUILTIN_PAGE_KINDS: readonly ["options", "text", "table", "cards", "chart"];
-/** Normalize the product-registered page slot catalog from raw config. */
-export declare function normalizePageComponents(raw: unknown): string[];
-/** Whether crtr or the product catalog registers a page slot kind. */
-export declare function isRegisteredPageKind(kind: string, productKinds: string[]): boolean;
+export declare const STRUCTURAL_PAGE_KINDS: readonly ["page", "step"];
+export interface PageComponentCatalogEntry {
+    kind: string;
+    tag: string;
+    description: string;
+    useWhen: string;
+    doc?: string;
+    builtin: boolean;
+    structural: boolean;
+}
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export declare function pageComponentTag(kind: string): string;
+/** The built-in component kind each authored JSX component name maps to. */
+export declare const BUILTIN_KIND_BY_TAG: Readonly<Record<string, string>>;
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export declare const BUILTIN_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export declare const DISPLAY_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export declare function normalizePageComponents(raw: unknown, label?: string): PageComponentRegistration[];
+/** One contributing source of product page components: a scope's own
+ *  `config.json` block, or one installed plugin's manifest contributions. */
+export interface PageComponentLayer {
+    /** How this source is named in a collision error, e.g. `plugin "northlight"`. */
+    origin: string;
+    components: readonly PageComponentRegistration[];
+}
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export declare function mergePageComponentLayers(layers: readonly PageComponentLayer[]): PageComponentRegistration[];
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export declare function invalidPageComponentsReasons(raw: unknown): string[];
+/** Names-only projection for page validation and rendering consumers. */
+export declare function pageComponentKinds(components: readonly PageComponentRegistration[]): string[];
+/** Full built-in + product catalog for CLI discovery. */
+export declare function pageComponentCatalog(components: readonly PageComponentRegistration[]): PageComponentCatalogEntry[];
+/** Whether crtr or the product catalog registers a page component kind. */
+export declare function productPageComponent(kind: string, components: ProductPageComponents): PageComponentRegistration | undefined;
+export declare function isRegisteredPageKind(kind: string, productComponents: ProductPageComponents): boolean;

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

@@ -1,7 +1,38 @@
-/** The page slot kinds crtr validates and renders itself. */
+/** The page component kinds crtr validates and renders itself. */
 export const BUILTIN_PAGE_KINDS = ['options', 'text', 'table', 'cards', 'chart'];
+export const STRUCTURAL_PAGE_KINDS = ['page', 'step'];
 const PAGE_KIND_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const BUILTIN_PAGE_KIND_SET = new Set(BUILTIN_PAGE_KINDS);
+const BUILTIN_COMPONENTS = [
+    { kind: 'page', tag: 'Page', description: 'the page itself: title, subtitle, and every step it contains', useWhen: 'use as the single root element every page returns', builtin: true, structural: true },
+    { kind: 'step', tag: 'Step', description: 'one step inside a Page', useWhen: 'use for each step the user sees and completes in sequence', builtin: true, structural: true },
+    { kind: 'options', tag: 'UserQuestion', description: 'known alternatives with single or multiple selection', useWhen: 'use when the user picks among known alternatives, optionally with freetext', builtin: true, structural: false },
+    { kind: 'text', tag: 'UserText', description: 'writing surface whose answer is the text the user hands back', useWhen: 'use when you need prose from the user — a value they write, or a draft they revise; prose they only read is a plain element', builtin: true, structural: false },
+    { kind: 'table', tag: 'UserTable', description: 'rows and columns with optional selection', useWhen: 'use when structured records are easiest to compare in rows and columns', builtin: true, structural: false },
+    { kind: 'cards', tag: 'UserCards', description: 'visual records with optional selection', useWhen: 'use when the user compares or picks richer items than a compact option list can carry', builtin: true, structural: false },
+    { kind: 'chart', tag: 'Chart', description: 'line, bar, or area data visualization', useWhen: 'use when shape, trend, or magnitude matters more than exact tabular values', builtin: true, structural: false },
+];
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export function pageComponentTag(kind) {
+    return kind.split('-').map((part) => (part === '' ? '' : `${part[0].toUpperCase()}${part.slice(1)}`)).join('');
+}
+/** The built-in component kind each authored JSX component name maps to. */
+export const BUILTIN_KIND_BY_TAG = Object.fromEntries(BUILTIN_COMPONENTS.filter((entry) => !entry.structural).map((entry) => [entry.tag, entry.kind]));
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export const BUILTIN_PAGE_COMPONENT_TAGS = new Set(BUILTIN_COMPONENTS.map((entry) => entry.tag));
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export const DISPLAY_PAGE_COMPONENT_TAGS = new Set([
+    'Card', 'CardHeader', 'CardTitle', 'CardDescription', 'CardContent', 'CardFooter', 'CardAction',
+    'Badge', 'Button', 'Separator', 'Progress', 'Alert', 'AlertTitle', 'AlertDescription',
+    'Table', 'TableHeader', 'TableBody', 'TableFooter', 'TableRow', 'TableHead', 'TableCell', 'TableCaption',
+    'Tabs', 'TabsList', 'TabsTrigger', 'TabsContent',
+    'Accordion', 'AccordionItem', 'AccordionTrigger', 'AccordionContent',
+]);
 function describeEntry(entry) {
     try {
         const json = JSON.stringify(entry);
@@ -11,33 +42,131 @@ function describeEntry(entry) {
         return String(entry);
     }
 }
-/** Normalize the product-registered page slot catalog from raw config. */
-export function normalizePageComponents(raw) {
+function optionalText(value, field, label, index) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${label}[${index}].${field} must be a non-empty string; received ${describeEntry(value)}`);
+    }
+    return value.trim();
+}
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export function normalizePageComponents(raw, label = 'page_components') {
     if (raw === undefined)
         return [];
-    if (!Array.isArray(raw)) {
-        throw new Error(`page_components must be an array; received ${describeEntry(raw)}`);
-    }
-    const seen = new Set();
+    if (!Array.isArray(raw))
+        throw new Error(`${label} must be an array; received ${describeEntry(raw)}`);
+    const seenKinds = new Set();
+    const seenTags = new Set();
     return raw.map((entry, index) => {
-        if (typeof entry !== 'string') {
-            throw new Error(`page_components[${index}] must be a string; offending entry: ${describeEntry(entry)}`);
+        let registration;
+        if (typeof entry === 'string') {
+            registration = { kind: entry.trim() };
         }
-        const kind = entry.trim();
-        if (!PAGE_KIND_PATTERN.test(kind)) {
-            throw new Error(`page_components[${index}] has invalid page kind ${describeEntry(entry)} after trimming; expected /^[a-z][a-z0-9-]{0,63}$/`);
+        else if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+            const object = entry;
+            const extra = Object.keys(object).filter((key) => !['kind', 'description', 'useWhen', 'doc', 'display'].includes(key));
+            if (extra.length > 0)
+                throw new Error(`${label}[${index}] has unknown field(s): ${extra.join(', ')}`);
+            if (typeof object['kind'] !== 'string')
+                throw new Error(`${label}[${index}].kind must be a string; offending entry: ${describeEntry(entry)}`);
+            if (object['display'] !== undefined && typeof object['display'] !== 'boolean')
+                throw new Error(`${label}[${index}].display must be a boolean; offending entry: ${describeEntry(entry)}`);
+            registration = {
+                kind: object['kind'].trim(),
+                ...(optionalText(object['description'], 'description', label, index) === undefined ? {} : { description: optionalText(object['description'], 'description', label, index) }),
+                ...(optionalText(object['useWhen'], 'useWhen', label, index) === undefined ? {} : { useWhen: optionalText(object['useWhen'], 'useWhen', label, index) }),
+                ...(optionalText(object['doc'], 'doc', label, index) === undefined ? {} : { doc: optionalText(object['doc'], 'doc', label, index) }),
+                ...(object['display'] === true ? { display: true } : {}),
+            };
         }
-        if (BUILTIN_PAGE_KIND_SET.has(kind)) {
-            throw new Error(`page_components[${index}] ${describeEntry(entry)} collides with built-in page kind "${kind}"`);
+        else {
+            throw new Error(`${label}[${index}] must be a string or component object; offending entry: ${describeEntry(entry)}`);
         }
-        if (seen.has(kind)) {
-            throw new Error(`page_components[${index}] ${describeEntry(entry)} duplicates page kind "${kind}"`);
-        }
-        seen.add(kind);
-        return kind;
+        const kind = registration.kind;
+        if (!PAGE_KIND_PATTERN.test(kind))
+            throw new Error(`${label}[${index}] has invalid page kind ${describeEntry(kind)}; expected /^[a-z][a-z0-9-]{0,63}$/`);
+        if (BUILTIN_PAGE_KIND_SET.has(kind) || STRUCTURAL_PAGE_KINDS.includes(kind))
+            throw new Error(`${label}[${index}] collides with built-in page kind "${kind}"`);
+        if (seenKinds.has(kind))
+            throw new Error(`${label}[${index}] duplicates page kind "${kind}"`);
+        const tag = pageComponentTag(kind);
+        if (BUILTIN_PAGE_COMPONENT_TAGS.has(tag))
+            throw new Error(`${label}[${index}] kind "${kind}" derives JSX tag "${tag}", which collides with a built-in page component`);
+        if (seenTags.has(tag))
+            throw new Error(`${label}[${index}] kind "${kind}" derives JSX tag "${tag}", which duplicates another product page component`);
+        seenKinds.add(kind);
+        seenTags.add(tag);
+        return registration;
     });
 }
-/** Whether crtr or the product catalog registers a page slot kind. */
-export function isRegisteredPageKind(kind, productKinds) {
-    return BUILTIN_PAGE_KIND_SET.has(kind) || productKinds.includes(kind);
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export function mergePageComponentLayers(layers) {
+    const originByKind = new Map();
+    const claimByTag = new Map();
+    const out = [];
+    for (const layer of layers) {
+        for (const component of layer.components) {
+            const kindOrigin = originByKind.get(component.kind);
+            if (kindOrigin !== undefined) {
+                throw new Error(`page component kind "${component.kind}" is registered by both ${kindOrigin} and ${layer.origin}`);
+            }
+            const tag = pageComponentTag(component.kind);
+            const tagClaim = claimByTag.get(tag);
+            if (tagClaim !== undefined) {
+                throw new Error(`page component kind "${component.kind}" (${layer.origin}) derives JSX tag "${tag}", which duplicates kind "${tagClaim.kind}" from ${tagClaim.origin}`);
+            }
+            originByKind.set(component.kind, layer.origin);
+            claimByTag.set(tag, { kind: component.kind, origin: layer.origin });
+            out.push(component);
+        }
+    }
+    return out;
+}
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export function invalidPageComponentsReasons(raw) {
+    try {
+        normalizePageComponents(raw);
+        return [];
+    }
+    catch (error) {
+        return [error instanceof Error ? error.message : String(error)];
+    }
+}
+/** Names-only projection for page validation and rendering consumers. */
+export function pageComponentKinds(components) {
+    return components.map((component) => component.kind);
+}
+/** Full built-in + product catalog for CLI discovery. */
+export function pageComponentCatalog(components) {
+    return [
+        ...BUILTIN_COMPONENTS,
+        ...components.map((component) => ({
+            kind: component.kind,
+            tag: pageComponentTag(component.kind),
+            description: component.description ?? 'product-registered page component',
+            useWhen: component.useWhen ?? 'use when the product component matches the structured UI the user needs',
+            ...(component.doc === undefined ? {} : { doc: component.doc }),
+            builtin: false,
+            structural: false,
+        })),
+    ];
+}
+/** Whether crtr or the product catalog registers a page component kind. */
+export function productPageComponent(kind, components) {
+    return components.find((component) => component.kind === kind);
+}
+export function isRegisteredPageKind(kind, productComponents) {
+    return BUILTIN_PAGE_KIND_SET.has(kind) || productPageComponent(kind, productComponents) !== undefined;
 }

package/dist/core/human/page-errors.d.ts

@@ -0,0 +1,4 @@
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export declare class PageAuthoringError extends Error {
+    constructor(message: string);
+}

package/dist/core/human/page-errors.js

@@ -0,0 +1,7 @@
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export class PageAuthoringError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PageAuthoringError';
+    }
+}

package/dist/core/human/page-eval.d.ts

@@ -0,0 +1,20 @@
+/** One element of the tree an authored page returns. `tag` is the JSX identifier the
+ *  author wrote: a registry component (`UserQuestion`), a display component (`Card`),
+ *  or a plain element (`div`). Helper components are expanded before they get here. */
+export interface PageNode {
+    tag: string;
+    props: Record<string, unknown>;
+    children: PageNode[];
+}
+/** Evaluate the compiled page module and return the element tree its default export renders.
+ *
+ *  Each in-scope component name is bound to itself, so `<UserQuestion>` renders as the tag
+ *  string `"UserQuestion"`. A name outside that set is not defined, and the page fails with
+ *  the reference error rather than rendering a component the host does not have. */
+export declare function evaluatePageTree(code: string, tags: Iterable<string>): PageNode[];
+/** Keep only what can cross the wire. A manifest is JSON, so handlers and undefined values
+ *  are dropped rather than rejected — a click handler is legitimate authoring, it simply has
+ *  no meaning to a host reading the manifest. The round-trip also rebuilds the props in this
+ *  realm: values born in the vm carry that realm's prototypes, which prototype-sensitive
+ *  comparisons reject. */
+export declare function jsonProps(props: Record<string, unknown>): Record<string, unknown>;

package/dist/core/human/page-eval.js

@@ -0,0 +1,123 @@
+import vm from 'node:vm';
+import { PageAuthoringError } from './page-errors.js';
+const EVAL_TIMEOUT_MS = 2000;
+const MAX_DEPTH = 64;
+const FRAGMENT = Symbol('page.fragment');
+/** Generic static-extraction binding for the host hook. It must tolerate any product capability name while leaving unrelated free identifiers as errors. */
+function hostStub() {
+    let proxy;
+    const callable = () => proxy;
+    proxy = new Proxy(callable, { get: () => proxy, apply: () => proxy });
+    return proxy;
+}
+/** A page is authored against React's classic runtime, so the compiled module calls
+ *  `React.createElement`. Nothing here renders: the stub records the tree and returns
+ *  initial values for the hooks a page might reach for, which is what a manifest wants. */
+function stubReact() {
+    // A helper component is expanded here, while the render is still inside the vm, so a
+    // component that never returns is stopped by the same timeout as the page itself.
+    const createElement = (type, props, ...children) => {
+        const { key: _key, ref: _ref, ...rest } = props ?? {};
+        const flat = children.flat(Infinity);
+        if (typeof type === 'function')
+            return type({ ...rest, ...(flat.length === 0 ? {} : { children: flat }) });
+        return { $page_element: true, type, props: rest, children: flat };
+    };
+    return {
+        createElement,
+        Fragment: FRAGMENT,
+        useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => { }],
+        useReducer: (_reducer, initial) => [initial, () => { }],
+        useMemo: (factory) => factory(),
+        useCallback: (fn) => fn,
+        useRef: (initial) => ({ current: initial }),
+        useEffect: () => { },
+        useLayoutEffect: () => { },
+        useId: () => 'page-id',
+    };
+}
+function isRawElement(value) {
+    return typeof value === 'object' && value !== null && value.$page_element === true;
+}
+/** Evaluate the compiled page module and return the element tree its default export renders.
+ *
+ *  Each in-scope component name is bound to itself, so `<UserQuestion>` renders as the tag
+ *  string `"UserQuestion"`. A name outside that set is not defined, and the page fails with
+ *  the reference error rather than rendering a component the host does not have. */
+export function evaluatePageTree(code, tags) {
+    const exported = {};
+    const base = {
+        React: stubReact(),
+        module: { exports: exported },
+        exports: exported,
+        console: { log: () => { }, warn: () => { }, error: () => { }, info: () => { }, debug: () => { } },
+        usePageHost: hostStub(),
+    };
+    for (const tag of tags)
+        base[tag] = tag;
+    const deadline = Date.now() + EVAL_TIMEOUT_MS;
+    let rendered;
+    try {
+        vm.createContext(base);
+        new vm.Script(code, { filename: 'page.tsx' }).runInContext(base, { timeout: EVAL_TIMEOUT_MS });
+        const component = base['module'].exports.default;
+        if (typeof component !== 'function')
+            throw new PageAuthoringError('page module must `export default` a component function');
+        // Render inside the context so a page that never returns is stopped by the timeout
+        // rather than hanging the caller.
+        rendered = new vm.Script('(module.exports.default)({})', { filename: 'page.tsx' }).runInContext(base, { timeout: EVAL_TIMEOUT_MS });
+    }
+    catch (error) {
+        if (error instanceof PageAuthoringError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PageAuthoringError(`page failed while rendering: ${message}`);
+    }
+    // The promise is built in the vm's realm, so identity checks against this realm's
+    // Promise do not hold; thenable is the honest test.
+    if (typeof rendered?.then === 'function')
+        throw new PageAuthoringError('page component is async; a page renders synchronously');
+    const normalize = (value, depth) => {
+        if (value === null || value === undefined || typeof value === 'boolean')
+            return [];
+        if (depth > MAX_DEPTH)
+            throw new PageAuthoringError('page nests deeper than a page can render; check for a component that renders itself');
+        if (Date.now() > deadline)
+            throw new PageAuthoringError('page took too long to render; check for a component that never finishes');
+        if (Array.isArray(value))
+            return value.flatMap((item) => normalize(item, depth + 1));
+        if (!isRawElement(value))
+            return [];
+        const { type, props, children } = value;
+        const nested = [...normalize(props['children'], depth + 1), ...children.flatMap((child) => normalize(child, depth + 1))];
+        if (type === FRAGMENT)
+            return nested;
+        if (typeof type !== 'string')
+            return nested;
+        const { children: _children, ...rest } = props;
+        return [{ tag: type, props: rest, children: nested }];
+    };
+    try {
+        return normalize(rendered, 0);
+    }
+    catch (error) {
+        if (error instanceof PageAuthoringError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PageAuthoringError(`page failed while rendering: ${message}`);
+    }
+}
+/** Keep only what can cross the wire. A manifest is JSON, so handlers and undefined values
+ *  are dropped rather than rejected — a click handler is legitimate authoring, it simply has
+ *  no meaning to a host reading the manifest. The round-trip also rebuilds the props in this
+ *  realm: values born in the vm carry that realm's prototypes, which prototype-sensitive
+ *  comparisons reject. */
+export function jsonProps(props) {
+    try {
+        return JSON.parse(JSON.stringify(props));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PageAuthoringError(`page prop cannot cross the wire: ${message}`);
+    }
+}