@north-light/crouter 0.3.318 → 0.3.319

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

@@ -1,106 +1 @@
-// 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 { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { getNode } from '../canvas/index.js';
-import { awaitCompanionBind, captureOrigin } from '../review/companion.js';
-import { COMPANION_BIND_DEADLINE_MS } from '../review/types.js';
-import { SessionManager } from '../runtime/broker-sdk.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 { materializeSessionBranchAt } from '../runtime/session-branch.js';
-import { initializeForkContextExposure } from '../substrate/injected-store.js';
-import { pagePath } from './convention.js';
-import { selectedPageDir } from './tickets.js';
-export function feedbackCompanionBranchPath(dir) { return `${dir}/companion-branch.jsonl`; }
-/** 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 function pageDocumentSha256(dir) {
-    return createHash('sha256').update(readFileSync(pagePath(selectedPageDir(dir), 'jsx'))).digest('hex');
-}
-/** Materialize the companion's fork branch, reusing only an already-valid one. */
-function materializeFeedbackBranch(dir, capture) {
-    const branchFile = feedbackCompanionBranchPath(dir);
-    if (existsSync(branchFile)) {
-        const branch = SessionManager.open(branchFile);
-        if (branch.getSessionFile() === resolve(branchFile) && branch.getSessionId() !== '')
-            return branchFile;
-    }
-    materializeSessionBranchAt(capture, branchFile);
-    return branchFile;
-}
-/** 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 function discardFeedbackCompanion(nodeId) {
-    try {
-        transition(nodeId, 'cancel', { reason: 'retired' });
-        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 = getNode(args.senderNodeId);
-    if (origin === null)
-        throw new Error(`page sender was not found: ${args.senderNodeId}`);
-    const capture = await captureOrigin(args.senderNodeId);
-    const branchFile = materializeFeedbackBranch(args.dir, 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(selectedPageDir(args.dir), 'jsx'),
-        },
-        name: `Feedback · ${args.title}`,
-        launch,
-    });
-    try {
-        initializeForkContextExposure(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) {
-        discardFeedbackCompanion(node.node_id);
-        throw error;
-    }
-    return node.node_id;
-}
+var s=Object.defineProperty;var n=(e,o)=>s(e,"name",{value:o,configurable:!0});import{createHash as f}from"node:crypto";import{existsSync as l,readFileSync as u}from"node:fs";import{resolve as h}from"node:path";import{getNode as w}from"../canvas/index.js";import{awaitCompanionBind as _,captureOrigin as b}from"../review/companion.js";import{COMPANION_BIND_DEADLINE_MS as d}from"../review/types.js";import{SessionManager as k}from"../runtime/broker-sdk.js";import{buildLaunchSpec as N}from"../runtime/launch.js";import{transition as I}from"../runtime/lifecycle.js";import{headlessBrokerHost as S}from"../runtime/host.js";import{spawnNode as x}from"../runtime/nodes.js";import{reviveNode as F}from"../runtime/revive.js";import{materializeSessionBranchAt as y}from"../runtime/session-branch.js";import{initializeForkContextExposure as B}from"../substrate/injected-store.js";import{pagePath as a}from"./convention.js";import{selectedPageDir as c}from"./tickets.js";function g(e){return`${e}/companion-branch.jsonl`}n(g,"feedbackCompanionBranchPath");function T(e){return f("sha256").update(u(a(c(e),"jsx"))).digest("hex")}n(T,"pageDocumentSha256");function v(e,o){const r=g(e);if(l(r)){const i=k.open(r);if(i.getSessionFile()===h(r)&&i.getSessionId()!=="")return r}return y(o,r),r}n(v,"materializeFeedbackBranch");function C(e){try{I(e,"cancel",{reason:"retired"}),S.teardown(e)}catch{}}n(C,"discardFeedbackCompanion");async function U(e){const o=w(e.senderNodeId);if(o===null)throw new Error(`page sender was not found: ${e.senderNodeId}`);const r=await b(e.senderNodeId),i=v(e.dir,r),{launch:m}=N(o.kind,o.mode,{lifecycle:"resident",hasManager:!1,model:r.modelSpec,modelExact:!0,cwd:o.cwd,profileId:o.profile_id??null}),t=await x({kind:o.kind,mode:o.mode,lifecycle:"resident",cwd:o.cwd,profile_id:o.profile_id??null,parent:e.senderNodeId,creator:e.senderNodeId,subscribe:!1,forkFrom:i,forkSourceFile:i,modelOverride:r.modelSpec,reviewBinding:{kind:"page_feedback",review_id:e.ticketId,origin_node_id:e.senderNodeId,branch_file:i,target_file:a(c(e.dir),"jsx")},name:`Feedback \xB7 ${e.title}`,launch:m});try{if(B(t.node_id,e.senderNodeId),await F(t.node_id,{resume:!1,capacity:"refuse"}),!await _(t.node_id,d))throw new Error(`feedback companion did not bind within ${d}ms`)}catch(p){throw C(t.node_id),p}return t.node_id}n(U,"realizeFeedbackCompanion");export{C as discardFeedbackCompanion,g as feedbackCompanionBranchPath,T as pageDocumentSha256,U as realizeFeedbackCompanion};

package/dist/core/human/feedback.js

@@ -1,88 +1 @@
-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: [] }; }
-function requestForDirectory(dir) {
-    const request = 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 function readPageFeedback(dir) { return feedback(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 function createPageFeedbackComment(dir, input) {
-    const request = requestForDirectory(dir);
-    return withCanvasWrite((db) => {
-        const current = 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);
-        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 function resolvePageFeedbackComment(dir, commentId) {
-    const request = requestForDirectory(dir);
-    return withCanvasWrite((db) => {
-        const current = 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();
-        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 };
-    });
-}
+var g=Object.defineProperty;var r=(t,e)=>g(t,"name",{value:e,configurable:!0});import{randomUUID as h}from"node:crypto";import{z as n}from"zod";import{withCanvasWrite as f}from"../canvas/db.js";import{getRequestByDirectory as b}from"./requests.js";const p="crtr.page-feedback/v1";function A(t){return`${t}/feedback-comments.json`}r(A,"pageFeedbackPath");const w=n.object({id:n.string().min(1),quote:n.string().min(1),context:n.string().optional(),note:n.string().min(1),status:n.enum(["open","resolved"]),createdAt:n.string().datetime({offset:!0}),resolvedAt:n.string().datetime({offset:!0}).optional()}).strict(),_=n.object({schema:n.literal(p),companionNodeId:n.string().min(1).optional(),firstCommentedSha256:n.string().min(1).optional(),comments:n.array(w)}).strict();function E(){return{schema:p,comments:[]}}r(E,"emptyFeedback");function m(t){const e=b(t);if(e===null||e.kind!=="page")throw new Error(`unknown page request directory: ${t}`);return e}r(m,"requestForDirectory");function u(t){if(t.feedback_json===null)return t.companion_node_id===null?E():{...E(),companionNodeId:t.companion_node_id};try{return _.parse(JSON.parse(t.feedback_json))}catch(e){throw new Error(`page feedback is malformed for ${t.request_id}`,{cause:e})}}r(u,"feedback");function v(t){return u(m(t))}r(v,"readPageFeedback");class k extends Error{static{r(this,"PageTicketTerminalError")}constructor(){super("ticket already has a terminal outcome")}}class S extends Error{static{r(this,"UnknownPageFeedbackCommentError")}constructor(e){super(`no feedback comment ${e} on this ticket`)}}class q extends Error{static{r(this,"PageFeedbackCommentAlreadyResolvedError")}constructor(e){super(`feedback comment ${e} is already resolved`)}}function D(t,e){const a=m(t);return f(i=>{const s=i.prepare("SELECT * FROM human_requests WHERE request_id = ?").get(a.request_id);if(s===void 0)throw new Error(`human request disappeared: ${a.request_id}`);if(s.state!=="open")throw new k;const c={...a,feedback_json:s.feedback_json,companion_node_id:s.companion_node_id},o=u(c);o.companionNodeId===void 0&&e.companionNodeId!==void 0&&(o.companionNodeId=e.companionNodeId,e.firstCommentedSha256!==void 0&&(o.firstCommentedSha256=e.firstCommentedSha256));const d={id:h(),quote:e.quote,...e.context===void 0?{}:{context:e.context},note:e.note,status:"open",createdAt:new Date().toISOString()};return o.comments.push(d),_.parse(o),i.prepare("UPDATE human_requests SET feedback_json = ?, companion_node_id = COALESCE(companion_node_id, ?), updated_at = ? WHERE request_id = ?").run(JSON.stringify(o),o.companionNodeId??null,new Date().toISOString(),a.request_id),{comment:d,feedback:o}})}r(D,"createPageFeedbackComment");function I(t,e){const a=m(t);return f(i=>{const s=i.prepare("SELECT * FROM human_requests WHERE request_id = ?").get(a.request_id);if(s===void 0)throw new Error(`human request disappeared: ${a.request_id}`);if(s.state!=="open")throw new k;const c={...a,feedback_json:s.feedback_json,companion_node_id:s.companion_node_id},o=u(c),d=o.comments.find(l=>l.id===e);if(d===void 0)throw new S(e);if(d.status==="resolved")throw new q(e);return d.status="resolved",d.resolvedAt=new Date().toISOString(),i.prepare("UPDATE human_requests SET feedback_json = ?, updated_at = ? WHERE request_id = ?").run(JSON.stringify(o),new Date().toISOString(),a.request_id),{comment:d,feedback:o}})}r(I,"resolvePageFeedbackComment");export{p as PAGE_FEEDBACK_SCHEMA,q as PageFeedbackCommentAlreadyResolvedError,k as PageTicketTerminalError,S as UnknownPageFeedbackCommentError,D as createPageFeedbackComment,A as pageFeedbackPath,v as readPageFeedback,I as resolvePageFeedbackComment};

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

@@ -1,19 +1 @@
-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') });
-}
+var c=Object.defineProperty;var r=(e,t)=>c(e,"name",{value:t,configurable:!0});import{existsSync as m,readFileSync as u}from"node:fs";import{compilePage as o,deriveHtmlPageManifest as l,derivePageManifestFromDocument as d,PageAuthoringError as n}from"./page.js";function a(e){const t={...e.source??{},emittedAt:e.source?.emittedAt??new Date().toISOString()},i=e.delivery??{placement:"inline",inbox:!1,reply:!1};return e.dialect==="html"?{document:e.document,manifest:l(e.document,t,i)}:{document:e.document,module:o(e.document),manifest:d(e.document,e.productKinds??[],t,i)}}r(a,"preparePageSource");function h(e){const t=/\.html?$/i.test(e.sourceFile);if(!t&&!e.sourceFile.endsWith(".tsx"))throw new n(`page source file must be .tsx, .html, or .htm: ${e.sourceFile}`);if(!m(e.sourceFile))throw new n(`page source file does not exist: ${e.sourceFile}`);return a({...e,dialect:t?"html":"jsx",document:u(e.sourceFile,"utf8")})}r(h,"preparePage");export{h as preparePage,a as preparePageSource};

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

@@ -1,172 +1 @@
-/** 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);
-        return json === undefined ? String(entry) : json;
-    }
-    catch {
-        return String(entry);
-    }
-}
-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(`${label} must be an array; received ${describeEntry(raw)}`);
-    const seenKinds = new Set();
-    const seenTags = new Set();
-    return raw.map((entry, index) => {
-        let registration;
-        if (typeof entry === 'string') {
-            registration = { kind: entry.trim() };
-        }
-        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 } : {}),
-            };
-        }
-        else {
-            throw new Error(`${label}[${index}] must be a string or component object; offending entry: ${describeEntry(entry)}`);
-        }
-        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;
-    });
-}
-/** 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;
-}
+var $=Object.defineProperty;var s=(t,e)=>$(t,"name",{value:e,configurable:!0});const k=["options","text","table","cards","chart"],T=["page","step"],b=/^[a-z][a-z0-9-]{0,63}$/,w=new Set(k),h=[{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:!0,structural:!0},{kind:"step",tag:"Step",description:"one step inside a Page",useWhen:"use for each step the user sees and completes in sequence",builtin:!0,structural:!0},{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:!0,structural:!1},{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 \u2014 a value they write, or a draft they revise; prose they only read is a plain element",builtin:!0,structural:!1},{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:!0,structural:!1},{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:!0,structural:!1},{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:!0,structural:!1}];function l(t){return t.split("-").map(e=>e===""?"":`${e[0].toUpperCase()}${e.slice(1)}`).join("")}s(l,"pageComponentTag");const S=Object.fromEntries(h.filter(t=>!t.structural).map(t=>[t.tag,t.kind])),y=new Set(h.map(t=>t.tag)),_=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 p(t){try{const e=JSON.stringify(t);return e===void 0?String(t):e}catch{return String(t)}}s(p,"describeEntry");function g(t,e,a,c){if(t!==void 0){if(typeof t!="string"||t.trim()==="")throw new Error(`${a}[${c}].${e} must be a non-empty string; received ${p(t)}`);return t.trim()}}s(g,"optionalText");function C(t,e="page_components"){if(t===void 0)return[];if(!Array.isArray(t))throw new Error(`${e} must be an array; received ${p(t)}`);const a=new Set,c=new Set;return t.map((r,n)=>{let u;if(typeof r=="string")u={kind:r.trim()};else if(r!==null&&typeof r=="object"&&!Array.isArray(r)){const o=r,f=Object.keys(o).filter(m=>!["kind","description","useWhen","doc","display"].includes(m));if(f.length>0)throw new Error(`${e}[${n}] has unknown field(s): ${f.join(", ")}`);if(typeof o.kind!="string")throw new Error(`${e}[${n}].kind must be a string; offending entry: ${p(r)}`);if(o.display!==void 0&&typeof o.display!="boolean")throw new Error(`${e}[${n}].display must be a boolean; offending entry: ${p(r)}`);u={kind:o.kind.trim(),...g(o.description,"description",e,n)===void 0?{}:{description:g(o.description,"description",e,n)},...g(o.useWhen,"useWhen",e,n)===void 0?{}:{useWhen:g(o.useWhen,"useWhen",e,n)},...g(o.doc,"doc",e,n)===void 0?{}:{doc:g(o.doc,"doc",e,n)},...o.display===!0?{display:!0}:{}}}else throw new Error(`${e}[${n}] must be a string or component object; offending entry: ${p(r)}`);const i=u.kind;if(!b.test(i))throw new Error(`${e}[${n}] has invalid page kind ${p(i)}; expected /^[a-z][a-z0-9-]{0,63}$/`);if(w.has(i)||T.includes(i))throw new Error(`${e}[${n}] collides with built-in page kind "${i}"`);if(a.has(i))throw new Error(`${e}[${n}] duplicates page kind "${i}"`);const d=l(i);if(y.has(d))throw new Error(`${e}[${n}] kind "${i}" derives JSX tag "${d}", which collides with a built-in page component`);if(c.has(d))throw new Error(`${e}[${n}] kind "${i}" derives JSX tag "${d}", which duplicates another product page component`);return a.add(i),c.add(d),u})}s(C,"normalizePageComponents");function P(t){const e=new Map,a=new Map,c=[];for(const r of t)for(const n of r.components){const u=e.get(n.kind);if(u!==void 0)throw new Error(`page component kind "${n.kind}" is registered by both ${u} and ${r.origin}`);const i=l(n.kind),d=a.get(i);if(d!==void 0)throw new Error(`page component kind "${n.kind}" (${r.origin}) derives JSX tag "${i}", which duplicates kind "${d.kind}" from ${d.origin}`);e.set(n.kind,r.origin),a.set(i,{kind:n.kind,origin:r.origin}),c.push(n)}return c}s(P,"mergePageComponentLayers");function I(t){try{return C(t),[]}catch(e){return[e instanceof Error?e.message:String(e)]}}s(I,"invalidPageComponentsReasons");function N(t){return t.map(e=>e.kind)}s(N,"pageComponentKinds");function W(t){return[...h,...t.map(e=>({kind:e.kind,tag:l(e.kind),description:e.description??"product-registered page component",useWhen:e.useWhen??"use when the product component matches the structured UI the user needs",...e.doc===void 0?{}:{doc:e.doc},builtin:!1,structural:!1}))]}s(W,"pageComponentCatalog");function E(t,e){return e.find(a=>a.kind===t)}s(E,"productPageComponent");function U(t,e){return w.has(t)||E(t,e)!==void 0}s(U,"isRegisteredPageKind");export{S as BUILTIN_KIND_BY_TAG,y as BUILTIN_PAGE_COMPONENT_TAGS,k as BUILTIN_PAGE_KINDS,_ as DISPLAY_PAGE_COMPONENT_TAGS,T as STRUCTURAL_PAGE_KINDS,I as invalidPageComponentsReasons,U as isRegisteredPageKind,P as mergePageComponentLayers,C as normalizePageComponents,W as pageComponentCatalog,N as pageComponentKinds,l as pageComponentTag,E as productPageComponent};

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

@@ -1,7 +1 @@
-/** 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';
-    }
-}
+var t=Object.defineProperty;var e=(o,r)=>t(o,"name",{value:r,configurable:!0});class n extends Error{static{e(this,"PageAuthoringError")}constructor(r){super(r),this.name="PageAuthoringError"}}export{n as PageAuthoringError};

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

@@ -1,125 +1 @@
-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}`);
-    }
-}
+var E=Object.defineProperty;var n=(r,t)=>E(r,"name",{value:t,configurable:!0});import l from"node:vm";import{PageAuthoringError as o}from"./page-errors.js";const m=2e3,S=64,w=Symbol("page.fragment");function b(){let r;const t=n(()=>r,"callable");return r=new Proxy(t,{get:n(()=>r,"get"),apply:n(()=>r,"apply")}),r}n(b,"hostStub");function _(){return{createElement:n((t,s,...a)=>{const{key:d,ref:i,...f}=s??{},e=a.flat(1/0);return typeof t=="function"?t({...f,...e.length===0?{}:{children:e}}):{$page_element:!0,type:t,props:f,children:e}},"createElement"),Fragment:w,useState:n(t=>[typeof t=="function"?t():t,()=>{}],"useState"),useReducer:n((t,s)=>[s,()=>{}],"useReducer"),useMemo:n(t=>t(),"useMemo"),useCallback:n(t=>t,"useCallback"),useRef:n(t=>({current:t}),"useRef"),useEffect:n(()=>{},"useEffect"),useLayoutEffect:n(()=>{},"useLayoutEffect"),useId:n(()=>"page-id","useId")}}n(_,"stubReact");function k(r){return typeof r=="object"&&r!==null&&r.$page_element===!0}n(k,"isRawElement");function I(r,t){const s={},a={React:_(),module:{exports:s},exports:s,console:{log:n(()=>{},"log"),warn:n(()=>{},"warn"),error:n(()=>{},"error"),info:n(()=>{},"info"),debug:n(()=>{},"debug")},usePageHost:b()};for(const e of t)a[e]=e;const d=Date.now()+m;let i;try{if(l.createContext(a),new l.Script(r,{filename:"page.tsx"}).runInContext(a,{timeout:m}),typeof a.module.exports.default!="function")throw new o("page module must `export default` a component function");i=new l.Script("(module.exports.default)({})",{filename:"page.tsx"}).runInContext(a,{timeout:m})}catch(e){if(e instanceof o)throw e;const c=e instanceof Error?e.message:String(e);throw new o(`page failed while rendering: ${c}`)}if(typeof i?.then=="function")throw new o("page component is async; a page renders synchronously");const f=n((e,c)=>{if(e==null||typeof e=="boolean")return[];if(c>S)throw new o("page nests deeper than a page can render; check for a component that renders itself");if(Date.now()>d)throw new o("page took too long to render; check for a component that never finishes");if(typeof e=="string"||typeof e=="number")return[{kind:"text",text:String(e)}];if(Array.isArray(e))return e.flatMap(g=>f(g,c+1));if(!k(e))return[];const{type:p,props:h,children:y}=e,u=[...f(h.children,c+1),...y.flatMap(g=>f(g,c+1))];if(p===w||typeof p!="string")return u;const{children:M,...x}=h;return[{kind:"element",tag:p,props:x,children:u}]},"normalize");try{return f(i,0)}catch(e){if(e instanceof o)throw e;const c=e instanceof Error?e.message:String(e);throw new o(`page failed while rendering: ${c}`)}}n(I,"evaluatePageTree");function T(r){try{return JSON.parse(JSON.stringify(r))}catch(t){const s=t instanceof Error?t.message:String(t);throw new o(`page prop cannot cross the wire: ${s}`)}}n(T,"jsonProps");export{I as evaluatePageTree,T as jsonProps};