@north-light/crouter 0.3.192 → 0.3.193

package/dist/core/human/page.js

@@ -0,0 +1,427 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkMarkdown } from '../termrender/termrender.js';
+import { BUILTIN_PAGE_KINDS, isRegisteredPageKind } from './page-catalog.js';
+import { isResponseBearingSlot, validatePageManifest } from './page-schema.js';
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export class PageAuthoringError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PageAuthoringError';
+    }
+}
+function asPageAuthoringError(error) {
+    if (error instanceof PageAuthoringError)
+        return error;
+    return new PageAuthoringError(error instanceof Error ? error.message : String(error));
+}
+function validateAuthoredManifest(parsed, productKinds) {
+    try {
+        return validatePageManifest(parsed, productKinds);
+    }
+    catch (error) {
+        throw asPageAuthoringError(error);
+    }
+}
+function parseJsonObject(raw, thing) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new PageAuthoringError(`${thing} must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (value === null || Array.isArray(value) || typeof value !== 'object')
+        throw new PageAuthoringError(`${thing} JSON must be one object`);
+    return value;
+}
+function parseFrontMatter(document) {
+    if (!(document.startsWith('---\n') || document.startsWith('---\r\n')))
+        throw new PageAuthoringError('md page front matter must begin at the first bytes with a --- delimiter line');
+    const firstEnd = document.indexOf('\n') + 1;
+    let cursor = firstEnd;
+    let closingStart = -1;
+    while (cursor <= document.length) {
+        const end = document.indexOf('\n', cursor);
+        const lineEnd = end === -1 ? document.length : end;
+        const line = document.slice(cursor, lineEnd).replace(/\r$/, '');
+        if (line === '---') {
+            closingStart = cursor;
+            cursor = end === -1 ? document.length : end + 1;
+            break;
+        }
+        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;
+    while (cursor < source.length) {
+        const newline = source.indexOf('\n', cursor);
+        const end = newline === -1 ? source.length : newline + 1;
+        const contentEnd = newline === -1 ? source.length : newline;
+        lines.push({ start: cursor, end, contentEnd, text: source.slice(cursor, contentEnd).replace(/\r$/, '') });
+        cursor = end;
+    }
+    return lines;
+}
+/** CommonMark closing fence: at least as many of the opener's fence character, nothing else on the line. */
+function closesFence(text, opener) {
+    const trimmed = text.trimEnd();
+    return trimmed.length >= opener.length && trimmed.split('').every((character) => character === opener.char);
+}
+function addProse(projection, raw) {
+    const markdown = raw.trim();
+    if (markdown !== '')
+        projection.push({ kind: 'prose', markdown });
+}
+function scanMarkdown(document, productKinds) {
+    const meta = parseFrontMatter(document);
+    const body = document.slice(meta.bodyStart);
+    const markdownCheck = checkMarkdown(body);
+    if (!markdownCheck.ok)
+        throw new PageAuthoringError(markdownCheck.error);
+    const lines = sourceLines(document, meta.bodyStart);
+    // Fence errors report document-absolute line numbers, past the front matter.
+    const lineOffset = document.slice(0, meta.bodyStart).split('\n').length - 1;
+    const slots = [];
+    const projection = [];
+    let proseStart = meta.bodyStart;
+    let ordinaryFence = null;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (ordinaryFence !== null) {
+            if (closesFence(line.text, ordinaryFence))
+                ordinaryFence = null;
+            continue;
+        }
+        const opening = line.text.match(/^(`{3,}|~{3,})(.*)$/);
+        if (opening === null)
+            continue;
+        const run = opening[1];
+        const fence = { char: run[0], length: run.length };
+        const info = opening[2];
+        if (fence.char !== '`' || !info.startsWith('slot:')) {
+            ordinaryFence = fence;
+            continue;
+        }
+        const kind = info.slice('slot:'.length);
+        if (kind === '' || info !== `slot:${kind}` || !isRegisteredPageKind(kind, productKinds)) {
+            throw new PageAuthoringError(`unregistered or invalid page slot kind "${kind}" in md fence at line ${lineOffset + index + 1}`);
+        }
+        let closeIndex = -1;
+        for (let candidate = index + 1; candidate < lines.length; candidate++) {
+            if (closesFence(lines[candidate].text, fence)) {
+                closeIndex = candidate;
+                break;
+            }
+        }
+        if (closeIndex === -1)
+            throw new PageAuthoringError(`slot:${kind} fence at line ${lineOffset + index + 1} has no matching ${run.length}-backtick closing fence`);
+        addProse(projection, document.slice(proseStart, line.start));
+        const rawObject = parseJsonObject(document.slice(line.end, lines[closeIndex].start), `slot:${kind} fence at line ${lineOffset + index + 1}`);
+        const { id, ...config } = rawObject;
+        if (id !== undefined && typeof id !== 'string')
+            throw new PageAuthoringError(`slot:${kind} fence at line ${lineOffset + index + 1} has non-string reserved id`);
+        slots.push({ ...(id === undefined ? {} : { id }), kind, step: 0, config, ...(BUILTIN_PAGE_KINDS.includes(kind) ? {} : { unvalidated: true }) });
+        projection.push({ kind: 'slot', slotIndex: slots.length - 1 });
+        proseStart = lines[closeIndex].end;
+        index = closeIndex;
+    }
+    addProse(projection, document.slice(proseStart));
+    return { title: meta.title, ...(meta.subtitle === undefined ? {} : { subtitle: meta.subtitle }), placement: meta.placement, steps: 1, slots, projection };
+}
+const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+function tagEnd(html, start) {
+    let quote = null;
+    for (let index = start + 1; index < html.length; index++) {
+        const character = html[index];
+        if (quote !== null) {
+            if (character === quote)
+                quote = null;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (character === '>')
+            return index + 1;
+    }
+    throw new PageAuthoringError(`unterminated HTML tag beginning at byte ${start}`);
+}
+function parseAttributes(source) {
+    const attrs = new Map();
+    const tagNameEnd = source.search(/\s/);
+    const body = tagNameEnd === -1 ? '' : source.slice(tagNameEnd);
+    const pattern = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+    for (const match of body.matchAll(pattern))
+        attrs.set(match[1].toLowerCase(), match[2] ?? match[3] ?? match[4] ?? '');
+    return attrs;
+}
+function parseHtmlElements(html) {
+    const roots = [];
+    const all = [];
+    const stack = [];
+    let cursor = 0;
+    while (cursor < html.length) {
+        const start = html.indexOf('<', cursor);
+        if (start === -1)
+            break;
+        if (html.startsWith('<!--', start)) {
+            const end = html.indexOf('-->', start + 4);
+            if (end === -1)
+                throw new PageAuthoringError(`unterminated HTML comment at byte ${start}`);
+            cursor = end + 3;
+            continue;
+        }
+        const end = tagEnd(html, start);
+        const token = html.slice(start, end);
+        if (/^<!/i.test(token) || /^<\?/i.test(token)) {
+            cursor = end;
+            continue;
+        }
+        const closing = token.match(/^<\s*\/\s*([^\s>]+)/);
+        if (closing !== null) {
+            const tag = closing[1].toLowerCase();
+            let match = stack.length - 1;
+            while (match >= 0 && stack[match].tag !== tag)
+                match--;
+            if (match >= 0)
+                stack.length = match;
+            cursor = end;
+            continue;
+        }
+        const opening = token.match(/^<\s*([^\s/>]+)/);
+        if (opening === null) {
+            cursor = end;
+            continue;
+        }
+        const tag = opening[1].toLowerCase();
+        const parent = stack.at(-1);
+        const element = { tag, attrs: parseAttributes(token.slice(1, -1)), start, ...(parent === undefined ? {} : { parent }), children: [] };
+        if (parent === undefined)
+            roots.push(element);
+        else
+            parent.children.push(element);
+        all.push(element);
+        const selfClosing = /\/\s*>$/.test(token) || VOID_TAGS.has(tag);
+        if (tag === 'script' && !selfClosing) {
+            const closePattern = /<\s*\/\s*script\s*>/gi;
+            closePattern.lastIndex = end;
+            const close = closePattern.exec(html);
+            if (close === null)
+                throw new PageAuthoringError(`unterminated <script> element at byte ${start}`);
+            element.text = html.slice(end, close.index);
+            cursor = closePattern.lastIndex;
+            continue;
+        }
+        if (!selfClosing)
+            stack.push(element);
+        cursor = end;
+    }
+    return all;
+}
+function ancestor(element, tag) {
+    let current = element.parent;
+    while (current !== undefined) {
+        if (current.tag === tag)
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}
+function decodeHtmlAttribute(value) {
+    return value.replace(/&(?:amp|quot|apos|lt|gt);|&#(?:x[0-9a-f]+|\d+);/gi, (entity) => {
+        const named = { '&amp;': '&', '&quot;': '"', '&apos;': "'", '&lt;': '<', '&gt;': '>' };
+        const lower = entity.toLowerCase();
+        if (named[lower] !== undefined)
+            return named[lower];
+        const numeric = lower.startsWith('&#x') ? Number.parseInt(lower.slice(3, -1), 16) : Number.parseInt(lower.slice(2, -1), 10);
+        return Number.isFinite(numeric) ? String.fromCodePoint(numeric) : entity;
+    });
+}
+function validateHtmlStructure(html) {
+    const counts = [
+        ['doctype', /<!doctype\b[^>]*>/gi, 'doctype'],
+        ['<head>', /<head(?=\s|>)/gi, '<head> opening tag'],
+        ['<body>', /<body(?=\s|>)/gi, '<body> opening tag'],
+    ];
+    for (const [, pattern, label] of counts) {
+        const count = html.match(pattern)?.length ?? 0;
+        if (count !== 1)
+            throw new PageAuthoringError(`Expected exactly one ${label}, found ${count}.`);
+    }
+}
+function readHtmlMetadata(elements) {
+    const recognized = new Map();
+    for (const element of elements.filter((candidate) => candidate.tag === 'meta')) {
+        const name = element.attrs.get('name');
+        if (name === undefined || !name.startsWith('crtr-page-'))
+            continue;
+        if (!['crtr-page-title', 'crtr-page-subtitle', 'crtr-page-placement'].includes(name))
+            throw new PageAuthoringError(`unknown page metadata element <meta name="${name}">`);
+        if (ancestor(element, 'head') === undefined)
+            throw new PageAuthoringError(`<meta name="${name}"> must appear inside <head>`);
+        const entries = recognized.get(name) ?? [];
+        entries.push(element);
+        recognized.set(name, entries);
+    }
+    for (const name of ['crtr-page-title', 'crtr-page-subtitle', 'crtr-page-placement']) {
+        const count = recognized.get(name)?.length ?? 0;
+        if ((name === 'crtr-page-title' && count !== 1) || (name !== 'crtr-page-title' && count > 1)) {
+            const expected = name === 'crtr-page-title' ? 'exactly one' : 'at most one';
+            throw new PageAuthoringError(`Expected ${expected} <meta name="${name}">, found ${count}.`);
+        }
+    }
+    const titleElement = recognized.get('crtr-page-title')[0];
+    const title = decodeHtmlAttribute(titleElement.attrs.get('content') ?? '').trim();
+    if (title === '')
+        throw new PageAuthoringError(`<meta name="crtr-page-title"> requires nonempty content`);
+    const subtitleElement = recognized.get('crtr-page-subtitle')?.[0];
+    const subtitle = subtitleElement === undefined ? undefined : decodeHtmlAttribute(subtitleElement.attrs.get('content') ?? '').trim();
+    const placementElement = recognized.get('crtr-page-placement')?.[0];
+    const placementValue = placementElement === undefined ? 'panel' : decodeHtmlAttribute(placementElement.attrs.get('content') ?? '').trim();
+    if (placementValue !== 'inline' && placementValue !== 'panel')
+        throw new PageAuthoringError(`<meta name="crtr-page-placement"> content must be exactly inline or panel; received "${placementValue}"`);
+    return { title, ...(subtitle === undefined ? {} : { subtitle }), placement: placementValue };
+}
+function configForHtmlElement(element) {
+    const script = element.children.find((child) => child.tag === 'script' && child.attrs.get('type') === 'application/json');
+    if (script === undefined)
+        throw new PageAuthoringError(`<${element.tag}> at byte ${element.start} requires a direct <script type="application/json"> child`);
+    return parseJsonObject(script.text ?? '', `<${element.tag}> at byte ${element.start}`);
+}
+function scanHtml(document, productKinds) {
+    validateHtmlStructure(document);
+    const elements = parseHtmlElements(document);
+    const metadata = readHtmlMetadata(elements);
+    const wrappers = elements.filter((element) => element.tag === 'crtr-pages');
+    if (wrappers.some((candidate) => ancestor(candidate, 'crtr-pages') !== undefined))
+        throw new PageAuthoringError('nested <crtr-pages> element is not allowed');
+    if (wrappers.length > 1)
+        throw new PageAuthoringError(`more than one <crtr-pages> element: found ${wrappers.length}`);
+    const wrapper = wrappers[0];
+    const pages = elements.filter((element) => element.tag === 'crtr-page');
+    for (const page of pages)
+        if (ancestor(page, 'crtr-pages') !== wrapper || wrapper === undefined)
+            throw new PageAuthoringError(`<crtr-page> outside <crtr-pages> at byte ${page.start}`);
+    if (wrapper !== undefined && pages.length === 0)
+        throw new PageAuthoringError('empty <crtr-pages> element must contain at least one <crtr-page>');
+    const pageIndexes = new Map(pages.map((page, index) => [page, index]));
+    const rawSlots = [];
+    const slotElements = [];
+    for (const element of elements) {
+        if (element.tag === 'crtr-pages' || element.tag === 'crtr-page')
+            continue;
+        let kind;
+        let unvalidated = false;
+        if (element.tag === 'crtr-slot') {
+            kind = element.attrs.get('kind');
+            if (kind === undefined || !productKinds.includes(kind) || BUILTIN_PAGE_KINDS.includes(kind))
+                throw new PageAuthoringError(`<crtr-slot> at byte ${element.start} names unregistered product kind "${kind ?? ''}"`);
+            unvalidated = true;
+        }
+        else if (element.tag.startsWith('crtr-')) {
+            kind = element.tag.slice('crtr-'.length);
+            if (!BUILTIN_PAGE_KINDS.includes(kind))
+                throw new PageAuthoringError(`unregistered page element <${element.tag}> at byte ${element.start}; product kinds use <crtr-slot kind="…">`);
+        }
+        if (kind === undefined)
+            continue;
+        const id = element.attrs.get('id');
+        const containingPage = ancestor(element, 'crtr-page');
+        const step = containingPage === undefined ? 0 : pageIndexes.get(containingPage) ?? 0;
+        rawSlots.push({ ...(id === undefined ? {} : { id }), kind, step, config: configForHtmlElement(element), ...(unvalidated ? { unvalidated: true } : {}) });
+        slotElements.push(element);
+    }
+    const steps = wrapper === undefined ? 1 : pages.length;
+    const provisional = validateAuthoredManifest({ schema: 'crtr.page/v1', dialect: 'html', ...metadata, document: 'page.html', steps, slots: rawSlots }, productKinds);
+    for (let index = 0; index < provisional.slots.length; index++) {
+        const slot = provisional.slots[index];
+        if (!isResponseBearingSlot(slot))
+            continue;
+        const element = slotElements[index];
+        if (ancestor(element, 'crtr-page') === undefined) {
+            throw new PageAuthoringError(`response-bearing element <${element.tag}> for slot "${slot.id}" is outside any <crtr-page>.\nWrap interactive elements with:\n<crtr-pages><crtr-page>…</crtr-page></crtr-pages>`);
+        }
+    }
+    return { ...metadata, steps, slots: provisional.slots, projection: provisional.slots.map((_, slotIndex) => ({ kind: 'slot', slotIndex })) };
+}
+function scanDocument(document, dialect, productKinds) {
+    return dialect === 'md' ? scanMarkdown(document, productKinds) : scanHtml(document, productKinds);
+}
+/** 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 page source file. */
+export function derivePageManifest(sourceFile, dialect, productKinds = [], source) {
+    return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), dialect, productKinds, source);
+}
+/** Read and validate page.json from a ticket directory. */
+export function parsePage(dir, productKinds = []) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
+    }
+    catch {
+        throw new PageAuthoringError('page.json is not valid JSON');
+    }
+    return validatePageManifest(raw, productKinds);
+}
+/** Key-order-independent value identity, so a re-scan compares by content. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => (left < right ? -1 : 1));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
+}
+/** Project authored source for local rendering and verify its slot references against the manifest. */
+export function parsePageSource(document, manifest, productKinds = []) {
+    const canonical = validateAuthoredManifest(manifest, productKinds);
+    const scanned = scanDocument(document, canonical.dialect, productKinds);
+    // Normalize the re-scan through the same schema pass the manifest went through,
+    // so per-kind config defaults are on both sides of the comparison.
+    const derived = validateAuthoredManifest({ schema: 'crtr.page/v1', dialect: canonical.dialect, title: scanned.title, ...(scanned.subtitle === undefined ? {} : { subtitle: scanned.subtitle }), placement: scanned.placement, document: canonical.document, steps: scanned.steps, slots: scanned.slots }, productKinds);
+    if (derived.slots.length !== canonical.slots.length)
+        throw new PageAuthoringError(`page source has ${derived.slots.length} slots but manifest has ${canonical.slots.length}`);
+    for (let index = 0; index < canonical.slots.length; index++) {
+        const left = derived.slots[index];
+        if (canonicalJson(left) !== canonicalJson(canonical.slots[index]))
+            throw new PageAuthoringError(`page source slot #${index} (${left.id ?? left.kind}) does not match manifest slot #${index}`);
+    }
+    return scanned.projection;
+}

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

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { ReviewDescriptor } from './types.js';
+export declare const reviewDescriptorSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"humanloop.review/v1">;
+    file: z.ZodString;
+    output: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodString;
+    source: z.ZodObject<{
+        sessionName: z.ZodOptional<z.ZodString>;
+        askedBy: z.ZodOptional<z.ZodString>;
+        blockedSince: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    blockedSince: z.ZodString;
+}, z.core.$strict>;
+export declare function validateReviewDescriptor(parsed: unknown): ReviewDescriptor;
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export declare function validateReviewProjection(dir: string, parsed: unknown): ReviewDescriptor;

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

@@ -0,0 +1,34 @@
+import { existsSync, realpathSync } from 'node:fs';
+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() });
+export const reviewDescriptorSchema = z.object({
+    schema: z.literal('humanloop.review/v1'),
+    file: z.string().min(1).refine(isAbsolute, 'file must be absolute'),
+    output: z.string().min(1).refine(isAbsolute, 'output must be absolute'),
+    title: z.string().trim().min(1),
+    subtitle: z.string().trim().min(1),
+    source: reviewSourceSchema,
+    blockedSince: z.string().datetime({ offset: true }),
+}).strict();
+export function validateReviewDescriptor(parsed) { return reviewDescriptorSchema.parse(parsed); }
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export function validateReviewProjection(dir, parsed) {
+    const descriptor = validateReviewDescriptor(parsed);
+    // Any reviewable UTF-8 text file: a .md artifact renders as a document, a
+    // source file as a syntax-highlighted code panel.
+    if (!existsSync(descriptor.file))
+        throw new Error('review file must be an existing absolute path');
+    const reviewable = checkReviewableFile(descriptor.file);
+    if (!reviewable.ok)
+        throw new Error(`review file is not reviewable: ${reviewable.reason}`);
+    const file = realpathSync(descriptor.file);
+    const output = resolve(realpathSync(dirname(descriptor.output)), basename(descriptor.output));
+    const reserved = new Set(['page.json', 'review.json', 'response.json', 'progress.json', 'claim.json']);
+    const ownProtocolPaths = new Set([pageManifestPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir)]);
+    if (output === file || reserved.has(basename(output)) || ownProtocolPaths.has(output))
+        throw new Error('review output must not alias the source or ticket protocol files');
+    return { ...descriptor, file, output };
+}

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

@@ -1,3 +1,12 @@
-import type { TicketSummary } from './types.js';
-/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
-export declare function scanInbox(): TicketSummary[];
+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 interface PageHistoryEntry extends PageTicketSummary {
+    state: 'pending' | 'resolved' | 'canceled';
+}
+/**
+ * Every page ticket raised by one node — pending, resolved or canceled — oldest
+ * 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[];

package/dist/core/human/scan.js

@@ -1,8 +1,10 @@
 import { readdirSync, statSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { claimPath, deckPath, isResolved, reviewPath } from './convention.js';
+import { claimPath, isResolved, pageManifestPath, reviewPath } from './convention.js';
 import { readJsonOrNull } from '../fs-utils.js';
-import { validateDeck, validateReviewDescriptor } from './deck-schema.js';
+import { validateReviewDescriptor } from './review-schema.js';
+import { isResponseBearingSlot, validatePageManifest } from './page-schema.js';
+import { pageTicketState } from './tickets.js';
 import { ticketsRoot } from './root.js';
 function claimSummary(dir) {
     const claim = readJsonOrNull(claimPath(dir));
@@ -10,46 +12,88 @@ function claimSummary(dir) {
         return undefined;
     return { owner: claim.host, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt };
 }
-function deckSummary(dir, id) {
-    const raw = readJsonOrNull(deckPath(dir));
+function reviewSummary(dir, id) {
+    const raw = readJsonOrNull(reviewPath(dir));
     if (raw === null)
         return null;
-    let deck;
+    let review;
     try {
-        deck = validateDeck(raw);
+        review = validateReviewDescriptor(raw);
     }
     catch {
         return null;
     }
-    const first = deck.interactions[0];
-    if (first === undefined)
+    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);
+    }
+    catch {
         return null;
-    let blockedSince = deck.source?.blockedSince;
+    }
+    let blockedSince = manifest.source?.blockedSince;
     if (blockedSince === undefined) {
         try {
-            blockedSince = statSync(deckPath(dir)).mtime.toISOString();
+            blockedSince = statSync(pageManifestPath(dir)).mtime.toISOString();
         }
         catch {
             return null;
         }
     }
-    return { dir, id, kind: 'deck', title: deck.title, subtitle: first.subtitle, interactionKind: first.kind, interactionCount: deck.interactions.length, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
+    return {
+        dir,
+        id,
+        kind: 'page',
+        title: manifest.title,
+        subtitle: manifest.subtitle ?? '',
+        dialect: manifest.dialect,
+        placement: manifest.placement,
+        steps: manifest.steps,
+        slotKinds: manifest.slots.map((slot) => slot.kind),
+        awaitsResponse: manifest.slots.some(isResponseBearingSlot),
+        source: manifest.source ?? {},
+        blockedSince,
+        claim: claimSummary(dir),
+    };
 }
-function reviewSummary(dir, id) {
-    const raw = readJsonOrNull(reviewPath(dir));
-    if (raw === null)
-        return null;
-    let review;
+/** Read all unresolved page/review tickets, newest first. Progress never affects visibility. */
+export function scanInbox(productKinds = []) {
+    let entries;
     try {
-        review = validateReviewDescriptor(raw);
+        entries = readdirSync(ticketsRoot());
     }
     catch {
-        return null;
+        return [];
     }
-    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) };
+    const items = [];
+    for (const entry of entries) {
+        const dir = join(ticketsRoot(), entry);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (isResolved(dir))
+            continue;
+        const item = reviewSummary(dir, basename(dir)) ?? pageSummary(dir, basename(dir), productKinds);
+        if (item !== null)
+            items.push(item);
+    }
+    return items.sort((a, b) => b.blockedSince.localeCompare(a.blockedSince) || a.id.localeCompare(b.id));
 }
-/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
-export function scanInbox() {
+/**
+ * Every page ticket raised by one node — pending, resolved or canceled — oldest
+ * 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 function scanPageHistory(nodeId, productKinds = []) {
     let entries;
     try {
         entries = readdirSync(ticketsRoot());
@@ -67,11 +111,10 @@ export function scanInbox() {
         catch {
             continue;
         }
-        if (isResolved(dir))
+        const summary = pageSummary(dir, basename(dir), productKinds);
+        if (summary === null || summary.source.nodeId !== nodeId)
             continue;
-        const item = deckSummary(dir, basename(dir)) ?? reviewSummary(dir, basename(dir));
-        if (item !== null)
-            items.push(item);
+        items.push({ ...summary, state: pageTicketState(dir) });
     }
-    return items.sort((a, b) => b.blockedSince.localeCompare(a.blockedSince) || a.id.localeCompare(b.id));
+    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,8 +1,7 @@
-import type { Deck, InteractionResponse } from './types.js';
+import { type PageManifest, type PageResponses } from './page-schema.js';
 /**
- * Deterministic, no-LLM resolution summary — one line per answered
- * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
- * (envelope summary) and `writeResponse` (persisted into response.json at write
- * time).
+ * 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 buildSummary(deck: Deck, responses: InteractionResponse[]): string;
+export declare function buildPageSummary(manifest: PageManifest, responses: PageResponses): string;