@north-light/crouter 0.3.318 → 0.3.319

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

@@ -1,34 +1,14 @@
-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.
-- A quoted JSX attribute does not interpret escape sequences, so \`body="one.\\n\\ntwo."\` reaches the reader as one run-on paragraph with a literal backslash-n in the middle of it. Write any markdown body that has a line or paragraph break as a braced string — \`body={"one.\\n\\ntwo."}\` — where the escape is real.
-- 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 is stored in the request's terminal result under 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. The reader writes one against a specific option or row in whatever host they read in — in the terminal inbox, \`c\` on the selected one — so every option and row needs a label that reads on its own. Feedback on the page's own prose is a separate channel, offered only by hosts that render the page, and never part of 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>\`
+var m=Object.defineProperty;var r=(t,n)=>m(t,"name",{value:n,configurable:!0});import{pageComponentCatalog as b}from"./page-catalog.js";function p(t){return new Map(b(t).filter(n=>!n.builtin).map(n=>[n.kind,n.tag]))}r(p,"productTags");const c='Component contract\n- 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.\n- `id` is required, must match `^[A-Za-z0-9_-]{1,64}$`, and must be unique across the page.\n- When a page has two or more response-bearing components, every one needs a nonempty `label`.\n- Config objects and every documented nested object reject unknown fields.\n- A quoted JSX attribute does not interpret escape sequences, so `body="one.\\n\\ntwo."` reaches the reader as one run-on paragraph with a literal backslash-n in the middle of it. Write any markdown body that has a line or paragraph break as a braced string \u2014 `body={"one.\\n\\ntwo."}` \u2014 where the escape is real.\n- The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape \u2014 mapped data, a helper component, a value from `useState`. Event handlers are dropped, because a manifest is JSON. The user\'s answer is stored in the request\'s terminal result under this `id`.',h='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. The reader writes one against a specific option or row in whatever host they read in \u2014 in the terminal inbox, `c` on the selected one \u2014 so every option and row needs a label that reads on its own. Feedback on the page\'s own prose is a separate channel, offered only by hosts that render the page, and never part of a response.',s="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.",i=[{names:["Page"],group:"structural",selectionLine:"`Page` \u2014 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.
+- \`title\` \u2014 required nonempty string. The headline the user sees in their inbox and in the terminal summary.
+- \`subtitle?:string\` \u2014 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.
+- Never render submit or dismiss chrome \u2014 the host owns it.
 
 Example
 \`\`\`jsx
@@ -40,56 +20,26 @@ export default function ShipGate() {
     </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>\`.
-- The reader sees one step at a time, so hold each step to one question or request for action, with the context that decision needs beside it. Several decisions means several steps, never one long scroll.
-
-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\`
+\`\`\``},{names:["Step"],group:"structural",selectionLine:"`Step` \u2014 one step of a multi-step page. Use as a direct child of `<Page>` when the user works through content in sequence.",contract:'`<Step>`\n\nStructural. One step of a multi-step page. It takes no `id` and contributes no response.\n\nProps\n- `title?:string` \u2014 the step heading.\n\nRules\n- `<Step>` elements are children of `<Page>`; step order is source order, and the ticket manifest records the step count.\n- A single-step page needs no `<Step>` at all \u2014 put the content directly in `<Page>`.\n- The reader sees one step at a time, so hold each step to one question or request for action, with the context that decision needs beside it. Several decisions means several steps, never one long scroll.\n\nExample\n```jsx\n<Page title="Migration plan">\n  <Step title="What changes"><Card>\u2026</Card></Step>\n  <Step title="Approve"><UserQuestion id="go" label="Proceed?" body="Applies on the next deploy." mode="single" options={lanes} /></Step>\n</Page>\n```'},{names:["UserQuestion"],group:"slot",selectionLine:"`UserQuestion` \u2014 known-alternative picker (wire kind `options`). Use when the user picks among known alternatives.",contract:`\`<UserQuestion>\` \u2014 wire kind \`options\`
 
 Response-bearing. The response is \`{selectedOptionIds:string[], comments:Comment[], freetext?:string}\`.
 
-${SLOT_RULES}
+${c}
 
 Props
-- \`id\` — required component id.
-- \`options\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string, recommended?:boolean}\`.
+- \`id\` \u2014 required component id.
+- \`options\` \u2014 required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string, recommended?:boolean}\`.
 - \`recommended\` on one option marks it the suggested answer. At most one option per question may set it. The inbox shows it on the row, and when this question is the page's only response-bearing component the user can accept it from the list with one keystroke, without opening the page. Recommend when you have a view worth acting on; leave it off when the choice is genuinely theirs.
-- \`mode\` — required: \`single\` or \`multi\`.
-- \`required?:boolean\` — whether an empty answer is refused. Defaults to the mode: a \`single\` question must be answered, a \`multi\` one need not be, because leaving every box unticked says "none of these apply". Set \`required\` when the mode's default is wrong — \`required={false}\` on a \`single\` question the user may skip, \`required\` on a \`multi\` one where at least one tick is the point.
-- \`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".
+- \`mode\` \u2014 required: \`single\` or \`multi\`.
+- \`required?:boolean\` \u2014 whether an empty answer is refused. Defaults to the mode: a \`single\` question must be answered, a \`multi\` one need not be, because leaving every box unticked says "none of these apply". Set \`required\` when the mode's default is wrong \u2014 \`required={false}\` on a \`single\` question the user may skip, \`required\` on a \`multi\` one where at least one tick is the point.
+- \`label\` \u2014 required nonempty string: the question itself, drawn as the bold first line.
+- \`body\` \u2014 required nonempty string: markdown rendered above the choices \u2014 the context under the question a label cannot carry. Display-only; contributes nothing to the response.
+- \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` \u2014 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. When the question is required, a \`single\` response needs exactly one selection or nonempty allowed \`freetext\`, and a \`multi\` response needs 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.
+- ${h} UserQuestion accepts only \`option\` anchors; \`optionId\` must name a configured option.
 
 Example
 \`\`\`jsx
@@ -100,84 +50,66 @@ Example
     { id: 'now', label: 'Ship now', description: 'Both gates are green.', recommended: true },
     { id: 'hold', label: 'Hold for the audit' },
   ]} />
-\`\`\``,
-    },
-    {
-        names: ['UserText'],
-        group: 'slot',
-        selectionLine: '`UserText` — writing surface (wire kind `text`). Use whenever the answer is written rather than chosen: a value, a paragraph, or a draft you seeded for them to revise; `singleLine` for a subject, name, or URL. This is the page\'s surface for freeform input — a picker\'s `allowFreetext` is an escape hatch beside its options, not a way to collect prose. Prose the user only reads is a plain element.',
-        contract: `\`<UserText>\` — wire kind \`text\`
+\`\`\``},{names:["UserText"],group:"slot",selectionLine:"`UserText` \u2014 writing surface (wire kind `text`). Use whenever the answer is written rather than chosen: a value, a paragraph, or a draft you seeded for them to revise; `singleLine` for a subject, name, or URL. This is the page's surface for freeform input \u2014 a picker's `allowFreetext` is an escape hatch beside its options, not a way to collect prose. Prose the user only reads is a plain element.",contract:`\`<UserText>\` \u2014 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.
 
-Reach for it whenever what you need back is written rather than picked — a value, a paragraph, or a draft you seeded with \`initialText\` for them to revise. It is the page's one writing surface: \`allowFreetext\` on a picker adds a single "something else" row beside the options, so prose you actually want belongs here instead. It collects text, 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 whenever what you need back is written rather than picked \u2014 a value, a paragraph, or a draft you seeded with \`initialText\` for them to revise. It is the page's one writing surface: \`allowFreetext\` on a picker adds a single "something else" row beside the options, so prose you actually want belongs here instead. It collects text, it does not present it \u2014 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.
 
-${SLOT_RULES}
+${c}
 
 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.
-- \`required?:boolean\` — defaults false. When set, a field left empty (whitespace only) is refused, and the inbox marks it unanswered rather than sending it.
+- \`id\` \u2014 required component id.
+- \`initialText\` \u2014 required string, including an empty string.
+- \`label?:string\` \u2014 the component's label; required by the multi-response page rule.
+- \`placeholder?:string\` \u2014 the hint shown while the field is empty.
+- \`singleLine?:boolean\` \u2014 swaps the writing surface for one compact form field.
+- \`required?:boolean\` \u2014 defaults false. When set, a field left empty (whitespace only) is refused, and the inbox marks it unanswered rather than sending it.
 
 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\`
+\`\`\``},{names:["UserTable"],group:"slot",selectionLine:"`UserTable` \u2014 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>\` \u2014 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}
+${c}
 
 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\`.
-- \`required?:boolean\` — defaults false. When set on a selectable table, a response selecting no row and no column is refused.
-- \`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.
+- \`id\` \u2014 required component id.
+- \`columns\` \u2014 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 \u2014 map your data into this array in the module.
+- \`rowSelect?:"none"|"single"|"multi"\` \u2014 defaults to \`none\`.
+- \`columnSelect?:"none"|"single"|"multi"\` \u2014 defaults to \`none\`.
+- \`required?:boolean\` \u2014 defaults false. When set on a selectable table, a response selecting no row and no column is refused.
+- \`label?:string\` \u2014 the component's label; required by the multi-response page rule when the table is selectable.
+- \`body?:string\` \u2014 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.
+- ${h} 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\`
+\`\`\``},{names:["UserCards"],group:"slot",selectionLine:"`UserCards` \u2014 visual item picker (wire kind `cards`). Use when the user chooses among rich, card-shaped alternatives.",contract:`\`<UserCards>\` \u2014 wire kind \`cards\`
 
-Response-bearing. The response is \`{selectedCardIds:string[]}\` — the selection alone; cards carry no comments.
+Response-bearing. The response is \`{selectedCardIds:string[]}\` \u2014 the selection alone; cards carry no comments.
 
-${SLOT_RULES}
+${c}
 
 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.
-- \`required?:boolean\` — defaults false. When set, a response selecting no card is refused.
-- \`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.
+- \`id\` \u2014 required component id.
+- \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`. Cards are inline \u2014 map your data into this array in the module.
+- \`mode\` \u2014 required: \`single\` or \`multi\`.
+- \`columns?:2|3\` \u2014 optional layout column count.
+- \`required?:boolean\` \u2014 defaults false. When set, a response selecting no card is refused.
+- \`label?:string\` \u2014 the component's label; required by the multi-response page rule.
+- \`body?:string\` \u2014 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.
@@ -186,37 +118,9 @@ 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\`
+\`\`\``},{names:["Chart"],group:"slot",selectionLine:"`Chart` \u2014 data visualization (wire kind `chart`, display-only). Use when a trend or comparison reads better than prose or a table.",contract:'`<Chart>` \u2014 wire kind `chart`\n\nDisplay-only; it has no response. It still takes an `id` when you want the chart recorded in the ticket manifest.\n\nProps\n- `kind` \u2014 required: `line`, `bar`, or `area`.\n- `x` \u2014 required nonempty string naming the x field.\n- `y` \u2014 required nonempty array of `{field:string (nonempty), label?:string}` series.\n- `title?:string`, `data?:` array of JSON row objects. Rows are inline \u2014 build them in the module.\n- `id?:string` \u2014 component id, subject to the same id rules as a response-bearing component when present.\n\nExample\n```jsx\n<Chart kind="line" title="Build minutes" x="day"\n  y={[{ field: \'minutes\', label: \'CI minutes\' }]}\n  data={days.map((d) => ({ day: d.label, minutes: d.minutes }))} />\n```'},{names:["Card","CardHeader","CardTitle","CardDescription","CardContent","CardFooter"],group:"display",selectionLine:"`Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` \u2014 the standard surface for grouping a block of page content.",contract:`\`<Card>\` family \u2014 \`Card\`, \`CardHeader\`, \`CardTitle\`, \`CardDescription\`, \`CardContent\`, \`CardFooter\`
 
-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}
+${s}
 
 Props
 - All six take \`className\` and children only; the nesting carries the meaning.
@@ -228,15 +132,9 @@ Example
   <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>\`
+\`\`\``},{names:["Badge"],group:"display",selectionLine:"`Badge` \u2014 small status or category chip.",contract:`\`<Badge>\`
 
-${DISPLAY_RULES}
+${s}
 
 Props
 - \`variant?:"default"|"secondary"|"destructive"|"outline"\`.
@@ -245,19 +143,13 @@ Props
 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.
+\`\`\``},{names:["Button"],group:"display",selectionLine:"`Button` \u2014 an in-page control. Never a submit: the host owns submit and dismiss.",contract:`\`<Button>\`
+
+${s} A page never renders its own submit or dismiss \u2014 use it for in-page interaction only (revealing detail, switching a local view).
+
+Props \u2014 this Button does NOT take shadcn's \`variant\`; a \`variant\` prop is silently ignored.
+- \`tone?:"brand"|"neutral"|"danger"\` \u2014 what the action means. Unstated, it resolves to \`brand\` on a solid button and \`neutral\` at every other weight.
+- \`weight?:"solid"|"outline"|"quiet"|"link"\` \u2014 how loudly it reads. Default \`solid\`. \`tone="danger"\` has no \`link\` weight \u2014 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.
@@ -265,15 +157,9 @@ Props — this Button does NOT take shadcn's \`variant\`; a \`variant\` prop is
 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\`
+\`\`\``},{names:["Table","TableHeader","TableBody","TableRow","TableHead","TableCell","TableCaption"],group:"display",selectionLine:"`Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` \u2014 read-only tabular layout. Use `UserTable` when the user must select rows or columns.",contract:`\`<Table>\` family \u2014 \`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\`.
+${s} 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\`.
@@ -287,54 +173,36 @@ Example
     <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\`
+\`\`\``},{names:["Tabs","TabsList","TabsTrigger","TabsContent"],group:"display",selectionLine:"`Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` \u2014 parallel views of the same subject behind one control.",contract:`\`<Tabs>\` family \u2014 \`Tabs\`, \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`
 
-${DISPLAY_RULES} Which tab the user opened is not part of the response.
+${s} 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.
+- \`TabsTrigger\` and \`TabsContent\`: \`value\` \u2014 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>
+  <TabsContent value="diff">\u2026</TabsContent>
+  <TabsContent value="risk">\u2026</TabsContent>
 </Tabs>
-\`\`\``,
-    },
-    {
-        names: ['Separator'],
-        group: 'display',
-        selectionLine: '`Separator` — a rule between sections.',
-        contract: `\`<Separator>\`
+\`\`\``},{names:["Separator"],group:"display",selectionLine:"`Separator` \u2014 a rule between sections.",contract:`\`<Separator>\`
 
-${DISPLAY_RULES}
+${s}
 
 Props
-- \`orientation?:"horizontal"|"vertical"\` — defaults to \`horizontal\`.
+- \`orientation?:"horizontal"|"vertical"\` \u2014 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\`
+\`\`\``},{names:["Alert","AlertTitle","AlertDescription"],group:"display",selectionLine:"`Alert`, `AlertTitle`, `AlertDescription` \u2014 a callout for the one thing the user must not miss.",contract:`\`<Alert>\` family \u2014 \`Alert\`, \`AlertTitle\`, \`AlertDescription\`
 
-${DISPLAY_RULES}
+${s}
 
 Props
 - \`Alert\`: \`variant?:"default"|"destructive"\`, \`className\`.
@@ -346,36 +214,24 @@ Example
   <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>\`
+\`\`\``},{names:["Progress"],group:"display",selectionLine:"`Progress` \u2014 a completion bar for a known ratio.",contract:`\`<Progress>\`
 
-${DISPLAY_RULES}
+${s}
 
 Props
-- \`value?:number\` — 0 to 100.
+- \`value?:number\` \u2014 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\`
+\`\`\``},{names:["Accordion","AccordionItem","AccordionTrigger","AccordionContent"],group:"display",selectionLine:"`Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` \u2014 supporting detail the user opens only if they want it.",contract:`\`<Accordion>\` family \u2014 \`Accordion\`, \`AccordionItem\`, \`AccordionTrigger\`, \`AccordionContent\`
 
-${DISPLAY_RULES}
+${s}
 
 Props
-- \`Accordion\`: \`type\` — required: \`single\` or \`multiple\`; \`collapsible?:boolean\`, \`defaultValue?:string|string[]\`, \`className\`.
-- \`AccordionItem\`: \`value\` — required, unique within the accordion.
+- \`Accordion\`: \`type\` \u2014 required: \`single\` or \`multiple\`; \`collapsible?:boolean\`, \`defaultValue?:string|string[]\`, \`className\`.
+- \`AccordionItem\`: \`value\` \u2014 required, unique within the accordion.
 - \`AccordionTrigger\` and \`AccordionContent\`: \`className\` and children.
 
 Example
@@ -386,57 +242,7 @@ Example
     <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`}`;
-}
+\`\`\``}],w=new Map(i.flatMap(t=>t.names.map(n=>[n,t]))),x=[...i.filter(t=>t.group!=="display").map(t=>t.selectionLine),"`usePageHost` \u2014 reserved host hook. Its product-supplied members are opaque to crouter; consult the owning product documentation."];function f(t){return w.get(t)}r(f,"componentDoc");function k(t){return[...i.flatMap(n=>[...n.names]),...p(t).values()]}r(k,"componentNames");const y={structural:"Structural \u2014 every page is built from these.",slot:"Response \u2014 each is recorded in the page manifest under its wire kind, and their answers are the page response.",display:"Display \u2014 shadcn components with their standard props, plus `className` for Tailwind. They contribute nothing to the response."};function v(t){const a=[`<components count="${i.reduce((e,o)=>e+o.names.length,0)+t.length}">`];for(const e of["structural","slot","display"])a.push(y[e],...i.filter(o=>o.group===e).map(o=>o.selectionLine),"");const l=p(t);t.length>0?a.push("Product-registered \u2014 registry components this product ships. Write each one under the tag shown; a `(kind \u2026)` suffix names its lowercase-hyphen wire kind."):a.pop();for(const e of t){const o=l.get(e.kind)??e.kind,u=o===e.kind?`\`${o}\``:`\`${o}\` (kind \`${e.kind}\`)`;if(e.description===void 0&&e.useWhen===void 0){a.push(`${u} \u2014 ${e.display===!0?"product-registered; display-only":"product-registered"}`);continue}const d=[e.description,e.useWhen===void 0?void 0:`${e.useWhen[0].toUpperCase()}${e.useWhen.slice(1)}`,...e.display===!0?["Display-only"]:[]].filter(g=>g!==void 0);a.push(`${u} \u2014 ${d.join(". ")}`)}return a.push("</components>"),a.join(`
+`)}r(v,"renderComponentCatalog");function A(t,n){const a=f(t);if(a!==void 0)return a.contract;const l=p(n),e=n.find(d=>d.kind===t||l.get(d.kind)===t);return e===void 0?void 0:`${`\`<${l.get(e.kind)??e.kind}>\` \u2014 product-registered, wire kind \`${e.kind}\``}
+
+${e.doc??`product-registered${e.display===!0?"; display-only":"; config is passed through unvalidated (unvalidated: true)"} \u2014 see the product's own docs`}`}r(A,"renderComponentContract");export{i as BUILTIN_COMPONENT_DOCS,x as CORE_COMPONENT_SELECTION_LINES,f as componentDoc,k as componentNames,v as renderComponentCatalog,A as renderComponentContract};

package/dist/core/human/convention.js

@@ -1,82 +1,2 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { atomicWriteJson, atomicWriteText } from '../fs-utils.js';
-export { atomicWriteJson, atomicWriteText };
-/** 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`; }
-/** The frozen completion-action binding, written once at request creation. */
-export function actionBindingPath(dir) { return `${dir}/action.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';
-    if (existsSync(responsePath(dir)))
-        return 'resolved';
-    return existsSync(claimPath(dir)) ? 'claimed' : 'pending';
-}
-export function isResolved(dir) { return existsSync(responsePath(dir)); }
-export function isClaimed(dir) { return existsSync(claimPath(dir)); }
-/** Resolve and verify a ticket directory without a registry. */
-export function requireTicket(dir) {
-    const canonicalDir = realpathSync(dir);
-    if (!existsSync(pageManifestPath(canonicalDir)) && !existsSync(reviewPath(canonicalDir))) {
-        throw new Error('ticket directory has no page or review');
-    }
-    return canonicalDir;
-}
-/** 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`;
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    try {
-        linkSync(tmp, path);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return false;
-        throw error;
-    }
-    finally {
-        unlinkSync(tmp);
-    }
-}
-export function clearProgress(dir) {
-    try {
-        unlinkSync(progressPath(dir));
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-    }
-}
+var d=Object.defineProperty;var t=(r,e)=>d(r,"name",{value:e,configurable:!0});import{existsSync as n,linkSync as x,mkdirSync as h,readFileSync as m,realpathSync as g,unlinkSync as c,writeFileSync as y}from"node:fs";import{dirname as $}from"node:path";import{atomicWriteJson as u,atomicWriteText as w}from"../fs-utils.js";function E(r,e="jsx"){return`${r}/page.${e==="jsx"?"tsx":"html"}`}t(E,"pagePath");function b(r){return`${r}/page.js`}t(b,"pageModulePath");function s(r){return`${r}/page.json`}t(s,"pageManifestPath");function a(r){return`${r}/review.json`}t(a,"reviewPath");function p(r){return`${r}/response.json`}t(p,"responsePath");function S(r){return`${r}/progress.json`}t(S,"progressPath");function l(r){return`${r}/claim.json`}t(l,"claimPath");function f(r){return`${r}/reply-route.json`}t(f,"replyRoutePath");function R(r){return`${r}/action.json`}t(R,"actionBindingPath");function T(r){const e=f(r);if(!n(e))return null;let o;try{o=JSON.parse(m(e,"utf8"))}catch{throw new Error(`invalid ticket reply route: ${e}`)}const i=o?.bridge_node_id;if(typeof i!="string"||i==="")throw new Error(`invalid ticket reply route: ${e}`);return{bridge_node_id:i}}t(T,"readTicketReplyRoute");function _(r,e){u(f(r),{bridge_node_id:e})}t(_,"bindTicketReplyRoute");function N(r){return!n(s(r))&&!n(a(r))?"missing":n(p(r))?"resolved":n(l(r))?"claimed":"pending"}t(N,"interactionState");function J(r){return n(p(r))}t(J,"isResolved");function M(r){return n(l(r))}t(M,"isClaimed");function O(r){const e=g(r);if(!n(s(e))&&!n(a(e)))throw new Error("ticket directory has no page or review");return e}t(O,"requireTicket");function F(r,e){const o=`${r}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;h($(r),{recursive:!0,mode:448}),y(o,`${JSON.stringify(e,null,2)}
+`,{mode:384});try{return x(o,r),!0}catch(i){if(i.code==="EEXIST")return!1;throw i}finally{c(o)}}t(F,"publishJsonExclusive");function I(r){try{c(S(r))}catch(e){if(e.code!=="ENOENT")throw e}}t(I,"clearProgress");export{R as actionBindingPath,u as atomicWriteJson,w as atomicWriteText,_ as bindTicketReplyRoute,l as claimPath,I as clearProgress,N as interactionState,M as isClaimed,J as isResolved,s as pageManifestPath,b as pageModulePath,E as pagePath,S as progressPath,F as publishJsonExclusive,T as readTicketReplyRoute,f as replyRoutePath,O as requireTicket,p as responsePath,a as reviewPath};