@north-light/api 0.3.580 → 0.3.587

package/dist/core/human/convention.js

@@ -0,0 +1,82 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { atomicWriteJson, atomicWriteText } from '../fs-utils.js';
+export { atomicWriteJson, atomicWriteText };
+/** The authored page source path, derived from the persisted dialect. */
+export function pagePath(dir, dialect = 'jsx') { return `${dir}/page.${dialect === 'jsx' ? 'tsx' : 'html'}`; }
+/** The compiled module the Gateway evaluates for JSX pages. */
+export function pageModulePath(dir) { return `${dir}/page.js`; }
+export function pageManifestPath(dir) { return `${dir}/page.json`; }
+export function reviewPath(dir) { return `${dir}/review.json`; }
+export function responsePath(dir) { return `${dir}/response.json`; }
+export function progressPath(dir) { return `${dir}/progress.json`; }
+export function claimPath(dir) { return `${dir}/claim.json`; }
+export function replyRoutePath(dir) { return `${dir}/reply-route.json`; }
+/** The frozen completion-action binding, written once at request creation. */
+export function actionBindingPath(dir) { return `${dir}/action.json`; }
+/** A reply route exists only when completing the ticket must finish a human
+ * bridge and fan its result back to subscribers. Its absence is the complete
+ * representation of a standalone page. */
+export function readTicketReplyRoute(dir) {
+    const path = replyRoutePath(dir);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`invalid ticket reply route: ${path}`);
+    }
+    const bridgeNodeId = raw?.bridge_node_id;
+    if (typeof bridgeNodeId !== 'string' || bridgeNodeId === '')
+        throw new Error(`invalid ticket reply route: ${path}`);
+    return { bridge_node_id: bridgeNodeId };
+}
+export function bindTicketReplyRoute(dir, bridgeNodeId) {
+    atomicWriteJson(replyRoutePath(dir), { bridge_node_id: bridgeNodeId });
+}
+export function interactionState(dir) {
+    if (!existsSync(pageManifestPath(dir)) && !existsSync(reviewPath(dir)))
+        return 'missing';
+    if (existsSync(responsePath(dir)))
+        return 'resolved';
+    return existsSync(claimPath(dir)) ? 'claimed' : 'pending';
+}
+export function isResolved(dir) { return existsSync(responsePath(dir)); }
+export function isClaimed(dir) { return existsSync(claimPath(dir)); }
+/** Resolve and verify a ticket directory without a registry. */
+export function requireTicket(dir) {
+    const canonicalDir = realpathSync(dir);
+    if (!existsSync(pageManifestPath(canonicalDir)) && !existsSync(reviewPath(canonicalDir))) {
+        throw new Error('ticket directory has no page or review');
+    }
+    return canonicalDir;
+}
+/** Publish one immutable JSON record without replacing an existing winner. */
+export function publishJsonExclusive(path, value) {
+    const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        linkSync(tmp, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        unlinkSync(tmp);
+    }
+}
+export function clearProgress(dir) {
+    try {
+        unlinkSync(progressPath(dir));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}

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

@@ -0,0 +1,19 @@
+/** Hex sha256 of the ticket's page document, recorded at first comment so the
+ * settle-time completion can say whether the page changed during feedback. */
+export declare function pageDocumentSha256(dir: string): Promise<string>;
+/** A companion node nothing on the ticket points at must not stay resident:
+ * the comment that would have bound it was refused, failed to commit, or lost
+ * the first-comment race to a concurrently recorded companion. */
+export declare function discardFeedbackCompanion(nodeId: string): Promise<void>;
+/**
+ * Fork the sending node's current state into the ticket-bound companion and
+ * wait for its durable boundary bind. Throws on any failure — the caller
+ * refuses the comment so no feedback is accepted without a visible
+ * conversation able to receive it.
+ */
+export declare function realizeFeedbackCompanion(args: {
+    ticketId: string;
+    dir: string;
+    senderNodeId: string;
+    title: string;
+}): Promise<string>;

package/dist/core/human/feedback-companion.js

@@ -0,0 +1,92 @@
+// Feedback-companion realization — the one path that creates a page ticket's
+// companion conversation. The first feedback comment forks the page's sending
+// node at its then-current state; the ticket then records that companion and
+// every later comment reaches the same conversation. No fork point is captured
+// at page send and no placeholder exists before feedback.
+import { createHash } from 'node:crypto';
+import { getNode } from '../canvas/index.js';
+import { awaitCompanionBind, captureOrigin } from '../review/companion.js';
+import { COMPANION_BIND_DEADLINE_MS } from '../review/types.js';
+import { buildLaunchSpec } from '../runtime/launch.js';
+import { transition } from '../runtime/lifecycle.js';
+import { headlessBrokerHost } from '../runtime/host.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { reviveNode } from '../runtime/revive.js';
+import { materializeSessionBranch } from '../runtime/session-branch.js';
+import { forkNodeLedger } from '../runtime/ledger.js';
+import { pagePath } from './convention.js';
+import { selectedPageDir } from './tickets.js';
+import { readRequestFile } from './request-files.js';
+/** Hex sha256 of the ticket's page document, recorded at first comment so the
+ * settle-time completion can say whether the page changed during feedback. */
+export async function pageDocumentSha256(dir) {
+    return createHash('sha256').update(await readRequestFile(pagePath(await selectedPageDir(dir), 'jsx'))).digest('hex');
+}
+/** A companion node nothing on the ticket points at must not stay resident:
+ * the comment that would have bound it was refused, failed to commit, or lost
+ * the first-comment race to a concurrently recorded companion. */
+export async function discardFeedbackCompanion(nodeId) {
+    try {
+        await transition(nodeId, 'cancel', { reason: 'retired' });
+        void headlessBrokerHost.teardown(nodeId);
+    }
+    catch { /* the refusal is authoritative; a straggler node is inert */ }
+}
+/**
+ * Fork the sending node's current state into the ticket-bound companion and
+ * wait for its durable boundary bind. Throws on any failure — the caller
+ * refuses the comment so no feedback is accepted without a visible
+ * conversation able to receive it.
+ */
+export async function realizeFeedbackCompanion(args) {
+    const origin = await getNode(args.senderNodeId);
+    if (origin === null)
+        throw new Error(`page sender was not found: ${args.senderNodeId}`);
+    const capture = await captureOrigin(args.senderNodeId);
+    const branchFile = await materializeSessionBranch(capture);
+    const { launch } = buildLaunchSpec(origin.kind, origin.mode, {
+        lifecycle: 'resident',
+        hasManager: false,
+        model: capture.modelSpec,
+        modelExact: true,
+        cwd: origin.cwd,
+        profileId: origin.profile_id ?? null,
+    });
+    const node = await spawnNode({
+        kind: origin.kind,
+        mode: origin.mode,
+        lifecycle: 'resident',
+        cwd: origin.cwd,
+        profile_id: origin.profile_id ?? null,
+        parent: args.senderNodeId,
+        creator: args.senderNodeId,
+        subscribe: false,
+        forkFrom: branchFile,
+        forkSourceFile: branchFile,
+        modelOverride: capture.modelSpec,
+        reviewBinding: {
+            kind: 'page_feedback',
+            review_id: args.ticketId,
+            origin_node_id: args.senderNodeId,
+            branch_file: branchFile,
+            target_file: pagePath(await selectedPageDir(args.dir), 'jsx'),
+        },
+        name: `Feedback · ${args.title}`,
+        launch,
+    });
+    try {
+        await forkNodeLedger(node.node_id, args.senderNodeId);
+        // The bind deadline below only a live broker can meet, so a capacity
+        // refusal must surface here and discard the companion — freezing would
+        // burn the whole deadline waiting for a launch that is not coming.
+        await reviveNode(node.node_id, { resume: false, capacity: 'refuse' });
+        if (!await awaitCompanionBind(node.node_id, COMPANION_BIND_DEADLINE_MS)) {
+            throw new Error(`feedback companion did not bind within ${COMPANION_BIND_DEADLINE_MS}ms`);
+        }
+    }
+    catch (error) {
+        await discardFeedbackCompanion(node.node_id);
+        throw error;
+    }
+    return node.node_id;
+}

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

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+export declare const PAGE_FEEDBACK_SCHEMA: "crtr.page-feedback/v1";
+/** The path is a presentation projection, not the feedback authority. */
+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 page feedback from the request row. */
+export declare function readPageFeedback(dir: string): Promise<PageFeedback>;
+export interface CreatePageFeedbackCommentInput {
+    quote: string;
+    context?: string;
+    note: string;
+    companionNodeId?: string;
+    firstCommentedSha256?: string;
+}
+export interface PageFeedbackMutation {
+    comment: PageFeedbackComment;
+    feedback: PageFeedback;
+}
+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);
+}
+/** Append feedback in the request transaction; terminal rows reject it. */
+export declare function createPageFeedbackComment(dir: string, input: CreatePageFeedbackCommentInput): Promise<PageFeedbackMutation>;
+/** Resolve one feedback comment in the request transaction. */
+export declare function resolvePageFeedbackComment(dir: string, commentId: string): Promise<PageFeedbackMutation>;
+export {};

package/dist/core/human/feedback.js

@@ -0,0 +1,88 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { withCanvasWrite } from '../canvas/db.js';
+import { getRequestByDirectory } from './requests.js';
+export const PAGE_FEEDBACK_SCHEMA = 'crtr.page-feedback/v1';
+/** The path is a presentation projection, not the feedback authority. */
+export function pageFeedbackPath(dir) { return `${dir}/feedback-comments.json`; }
+const pageFeedbackCommentSchema = z.object({
+    id: z.string().min(1), quote: z.string().min(1), context: z.string().optional(), note: z.string().min(1),
+    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), companionNodeId: z.string().min(1).optional(),
+    firstCommentedSha256: z.string().min(1).optional(), comments: z.array(pageFeedbackCommentSchema),
+}).strict();
+function emptyFeedback() { return { schema: PAGE_FEEDBACK_SCHEMA, comments: [] }; }
+async function requestForDirectory(dir) {
+    const request = await getRequestByDirectory(dir);
+    if (request === null || request.kind !== 'page')
+        throw new Error(`unknown page request directory: ${dir}`);
+    return request;
+}
+function feedback(request) {
+    if (request.feedback_json === null)
+        return request.companion_node_id === null ? emptyFeedback() : { ...emptyFeedback(), companionNodeId: request.companion_node_id };
+    try {
+        return pageFeedbackSchema.parse(JSON.parse(request.feedback_json));
+    }
+    catch (error) {
+        throw new Error(`page feedback is malformed for ${request.request_id}`, { cause: error });
+    }
+}
+/** Read page feedback from the request row. */
+export async function readPageFeedback(dir) { return feedback(await requestForDirectory(dir)); }
+export class PageTicketTerminalError extends Error {
+    constructor() { super('ticket already has a terminal outcome'); }
+}
+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`); }
+}
+/** Append feedback in the request transaction; terminal rows reject it. */
+export async function createPageFeedbackComment(dir, input) {
+    const request = await requestForDirectory(dir);
+    return await withCanvasWrite(async (db) => {
+        const current = await db.prepare('SELECT * FROM human_requests WHERE request_id = ?').get(request.request_id);
+        if (current === undefined)
+            throw new Error(`human request disappeared: ${request.request_id}`);
+        if (current['state'] !== 'open')
+            throw new PageTicketTerminalError();
+        const row = { ...request, feedback_json: current['feedback_json'], companion_node_id: current['companion_node_id'] };
+        const next = feedback(row);
+        if (next.companionNodeId === undefined && input.companionNodeId !== undefined) {
+            next.companionNodeId = input.companionNodeId;
+            if (input.firstCommentedSha256 !== undefined)
+                next.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() };
+        next.comments.push(comment);
+        pageFeedbackSchema.parse(next);
+        await db.prepare('UPDATE human_requests SET feedback_json = ?, companion_node_id = COALESCE(companion_node_id, ?), updated_at = ? WHERE request_id = ?').run(JSON.stringify(next), next.companionNodeId ?? null, new Date().toISOString(), request.request_id);
+        return { comment, feedback: next };
+    });
+}
+/** Resolve one feedback comment in the request transaction. */
+export async function resolvePageFeedbackComment(dir, commentId) {
+    const request = await requestForDirectory(dir);
+    return await withCanvasWrite(async (db) => {
+        const current = await db.prepare('SELECT * FROM human_requests WHERE request_id = ?').get(request.request_id);
+        if (current === undefined)
+            throw new Error(`human request disappeared: ${request.request_id}`);
+        if (current['state'] !== 'open')
+            throw new PageTicketTerminalError();
+        const row = { ...request, feedback_json: current['feedback_json'], companion_node_id: current['companion_node_id'] };
+        const next = feedback(row);
+        const comment = next.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();
+        await db.prepare('UPDATE human_requests SET feedback_json = ?, updated_at = ? WHERE request_id = ?').run(JSON.stringify(next), new Date().toISOString(), request.request_id);
+        return { comment, feedback: next };
+    });
+}

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

@@ -0,0 +1,30 @@
+import type { ProductPageComponents } from '../../types.js';
+import type { PageDelivery, PageManifest, PageSource } from './page-schema.js';
+/** One validated page, ready for the daemon to publish. */
+export interface PreparedPage {
+    /** The authored source, verbatim, as the request's `document`. */
+    document: string;
+    /** The compiled CommonJS module the Gateway evaluates for JSX pages. */
+    module?: string;
+    manifest: PageManifest;
+}
+export interface PreparePageSourceOptions {
+    /** `jsx` carries .tsx semantics; `html` is a complete document. */
+    dialect: 'jsx' | 'html';
+    /** The complete authored page text, inline. */
+    document: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+export interface PreparePageOptions {
+    /** The authored page source. */
+    sourceFile: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+/** Validate one authored page document into a transportable request. */
+export declare function preparePageSource(opts: PreparePageSourceOptions): PreparedPage;
+/** Validate one authored page source file without reading or writing canvas state. */
+export declare function preparePage(opts: PreparePageOptions): PreparedPage;

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

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { compilePage, deriveHtmlPageManifest, derivePageManifestFromDocument, PageAuthoringError } from './page.js';
+/** Validate one authored page document into a transportable request. */
+export function preparePageSource(opts) {
+    const stamped = { ...(opts.source ?? {}), emittedAt: opts.source?.emittedAt ?? new Date().toISOString() };
+    const delivery = opts.delivery ?? { placement: 'inline', inbox: false, reply: false };
+    if (opts.dialect === 'html')
+        return { document: opts.document, manifest: deriveHtmlPageManifest(opts.document, stamped, delivery) };
+    return { document: opts.document, module: compilePage(opts.document), manifest: derivePageManifestFromDocument(opts.document, opts.productKinds ?? [], stamped, delivery) };
+}
+/** Validate one authored page source file without reading or writing canvas state. */
+export function preparePage(opts) {
+    const html = /\.html?$/i.test(opts.sourceFile);
+    if (!html && !opts.sourceFile.endsWith('.tsx'))
+        throw new PageAuthoringError(`page source file must be .tsx, .html, or .htm: ${opts.sourceFile}`);
+    if (!existsSync(opts.sourceFile))
+        throw new PageAuthoringError(`page source file does not exist: ${opts.sourceFile}`);
+    return preparePageSource({ ...opts, dialect: html ? 'html' : 'jsx', document: readFileSync(opts.sourceFile, 'utf8') });
+}

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

@@ -0,0 +1,8 @@
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export declare class PageAuthoringError extends Error {
+    constructor(message: string);
+}
+/** The page compiler itself failed; the page is not at fault, so callers must not report it as bad page input. */
+export declare class PageCompilerError extends Error {
+    constructor(message: string);
+}

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

@@ -0,0 +1,14 @@
+/** 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';
+    }
+}
+/** The page compiler itself failed; the page is not at fault, so callers must not report it as bad page input. */
+export class PageCompilerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PageCompilerError';
+    }
+}

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

@@ -0,0 +1,25 @@
+/** One node in the rendered tree. Helper components are expanded before this point. */
+export type PageNode = PageElementNode | PageTextNode;
+export interface PageElementNode {
+    kind: 'element';
+    /** Registry component (`UserQuestion`), display component (`Card`), or plain element (`div`). */
+    tag: string;
+    props: Record<string, unknown>;
+    children: PageNode[];
+}
+export interface PageTextNode {
+    kind: 'text';
+    text: string;
+}
+/** 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,125 @@
+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 (typeof value === 'string' || typeof value === 'number')
+            return [{ kind: 'text', text: String(value) }];
+        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 [{ kind: 'element', 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-html-markdown.d.ts

@@ -0,0 +1,8 @@
+/** An HTML page's document projected to markdown, so a terminal reader sees the
+ *  page's actual content instead of a placeholder line. HTML pages are authored
+ *  for a browser surface and carry no slots, so this is a reading projection
+ *  only — layout, styling, and scripting are dropped, and what survives is the
+ *  prose, headings, lists, links, code, and table cells the author wrote. */
+/** Project one authored HTML document to markdown. Never throws: a document
+ *  this cannot make sense of yields whatever text it did find, down to ''. */
+export declare function projectHtmlDocumentMarkdown(document: string): string;