@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/human/component-docs.js

@@ -0,0 +1,434 @@
+import { pageComponentCatalog } from './page-catalog.js';
+/** A product registers a lowercase-hyphen kind; its JSX tag is the PascalCase derivation
+ * (`worker-card` → `<WorkerCard>`), which page-catalog carries as the entry `tag`. */
+function productTags(components) {
+    return new Map(pageComponentCatalog(components).filter((entry) => !entry.builtin).map((entry) => [entry.kind, entry.tag]));
+}
+const SLOT_RULES = `Component contract
+- Props are the component's config, spread flat as JSX attributes; the component registers itself with the host at mount and enforces its own response shape.
+- \`id\` is required, must match \`^[A-Za-z0-9_-]{1,64}$\`, and must be unique across the page.
+- When a page has two or more response-bearing components, every one needs a nonempty \`label\`.
+- Config objects and every documented nested object reject unknown fields.
+- The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape — mapped data, a helper component, a value from \`useState\`. Event handlers are dropped, because a manifest is JSON. The user's answer lands in \`response.json\` keyed by this \`id\`.`;
+const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\` and qualify the answer itself. \`Anchor\` is \`{kind:"option",optionId:string}\` or \`{kind:"row",rowId:string}\`; each component accepts only the anchors named next. Feedback on rendered page content — including the question text — is given by highlighting it on the page, never authored into a response.`;
+const DISPLAY_RULES = `Display-only: it is not recorded in the page manifest and contributes nothing to the response. Every display component also takes \`className\` for Tailwind utilities, and standard shadcn props otherwise.`;
+export const BUILTIN_COMPONENT_DOCS = [
+    {
+        names: ['Page'],
+        group: 'structural',
+        selectionLine: '`Page` — the page root. Every module default-exports a component whose root element is `<Page>`; it carries title and subtitle.',
+        contract: `\`<Page>\`
+
+Structural root. The \`.tsx\` module's default export returns exactly one \`<Page>\`; it takes no \`id\` and contributes no response.
+
+Props
+- \`title\` — required nonempty string. The headline the user sees in their inbox and in the terminal summary.
+- \`subtitle?:string\` — one line under the title.
+
+Rules
+- Children are page content: registry components, plain elements with Tailwind classes, or \`<Step>\` elements for a multi-step page.
+- Never render submit or dismiss chrome — the host owns it.
+
+Example
+\`\`\`jsx
+export default function ShipGate() {
+  return (
+    <Page title="Ship 0.4.0?" subtitle="Two gates left.">
+      <UserQuestion id="lane" label="Release lane" body="The audit closes tomorrow." mode="single"
+        options={[{ id: 'now', label: 'Ship now' }, { id: 'hold', label: 'Hold for the audit' }]} />
+    </Page>
+  );
+}
+\`\`\``,
+    },
+    {
+        names: ['Step'],
+        group: 'structural',
+        selectionLine: '`Step` — one step of a multi-step page. Use as a direct child of `<Page>` when the user works through content in sequence.',
+        contract: `\`<Step>\`
+
+Structural. One step of a multi-step page. It takes no \`id\` and contributes no response.
+
+Props
+- \`title?:string\` — the step heading.
+
+Rules
+- \`<Step>\` elements are children of \`<Page>\`; step order is source order, and the ticket manifest records the step count.
+- A single-step page needs no \`<Step>\` at all — put the content directly in \`<Page>\`.
+
+Example
+\`\`\`jsx
+<Page title="Migration plan">
+  <Step title="What changes"><Card>…</Card></Step>
+  <Step title="Approve"><UserQuestion id="go" label="Proceed?" body="Applies on the next deploy." mode="single" options={lanes} /></Step>
+</Page>
+\`\`\``,
+    },
+    {
+        names: ['UserQuestion'],
+        group: 'slot',
+        selectionLine: '`UserQuestion` — known-alternative picker (wire kind `options`). Use when the user picks among known alternatives.',
+        contract: `\`<UserQuestion>\` — wire kind \`options\`
+
+Response-bearing. The response is \`{selectedOptionIds:string[], comments:Comment[], freetext?:string}\`.
+
+${SLOT_RULES}
+
+Props
+- \`id\` — required component id.
+- \`options\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string}\`.
+- \`mode\` — required: \`single\` or \`multi\`.
+- \`label\` — required nonempty string: the question itself, drawn as the bold first line.
+- \`body\` — required nonempty string: markdown rendered above the choices — the context under the question a label cannot carry. Display-only; contributes nothing to the response.
+- \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` — adds a final "something else" choice, drawn as one more row with its own control and a field to write in rather than as a note on the question. It is exclusive on a \`single\` question (choosing it clears the selection, and choosing an option clears what was written) and just another box on a \`multi\` one. \`freetextLabel\` names that row, default "Something else".
+
+Response rules
+- \`selectedOptionIds\` contains unique known option ids. A \`single\` response has at most one selected id and requires exactly one selection or nonempty allowed \`freetext\`; a \`multi\` response requires a selection, comment, or nonempty allowed \`freetext\`.
+- \`freetext\` is accepted only when \`allowFreetext:true\`.
+- ${COMMENT_SHAPE} UserQuestion accepts only \`option\` anchors; \`optionId\` must name a configured option.
+
+Example
+\`\`\`jsx
+<UserQuestion id="lane" label="Release lane" body="The audit closes tomorrow." mode="single" allowFreetext
+  freetextLabel="Something else"
+  options={[
+    { id: 'now', label: 'Ship now', description: 'Both gates are green.' },
+    { id: 'hold', label: 'Hold for the audit' },
+  ]} />
+\`\`\``,
+    },
+    {
+        names: ['UserText'],
+        group: 'slot',
+        selectionLine: '`UserText` — writing surface (wire kind `text`). Use when you need prose back from the user — a value they write, or a draft they hand back revised; use `singleLine` for a subject, name, or URL. Prose the user only reads is a plain element, never this.',
+        contract: `\`<UserText>\` — wire kind \`text\`
+
+Response-bearing. The response is \`{text:string, edited:boolean}\`: the text the user hands back, and whether they changed what you drafted.
+
+It collects prose, it does not present it. Text the user only reads is a plain element with Tailwind classes — \`<p className="whitespace-pre-wrap">\` — which renders the same and asks nothing of them. Reach for it only when the answer you need is the string left in the field. Feedback on the rendered text is given by highlighting it on the page, not authored into the response.
+
+${SLOT_RULES}
+
+Props
+- \`id\` — required component id.
+- \`initialText\` — required string, including an empty string.
+- \`label?:string\` — the component's label; required by the multi-response page rule.
+- \`placeholder?:string\` — the hint shown while the field is empty.
+- \`singleLine?:boolean\` — swaps the writing surface for one compact form field.
+
+The field is always writable; there is no read-only mode, and the config rejects an \`editable\` prop.
+
+Example
+\`\`\`jsx
+<UserText id="subject" label="Subject line" singleLine initialText="Following up on the audit" />
+\`\`\``,
+    },
+    {
+        names: ['UserTable'],
+        group: 'slot',
+        selectionLine: '`UserTable` — selectable rows and columns (wire kind `table`). Use when the user inspects or selects tabular data; for a table the user only reads, `Table` is lighter.',
+        contract: `\`<UserTable>\` — wire kind \`table\`
+
+Display-only when both selection modes are \`none\`; response-bearing when \`rowSelect\` or \`columnSelect\` is \`single\` or \`multi\`. Its response when selectable is \`{selectedRowIds:string[], selectedColumnIds:string[], comments:Comment[]}\`.
+
+${SLOT_RULES}
+
+Props
+- \`id\` — required component id.
+- \`columns\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), align?:"left"|"right", mono?:boolean}\`.
+- \`rows?:\` array of \`{id:string (nonempty, unique), cells:Record<string,string|number|boolean|null>}\`. Rows are inline — map your data into this array in the module.
+- \`rowSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
+- \`columnSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
+- \`label?:string\` — the component's label; required by the multi-response page rule when the table is selectable.
+- \`body?:string\` — optional markdown rendered above the table. Display-only; it contributes nothing to the response.
+
+Response rules when selectable
+- Selected row and column ids are unique and must name configured ids. \`none\` permits no corresponding selected ids; \`single\` permits at most one.
+- ${COMMENT_SHAPE} UserTable accepts only \`row\` anchors, which must name configured row ids.
+
+Example
+\`\`\`jsx
+<UserTable id="picks" label="Which findings do we fix?" rowSelect="multi"
+  columns={[{ id: 'finding', label: 'Finding' }, { id: 'severity', label: 'Severity' }]}
+  rows={findings.map((f) => ({ id: f.id, cells: { finding: f.title, severity: f.severity } }))} />
+\`\`\``,
+    },
+    {
+        names: ['UserCards'],
+        group: 'slot',
+        selectionLine: '`UserCards` — visual item picker (wire kind `cards`). Use when the user chooses among rich, card-shaped alternatives.',
+        contract: `\`<UserCards>\` — wire kind \`cards\`
+
+Response-bearing. The response is \`{selectedCardIds:string[]}\`. Feedback on a card's content is given by highlighting it on the page, not authored into the response.
+
+${SLOT_RULES}
+
+Props
+- \`id\` — required component id.
+- \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`. Cards are inline — map your data into this array in the module.
+- \`mode\` — required: \`single\` or \`multi\`.
+- \`columns?:2|3\` — optional layout column count.
+- \`label?:string\` — the component's label; required by the multi-response page rule.
+- \`body?:string\` — optional markdown rendered above the cards. Display-only; it contributes nothing to the response.
+
+Response rules
+- \`selectedCardIds\` contains unique configured card ids. \`single\` permits at most one selected card.
+
+Example
+\`\`\`jsx
+<UserCards id="candidate" label="Who do we interview next?" mode="single" columns={3}
+  cards={[{ id: 'a', title: 'Dana Whitfield', subtitle: 'Staff eng', tag: 'referral' }]} />
+\`\`\``,
+    },
+    {
+        names: ['Chart'],
+        group: 'slot',
+        selectionLine: '`Chart` — data visualization (wire kind `chart`, display-only). Use when a trend or comparison reads better than prose or a table.',
+        contract: `\`<Chart>\` — wire kind \`chart\`
+
+Display-only; it has no response. It still takes an \`id\` when you want the chart recorded in the ticket manifest.
+
+Props
+- \`kind\` — required: \`line\`, \`bar\`, or \`area\`.
+- \`x\` — required nonempty string naming the x field.
+- \`y\` — required nonempty array of \`{field:string (nonempty), label?:string}\` series.
+- \`title?:string\`, \`data?:\` array of JSON row objects. Rows are inline — build them in the module.
+- \`id?:string\` — component id, subject to the same id rules as a response-bearing component when present.
+
+Example
+\`\`\`jsx
+<Chart kind="line" title="Build minutes" x="day"
+  y={[{ field: 'minutes', label: 'CI minutes' }]}
+  data={days.map((d) => ({ day: d.label, minutes: d.minutes }))} />
+\`\`\``,
+    },
+    {
+        names: ['Card', 'CardHeader', 'CardTitle', 'CardDescription', 'CardContent', 'CardFooter'],
+        group: 'display',
+        selectionLine: '`Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` — the standard surface for grouping a block of page content.',
+        contract: `\`<Card>\` family — \`Card\`, \`CardHeader\`, \`CardTitle\`, \`CardDescription\`, \`CardContent\`, \`CardFooter\`
+
+${DISPLAY_RULES}
+
+Props
+- All six take \`className\` and children only; the nesting carries the meaning.
+- Order inside \`<Card>\`: \`<CardHeader>\` (holding \`<CardTitle>\` and optional \`<CardDescription>\`), then \`<CardContent>\`, then optional \`<CardFooter>\`.
+
+Example
+\`\`\`jsx
+<Card>
+  <CardHeader><CardTitle>Release gates</CardTitle><CardDescription>Two left.</CardDescription></CardHeader>
+  <CardContent><Chart kind="bar" x="gate" y={[{ field: 'minutes' }]} data={gates} /></CardContent>
+</Card>
+\`\`\``,
+    },
+    {
+        names: ['Badge'],
+        group: 'display',
+        selectionLine: '`Badge` — small status or category chip.',
+        contract: `\`<Badge>\`
+
+${DISPLAY_RULES}
+
+Props
+- \`variant?:"default"|"secondary"|"destructive"|"outline"\`.
+- \`className\`, children.
+
+Example
+\`\`\`jsx
+<Badge variant="destructive">blocked</Badge>
+\`\`\``,
+    },
+    {
+        names: ['Button'],
+        group: 'display',
+        selectionLine: '`Button` — an in-page control. Never a submit: the host owns submit and dismiss.',
+        contract: `\`<Button>\`
+
+${DISPLAY_RULES} A page never renders its own submit or dismiss — use it for in-page interaction only (revealing detail, switching a local view).
+
+Props — this Button does NOT take shadcn's \`variant\`; a \`variant\` prop is silently ignored.
+- \`tone?:"brand"|"neutral"|"danger"\` — what the action means. Unstated, it resolves to \`brand\` on a solid button and \`neutral\` at every other weight.
+- \`weight?:"solid"|"outline"|"quiet"|"link"\` — how loudly it reads. Default \`solid\`. \`tone="danger"\` has no \`link\` weight — that pair warns and renders untoned.
+- \`size?:"xs"|"sm"|"default"|"lg"\` (icon-only circles: \`"icon-xs"|"icon-sm"|"icon"|"icon-lg"\`). Default \`default\`.
+- \`width?:"auto"|"full"\`. Default \`auto\`.
+- \`loading?:boolean\`, \`onClick?:(event) => void\`, \`disabled?:boolean\`, \`className\`, children.
+
+Example
+\`\`\`jsx
+<Button tone="neutral" weight="outline" size="sm" onClick={() => setShowAll(true)}>Show all 12</Button>
+\`\`\``,
+    },
+    {
+        names: ['Table', 'TableHeader', 'TableBody', 'TableRow', 'TableHead', 'TableCell', 'TableCaption'],
+        group: 'display',
+        selectionLine: '`Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` — read-only tabular layout. Use `UserTable` when the user must select rows or columns.',
+        contract: `\`<Table>\` family — \`Table\`, \`TableHeader\`, \`TableBody\`, \`TableRow\`, \`TableHead\`, \`TableCell\`, \`TableCaption\`
+
+${DISPLAY_RULES} It is layout only: nothing in it is selectable and nothing reaches the response. For selection, use \`UserTable\`.
+
+Props
+- All take \`className\` and children. \`TableHead\` and \`TableCell\` additionally take \`colSpan\`.
+- Structure: \`<Table>\` wraps optional \`<TableCaption>\`, \`<TableHeader>\` (rows of \`<TableHead>\`), and \`<TableBody>\` (rows of \`<TableCell>\`).
+
+Example
+\`\`\`jsx
+<Table>
+  <TableHeader><TableRow><TableHead>Gate</TableHead><TableHead>State</TableHead></TableRow></TableHeader>
+  <TableBody>{gates.map((g) => (
+    <TableRow key={g.id}><TableCell>{g.name}</TableCell><TableCell>{g.state}</TableCell></TableRow>
+  ))}</TableBody>
+</Table>
+\`\`\``,
+    },
+    {
+        names: ['Tabs', 'TabsList', 'TabsTrigger', 'TabsContent'],
+        group: 'display',
+        selectionLine: '`Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` — parallel views of the same subject behind one control.',
+        contract: `\`<Tabs>\` family — \`Tabs\`, \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`
+
+${DISPLAY_RULES} Which tab the user opened is not part of the response.
+
+Props
+- \`Tabs\`: \`defaultValue?:string\`, \`value?:string\`, \`onValueChange?:(value:string) => void\`, \`className\`.
+- \`TabsTrigger\` and \`TabsContent\`: \`value\` — required, and the two match by that value.
+- \`TabsList\`: \`className\` and children.
+
+Example
+\`\`\`jsx
+<Tabs defaultValue="diff">
+  <TabsList><TabsTrigger value="diff">Diff</TabsTrigger><TabsTrigger value="risk">Risk</TabsTrigger></TabsList>
+  <TabsContent value="diff">…</TabsContent>
+  <TabsContent value="risk">…</TabsContent>
+</Tabs>
+\`\`\``,
+    },
+    {
+        names: ['Separator'],
+        group: 'display',
+        selectionLine: '`Separator` — a rule between sections.',
+        contract: `\`<Separator>\`
+
+${DISPLAY_RULES}
+
+Props
+- \`orientation?:"horizontal"|"vertical"\` — defaults to \`horizontal\`.
+- \`className\`.
+
+Example
+\`\`\`jsx
+<Separator className="my-4" />
+\`\`\``,
+    },
+    {
+        names: ['Alert', 'AlertTitle', 'AlertDescription'],
+        group: 'display',
+        selectionLine: '`Alert`, `AlertTitle`, `AlertDescription` — a callout for the one thing the user must not miss.',
+        contract: `\`<Alert>\` family — \`Alert\`, \`AlertTitle\`, \`AlertDescription\`
+
+${DISPLAY_RULES}
+
+Props
+- \`Alert\`: \`variant?:"default"|"destructive"\`, \`className\`.
+- \`AlertTitle\` and \`AlertDescription\`: \`className\` and children.
+
+Example
+\`\`\`jsx
+<Alert variant="destructive">
+  <AlertTitle>Migration is irreversible</AlertTitle>
+  <AlertDescription>The old rows are dropped, not archived.</AlertDescription>
+</Alert>
+\`\`\``,
+    },
+    {
+        names: ['Progress'],
+        group: 'display',
+        selectionLine: '`Progress` — a completion bar for a known ratio.',
+        contract: `\`<Progress>\`
+
+${DISPLAY_RULES}
+
+Props
+- \`value?:number\` — 0 to 100.
+- \`className\`.
+
+Example
+\`\`\`jsx
+<Progress value={Math.round((done / total) * 100)} />
+\`\`\``,
+    },
+    {
+        names: ['Accordion', 'AccordionItem', 'AccordionTrigger', 'AccordionContent'],
+        group: 'display',
+        selectionLine: '`Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` — supporting detail the user opens only if they want it.',
+        contract: `\`<Accordion>\` family — \`Accordion\`, \`AccordionItem\`, \`AccordionTrigger\`, \`AccordionContent\`
+
+${DISPLAY_RULES}
+
+Props
+- \`Accordion\`: \`type\` — required: \`single\` or \`multiple\`; \`collapsible?:boolean\`, \`defaultValue?:string|string[]\`, \`className\`.
+- \`AccordionItem\`: \`value\` — required, unique within the accordion.
+- \`AccordionTrigger\` and \`AccordionContent\`: \`className\` and children.
+
+Example
+\`\`\`jsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="why">
+    <AccordionTrigger>Why this is blocked</AccordionTrigger>
+    <AccordionContent>The audit job has not run since Tuesday.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+\`\`\``,
+    },
+];
+const docsByName = new Map(BUILTIN_COMPONENT_DOCS.flatMap((doc) => doc.names.map((name) => [name, doc])));
+/** The structural and response-bearing rows — the ones that decide what a page can ask. `human -h` carries these;
+ * the display set is one line there and the full catalog is `human components list`. */
+export const CORE_COMPONENT_SELECTION_LINES = [...BUILTIN_COMPONENT_DOCS.filter((doc) => doc.group !== 'display').map((doc) => doc.selectionLine), '`usePageHost` — reserved host hook. Its product-supplied members are opaque to crouter; consult the owning product documentation.'];
+export function componentDoc(name) {
+    return docsByName.get(name);
+}
+export function componentNames(productComponents) {
+    return [...BUILTIN_COMPONENT_DOCS.flatMap((doc) => [...doc.names]), ...productTags(productComponents).values()];
+}
+const GROUP_HEADINGS = {
+    structural: 'Structural — every page is built from these.',
+    slot: 'Response — each is recorded in the page manifest under its wire kind, and their answers are the page response.',
+    display: 'Display — shadcn components with their standard props, plus `className` for Tailwind. They contribute nothing to the response.',
+};
+export function renderComponentCatalog(productComponents) {
+    const builtinCount = BUILTIN_COMPONENT_DOCS.reduce((total, doc) => total + doc.names.length, 0);
+    const lines = [`<components count="${builtinCount + productComponents.length}">`];
+    for (const group of ['structural', 'slot', 'display']) {
+        lines.push(GROUP_HEADINGS[group], ...BUILTIN_COMPONENT_DOCS.filter((doc) => doc.group === group).map((doc) => doc.selectionLine), '');
+    }
+    const tags = productTags(productComponents);
+    if (productComponents.length > 0)
+        lines.push('Product-registered — registry components this product ships. Write each one under the tag shown; a `(kind …)` suffix names its lowercase-hyphen wire kind.');
+    else
+        lines.pop();
+    for (const component of productComponents) {
+        const tag = tags.get(component.kind) ?? component.kind;
+        const label = tag === component.kind ? `\`${tag}\`` : `\`${tag}\` (kind \`${component.kind}\`)`;
+        if (component.description === undefined && component.useWhen === undefined) {
+            lines.push(`${label} — ${component.display === true ? 'product-registered; display-only' : 'product-registered'}`);
+            continue;
+        }
+        const details = [component.description, component.useWhen === undefined ? undefined : `${component.useWhen[0].toUpperCase()}${component.useWhen.slice(1)}`, ...(component.display === true ? ['Display-only'] : [])].filter((detail) => detail !== undefined);
+        lines.push(`${label} — ${details.join('. ')}`);
+    }
+    lines.push('</components>');
+    return lines.join('\n');
+}
+export function renderComponentContract(name, productComponents) {
+    const builtin = componentDoc(name);
+    if (builtin !== undefined)
+        return builtin.contract;
+    const tags = productTags(productComponents);
+    const productComponent = productComponents.find((component) => component.kind === name || tags.get(component.kind) === name);
+    if (productComponent === undefined)
+        return undefined;
+    const tag = tags.get(productComponent.kind) ?? productComponent.kind;
+    const heading = `\`<${tag}>\` — product-registered, wire kind \`${productComponent.kind}\``;
+    return `${heading}\n\n${productComponent.doc ?? `product-registered${productComponent.display === true ? '; display-only' : '; config is passed through unvalidated (unvalidated: true)'} — see the product's own docs`}`;
+}

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

@@ -1,17 +1,31 @@
-import type { PageManifest } from './page-schema.js';
-/** The authored page source, colocated with its derived manifest in the bridge node directory. */
-export declare function pagePath(dir: string, dialect: PageManifest['dialect']): string;
+/** The authored page source path, derived from the persisted dialect. */
+export declare function pagePath(dir: string, dialect?: 'jsx' | 'html'): string;
+/** The compiled module the Gateway evaluates for JSX pages. */
+export declare function pageModulePath(dir: string): string;
 export declare function pageManifestPath(dir: string): string;
 export declare function reviewPath(dir: string): string;
 export declare function responsePath(dir: string): string;
 export declare function progressPath(dir: string): string;
 export declare function claimPath(dir: string): string;
+export declare function replyRoutePath(dir: string): string;
+export interface TicketReplyRoute {
+    bridge_node_id: string;
+}
+/** A reply route exists only when completing the ticket must finish a human
+ * bridge and fan its result back to subscribers. Its absence is the complete
+ * representation of a standalone page. */
+export declare function readTicketReplyRoute(dir: string): TicketReplyRoute | null;
+export declare function bindTicketReplyRoute(dir: string, bridgeNodeId: string): void;
 export type InteractionState = 'pending' | 'claimed' | 'resolved' | 'missing';
 export declare function interactionState(dir: string): InteractionState;
 export declare function isResolved(dir: string): boolean;
 export declare function isClaimed(dir: string): boolean;
 /** Resolve and verify a ticket directory without a registry. */
 export declare function requireTicket(dir: string): string;
+/** Replace one file's contents in a single rename, so a concurrent reader —
+ *  the tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export declare function atomicWriteText(path: string, contents: string): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;

package/dist/core/human/convention.js

@@ -1,12 +1,37 @@
-import { existsSync, linkSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-/** The authored page source, colocated with its derived manifest in the bridge node directory. */
-export function pagePath(dir, dialect) { return `${dir}/page.${dialect}`; }
+/** The authored page source path, derived from the persisted dialect. */
+export function pagePath(dir, dialect = 'jsx') { return `${dir}/page.${dialect === 'jsx' ? 'tsx' : 'html'}`; }
+/** The compiled module the Gateway evaluates for JSX pages. */
+export function pageModulePath(dir) { return `${dir}/page.js`; }
 export function pageManifestPath(dir) { return `${dir}/page.json`; }
 export function reviewPath(dir) { return `${dir}/review.json`; }
 export function responsePath(dir) { return `${dir}/response.json`; }
 export function progressPath(dir) { return `${dir}/progress.json`; }
 export function claimPath(dir) { return `${dir}/claim.json`; }
+export function replyRoutePath(dir) { return `${dir}/reply-route.json`; }
+/** A reply route exists only when completing the ticket must finish a human
+ * bridge and fan its result back to subscribers. Its absence is the complete
+ * representation of a standalone page. */
+export function readTicketReplyRoute(dir) {
+    const path = replyRoutePath(dir);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`invalid ticket reply route: ${path}`);
+    }
+    const bridgeNodeId = raw?.bridge_node_id;
+    if (typeof bridgeNodeId !== 'string' || bridgeNodeId === '')
+        throw new Error(`invalid ticket reply route: ${path}`);
+    return { bridge_node_id: bridgeNodeId };
+}
+export function bindTicketReplyRoute(dir, bridgeNodeId) {
+    atomicWriteJson(replyRoutePath(dir), { bridge_node_id: bridgeNodeId });
+}
 export function interactionState(dir) {
     if (!existsSync(pageManifestPath(dir)) && !existsSync(reviewPath(dir)))
         return 'missing';
@@ -24,12 +49,18 @@ export function requireTicket(dir) {
     }
     return canonicalDir;
 }
-export function atomicWriteJson(path, value) {
+/** Replace one file's contents in a single rename, so a concurrent reader —
+ *  the tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export function atomicWriteText(path, contents) {
     const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    writeFileSync(tmp, contents, { mode: 0o600 });
     renameSync(tmp, path);
 }
+export function atomicWriteJson(path, value) {
+    atomicWriteText(path, `${JSON.stringify(value, null, 2)}\n`);
+}
 /** Publish one immutable JSON record without replacing an existing winner. */
 export function publishJsonExclusive(path, value) {
     const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;

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;
+}