@north-light/crouter 0.3.198 → 0.3.200

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}`);
+    }
+}

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

@@ -3,47 +3,21 @@ import { BUILTIN_PAGE_KINDS } from './page-catalog.js';
 import type { ProductPageComponents } from '../../types.js';
 export declare const PAGE_SLOT_ID_PATTERN: RegExp;
 export declare const commentAnchorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    kind: z.ZodLiteral<"whole">;
-}, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"option">;
     optionId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"row">;
     rowId: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"column">;
-    columnId: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"card">;
-    cardId: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"range">;
-    start: z.ZodNumber;
-    end: z.ZodNumber;
-    quote: z.ZodString;
 }, z.core.$strict>], "kind">;
 export type CommentAnchor = z.infer<typeof commentAnchorSchema>;
 export declare const commentSchema: z.ZodObject<{
     id: z.ZodString;
     anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"whole">;
-    }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"option">;
         optionId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"row">;
         rowId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"column">;
-        columnId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"card">;
-        cardId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"range">;
-        start: z.ZodNumber;
-        end: z.ZodNumber;
-        quote: z.ZodString;
     }, z.core.$strict>], "kind">;
     text: z.ZodString;
 }, z.core.$strict>;
@@ -55,6 +29,7 @@ export declare const optionSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const optionsConfigSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
     options: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
@@ -74,24 +49,11 @@ export declare const optionsResponseSchema: z.ZodObject<{
     comments: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"whole">;
-        }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"option">;
             optionId: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"row">;
             rowId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"column">;
-            columnId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"card">;
-            cardId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"range">;
-            start: z.ZodNumber;
-            end: z.ZodNumber;
-            quote: z.ZodString;
         }, z.core.$strict>], "kind">;
         text: z.ZodString;
     }, z.core.$strict>>;
@@ -101,7 +63,6 @@ export type OptionsResponse = z.infer<typeof optionsResponseSchema>;
 export declare const textConfigSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     initialText: z.ZodString;
-    editable: z.ZodOptional<z.ZodBoolean>;
     placeholder: z.ZodOptional<z.ZodString>;
     singleLine: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
@@ -109,30 +70,6 @@ export type TextConfig = z.infer<typeof textConfigSchema>;
 export declare const textResponseSchema: z.ZodObject<{
     text: z.ZodString;
     edited: z.ZodBoolean;
-    comments: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"whole">;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"option">;
-            optionId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"row">;
-            rowId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"column">;
-            columnId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"card">;
-            cardId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"range">;
-            start: z.ZodNumber;
-            end: z.ZodNumber;
-            quote: z.ZodString;
-        }, z.core.$strict>], "kind">;
-        text: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TextResponse = z.infer<typeof textResponseSchema>;
 export declare const tableColumnSchema: z.ZodObject<{
@@ -153,37 +90,10 @@ export declare const tableRowsSchema: z.ZodArray<z.ZodObject<{
     id: z.ZodString;
     cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
 }, z.core.$strict>>;
-/** Stored table config: its data is always embedded. */
+/** Table config: its data is always embedded. */
 export declare const tableConfigSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
-    columns: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        label: z.ZodString;
-        align: z.ZodOptional<z.ZodEnum<{
-            right: "right";
-            left: "left";
-        }>>;
-        mono: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>>;
-    rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
-    }, z.core.$strict>>>;
-    rowSelect: z.ZodDefault<z.ZodEnum<{
-        none: "none";
-        single: "single";
-        multi: "multi";
-    }>>;
-    columnSelect: z.ZodDefault<z.ZodEnum<{
-        none: "none";
-        single: "single";
-        multi: "multi";
-    }>>;
-}, z.core.$strict>;
-/** Authored table config: `source` is resolved before the manifest is stored. */
-export declare const authoredTableConfigSchema: z.ZodObject<{
-    source: z.ZodString;
-    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
     columns: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
@@ -209,31 +119,17 @@ export declare const authoredTableConfigSchema: z.ZodObject<{
     }>>;
 }, z.core.$strict>;
 export type TableConfig = z.infer<typeof tableConfigSchema>;
-export type AuthoredTableConfig = TableConfig | z.infer<typeof authoredTableConfigSchema>;
 export declare const tableResponseSchema: z.ZodObject<{
     selectedRowIds: z.ZodArray<z.ZodString>;
     selectedColumnIds: z.ZodArray<z.ZodString>;
     comments: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"whole">;
-        }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"option">;
             optionId: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"row">;
             rowId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"column">;
-            columnId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"card">;
-            cardId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"range">;
-            start: z.ZodNumber;
-            end: z.ZodNumber;
-            quote: z.ZodString;
         }, z.core.$strict>], "kind">;
         text: z.ZodString;
     }, z.core.$strict>>;
@@ -253,26 +149,10 @@ export declare const cardsSchema: z.ZodArray<z.ZodObject<{
     body: z.ZodOptional<z.ZodString>;
     tag: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
-/** Stored cards config: its data is always embedded. */
+/** Cards config: its data is always embedded. */
 export declare const cardsConfigSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
-    cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        title: z.ZodString;
-        subtitle: z.ZodOptional<z.ZodString>;
-        body: z.ZodOptional<z.ZodString>;
-        tag: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    mode: z.ZodEnum<{
-        single: "single";
-        multi: "multi";
-    }>;
-    columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
-}, z.core.$strict>;
-/** Authored cards config: `source` is resolved before the manifest is stored. */
-export declare const authoredCardsConfigSchema: z.ZodObject<{
-    source: z.ZodString;
-    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
     cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
@@ -287,33 +167,8 @@ export declare const authoredCardsConfigSchema: z.ZodObject<{
     columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
 }, z.core.$strict>;
 export type CardsConfig = z.infer<typeof cardsConfigSchema>;
-export type AuthoredCardsConfig = CardsConfig | z.infer<typeof authoredCardsConfigSchema>;
 export declare const cardsResponseSchema: z.ZodObject<{
     selectedCardIds: z.ZodArray<z.ZodString>;
-    comments: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"whole">;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"option">;
-            optionId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"row">;
-            rowId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"column">;
-            columnId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"card">;
-            cardId: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"range">;
-            start: z.ZodNumber;
-            end: z.ZodNumber;
-            quote: z.ZodString;
-        }, z.core.$strict>], "kind">;
-        text: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type CardsResponse = z.infer<typeof cardsResponseSchema>;
 export declare const chartSeriesSchema: z.ZodObject<{
@@ -321,7 +176,7 @@ export declare const chartSeriesSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const chartDataRowsSchema: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-/** Stored chart config: its data is always embedded. */
+/** Chart config: its data is always embedded. */
 export declare const chartConfigSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         line: "line";
@@ -336,26 +191,8 @@ export declare const chartConfigSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     data: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
 }, z.core.$strict>;
-/** Authored chart config: `source` is resolved before the manifest is stored. */
-export declare const authoredChartConfigSchema: z.ZodObject<{
-    source: z.ZodString;
-    kind: z.ZodEnum<{
-        line: "line";
-        bar: "bar";
-        area: "area";
-    }>;
-    x: z.ZodString;
-    y: z.ZodArray<z.ZodObject<{
-        field: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    title: z.ZodOptional<z.ZodString>;
-    data: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-}, z.core.$strict>;
 export type ChartConfig = z.infer<typeof chartConfigSchema>;
-export type AuthoredChartConfig = ChartConfig | z.infer<typeof authoredChartConfigSchema>;
 export type SlotConfig = OptionsConfig | TextConfig | TableConfig | CardsConfig | ChartConfig | Record<string, unknown>;
-export type AuthoredSlotConfig = OptionsConfig | TextConfig | AuthoredTableConfig | AuthoredCardsConfig | AuthoredChartConfig | Record<string, unknown>;
 export type SlotResponse = OptionsResponse | TextResponse | TableResponse | CardsResponse | Record<string, unknown>;
 export interface PageSlot {
     id?: string;
@@ -363,50 +200,45 @@ export interface PageSlot {
     step: number;
     config: SlotConfig;
     unvalidated?: true;
-    /** Product registration declares this slot display-only. */
+    /** Product registration declares this component display-only, so it carries no response. */
     display?: true;
 }
-/** A page before submit may contain filesystem `source` paths. */
-export interface AuthoredPageSlot extends Omit<PageSlot, 'config'> {
-    config: AuthoredSlotConfig;
-}
 export interface PageSource {
     sessionName?: string;
     askedBy?: string;
-    blockedSince?: string;
+    emittedAt?: string;
     profileName?: string;
     nodeId?: string;
 }
+export interface PageDelivery {
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    reply: boolean;
+}
 export interface PageManifest {
-    schema: 'crtr.page/v1';
-    dialect: 'md' | 'html';
+    schema: 'crtr.page/v2';
+    dialect: 'jsx' | 'html';
     title: string;
     subtitle?: string;
-    placement: 'inline' | 'panel';
-    document: 'page.md' | 'page.html';
+    delivery: PageDelivery;
+    document: 'page.tsx' | 'page.html';
     steps: number;
-    /** Persisted slots never carry a source path. */
     slots: PageSlot[];
     source?: PageSource;
 }
-/** A page before submit may carry filesystem source paths in its built-in slots. */
-export interface AuthoredPageManifest extends Omit<PageManifest, 'slots'> {
-    slots: AuthoredPageSlot[];
-}
 export declare const BUILTIN_PAGE_CONFIG_SCHEMAS: Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>;
 export declare const BUILTIN_PAGE_RESPONSE_SCHEMAS: Partial<Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>>;
 export declare function issueText(error: z.ZodError): string;
 /** The canonical response-bearing predicate used by every page consumer. */
 export declare function isResponseBearingSlot(slot: PageSlot): boolean;
-/** Validate a persisted manifest. Source paths are rejected: pages render only embedded data. */
-export declare function validatePageManifest(parsed: unknown, productComponents?: ProductPageComponents): PageManifest;
-/** Validate an authored manifest before submit. Source paths are resolved by `snapshotPageSources`. */
-export declare function validateAuthoredPageManifest(parsed: unknown, productComponents?: ProductPageComponents): AuthoredPageManifest;
-export declare function createPageManifestSchema(productComponents?: ProductPageComponents): z.ZodType<PageManifest>;
-/** Built-in-only manifest schema; product-aware callers use createPageManifestSchema. */
+/** Validate a persisted manifest. Publish-time validation made its slots authoritative, so reads do not resolve a component catalog. */
+export declare function validatePageManifest(parsed: unknown): PageManifest;
+/** Validate a manifest derived from an authored page, where the display flag comes from the registration rather than the source. */
+export declare function validateAuthoredPageManifest(parsed: unknown, productComponents?: ProductPageComponents): PageManifest;
+export declare function createPageManifestSchema(): z.ZodType<PageManifest>;
 export declare const pageManifestSchema: z.ZodType<PageManifest, unknown, z.core.$ZodTypeInternals<PageManifest, unknown>>;
 export type PageResponses = Record<string, SlotResponse>;
 /** Validate a complete final response map. */
 export declare function validatePageResponses(manifest: PageManifest, responses: unknown): PageResponses;
-/** Validate an autosaved response map, permitting omitted response-bearing slots. */
+/** Validate an autosaved response map, permitting omitted response-bearing components. */
 export declare function validatePartialPageResponses(manifest: PageManifest, responses: unknown): PageResponses;