@north-light/crouter 0.3.317 → 0.3.319

package/dist/core/human/page.js

@@ -1,198 +1 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { transformSync } from 'esbuild';
-import ts from 'typescript';
-import { BUILTIN_KIND_BY_TAG, BUILTIN_PAGE_COMPONENT_TAGS, DISPLAY_PAGE_COMPONENT_TAGS, pageComponentTag } from './page-catalog.js';
-import { isResponseBearingSlot, pageDeliverySchema, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
-import { evaluatePageTree, jsonProps } from './page-eval.js';
-import { PageAuthoringError } from './page-errors.js';
-export { PageAuthoringError };
-function asPageAuthoringError(error) {
-    if (error instanceof PageAuthoringError)
-        return error;
-    return new PageAuthoringError(error instanceof Error ? error.message : String(error));
-}
-function validateAuthoredManifest(parsed, productComponents) {
-    try {
-        const manifest = validateAuthoredPageManifest(parsed, productComponents);
-        const responseBearing = manifest.slots.filter(isResponseBearingSlot);
-        if (responseBearing.length >= 2) {
-            for (const slot of responseBearing) {
-                const label = slot.config.label;
-                if (typeof label !== 'string' || label === '')
-                    throw new PageAuthoringError(`response-bearing slot "${slot.id}" requires a nonempty config.label when the page has multiple response-bearing slots`);
-            }
-        }
-        return manifest;
-    }
-    catch (error) {
-        throw asPageAuthoringError(error);
-    }
-}
-const IMPORTLESS_SCOPE = 'a page is evaluated with React and every registry component already in scope, so it takes no imports — write `<Page>`, `<UserQuestion>`, `<Card>` and friends directly.';
-/** Compile one authored TSX page to the CommonJS module the Gateway evaluates.
- *  Registry names stay free identifiers; the Gateway supplies them at eval. */
-export function compilePage(document) {
-    try {
-        return transformSync(document, {
-            loader: 'tsx',
-            format: 'cjs',
-            jsx: 'transform',
-            jsxFactory: 'React.createElement',
-            jsxFragment: 'React.Fragment',
-            target: 'es2020',
-            sourcefile: 'page.tsx',
-        }).code;
-    }
-    catch (error) {
-        const errors = error.errors;
-        const first = errors?.[0];
-        if (first === undefined)
-            throw asPageAuthoringError(error);
-        const at = first.location == null ? '' : ` (page.tsx:${first.location.line}:${first.location.column})`;
-        throw new PageAuthoringError(`page does not compile: ${first.text ?? 'unknown error'}${at}`);
-    }
-}
-function parseTsx(document) {
-    return ts.createSourceFile('page.tsx', document, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TSX);
-}
-function eachNode(node, visit) {
-    visit(node);
-    node.forEachChild((child) => eachNode(child, visit));
-}
-/** Reject module plumbing: the compiled module is evaluated with no loader behind it,
- *  so any `import` or `require` could only fail at render time. */
-function rejectModulePlumbing(sourceFile) {
-    let offense;
-    eachNode(sourceFile, (node) => {
-        if (offense !== undefined)
-            return;
-        if (ts.isImportDeclaration(node) || ts.isImportEqualsDeclaration(node))
-            offense = 'import';
-        else if (ts.isExportDeclaration(node) && node.moduleSpecifier !== undefined)
-            offense = 'export … from';
-        else if (ts.isCallExpression(node)) {
-            if (node.expression.kind === ts.SyntaxKind.ImportKeyword)
-                offense = 'dynamic import()';
-            else if (ts.isIdentifier(node.expression) && node.expression.text === 'require')
-                offense = 'require()';
-        }
-    });
-    if (offense !== undefined)
-        throw new PageAuthoringError(`page source uses ${offense}: ${IMPORTLESS_SCOPE}`);
-}
-function stringProp(props, name) {
-    const value = props[name];
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'string')
-        throw new PageAuthoringError(`<Page> prop ${name} must be a string; it is part of the page manifest`);
-    return value;
-}
-function scanPage(document, code, productComponents) {
-    rejectModulePlumbing(parseTsx(document));
-    const inScope = [...BUILTIN_PAGE_COMPONENT_TAGS, ...DISPLAY_PAGE_COMPONENT_TAGS, ...productComponents.map((component) => pageComponentTag(component.kind))];
-    const roots = evaluatePageTree(code, inScope);
-    const pages = [];
-    const collectPages = (nodes) => {
-        for (const node of nodes) {
-            if (node.kind === 'text')
-                continue;
-            if (node.tag === 'Page')
-                pages.push(node);
-            collectPages(node.children);
-        }
-    };
-    collectPages(roots);
-    if (pages.length === 0)
-        throw new PageAuthoringError('page default export must render exactly one <Page title="…"> root; it rendered none');
-    if (pages.length > 1)
-        throw new PageAuthoringError(`page default export renders ${pages.length} <Page> elements; exactly one is allowed`);
-    const page = pages[0];
-    const title = (stringProp(page.props, 'title') ?? '').trim();
-    if (title === '')
-        throw new PageAuthoringError('<Page> requires a nonempty title prop');
-    const subtitle = stringProp(page.props, 'subtitle')?.trim();
-    if (page.props['placement'] !== undefined)
-        throw new PageAuthoringError('<Page> placement is not authored; choose --placement inline or --placement panel when sending the page.');
-    const productTags = new Map();
-    for (const component of productComponents) {
-        const tag = pageComponentTag(component.kind);
-        if (BUILTIN_PAGE_COMPONENT_TAGS.has(tag))
-            throw new PageAuthoringError(`product page component kind "${component.kind}" derives JSX tag "${tag}", which collides with a built-in page component`);
-        if (productTags.has(tag))
-            throw new PageAuthoringError(`product page component kind "${component.kind}" derives JSX tag "${tag}", which duplicates product page component kind "${productTags.get(tag)}"`);
-        productTags.set(tag, component.kind);
-    }
-    const slots = [];
-    let stepCount = 0;
-    const collectSlots = (nodes, step) => {
-        for (const node of nodes) {
-            if (node.kind === 'text')
-                continue;
-            const inStep = node.tag === 'Step' ? stepCount++ : step;
-            const builtin = BUILTIN_KIND_BY_TAG[node.tag];
-            const product = productTags.get(node.tag);
-            if (builtin !== undefined || product !== undefined) {
-                const { id, ...config } = jsonProps(node.props);
-                if (id !== undefined && typeof id !== 'string')
-                    throw new PageAuthoringError(`<${node.tag}> id prop must be a string`);
-                slots.push({
-                    ...(id === undefined ? {} : { id }),
-                    kind: builtin ?? product,
-                    step: inStep,
-                    config,
-                    ...(builtin === undefined ? { unvalidated: true } : {}),
-                });
-            }
-            collectSlots(node.children, inStep);
-        }
-    };
-    collectSlots(page.children, 0);
-    return { title, ...(subtitle === undefined || subtitle === '' ? {} : { subtitle }), steps: Math.max(stepCount, 1), slots };
-}
-/** Derive the transport manifest from one authored TSX page document. */
-export function derivePageManifestFromDocument(document, productComponents = [], source, delivery = { placement: 'inline', inbox: false, reply: false }) {
-    const scanned = scanPage(document, compilePage(document), productComponents);
-    return validateAuthoredManifest({ schema: 'crtr.page/v2', dialect: 'jsx', title: scanned.title, ...(scanned.subtitle === undefined ? {} : { subtitle: scanned.subtitle }), delivery, document: 'page.tsx', steps: scanned.steps, slots: scanned.slots, ...(source === undefined ? {} : { source }) }, productComponents);
-}
-function htmlMetadata(document) {
-    const title = /<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(document)?.[1]?.replace(/<[^>]+>/g, '').trim();
-    if (title === undefined || title === '')
-        throw new PageAuthoringError('HTML page requires a nonempty <title>.');
-    const description = [...document.matchAll(/<meta\b[^>]*>/gi)].map((match) => match[0]).map((tag) => {
-        const attrs = new Map([...tag.matchAll(/\b([^\s=/>]+)\s*=\s*(["'])([\s\S]*?)\2/g)].map((match) => [match[1].toLowerCase(), match[3]]));
-        return attrs.get('name')?.toLowerCase() === 'description' ? attrs.get('content')?.trim() : undefined;
-    }).find((value) => value !== undefined);
-    return { title, ...(description === undefined || description === '' ? {} : { subtitle: description }) };
-}
-export function deriveHtmlPageManifest(document, source, delivery = { placement: 'inline', inbox: false, reply: false }) {
-    const metadata = htmlMetadata(document);
-    return validateAuthoredManifest({ schema: 'crtr.page/v2', dialect: 'html', ...metadata, delivery, document: 'page.html', steps: 1, slots: [], ...(source === undefined ? {} : { source }) }, []);
-}
-/** Derive the transport manifest from one authored TSX page source file. */
-export function derivePageManifest(sourceFile, productComponents = [], source, delivery) {
-    return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), productComponents, source, delivery);
-}
-function readPageJson(dir) {
-    try {
-        return JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
-    }
-    catch {
-        throw new PageAuthoringError('page.json is not valid JSON');
-    }
-}
-/** Read and validate page.json from a ticket directory. */
-export function parsePage(dir) {
-    return validatePageManifest(readPageJson(dir));
-}
-/** Read only the stable delivery envelope without interpreting component config. */
-export function parsePageDelivery(dir) {
-    const raw = readPageJson(dir);
-    const parsed = pageDeliverySchema.safeParse(typeof raw === 'object' && raw !== null && !Array.isArray(raw)
-        ? raw['delivery']
-        : undefined);
-    if (!parsed.success)
-        throw new PageAuthoringError('page.json has an invalid delivery envelope');
-    return parsed.data;
-}
+var _=Object.defineProperty;var i=(t,e)=>_(t,"name",{value:e,configurable:!0});import{readFileSync as E}from"node:fs";import{join as C}from"node:path";import{transformSync as D}from"esbuild";import l from"typescript";import{BUILTIN_KIND_BY_TAG as O,BUILTIN_PAGE_COMPONENT_TAGS as M,DISPLAY_PAGE_COMPONENT_TAGS as L,pageComponentTag as T}from"./page-catalog.js";import{isResponseBearingSlot as q,pageDeliverySchema as F,validateAuthoredPageManifest as B,validatePageManifest as G}from"./page-schema.js";import{evaluatePageTree as J,jsonProps as R}from"./page-eval.js";import{PageAuthoringError as o}from"./page-errors.js";function $(t){return t instanceof o?t:new o(t instanceof Error?t.message:String(t))}i($,"asPageAuthoringError");function k(t,e){try{const n=B(t,e),r=n.slots.filter(q);if(r.length>=2)for(const s of r){const c=s.config.label;if(typeof c!="string"||c==="")throw new o(`response-bearing slot "${s.id}" requires a nonempty config.label when the page has multiple response-bearing slots`)}return n}catch(n){throw $(n)}}i(k,"validateAuthoredManifest");const K="a page is evaluated with React and every registry component already in scope, so it takes no imports \u2014 write `<Page>`, `<UserQuestion>`, `<Card>` and friends directly.";function U(t){try{return D(t,{loader:"tsx",format:"cjs",jsx:"transform",jsxFactory:"React.createElement",jsxFragment:"React.Fragment",target:"es2020",sourcefile:"page.tsx"}).code}catch(e){const r=e.errors?.[0];if(r===void 0)throw $(e);const s=r.location==null?"":` (page.tsx:${r.location.line}:${r.location.column})`;throw new o(`page does not compile: ${r.text??"unknown error"}${s}`)}}i(U,"compilePage");function X(t){return l.createSourceFile("page.tsx",t,l.ScriptTarget.ES2022,!0,l.ScriptKind.TSX)}i(X,"parseTsx");function A(t,e){e(t),t.forEachChild(n=>A(n,e))}i(A,"eachNode");function H(t){let e;if(A(t,n=>{e===void 0&&(l.isImportDeclaration(n)||l.isImportEqualsDeclaration(n)?e="import":l.isExportDeclaration(n)&&n.moduleSpecifier!==void 0?e="export \u2026 from":l.isCallExpression(n)&&(n.expression.kind===l.SyntaxKind.ImportKeyword?e="dynamic import()":l.isIdentifier(n.expression)&&n.expression.text==="require"&&(e="require()")))}),e!==void 0)throw new o(`page source uses ${e}: ${K}`)}i(H,"rejectModulePlumbing");function j(t,e){const n=t[e];if(n!==void 0){if(typeof n!="string")throw new o(`<Page> prop ${e} must be a string; it is part of the page manifest`);return n}}i(j,"stringProp");function Y(t,e,n){H(X(t));const r=[...M,...L,...n.map(p=>T(p.kind))],s=J(e,r),c=[],w=i(p=>{for(const a of p)a.kind!=="text"&&(a.tag==="Page"&&c.push(a),w(a.children))},"collectPages");if(w(s),c.length===0)throw new o('page default export must render exactly one <Page title="\u2026"> root; it rendered none');if(c.length>1)throw new o(`page default export renders ${c.length} <Page> elements; exactly one is allowed`);const d=c[0],x=(j(d.props,"title")??"").trim();if(x==="")throw new o("<Page> requires a nonempty title prop");const m=j(d.props,"subtitle")?.trim();if(d.props.placement!==void 0)throw new o("<Page> placement is not authored; choose --placement inline or --placement panel when sending the page.");const u=new Map;for(const p of n){const a=T(p.kind);if(M.has(a))throw new o(`product page component kind "${p.kind}" derives JSX tag "${a}", which collides with a built-in page component`);if(u.has(a))throw new o(`product page component kind "${p.kind}" derives JSX tag "${a}", which duplicates product page component kind "${u.get(a)}"`);u.set(a,p.kind)}const P=[];let y=0;const S=i((p,a)=>{for(const f of p){if(f.kind==="text")continue;const b=f.tag==="Step"?y++:a,h=O[f.tag],v=u.get(f.tag);if(h!==void 0||v!==void 0){const{id:g,...N}=R(f.props);if(g!==void 0&&typeof g!="string")throw new o(`<${f.tag}> id prop must be a string`);P.push({...g===void 0?{}:{id:g},kind:h??v,step:b,config:N,...h===void 0?{unvalidated:!0}:{}})}S(f.children,b)}},"collectSlots");return S(d.children,0),{title:x,...m===void 0||m===""?{}:{subtitle:m},steps:Math.max(y,1),slots:P}}i(Y,"scanPage");function Q(t,e=[],n,r={placement:"inline",inbox:!1,reply:!1}){const s=Y(t,U(t),e);return k({schema:"crtr.page/v2",dialect:"jsx",title:s.title,...s.subtitle===void 0?{}:{subtitle:s.subtitle},delivery:r,document:"page.tsx",steps:s.steps,slots:s.slots,...n===void 0?{}:{source:n}},e)}i(Q,"derivePageManifestFromDocument");function z(t){const e=/<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(t)?.[1]?.replace(/<[^>]+>/g,"").trim();if(e===void 0||e==="")throw new o("HTML page requires a nonempty <title>.");const n=[...t.matchAll(/<meta\b[^>]*>/gi)].map(r=>r[0]).map(r=>{const s=new Map([...r.matchAll(/\b([^\s=/>]+)\s*=\s*(["'])([\s\S]*?)\2/g)].map(c=>[c[1].toLowerCase(),c[3]]));return s.get("name")?.toLowerCase()==="description"?s.get("content")?.trim():void 0}).find(r=>r!==void 0);return{title:e,...n===void 0||n===""?{}:{subtitle:n}}}i(z,"htmlMetadata");function se(t,e,n={placement:"inline",inbox:!1,reply:!1}){const r=z(t);return k({schema:"crtr.page/v2",dialect:"html",...r,delivery:n,document:"page.html",steps:1,slots:[],...e===void 0?{}:{source:e}},[])}i(se,"deriveHtmlPageManifest");function ae(t,e=[],n,r){return Q(E(t,"utf8"),e,n,r)}i(ae,"derivePageManifest");function I(t){try{return JSON.parse(E(C(t,"page.json"),"utf8"))}catch{throw new o("page.json is not valid JSON")}}i(I,"readPageJson");function ce(t){return G(I(t))}i(ce,"parsePage");function pe(t){const e=I(t),n=F.safeParse(typeof e=="object"&&e!==null&&!Array.isArray(e)?e.delivery:void 0);if(!n.success)throw new o("page.json has an invalid delivery envelope");return n.data}i(pe,"parsePageDelivery");export{o as PageAuthoringError,U as compilePage,se as deriveHtmlPageManifest,ae as derivePageManifest,Q as derivePageManifestFromDocument,ce as parsePage,pe as parsePageDelivery};