@north-light/crouter 0.3.198 → 0.3.200

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

@@ -13,21 +13,19 @@ function uniqueIds(items, ctx, label) {
         seen.add(item.id);
     });
 }
+// Response comments qualify the answer itself, so anchors name only answerable structure:
+// one of a question's options, or a table row. Feedback on rendered page content — including
+// the question text itself — is a ticket-level feedback comment (feedback.ts), not part of
+// any response.
 export const commentAnchorSchema = z.discriminatedUnion('kind', [
-    z.object({ kind: z.literal('whole') }).strict(),
     z.object({ kind: z.literal('option'), optionId: itemIdSchema }).strict(),
     z.object({ kind: z.literal('row'), rowId: itemIdSchema }).strict(),
-    z.object({ kind: z.literal('column'), columnId: itemIdSchema }).strict(),
-    z.object({ kind: z.literal('card'), cardId: itemIdSchema }).strict(),
-    z.object({ kind: z.literal('range'), start: z.number().int().nonnegative(), end: z.number().int().nonnegative(), quote: z.string() }).strict().superRefine((anchor, ctx) => {
-        if (anchor.end < anchor.start)
-            ctx.addIssue({ code: 'custom', path: ['end'], message: 'range end must be greater than or equal to start' });
-    }),
 ]);
 export const commentSchema = z.object({ id: z.string().min(1), anchor: commentAnchorSchema, text: z.string() }).strict();
 export const optionSchema = z.object({ id: itemIdSchema, label: z.string().min(1), description: z.string().optional() }).strict();
 export const optionsConfigSchema = z.object({
     label: z.string().optional(),
+    body: z.string().optional(),
     options: z.array(optionSchema).min(1).superRefine((items, ctx) => uniqueIds(items, ctx, 'option')),
     mode: z.enum(['single', 'multi']),
     allowFreetext: z.boolean().optional(),
@@ -35,49 +33,38 @@ export const optionsConfigSchema = z.object({
     freetextPlaceholder: z.string().optional(),
 }).strict();
 export const optionsResponseSchema = z.object({ selectedOptionIds: z.array(itemIdSchema), comments: z.array(commentSchema), freetext: z.string().optional() }).strict();
-// `singleLine` swaps the writing surface for one compact form field — a subject line, a name,
-// a URL. It is an input by definition, so it is always editable and `editable: false` on it is
-// an authoring mistake rather than a read-only one-liner.
-export const textConfigSchema = z.object({ label: z.string().optional(), initialText: z.string(), editable: z.boolean().optional(), placeholder: z.string().optional(), singleLine: z.boolean().optional() }).strict().superRefine((config, ctx) => {
-    if (config.singleLine === true && config.editable === false)
-        ctx.addIssue({ code: 'custom', path: ['editable'], message: 'single-line text is always editable; drop editable: false' });
-});
-export const textResponseSchema = z.object({ text: z.string(), edited: z.boolean(), comments: z.array(commentSchema) }).strict();
+// Text is a writing surface, always: its whole point is the string the user hands back, so
+// there is no read-only mode. `singleLine` only swaps the multi-line surface for one compact
+// form field — a subject line, a name, a URL.
+export const textConfigSchema = z.object({ label: z.string().optional(), initialText: z.string(), placeholder: z.string().optional(), singleLine: z.boolean().optional() }).strict();
+export const textResponseSchema = z.object({ text: z.string(), edited: z.boolean() }).strict();
 export const tableColumnSchema = z.object({ id: itemIdSchema, label: z.string().min(1), align: z.enum(['left', 'right']).optional(), mono: z.boolean().optional() }).strict();
 export const tableCellSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 export const tableRowSchema = z.object({ id: itemIdSchema, cells: z.record(z.string(), tableCellSchema) }).strict();
 export const tableRowsSchema = z.array(tableRowSchema).superRefine((items, ctx) => uniqueIds(items, ctx, 'row'));
 const tableConfigFields = {
     label: z.string().optional(),
+    body: z.string().optional(),
     columns: z.array(tableColumnSchema).min(1).superRefine((items, ctx) => uniqueIds(items, ctx, 'column')),
     rows: tableRowsSchema.optional(),
     rowSelect: selectModeSchema.default('none'),
     columnSelect: selectModeSchema.default('none'),
 };
-/** Stored table config: its data is always embedded. */
+/** Table config: its data is always embedded. */
 export const tableConfigSchema = z.object(tableConfigFields).strict();
-/** Authored table config: `source` is resolved before the manifest is stored. */
-export const authoredTableConfigSchema = z.object({ ...tableConfigFields, source: z.string() }).strict().superRefine((config, ctx) => {
-    if (config.rows !== undefined)
-        ctx.addIssue({ code: 'custom', message: 'table rows and source are mutually exclusive' });
-});
 export const tableResponseSchema = z.object({ selectedRowIds: z.array(itemIdSchema), selectedColumnIds: z.array(itemIdSchema), comments: z.array(commentSchema) }).strict();
 export const cardSchema = z.object({ id: itemIdSchema, title: z.string().min(1), subtitle: z.string().optional(), body: z.string().optional(), tag: z.string().optional() }).strict();
 export const cardsSchema = z.array(cardSchema).superRefine((items, ctx) => uniqueIds(items, ctx, 'card'));
 const cardsConfigFields = {
     label: z.string().optional(),
+    body: z.string().optional(),
     cards: cardsSchema.optional(),
     mode: z.enum(['single', 'multi']),
     columns: z.union([z.literal(2), z.literal(3)]).optional(),
 };
-/** Stored cards config: its data is always embedded. */
+/** Cards config: its data is always embedded. */
 export const cardsConfigSchema = z.object(cardsConfigFields).strict();
-/** Authored cards config: `source` is resolved before the manifest is stored. */
-export const authoredCardsConfigSchema = z.object({ ...cardsConfigFields, source: z.string() }).strict().superRefine((config, ctx) => {
-    if (config.cards !== undefined)
-        ctx.addIssue({ code: 'custom', message: 'cards data and source are mutually exclusive' });
-});
-export const cardsResponseSchema = z.object({ selectedCardIds: z.array(itemIdSchema), comments: z.array(commentSchema) }).strict();
+export const cardsResponseSchema = z.object({ selectedCardIds: z.array(itemIdSchema) }).strict();
 export const chartSeriesSchema = z.object({ field: z.string().min(1), label: z.string().optional() }).strict();
 export const chartDataRowsSchema = z.array(z.record(z.string(), z.unknown()));
 const chartConfigFields = {
@@ -87,26 +74,27 @@ const chartConfigFields = {
     title: z.string().optional(),
     data: chartDataRowsSchema.optional(),
 };
-/** Stored chart config: its data is always embedded. */
+/** Chart config: its data is always embedded. */
 export const chartConfigSchema = z.object(chartConfigFields).strict();
-/** Authored chart config: `source` is resolved before the manifest is stored. */
-export const authoredChartConfigSchema = z.object({ ...chartConfigFields, source: z.string() }).strict().superRefine((config, ctx) => {
-    if (config.data !== undefined)
-        ctx.addIssue({ code: 'custom', message: 'chart data and source are mutually exclusive' });
-});
-const sourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), profileName: z.string().optional(), nodeId: z.string().optional() }).strict();
+const sourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), emittedAt: z.string().datetime({ offset: true }).optional(), profileName: z.string().optional(), nodeId: z.string().optional() }).strict();
+const deliverySchema = z.object({ placement: z.enum(['inline', 'panel']), inbox: z.boolean(), reply: z.boolean() }).strict();
 const rawSlotSchema = z.object({ id: idSchema.optional(), kind: z.string().min(1), step: z.number().int().nonnegative(), config: jsonObjectSchema, unvalidated: z.literal(true).optional(), display: z.literal(true).optional() }).strict();
 const rawPageManifestSchema = z.object({
-    schema: z.literal('crtr.page/v1'),
-    dialect: z.enum(['md', 'html']),
+    schema: z.literal('crtr.page/v2'),
+    dialect: z.enum(['jsx', 'html']),
     title: z.string().trim().min(1),
     subtitle: z.string().optional(),
-    placement: z.enum(['inline', 'panel']),
-    document: z.enum(['page.md', 'page.html']),
+    delivery: deliverySchema,
+    document: z.enum(['page.tsx', 'page.html']),
     steps: z.number().int().positive(),
     slots: z.array(rawSlotSchema),
     source: sourceSchema.optional(),
-}).strict();
+}).strict().superRefine((manifest, ctx) => {
+    if ((manifest.dialect === 'jsx') !== (manifest.document === 'page.tsx'))
+        ctx.addIssue({ code: 'custom', path: ['document'], message: 'document must agree with dialect' });
+    if (manifest.dialect === 'html' && (manifest.steps !== 1 || manifest.slots.length !== 0))
+        ctx.addIssue({ code: 'custom', path: ['slots'], message: 'HTML pages have exactly one step and no slots' });
+});
 export const BUILTIN_PAGE_CONFIG_SCHEMAS = {
     options: optionsConfigSchema,
     text: textConfigSchema,
@@ -114,13 +102,6 @@ export const BUILTIN_PAGE_CONFIG_SCHEMAS = {
     cards: cardsConfigSchema,
     chart: chartConfigSchema,
 };
-const AUTHORED_PAGE_CONFIG_SCHEMAS = {
-    options: optionsConfigSchema,
-    text: textConfigSchema,
-    table: z.union([tableConfigSchema, authoredTableConfigSchema]),
-    cards: z.union([cardsConfigSchema, authoredCardsConfigSchema]),
-    chart: z.union([chartConfigSchema, authoredChartConfigSchema]),
-};
 export const BUILTIN_PAGE_RESPONSE_SCHEMAS = {
     options: optionsResponseSchema,
     text: textResponseSchema,
@@ -145,10 +126,8 @@ export function isResponseBearingSlot(slot) {
 }
 function validateManifest(parsed, productComponents, authored) {
     const manifest = rawPageManifestSchema.parse(parsed);
-    if (manifest.document !== (manifest.dialect === 'md' ? 'page.md' : 'page.html'))
-        throw new Error(`page document "${manifest.document}" does not match ${manifest.dialect} dialect`);
-    if (manifest.dialect === 'md' && manifest.steps !== 1)
-        throw new Error(`md page steps must be 1; received ${manifest.steps}`);
+    if (!authored && manifest.dialect === 'html')
+        return manifest;
     const seen = new Set();
     const slots = manifest.slots.map((raw, index) => {
         if (raw.step >= manifest.steps)
@@ -159,29 +138,38 @@ function validateManifest(parsed, productComponents, authored) {
                 throw new Error(`built-in slot kind "${raw.kind}" cannot be unvalidated`);
             if (raw.display === true)
                 throw new Error(`built-in slot kind "${raw.kind}" cannot set display: true`);
-            const result = (authored ? AUTHORED_PAGE_CONFIG_SCHEMAS : BUILTIN_PAGE_CONFIG_SCHEMAS)[raw.kind].safeParse(raw.config);
+            const result = BUILTIN_PAGE_CONFIG_SCHEMAS[raw.kind].safeParse(raw.config);
             if (!result.success)
                 throw new Error(`invalid config for slot ${raw.id === undefined ? `#${index}` : `"${raw.id}"`} (${raw.kind}): ${issueText(result.error)}`);
+            // Authoring-time only: persisted manifests predate this rule and must keep reading.
+            if (authored && raw.kind === 'options') {
+                const options = result.data;
+                const slotName = raw.id === undefined ? `#${index}` : `"${raw.id}"`;
+                if ((options.label ?? '').trim() === '')
+                    throw new Error(`slot ${slotName} (options): label is required — the question itself, drawn as the bold first line`);
+                if ((options.body ?? '').trim() === '')
+                    throw new Error(`slot ${slotName} (options): body is required — the context under the question a label cannot carry`);
+            }
             slot = { ...(raw.id === undefined ? {} : { id: raw.id }), kind: raw.kind, step: raw.step, config: result.data };
         }
         else {
-            const component = productPageComponent(raw.kind, productComponents);
-            if (component === undefined)
+            const component = productComponents === undefined ? undefined : productPageComponent(raw.kind, productComponents);
+            if (authored && component === undefined)
                 throw new Error(`unregistered page slot kind "${raw.kind}" at slot #${index}`);
             if (raw.unvalidated !== true)
-                throw new Error(`registered product slot kind "${raw.kind}" must set unvalidated: true`);
-            if (!authored && raw.display !== (component.display === true ? true : undefined))
-                throw new Error(component.display === true
-                    ? `display product slot kind "${raw.kind}" must set display: true`
-                    : `non-display product slot kind "${raw.kind}" cannot set display: true`);
-            if (authored && raw.display === true && component.display !== true)
-                throw new Error(`non-display product slot kind "${raw.kind}" cannot set display: true`);
-            slot = { ...(raw.id === undefined ? {} : { id: raw.id }), kind: raw.kind, step: raw.step, config: raw.config, unvalidated: true, ...(component.display === true ? { display: true } : {}) };
+                throw new Error(`registered page slot kind "${raw.kind}" must set unvalidated: true`);
+            if (!authored)
+                slot = { ...(raw.id === undefined ? {} : { id: raw.id }), kind: raw.kind, step: raw.step, config: raw.config, unvalidated: true, ...(raw.display === true ? { display: true } : {}) };
+            else {
+                if (raw.display === true && component?.display !== true)
+                    throw new Error(`non-display page slot kind "${raw.kind}" cannot set display: true`);
+                slot = { ...(raw.id === undefined ? {} : { id: raw.id }), kind: raw.kind, step: raw.step, config: raw.config, unvalidated: true, ...(component?.display === true ? { display: true } : {}) };
+            }
         }
         if (isResponseBearingSlot(slot) && slot.id === undefined) {
             throw new Error(slot.unvalidated === true
-                ? `product slot kind "${slot.kind}" at slot #${index} requires an id="…" attribute on its <crtr-slot> element`
-                : `response-bearing slot kind "${slot.kind}" at slot #${index} requires an id="…" attribute on its element`);
+                ? `product slot kind "${slot.kind}" at slot #${index} requires an id prop`
+                : `response-bearing slot kind "${slot.kind}" at slot #${index} requires an id prop`);
         }
         if (slot.id !== undefined) {
             if (seen.has(slot.id))
@@ -192,26 +180,25 @@ function validateManifest(parsed, productComponents, authored) {
     });
     return { ...manifest, slots };
 }
-/** Validate a persisted manifest. Source paths are rejected: pages render only embedded data. */
-export function validatePageManifest(parsed, productComponents = []) {
-    return validateManifest(parsed, productComponents, false);
+/** Validate a persisted manifest. Publish-time validation made its slots authoritative, so reads do not resolve a component catalog. */
+export function validatePageManifest(parsed) {
+    return validateManifest(parsed, undefined, false);
 }
-/** Validate an authored manifest before submit. Source paths are resolved by `snapshotPageSources`. */
+/** Validate a manifest derived from an authored page, where the display flag comes from the registration rather than the source. */
 export function validateAuthoredPageManifest(parsed, productComponents = []) {
     return validateManifest(parsed, productComponents, true);
 }
-export function createPageManifestSchema(productComponents = []) {
+export function createPageManifestSchema() {
     return z.custom((value) => {
         try {
-            validatePageManifest(value, productComponents);
+            validatePageManifest(value);
             return true;
         }
         catch {
             return false;
         }
-    }, { error: 'invalid page manifest' }).transform((value) => validatePageManifest(value, productComponents));
+    }, { error: 'invalid page manifest' }).transform((value) => validatePageManifest(value));
 }
-/** Built-in-only manifest schema; product-aware callers use createPageManifestSchema. */
 export const pageManifestSchema = createPageManifestSchema();
 function assertUnique(values, slotId, field) {
     if (new Set(values).size !== values.length)
@@ -221,30 +208,16 @@ function validateComments(slot, comments) {
     const config = slot.config;
     for (const comment of comments) {
         const anchor = comment.anchor;
-        if (anchor.kind === 'whole')
-            continue;
         if (slot.kind === 'options' && anchor.kind === 'option') {
             if (!config.options.some((option) => option.id === anchor.optionId))
                 throw new Error(`slot "${slot.id}" comment names unknown option id "${anchor.optionId}"`);
             continue;
         }
-        if (slot.kind === 'text' && anchor.kind === 'range')
-            continue;
         if (slot.kind === 'table' && anchor.kind === 'row') {
             if (!(config.rows ?? []).some((row) => row.id === anchor.rowId))
                 throw new Error(`slot "${slot.id}" comment names unknown row id "${anchor.rowId}"`);
             continue;
         }
-        if (slot.kind === 'table' && anchor.kind === 'column') {
-            if (!config.columns.some((column) => column.id === anchor.columnId))
-                throw new Error(`slot "${slot.id}" comment names unknown column id "${anchor.columnId}"`);
-            continue;
-        }
-        if (slot.kind === 'cards' && anchor.kind === 'card') {
-            if (!(config.cards ?? []).some((card) => card.id === anchor.cardId))
-                throw new Error(`slot "${slot.id}" comment names unknown card id "${anchor.cardId}"`);
-            continue;
-        }
         throw new Error(`slot "${slot.id}" does not allow comment anchor kind "${anchor.kind}"`);
     }
 }
@@ -281,7 +254,6 @@ function parseResponse(slot, raw) {
         const result = textResponseSchema.safeParse(raw);
         if (!result.success)
             throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
-        validateComments(slot, result.data.comments);
         return result.data;
     }
     if (slot.kind === 'table') {
@@ -319,7 +291,6 @@ function parseResponse(slot, raw) {
                 throw new Error(`slot "${slot.id}" selects unknown card id "${id}"`);
         if (config.mode === 'single' && response.selectedCardIds.length > 1)
             throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedCardIds.length} card ids`);
-        validateComments(slot, response.comments);
         return response;
     }
     throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);
@@ -344,5 +315,5 @@ function validateResponses(manifest, raw, partial) {
 }
 /** Validate a complete final response map. */
 export function validatePageResponses(manifest, responses) { return validateResponses(manifest, responses, false); }
-/** Validate an autosaved response map, permitting omitted response-bearing slots. */
+/** Validate an autosaved response map, permitting omitted response-bearing components. */
 export function validatePartialPageResponses(manifest, responses) { return validateResponses(manifest, responses, true); }

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

@@ -1,4 +1,4 @@
-/** Build a complete HTML page from title, subtitle, and body for internal producers. */
+/** Build a complete TSX page from title, subtitle, and body for internal producers. */
 export declare function synthesizedPageDocument(title: string, subtitle: string, body: string, responseBearing: boolean): string;
 /** Materialize an internally generated document into a private temp dir; the caller removes it after submission. */
 export declare function writeSynthesizedPage(document: string): {

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

@@ -1,33 +1,30 @@
 import { join } from 'node:path';
 import { mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-function escapeHtml(value) {
-    return value.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
-}
-function bodyHtml(body) {
+/** Text reaches JSX as a string expression, so arbitrary bytes need no markup escaping. */
+function jsxText(value) { return `{${JSON.stringify(value)}}`; }
+function bodyJsx(body) {
     if (body === '')
         return '';
-    return `<p>${escapeHtml(body).replace(/\r?\n/g, '<br>')}</p>`;
+    const lines = body.replace(/\r\n/g, '\n').split('\n');
+    return `      <p className="whitespace-pre-wrap">${lines.map(jsxText).join('<br />')}</p>\n`;
 }
-/** Build a complete HTML page from title, subtitle, and body for internal producers. */
+/** Build a complete TSX page from title, subtitle, and body for internal producers. */
 export function synthesizedPageDocument(title, subtitle, body, responseBearing) {
-    const contents = bodyHtml(body);
-    const interactive = responseBearing
-        ? `<crtr-pages><crtr-page><crtr-text id="response"><script type="application/json">{"initialText":"","editable":true}</script></crtr-text></crtr-page></crtr-pages>`
-        : '';
-    return `<!doctype html>
-<html><head>
-<meta name="crtr-page-title" content="${escapeHtml(title)}">
-<meta name="crtr-page-subtitle" content="${escapeHtml(subtitle)}">
-</head><body>
-${contents}${contents === '' || interactive === '' ? '' : '\n'}${interactive}
-</body></html>
+    const interactive = responseBearing ? `      <UserText id="response" initialText="" />\n` : '';
+    const subtitleProp = subtitle === '' ? '' : ` subtitle=${jsxText(subtitle)}`;
+    return `export default function SynthesizedPage() {
+  return (
+    <Page title=${jsxText(title)}${subtitleProp}>
+${bodyJsx(body)}${interactive}    </Page>
+  );
+}
 `;
 }
 /** Materialize an internally generated document into a private temp dir; the caller removes it after submission. */
 export function writeSynthesizedPage(document) {
     const dir = mkdtempSync(join(tmpdir(), 'crtr-human-page-'));
-    const path = join(dir, 'page.html');
+    const path = join(dir, 'page.tsx');
     writeFileSync(path, document, { encoding: 'utf8', mode: 0o600 });
     return { dir, path };
 }

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

@@ -1,29 +1,14 @@
 import type { ProductPageComponents } from '../../types.js';
-import { type AuthoredPageManifest, type PageManifest, type PageSource } from './page-schema.js';
-/** Dialects retained in persisted manifests. New page authoring is HTML-only. */
-export type PageDialect = 'md' | 'html';
-export type AuthoredPageDialect = 'html';
-export type PageSourceBlock = {
-    kind: 'prose';
-    markdown: string;
-} | {
-    kind: 'slot';
-    slotIndex: number;
-};
-export type PageSourceProjection = PageSourceBlock[];
-/** A page failed authoring or validation; the caller can report it as bad page input. */
-export declare class PageAuthoringError extends Error {
-    constructor(message: string);
-}
-/** Derive the transport manifest from one authored HTML page document. */
-export declare function derivePageManifestFromDocument(document: string, dialect: AuthoredPageDialect, productComponents?: ProductPageComponents, source?: PageSource): AuthoredPageManifest;
-/** Derive the transport manifest from one authored HTML page source file. */
-export declare function derivePageManifest(sourceFile: string, dialect: AuthoredPageDialect, productComponents?: ProductPageComponents, source?: PageSource): AuthoredPageManifest;
-/** Read source files into their built-in slots, returning a self-contained stored manifest. */
-export declare function snapshotPageSources(manifest: AuthoredPageManifest, productComponents?: ProductPageComponents): PageManifest;
-/** Replace every authored slot config with its stored, self-contained config for runtime rendering. */
-export declare function embedPageSlotConfigs(document: string, manifest: PageManifest): string;
+import { type PageDelivery, type PageManifest, type PageSource } from './page-schema.js';
+import { PageAuthoringError } from './page-errors.js';
+export { PageAuthoringError };
+/** Compile one authored TSX page to the CommonJS module the Gateway evaluates.
+ *  Registry names stay free identifiers; the Gateway supplies them at eval. */
+export declare function compilePage(document: string): string;
+/** Derive the transport manifest from one authored TSX page document. */
+export declare function derivePageManifestFromDocument(document: string, productComponents?: ProductPageComponents, source?: PageSource, delivery?: PageDelivery): PageManifest;
+export declare function deriveHtmlPageManifest(document: string, source?: PageSource, delivery?: PageDelivery): PageManifest;
+/** Derive the transport manifest from one authored TSX page source file. */
+export declare function derivePageManifest(sourceFile: string, productComponents?: ProductPageComponents, source?: PageSource, delivery?: PageDelivery): PageManifest;
 /** Read and validate page.json from a ticket directory. */
-export declare function parsePage(dir: string, productComponents?: ProductPageComponents): PageManifest;
-/** Project authored source for local rendering and verify its slot references against the manifest. */
-export declare function parsePageSource(document: string, manifest: PageManifest, productComponents?: ProductPageComponents): PageSourceProjection;
+export declare function parsePage(dir: string): PageManifest;