@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,291 @@
+import { z } from 'zod';
+import { BUILTIN_PAGE_KINDS } from './page-catalog.js';
+import type { ProductPageComponents } from '../../types.js';
+export declare const PAGE_SLOT_ID_PATTERN: RegExp;
+export declare const pageCommentAnchorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"option">;
+    optionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"row">;
+    rowId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type PageCommentAnchor = z.infer<typeof pageCommentAnchorSchema>;
+export declare const commentSchema: z.ZodObject<{
+    id: z.ZodString;
+    anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"option">;
+        optionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"row">;
+        rowId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type Comment = z.infer<typeof commentSchema>;
+export declare const optionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    recommended: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const optionsConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        recommended: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    mode: z.ZodEnum<{
+        single: "single";
+        multi: "multi";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    allowFreetext: z.ZodOptional<z.ZodBoolean>;
+    freetextLabel: z.ZodOptional<z.ZodString>;
+    freetextPlaceholder: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OptionsConfig = z.infer<typeof optionsConfigSchema>;
+export declare const optionsResponseSchema: z.ZodObject<{
+    selectedOptionIds: z.ZodArray<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"option">;
+            optionId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"row">;
+            rowId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    freetext: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OptionsResponse = z.infer<typeof optionsResponseSchema>;
+export declare const textConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    initialText: z.ZodString;
+    placeholder: z.ZodOptional<z.ZodString>;
+    singleLine: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type TextConfig = z.infer<typeof textConfigSchema>;
+export declare const textResponseSchema: z.ZodObject<{
+    text: z.ZodString;
+    edited: z.ZodBoolean;
+}, z.core.$strict>;
+export type TextResponse = z.infer<typeof textResponseSchema>;
+export declare const tableColumnSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+    }>>;
+    mono: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const tableCellSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export declare const tableRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>;
+export declare const tableRowsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>>;
+/** Table config: its data is always embedded. */
+export declare const tableConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        align: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+        mono: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        cells: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>>;
+    rowSelect: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        single: "single";
+        multi: "multi";
+    }>>;
+    columnSelect: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        single: "single";
+        multi: "multi";
+    }>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type TableConfig = z.infer<typeof tableConfigSchema>;
+export declare const tableResponseSchema: z.ZodObject<{
+    selectedRowIds: z.ZodArray<z.ZodString>;
+    selectedColumnIds: z.ZodArray<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        anchor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"option">;
+            optionId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"row">;
+            rowId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TableResponse = z.infer<typeof tableResponseSchema>;
+export declare const cardSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const cardsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/** Cards config: its data is always embedded. */
+export declare const cardsConfigSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        subtitle: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        tag: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    mode: z.ZodEnum<{
+        single: "single";
+        multi: "multi";
+    }>;
+    columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CardsConfig = z.infer<typeof cardsConfigSchema>;
+export declare const cardsResponseSchema: z.ZodObject<{
+    selectedCardIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type CardsResponse = z.infer<typeof cardsResponseSchema>;
+export declare const chartSeriesSchema: z.ZodObject<{
+    field: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const chartDataRowsSchema: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/** Chart config: its data is always embedded. */
+export declare const chartConfigSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        line: "line";
+        area: "area";
+        bar: "bar";
+    }>;
+    x: z.ZodString;
+    y: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    title: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>;
+export type ChartConfig = z.infer<typeof chartConfigSchema>;
+export type SlotConfig = OptionsConfig | TextConfig | TableConfig | CardsConfig | ChartConfig | Record<string, unknown>;
+export type SlotResponse = OptionsResponse | TextResponse | TableResponse | CardsResponse | Record<string, unknown>;
+export interface PageSlot {
+    id?: string;
+    kind: string;
+    step: number;
+    config: SlotConfig;
+    unvalidated?: true;
+    /** Product registration declares this component display-only, so it carries no response. */
+    display?: true;
+}
+export interface PageSource {
+    sessionName?: string;
+    askedBy?: string;
+    emittedAt?: string;
+    profileName?: string;
+    nodeId?: string;
+}
+export interface PageDelivery {
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    /** Routing only: whether an answer travels back to a resident agent's bridge. Never whether the page can be answered — {@link pageAwaitsResponse} decides that. */
+    reply: boolean;
+}
+export interface PageManifest {
+    schema: 'crtr.page/v2';
+    dialect: 'jsx' | 'html';
+    title: string;
+    subtitle?: string;
+    delivery: PageDelivery;
+    document: 'page.tsx' | 'page.html';
+    steps: number;
+    slots: PageSlot[];
+    source?: PageSource;
+}
+export declare const pageDeliverySchema: z.ZodObject<{
+    placement: z.ZodEnum<{
+        inline: "inline";
+        panel: "panel";
+    }>;
+    inbox: z.ZodBoolean;
+    reply: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const BUILTIN_PAGE_CONFIG_SCHEMAS: Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>;
+export declare const BUILTIN_PAGE_RESPONSE_SCHEMAS: Partial<Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>>;
+export declare function issueText(error: z.ZodError): string;
+/** One question's recommended option, named well enough for a list row to draw it without reading the page. */
+export interface RecommendedOption {
+    slotId: string;
+    optionId: string;
+    label: string;
+}
+/**
+ * What one keypress on an inbox row publishes. `responses` is a complete, already-valid
+ * final response map, so the surface that sends it never assembles or interprets one.
+ * `kind` carries the semantic only — the words shown to a person belong to the surface.
+ */
+export interface PageFastAction {
+    kind: 'answer' | 'acknowledge';
+    responses: PageResponses;
+}
+/**
+ * The two independent overview facts: what a row displays, and what it can publish.
+ * A page can recommend without being fast-settleable — a recommendation beside a sibling
+ * input is still worth showing, but only the page itself can answer the rest of it.
+ */
+export interface PageOverviewActions {
+    recommendedOptions: RecommendedOption[];
+    fastAction?: PageFastAction;
+}
+/** Derive both overview facts from a manifest alone. Pure: no ticket state, no second read. */
+export declare function pageOverviewActions(manifest: PageManifest): PageOverviewActions;
+/** Whether this page is waiting on a person: it asks something, or an agent bridge is parked on its reply. */
+export declare function pageAwaitsResponse(manifest: PageManifest): boolean;
+/** The canonical response-bearing predicate used by every page consumer. */
+export declare function isResponseBearingSlot(slot: PageSlot): boolean;
+/** SQL form of `!pageAwaitsResponse(manifest)` over a `specification_json` column; keep it beside `isResponseBearingSlot`, which it mirrors. */
+export declare const pageIsNoticeSql: (column: string) => string;
+/** Validate a persisted manifest. Publish-time validation made its slots authoritative, so reads do not resolve a component catalog. */
+export declare function validatePageManifest(parsed: unknown): PageManifest;
+/** Validate a manifest derived from an authored page, where the display flag comes from the registration rather than the source. */
+export declare function validateAuthoredPageManifest(parsed: unknown, productComponents?: ProductPageComponents): PageManifest;
+export declare function createPageManifestSchema(): z.ZodType<PageManifest>;
+export declare const pageManifestSchema: z.ZodType<PageManifest, unknown, z.core.$ZodTypeInternals<PageManifest, unknown>>;
+export type PageResponses = Record<string, SlotResponse>;
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export declare function optionsRequired(config: OptionsConfig): boolean;
+/** Validate a complete final response map. */
+export declare function validatePageResponses(manifest: PageManifest, responses: unknown): PageResponses;
+/** Validate an autosaved response map, permitting omitted response-bearing components. */
+export declare function validatePartialPageResponses(manifest: PageManifest, responses: unknown): PageResponses;

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

@@ -0,0 +1,381 @@
+import { z } from 'zod';
+import { BUILTIN_PAGE_KINDS, productPageComponent } from './page-catalog.js';
+export const PAGE_SLOT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const idSchema = z.string().regex(PAGE_SLOT_ID_PATTERN, { error: 'slot id must match /^[A-Za-z0-9_-]{1,64}$/' });
+const itemIdSchema = z.string().min(1);
+const selectModeSchema = z.enum(['none', 'single', 'multi']);
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+function uniqueIds(items, ctx, label) {
+    const seen = new Set();
+    items.forEach((item, index) => {
+        if (seen.has(item.id))
+            ctx.addIssue({ code: 'custom', path: [index, 'id'], message: `duplicate ${label} id "${item.id}"` });
+        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 pageCommentAnchorSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('option'), optionId: itemIdSchema }).strict(),
+    z.object({ kind: z.literal('row'), rowId: itemIdSchema }).strict(),
+]);
+export const commentSchema = z.object({ id: z.string().min(1), anchor: pageCommentAnchorSchema, text: z.string() }).strict();
+export const optionSchema = z.object({ id: itemIdSchema, label: z.string().min(1), description: z.string().optional(), recommended: z.boolean().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']),
+    // Defaults with the mode: a radio group means "pick one", while an empty checkbox
+    // list is itself an answer ("none of these apply").
+    required: z.boolean().optional(),
+    allowFreetext: z.boolean().optional(),
+    freetextLabel: z.string().optional(),
+    freetextPlaceholder: z.string().optional(),
+}).strict().superRefine((config, ctx) => {
+    const recommended = config.options.filter((option) => option.recommended === true);
+    // A radio group has one suggested answer; a checkbox list can suggest a set.
+    if (config.mode === 'single' && recommended.length > 1)
+        ctx.addIssue({ code: 'custom', path: ['options'], message: `a mode="single" question may recommend at most one option, but ${recommended.length} are marked recommended (${recommended.map((option) => option.id).join(', ')}); keep one, or use mode="multi" to recommend several` });
+});
+export const optionsResponseSchema = z.object({ selectedOptionIds: z.array(itemIdSchema), comments: z.array(commentSchema), freetext: z.string().optional() }).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(), required: 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'),
+    required: z.boolean().optional(),
+};
+/** Table config: its data is always embedded. */
+export const tableConfigSchema = z.object(tableConfigFields).strict();
+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(),
+    required: z.boolean().optional(),
+};
+/** Cards config: its data is always embedded. */
+export const cardsConfigSchema = z.object(cardsConfigFields).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 = {
+    kind: z.enum(['line', 'bar', 'area']),
+    x: z.string().min(1),
+    y: z.array(chartSeriesSchema).min(1),
+    title: z.string().optional(),
+    data: chartDataRowsSchema.optional(),
+};
+/** Chart config: its data is always embedded. */
+export const chartConfigSchema = z.object(chartConfigFields).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();
+export const pageDeliverySchema = 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/v2'),
+    dialect: z.enum(['jsx', 'html']),
+    title: z.string().trim().min(1),
+    subtitle: z.string().optional(),
+    delivery: pageDeliverySchema,
+    document: z.enum(['page.tsx', 'page.html']),
+    steps: z.number().int().positive(),
+    slots: z.array(rawSlotSchema),
+    source: sourceSchema.optional(),
+}).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,
+    table: tableConfigSchema,
+    cards: cardsConfigSchema,
+    chart: chartConfigSchema,
+};
+export const BUILTIN_PAGE_RESPONSE_SCHEMAS = {
+    options: optionsResponseSchema,
+    text: textResponseSchema,
+    table: tableResponseSchema,
+    cards: cardsResponseSchema,
+};
+export function issueText(error) {
+    return error.issues.map((issue) => `${issue.path.length === 0 ? 'value' : issue.path.join('.')}: ${issue.message}`).join('; ');
+}
+/** Derive both overview facts from a manifest alone. Pure: no ticket state, no second read. */
+export function pageOverviewActions(manifest) {
+    const recommendedOptions = [];
+    for (const slot of manifest.slots) {
+        if (slot.kind !== 'options' || slot.id === undefined)
+            continue;
+        const config = slot.config;
+        // Persisted single-select manifests predate the one-recommendation rule, so take the first rather than assuming.
+        const marked = config.options.filter((candidate) => candidate.recommended === true);
+        for (const option of config.mode === 'multi' ? marked : marked.slice(0, 1))
+            recommendedOptions.push({ slotId: slot.id, optionId: option.id, label: option.label });
+    }
+    // An inline page lives in the transcript, where there is no row to press.
+    if (manifest.delivery.placement !== 'panel')
+        return { recommendedOptions };
+    const answerable = manifest.slots.filter(isResponseBearingSlot);
+    // A notice settles on the empty map, which is exactly what Acknowledge publishes from the page.
+    if (answerable.length === 0)
+        return { recommendedOptions, fastAction: { kind: 'acknowledge', responses: {} } };
+    if (answerable.length > 1)
+        return { recommendedOptions };
+    const slot = answerable[0];
+    const recommendation = recommendedOptions.filter((candidate) => candidate.slotId === slot.id);
+    if (slot.kind !== 'options' || recommendation.length === 0)
+        return { recommendedOptions };
+    return {
+        recommendedOptions,
+        fastAction: { kind: 'answer', responses: { [slot.id]: { selectedOptionIds: recommendation.map((candidate) => candidate.optionId), comments: [] } } },
+    };
+}
+/** Whether this page is waiting on a person: it asks something, or an agent bridge is parked on its reply. */
+export function pageAwaitsResponse(manifest) {
+    return manifest.delivery.reply || manifest.slots.some(isResponseBearingSlot);
+}
+/** The canonical response-bearing predicate used by every page consumer. */
+export function isResponseBearingSlot(slot) {
+    if (slot.display === true)
+        return false;
+    if (slot.unvalidated === true)
+        return true;
+    if (slot.kind === 'options' || slot.kind === 'text' || slot.kind === 'cards')
+        return true;
+    if (slot.kind !== 'table')
+        return false;
+    const config = slot.config;
+    return (config.rowSelect ?? 'none') !== 'none' || (config.columnSelect ?? 'none') !== 'none';
+}
+/** SQL form of `!pageAwaitsResponse(manifest)` over a `specification_json` column; keep it beside `isResponseBearingSlot`, which it mirrors. */
+export const pageIsNoticeSql = (column) => `(COALESCE(${column} #>> '{delivery,reply}', 'false') = 'false'
+  AND NOT EXISTS (SELECT 1 FROM jsonb_array_elements(CASE WHEN jsonb_typeof(${column} -> 'slots') = 'array' THEN ${column} -> 'slots' ELSE '[]'::jsonb END) AS s(value)
+    WHERE COALESCE(s.value ->> 'display', 'false') <> 'true'
+    AND (COALESCE(s.value ->> 'unvalidated', 'false') = 'true' OR s.value ->> 'kind' IN ('options', 'text', 'cards')
+      OR (s.value ->> 'kind' = 'table' AND (COALESCE(s.value #>> '{config,rowSelect}', 'none') <> 'none' OR COALESCE(s.value #>> '{config,columnSelect}', 'none') <> 'none')))))`;
+function validateManifest(parsed, productComponents, authored) {
+    const manifest = rawPageManifestSchema.parse(parsed);
+    if (!authored && manifest.dialect === 'html')
+        return manifest;
+    const seen = new Set();
+    const slots = manifest.slots.map((raw, index) => {
+        if (raw.step >= manifest.steps)
+            throw new Error(`slot ${raw.id === undefined ? `#${index}` : `"${raw.id}"`} has step ${raw.step}, outside page steps ${manifest.steps}`);
+        let slot;
+        if (BUILTIN_PAGE_KINDS.includes(raw.kind)) {
+            if (raw.unvalidated === true)
+                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 = 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 = 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 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 prop`
+                : `response-bearing slot kind "${slot.kind}" at slot #${index} requires an id prop`);
+        }
+        if (slot.id !== undefined) {
+            if (seen.has(slot.id))
+                throw new Error(`duplicate slot id "${slot.id}"`);
+            seen.add(slot.id);
+        }
+        return slot;
+    });
+    return { ...manifest, slots };
+}
+/** 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 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() {
+    return z.custom((value) => {
+        try {
+            validatePageManifest(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { error: 'invalid page manifest' }).transform((value) => validatePageManifest(value));
+}
+export const pageManifestSchema = createPageManifestSchema();
+function assertUnique(values, slotId, field) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`slot "${slotId}" has duplicate id in ${field}`);
+}
+function validateComments(slot, comments) {
+    const config = slot.config;
+    for (const comment of comments) {
+        const anchor = comment.anchor;
+        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 === '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;
+        }
+        throw new Error(`slot "${slot.id}" does not allow comment anchor kind "${anchor.kind}"`);
+    }
+}
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export function optionsRequired(config) {
+    return config.required ?? config.mode === 'single';
+}
+function parseResponse(slot, raw) {
+    if (slot.unvalidated === true) {
+        const result = jsonObjectSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`response for unvalidated slot "${slot.id}" must be an object`);
+        return result.data;
+    }
+    if (slot.kind === 'options') {
+        const result = optionsResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        const response = result.data;
+        const config = slot.config;
+        assertUnique(response.selectedOptionIds, slot.id, 'selectedOptionIds');
+        for (const id of response.selectedOptionIds)
+            if (!config.options.some((option) => option.id === id))
+                throw new Error(`slot "${slot.id}" selects unknown option id "${id}"`);
+        if (response.freetext !== undefined && config.allowFreetext !== true)
+            throw new Error(`slot "${slot.id}" does not allow freetext`);
+        if (config.mode === 'single' && response.selectedOptionIds.length > 1)
+            throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedOptionIds.length} option ids`);
+        const hasFreetext = config.allowFreetext === true && (response.freetext?.trim() ?? '') !== '';
+        if (optionsRequired(config)) {
+            if (config.mode === 'single' && response.selectedOptionIds.length !== 1 && !hasFreetext)
+                throw new Error(`single-select slot "${slot.id}" requires exactly one selection or nonempty allowed freetext`);
+            if (config.mode === 'multi' && response.selectedOptionIds.length === 0 && response.comments.length === 0 && !hasFreetext)
+                throw new Error(`multi-select slot "${slot.id}" requires a selection, comment, or nonempty allowed freetext`);
+        }
+        validateComments(slot, response.comments);
+        return response;
+    }
+    if (slot.kind === 'text') {
+        const result = textResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        if (slot.config.required === true && result.data.text.trim() === '')
+            throw new Error(`slot "${slot.id}" is required and was left empty`);
+        return result.data;
+    }
+    if (slot.kind === 'table') {
+        const result = tableResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        const response = result.data;
+        const config = slot.config;
+        assertUnique(response.selectedRowIds, slot.id, 'selectedRowIds');
+        assertUnique(response.selectedColumnIds, slot.id, 'selectedColumnIds');
+        const rowIds = new Set((config.rows ?? []).map((row) => row.id));
+        const columnIds = new Set(config.columns.map((column) => column.id));
+        for (const id of response.selectedRowIds)
+            if (!rowIds.has(id))
+                throw new Error(`slot "${slot.id}" selects unknown row id "${id}"`);
+        for (const id of response.selectedColumnIds)
+            if (!columnIds.has(id))
+                throw new Error(`slot "${slot.id}" selects unknown column id "${id}"`);
+        if (config.required === true && response.selectedRowIds.length === 0 && response.selectedColumnIds.length === 0)
+            throw new Error(`slot "${slot.id}" is required and nothing is selected`);
+        if ((config.rowSelect === 'none' && response.selectedRowIds.length > 0) || (config.rowSelect === 'single' && response.selectedRowIds.length > 1))
+            throw new Error(`slot "${slot.id}" response violates row select mode "${config.rowSelect}"`);
+        if ((config.columnSelect === 'none' && response.selectedColumnIds.length > 0) || (config.columnSelect === 'single' && response.selectedColumnIds.length > 1))
+            throw new Error(`slot "${slot.id}" response violates column select mode "${config.columnSelect}"`);
+        validateComments(slot, response.comments);
+        return response;
+    }
+    if (slot.kind === 'cards') {
+        const result = cardsResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        const response = result.data;
+        const config = slot.config;
+        assertUnique(response.selectedCardIds, slot.id, 'selectedCardIds');
+        for (const id of response.selectedCardIds)
+            if (!(config.cards ?? []).some((card) => card.id === id))
+                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`);
+        if (config.required === true && response.selectedCardIds.length === 0)
+            throw new Error(`slot "${slot.id}" is required and nothing is selected`);
+        return response;
+    }
+    throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);
+}
+function validateResponses(manifest, raw, partial) {
+    const result = jsonObjectSchema.safeParse(raw);
+    if (!result.success)
+        throw new Error('page responses must be an object keyed by slot id');
+    const expected = new Map(manifest.slots.filter(isResponseBearingSlot).map((slot) => [slot.id, slot]));
+    const responses = {};
+    for (const [id, value] of Object.entries(result.data)) {
+        const slot = expected.get(id);
+        if (slot === undefined)
+            throw new Error(`response names unknown or non-response-bearing slot id "${id}"`);
+        responses[id] = parseResponse(slot, value);
+    }
+    if (!partial)
+        for (const id of expected.keys())
+            if (!(id in responses))
+                throw new Error(`final page response is missing response-bearing slot id "${id}"`);
+    return responses;
+}
+/** 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 components. */
+export function validatePartialPageResponses(manifest, responses) { return validateResponses(manifest, responses, true); }