@north-light/crouter 0.3.198 → 0.3.199

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

@@ -1,161 +1,434 @@
-const ELEMENT_RULES = `Element contract
-- Put the JSON config in the first direct \`<script type="application/json">\` child of the component element. It must contain one JSON object.
-- \`id\` must match \`^[A-Za-z0-9_-]{1,64}$\`, be unique across the page when present, and is required only for response-bearing components. Display-only components do not need an id.
-- When a page has two or more response-bearing components, every one needs a nonempty \`config.label\`.
-- Config objects and every documented nested object reject unknown fields.`;
-const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\`. Every response carries \`comments\` as an array. \`Anchor\` is one of \`{kind:"whole"}\`, \`{kind:"option",optionId:string}\`, \`{kind:"row",rowId:string}\`, \`{kind:"column",columnId:string}\`, \`{kind:"card",cardId:string}\`, or \`{kind:"range",start:nonnegative integer,end:nonnegative integer >= start,quote:string}\`; each component accepts only the anchors named below.`;
+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 = [
     {
-        kind: 'crtr-pages',
-        tag: '<crtr-pages>',
-        selectionLine: '`<crtr-pages>` — step wrapper. Use when a page is interactive or multi-step; it is always the wrapper for interactive/multi-step pages.',
-        contract: `\`<crtr-pages>\`
+        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.
 
-Display-only structural primitive. It takes no config or 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.
 
-- Use exactly one wrapper when the page has a response-bearing component or more than one step; do not nest wrappers.
-- It contains one or more \`<crtr-page>\` elements. A wrapper with no steps is invalid.`,
+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>
+  );
+}
+\`\`\``,
     },
     {
-        kind: 'crtr-page',
-        tag: '<crtr-page>',
-        selectionLine: '`<crtr-page>` — one page step. Use inside `<crtr-pages>` to group a step of an interactive or multi-step page.',
-        contract: `\`<crtr-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>\`
 
-Display-only structural primitive. It takes no config or response.
+Structural. One step of a multi-step page. It takes no \`id\` and contributes no response.
 
-- Every \`<crtr-page>\` is a direct-or-descendant step of the one \`<crtr-pages>\` wrapper; it may not appear outside that wrapper.
-- Response-bearing components must be inside a \`<crtr-page>\`. Step order is document order.`,
+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>
+\`\`\``,
     },
     {
-        kind: 'options',
-        tag: '<crtr-options>',
-        selectionLine: '`<crtr-options>` — known-alternative picker. Use when the human picks among known alternatives.',
-        contract: `\`<crtr-options>\`
+        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}\`.
 
-${ELEMENT_RULES}
+${SLOT_RULES}
 
-Config JSON
+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?:string\` — slot label; required by the multi-response page rule.
-- \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` — optional free-text affordance fields.
+- \`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} Options accept only \`whole\` and \`option\` anchors; \`optionId\` must name a configured option.`,
+- ${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' },
+  ]} />
+\`\`\``,
     },
     {
-        kind: 'text',
-        tag: '<crtr-text>',
-        selectionLine: '`<crtr-text>` — prose field. Use when presenting or collecting prose; use `singleLine` for a subject, name, or URL.',
-        contract: `\`<crtr-text>\`
+        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.
 
-Response-bearing. The response is \`{text:string, edited:boolean, comments:Comment[]}\`.
+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.
 
-${ELEMENT_RULES}
+${SLOT_RULES}
 
-Config JSON
+Props
+- \`id\` — required component id.
 - \`initialText\` — required string, including an empty string.
-- \`label?:string\` — slot label; required by the multi-response page rule.
-- \`editable?:boolean\`, \`placeholder?:string\`, \`singleLine?:boolean\` — optional presentation/input settings.
-- \`singleLine:true\` is mutually exclusive with \`editable:false\`: a single-line field is always editable.
+- \`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.
 
-Response rules
-- ${COMMENT_SHAPE} Text accepts only \`whole\` and \`range\` anchors.`,
+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" />
+\`\`\``,
     },
     {
-        kind: 'table',
-        tag: '<crtr-table>',
-        selectionLine: '`<crtr-table>` — structured rows and columns. Use when the human needs to inspect or select tabular data.',
-        contract: `\`<crtr-table>\`
+        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[]}\`.
 
-${ELEMENT_RULES}
+${SLOT_RULES}
 
-Config JSON
+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>}\`.
-- \`source?:string\` — path to a local JSON file containing the rows array. At submit it is read, validated as \`rows\`, and embedded; the stored ticket is self-contained and elements never see \`source\`. \`rows\` and \`source\` are mutually exclusive.
+- \`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\` — slot label; required by the multi-response page rule when the table is selectable.
+- \`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} Tables accept only \`whole\`, \`row\`, and \`column\` anchors. Row and column anchors must name configured ids.`,
+- ${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 } }))} />
+\`\`\``,
     },
     {
-        kind: 'cards',
-        tag: '<crtr-cards>',
-        selectionLine: '`<crtr-cards>` — visual item picker. Use when the human chooses one or more rich, card-shaped alternatives.',
-        contract: `\`<crtr-cards>\`
+        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[], comments:Comment[]}\`.
+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.
 
-${ELEMENT_RULES}
+${SLOT_RULES}
 
-Config JSON
-- \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`.
-- \`source?:string\` — path to a local JSON file containing the cards array. At submit it is read, validated as \`cards\`, and embedded; the stored ticket is self-contained and elements never see \`source\`. \`cards\` and \`source\` are mutually exclusive.
+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\` — slot label; required by the multi-response page rule.
+- \`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.
-- ${COMMENT_SHAPE} Cards accept only \`whole\` and \`card\` anchors. Card anchors must name configured ids.`,
+
+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' }]} />
+\`\`\``,
     },
     {
-        kind: 'chart',
-        tag: '<crtr-chart>',
-        selectionLine: '`<crtr-chart>` — data visualization. Use when a chart communicates a trend or comparison better than prose or a table.',
-        contract: `\`<crtr-chart>\`
+        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.
+Display-only; it has no response. It still takes an \`id\` when you want the chart recorded in the ticket manifest.
 
-${ELEMENT_RULES}
-
-Config JSON
+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 — optional display inputs.
-- \`source?:string\` — path to a local JSON file containing the \`data\` array. At submit it is read, validated as \`data\`, and embedded; the stored ticket is self-contained and elements never see \`source\`. \`data\` and \`source\` are mutually exclusive.`,
+- \`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 docsByKind = new Map(BUILTIN_COMPONENT_DOCS.map((doc) => [doc.kind, doc]));
-/** Compact catalog rows shared by `human -h` and `human html list`. */
-export const BUILTIN_COMPONENT_SELECTION_LINES = BUILTIN_COMPONENT_DOCS.map((doc) => doc.selectionLine);
-export function componentDoc(kind) {
-    return docsByKind.get(kind);
+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 componentKinds(productKinds) {
-    return [...BUILTIN_COMPONENT_DOCS.map((doc) => doc.kind), ...productKinds];
+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 lines = [`<components count="${BUILTIN_COMPONENT_DOCS.length + productComponents.length}">`, ...BUILTIN_COMPONENT_SELECTION_LINES];
+    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('', `\`${component.kind}\``, component.display === true ? 'product-registered; display-only' : 'product-registered');
+            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('', `\`${component.kind}\` — ${details.join('. ')}`);
+        lines.push(`${label} — ${details.join('. ')}`);
     }
     lines.push('</components>');
     return lines.join('\n');
 }
-export function renderComponentContract(kind, productComponents) {
-    const builtin = componentDoc(kind);
+export function renderComponentContract(name, productComponents) {
+    const builtin = componentDoc(name);
     if (builtin !== undefined)
         return builtin.contract;
-    const productComponent = productComponents.find((component) => component.kind === kind);
-    if (productComponent !== undefined)
-        return `\`${kind}\`\n\n${productComponent.doc ?? `product-registered${productComponent.display === true ? '; display-only' : '; config is passed through unvalidated (unvalidated: true)'} — see the product's own docs`}`;
-    return undefined;
+    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`;