@north-light/api 0.3.580 → 0.3.588

package/dist/core/human/claim.js

@@ -0,0 +1,67 @@
+import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { claimPath } from './convention.js';
+import { readJsonOrNull } from '../fs-utils.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
+const REMOTE_STALE_MS = 30_000;
+function parseClaim(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const claim = raw;
+    if (typeof claim.token !== 'string' || typeof claim.host !== 'string' || !Number.isInteger(claim.pid) || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
+        return null;
+    return { token: claim.token, host: claim.host, pid: claim.pid, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt, ...(typeof claim.tmuxClient === 'string' ? { tmuxClient: claim.tmuxClient } : {}) };
+}
+export function readTicketClaim(dir) { return parseClaim(readJsonOrNull(claimPath(dir))); }
+function isLiveLocalPid(pid) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} }
+export function isStaleClaim(claim, now = Date.now(), localHost = hostname()) {
+    if (claim.host === localHost)
+        return !isLiveLocalPid(claim.pid);
+    const heartbeat = Date.parse(claim.heartbeatAt);
+    return !Number.isFinite(heartbeat) || now - heartbeat > REMOTE_STALE_MS;
+}
+/** Exclude another live presenter; the daemon owns whether the request can settle. */
+export function claimTicket(dir, opts = {}) {
+    return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => {
+        const path = claimPath(dir);
+        const existing = readTicketClaim(dir);
+        if (existing !== null && !isStaleClaim(existing, Date.now(), opts.host ?? hostname()))
+            return null;
+        if (existsSync(path))
+            unlinkSync(path);
+        const host = opts.host ?? hostname();
+        const pid = opts.pid ?? process.pid;
+        const now = (opts.now ?? new Date()).toISOString();
+        const claim = { token: randomUUID(), host, pid, claimedAt: now, heartbeatAt: now, ...(opts.tmuxClient ? { tmuxClient: opts.tmuxClient } : {}) };
+        writeFileSync(path, `${JSON.stringify(claim)}\n`, { flag: 'wx', mode: 0o600 });
+        return claim;
+    });
+}
+export function heartbeatClaim(dir, token, now = new Date()) {
+    return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => {
+        const claim = readTicketClaim(dir);
+        if (claim === null || claim.token !== token)
+            return false;
+        const temp = `${claimPath(dir)}.${token}.heartbeat`;
+        writeFileSync(temp, `${JSON.stringify({ ...claim, heartbeatAt: now.toISOString() })}\n`, { flag: 'wx', mode: 0o600 });
+        renameSync(temp, claimPath(dir));
+        return true;
+    });
+}
+export function releaseClaimLocked(dir, token) {
+    const claim = readTicketClaim(dir);
+    if (claim === null || claim.token !== token)
+        return false;
+    unlinkSync(claimPath(dir));
+    return true;
+}
+export function releaseClaim(dir, token) { return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => releaseClaimLocked(dir, token)); }
+export function claimExists(dir) { return existsSync(claimPath(dir)); }
+export function withTicketLock(dir, operation) { return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, operation); }

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

@@ -0,0 +1,38 @@
+import type { TicketActionBinding } from './action-binding.js';
+import type { PageSource } from './page-schema.js';
+import type { TicketResult } from './types.js';
+export type HumanCompletionEvent = 'answered' | 'dismissed' | 'canceled';
+export interface HumanCompletionV1 {
+    schema: 'crtr.human-completion/v1';
+    requestId: string;
+    event: HumanCompletionEvent;
+    settledAt: string;
+    /** Present only when `event` is `answered`; absent, never empty, otherwise. */
+    responses?: Record<string, Record<string, unknown>>;
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    provenance: {
+        source: PageSource;
+        actor?: string;
+    };
+    /** The lane overwrites this with the real attempt before writing stdin. */
+    delivery: {
+        attempt: number;
+    };
+}
+/** The one place a cancellation record without `disposition` reads as
+ * `canceled`. Every other reader treats both dispositions alike. */
+export declare function completionEventFor(result: TicketResult): HumanCompletionEvent;
+/** Build the complete document with `delivery.attempt` as the lane's placeholder. */
+export declare function composeHumanCompletion(args: {
+    requestId: string;
+    result: PageTerminalResult;
+    binding: TicketActionBinding;
+    source: PageSource;
+}): HumanCompletionV1;
+/** A review result can never carry an action binding; the composer is total over the rest. */
+export type PageTerminalResult = Extract<TicketResult, {
+    kind: 'page' | 'canceled';
+}>;

package/dist/core/human/completion.js

@@ -0,0 +1,27 @@
+// The `crtr.human-completion/v1` document handed to a completion action on
+// stdin. Composed at settlement from the canonical terminal result, so the
+// delivered document reflects the settlement instant and the delivery lane
+// never reads ticket storage.
+/** The one place a cancellation record without `disposition` reads as
+ * `canceled`. Every other reader treats both dispositions alike. */
+export function completionEventFor(result) {
+    if (result.kind === 'canceled')
+        return result.disposition ?? 'canceled';
+    return 'answered';
+}
+/** Build the complete document with `delivery.attempt` as the lane's placeholder. */
+export function composeHumanCompletion(args) {
+    const { requestId, result, binding, source } = args;
+    const event = completionEventFor(result);
+    const actor = result.actor;
+    return {
+        schema: 'crtr.human-completion/v1',
+        requestId,
+        event,
+        settledAt: result.kind === 'page' ? result.completedAt : result.canceledAt,
+        ...(result.kind === 'page' ? { responses: result.responses } : {}),
+        action: { name: binding.name, payload: binding.payload },
+        provenance: { source, ...(actor === undefined ? {} : { actor }) },
+        delivery: { attempt: 0 },
+    };
+}

package/dist/core/human/component-docs.d.ts

@@ -0,0 +1,18 @@
+import type { PageComponentRegistration } from '../../types.js';
+export interface ComponentDoc {
+    /** Registry names this doc covers. A family (Card, CardHeader, …) shares one contract. */
+    names: readonly string[];
+    /** `structural` builds the page, `slot` is a registry component that gets its own manifest
+     * record (and, unless display-only, its own response), `display` is presentation only. */
+    group: 'structural' | 'slot' | 'display';
+    selectionLine: string;
+    contract: string;
+}
+export declare const BUILTIN_COMPONENT_DOCS: readonly ComponentDoc[];
+/** 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 declare const CORE_COMPONENT_SELECTION_LINES: string[];
+export declare function componentDoc(name: string): ComponentDoc | undefined;
+export declare function componentNames(productComponents: readonly PageComponentRegistration[]): string[];
+export declare function renderComponentCatalog(productComponents: readonly PageComponentRegistration[]): string;
+export declare function renderComponentContract(name: string, productComponents: readonly PageComponentRegistration[]): string | undefined;

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

@@ -0,0 +1,442 @@
+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>\`
+
+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>\`.
+- 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\`
+
+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, recommended?:boolean}\`.
+- \`recommended\` on one option marks it the suggested answer. A \`single\` question may recommend at most one option; a \`multi\` question may recommend several, and accepting from the list ticks them all. 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".
+
+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.
+
+Example
+\`\`\`jsx
+<UserQuestion id="lane" label="Release lane" mode="single" allowFreetext
+  body={"The audit closes tomorrow.\\n\\nBoth release gates are green as of this morning."}
+  freetextLabel="Something else"
+  options={[
+    { 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\`
+
+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.
+
+${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.
+- \`required?:boolean\` — 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\`
+
+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\`.
+- \`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.
+
+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[]}\` — the selection alone; cards carry no comments.
+
+${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.
+- \`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.
+
+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

@@ -0,0 +1,31 @@
+import { atomicWriteJson, atomicWriteText } from '../fs-utils.js';
+export { atomicWriteJson, atomicWriteText };
+/** 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;
+/** The frozen completion-action binding, written once at request creation. */
+export declare function actionBindingPath(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;
+/** Publish one immutable JSON record without replacing an existing winner. */
+export declare function publishJsonExclusive(path: string, value: unknown): boolean;
+export declare function clearProgress(dir: string): void;