@north-light/crouter 0.3.196 → 0.3.198

package/dist/core/human/page.js

@@ -1,8 +1,7 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, 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';
+import { cardsSchema, chartDataRowsSchema, isResponseBearingSlot, issueText, tableRowsSchema, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
 /** A page failed authoring or validation; the caller can report it as bad page input. */
 export class PageAuthoringError extends Error {
     constructor(message) {
@@ -15,9 +14,18 @@ function asPageAuthoringError(error) {
         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);
@@ -35,53 +43,6 @@ function parseJsonObject(raw, thing) {
         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;
-        }
-        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 };
-}
 function sourceLines(source, start) {
     const lines = [];
     let cursor = start;
@@ -104,18 +65,35 @@ function addProse(projection, raw) {
     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;
+/**
+ * Project a pre-cutover Markdown ticket for terminal replay only. This is not
+ * an authoring contract: no new page path accepts Markdown, and its old front
+ * matter is merely skipped to recover the stored source body.
+ */
+function projectLegacyMarkdownSource(document, productComponents) {
+    if (!(document.startsWith('---\n') || document.startsWith('---\r\n'))) {
+        throw new PageAuthoringError('stored md page is missing its opening front matter delimiter');
+    }
+    const firstEnd = document.indexOf('\n') + 1;
+    let bodyStart = -1;
+    let cursor = firstEnd;
+    while (cursor <= document.length) {
+        const newline = document.indexOf('\n', cursor);
+        const lineEnd = newline === -1 ? document.length : newline;
+        if (document.slice(cursor, lineEnd).replace(/\r$/, '') === '---') {
+            bodyStart = newline === -1 ? document.length : newline + 1;
+            break;
+        }
+        if (newline === -1)
+            break;
+        cursor = newline + 1;
+    }
+    if (bodyStart === -1)
+        throw new PageAuthoringError('stored md page is missing its closing front matter delimiter');
+    const lines = sourceLines(document, bodyStart);
     const slots = [];
     const projection = [];
-    let proseStart = meta.bodyStart;
+    let proseStart = bodyStart;
     let ordinaryFence = null;
     for (let index = 0; index < lines.length; index++) {
         const line = lines[index];
@@ -135,8 +113,8 @@ function scanMarkdown(document, productKinds) {
             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}`);
+        if (kind === '' || info !== `slot:${kind}` || !isRegisteredPageKind(kind, productComponents)) {
+            throw new PageAuthoringError(`unregistered or invalid page slot kind "${kind}" in stored md fence`);
         }
         let closeIndex = -1;
         for (let candidate = index + 1; candidate < lines.length; candidate++) {
@@ -146,19 +124,19 @@ function scanMarkdown(document, productKinds) {
             }
         }
         if (closeIndex === -1)
-            throw new PageAuthoringError(`slot:${kind} fence at line ${lineOffset + index + 1} has no matching ${run.length}-backtick closing fence`);
+            throw new PageAuthoringError(`slot:${kind} fence has no matching ${run.length}-backtick closing fence`);
         addProse(projection, document.slice(proseStart, line.start));
-        const rawObject = parseJsonObject(document.slice(line.end, lines[closeIndex].start), `slot:${kind} fence at line ${lineOffset + index + 1}`);
+        const rawObject = parseJsonObject(document.slice(line.end, lines[closeIndex].start), `stored slot:${kind} fence`);
         const { id, ...config } = rawObject;
         if (id !== undefined && typeof id !== 'string')
-            throw new PageAuthoringError(`slot:${kind} fence at line ${lineOffset + index + 1} has non-string reserved id`);
+            throw new PageAuthoringError(`stored slot:${kind} fence has non-string reserved id`);
         slots.push({ ...(id === undefined ? {} : { id }), kind, step: 0, config, ...(BUILTIN_PAGE_KINDS.includes(kind) ? {} : { unvalidated: true }) });
         projection.push({ kind: 'slot', slotIndex: slots.length - 1 });
         proseStart = lines[closeIndex].end;
         index = closeIndex;
     }
     addProse(projection, document.slice(proseStart));
-    return { title: meta.title, ...(meta.subtitle === undefined ? {} : { subtitle: meta.subtitle }), placement: meta.placement, steps: 1, slots, projection };
+    return { steps: 1, slots, projection };
 }
 const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
 function tagEnd(html, start) {
@@ -216,8 +194,12 @@ function parseHtmlElements(html) {
             let match = stack.length - 1;
             while (match >= 0 && stack[match].tag !== tag)
                 match--;
-            if (match >= 0)
+            if (match >= 0) {
+                const element = stack[match];
+                element.closeStart = start;
+                element.end = end;
                 stack.length = match;
+            }
             cursor = end;
             continue;
         }
@@ -228,7 +210,7 @@ function parseHtmlElements(html) {
         }
         const tag = opening[1].toLowerCase();
         const parent = stack.at(-1);
-        const element = { tag, attrs: parseAttributes(token.slice(1, -1)), start, ...(parent === undefined ? {} : { parent }), children: [] };
+        const element = { tag, attrs: parseAttributes(token.slice(1, -1)), start, openEnd: end, end, ...(parent === undefined ? {} : { parent }), children: [] };
         if (parent === undefined)
             roots.push(element);
         else
@@ -242,6 +224,8 @@ function parseHtmlElements(html) {
             if (close === null)
                 throw new PageAuthoringError(`unterminated <script> element at byte ${start}`);
             element.text = html.slice(end, close.index);
+            element.closeStart = close.index;
+            element.end = closePattern.lastIndex;
             cursor = closePattern.lastIndex;
             continue;
         }
@@ -321,7 +305,41 @@ function configForHtmlElement(element) {
         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) {
+/** Project only body prose: slots remain terminal panels, while the pager's
+ * structural tags are invisible in the terminal. The raw fragments flow to
+ * the renderer, which downconverts HTML according to the manifest dialect. */
+function htmlProjection(document, elements, slotElements) {
+    const body = elements.find((element) => element.tag === 'body');
+    if (body === undefined)
+        throw new PageAuthoringError('page document has no <body> element');
+    const bodyEnd = body.closeStart ?? document.length;
+    const excluded = slotElements.map((element) => ({ start: element.start, end: element.end }));
+    for (const element of elements) {
+        if (element.tag !== 'crtr-pages' && element.tag !== 'crtr-page')
+            continue;
+        excluded.push({ start: element.start, end: element.openEnd });
+        if (element.closeStart !== undefined)
+            excluded.push({ start: element.closeStart, end: element.end });
+    }
+    const ranges = excluded
+        .map((range) => ({ start: Math.max(range.start, body.openEnd), end: Math.min(range.end, bodyEnd) }))
+        .filter((range) => range.start < range.end)
+        .sort((left, right) => left.start - right.start || left.end - right.end);
+    const projection = [];
+    let cursor = body.openEnd;
+    for (const range of ranges) {
+        if (range.end <= cursor)
+            continue;
+        addProse(projection, document.slice(cursor, range.start));
+        const element = slotElements.find((slot) => slot.start === range.start && slot.end === range.end);
+        if (element !== undefined)
+            projection.push({ kind: 'slot', slotIndex: slotElements.indexOf(element) });
+        cursor = range.end;
+    }
+    addProse(projection, document.slice(cursor, bodyEnd));
+    return projection;
+}
+function scanHtml(document, productComponents) {
     validateHtmlStructure(document);
     const elements = parseHtmlElements(document);
     const metadata = readHtmlMetadata(elements);
@@ -347,7 +365,7 @@ function scanHtml(document, productKinds) {
         let unvalidated = false;
         if (element.tag === 'crtr-slot') {
             kind = element.attrs.get('kind');
-            if (kind === undefined || !productKinds.includes(kind) || BUILTIN_PAGE_KINDS.includes(kind))
+            if (kind === undefined || !isRegisteredPageKind(kind, productComponents) || BUILTIN_PAGE_KINDS.includes(kind))
                 throw new PageAuthoringError(`<crtr-slot> at byte ${element.start} names unregistered product kind "${kind ?? ''}"`);
             unvalidated = true;
         }
@@ -358,6 +376,8 @@ function scanHtml(document, productKinds) {
         }
         if (kind === undefined)
             continue;
+        if (element.attrs.has('slot-id'))
+            throw new PageAuthoringError(`<${element.tag}> at byte ${element.start} has a slot-id attribute; author the slot id as id="…" — slot-id is written by the renderer`);
         const id = element.attrs.get('id');
         const containingPage = ancestor(element, 'crtr-page');
         const step = containingPage === undefined ? 0 : pageIndexes.get(containingPage) ?? 0;
@@ -365,7 +385,7 @@ function scanHtml(document, productKinds) {
         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);
+    const provisional = validateAuthoredManifest({ schema: 'crtr.page/v1', dialect: 'html', ...metadata, document: 'page.html', steps, slots: rawSlots }, productComponents);
     for (let index = 0; index < provisional.slots.length; index++) {
         const slot = provisional.slots[index];
         if (!isResponseBearingSlot(slot))
@@ -375,22 +395,79 @@ function scanHtml(document, productKinds) {
             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 })) };
+    return { ...metadata, steps, slots: provisional.slots, projection: htmlProjection(document, elements, slotElements) };
 }
-function scanDocument(document, dialect, productKinds) {
-    return dialect === 'md' ? scanMarkdown(document, productKinds) : scanHtml(document, productKinds);
+/** Derive the transport manifest from one authored HTML page document. */
+export function derivePageManifestFromDocument(document, dialect, productComponents = [], source) {
+    const scanned = scanHtml(document, productComponents);
+    return validateAuthoredManifest({ schema: 'crtr.page/v1', dialect, title: scanned.title, ...(scanned.subtitle === undefined ? {} : { subtitle: scanned.subtitle }), placement: scanned.placement, document: 'page.html', steps: scanned.steps, slots: scanned.slots, ...(source === undefined ? {} : { source }) }, productComponents);
 }
-/** Derive the transport manifest from one authored 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);
+/** Derive the transport manifest from one authored HTML page source file. */
+export function derivePageManifest(sourceFile, dialect, productComponents = [], source) {
+    return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), dialect, productComponents, source);
 }
-/** 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);
+const SOURCE_EMBED = {
+    table: { field: 'rows', schema: tableRowsSchema },
+    cards: { field: 'cards', schema: cardsSchema },
+    chart: { field: 'data', schema: chartDataRowsSchema },
+};
+function readSourceFile(path, context) {
+    if (!existsSync(path))
+        throw new PageAuthoringError(`${context} source file does not exist: ${path}`);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new PageAuthoringError(`${context} source file is not readable: ${path} (${error instanceof Error ? error.message : String(error)})`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new PageAuthoringError(`${context} source file is not valid JSON: ${path} (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+/** Read source files into their built-in slots, returning a self-contained stored manifest. */
+export function snapshotPageSources(manifest, productComponents = []) {
+    const slots = manifest.slots.map((slot, index) => {
+        const embed = slot.unvalidated === true ? undefined : SOURCE_EMBED[slot.kind];
+        const config = slot.config;
+        if (embed === undefined || typeof config.source !== 'string')
+            return slot;
+        const context = `slot ${slot.id === undefined ? `#${index}` : `"${slot.id}"`} (${slot.kind})`;
+        const raw = readSourceFile(config.source, context);
+        const parsed = embed.schema.safeParse(raw);
+        if (!parsed.success)
+            throw new PageAuthoringError(`${context} source data is invalid: ${issueText(parsed.error)}`);
+        const { source: _drop, ...rest } = config;
+        return { ...slot, config: { ...rest, [embed.field]: parsed.data } };
+    });
+    return validatePageManifest({ ...manifest, slots }, productComponents);
+}
+/** Replace every authored slot config with its stored, self-contained config for runtime rendering. */
+export function embedPageSlotConfigs(document, manifest) {
+    const replacements = [];
+    let slotIndex = 0;
+    for (const element of parseHtmlElements(document)) {
+        const isSlot = element.tag === 'crtr-slot' || (element.tag.startsWith('crtr-') && element.tag !== 'crtr-pages' && element.tag !== 'crtr-page');
+        if (!isSlot)
+            continue;
+        const slot = manifest.slots[slotIndex];
+        if (slot === undefined)
+            throw new PageAuthoringError(`page document has more slots than its manifest at slot #${slotIndex}`);
+        const script = element.children.find((child) => child.tag === 'script' && child.attrs.get('type') === 'application/json');
+        if (script?.closeStart === undefined)
+            throw new PageAuthoringError(`slot #${slotIndex} has no JSON config script`);
+        replacements.push({ start: script.openEnd, end: script.closeStart, text: JSON.stringify(slot.config).replace(/</g, '\\u003c') });
+        slotIndex += 1;
+    }
+    if (slotIndex !== manifest.slots.length)
+        throw new PageAuthoringError(`page document has ${slotIndex} slots but manifest has ${manifest.slots.length}`);
+    return replacements.reduceRight((result, replacement) => `${result.slice(0, replacement.start)}${replacement.text}${result.slice(replacement.end)}`, document);
 }
 /** Read and validate page.json from a ticket directory. */
-export function parsePage(dir, productKinds = []) {
+export function parsePage(dir, productComponents = []) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
@@ -398,7 +475,7 @@ export function parsePage(dir, productKinds = []) {
     catch {
         throw new PageAuthoringError('page.json is not valid JSON');
     }
-    return validatePageManifest(raw, productKinds);
+    return validatePageManifest(raw, productComponents);
 }
 /** Key-order-independent value identity, so a re-scan compares by content. */
 function canonicalJson(value) {
@@ -409,18 +486,29 @@ function canonicalJson(value) {
     const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => (left < right ? -1 : 1));
     return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
 }
+function comparableConfig(kind, config, sourceProjection) {
+    const embed = SOURCE_EMBED[kind];
+    if (embed === undefined || !sourceProjection)
+        return config;
+    const { source: _source, [embed.field]: _data, ...rest } = config;
+    return rest;
+}
 /** Project authored source for local rendering and verify its slot references against the manifest. */
-export function parsePageSource(document, manifest, productKinds = []) {
-    const canonical = validateAuthoredManifest(manifest, productKinds);
-    const scanned = scanDocument(document, canonical.dialect, productKinds);
+export function parsePageSource(document, manifest, productComponents = []) {
+    const canonical = validatePageManifest(manifest, productComponents);
+    const scanned = canonical.dialect === 'md'
+        ? projectLegacyMarkdownSource(document, productComponents)
+        : scanHtml(document, productComponents);
     // Normalize the re-scan through the same schema pass the manifest went through,
     // so per-kind config defaults are on both sides of the comparison.
-    const derived = 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);
+    const derived = validateAuthoredPageManifest({ schema: 'crtr.page/v1', dialect: canonical.dialect, title: canonical.title, ...(canonical.subtitle === undefined ? {} : { subtitle: canonical.subtitle }), placement: canonical.placement, document: canonical.document, steps: scanned.steps, slots: scanned.slots }, productComponents);
     if (derived.slots.length !== canonical.slots.length)
         throw new PageAuthoringError(`page source has ${derived.slots.length} slots but manifest has ${canonical.slots.length}`);
     for (let index = 0; index < canonical.slots.length; index++) {
         const left = derived.slots[index];
-        if (canonicalJson(left) !== canonicalJson(canonical.slots[index]))
+        const right = canonical.slots[index];
+        const sourceProjection = typeof left.config.source === 'string';
+        if (canonicalJson({ ...left, config: comparableConfig(left.kind, left.config, sourceProjection) }) !== canonicalJson({ ...right, config: comparableConfig(right.kind, right.config, sourceProjection) }))
             throw new PageAuthoringError(`page source slot #${index} (${left.id ?? left.kind}) does not match manifest slot #${index}`);
     }
     return scanned.projection;

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/scan.d.ts

@@ -1,6 +1,7 @@
+import type { ProductPageComponents } from '../../types.js';
 import type { PageTicketSummary, TicketSummary } from './types.js';
 /** Read all unresolved page/review tickets, newest first. Progress never affects visibility. */
-export declare function scanInbox(productKinds?: string[]): TicketSummary[];
+export declare function scanInbox(productKinds?: ProductPageComponents): TicketSummary[];
 export interface PageHistoryEntry extends PageTicketSummary {
     state: 'pending' | 'resolved' | 'canceled';
 }
@@ -9,4 +10,4 @@ export interface PageHistoryEntry extends PageTicketSummary {
  * first. This is the durable discovery seam for transcript placement, so it is a
  * separate walk from the pending-only inbox scan and never filters on a terminal file.
  */
-export declare function scanPageHistory(nodeId: string, productKinds?: string[]): PageHistoryEntry[];
+export declare function scanPageHistory(nodeId: string, productKinds?: ProductPageComponents): PageHistoryEntry[];

package/dist/core/human/scan.js

@@ -3,8 +3,8 @@ import { basename, join } from 'node:path';
 import { claimPath, isResolved, pageManifestPath, reviewPath } from './convention.js';
 import { readJsonOrNull } from '../fs-utils.js';
 import { validateReviewDescriptor } from './review-schema.js';
-import { isResponseBearingSlot, validatePageManifest } from './page-schema.js';
-import { pageTicketState } from './tickets.js';
+import { parsePage } from './page.js';
+import { pageTicketState, readTicketResult } from './tickets.js';
 import { ticketsRoot } from './root.js';
 function claimSummary(dir) {
     const claim = readJsonOrNull(claimPath(dir));
@@ -26,12 +26,9 @@ function reviewSummary(dir, id) {
     return { dir, id, kind: 'review', title: review.title, subtitle: review.subtitle, file: review.file, output: review.output, source: review.source, blockedSince: review.blockedSince, claim: claimSummary(dir) };
 }
 function pageSummary(dir, id, productKinds) {
-    const raw = readJsonOrNull(pageManifestPath(dir));
-    if (raw === null)
-        return null;
     let manifest;
     try {
-        manifest = validatePageManifest(raw, productKinds);
+        manifest = parsePage(dir, productKinds);
     }
     catch {
         return null;
@@ -55,7 +52,7 @@ function pageSummary(dir, id, productKinds) {
         placement: manifest.placement,
         steps: manifest.steps,
         slotKinds: manifest.slots.map((slot) => slot.kind),
-        awaitsResponse: manifest.slots.some(isResponseBearingSlot),
+        awaitsResponse: readJsonOrNull(join(dir, 'run.json'))?.mode === 'ask',
         source: manifest.source ?? {},
         blockedSince,
         claim: claimSummary(dir),
@@ -114,7 +111,9 @@ export function scanPageHistory(nodeId, productKinds = []) {
         const summary = pageSummary(dir, basename(dir), productKinds);
         if (summary === null || summary.source.nodeId !== nodeId)
             continue;
-        items.push({ ...summary, state: pageTicketState(dir) });
+        const state = pageTicketState(dir);
+        const result = state === 'resolved' ? readTicketResult(dir) : null;
+        items.push({ ...summary, state, ...(result?.kind === 'page' ? { answerDigest: result.summary.replace(/\s+/g, ' ').trim() } : {}) });
     }
     return items.sort((a, b) => Date.parse(a.blockedSince) - Date.parse(b.blockedSince) || a.id.localeCompare(b.id));
 }

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

@@ -1,7 +1,4 @@
-import { type PageManifest, type PageResponses } from './page-schema.js';
-/**
- * Deterministic, no-LLM page resolution summary — one line per answered slot in
- * document order: `"<slot id>: <answer>"`. An acknowledgement (`responses: {}`)
- * summarizes as the empty string.
- */
-export declare function buildPageSummary(manifest: PageManifest, responses: PageResponses): string;
+import type { ProductPageComponents } from '../../types.js';
+import type { PageManifest, PageResponses } from './page-schema.js';
+/** The stable one-line digest stored in response.json. */
+export declare function buildPageSummary(manifest: PageManifest, responses: PageResponses, productKinds?: ProductPageComponents): string;

package/dist/core/human/summary.js

@@ -1,61 +1,5 @@
-import { isResponseBearingSlot } from './page-schema.js';
-function labelsOf(items, ids, labelKey) {
-    const byId = new Map((Array.isArray(items) ? items : [])
-        .filter((item) => typeof item === 'object' && item !== null)
-        .map((item) => [String(item['id']), typeof item[labelKey] === 'string' ? item[labelKey] : String(item['id'])]));
-    return (Array.isArray(ids) ? ids : []).map((id) => byId.get(String(id)) ?? String(id));
-}
-function pickedWithFreetext(picked, freetext) {
-    const text = typeof freetext === 'string' && freetext !== '' ? freetext : undefined;
-    const selection = picked.length > 0 ? picked.join(', ') : undefined;
-    if (selection !== undefined && text !== undefined)
-        return `${selection} — ${text}`;
-    return selection ?? text ?? '(no selection)';
-}
-function commentSuffix(response) {
-    const comments = response['comments'];
-    const count = Array.isArray(comments) ? comments.length : 0;
-    return count === 0 ? '' : ` (${count} comment${count === 1 ? '' : 's'})`;
-}
-function describeSlotResponse(slot, response) {
-    const value = response;
-    const config = slot.config;
-    switch (slot.kind) {
-        case 'options':
-            return `${pickedWithFreetext(labelsOf(config['options'], value['selectedOptionIds'], 'label'), value['freetext'])}${commentSuffix(value)}`;
-        case 'text': {
-            const text = typeof value['text'] === 'string' ? value['text'].replace(/\s+/g, ' ').trim() : '';
-            return `${text === '' ? '(empty)' : text}${commentSuffix(value)}`;
-        }
-        case 'table': {
-            const rows = (Array.isArray(value['selectedRowIds']) ? value['selectedRowIds'] : []).map(String);
-            const columns = labelsOf(config['columns'], value['selectedColumnIds'], 'label');
-            const parts = [...(rows.length > 0 ? [`rows ${rows.join(', ')}`] : []), ...(columns.length > 0 ? [`columns ${columns.join(', ')}`] : [])];
-            return `${parts.length === 0 ? '(no selection)' : parts.join('; ')}${commentSuffix(value)}`;
-        }
-        case 'cards': {
-            const picked = labelsOf(config['cards'], value['selectedCardIds'], 'title');
-            return `${picked.length === 0 ? '(no selection)' : picked.join(', ')}${commentSuffix(value)}`;
-        }
-        default:
-            // A product kind crtr does not render: its opaque response is the summary.
-            return JSON.stringify(value);
-    }
-}
-/**
- * Deterministic, no-LLM page resolution summary — one line per answered slot in
- * document order: `"<slot id>: <answer>"`. An acknowledgement (`responses: {}`)
- * summarizes as the empty string.
- */
-export function buildPageSummary(manifest, responses) {
-    const lines = [];
-    for (const slot of manifest.slots) {
-        if (!isResponseBearingSlot(slot) || slot.id === undefined)
-            continue;
-        const response = responses[slot.id];
-        if (response === undefined)
-            continue;
-        lines.push(`${slot.id}: ${describeSlotResponse(slot, response)}`);
-    }
-    return lines.join('\n');
+import { describePageAnswer } from './answer.js';
+/** The stable one-line digest stored in response.json. */
+export function buildPageSummary(manifest, responses, productKinds) {
+    return describePageAnswer(manifest, responses, { completedAt: '', productKinds }).digest;
 }

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

@@ -1,5 +1,6 @@
 import type { ReviewDescriptor, TicketResult } from './types.js';
-import { type PageDialect } from './page.js';
+import type { ProductPageComponents } from '../../types.js';
+import { type AuthoredPageDialect } from './page.js';
 import { type PageManifest, type PageResponses, type PageSource } from './page-schema.js';
 /** Strict decoder for the only canonical final marker. */
 export declare function readTicketResult(dir: string): TicketResult | null;
@@ -7,13 +8,13 @@ export interface SubmitPageOptions {
     dir: string;
     /** The authored page source; copied into the ticket directory as its `document`. */
     sourceFile: string;
-    dialect: PageDialect;
+    dialect: AuthoredPageDialect;
     source?: PageSource;
-    productKinds?: string[];
+    productKinds?: ProductPageComponents;
 }
 /** One validated page, ready to publish into a ticket directory. */
 export interface PreparedPage {
-    dialect: PageDialect;
+    dialect: AuthoredPageDialect;
     /** The authored source, verbatim, as the ticket's `document`. */
     document: string;
     manifest: PageManifest;
@@ -53,13 +54,13 @@ export declare function submitReview(opts: SubmitReviewOptions): {
     kind: 'review';
 };
 /** Validate a page resolution against its canonical ticket before claim takeover. */
-export declare function validatePageTicketResponses(dir: string, responses: unknown, productKinds?: string[]): PageResponses;
+export declare function validatePageTicketResponses(dir: string, responses: unknown, productKinds?: ProductPageComponents): PageResponses;
 /** The three terminal states of a page ticket, derived from its published result. */
 export declare function pageTicketState(dir: string): 'pending' | 'resolved' | 'canceled';
 /** Autosave partial page work. Every supplied response is validated; omitted slots are permitted. */
-export declare function writePageProgress(dir: string, responses: unknown, productKinds?: string[]): PageResponses;
+export declare function writePageProgress(dir: string, responses: unknown, productKinds?: ProductPageComponents): PageResponses;
 /** Saved partial work, or null when none exists. Malformed progress is an error, never silently discarded. */
-export declare function readPageProgress(dir: string, productKinds?: string[]): PageResponses | null;
+export declare function readPageProgress(dir: string, productKinds?: ProductPageComponents): PageResponses | null;
 export interface PageTicket {
     dir: string;
     id: string;
@@ -70,9 +71,9 @@ export interface PageTicket {
     progress: PageResponses | null;
 }
 /** Read one addressable page ticket — pending, resolved or canceled alike. */
-export declare function readPageTicket(dir: string, productKinds?: string[]): PageTicket;
+export declare function readPageTicket(dir: string, productKinds?: ProductPageComponents): PageTicket;
 export interface CompletePageOptions {
-    productKinds?: string[];
+    productKinds?: ProductPageComponents;
     completedAt?: string;
 }
 export declare function completePage(dir: string, responses: unknown, claimToken: string, opts?: CompletePageOptions): {