@north-light/crouter 0.3.196 → 0.3.198

package/dist/core/human/component-docs.js

@@ -0,0 +1,161 @@
+const ELEMENT_RULES = `Element contract
+- Put the JSON config in the first direct \`<script type="application/json">\` child of the component element. It must contain one JSON object.
+- \`id\` must match \`^[A-Za-z0-9_-]{1,64}$\`, be unique across the page when present, and is required only for response-bearing components. Display-only components do not need an id.
+- When a page has two or more response-bearing components, every one needs a nonempty \`config.label\`.
+- Config objects and every documented nested object reject unknown fields.`;
+const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\`. Every response carries \`comments\` as an array. \`Anchor\` is one of \`{kind:"whole"}\`, \`{kind:"option",optionId:string}\`, \`{kind:"row",rowId:string}\`, \`{kind:"column",columnId:string}\`, \`{kind:"card",cardId:string}\`, or \`{kind:"range",start:nonnegative integer,end:nonnegative integer >= start,quote:string}\`; each component accepts only the anchors named below.`;
+export const BUILTIN_COMPONENT_DOCS = [
+    {
+        kind: 'crtr-pages',
+        tag: '<crtr-pages>',
+        selectionLine: '`<crtr-pages>` — step wrapper. Use when a page is interactive or multi-step; it is always the wrapper for interactive/multi-step pages.',
+        contract: `\`<crtr-pages>\`
+
+Display-only structural primitive. It takes no config or response.
+
+- Use exactly one wrapper when the page has a response-bearing component or more than one step; do not nest wrappers.
+- It contains one or more \`<crtr-page>\` elements. A wrapper with no steps is invalid.`,
+    },
+    {
+        kind: 'crtr-page',
+        tag: '<crtr-page>',
+        selectionLine: '`<crtr-page>` — one page step. Use inside `<crtr-pages>` to group a step of an interactive or multi-step page.',
+        contract: `\`<crtr-page>\`
+
+Display-only structural primitive. It takes no config or response.
+
+- Every \`<crtr-page>\` is a direct-or-descendant step of the one \`<crtr-pages>\` wrapper; it may not appear outside that wrapper.
+- Response-bearing components must be inside a \`<crtr-page>\`. Step order is document order.`,
+    },
+    {
+        kind: 'options',
+        tag: '<crtr-options>',
+        selectionLine: '`<crtr-options>` — known-alternative picker. Use when the human picks among known alternatives.',
+        contract: `\`<crtr-options>\`
+
+Response-bearing. The response is \`{selectedOptionIds:string[], comments:Comment[], freetext?:string}\`.
+
+${ELEMENT_RULES}
+
+Config JSON
+- \`options\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string}\`.
+- \`mode\` — required: \`single\` or \`multi\`.
+- \`label?:string\` — slot label; required by the multi-response page rule.
+- \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` — optional free-text affordance fields.
+
+Response rules
+- \`selectedOptionIds\` contains unique known option ids. A \`single\` response has at most one selected id and requires exactly one selection or nonempty allowed \`freetext\`; a \`multi\` response requires a selection, comment, or nonempty allowed \`freetext\`.
+- \`freetext\` is accepted only when \`allowFreetext:true\`.
+- ${COMMENT_SHAPE} Options accept only \`whole\` and \`option\` anchors; \`optionId\` must name a configured option.`,
+    },
+    {
+        kind: 'text',
+        tag: '<crtr-text>',
+        selectionLine: '`<crtr-text>` — prose field. Use when presenting or collecting prose; use `singleLine` for a subject, name, or URL.',
+        contract: `\`<crtr-text>\`
+
+Response-bearing. The response is \`{text:string, edited:boolean, comments:Comment[]}\`.
+
+${ELEMENT_RULES}
+
+Config JSON
+- \`initialText\` — required string, including an empty string.
+- \`label?:string\` — slot label; required by the multi-response page rule.
+- \`editable?:boolean\`, \`placeholder?:string\`, \`singleLine?:boolean\` — optional presentation/input settings.
+- \`singleLine:true\` is mutually exclusive with \`editable:false\`: a single-line field is always editable.
+
+Response rules
+- ${COMMENT_SHAPE} Text accepts only \`whole\` and \`range\` anchors.`,
+    },
+    {
+        kind: 'table',
+        tag: '<crtr-table>',
+        selectionLine: '`<crtr-table>` — structured rows and columns. Use when the human needs to inspect or select tabular data.',
+        contract: `\`<crtr-table>\`
+
+Display-only when both selection modes are \`none\`; response-bearing when \`rowSelect\` or \`columnSelect\` is \`single\` or \`multi\`. Its response when selectable is \`{selectedRowIds:string[], selectedColumnIds:string[], comments:Comment[]}\`.
+
+${ELEMENT_RULES}
+
+Config JSON
+- \`columns\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), align?:"left"|"right", mono?:boolean}\`.
+- \`rows?:\` array of \`{id:string (nonempty, unique), cells:Record<string,string|number|boolean|null>}\`.
+- \`source?:string\` — path to a local JSON file containing the rows array. At submit it is read, validated as \`rows\`, and embedded; the stored ticket is self-contained and elements never see \`source\`. \`rows\` and \`source\` are mutually exclusive.
+- \`rowSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
+- \`columnSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
+- \`label?:string\` — slot label; required by the multi-response page rule when the table is selectable.
+
+Response rules when selectable
+- Selected row and column ids are unique and must name configured ids. \`none\` permits no corresponding selected ids; \`single\` permits at most one.
+- ${COMMENT_SHAPE} Tables accept only \`whole\`, \`row\`, and \`column\` anchors. Row and column anchors must name configured ids.`,
+    },
+    {
+        kind: 'cards',
+        tag: '<crtr-cards>',
+        selectionLine: '`<crtr-cards>` — visual item picker. Use when the human chooses one or more rich, card-shaped alternatives.',
+        contract: `\`<crtr-cards>\`
+
+Response-bearing. The response is \`{selectedCardIds:string[], comments:Comment[]}\`.
+
+${ELEMENT_RULES}
+
+Config JSON
+- \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`.
+- \`source?:string\` — path to a local JSON file containing the cards array. At submit it is read, validated as \`cards\`, and embedded; the stored ticket is self-contained and elements never see \`source\`. \`cards\` and \`source\` are mutually exclusive.
+- \`mode\` — required: \`single\` or \`multi\`.
+- \`columns?:2|3\` — optional layout column count.
+- \`label?:string\` — slot label; required by the multi-response page rule.
+
+Response rules
+- \`selectedCardIds\` contains unique configured card ids. \`single\` permits at most one selected card.
+- ${COMMENT_SHAPE} Cards accept only \`whole\` and \`card\` anchors. Card anchors must name configured ids.`,
+    },
+    {
+        kind: 'chart',
+        tag: '<crtr-chart>',
+        selectionLine: '`<crtr-chart>` — data visualization. Use when a chart communicates a trend or comparison better than prose or a table.',
+        contract: `\`<crtr-chart>\`
+
+Display-only; it has no response.
+
+${ELEMENT_RULES}
+
+Config JSON
+- \`kind\` — required: \`line\`, \`bar\`, or \`area\`.
+- \`x\` — required nonempty string naming the x field.
+- \`y\` — required nonempty array of \`{field:string (nonempty), label?:string}\` series.
+- \`title?:string\`, \`data?:\` array of JSON row objects — optional display inputs.
+- \`source?:string\` — path to a local JSON file containing the \`data\` array. At submit it is read, validated as \`data\`, and embedded; the stored ticket is self-contained and elements never see \`source\`. \`data\` and \`source\` are mutually exclusive.`,
+    },
+];
+const docsByKind = new Map(BUILTIN_COMPONENT_DOCS.map((doc) => [doc.kind, doc]));
+/** Compact catalog rows shared by `human -h` and `human html list`. */
+export const BUILTIN_COMPONENT_SELECTION_LINES = BUILTIN_COMPONENT_DOCS.map((doc) => doc.selectionLine);
+export function componentDoc(kind) {
+    return docsByKind.get(kind);
+}
+export function componentKinds(productKinds) {
+    return [...BUILTIN_COMPONENT_DOCS.map((doc) => doc.kind), ...productKinds];
+}
+export function renderComponentCatalog(productComponents) {
+    const lines = [`<components count="${BUILTIN_COMPONENT_DOCS.length + productComponents.length}">`, ...BUILTIN_COMPONENT_SELECTION_LINES];
+    for (const component of productComponents) {
+        if (component.description === undefined && component.useWhen === undefined) {
+            lines.push('', `\`${component.kind}\``, component.display === true ? 'product-registered; display-only' : 'product-registered');
+            continue;
+        }
+        const details = [component.description, component.useWhen === undefined ? undefined : `${component.useWhen[0].toUpperCase()}${component.useWhen.slice(1)}`, ...(component.display === true ? ['Display-only'] : [])].filter((detail) => detail !== undefined);
+        lines.push('', `\`${component.kind}\` — ${details.join('. ')}`);
+    }
+    lines.push('</components>');
+    return lines.join('\n');
+}
+export function renderComponentContract(kind, productComponents) {
+    const builtin = componentDoc(kind);
+    if (builtin !== undefined)
+        return builtin.contract;
+    const productComponent = productComponents.find((component) => component.kind === kind);
+    if (productComponent !== undefined)
+        return `\`${kind}\`\n\n${productComponent.doc ?? `product-registered${productComponent.display === true ? '; display-only' : '; config is passed through unvalidated (unvalidated: true)'} — see the product's own docs`}`;
+    return undefined;
+}

package/dist/core/human/html-markdown.d.ts

@@ -0,0 +1,3 @@
+export declare const RICH_PAGE_PLACEHOLDER = "rich page \u2014 open in Northlight";
+/** Downconvert the semantic prose in one HTML fragment or complete document. */
+export declare function renderHtmlProseAsMarkdown(html: string): string;

package/dist/core/human/html-markdown.js

@@ -0,0 +1,288 @@
+// Bounded semantic HTML → Markdown for terminal page prose. This is deliberately
+// not an HTML renderer: slots keep their own terminal panels, while custom chrome
+// is reduced to text or one clear Northlight handoff.
+export const RICH_PAGE_PLACEHOLDER = 'rich page — open in Northlight';
+const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const RAW_TEXT_TAGS = new Set(['script', 'style', 'template']);
+const RICH_TAGS = new Set(['audio', 'button', 'canvas', 'dialog', 'embed', 'form', 'iframe', 'img', 'input', 'math', 'object', 'picture', 'select', 'svg', 'textarea', 'video']);
+const BLOCK_TAGS = new Set(['article', 'aside', 'blockquote', 'body', 'div', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'li', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'table', 'ul']);
+const INLINE_BREAK = '\uE001';
+/** Downconvert the semantic prose in one HTML fragment or complete document. */
+export function renderHtmlProseAsMarkdown(html) {
+    const root = { type: 'element', tag: '#root', attrs: new Map(), children: parseHtml(html) };
+    const body = findElement(root, 'body');
+    return renderBlocks(body?.children ?? root.children).trim();
+}
+function parseHtml(html) {
+    const root = { type: 'element', tag: '#root', attrs: new Map(), children: [] };
+    const stack = [root];
+    let cursor = 0;
+    const appendText = (value) => { if (value !== '')
+        stack.at(-1).children.push({ type: 'text', value }); };
+    while (cursor < html.length) {
+        const start = html.indexOf('<', cursor);
+        if (start === -1) {
+            appendText(html.slice(cursor));
+            break;
+        }
+        appendText(html.slice(cursor, start));
+        if (html.startsWith('<!--', start)) {
+            const end = html.indexOf('-->', start + 4);
+            cursor = end === -1 ? html.length : end + 3;
+            continue;
+        }
+        const end = tagEnd(html, start);
+        if (end === -1) {
+            appendText(html.slice(start));
+            break;
+        }
+        const token = html.slice(start, end);
+        if (/^<!|^<\?/i.test(token)) {
+            cursor = end;
+            continue;
+        }
+        const closing = /^<\s*\/\s*([^\s>]+)/.exec(token);
+        if (closing !== null) {
+            const tag = closing[1].toLowerCase();
+            for (let index = stack.length - 1; index > 0; index--) {
+                if (stack[index].tag === tag) {
+                    stack.length = index;
+                    break;
+                }
+            }
+            cursor = end;
+            continue;
+        }
+        const opening = /^<\s*([^\s/>]+)/.exec(token);
+        if (opening === null) {
+            appendText(token);
+            cursor = end;
+            continue;
+        }
+        const tag = opening[1].toLowerCase();
+        const element = { type: 'element', tag, attrs: parseAttributes(token), children: [] };
+        stack.at(-1).children.push(element);
+        const selfClosing = /\/\s*>$/.test(token) || VOID_TAGS.has(tag);
+        if (RAW_TEXT_TAGS.has(tag) && !selfClosing) {
+            const close = new RegExp(`<\\s*/\\s*${escapeRegExp(tag)}\\s*>`, 'ig');
+            close.lastIndex = end;
+            const match = close.exec(html);
+            if (match !== null) {
+                element.children.push({ type: 'text', value: html.slice(end, match.index) });
+                cursor = close.lastIndex;
+            }
+            else
+                cursor = html.length;
+            continue;
+        }
+        if (!selfClosing)
+            stack.push(element);
+        cursor = end;
+    }
+    return root.children;
+}
+function tagEnd(html, start) {
+    let quote;
+    for (let index = start + 1; index < html.length; index++) {
+        const character = html[index];
+        if (quote !== undefined) {
+            if (character === quote)
+                quote = undefined;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (character === '>')
+            return index + 1;
+    }
+    return -1;
+}
+function parseAttributes(token) {
+    const attrs = new Map();
+    const source = token.slice(1, -1);
+    const firstSpace = source.search(/\s/);
+    if (firstSpace === -1)
+        return attrs;
+    const body = source.slice(firstSpace);
+    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 findElement(node, tag) {
+    if (node.tag === tag)
+        return node;
+    for (const child of node.children)
+        if (child.type === 'element') {
+            const found = findElement(child, tag);
+            if (found !== undefined)
+                return found;
+        }
+    return undefined;
+}
+function renderBlocks(nodes) {
+    const blocks = [];
+    for (const node of nodes) {
+        const block = renderBlock(node).trim();
+        if (block !== '')
+            blocks.push(block);
+    }
+    return blocks.join('\n\n');
+}
+function renderBlock(node) {
+    if (node.type === 'text')
+        return markdownText(node.value).trim();
+    if (isInteractiveSlot(node))
+        return '';
+    if (isStructuralWrapper(node))
+        return renderBlocks(node.children);
+    if (isRichBlock(node))
+        return RICH_PAGE_PLACEHOLDER;
+    if (/^h[1-6]$/.test(node.tag))
+        return `${'#'.repeat(Number(node.tag[1]))} ${renderInline(node.children)}`;
+    if (node.tag === 'p')
+        return renderInline(node.children);
+    if (node.tag === 'blockquote')
+        return quote(renderBlocks(node.children));
+    if (node.tag === 'pre')
+        return fencedCode(node);
+    if (node.tag === 'ul' || node.tag === 'ol')
+        return renderList(node);
+    if (node.tag === 'table')
+        return renderTable(node);
+    if (node.tag === 'hr')
+        return '---';
+    if (node.tag === 'br')
+        return '';
+    if (BLOCK_TAGS.has(node.tag))
+        return node.children.some((child) => child.type === 'element' && BLOCK_TAGS.has(child.tag)) ? renderBlocks(node.children) : renderInline(node.children);
+    return renderInline(node.children);
+}
+function renderInline(nodes) {
+    return nodes.map(renderInlineNode).join('').replace(/\s+/g, ' ').replaceAll(INLINE_BREAK, '  \n').trim();
+}
+function renderInlineNode(node) {
+    if (node.type === 'text')
+        return markdownText(node.value);
+    if (isInteractiveSlot(node) || RAW_TEXT_TAGS.has(node.tag))
+        return '';
+    const content = renderInline(node.children);
+    if (node.tag === 'br')
+        return INLINE_BREAK;
+    if (isStructuralWrapper(node))
+        return content;
+    if (node.tag === 'strong' || node.tag === 'b')
+        return content === '' ? '' : `**${content}**`;
+    if (node.tag === 'em' || node.tag === 'i')
+        return content === '' ? '' : `*${content}*`;
+    if (node.tag === 'code')
+        return codeSpan(textContent(node));
+    if (node.tag === 'a') {
+        const href = node.attrs.get('href');
+        return href === undefined || href === '' || content === '' ? content : `[${content}](${markdownUrl(href)})`;
+    }
+    if (BLOCK_TAGS.has(node.tag))
+        return content;
+    // Unknown inline markup is prose, not terminal UI. Keeping its text prevents
+    // raw `<span>`-style tags from leaking through termrender.
+    return content;
+}
+function renderList(element) {
+    const items = element.children.filter((child) => child.type === 'element' && child.tag === 'li');
+    return items.map((item, index) => {
+        const nested = item.children.filter((child) => child.type === 'element' && (child.tag === 'ul' || child.tag === 'ol'));
+        const content = item.children.filter((child) => !(child.type === 'element' && (child.tag === 'ul' || child.tag === 'ol')));
+        const marker = element.tag === 'ol' ? `${index + 1}.` : '-';
+        const first = renderListItem(content);
+        const children = nested.map(renderList).filter(Boolean).map((list) => list.split('\n').map((line) => `  ${line}`).join('\n'));
+        return [first === '' ? marker : `${marker} ${first}`, ...children].join('\n');
+    }).join('\n');
+}
+function renderListItem(nodes) {
+    const blocks = renderBlocks(nodes);
+    return blocks.replace(/\n\n+/g, '\n').replace(/\n/g, '\n  ');
+}
+function renderTable(table) {
+    const rows = findElements(table, 'tr').map((row) => row.children.filter((child) => child.type === 'element' && (child.tag === 'th' || child.tag === 'td')).map((cell) => renderInline(cell.children).replace(/\|/g, '\\|'))).filter((row) => row.length > 0);
+    if (rows.length === 0)
+        return '';
+    const width = Math.max(...rows.map((row) => row.length));
+    const normalized = rows.map((row) => Array.from({ length: width }, (_, index) => row[index] ?? ''));
+    const header = normalized[0];
+    const data = normalized.slice(1);
+    return [`| ${header.join(' | ')} |`, `| ${header.map(() => '---').join(' | ')} |`, ...data.map((row) => `| ${row.join(' | ')} |`)].join('\n');
+}
+function fencedCode(pre) {
+    const code = pre.children.find((child) => child.type === 'element' && child.tag === 'code');
+    const source = textContent(code ?? pre).replace(/\r\n?/g, '\n').replace(/\n$/, '');
+    const fence = source.includes('```') ? '~~~' : '```';
+    const language = code?.attrs.get('class')?.match(/(?:^|\s)language-([^\s]+)/)?.[1] ?? '';
+    return `${fence}${language}\n${source}\n${fence}`;
+}
+function quote(markdown) {
+    return markdown.split('\n').map((line) => line === '' ? '>' : `> ${line}`).join('\n');
+}
+function textContent(node) {
+    if (node.type === 'text')
+        return decodeEntities(node.value);
+    return node.children.map(textContent).join('');
+}
+function markdownText(value) {
+    return decodeEntities(value)
+        .replace(/\\/g, '\\\\')
+        .replace(/[<>]/g, (character) => character === '<' ? '&lt;' : '&gt;')
+        .replace(/(^|\n)(?=(?:#{1,6}\s|[-+]\s))/g, '$1\\')
+        .replace(/(^|\n)(\d+)([.)])(?=\s)/g, '$1$2\\$3')
+        .replace(/([\[\]*_`|])/g, '\\$1');
+}
+function codeSpan(value) {
+    const source = value.replace(/\r?\n/g, ' ');
+    const delimiter = source.includes('`') ? '``' : '`';
+    return `${delimiter}${source}${delimiter}`;
+}
+function markdownUrl(value) {
+    return `<${decodeEntities(value).replace(/>/g, '%3E')}>`;
+}
+function isStructuralWrapper(node) {
+    return node.tag === 'crtr-pages' || node.tag === 'crtr-page';
+}
+function isInteractiveSlot(node) {
+    return !isStructuralWrapper(node) && (node.tag === 'crtr-slot' || node.tag.startsWith('crtr-'));
+}
+function isRichBlock(node) {
+    if (RAW_TEXT_TAGS.has(node.tag) || RICH_TAGS.has(node.tag) || node.tag.includes('-'))
+        return true;
+    if (!BLOCK_TAGS.has(node.tag))
+        return false;
+    return [...node.attrs.keys()].some((attribute) => attribute === 'class' || attribute === 'style' || attribute === 'id' || attribute.startsWith('on'));
+}
+function findElements(node, tag) {
+    const found = [];
+    for (const child of node.children)
+        if (child.type === 'element') {
+            if (child.tag === tag)
+                found.push(child);
+            found.push(...findElements(child, tag));
+        }
+    return found;
+}
+function decodeEntities(value) {
+    return value.replace(/&(?:amp|apos|gt|lt|quot);|&#(?:x[0-9a-f]+|\d+);/gi, (entity) => {
+        const named = { '&amp;': '&', '&apos;': "'", '&gt;': '>', '&lt;': '<', '&quot;': '"' };
+        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);
+        try {
+            return Number.isFinite(numeric) ? String.fromCodePoint(numeric) : entity;
+        }
+        catch {
+            return entity;
+        }
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -1,6 +1,22 @@
+import type { PageComponentRegistration, ProductPageComponents } from '../../types.js';
 /** The page slot kinds crtr validates and renders itself. */
 export declare const BUILTIN_PAGE_KINDS: readonly ["options", "text", "table", "cards", "chart"];
-/** Normalize the product-registered page slot catalog from raw config. */
-export declare function normalizePageComponents(raw: unknown): string[];
+export declare const STRUCTURAL_PAGE_KINDS: readonly ["crtr-pages", "crtr-page"];
+export interface PageComponentCatalogEntry {
+    kind: string;
+    tag: string;
+    description: string;
+    useWhen: string;
+    doc?: string;
+    builtin: boolean;
+    structural: boolean;
+}
+/** Normalize legacy kind strings and documented product component registrations. */
+export declare function normalizePageComponents(raw: unknown): PageComponentRegistration[];
+/** Names-only projection for page validation and rendering consumers. */
+export declare function pageComponentKinds(components: readonly PageComponentRegistration[]): string[];
+/** Full built-in + product catalog for CLI discovery. */
+export declare function pageComponentCatalog(components: readonly PageComponentRegistration[]): PageComponentCatalogEntry[];
 /** Whether crtr or the product catalog registers a page slot kind. */
-export declare function isRegisteredPageKind(kind: string, productKinds: string[]): boolean;
+export declare function productPageComponent(kind: string, components: ProductPageComponents): PageComponentRegistration | undefined;
+export declare function isRegisteredPageKind(kind: string, productComponents: ProductPageComponents): boolean;

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

@@ -1,7 +1,17 @@
 /** The page slot kinds crtr validates and renders itself. */
 export const BUILTIN_PAGE_KINDS = ['options', 'text', 'table', 'cards', 'chart'];
+export const STRUCTURAL_PAGE_KINDS = ['crtr-pages', 'crtr-page'];
 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: 'crtr-pages', tag: 'crtr-pages', description: 'ordered wrapper for one or more page steps', useWhen: 'use when the page has a response-bearing component or multiple steps', builtin: true, structural: true },
+    { kind: 'crtr-page', tag: 'crtr-page', description: 'one step inside a crtr-pages flow', useWhen: 'use for each step the human sees and completes in sequence', builtin: true, structural: true },
+    { kind: 'options', tag: 'crtr-options', description: 'known alternatives with single or multiple selection', useWhen: 'use when the human picks among known alternatives, optionally with freetext', builtin: true, structural: false },
+    { kind: 'text', tag: 'crtr-text', description: 'editable or read-only text surface', useWhen: 'use when the human writes, edits, or reviews text', builtin: true, structural: false },
+    { kind: 'table', tag: 'crtr-table', 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: 'crtr-cards', description: 'visual records with optional selection', useWhen: 'use when the human compares or picks richer items than a compact option list can carry', builtin: true, structural: false },
+    { kind: 'chart', tag: 'crtr-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 },
+];
 function describeEntry(entry) {
     try {
         const json = JSON.stringify(entry);
@@ -11,33 +21,80 @@ function describeEntry(entry) {
         return String(entry);
     }
 }
-/** Normalize the product-registered page slot catalog from raw config. */
+function optionalText(value, field, index) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`page_components[${index}].${field} must be a non-empty string; received ${describeEntry(value)}`);
+    }
+    return value.trim();
+}
+/** Normalize legacy kind strings and documented product component registrations. */
 export function normalizePageComponents(raw) {
     if (raw === undefined)
         return [];
-    if (!Array.isArray(raw)) {
+    if (!Array.isArray(raw))
         throw new Error(`page_components must be an array; received ${describeEntry(raw)}`);
-    }
     const seen = new Set();
     return raw.map((entry, index) => {
-        if (typeof entry !== 'string') {
-            throw new Error(`page_components[${index}] must be a string; offending entry: ${describeEntry(entry)}`);
-        }
-        const kind = entry.trim();
-        if (!PAGE_KIND_PATTERN.test(kind)) {
-            throw new Error(`page_components[${index}] has invalid page kind ${describeEntry(entry)} after trimming; expected /^[a-z][a-z0-9-]{0,63}$/`);
+        let registration;
+        if (typeof entry === 'string') {
+            registration = { kind: entry.trim() };
         }
-        if (BUILTIN_PAGE_KIND_SET.has(kind)) {
-            throw new Error(`page_components[${index}] ${describeEntry(entry)} collides with built-in page kind "${kind}"`);
+        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(`page_components[${index}] has unknown field(s): ${extra.join(', ')}`);
+            if (typeof object['kind'] !== 'string')
+                throw new Error(`page_components[${index}].kind must be a string; offending entry: ${describeEntry(entry)}`);
+            if (object['display'] !== undefined && typeof object['display'] !== 'boolean')
+                throw new Error(`page_components[${index}].display must be a boolean; offending entry: ${describeEntry(entry)}`);
+            registration = {
+                kind: object['kind'].trim(),
+                ...(optionalText(object['description'], 'description', index) === undefined ? {} : { description: optionalText(object['description'], 'description', index) }),
+                ...(optionalText(object['useWhen'], 'useWhen', index) === undefined ? {} : { useWhen: optionalText(object['useWhen'], 'useWhen', index) }),
+                ...(optionalText(object['doc'], 'doc', index) === undefined ? {} : { doc: optionalText(object['doc'], 'doc', index) }),
+                ...(object['display'] === true ? { display: true } : {}),
+            };
         }
-        if (seen.has(kind)) {
-            throw new Error(`page_components[${index}] ${describeEntry(entry)} duplicates page kind "${kind}"`);
+        else {
+            throw new Error(`page_components[${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(`page_components[${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(`page_components[${index}] collides with built-in page kind "${kind}"`);
+        if (seen.has(kind))
+            throw new Error(`page_components[${index}] duplicates page kind "${kind}"`);
         seen.add(kind);
-        return kind;
+        return registration;
     });
 }
+/** 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: component.kind,
+            description: component.description ?? 'product-registered page component',
+            useWhen: component.useWhen ?? 'use when the product component matches the structured UI the human needs',
+            ...(component.doc === undefined ? {} : { doc: component.doc }),
+            builtin: false,
+            structural: false,
+        })),
+    ];
+}
 /** Whether crtr or the product catalog registers a page slot kind. */
-export function isRegisteredPageKind(kind, productKinds) {
-    return BUILTIN_PAGE_KIND_SET.has(kind) || productKinds.includes(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;
 }

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

@@ -1,3 +1,4 @@
-import { type PageManifest } from './page-schema.js';
+import type { ProductPageComponents } from '../../types.js';
+import type { PageManifest } from './page-schema.js';
 /** Render one page ticket's authored document as the runtime's HTML payload. */
-export declare function renderPageHtml(manifest: PageManifest, document: string, productKinds?: string[]): string;
+export declare function renderPageHtml(manifest: PageManifest, document: string, productKinds?: ProductPageComponents): string;