@north-light/crouter 0.3.198 → 0.3.199

package/dist/core/human/page.js

@@ -1,14 +1,12 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { BUILTIN_PAGE_KINDS, isRegisteredPageKind } from './page-catalog.js';
-import { cardsSchema, chartDataRowsSchema, isResponseBearingSlot, issueText, tableRowsSchema, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
-/** 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';
-    }
-}
+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, 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;
@@ -31,443 +29,149 @@ function validateAuthoredManifest(parsed, productComponents) {
         throw asPageAuthoringError(error);
     }
 }
-function parseJsonObject(raw, thing) {
-    let value;
+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 {
-        value = JSON.parse(raw);
+        return transformSync(document, {
+            loader: 'tsx',
+            format: 'cjs',
+            jsx: 'transform',
+            jsxFactory: 'React.createElement',
+            jsxFragment: 'React.Fragment',
+            target: 'es2020',
+            sourcefile: 'page.tsx',
+        }).code;
     }
     catch (error) {
-        throw new PageAuthoringError(`${thing} must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (value === null || Array.isArray(value) || typeof value !== 'object')
-        throw new PageAuthoringError(`${thing} JSON must be one object`);
-    return value;
-}
-function sourceLines(source, start) {
-    const lines = [];
-    let cursor = start;
-    while (cursor < source.length) {
-        const newline = source.indexOf('\n', cursor);
-        const end = newline === -1 ? source.length : newline + 1;
-        const contentEnd = newline === -1 ? source.length : newline;
-        lines.push({ start: cursor, end, contentEnd, text: source.slice(cursor, contentEnd).replace(/\r$/, '') });
-        cursor = end;
-    }
-    return lines;
-}
-/** CommonMark closing fence: at least as many of the opener's fence character, nothing else on the line. */
-function closesFence(text, opener) {
-    const trimmed = text.trimEnd();
-    return trimmed.length >= opener.length && trimmed.split('').every((character) => character === opener.char);
-}
-function addProse(projection, raw) {
-    const markdown = raw.trim();
-    if (markdown !== '')
-        projection.push({ kind: 'prose', markdown });
-}
-/**
- * Project a pre-cutover Markdown ticket for terminal replay only. This is not
- * an authoring contract: no new page path accepts Markdown, and its old front
- * matter is merely skipped to recover the stored source body.
- */
-function projectLegacyMarkdownSource(document, productComponents) {
-    if (!(document.startsWith('---\n') || document.startsWith('---\r\n'))) {
-        throw new PageAuthoringError('stored md page is missing its opening front matter delimiter');
-    }
-    const firstEnd = document.indexOf('\n') + 1;
-    let bodyStart = -1;
-    let cursor = firstEnd;
-    while (cursor <= document.length) {
-        const newline = document.indexOf('\n', cursor);
-        const lineEnd = newline === -1 ? document.length : newline;
-        if (document.slice(cursor, lineEnd).replace(/\r$/, '') === '---') {
-            bodyStart = newline === -1 ? document.length : newline + 1;
-            break;
-        }
-        if (newline === -1)
-            break;
-        cursor = newline + 1;
-    }
-    if (bodyStart === -1)
-        throw new PageAuthoringError('stored md page is missing its closing front matter delimiter');
-    const lines = sourceLines(document, bodyStart);
-    const slots = [];
-    const projection = [];
-    let proseStart = bodyStart;
-    let ordinaryFence = null;
-    for (let index = 0; index < lines.length; index++) {
-        const line = lines[index];
-        if (ordinaryFence !== null) {
-            if (closesFence(line.text, ordinaryFence))
-                ordinaryFence = null;
-            continue;
-        }
-        const opening = line.text.match(/^(`{3,}|~{3,})(.*)$/);
-        if (opening === null)
-            continue;
-        const run = opening[1];
-        const fence = { char: run[0], length: run.length };
-        const info = opening[2];
-        if (fence.char !== '`' || !info.startsWith('slot:')) {
-            ordinaryFence = fence;
-            continue;
-        }
-        const kind = info.slice('slot:'.length);
-        if (kind === '' || info !== `slot:${kind}` || !isRegisteredPageKind(kind, productComponents)) {
-            throw new PageAuthoringError(`unregistered or invalid page slot kind "${kind}" in stored md fence`);
-        }
-        let closeIndex = -1;
-        for (let candidate = index + 1; candidate < lines.length; candidate++) {
-            if (closesFence(lines[candidate].text, fence)) {
-                closeIndex = candidate;
-                break;
-            }
-        }
-        if (closeIndex === -1)
-            throw new PageAuthoringError(`slot:${kind} fence has no matching ${run.length}-backtick closing fence`);
-        addProse(projection, document.slice(proseStart, line.start));
-        const rawObject = parseJsonObject(document.slice(line.end, lines[closeIndex].start), `stored slot:${kind} fence`);
-        const { id, ...config } = rawObject;
-        if (id !== undefined && typeof id !== 'string')
-            throw new PageAuthoringError(`stored slot:${kind} fence has non-string reserved id`);
-        slots.push({ ...(id === undefined ? {} : { id }), kind, step: 0, config, ...(BUILTIN_PAGE_KINDS.includes(kind) ? {} : { unvalidated: true }) });
-        projection.push({ kind: 'slot', slotIndex: slots.length - 1 });
-        proseStart = lines[closeIndex].end;
-        index = closeIndex;
-    }
-    addProse(projection, document.slice(proseStart));
-    return { steps: 1, slots, projection };
-}
-const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
-function tagEnd(html, start) {
-    let quote = null;
-    for (let index = start + 1; index < html.length; index++) {
-        const character = html[index];
-        if (quote !== null) {
-            if (character === quote)
-                quote = null;
-            continue;
-        }
-        if (character === '"' || character === "'") {
-            quote = character;
-            continue;
-        }
-        if (character === '>')
-            return index + 1;
-    }
-    throw new PageAuthoringError(`unterminated HTML tag beginning at byte ${start}`);
-}
-function parseAttributes(source) {
-    const attrs = new Map();
-    const tagNameEnd = source.search(/\s/);
-    const body = tagNameEnd === -1 ? '' : source.slice(tagNameEnd);
-    const pattern = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
-    for (const match of body.matchAll(pattern))
-        attrs.set(match[1].toLowerCase(), match[2] ?? match[3] ?? match[4] ?? '');
-    return attrs;
-}
-function parseHtmlElements(html) {
-    const roots = [];
-    const all = [];
-    const stack = [];
-    let cursor = 0;
-    while (cursor < html.length) {
-        const start = html.indexOf('<', cursor);
-        if (start === -1)
-            break;
-        if (html.startsWith('<!--', start)) {
-            const end = html.indexOf('-->', start + 4);
-            if (end === -1)
-                throw new PageAuthoringError(`unterminated HTML comment at byte ${start}`);
-            cursor = end + 3;
-            continue;
-        }
-        const end = tagEnd(html, start);
-        const token = html.slice(start, end);
-        if (/^<!/i.test(token) || /^<\?/i.test(token)) {
-            cursor = end;
-            continue;
-        }
-        const closing = token.match(/^<\s*\/\s*([^\s>]+)/);
-        if (closing !== null) {
-            const tag = closing[1].toLowerCase();
-            let match = stack.length - 1;
-            while (match >= 0 && stack[match].tag !== tag)
-                match--;
-            if (match >= 0) {
-                const element = stack[match];
-                element.closeStart = start;
-                element.end = end;
-                stack.length = match;
-            }
-            cursor = end;
-            continue;
-        }
-        const opening = token.match(/^<\s*([^\s/>]+)/);
-        if (opening === null) {
-            cursor = end;
-            continue;
-        }
-        const tag = opening[1].toLowerCase();
-        const parent = stack.at(-1);
-        const element = { tag, attrs: parseAttributes(token.slice(1, -1)), start, openEnd: end, end, ...(parent === undefined ? {} : { parent }), children: [] };
-        if (parent === undefined)
-            roots.push(element);
-        else
-            parent.children.push(element);
-        all.push(element);
-        const selfClosing = /\/\s*>$/.test(token) || VOID_TAGS.has(tag);
-        if (tag === 'script' && !selfClosing) {
-            const closePattern = /<\s*\/\s*script\s*>/gi;
-            closePattern.lastIndex = end;
-            const close = closePattern.exec(html);
-            if (close === null)
-                throw new PageAuthoringError(`unterminated <script> element at byte ${start}`);
-            element.text = html.slice(end, close.index);
-            element.closeStart = close.index;
-            element.end = closePattern.lastIndex;
-            cursor = closePattern.lastIndex;
-            continue;
+        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 (!selfClosing)
-            stack.push(element);
-        cursor = end;
-    }
-    return all;
-}
-function ancestor(element, tag) {
-    let current = element.parent;
-    while (current !== undefined) {
-        if (current.tag === tag)
-            return current;
-        current = current.parent;
-    }
-    return undefined;
-}
-function decodeHtmlAttribute(value) {
-    return value.replace(/&(?:amp|quot|apos|lt|gt);|&#(?:x[0-9a-f]+|\d+);/gi, (entity) => {
-        const named = { '&amp;': '&', '&quot;': '"', '&apos;': "'", '&lt;': '<', '&gt;': '>' };
-        const lower = entity.toLowerCase();
-        if (named[lower] !== undefined)
-            return named[lower];
-        const numeric = lower.startsWith('&#x') ? Number.parseInt(lower.slice(3, -1), 16) : Number.parseInt(lower.slice(2, -1), 10);
-        return Number.isFinite(numeric) ? String.fromCodePoint(numeric) : entity;
     });
+    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 validateHtmlStructure(html) {
-    const counts = [
-        ['doctype', /<!doctype\b[^>]*>/gi, 'doctype'],
-        ['<head>', /<head(?=\s|>)/gi, '<head> opening tag'],
-        ['<body>', /<body(?=\s|>)/gi, '<body> opening tag'],
-    ];
-    for (const [, pattern, label] of counts) {
-        const count = html.match(pattern)?.length ?? 0;
-        if (count !== 1)
-            throw new PageAuthoringError(`Expected exactly one ${label}, found ${count}.`);
-    }
-}
-function readHtmlMetadata(elements) {
-    const recognized = new Map();
-    for (const element of elements.filter((candidate) => candidate.tag === 'meta')) {
-        const name = element.attrs.get('name');
-        if (name === undefined || !name.startsWith('crtr-page-'))
-            continue;
-        if (!['crtr-page-title', 'crtr-page-subtitle', 'crtr-page-placement'].includes(name))
-            throw new PageAuthoringError(`unknown page metadata element <meta name="${name}">`);
-        if (ancestor(element, 'head') === undefined)
-            throw new PageAuthoringError(`<meta name="${name}"> must appear inside <head>`);
-        const entries = recognized.get(name) ?? [];
-        entries.push(element);
-        recognized.set(name, entries);
-    }
-    for (const name of ['crtr-page-title', 'crtr-page-subtitle', 'crtr-page-placement']) {
-        const count = recognized.get(name)?.length ?? 0;
-        if ((name === 'crtr-page-title' && count !== 1) || (name !== 'crtr-page-title' && count > 1)) {
-            const expected = name === 'crtr-page-title' ? 'exactly one' : 'at most one';
-            throw new PageAuthoringError(`Expected ${expected} <meta name="${name}">, found ${count}.`);
-        }
-    }
-    const titleElement = recognized.get('crtr-page-title')[0];
-    const title = decodeHtmlAttribute(titleElement.attrs.get('content') ?? '').trim();
+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.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(`<meta name="crtr-page-title"> requires nonempty content`);
-    const subtitleElement = recognized.get('crtr-page-subtitle')?.[0];
-    const subtitle = subtitleElement === undefined ? undefined : decodeHtmlAttribute(subtitleElement.attrs.get('content') ?? '').trim();
-    const placementElement = recognized.get('crtr-page-placement')?.[0];
-    const placementValue = placementElement === undefined ? 'panel' : decodeHtmlAttribute(placementElement.attrs.get('content') ?? '').trim();
-    if (placementValue !== 'inline' && placementValue !== 'panel')
-        throw new PageAuthoringError(`<meta name="crtr-page-placement"> content must be exactly inline or panel; received "${placementValue}"`);
-    return { title, ...(subtitle === undefined ? {} : { subtitle }), placement: placementValue };
-}
-function configForHtmlElement(element) {
-    const script = element.children.find((child) => child.tag === 'script' && child.attrs.get('type') === 'application/json');
-    if (script === undefined)
-        throw new PageAuthoringError(`<${element.tag}> at byte ${element.start} requires a direct <script type="application/json"> child`);
-    return parseJsonObject(script.text ?? '', `<${element.tag}> at byte ${element.start}`);
-}
-/** Project only body prose: slots remain terminal panels, while the pager's
- * structural tags are invisible in the terminal. The raw fragments flow to
- * the renderer, which downconverts HTML according to the manifest dialect. */
-function htmlProjection(document, elements, slotElements) {
-    const body = elements.find((element) => element.tag === 'body');
-    if (body === undefined)
-        throw new PageAuthoringError('page document has no <body> element');
-    const bodyEnd = body.closeStart ?? document.length;
-    const excluded = slotElements.map((element) => ({ start: element.start, end: element.end }));
-    for (const element of elements) {
-        if (element.tag !== 'crtr-pages' && element.tag !== 'crtr-page')
-            continue;
-        excluded.push({ start: element.start, end: element.openEnd });
-        if (element.closeStart !== undefined)
-            excluded.push({ start: element.closeStart, end: element.end });
-    }
-    const ranges = excluded
-        .map((range) => ({ start: Math.max(range.start, body.openEnd), end: Math.min(range.end, bodyEnd) }))
-        .filter((range) => range.start < range.end)
-        .sort((left, right) => left.start - right.start || left.end - right.end);
-    const projection = [];
-    let cursor = body.openEnd;
-    for (const range of ranges) {
-        if (range.end <= cursor)
-            continue;
-        addProse(projection, document.slice(cursor, range.start));
-        const element = slotElements.find((slot) => slot.start === range.start && slot.end === range.end);
-        if (element !== undefined)
-            projection.push({ kind: 'slot', slotIndex: slotElements.indexOf(element) });
-        cursor = range.end;
-    }
-    addProse(projection, document.slice(cursor, bodyEnd));
-    return projection;
-}
-function scanHtml(document, productComponents) {
-    validateHtmlStructure(document);
-    const elements = parseHtmlElements(document);
-    const metadata = readHtmlMetadata(elements);
-    const wrappers = elements.filter((element) => element.tag === 'crtr-pages');
-    if (wrappers.some((candidate) => ancestor(candidate, 'crtr-pages') !== undefined))
-        throw new PageAuthoringError('nested <crtr-pages> element is not allowed');
-    if (wrappers.length > 1)
-        throw new PageAuthoringError(`more than one <crtr-pages> element: found ${wrappers.length}`);
-    const wrapper = wrappers[0];
-    const pages = elements.filter((element) => element.tag === 'crtr-page');
-    for (const page of pages)
-        if (ancestor(page, 'crtr-pages') !== wrapper || wrapper === undefined)
-            throw new PageAuthoringError(`<crtr-page> outside <crtr-pages> at byte ${page.start}`);
-    if (wrapper !== undefined && pages.length === 0)
-        throw new PageAuthoringError('empty <crtr-pages> element must contain at least one <crtr-page>');
-    const pageIndexes = new Map(pages.map((page, index) => [page, index]));
-    const rawSlots = [];
-    const slotElements = [];
-    for (const element of elements) {
-        if (element.tag === 'crtr-pages' || element.tag === 'crtr-page')
-            continue;
-        let kind;
-        let unvalidated = false;
-        if (element.tag === 'crtr-slot') {
-            kind = element.attrs.get('kind');
-            if (kind === undefined || !isRegisteredPageKind(kind, productComponents) || BUILTIN_PAGE_KINDS.includes(kind))
-                throw new PageAuthoringError(`<crtr-slot> at byte ${element.start} names unregistered product kind "${kind ?? ''}"`);
-            unvalidated = true;
-        }
-        else if (element.tag.startsWith('crtr-')) {
-            kind = element.tag.slice('crtr-'.length);
-            if (!BUILTIN_PAGE_KINDS.includes(kind))
-                throw new PageAuthoringError(`unregistered page element <${element.tag}> at byte ${element.start}; product kinds use <crtr-slot kind="…">`);
-        }
-        if (kind === undefined)
-            continue;
-        if (element.attrs.has('slot-id'))
-            throw new PageAuthoringError(`<${element.tag}> at byte ${element.start} has a slot-id attribute; author the slot id as id="…" — slot-id is written by the renderer`);
-        const id = element.attrs.get('id');
-        const containingPage = ancestor(element, 'crtr-page');
-        const step = containingPage === undefined ? 0 : pageIndexes.get(containingPage) ?? 0;
-        rawSlots.push({ ...(id === undefined ? {} : { id }), kind, step, config: configForHtmlElement(element), ...(unvalidated ? { unvalidated: true } : {}) });
-        slotElements.push(element);
+        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 steps = wrapper === undefined ? 1 : pages.length;
-    const provisional = validateAuthoredManifest({ schema: 'crtr.page/v1', dialect: 'html', ...metadata, document: 'page.html', steps, slots: rawSlots }, productComponents);
-    for (let index = 0; index < provisional.slots.length; index++) {
-        const slot = provisional.slots[index];
-        if (!isResponseBearingSlot(slot))
-            continue;
-        const element = slotElements[index];
-        if (ancestor(element, 'crtr-page') === undefined) {
-            throw new PageAuthoringError(`response-bearing element <${element.tag}> for slot "${slot.id}" is outside any <crtr-page>.\nWrap interactive elements with:\n<crtr-pages><crtr-page>…</crtr-page></crtr-pages>`);
-        }
-    }
-    return { ...metadata, steps, slots: provisional.slots, projection: htmlProjection(document, elements, slotElements) };
-}
-/** Derive the transport manifest from one authored HTML page document. */
-export function derivePageManifestFromDocument(document, dialect, productComponents = [], source) {
-    const scanned = scanHtml(document, productComponents);
-    return validateAuthoredManifest({ schema: 'crtr.page/v1', dialect, title: scanned.title, ...(scanned.subtitle === undefined ? {} : { subtitle: scanned.subtitle }), placement: scanned.placement, document: 'page.html', steps: scanned.steps, slots: scanned.slots, ...(source === undefined ? {} : { source }) }, productComponents);
-}
-/** Derive the transport manifest from one authored HTML page source file. */
-export function derivePageManifest(sourceFile, dialect, productComponents = [], source) {
-    return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), dialect, productComponents, source);
-}
-const SOURCE_EMBED = {
-    table: { field: 'rows', schema: tableRowsSchema },
-    cards: { field: 'cards', schema: cardsSchema },
-    chart: { field: 'data', schema: chartDataRowsSchema },
-};
-function readSourceFile(path, context) {
-    if (!existsSync(path))
-        throw new PageAuthoringError(`${context} source file does not exist: ${path}`);
-    let raw;
-    try {
-        raw = readFileSync(path, 'utf8');
-    }
-    catch (error) {
-        throw new PageAuthoringError(`${context} source file is not readable: ${path} (${error instanceof Error ? error.message : String(error)})`);
-    }
-    try {
-        return JSON.parse(raw);
-    }
-    catch (error) {
-        throw new PageAuthoringError(`${context} source file is not valid JSON: ${path} (${error instanceof Error ? error.message : String(error)})`);
-    }
-}
-/** Read source files into their built-in slots, returning a self-contained stored manifest. */
-export function snapshotPageSources(manifest, productComponents = []) {
-    const slots = manifest.slots.map((slot, index) => {
-        const embed = slot.unvalidated === true ? undefined : SOURCE_EMBED[slot.kind];
-        const config = slot.config;
-        if (embed === undefined || typeof config.source !== 'string')
-            return slot;
-        const context = `slot ${slot.id === undefined ? `#${index}` : `"${slot.id}"`} (${slot.kind})`;
-        const raw = readSourceFile(config.source, context);
-        const parsed = embed.schema.safeParse(raw);
-        if (!parsed.success)
-            throw new PageAuthoringError(`${context} source data is invalid: ${issueText(parsed.error)}`);
-        const { source: _drop, ...rest } = config;
-        return { ...slot, config: { ...rest, [embed.field]: parsed.data } };
-    });
-    return validatePageManifest({ ...manifest, slots }, productComponents);
-}
-/** Replace every authored slot config with its stored, self-contained config for runtime rendering. */
-export function embedPageSlotConfigs(document, manifest) {
-    const replacements = [];
-    let slotIndex = 0;
-    for (const element of parseHtmlElements(document)) {
-        const isSlot = element.tag === 'crtr-slot' || (element.tag.startsWith('crtr-') && element.tag !== 'crtr-pages' && element.tag !== 'crtr-page');
-        if (!isSlot)
-            continue;
-        const slot = manifest.slots[slotIndex];
-        if (slot === undefined)
-            throw new PageAuthoringError(`page document has more slots than its manifest at slot #${slotIndex}`);
-        const script = element.children.find((child) => child.tag === 'script' && child.attrs.get('type') === 'application/json');
-        if (script?.closeStart === undefined)
-            throw new PageAuthoringError(`slot #${slotIndex} has no JSON config script`);
-        replacements.push({ start: script.openEnd, end: script.closeStart, text: JSON.stringify(slot.config).replace(/</g, '\\u003c') });
-        slotIndex += 1;
-    }
-    if (slotIndex !== manifest.slots.length)
-        throw new PageAuthoringError(`page document has ${slotIndex} slots but manifest has ${manifest.slots.length}`);
-    return replacements.reduceRight((result, replacement) => `${result.slice(0, replacement.start)}${replacement.text}${result.slice(replacement.end)}`, document);
+    const slots = [];
+    let stepCount = 0;
+    const collectSlots = (nodes, step) => {
+        for (const node of nodes) {
+            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);
 }
 /** Read and validate page.json from a ticket directory. */
-export function parsePage(dir, productComponents = []) {
+export function parsePage(dir) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
@@ -475,41 +179,5 @@ export function parsePage(dir, productComponents = []) {
     catch {
         throw new PageAuthoringError('page.json is not valid JSON');
     }
-    return validatePageManifest(raw, productComponents);
-}
-/** Key-order-independent value identity, so a re-scan compares by content. */
-function canonicalJson(value) {
-    if (value === null || typeof value !== 'object')
-        return JSON.stringify(value) ?? 'null';
-    if (Array.isArray(value))
-        return `[${value.map(canonicalJson).join(',')}]`;
-    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => (left < right ? -1 : 1));
-    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
-}
-function comparableConfig(kind, config, sourceProjection) {
-    const embed = SOURCE_EMBED[kind];
-    if (embed === undefined || !sourceProjection)
-        return config;
-    const { source: _source, [embed.field]: _data, ...rest } = config;
-    return rest;
-}
-/** Project authored source for local rendering and verify its slot references against the manifest. */
-export function parsePageSource(document, manifest, productComponents = []) {
-    const canonical = validatePageManifest(manifest, productComponents);
-    const scanned = canonical.dialect === 'md'
-        ? projectLegacyMarkdownSource(document, productComponents)
-        : scanHtml(document, productComponents);
-    // Normalize the re-scan through the same schema pass the manifest went through,
-    // so per-kind config defaults are on both sides of the comparison.
-    const derived = validateAuthoredPageManifest({ schema: 'crtr.page/v1', dialect: canonical.dialect, title: canonical.title, ...(canonical.subtitle === undefined ? {} : { subtitle: canonical.subtitle }), placement: canonical.placement, document: canonical.document, steps: scanned.steps, slots: scanned.slots }, productComponents);
-    if (derived.slots.length !== canonical.slots.length)
-        throw new PageAuthoringError(`page source has ${derived.slots.length} slots but manifest has ${canonical.slots.length}`);
-    for (let index = 0; index < canonical.slots.length; index++) {
-        const left = derived.slots[index];
-        const right = canonical.slots[index];
-        const sourceProjection = typeof left.config.source === 'string';
-        if (canonicalJson({ ...left, config: comparableConfig(left.kind, left.config, sourceProjection) }) !== canonicalJson({ ...right, config: comparableConfig(right.kind, right.config, sourceProjection) }))
-            throw new PageAuthoringError(`page source slot #${index} (${left.id ?? left.kind}) does not match manifest slot #${index}`);
-    }
-    return scanned.projection;
+    return validatePageManifest(raw);
 }