@north-light/crouter 0.3.198 → 0.3.200

package/dist/core/human/feedback-companion.d.ts

@@ -0,0 +1,20 @@
+export declare function feedbackCompanionBranchPath(dir: string): string;
+/** Hex sha256 of the ticket's page document, recorded at first comment so the
+ * settle-time completion can say whether the page changed during feedback. */
+export declare function pageDocumentSha256(dir: string): string;
+/** A companion node nothing on the ticket points at must not stay resident:
+ * the comment that would have bound it was refused, failed to commit, or lost
+ * the first-comment race to a concurrently recorded companion. */
+export declare function discardFeedbackCompanion(nodeId: string): void;
+/**
+ * Fork the sending node's current state into the ticket-bound companion and
+ * wait for its durable boundary bind. Throws on any failure — the caller
+ * refuses the comment so no feedback is accepted without a visible
+ * conversation able to receive it.
+ */
+export declare function realizeFeedbackCompanion(args: {
+    ticketId: string;
+    dir: string;
+    senderNodeId: string;
+    title: string;
+}): Promise<string>;

package/dist/core/human/feedback-companion.js

@@ -0,0 +1,98 @@
+// Feedback-companion realization — the one path that creates a page ticket's
+// companion conversation. The first feedback comment forks the page's sending
+// node at its then-current state; the ticket then records that companion and
+// every later comment reaches the same conversation. No fork point is captured
+// at page send and no placeholder exists before feedback.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getNode } from '../canvas/index.js';
+import { awaitCompanionBind, captureOrigin } from '../review/companion.js';
+import { COMPANION_BIND_DEADLINE_MS } from '../review/types.js';
+import { SessionManager } from '../runtime/broker-sdk.js';
+import { buildLaunchSpec } from '../runtime/launch.js';
+import { transition } from '../runtime/lifecycle.js';
+import { headlessBrokerHost } from '../runtime/host.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { reviveNode } from '../runtime/revive.js';
+import { materializeSessionBranchAt } from '../runtime/session-branch.js';
+import { pagePath } from './convention.js';
+export function feedbackCompanionBranchPath(dir) { return `${dir}/companion-branch.jsonl`; }
+/** Hex sha256 of the ticket's page document, recorded at first comment so the
+ * settle-time completion can say whether the page changed during feedback. */
+export function pageDocumentSha256(dir) {
+    return createHash('sha256').update(readFileSync(pagePath(dir, 'jsx'))).digest('hex');
+}
+/** Materialize the companion's fork branch, reusing only an already-valid one. */
+function materializeFeedbackBranch(dir, capture) {
+    const branchFile = feedbackCompanionBranchPath(dir);
+    if (existsSync(branchFile)) {
+        const branch = SessionManager.open(branchFile);
+        if (branch.getSessionFile() === resolve(branchFile) && branch.getSessionId() !== '')
+            return branchFile;
+    }
+    materializeSessionBranchAt(capture, branchFile);
+    return branchFile;
+}
+/** A companion node nothing on the ticket points at must not stay resident:
+ * the comment that would have bound it was refused, failed to commit, or lost
+ * the first-comment race to a concurrently recorded companion. */
+export function discardFeedbackCompanion(nodeId) {
+    try {
+        transition(nodeId, 'cancel');
+        headlessBrokerHost.teardown(nodeId);
+    }
+    catch { /* the refusal is authoritative; a straggler node is inert */ }
+}
+/**
+ * Fork the sending node's current state into the ticket-bound companion and
+ * wait for its durable boundary bind. Throws on any failure — the caller
+ * refuses the comment so no feedback is accepted without a visible
+ * conversation able to receive it.
+ */
+export async function realizeFeedbackCompanion(args) {
+    const origin = getNode(args.senderNodeId);
+    if (origin === null)
+        throw new Error(`page sender was not found: ${args.senderNodeId}`);
+    const capture = await captureOrigin(args.senderNodeId);
+    const branchFile = materializeFeedbackBranch(args.dir, capture);
+    const { launch } = buildLaunchSpec(origin.kind, origin.mode, {
+        lifecycle: 'resident',
+        hasManager: false,
+        model: capture.modelSpec,
+        modelExact: true,
+        cwd: origin.cwd,
+        profileId: origin.profile_id ?? null,
+    });
+    const node = spawnNode({
+        kind: origin.kind,
+        mode: origin.mode,
+        lifecycle: 'resident',
+        cwd: origin.cwd,
+        profile_id: origin.profile_id ?? null,
+        parent: args.senderNodeId,
+        subscribe: false,
+        forkFrom: branchFile,
+        modelOverride: capture.modelSpec,
+        reviewBinding: {
+            kind: 'page_feedback',
+            review_id: args.ticketId,
+            origin_node_id: args.senderNodeId,
+            branch_file: branchFile,
+            target_file: pagePath(args.dir, 'jsx'),
+        },
+        name: `Feedback · ${args.title}`,
+        launch,
+    });
+    try {
+        reviveNode(node.node_id, { resume: false });
+        if (!await awaitCompanionBind(node.node_id, COMPANION_BIND_DEADLINE_MS)) {
+            throw new Error(`feedback companion did not bind within ${COMPANION_BIND_DEADLINE_MS}ms`);
+        }
+    }
+    catch (error) {
+        discardFeedbackCompanion(node.node_id);
+        throw error;
+    }
+    return node.node_id;
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export declare const PAGE_FEEDBACK_SCHEMA: "crtr.page-feedback/v1";
+export declare function pageFeedbackPath(dir: string): string;
+declare const pageFeedbackCommentSchema: z.ZodObject<{
+    id: z.ZodString;
+    quote: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    note: z.ZodString;
+    status: z.ZodEnum<{
+        open: "open";
+        resolved: "resolved";
+    }>;
+    createdAt: z.ZodString;
+    resolvedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const pageFeedbackSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"crtr.page-feedback/v1">;
+    companionNodeId: z.ZodOptional<z.ZodString>;
+    firstCommentedSha256: z.ZodOptional<z.ZodString>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        quote: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        note: z.ZodString;
+        status: z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>;
+        createdAt: z.ZodString;
+        resolvedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PageFeedbackComment = z.infer<typeof pageFeedbackCommentSchema>;
+export type PageFeedback = z.infer<typeof pageFeedbackSchema>;
+/** Read a ticket's feedback comments; a ticket without any has an empty record. */
+export declare function readPageFeedback(dir: string): PageFeedback;
+export interface CreatePageFeedbackCommentInput {
+    quote: string;
+    context?: string;
+    note: string;
+    /** Bound as the ticket's companion when none is recorded yet. An already
+     * recorded companion wins; the first writer's companion stays the target. */
+    companionNodeId?: string;
+    /** Recorded with the companion binding; ignored once one is recorded. */
+    firstCommentedSha256?: string;
+}
+export interface PageFeedbackMutation {
+    comment: PageFeedbackComment;
+    feedback: PageFeedback;
+}
+/** Append one open feedback comment under the ticket lock. */
+export declare function createPageFeedbackComment(dir: string, input: CreatePageFeedbackCommentInput): PageFeedbackMutation;
+export declare class PageTicketTerminalError extends Error {
+    constructor();
+}
+export declare class UnknownPageFeedbackCommentError extends Error {
+    constructor(commentId: string);
+}
+export declare class PageFeedbackCommentAlreadyResolvedError extends Error {
+    constructor(commentId: string);
+}
+/** Mark one open comment resolved under the ticket lock. Terminal: a resolved
+ * comment never reopens; a renewed concern is a new comment. */
+export declare function resolvePageFeedbackComment(dir: string, commentId: string): PageFeedbackMutation;
+export {};

package/dist/core/human/feedback.js

@@ -0,0 +1,116 @@
+// Page feedback comments — ticket-attached notes on highlighted page content.
+// Feedback is about the agent's WORK, never part of the page answer: it lives
+// in its own file beside the page, delivers immediately to the ticket's
+// companion conversation, and reaches the response the sender reads at settle
+// only as the unresolved-item addendum. A sent comment is immutable — it is
+// either open or resolved, and only the companion resolves it. The file name
+// is `feedback-comments.json` — `feedback.json` is the review subsystem's
+// output file and must not be shadowed.
+import { existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { atomicWriteJson } from './convention.js';
+import { withTicketLock } from './claim.js';
+import { pageTicketState } from './tickets.js';
+export const PAGE_FEEDBACK_SCHEMA = 'crtr.page-feedback/v1';
+export function pageFeedbackPath(dir) { return `${dir}/feedback-comments.json`; }
+const pageFeedbackCommentSchema = z.object({
+    id: z.string().min(1),
+    /** The highlighted text the note is about; for a chart, its title. */
+    quote: z.string().min(1),
+    /** Surrounding text that locates the quote on the page. */
+    context: z.string().optional(),
+    note: z.string().min(1),
+    /** Open until the companion has dealt with it; resolution is terminal. */
+    status: z.enum(['open', 'resolved']),
+    createdAt: z.string().datetime({ offset: true }),
+    resolvedAt: z.string().datetime({ offset: true }).optional(),
+}).strict();
+const pageFeedbackSchema = z.object({
+    schema: z.literal(PAGE_FEEDBACK_SCHEMA),
+    /** The ticket-bound companion conversation every comment delivers to;
+     * recorded by the first comment and never replaced. */
+    companionNodeId: z.string().min(1).optional(),
+    /** Hex sha256 of the page document at first comment, for the settle-time
+     * change notice to the sender. */
+    firstCommentedSha256: z.string().min(1).optional(),
+    comments: z.array(pageFeedbackCommentSchema),
+}).strict();
+function emptyFeedback() {
+    return { schema: PAGE_FEEDBACK_SCHEMA, comments: [] };
+}
+/** Read a ticket's feedback comments; a ticket without any has an empty record. */
+export function readPageFeedback(dir) {
+    const path = pageFeedbackPath(dir);
+    if (!existsSync(path))
+        return emptyFeedback();
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`page feedback is not valid JSON: ${path}`);
+    }
+    const parsed = pageFeedbackSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`page feedback is malformed: ${path}`);
+    return parsed.data;
+}
+/** Append one open feedback comment under the ticket lock. */
+export function createPageFeedbackComment(dir, input) {
+    return withTicketLock(dir, () => {
+        requirePendingTicket(dir);
+        const feedback = readPageFeedback(dir);
+        if (feedback.companionNodeId === undefined && input.companionNodeId !== undefined) {
+            feedback.companionNodeId = input.companionNodeId;
+            if (input.firstCommentedSha256 !== undefined)
+                feedback.firstCommentedSha256 = input.firstCommentedSha256;
+        }
+        const comment = {
+            id: randomUUID(),
+            quote: input.quote,
+            ...(input.context === undefined ? {} : { context: input.context }),
+            note: input.note,
+            status: 'open',
+            createdAt: new Date().toISOString(),
+        };
+        feedback.comments.push(comment);
+        atomicWriteJson(pageFeedbackPath(dir), feedback);
+        return { comment, feedback };
+    });
+}
+export class PageTicketTerminalError extends Error {
+    constructor() { super('ticket already has a terminal outcome'); }
+}
+/** Settlement commits its terminal outcome under this same ticket lock, so an
+ * in-lock pending check is the race-free gate: no feedback mutation may land
+ * after the first ticket-ending action, however long the caller's own
+ * pre-lock work (a companion fork await) took. */
+function requirePendingTicket(dir) {
+    const state = pageTicketState(dir);
+    if (state === 'resolved' || state === 'canceled')
+        throw new PageTicketTerminalError();
+}
+export class UnknownPageFeedbackCommentError extends Error {
+    constructor(commentId) { super(`no feedback comment ${commentId} on this ticket`); }
+}
+export class PageFeedbackCommentAlreadyResolvedError extends Error {
+    constructor(commentId) { super(`feedback comment ${commentId} is already resolved`); }
+}
+/** Mark one open comment resolved under the ticket lock. Terminal: a resolved
+ * comment never reopens; a renewed concern is a new comment. */
+export function resolvePageFeedbackComment(dir, commentId) {
+    return withTicketLock(dir, () => {
+        requirePendingTicket(dir);
+        const feedback = readPageFeedback(dir);
+        const comment = feedback.comments.find((entry) => entry.id === commentId);
+        if (comment === undefined)
+            throw new UnknownPageFeedbackCommentError(commentId);
+        if (comment.status === 'resolved')
+            throw new PageFeedbackCommentAlreadyResolvedError(commentId);
+        comment.status = 'resolved';
+        comment.resolvedAt = new Date().toISOString();
+        atomicWriteJson(pageFeedbackPath(dir), feedback);
+        return { comment, feedback };
+    });
+}

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

@@ -1,7 +1,7 @@
 import type { PageComponentRegistration, ProductPageComponents } from '../../types.js';
-/** The page slot kinds crtr validates and renders itself. */
+/** The page component kinds crtr validates and renders itself. */
 export declare const BUILTIN_PAGE_KINDS: readonly ["options", "text", "table", "cards", "chart"];
-export declare const STRUCTURAL_PAGE_KINDS: readonly ["crtr-pages", "crtr-page"];
+export declare const STRUCTURAL_PAGE_KINDS: readonly ["page", "step"];
 export interface PageComponentCatalogEntry {
     kind: string;
     tag: string;
@@ -11,12 +11,47 @@ export interface PageComponentCatalogEntry {
     builtin: boolean;
     structural: boolean;
 }
-/** Normalize legacy kind strings and documented product component registrations. */
-export declare function normalizePageComponents(raw: unknown): PageComponentRegistration[];
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export declare function pageComponentTag(kind: string): string;
+/** The built-in component kind each authored JSX component name maps to. */
+export declare const BUILTIN_KIND_BY_TAG: Readonly<Record<string, string>>;
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export declare const BUILTIN_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export declare const DISPLAY_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export declare function normalizePageComponents(raw: unknown, label?: string): PageComponentRegistration[];
+/** One contributing source of product page components: a scope's own
+ *  `config.json` block, or one installed plugin's manifest contributions. */
+export interface PageComponentLayer {
+    /** How this source is named in a collision error, e.g. `plugin "northlight"`. */
+    origin: string;
+    components: readonly PageComponentRegistration[];
+}
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export declare function mergePageComponentLayers(layers: readonly PageComponentLayer[]): PageComponentRegistration[];
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export declare function invalidPageComponentsReasons(raw: unknown): string[];
 /** Names-only projection for page validation and rendering consumers. */
 export declare function pageComponentKinds(components: readonly PageComponentRegistration[]): string[];
 /** Full built-in + product catalog for CLI discovery. */
 export declare function pageComponentCatalog(components: readonly PageComponentRegistration[]): PageComponentCatalogEntry[];
-/** Whether crtr or the product catalog registers a page slot kind. */
+/** Whether crtr or the product catalog registers a page component kind. */
 export declare function productPageComponent(kind: string, components: ProductPageComponents): PageComponentRegistration | undefined;
 export declare function isRegisteredPageKind(kind: string, productComponents: ProductPageComponents): boolean;

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

@@ -1,17 +1,38 @@
-/** The page slot kinds crtr validates and renders itself. */
+/** The page component kinds crtr validates and renders itself. */
 export const BUILTIN_PAGE_KINDS = ['options', 'text', 'table', 'cards', 'chart'];
-export const STRUCTURAL_PAGE_KINDS = ['crtr-pages', 'crtr-page'];
+export const STRUCTURAL_PAGE_KINDS = ['page', 'step'];
 const PAGE_KIND_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const BUILTIN_PAGE_KIND_SET = new Set(BUILTIN_PAGE_KINDS);
 const BUILTIN_COMPONENTS = [
-    { kind: 'crtr-pages', tag: 'crtr-pages', description: 'ordered wrapper for one or more page steps', useWhen: 'use when the page has a response-bearing component or multiple steps', builtin: true, structural: true },
-    { kind: 'crtr-page', tag: 'crtr-page', description: 'one step inside a crtr-pages flow', useWhen: 'use for each step the human sees and completes in sequence', builtin: true, structural: true },
-    { kind: 'options', tag: 'crtr-options', description: 'known alternatives with single or multiple selection', useWhen: 'use when the human picks among known alternatives, optionally with freetext', builtin: true, structural: false },
-    { kind: 'text', tag: 'crtr-text', description: 'editable or read-only text surface', useWhen: 'use when the human writes, edits, or reviews text', builtin: true, structural: false },
-    { kind: 'table', tag: 'crtr-table', description: 'rows and columns with optional selection', useWhen: 'use when structured records are easiest to compare in rows and columns', builtin: true, structural: false },
-    { kind: 'cards', tag: 'crtr-cards', description: 'visual records with optional selection', useWhen: 'use when the human compares or picks richer items than a compact option list can carry', builtin: true, structural: false },
-    { kind: 'chart', tag: 'crtr-chart', description: 'line, bar, or area data visualization', useWhen: 'use when shape, trend, or magnitude matters more than exact tabular values', builtin: true, structural: false },
+    { kind: 'page', tag: 'Page', description: 'the page itself: title, subtitle, and every step it contains', useWhen: 'use as the single root element every page returns', builtin: true, structural: true },
+    { kind: 'step', tag: 'Step', description: 'one step inside a Page', useWhen: 'use for each step the user sees and completes in sequence', builtin: true, structural: true },
+    { kind: 'options', tag: 'UserQuestion', description: 'known alternatives with single or multiple selection', useWhen: 'use when the user picks among known alternatives, optionally with freetext', builtin: true, structural: false },
+    { kind: 'text', tag: 'UserText', description: 'writing surface whose answer is the text the user hands back', useWhen: 'use when you need prose from the user — a value they write, or a draft they revise; prose they only read is a plain element', builtin: true, structural: false },
+    { kind: 'table', tag: 'UserTable', description: 'rows and columns with optional selection', useWhen: 'use when structured records are easiest to compare in rows and columns', builtin: true, structural: false },
+    { kind: 'cards', tag: 'UserCards', description: 'visual records with optional selection', useWhen: 'use when the user compares or picks richer items than a compact option list can carry', builtin: true, structural: false },
+    { kind: 'chart', tag: 'Chart', description: 'line, bar, or area data visualization', useWhen: 'use when shape, trend, or magnitude matters more than exact tabular values', builtin: true, structural: false },
 ];
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export function pageComponentTag(kind) {
+    return kind.split('-').map((part) => (part === '' ? '' : `${part[0].toUpperCase()}${part.slice(1)}`)).join('');
+}
+/** The built-in component kind each authored JSX component name maps to. */
+export const BUILTIN_KIND_BY_TAG = Object.fromEntries(BUILTIN_COMPONENTS.filter((entry) => !entry.structural).map((entry) => [entry.tag, entry.kind]));
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export const BUILTIN_PAGE_COMPONENT_TAGS = new Set(BUILTIN_COMPONENTS.map((entry) => entry.tag));
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export const DISPLAY_PAGE_COMPONENT_TAGS = new Set([
+    'Card', 'CardHeader', 'CardTitle', 'CardDescription', 'CardContent', 'CardFooter', 'CardAction',
+    'Badge', 'Button', 'Separator', 'Progress', 'Alert', 'AlertTitle', 'AlertDescription',
+    'Table', 'TableHeader', 'TableBody', 'TableFooter', 'TableRow', 'TableHead', 'TableCell', 'TableCaption',
+    'Tabs', 'TabsList', 'TabsTrigger', 'TabsContent',
+    'Accordion', 'AccordionItem', 'AccordionTrigger', 'AccordionContent',
+]);
 function describeEntry(entry) {
     try {
         const json = JSON.stringify(entry);
@@ -21,21 +42,25 @@ function describeEntry(entry) {
         return String(entry);
     }
 }
-function optionalText(value, field, index) {
+function optionalText(value, field, label, index) {
     if (value === undefined)
         return undefined;
     if (typeof value !== 'string' || value.trim() === '') {
-        throw new Error(`page_components[${index}].${field} must be a non-empty string; received ${describeEntry(value)}`);
+        throw new Error(`${label}[${index}].${field} must be a non-empty string; received ${describeEntry(value)}`);
     }
     return value.trim();
 }
-/** Normalize legacy kind strings and documented product component registrations. */
-export function normalizePageComponents(raw) {
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export function normalizePageComponents(raw, label = 'page_components') {
     if (raw === undefined)
         return [];
     if (!Array.isArray(raw))
-        throw new Error(`page_components must be an array; received ${describeEntry(raw)}`);
-    const seen = new Set();
+        throw new Error(`${label} must be an array; received ${describeEntry(raw)}`);
+    const seenKinds = new Set();
+    const seenTags = new Set();
     return raw.map((entry, index) => {
         let registration;
         if (typeof entry === 'string') {
@@ -45,33 +70,80 @@ export function normalizePageComponents(raw) {
             const object = entry;
             const extra = Object.keys(object).filter((key) => !['kind', 'description', 'useWhen', 'doc', 'display'].includes(key));
             if (extra.length > 0)
-                throw new Error(`page_components[${index}] has unknown field(s): ${extra.join(', ')}`);
+                throw new Error(`${label}[${index}] has unknown field(s): ${extra.join(', ')}`);
             if (typeof object['kind'] !== 'string')
-                throw new Error(`page_components[${index}].kind must be a string; offending entry: ${describeEntry(entry)}`);
+                throw new Error(`${label}[${index}].kind must be a string; offending entry: ${describeEntry(entry)}`);
             if (object['display'] !== undefined && typeof object['display'] !== 'boolean')
-                throw new Error(`page_components[${index}].display must be a boolean; offending entry: ${describeEntry(entry)}`);
+                throw new Error(`${label}[${index}].display must be a boolean; offending entry: ${describeEntry(entry)}`);
             registration = {
                 kind: object['kind'].trim(),
-                ...(optionalText(object['description'], 'description', index) === undefined ? {} : { description: optionalText(object['description'], 'description', index) }),
-                ...(optionalText(object['useWhen'], 'useWhen', index) === undefined ? {} : { useWhen: optionalText(object['useWhen'], 'useWhen', index) }),
-                ...(optionalText(object['doc'], 'doc', index) === undefined ? {} : { doc: optionalText(object['doc'], 'doc', index) }),
+                ...(optionalText(object['description'], 'description', label, index) === undefined ? {} : { description: optionalText(object['description'], 'description', label, index) }),
+                ...(optionalText(object['useWhen'], 'useWhen', label, index) === undefined ? {} : { useWhen: optionalText(object['useWhen'], 'useWhen', label, index) }),
+                ...(optionalText(object['doc'], 'doc', label, index) === undefined ? {} : { doc: optionalText(object['doc'], 'doc', label, index) }),
                 ...(object['display'] === true ? { display: true } : {}),
             };
         }
         else {
-            throw new Error(`page_components[${index}] must be a string or component object; offending entry: ${describeEntry(entry)}`);
+            throw new Error(`${label}[${index}] must be a string or component object; offending entry: ${describeEntry(entry)}`);
         }
         const kind = registration.kind;
         if (!PAGE_KIND_PATTERN.test(kind))
-            throw new Error(`page_components[${index}] has invalid page kind ${describeEntry(kind)}; expected /^[a-z][a-z0-9-]{0,63}$/`);
+            throw new Error(`${label}[${index}] has invalid page kind ${describeEntry(kind)}; expected /^[a-z][a-z0-9-]{0,63}$/`);
         if (BUILTIN_PAGE_KIND_SET.has(kind) || STRUCTURAL_PAGE_KINDS.includes(kind))
-            throw new Error(`page_components[${index}] collides with built-in page kind "${kind}"`);
-        if (seen.has(kind))
-            throw new Error(`page_components[${index}] duplicates page kind "${kind}"`);
-        seen.add(kind);
+            throw new Error(`${label}[${index}] collides with built-in page kind "${kind}"`);
+        if (seenKinds.has(kind))
+            throw new Error(`${label}[${index}] duplicates page kind "${kind}"`);
+        const tag = pageComponentTag(kind);
+        if (BUILTIN_PAGE_COMPONENT_TAGS.has(tag))
+            throw new Error(`${label}[${index}] kind "${kind}" derives JSX tag "${tag}", which collides with a built-in page component`);
+        if (seenTags.has(tag))
+            throw new Error(`${label}[${index}] kind "${kind}" derives JSX tag "${tag}", which duplicates another product page component`);
+        seenKinds.add(kind);
+        seenTags.add(tag);
         return registration;
     });
 }
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export function mergePageComponentLayers(layers) {
+    const originByKind = new Map();
+    const claimByTag = new Map();
+    const out = [];
+    for (const layer of layers) {
+        for (const component of layer.components) {
+            const kindOrigin = originByKind.get(component.kind);
+            if (kindOrigin !== undefined) {
+                throw new Error(`page component kind "${component.kind}" is registered by both ${kindOrigin} and ${layer.origin}`);
+            }
+            const tag = pageComponentTag(component.kind);
+            const tagClaim = claimByTag.get(tag);
+            if (tagClaim !== undefined) {
+                throw new Error(`page component kind "${component.kind}" (${layer.origin}) derives JSX tag "${tag}", which duplicates kind "${tagClaim.kind}" from ${tagClaim.origin}`);
+            }
+            originByKind.set(component.kind, layer.origin);
+            claimByTag.set(tag, { kind: component.kind, origin: layer.origin });
+            out.push(component);
+        }
+    }
+    return out;
+}
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export function invalidPageComponentsReasons(raw) {
+    try {
+        normalizePageComponents(raw);
+        return [];
+    }
+    catch (error) {
+        return [error instanceof Error ? error.message : String(error)];
+    }
+}
 /** Names-only projection for page validation and rendering consumers. */
 export function pageComponentKinds(components) {
     return components.map((component) => component.kind);
@@ -82,16 +154,16 @@ export function pageComponentCatalog(components) {
         ...BUILTIN_COMPONENTS,
         ...components.map((component) => ({
             kind: component.kind,
-            tag: component.kind,
+            tag: pageComponentTag(component.kind),
             description: component.description ?? 'product-registered page component',
-            useWhen: component.useWhen ?? 'use when the product component matches the structured UI the human needs',
+            useWhen: component.useWhen ?? 'use when the product component matches the structured UI the user needs',
             ...(component.doc === undefined ? {} : { doc: component.doc }),
             builtin: false,
             structural: false,
         })),
     ];
 }
-/** Whether crtr or the product catalog registers a page slot kind. */
+/** Whether crtr or the product catalog registers a page component kind. */
 export function productPageComponent(kind, components) {
     return components.find((component) => component.kind === kind);
 }

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

@@ -0,0 +1,4 @@
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export declare class PageAuthoringError extends Error {
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/** 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';
+    }
+}

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

@@ -0,0 +1,20 @@
+/** One element of the tree an authored page returns. `tag` is the JSX identifier the
+ *  author wrote: a registry component (`UserQuestion`), a display component (`Card`),
+ *  or a plain element (`div`). Helper components are expanded before they get here. */
+export interface PageNode {
+    tag: string;
+    props: Record<string, unknown>;
+    children: PageNode[];
+}
+/** Evaluate the compiled page module and return the element tree its default export renders.
+ *
+ *  Each in-scope component name is bound to itself, so `<UserQuestion>` renders as the tag
+ *  string `"UserQuestion"`. A name outside that set is not defined, and the page fails with
+ *  the reference error rather than rendering a component the host does not have. */
+export declare function evaluatePageTree(code: string, tags: Iterable<string>): PageNode[];
+/** Keep only what can cross the wire. A manifest is JSON, so handlers and undefined values
+ *  are dropped rather than rejected — a click handler is legitimate authoring, it simply has
+ *  no meaning to a host reading the manifest. The round-trip also rebuilds the props in this
+ *  realm: values born in the vm carry that realm's prototypes, which prototype-sensitive
+ *  comparisons reject. */
+export declare function jsonProps(props: Record<string, unknown>): Record<string, unknown>;