@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/human/page.js

@@ -1,396 +1,177 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { checkMarkdown } from '../termrender/termrender.js';
-import { BUILTIN_PAGE_KINDS, isRegisteredPageKind } from './page-catalog.js';
-import { isResponseBearingSlot, 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;
     return new PageAuthoringError(error instanceof Error ? error.message : String(error));
 }
-function validateAuthoredManifest(parsed, productKinds) {
+function validateAuthoredManifest(parsed, productComponents) {
     try {
-        return validatePageManifest(parsed, productKinds);
+        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);
     }
 }
-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 parseFrontMatter(document) {
-    if (!(document.startsWith('---\n') || document.startsWith('---\r\n')))
-        throw new PageAuthoringError('md page front matter must begin at the first bytes with a --- delimiter line');
-    const firstEnd = document.indexOf('\n') + 1;
-    let cursor = firstEnd;
-    let closingStart = -1;
-    while (cursor <= document.length) {
-        const end = document.indexOf('\n', cursor);
-        const lineEnd = end === -1 ? document.length : end;
-        const line = document.slice(cursor, lineEnd).replace(/\r$/, '');
-        if (line === '---') {
-            closingStart = cursor;
-            cursor = end === -1 ? document.length : end + 1;
-            break;
+        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 (end === -1)
-            break;
-        cursor = end + 1;
-    }
-    if (closingStart === -1)
-        throw new PageAuthoringError('md page front matter is missing its closing --- delimiter line');
-    const raw = document.slice(firstEnd, closingStart);
-    const values = new Map();
-    const rawLines = raw.split(/\r?\n/);
-    if (rawLines.at(-1) === '')
-        rawLines.pop();
-    for (const [index, line] of rawLines.entries()) {
-        const colon = line.indexOf(':');
-        if (colon <= 0)
-            throw new PageAuthoringError(`front matter line ${index + 2} must be "key: value"`);
-        const key = line.slice(0, colon).trim();
-        const value = line.slice(colon + 1).trim();
-        if (!['title', 'subtitle', 'placement'].includes(key))
-            throw new PageAuthoringError(`unknown page front matter key "${key}"`);
-        if (values.has(key))
-            throw new PageAuthoringError(`duplicate page front matter key "${key}"`);
-        values.set(key, value);
-    }
-    const title = values.get('title');
-    if (title === undefined || title === '')
-        throw new PageAuthoringError('page front matter title is required and must be nonempty');
-    const placement = values.get('placement') ?? 'panel';
-    if (placement !== 'inline' && placement !== 'panel')
-        throw new PageAuthoringError(`page front matter placement must be exactly inline or panel; received "${placement}"`);
-    const subtitle = values.get('subtitle');
-    return { title, ...(subtitle === undefined ? {} : { subtitle }), placement, bodyStart: cursor };
+    });
+    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 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;
+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('<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);
     }
-    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 });
-}
-function scanMarkdown(document, productKinds) {
-    const meta = parseFrontMatter(document);
-    const body = document.slice(meta.bodyStart);
-    const markdownCheck = checkMarkdown(body);
-    if (!markdownCheck.ok)
-        throw new PageAuthoringError(markdownCheck.error);
-    const lines = sourceLines(document, meta.bodyStart);
-    // Fence errors report document-absolute line numbers, past the front matter.
-    const lineOffset = document.slice(0, meta.bodyStart).split('\n').length - 1;
     const slots = [];
-    const projection = [];
-    let proseStart = meta.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, productKinds)) {
-            throw new PageAuthoringError(`unregistered or invalid page slot kind "${kind}" in md fence at line ${lineOffset + index + 1}`);
-        }
-        let closeIndex = -1;
-        for (let candidate = index + 1; candidate < lines.length; candidate++) {
-            if (closesFence(lines[candidate].text, fence)) {
-                closeIndex = candidate;
-                break;
+    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);
         }
-        if (closeIndex === -1)
-            throw new PageAuthoringError(`slot:${kind} fence at line ${lineOffset + index + 1} 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), `slot:${kind} fence at line ${lineOffset + index + 1}`);
-        const { id, ...config } = rawObject;
-        if (id !== undefined && typeof id !== 'string')
-            throw new PageAuthoringError(`slot:${kind} fence at line ${lineOffset + index + 1} 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 { title: meta.title, ...(meta.subtitle === undefined ? {} : { subtitle: meta.subtitle }), placement: meta.placement, steps: 1, slots, projection };
+    };
+    collectSlots(page.children, 0);
+    return { title, ...(subtitle === undefined || subtitle === '' ? {} : { subtitle }), steps: Math.max(stepCount, 1), slots };
 }
-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;
+/** 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 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)
-                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, ...(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);
-            cursor = closePattern.lastIndex;
-            continue;
-        }
-        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;
-    });
-}
-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();
-    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}`);
-}
-function scanHtml(document, productKinds) {
-    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 || !productKinds.includes(kind) || 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;
-        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);
-    }
-    const steps = wrapper === undefined ? 1 : pages.length;
-    const provisional = validateAuthoredManifest({ schema: 'crtr.page/v1', dialect: 'html', ...metadata, document: 'page.html', steps, slots: rawSlots }, productKinds);
-    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: provisional.slots.map((_, slotIndex) => ({ kind: 'slot', slotIndex })) };
-}
-function scanDocument(document, dialect, productKinds) {
-    return dialect === 'md' ? scanMarkdown(document, productKinds) : scanHtml(document, productKinds);
+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 }) };
 }
-/** Derive the transport manifest from one authored page document. */
-export function derivePageManifestFromDocument(document, dialect, productKinds = [], source) {
-    const scanned = scanDocument(document, dialect, productKinds);
-    return validateAuthoredManifest({ schema: 'crtr.page/v1', dialect, title: scanned.title, ...(scanned.subtitle === undefined ? {} : { subtitle: scanned.subtitle }), placement: scanned.placement, document: dialect === 'md' ? 'page.md' : 'page.html', steps: scanned.steps, slots: scanned.slots, ...(source === undefined ? {} : { source }) }, productKinds);
+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 page source file. */
-export function derivePageManifest(sourceFile, dialect, productKinds = [], source) {
-    return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), dialect, productKinds, 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, productKinds = []) {
+export function parsePage(dir) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
@@ -398,30 +179,5 @@ export function parsePage(dir, productKinds = []) {
     catch {
         throw new PageAuthoringError('page.json is not valid JSON');
     }
-    return validatePageManifest(raw, productKinds);
-}
-/** 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(',')}}`;
-}
-/** Project authored source for local rendering and verify its slot references against the manifest. */
-export function parsePageSource(document, manifest, productKinds = []) {
-    const canonical = validateAuthoredManifest(manifest, productKinds);
-    const scanned = scanDocument(document, canonical.dialect, productKinds);
-    // 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 = validateAuthoredManifest({ schema: 'crtr.page/v1', dialect: canonical.dialect, title: scanned.title, ...(scanned.subtitle === undefined ? {} : { subtitle: scanned.subtitle }), placement: scanned.placement, document: canonical.document, steps: scanned.steps, slots: scanned.slots }, productKinds);
-    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];
-        if (canonicalJson(left) !== canonicalJson(canonical.slots[index]))
-            throw new PageAuthoringError(`page source slot #${index} (${left.id ?? left.kind}) does not match manifest slot #${index}`);
-    }
-    return scanned.projection;
+    return validatePageManifest(raw);
 }

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

@@ -10,6 +10,7 @@ export declare const reviewDescriptorSchema: z.ZodObject<{
         sessionName: z.ZodOptional<z.ZodString>;
         askedBy: z.ZodOptional<z.ZodString>;
         blockedSince: z.ZodOptional<z.ZodString>;
+        profileName: z.ZodOptional<z.ZodString>;
         nodeId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     blockedSince: z.ZodString;

package/dist/core/human/review-schema.js

@@ -3,7 +3,7 @@ import { basename, dirname, isAbsolute, resolve } from 'node:path';
 import { claimPath, pageManifestPath, progressPath, responsePath, reviewPath } from './convention.js';
 import { z } from 'zod';
 import { checkReviewableFile } from './visible-paths.js';
-const reviewSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional() });
+const reviewSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), profileName: z.string().optional(), nodeId: z.string().optional() });
 export const reviewDescriptorSchema = z.object({
     schema: z.literal('humanloop.review/v1'),
     file: z.string().min(1).refine(isAbsolute, 'file must be absolute'),

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

@@ -1,6 +1,10 @@
 export declare function ticketsRoot(): string;
-/** A ticket directory is the bridge node's canvas directory, the same path by construction. */
-export declare function ticketDir(nodeId: string): string;
+/** The opaque id the `/v1/human/inbox` routes address a ticket by — a hash of
+ * the canonical tickets root and the ticket directory basename. The daemon
+ * derives the same value when it resolves a route id back to a directory. */
+export declare function opaqueInboxTicketId(ticketId: string): string;
+/** Ticket directories share the canvas node root. Reply-bearing tickets may use their bridge id; standalone pages use an independent ticket id. */
+export declare function ticketDir(ticketId: string): string;
 export declare function inboxActivityPath(): string;
 /** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
 export declare function signalInboxActivity(): void;

package/dist/core/human/root.js

@@ -1,12 +1,20 @@
-import { mkdirSync, watch, writeFileSync } from 'node:fs';
+import { mkdirSync, realpathSync, watch, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
 import { crtrHome, nodeDir, nodesRoot } from '../canvas/paths.js';
 export function ticketsRoot() {
     return nodesRoot();
 }
-/** A ticket directory is the bridge node's canvas directory, the same path by construction. */
-export function ticketDir(nodeId) {
-    return nodeDir(nodeId);
+/** The opaque id the `/v1/human/inbox` routes address a ticket by — a hash of
+ * the canonical tickets root and the ticket directory basename. The daemon
+ * derives the same value when it resolves a route id back to a directory. */
+export function opaqueInboxTicketId(ticketId) {
+    const canonicalRoot = realpathSync(ticketsRoot());
+    return createHash('sha256').update(`${canonicalRoot}\0${ticketId}`, 'utf8').digest('hex');
+}
+/** Ticket directories share the canvas node root. Reply-bearing tickets may use their bridge id; standalone pages use an independent ticket id. */
+export function ticketDir(ticketId) {
+    return nodeDir(ticketId);
 }
 export function inboxActivityPath() {
     return join(crtrHome(), 'signals', 'inbox-activity');