@handamade/psi-mcp 0.25.0 → 0.27.0

package/README.md

@@ -1,6 +1,6 @@
 # @handamade/psi-mcp
 
-MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 47 React 19 components, 23 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
+MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 52 React 19 components, 24 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
 
 ## Connect
 

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.25.0",
+ "version": "0.27.0",
  "themes": [
   "light",
   "dark",
@@ -242,6 +242,120 @@
    ],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Panel\n\nElevated surface panel (D51): secondary background, faint hairline, radius-12 — the shared --psi-surface-* recipe Dialog's panel also binds. Not a Card: no media slot, no hover lift, opaque by design.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Panel contents. |\n| `padding` | `16 \\| 24` | 24 | no | Inner padding in px. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the root element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Skipped — Panel itself is not focusable; focus moves through its children. |\n\nPlain <div> container with no implicit role. Pass aria-* host props if the panel should announce as a region.\n\n## Theming\n\nOverride `--psi-panel-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
+  {
+   "name": "Stack",
+   "description": "A column with a gap from the space scale (D109): Toolbar's vertical counterpart, minus the wrap. A plain <div> with no role. It gives a pattern tree a layout context, which Panel and the psi-gap-* utilities do not.",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Stack contents, laid out top to bottom."
+    },
+    {
+     "name": "gap",
+     "type": "4 | 8 | 12 | 16 | 24 | 32",
+     "required": false,
+     "default": 16,
+     "description": "Space between children in px, from the space scale."
+    },
+    {
+     "name": "align",
+     "type": "\"stretch\" | \"start\" | \"center\" | \"end\"",
+     "required": false,
+     "default": "stretch",
+     "description": "Cross-axis alignment. `stretch` (the default) makes each child full\nwidth; `start` keeps a Button or a short line at its own width."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the root element."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Stack\n\nA column with a gap from the space scale (D109): Toolbar's vertical counterpart, minus the wrap. A plain <div> with no role. It gives a pattern tree a layout context, which Panel and the psi-gap-* utilities do not.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Stack contents, laid out top to bottom. |\n| `gap` | `4 \\| 8 \\| 12 \\| 16 \\| 24 \\| 32` | 16 | no | Space between children in px, from the space scale. |\n| `align` | `\"stretch\" \\| \"start\" \\| \"center\" \\| \"end\"` | stretch | no | Cross-axis alignment. `stretch` (the default) makes each child full width; `start` keeps a Button or a short line at its own width. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the root element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Skipped — Stack itself is not focusable; focus moves through its children in source order. |\n\nPlain <div> with no role (D109): a column with a gap. Visual order is source order, so reading and focus order match.\n\n## Theming\n\nThis component has no `--psi-stack-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "Text",
+   "description": "A line or paragraph of text at one of Psi's text styles (D109). It gives a pattern tree an element per line, so a headline and its explanation do not run together. Margin 0: a Stack's gap does the spacing.",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "The text."
+    },
+    {
+     "name": "as",
+     "type": "\"p\" | \"span\" | \"div\" | \"h2\" | \"h3\" | \"h4\"",
+     "required": false,
+     "default": "p",
+     "description": "The element. A heading's level follows the document outline, its size\nthe design, so `as` and `size` are separate."
+    },
+    {
+     "name": "size",
+     "type": "12 | 14 | 16 | 18",
+     "required": false,
+     "default": 14,
+     "description": "Font size in px; each size carries its own line height."
+    },
+    {
+     "name": "weight",
+     "type": "\"regular\" | \"medium\"",
+     "required": false,
+     "default": "regular",
+     "description": ""
+    },
+    {
+     "name": "tone",
+     "type": "\"primary\" | \"secondary\"",
+     "required": false,
+     "default": "primary",
+     "description": "`secondary` for supporting text."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the element."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Text\n\nA line or paragraph of text at one of Psi's text styles (D109). It gives a pattern tree an element per line, so a headline and its explanation do not run together. Margin 0: a Stack's gap does the spacing.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The text. |\n| `as` | `\"p\" \\| \"span\" \\| \"div\" \\| \"h2\" \\| \"h3\" \\| \"h4\"` | p | no | The element. A heading's level follows the document outline, its size the design, so `as` and `size` are separate. |\n| `size` | `12 \\| 14 \\| 16 \\| 18` | 14 | no | Font size in px; each size carries its own line height. |\n| `weight` | `\"regular\" \\| \"medium\"` | regular | no |  |\n| `tone` | `\"primary\" \\| \"secondary\"` | primary | no | `secondary` for supporting text. |\n| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Not focusable. |\n\nRenders the element `as` names (p by default). Use h2–h4 for a heading at its outline level, whatever its `size`.\n\n## Theming\n\nOverride `--psi-text-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
   {
    "name": "DescriptionList",
    "description": "Key/value display (D70): a `<dl>` of term/value pairs, the body `detail-drawer` has always described and never had a component for. No `size` prop — this is type, and the type scale is already expressed by --psi-text-*. Consumers restyle via the token family, not a prop.",
@@ -587,7 +701,28 @@
      "type": "boolean",
      "required": false,
      "default": true,
-     "description": "false = no close button, Esc and backdrop swallowed — footer is the only exit."
+     "description": "false = no close button, Esc and backdrop swallowed — footer is the only exit.\n`closeOnEscape` can give Escape back on its own (D101)."
+    },
+    {
+     "name": "closeOnEscape",
+     "type": "boolean",
+     "required": false,
+     "default": "dismissible",
+     "description": "Whether Escape reports onClose(\"esc\"), separately from the close button\nand the backdrop (D101). A consequential confirmation is\n`dismissible={false} closeOnEscape`: no close button, no backdrop\ndismissal, and Escape cancels."
+    },
+    {
+     "name": "initialFocus",
+     "type": "RefObject<HTMLElement | null>",
+     "required": false,
+     "default": null,
+     "description": "The element to focus each time the dialog opens, after the platform's own\nfocusing (D101), e.g. a ref to the footer's Cancel button. Without it, the\nplatform focuses the first focusable control, as before."
+    },
+    {
+     "name": "closeLabel",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Visible text for the close button (D101). When set, the close button is a\nghost Button with this text instead of the icon-only \"Close dialog\"\nbutton."
     },
     {
      "name": "ref",
@@ -635,11 +770,11 @@
      "order": 3
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Dialog\n\nModal dialog on the native <dialog> top layer: focus trap, aria-modal and focus restore come from the platform; title/footer slots, Esc/backdrop/ close-button dismissal via onClose(reason) (D50). `placement` moves the panel and nothing else (D66): an `inline-start` / `inline-end` Dialog is a drawer, pinned full-height to that edge, with the same modality, focus trap, focus restore and dismissal reasons as a centered one. There is deliberately no separate Drawer component — a sibling would have to duplicate or wrap all of that.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Body content, between the title and footer slots. |\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showModal()/close(). |\n| `onClose` | `(reason: \"esc\" \\| \"backdrop\" \\| \"close-button\") => void` | — | yes | Called on every dismissal attempt with its source; the consumer flips `open`. |\n| `title` | `ReactNode` | — | no | Heading; renders an <h2> wired to aria-labelledby. Without it, pass aria-label. |\n| `footer` | `ReactNode` | — | no | Action row (Buttons — one accent per group, danger for destructive). |\n| `width` | `400 \\| 560 \\| 720` | 560 | no | Panel width in px (400 \\| 560 \\| 720). For an `inline-*` placement this is the drawer's width; the height is always the full viewport. |\n| `placement` | `\"center\" \\| \"inline-start\" \\| \"inline-end\"` | center | no | Where the panel sits. `inline-start` / `inline-end` pin it full-height to that edge, making it a drawer (D66). |\n| `dismissible` | `boolean` | true | no | false = no close button, Esc and backdrop swallowed — footer is the only exit. |\n| `ref` | `Ref<HTMLDialogElement>` | — | no | Forwarded ref to the underlying <dialog> element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Esc | Dismisses via onClose('esc') when dismissible; swallowed otherwise. |\n| Tab | Focus is trapped inside by the native <dialog> top layer; restored on close. |\n\nRendered with showModal(): aria-modal, inert background and focus restore come from the platform. title wires aria-labelledby; without title, pass aria-label. Backdrop click dismisses only when dismissible. placement=\"inline-start\"/\"inline-end\" pins the panel full-height to that edge — that is Psi's drawer, and it changes nothing about modality, the focus trap, focus restore or the dismissal reasons (D66). A drawer's panel scrolls internally so a dismissible={false} footer stays reachable.\n\n## Theming\n\nOverride `--psi-dialog-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Dialog\n\nModal dialog on the native <dialog> top layer: focus trap, aria-modal and focus restore come from the platform; title/footer slots, Esc/backdrop/ close-button dismissal via onClose(reason) (D50). `placement` moves the panel and nothing else (D66): an `inline-start` / `inline-end` Dialog is a drawer, pinned full-height to that edge, with the same modality, focus trap, focus restore and dismissal reasons as a centered one. There is deliberately no separate Drawer component — a sibling would have to duplicate or wrap all of that.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Body content, between the title and footer slots. |\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showModal()/close(). |\n| `onClose` | `(reason: \"esc\" \\| \"backdrop\" \\| \"close-button\") => void` | — | yes | Called on every dismissal attempt with its source; the consumer flips `open`. |\n| `title` | `ReactNode` | — | no | Heading; renders an <h2> wired to aria-labelledby. Without it, pass aria-label. |\n| `footer` | `ReactNode` | — | no | Action row (Buttons — one accent per group, danger for destructive). |\n| `width` | `400 \\| 560 \\| 720` | 560 | no | Panel width in px (400 \\| 560 \\| 720). For an `inline-*` placement this is the drawer's width; the height is always the full viewport. |\n| `placement` | `\"center\" \\| \"inline-start\" \\| \"inline-end\"` | center | no | Where the panel sits. `inline-start` / `inline-end` pin it full-height to that edge, making it a drawer (D66). |\n| `dismissible` | `boolean` | true | no | false = no close button, Esc and backdrop swallowed — footer is the only exit. `closeOnEscape` can give Escape back on its own (D101). |\n| `closeOnEscape` | `boolean` | dismissible | no | Whether Escape reports onClose(\"esc\"), separately from the close button and the backdrop (D101). A consequential confirmation is `dismissible={false} closeOnEscape`: no close button, no backdrop dismissal, and Escape cancels. |\n| `initialFocus` | `RefObject<HTMLElement \\| null>` | — | no | The element to focus each time the dialog opens, after the platform's own focusing (D101), e.g. a ref to the footer's Cancel button. Without it, the platform focuses the first focusable control, as before. |\n| `closeLabel` | `string` | — | no | Visible text for the close button (D101). When set, the close button is a ghost Button with this text instead of the icon-only \"Close dialog\" button. |\n| `ref` | `Ref<HTMLDialogElement>` | — | no | Forwarded ref to the underlying <dialog> element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Esc | Dismisses via onClose('esc') when closeOnEscape (default: dismissible); swallowed otherwise (D101). |\n| Tab | Focus is trapped inside by the native <dialog> top layer; restored on close. |\n\nRendered with showModal(): aria-modal, inert background and focus restore come from the platform. title wires aria-labelledby; without title, pass aria-label. Backdrop click dismisses only when dismissible. placement=\"inline-start\"/\"inline-end\" pins the panel full-height to that edge — that is Psi's drawer, and it changes nothing about modality, the focus trap, focus restore or the dismissal reasons (D66). A drawer's panel scrolls internally so a dismissible={false} footer stays reachable.\n\n## Theming\n\nOverride `--psi-dialog-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "Checkbox",
-   "description": "Native checkbox with a built-in label; for independent binary choices.",
+   "description": "Native checkbox with a built-in label; for independent binary choices. In an invalid group Field it is aria-invalid, and an unchecked box marked aria-invalid outlines in the error colour (D108).",
    "props": [
     {
      "name": "children",
@@ -655,6 +790,13 @@
      "default": null,
      "description": "Accessible name when there is no visible label — a table's row-selection\ncheckbox, say. Optional, unlike IconButton's required form (D60): a\nlabelled checkbox is still the common case."
     },
+    {
+     "name": "indeterminate",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "The mixed state, e.g. a \"select all\" over a partial selection (D103).\nSets the input's DOM property, which the platform exposes as\naria-checked=\"mixed\", and draws a dash. Re-applied on every render,\nbecause a click clears the property before the consumer re-renders.\nWhen absent, the property is left alone, so a state set through the ref\nsurvives."
+    },
     {
      "name": "ref",
      "type": "Ref<HTMLInputElement>",
@@ -671,7 +813,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Checkbox\n\nNative checkbox with a built-in label; for independent binary choices.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label text. |\n| `aria-label` | `string` | — | no | Accessible name when there is no visible label — a table's row-selection checkbox, say. Optional, unlike IconButton's required form (D60): a labelled checkbox is still the common case. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input type=\"checkbox\">` element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Space | Toggles. Native <input type=checkbox> underneath (visually hidden). |\n\n\n## Theming\n\nOverride `--psi-checkbox-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Checkbox\n\nNative checkbox with a built-in label; for independent binary choices. In an invalid group Field it is aria-invalid, and an unchecked box marked aria-invalid outlines in the error colour (D108).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label text. |\n| `aria-label` | `string` | — | no | Accessible name when there is no visible label — a table's row-selection checkbox, say. Optional, unlike IconButton's required form (D60): a labelled checkbox is still the common case. |\n| `indeterminate` | `boolean` | — | no | The mixed state, e.g. a \"select all\" over a partial selection (D103). Sets the input's DOM property, which the platform exposes as aria-checked=\"mixed\", and draws a dash. Re-applied on every render, because a click clears the property before the consumer re-renders. When absent, the property is left alone, so a state set through the ref survives. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input type=\"checkbox\">` element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Space | Toggles. Native <input type=checkbox> underneath (visually hidden). |\n\n\n## Theming\n\nOverride `--psi-checkbox-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "Switch",
@@ -702,6 +844,202 @@
    "slots": [],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Switch\n\nOn/off toggle (`role=\"switch\"`) with a built-in label; for settings that take effect immediately.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label text. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input type=\"checkbox\" role=\"switch\">` element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Space | Toggles. Native checkbox input with role=\"switch\"; announced as a switch, not a checkbox. |\n\n\n## Theming\n\nOverride `--psi-switch-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
+  {
+   "name": "Textarea",
+   "description": "Multi-line text input (D104): the Input recipe on a native `<textarea>`. Inside a Field, id/aria-describedby/aria-invalid/required are wired as for Input (D49). `minLength` and `maxLength` are the native attributes. With `maxLength`, a counter under the control shows the length; it is not a live region (a count spoken on every keystroke is noise) and joins aria-describedby, so it is read with the field on focus.",
+   "props": [
+    {
+     "name": "rows",
+     "type": "number",
+     "required": false,
+     "default": 3,
+     "description": "Visible rows. A textarea's height is its rows; there is no `size`."
+    },
+    {
+     "name": "minLength",
+     "type": "number",
+     "required": false,
+     "default": null,
+     "description": "Native minimum length, reported by constraint validation."
+    },
+    {
+     "name": "maxLength",
+     "type": "number",
+     "required": false,
+     "default": null,
+     "description": "Native maximum length, enforced while typing. With it, the counter shows\n`{length} / {maxLength}` unless `showCounter={false}`."
+    },
+    {
+     "name": "error",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": "Show error styling. Inside a Field, the Field's error also lights this."
+    },
+    {
+     "name": "showCounter",
+     "type": "boolean",
+     "required": false,
+     "default": true,
+     "description": "With `maxLength`, show the `{length} / {maxLength}` counter under the\ncontrol. It is not a live region; it describes the textarea."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLTextAreaElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<textarea>` element."
+    },
+    {
+     "name": "placeholder",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Native placeholder text shown while the field is empty (only on components whose host element supports it)."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Textarea\n\nMulti-line text input (D104): the Input recipe on a native `<textarea>`. Inside a Field, id/aria-describedby/aria-invalid/required are wired as for Input (D49). `minLength` and `maxLength` are the native attributes. With `maxLength`, a counter under the control shows the length; it is not a live region (a count spoken on every keystroke is noise) and joins aria-describedby, so it is read with the field on focus.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `rows` | `number` | 3 | no | Visible rows. A textarea's height is its rows; there is no `size`. |\n| `minLength` | `number` | — | no | Native minimum length, reported by constraint validation. |\n| `maxLength` | `number` | — | no | Native maximum length, enforced while typing. With it, the counter shows `{length} / {maxLength}` unless `showCounter={false}`. |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `showCounter` | `boolean` | true | no | With `maxLength`, show the `{length} / {maxLength}` counter under the control. It is not a live region; it describes the textarea. |\n| `ref` | `Ref<HTMLTextAreaElement>` | — | no | Forwarded ref to the underlying `<textarea>` element. |\n| `placeholder` | `string` | — | no | Native placeholder text shown while the field is empty (only on components whose host element supports it). |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | A native <textarea>; Enter adds a line, it does not submit the form. |\n\nInside a Field, id/aria-describedby/aria-invalid/required are wired as for Input (D104). minLength and maxLength are native. With maxLength, a counter under the control shows {length} / {maxLength}; it is not a live region, and it joins aria-describedby so it is read with the field on focus, with a visually hidden \"characters\".\n\n## Theming\n\nOverride `--psi-textarea-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "RadioGroup",
+   "description": "A set of native radios sharing one name (D104). The browser supplies the keyboard: Tab enters on the checked radio, and the arrows move and select. Inside `Field group` the fieldset and legend form and name the group, so this adds no role; standalone it is `role=\"radiogroup\"` and needs `aria-label` or `aria-labelledby`. A required or invalid Field makes every radio `required` and `aria-invalid`.",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "`Radio` children."
+    },
+    {
+     "name": "name",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "The radios' shared `name`. Generated when absent."
+    },
+    {
+     "name": "value",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "The selected value (controlled)."
+    },
+    {
+     "name": "defaultValue",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "The initially selected value (uncontrolled)."
+    },
+    {
+     "name": "onValueChange",
+     "type": "((value: string) => void)",
+     "required": false,
+     "default": null,
+     "description": "Called with the value of the radio the user selects."
+    },
+    {
+     "name": "disabled",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": "Disables every radio in the group."
+    },
+    {
+     "name": "orientation",
+     "type": "\"vertical\" | \"horizontal\"",
+     "required": false,
+     "default": "vertical",
+     "description": "Stack the radios, or lay them in a row."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name when the group stands alone. Inside `Field group` the\nlegend names the group instead."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the root element."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {
+      "components": [
+       "Radio"
+      ]
+     },
+     "cardinality": "1..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# RadioGroup\n\nA set of native radios sharing one name (D104). The browser supplies the keyboard: Tab enters on the checked radio, and the arrows move and select. Inside `Field group` the fieldset and legend form and name the group, so this adds no role; standalone it is `role=\"radiogroup\"` and needs `aria-label` or `aria-labelledby`. A required or invalid Field makes every radio `required` and `aria-invalid`.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | `Radio` children. |\n| `name` | `string` | — | no | The radios' shared `name`. Generated when absent. |\n| `value` | `string` | — | no | The selected value (controlled). |\n| `defaultValue` | `string` | — | no | The initially selected value (uncontrolled). |\n| `onValueChange` | `((value: string) => void)` | — | no | Called with the value of the radio the user selects. |\n| `disabled` | `boolean` | false | no | Disables every radio in the group. |\n| `orientation` | `\"vertical\" \\| \"horizontal\"` | vertical | no | Stack the radios, or lay them in a row. |\n| `aria-label` | `string` | — | no | Accessible name when the group stands alone. Inside `Field group` the legend names the group instead. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the root element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Enters the group on the checked radio, or the first one; one tab stop for the group. |\n| Arrow keys | Move to the next or previous radio and select it (native radios sharing one name). |\n\nNative radios sharing one name (D104). Inside Field group the fieldset and legend form and name the group, so RadioGroup adds no role; standalone it is role=\"radiogroup\" and needs aria-label or aria-labelledby. A required or invalid Field makes every radio required and aria-invalid.\n\n## Theming\n\nOverride `--psi-radio-group-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "Radio",
+   "description": "One choice in a RadioGroup (D104): a native radio with a built-in label, drawn like Checkbox on a circle. Takes its name, checked state, required and aria-invalid from the group.",
+   "props": [
+    {
+     "name": "value",
+     "type": "string",
+     "required": true,
+     "default": null,
+     "description": "The value this radio selects."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Label text."
+    },
+    {
+     "name": "disabled",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "Disables this radio; a disabled RadioGroup disables all of them."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLInputElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<input type=\"radio\">` element."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Radio\n\nOne choice in a RadioGroup (D104): a native radio with a built-in label, drawn like Checkbox on a circle. Takes its name, checked state, required and aria-invalid from the group.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | The value this radio selects. |\n| `children` | `ReactNode` | — | no | Label text. |\n| `disabled` | `boolean` | — | no | Disables this radio; a disabled RadioGroup disables all of them. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input type=\"radio\">` element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Space | Selects the focused radio when none is selected. |\n\nNative <input type=radio> underneath (visually hidden), drawn like Checkbox on a circle. Takes its name, checked state, required and aria-invalid from its RadioGroup.\n\n## Theming\n\nThis component has no `--psi-radio-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
   {
    "name": "Tag",
    "description": "Compact label for status or category; semantic variants, optional subtle tint and dismiss button.",
@@ -825,7 +1163,7 @@
      "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
      "required": true,
      "default": null,
-     "description": "The trigger element (must accept ref, onMouseEnter/Leave, onFocus/Blur)."
+     "description": "The trigger element (must accept onFocus/Blur)."
     },
     {
      "name": "placement",
@@ -836,7 +1174,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tooltip\n\nShort hover/focus hint attached to a single trigger element.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `content` | `ReactNode` | — | yes | Tooltip content. |\n| `children` | `ReactElement<Record<string, unknown>, string \\| JSXElementConstructor<any>>` | — | yes | The trigger element (must accept ref, onMouseEnter/Leave, onFocus/Blur). |\n| `placement` | `\"top\" \\| \"bottom\" \\| \"left\" \\| \"right\"` | top | no | Preferred placement. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab (focus trigger) | Shows immediately on focus (no delay). |\n| Escape | Dismisses while visible (WCAG 1.4.13). |\n\nHover opens after a short delay; content is linked via aria-describedby while visible. Trigger must accept onMouseEnter/Leave and onFocus/Blur props (cloned in automatically) — no ref forwarding required.\n\n## Theming\n\nOverride `--psi-tooltip-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tooltip\n\nShort hover/focus hint attached to a single trigger element.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `content` | `ReactNode` | — | yes | Tooltip content. |\n| `children` | `ReactElement<Record<string, unknown>, string \\| JSXElementConstructor<any>>` | — | yes | The trigger element (must accept onFocus/Blur). |\n| `placement` | `\"top\" \\| \"bottom\" \\| \"left\" \\| \"right\"` | top | no | Preferred placement. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab (focus trigger) | Shows immediately on focus (no delay). |\n| Escape | Dismisses while visible (WCAG 1.4.13). |\n\nHover opens after a short delay; content is linked via aria-describedby while visible. Trigger must accept onMouseEnter/Leave and onFocus/Blur props (cloned in automatically) — no ref forwarding required.\n\n## Theming\n\nOverride `--psi-tooltip-*` custom properties at any scope.\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "NavBar",
@@ -1248,10 +1586,10 @@
     },
     {
      "name": "onClose",
-     "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => void",
+     "type": "(reason: MenuCloseReason) => void",
      "required": true,
      "default": null,
-     "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step.\n\nInvariant (D58): a dismissal is only ever reported for a menu that is\ncurrently open according to its own `open` prop. The platform can close\nan auto popover before the consumer's state catches up — clicking another\nmenu's trigger light-dismisses this one before the consumer's click\nhandler runs — and a report for an already-closed menu would clear a\nselection that has since moved on."
+     "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step.\n\nInvariant (D58): a dismissal is only ever reported for a menu that is\ncurrently open according to its own `open` prop. The platform can close\nan auto popover before the consumer's state catches up — clicking another\nmenu's trigger light-dismisses this one before the consumer's click\nhandler runs — and a report for an already-closed menu would clear a\nselection that has since moved on.\n\n`\"tab\"` (D102): Tab or Shift Tab inside the open menu. Focus moves on to\nthe next control as the browser moves it; the consumer flips `open`."
     },
     {
      "name": "trigger",
@@ -1267,6 +1605,13 @@
      "default": "bottom-start",
      "description": "Placement relative to the trigger."
     },
+    {
+     "name": "id",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "The menu element's id, which the trigger's `aria-controls` names (D102).\nGenerated when absent."
+    },
     {
      "name": "aria-label",
      "type": "string",
@@ -1327,7 +1672,7 @@
      "order": 2
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Menu\n\nAction menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showPopover()/hidePopover(). |\n| `onClose` | `(reason: \"item-select\" \\| \"esc\" \\| \"outside\") => void` | — | yes | Called when a dismissal is *requested*; the consumer flips `open`. Menu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays open until `open` becomes false (D50). `\"outside\"` is the one exception: light dismiss is performed by the browser before it tells us, so by the time that reason is reported the popover is already closed. Flipping `open` to false is still required, to keep React's state in step. Invariant (D58): a dismissal is only ever reported for a menu that is currently open according to its own `open` prop. The platform can close an auto popover before the consumer's state catches up — clicking another menu's trigger light-dismisses this one before the consumer's click handler runs — and a report for an already-closed menu would clear a selection that has since moved on. |\n| `trigger` | `ReactElement<Record<string, unknown>, string \\| JSXElementConstructor<any>>` | — | yes | The trigger element. Must be a single React element that spreads unknown props onto a focusable node (a Psi `Button`, say): Menu clones it to add `aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates the menu with the control users actually focus. |\n| `placement` | `\"bottom-start\" \\| \"bottom-end\" \\| \"top-start\" \\| \"top-end\"` | bottom-start | no | Placement relative to the trigger. |\n| `aria-label` | `string` | — | no | Accessible name for the menu when there is no visible label. |\n| `aria-describedby` | `string` | — | no | The id of a `MenuText` (or any element) that describes the menu (D99). Unset by default: a description may be spoken every time the menu opens. |\n| `children` | `ReactNode` | — | yes | MenuItem, MenuSeparator and MenuText children. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the popover element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Arrow Down / Arrow Up | Moves between enabled items, wrapping at both ends. Disabled items are skipped. |\n| Home / End | Jumps to the first or last enabled item. |\n| Any single printable key | Typeahead — focuses the first enabled item whose label starts with the typed prefix; the prefix resets after 500ms. Keystrokes with Meta/Ctrl/Alt held are ignored. |\n| Esc | Suppresses the platform's own dismissal and reports onClose(\"esc\"); the menu stays open until the consumer flips `open` (D50). |\n| Enter / Space | Activates the focused item (native button behavior). |\n\nOpens on the native top layer via popover=\"auto\", which supplies light dismiss. Controlled-only: every dismissal path (esc, item-select, outside) only reports onClose(reason) — the consumer must flip `open` to actually close it; outside is the one path the platform has already acted on by the time it is reported. Opening moves focus to the first enabled item — Menu takes focus off the trigger as soon as `open` becomes true. Focus returns to the trigger when the menu actually closes, and only if focus is still inside the menu, so a light dismiss onto another control does not steal focus back. Requires an accessible name — pass aria-label. Placement uses CSS anchor positioning where supported and a JS fallback below that floor; below it there is no collision flip.\n\n## Theming\n\nOverride `--psi-menu-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Menu\n\nAction menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showPopover()/hidePopover(). |\n| `onClose` | `(reason: MenuCloseReason) => void` | — | yes | Called when a dismissal is *requested*; the consumer flips `open`. Menu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays open until `open` becomes false (D50). `\"outside\"` is the one exception: light dismiss is performed by the browser before it tells us, so by the time that reason is reported the popover is already closed. Flipping `open` to false is still required, to keep React's state in step. Invariant (D58): a dismissal is only ever reported for a menu that is currently open according to its own `open` prop. The platform can close an auto popover before the consumer's state catches up — clicking another menu's trigger light-dismisses this one before the consumer's click handler runs — and a report for an already-closed menu would clear a selection that has since moved on. `\"tab\"` (D102): Tab or Shift Tab inside the open menu. Focus moves on to the next control as the browser moves it; the consumer flips `open`. |\n| `trigger` | `ReactElement<Record<string, unknown>, string \\| JSXElementConstructor<any>>` | — | yes | The trigger element. Must be a single React element that spreads unknown props onto a focusable node (a Psi `Button`, say): Menu clones it to add `aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates the menu with the control users actually focus. |\n| `placement` | `\"bottom-start\" \\| \"bottom-end\" \\| \"top-start\" \\| \"top-end\"` | bottom-start | no | Placement relative to the trigger. |\n| `id` | `string` | — | no | The menu element's id, which the trigger's `aria-controls` names (D102). Generated when absent. |\n| `aria-label` | `string` | — | no | Accessible name for the menu when there is no visible label. |\n| `aria-describedby` | `string` | — | no | The id of a `MenuText` (or any element) that describes the menu (D99). Unset by default: a description may be spoken every time the menu opens. |\n| `children` | `ReactNode` | — | yes | MenuItem, MenuSeparator and MenuText children. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the popover element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Arrow Down / Arrow Up | Moves between enabled items, wrapping at both ends. Disabled items are skipped. |\n| Home / End | Jumps to the first or last enabled item. |\n| Any single printable key | Typeahead — focuses the first enabled item whose label starts with the typed prefix; the prefix resets after 500ms. Keystrokes with Meta/Ctrl/Alt held are ignored. |\n| Esc | Suppresses the platform's own dismissal and reports onClose(\"esc\"); the menu stays open until the consumer flips `open` (D50). |\n| Enter / Space | Activates the focused item (native button behavior). |\n| Arrow Down / Arrow Up on the closed trigger | Opens the menu on its first / last enabled item by clicking the trigger, since Menu cannot open itself; the consumer's onClick flips `open` (D102). |\n| Tab / Shift Tab | Reports onClose(\"tab\") and lets focus move on to the next control; the consumer flips `open`, and focus is not pulled back to the trigger (D102). |\n\nOpens on the native top layer via popover=\"auto\", which supplies light dismiss. Controlled-only: every dismissal path (esc, item-select, outside) only reports onClose(reason) — the consumer must flip `open` to actually close it; outside is the one path the platform has already acted on by the time it is reported. Opening moves focus to the first enabled item — Menu takes focus off the trigger as soon as `open` becomes true. Focus returns to the trigger when the menu actually closes, and only if focus is still inside the menu, so a light dismiss onto another control does not steal focus back. Requires an accessible name — pass aria-label. Placement uses CSS anchor positioning where supported and a JS fallback below that floor; below it there is no collision flip.\n\n## Theming\n\nOverride `--psi-menu-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "MenuItem",
@@ -3757,6 +4102,48 @@
     }
    }
   },
+  {
+   "name": "borderControl",
+   "formula": "ref(fgPrimary) → alpha(0.55)",
+   "values": {
+    "light": {
+     "oklch": {
+      "l": 0.3,
+      "c": 0.03,
+      "h": 250,
+      "alpha": 0.55
+     },
+     "hex": "#222f3c"
+    },
+    "dark": {
+     "oklch": {
+      "l": 0.93,
+      "c": 0.01,
+      "h": 250,
+      "alpha": 0.4
+     },
+     "hex": "#e3e8ee"
+    },
+    "acme": {
+     "oklch": {
+      "l": 0.3,
+      "c": 0.03,
+      "h": 30,
+      "alpha": 0.55
+     },
+     "hex": "#3c2825"
+    },
+    "ember": {
+     "oklch": {
+      "l": 0.949,
+      "c": 0.011,
+      "h": 72,
+      "alpha": 0.4
+     },
+     "hex": "#f3ede6"
+    }
+   }
+  },
   {
    "name": "borderFocus",
    "formula": "ref(fgAccent)",
@@ -4845,14 +5232,39 @@
     },
     "slots": {
      "body": [
-      "{content:headline}",
-      "{content:explanation}",
       {
-       "component": "Button",
+       "component": "Stack",
        "props": {
-        "variant": "neutral"
+        "gap": 8,
+        "align": "start"
        },
-       "content": "reset-label"
+       "slots": {
+        "body": [
+         {
+          "component": "Text",
+          "props": {
+           "as": "h3",
+           "size": 16,
+           "weight": "medium"
+          },
+          "content": "headline"
+         },
+         {
+          "component": "Text",
+          "props": {
+           "tone": "secondary"
+          },
+          "content": "explanation"
+         },
+         {
+          "component": "Button",
+          "props": {
+           "variant": "neutral"
+          },
+          "content": "reset-label"
+         }
+        ]
+       }
       }
      ]
     }
@@ -4865,7 +5277,129 @@
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Panel\n  padding={24}\n>\n  [nothing matches these filters]\n  [say whether the dataset is empty or the filters are too narrow]\n  <Button variant=\"neutral\">Clear filters</Button>\n</Panel>\n"
+   "preset": "<Panel\n  padding={24}\n>\n  <Stack\n    align=\"start\"\n    gap={8}\n  >\n    <Text as=\"h3\" size={16} weight=\"medium\">[nothing matches these filters]</Text>\n    <Text tone=\"secondary\">[say whether the dataset is empty or the filters are too narrow]</Text>\n    <Button variant=\"neutral\">Clear filters</Button>\n  </Stack>\n</Panel>\n"
+  },
+  {
+   "id": "feedback-form",
+   "intent": "A short report form: a required choice of category as radios, a bounded description with a length counter, and a submit button",
+   "match": [
+    "feedback form",
+    "report a problem",
+    "radio buttons",
+    "text area",
+    "character counter"
+   ],
+   "compose": {
+    "component": "Panel",
+    "props": {
+     "padding": 24
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Stack",
+       "props": {
+        "gap": 24
+       },
+       "slots": {
+        "body": [
+         {
+          "component": "Field",
+          "props": {
+           "group": true,
+           "required": true,
+           "requiredText": "(Required)"
+          },
+          "slots": {
+           "label": [
+            "{content:category-label}"
+           ],
+           "body": [
+            {
+             "component": "RadioGroup",
+             "slots": {
+              "body": [
+               {
+                "component": "Radio",
+                "props": {
+                 "value": "problem"
+                },
+                "content": "first-option"
+               },
+               {
+                "component": "Radio",
+                "props": {
+                 "value": "idea"
+                },
+                "content": "second-option"
+               },
+               {
+                "component": "Radio",
+                "props": {
+                 "value": "other"
+                },
+                "content": "third-option"
+               }
+              ]
+             }
+            }
+           ]
+          }
+         },
+         {
+          "component": "Field",
+          "slots": {
+           "label": [
+            "{content:description-label}"
+           ],
+           "body": [
+            {
+             "component": "Textarea",
+             "props": {
+              "maxLength": 500,
+              "rows": 4
+             }
+            }
+           ],
+           "description": [
+            "{content:description-help}"
+           ]
+          }
+         },
+         {
+          "component": "Toolbar",
+          "slots": {
+           "body": [
+            {
+             "component": "Button",
+             "props": {
+              "type": "submit",
+              "variant": "accent"
+             },
+             "content": "submit-label"
+            }
+           ]
+          }
+         }
+        ]
+       }
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "category-label": "Category",
+    "first-option": "Something is broken",
+    "second-option": "An idea",
+    "third-option": "Something else",
+    "description-label": "Description",
+    "description-help": "[what happened, and what you expected]",
+    "submit-label": "Send"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Panel\n  padding={24}\n>\n  <Stack\n    gap={24}\n  >\n    <Field\n      group={true}\n      label=\"Category\"\n      required={true}\n      requiredText=\"(Required)\"\n    >\n      <RadioGroup>\n        <Radio value=\"problem\">Something is broken</Radio>\n        <Radio value=\"idea\">An idea</Radio>\n        <Radio value=\"other\">Something else</Radio>\n      </RadioGroup>\n    </Field>\n    <Field\n      description=\"[what happened, and what you expected]\"\n      label=\"Description\"\n    >\n      <Textarea maxLength={500} rows={4} />\n    </Field>\n    <Toolbar>\n      <Button type=\"submit\" variant=\"accent\">Send</Button>\n    </Toolbar>\n  </Stack>\n</Panel>\n"
   },
   {
    "id": "filter-form",

package/llms.txt

@@ -7,4 +7,4 @@ Ids: component:<Name>, token:<name>, topic:<key>, pattern:<id>; bare names resol
 
 Connect: https://psi.kurkin.de/mcp (Streamable HTTP) or `npx @handamade/psi-mcp` (stdio).
 Agent context: `npx @handamade/psi-mcp init [--claude]` writes a marker-delimited block into AGENTS.md/CLAUDE.md (D44).
-The index bakes packages/react/dist/{manifest.json,patterns.json} (patterns.json: 23 composition patterns with clarifying parameters, blocked/gaps flags, preset JSX) + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).
+The index bakes packages/react/dist/{manifest.json,patterns.json} (patterns.json: 24 composition patterns with clarifying parameters, blocked/gaps flags, preset JSX) + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-mcp",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "license": "MIT",
   "description": "MCP server and agent-context generator for the Psi (Ψ) design system",
   "type": "module",
@@ -33,8 +33,8 @@
     "tsx": "^4.22.4",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6",
-    "@handamade/psi-tokens": "0.25.0",
-    "@handamade/psi-react": "0.25.0"
+    "@handamade/psi-react": "0.27.0",
+    "@handamade/psi-tokens": "0.27.0"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"