@handamade/psi-mcp 0.20.0 → 0.22.0

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.20.0",
+ "version": "0.22.0",
  "themes": [
   "light",
   "dark",
@@ -32,6 +32,13 @@
      "default": 32,
      "description": "Height in px (24 | 32 | 40 | 48)."
     },
+    {
+     "name": "type",
+     "type": "\"button\" | \"submit\" | \"reset\"",
+     "required": false,
+     "default": null,
+     "description": "Button type. Declared so the manifest lists it and a pattern can say\n`submit` (D87). No default is set: the platform's applies — `submit`\ninside a form, a plain button elsewhere."
+    },
     {
      "name": "href",
      "type": "string",
@@ -69,7 +76,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Button\n\nAction trigger. With `href` renders an anchor with identical styling (D33); `disabled` then maps to `aria-disabled`.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label content. |\n| `variant` | `\"accent\" \\| \"accent-subtle\" \\| \"neutral\" \\| \"neutral-subtle\" \\| \"ghost\" \\| \"danger\" \\| \"danger-subtle\" \\| \"outline\"` | neutral | no | Visual variant. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). |\n| `href` | `string` | — | no | Render as an anchor with this href (D33). disabled → aria-disabled, no href attribute, pointer-events: none. |\n| `target` | `string` | — | no | Anchor target; only used with href. |\n| `rel` | `string` | — | no | Anchor rel; only used with href. |\n| `ref` | `Ref<HTMLButtonElement \\| HTMLAnchorElement>` | — | no | Forwarded ref to the underlying 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| Enter / Space | Activates the button. |\n| Tab | Focusable; visible focus ring via :focus-visible. |\n\nWith href it renders an <a>; disabled anchors get aria-disabled, lose the href attribute, and suppress activation (D33).\n\n## Theming\n\nOverride `--psi-button-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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).\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# Button\n\nAction trigger. With `href` renders an anchor with identical styling (D33); `disabled` then maps to `aria-disabled`.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label content. |\n| `variant` | `\"accent\" \\| \"accent-subtle\" \\| \"neutral\" \\| \"neutral-subtle\" \\| \"ghost\" \\| \"danger\" \\| \"danger-subtle\" \\| \"outline\"` | neutral | no | Visual variant. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). |\n| `type` | `\"button\" \\| \"submit\" \\| \"reset\"` | — | no | Button type. Declared so the manifest lists it and a pattern can say `submit` (D87). No default is set: the platform's applies — `submit` inside a form, a plain button elsewhere. |\n| `href` | `string` | — | no | Render as an anchor with this href (D33). disabled → aria-disabled, no href attribute, pointer-events: none. |\n| `target` | `string` | — | no | Anchor target; only used with href. |\n| `rel` | `string` | — | no | Anchor rel; only used with href. |\n| `ref` | `Ref<HTMLButtonElement \\| HTMLAnchorElement>` | — | no | Forwarded ref to the underlying 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| Enter / Space | Activates the button. |\n| Tab | Focusable; visible focus ring via :focus-visible. |\n\nWith href it renders an <a>; disabled anchors get aria-disabled, lose the href attribute, and suppress activation (D33).\n\n## Theming\n\nOverride `--psi-button-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "IconButton",
@@ -140,7 +147,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# IconButton\n\nSquare icon-only button; same variant/size/href contract as Button. Give it an accessible name (`aria-label`).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The icon element — an Icon* component. |\n| `aria-label` | `string` | — | yes | Accessible name for the icon-only control. Required: an IconButton has no text to name it, so omitting this ships an unnameable button (D60). If you also pass `aria-labelledby`, that wins per the accname algorithm. |\n| `variant` | `\"accent\" \\| \"neutral\" \\| \"ghost\" \\| \"danger\"` | neutral | no | Visual variant. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Square size in px (24 \\| 32 \\| 40 \\| 48). |\n| `href` | `string` | — | no | Render as an anchor with this href (D33). disabled → aria-disabled, no href attribute, pointer-events: none. |\n| `target` | `string` | — | no | Anchor target; only used with href. |\n| `rel` | `string` | — | no | Anchor rel; only used with href. |\n| `ref` | `Ref<HTMLButtonElement \\| HTMLAnchorElement>` | — | no | Forwarded ref to the underlying 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| Enter / Space | Activates. |\n\nRequires an accessible name — pass aria-label. IconButton does not hide its icon for you; mark the icon aria-hidden yourself.\n\n## Theming\n\nOverride `--psi-button-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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).\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# IconButton\n\nSquare icon-only button; same variant/size/href contract as Button. Give it an accessible name (`aria-label`).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The icon element — an Icon* component. |\n| `aria-label` | `string` | — | yes | Accessible name for the icon-only control. Required: an IconButton has no text to name it, so omitting this ships an unnameable button (D60). If you also pass `aria-labelledby`, that wins per the accname algorithm. |\n| `variant` | `\"accent\" \\| \"neutral\" \\| \"ghost\" \\| \"danger\"` | neutral | no | Visual variant. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Square size in px (24 \\| 32 \\| 40 \\| 48). |\n| `href` | `string` | — | no | Render as an anchor with this href (D33). disabled → aria-disabled, no href attribute, pointer-events: none. |\n| `target` | `string` | — | no | Anchor target; only used with href. |\n| `rel` | `string` | — | no | Anchor rel; only used with href. |\n| `ref` | `Ref<HTMLButtonElement \\| HTMLAnchorElement>` | — | no | Forwarded ref to the underlying 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| Enter / Space | Activates. |\n\nRequires an accessible name — pass aria-label. IconButton does not hide its icon for you; mark the icon aria-hidden yourself.\n\n## Theming\n\nOverride `--psi-button-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "Card",
@@ -190,7 +197,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Card\n\nContent container with an optional edge-to-edge media slot; `stacked` (media above body) or `featured` (media beside body) layout.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Body content, beside or below the media slot. |\n| `variant` | `\"stacked\" \\| \"featured\"` | stacked | no | stacked = media above body; featured = media beside body (~1.6fr/1fr), stacks under md. |\n| `media` | `ReactNode` | — | no | Media slot rendered edge-to-edge (img, AspectRatio, …). |\n| `hoverLift` | `boolean` | false | no | Lift on hover: translateY(-6px) over --psi-duration-350. |\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## Theming\n\nOverride `--psi-card-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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).\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# Card\n\nContent container with an optional edge-to-edge media slot; `stacked` (media above body) or `featured` (media beside body) layout.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Body content, beside or below the media slot. |\n| `variant` | `\"stacked\" \\| \"featured\"` | stacked | no | stacked = media above body; featured = media beside body (~1.6fr/1fr), stacks under md. |\n| `media` | `ReactNode` | — | no | Media slot rendered edge-to-edge (img, AspectRatio, …). |\n| `hoverLift` | `boolean` | false | no | Lift on hover: translateY(-6px) over --psi-duration-350. |\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## Theming\n\nOverride `--psi-card-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "Panel",
@@ -233,7 +240,7 @@
      "order": 1
     }
    ],
-   "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).\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# 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": "DescriptionList",
@@ -287,7 +294,7 @@
      "order": 1
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# DescriptionList\n\nKey/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.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | One DescriptionItem per field. |\n| `layout` | `\"stacked\" \\| \"inline\"` | stacked | no | `stacked` puts the term above its value; `inline` puts them in a two-column grid, which is what a detail drawer wants. |\n| `gap` | `8 \\| 12 \\| 16` | 12 | no | Gap between pairs, in px. |\n| `ref` | `Ref<HTMLDListElement>` | — | 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## Theming\n\nOverride `--psi-description-list-*` 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).\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# DescriptionList\n\nKey/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.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | One DescriptionItem per field. |\n| `layout` | `\"stacked\" \\| \"inline\"` | stacked | no | `stacked` puts the term above its value; `inline` puts them in a two-column grid, which is what a detail drawer wants. |\n| `gap` | `8 \\| 12 \\| 16` | 12 | no | Gap between pairs, in px. |\n| `ref` | `Ref<HTMLDListElement>` | — | 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## Theming\n\nOverride `--psi-description-list-*` 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": "DescriptionItem",
@@ -323,7 +330,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# DescriptionItem\n\nOne term/value pair. The term is a prop and the value is children, matching Field's `label` idiom rather than inventing a two-slot shape. Renders `<div><dt/><dd/></div>`. The wrapper is the HTML5-sanctioned grouping element for a `<dl>`, so the `<dt>`/`<dd>` association assistive tech relies on is intact — and it keeps both layouts to one CSS rule each instead of fighting a single grid to space pairs differently from the term/value inside a pair.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The value — renders the <dd>. |\n| `term` | `ReactNode` | — | yes | The term — renders the `<dt>`. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the group wrapper. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-description-item-*` 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).\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# DescriptionItem\n\nOne term/value pair. The term is a prop and the value is children, matching Field's `label` idiom rather than inventing a two-slot shape. Renders `<div><dt/><dd/></div>`. The wrapper is the HTML5-sanctioned grouping element for a `<dl>`, so the `<dt>`/`<dd>` association assistive tech relies on is intact — and it keeps both layouts to one CSS rule each instead of fighting a single grid to space pairs differently from the term/value inside a pair.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The value — renders the <dd>. |\n| `term` | `ReactNode` | — | yes | The term — renders the `<dt>`. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the group wrapper. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-description-item-*` 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": "Input",
@@ -373,7 +380,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Input\n\nSingle-line text input with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `type` | `\"number\" \\| \"text\" \\| \"search\" \\| \"email\" \\| \"tel\" \\| \"url\" \\| \"password\" \\| \"date\"` | text | no | Input type. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input>` 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 | Focuses the native <input>; focus ring on the field. |\n\nerror sets a red border only. Inside a Field, aria-invalid and aria-describedby are wired automatically (D49); standalone, pair them yourself.\n\n## Theming\n\nOverride `--psi-input-*` 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).\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# Input\n\nSingle-line text input with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `type` | `\"number\" \\| \"text\" \\| \"search\" \\| \"email\" \\| \"tel\" \\| \"url\" \\| \"password\" \\| \"date\"` | text | no | Input type. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input>` 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 | Focuses the native <input>; focus ring on the field. |\n\nerror sets a red border only. Inside a Field, aria-invalid and aria-describedby are wired automatically (D49); standalone, pair them yourself.\n\n## Theming\n\nOverride `--psi-input-*` 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": "Select",
@@ -416,11 +423,11 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Select\n\nStyled native `<select>` with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The <option> elements. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). Replaces the native `size` attribute (which sets the visible option-row count on a listbox-style `<select>`) with the design system's control height in pixels. |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `ref` | `Ref<HTMLSelectElement>` | — | no | Forwarded ref to the underlying `<select>` 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 | Focuses the native <select>. |\n| Arrow keys / typeahead | Native option navigation. |\n\nerror: same contract as Input — sets a red border only. Inside a Field, aria-invalid and aria-describedby are wired automatically (D49); standalone, pair them yourself.\n\n## Theming\n\nOverride `--psi-select-*` 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).\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# Select\n\nStyled native `<select>` with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The <option> elements. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). Replaces the native `size` attribute (which sets the visible option-row count on a listbox-style `<select>`) with the design system's control height in pixels. |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `ref` | `Ref<HTMLSelectElement>` | — | no | Forwarded ref to the underlying `<select>` 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 | Focuses the native <select>. |\n| Arrow keys / typeahead | Native option navigation. |\n\nerror: same contract as Input — sets a red border only. Inside a Field, aria-invalid and aria-describedby are wired automatically (D49); standalone, pair them yourself.\n\n## Theming\n\nOverride `--psi-select-*` 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": "Field",
-   "description": "Labeled form-row wrapper: label above, control, one message line below — description normally, error when set (aria-live unless `announce={false}`). Auto-wires id/aria-describedby/aria-invalid into Input and Select (D49).",
+   "description": "Labeled form-row wrapper: label above, control, one message line below — description normally, error when set (aria-live unless `announce={false}`). Auto-wires id/aria-describedby/aria-invalid into Input and Select (D49). Overriding `--psi-field-gap` or `--psi-field-label-height` on a narrower scope than the theme root, inside a `Toolbar align=\"start\"` row, also needs `--psi-toolbar-action-offset` set on that same scope, or the row's button keeps the theme-root offset (D92).",
    "props": [
     {
      "name": "children",
@@ -457,6 +464,13 @@
      "default": false,
      "description": "Renders the required marker and flows `required` to the control."
     },
+    {
+     "name": "requiredText",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "With `required`, the label shows this text — \"(Required)\", say — instead\nof the asterisk, so the requirement is stated in words and not by a glyph\nalone (D84). Visible and aria-hidden: the control carries the programmatic\nsignal (`required` / `aria-required`), and a screen reader that heard both\nwould say it twice. Without `required` it renders nothing."
+    },
     {
      "name": "group",
      "type": "boolean",
@@ -513,7 +527,7 @@
      "order": 3
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Field\n\nLabeled form-row wrapper: label above, control, one message line below — description normally, error when set (aria-live unless `announce={false}`). Auto-wires id/aria-describedby/aria-invalid into Input and Select (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The control this field labels. |\n| `label` | `ReactNode` | — | no | Label content; renders a <label> (or <legend> in group mode). |\n| `description` | `ReactNode` | — | no | Helper line under the control; replaced by error when error is set. |\n| `error` | `ReactNode` | — | no | Error content; when truthy it replaces the description and switches the field (and a wrapped Input/Select) into error state. |\n| `required` | `boolean` | false | no | Renders the required marker and flows `required` to the control. |\n| `group` | `boolean` | false | no | Group mode: fieldset/legend wrapping several self-labeled controls (Checkbox/Switch); the message describes the whole group. |\n| `htmlFor` | `string` | — | no | Override the generated control id (pair it with the same id on the control). |\n| `announce` | `boolean` | true | no | When false, the message line is not a live region: an application that routes every announcement through one announcer of its own sets this and announces field errors itself. The message still describes the control (aria-describedby). |\n| `ref` | `Ref<HTMLDivElement \\| HTMLFieldSetElement>` | — | 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 | Focus moves to the wrapped control; the label is announced with it. |\n\nWires label association, aria-describedby and aria-invalid into a wrapped Input/Select automatically; the message line is aria-live=polite. Group mode renders fieldset/legend.\n\n## Theming\n\nOverride `--psi-field-*` 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).\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# Field\n\nLabeled form-row wrapper: label above, control, one message line below — description normally, error when set (aria-live unless `announce={false}`). Auto-wires id/aria-describedby/aria-invalid into Input and Select (D49). Overriding `--psi-field-gap` or `--psi-field-label-height` on a narrower scope than the theme root, inside a `Toolbar align=\"start\"` row, also needs `--psi-toolbar-action-offset` set on that same scope, or the row's button keeps the theme-root offset (D92).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The control this field labels. |\n| `label` | `ReactNode` | — | no | Label content; renders a <label> (or <legend> in group mode). |\n| `description` | `ReactNode` | — | no | Helper line under the control; replaced by error when error is set. |\n| `error` | `ReactNode` | — | no | Error content; when truthy it replaces the description and switches the field (and a wrapped Input/Select) into error state. |\n| `required` | `boolean` | false | no | Renders the required marker and flows `required` to the control. |\n| `requiredText` | `string` | — | no | With `required`, the label shows this text — \"(Required)\", say — instead of the asterisk, so the requirement is stated in words and not by a glyph alone (D84). Visible and aria-hidden: the control carries the programmatic signal (`required` / `aria-required`), and a screen reader that heard both would say it twice. Without `required` it renders nothing. |\n| `group` | `boolean` | false | no | Group mode: fieldset/legend wrapping several self-labeled controls (Checkbox/Switch); the message describes the whole group. |\n| `htmlFor` | `string` | — | no | Override the generated control id (pair it with the same id on the control). |\n| `announce` | `boolean` | true | no | When false, the message line is not a live region: an application that routes every announcement through one announcer of its own sets this and announces field errors itself. The message still describes the control (aria-describedby). |\n| `ref` | `Ref<HTMLDivElement \\| HTMLFieldSetElement>` | — | 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 | Focus moves to the wrapped control; the label is announced with it. |\n\nWires label association, aria-describedby and aria-invalid into a wrapped Input/Select automatically; the message line is aria-live=polite. Group mode renders fieldset/legend. required marks the label with an aria-hidden asterisk and flows required to the control; requiredText replaces the asterisk with a visible word such as \"(Required)\", also aria-hidden, because the control's required/aria-required is what assistive tech reads (D84). A control Psi did not write joins the same wiring through useFieldControl(): spread its result — id, aria-labelledby (a label-for names only a labelable element, and a custom control is usually not one), aria-describedby, aria-invalid, aria-required, required, each present only when the Field sets it — onto the element that takes focus (D84).\n\n## Theming\n\nOverride `--psi-field-*` 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": "Dialog",
@@ -621,7 +635,7 @@
      "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).\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. |\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"
   },
   {
    "name": "Checkbox",
@@ -657,7 +671,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).\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.\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"
   },
   {
    "name": "Switch",
@@ -686,7 +700,7 @@
     }
    ],
    "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).\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# 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": "Tag",
@@ -736,11 +750,11 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tag\n\nCompact label for status or category; semantic variants, optional subtle tint and dismiss button.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label content. |\n| `variant` | `\"neutral\" \\| \"accent\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Semantic color variant. |\n| `subtle` | `boolean` | false | no | Use tinted background with semantic foreground. |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders a dismiss button that calls this handler. |\n| `ref` | `Ref<HTMLSpanElement>` | — | no | Forwarded ref to the underlying `<span>` 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| Enter / Space (dismiss button) | onDismiss renders a real <button>; keyboard-dismissible. |\n\nPassive label otherwise; not in the tab order without onDismiss.\n\n## Theming\n\nOverride `--psi-tag-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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).\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# Tag\n\nCompact label for status or category; semantic variants, optional subtle tint and dismiss button.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Label content. |\n| `variant` | `\"neutral\" \\| \"accent\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Semantic color variant. |\n| `subtle` | `boolean` | false | no | Use tinted background with semantic foreground. |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders a dismiss button that calls this handler. |\n| `ref` | `Ref<HTMLSpanElement>` | — | no | Forwarded ref to the underlying `<span>` 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| Enter / Space (dismiss button) | onDismiss renders a real <button>; keyboard-dismissible. |\n\nPassive label otherwise; not in the tab order without onDismiss.\n\n## Theming\n\nOverride `--psi-tag-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "Toolbar",
-   "description": "Horizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\".",
+   "description": "Horizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\"; as a form, as a named form landmark instead (D87).",
    "props": [
     {
      "name": "children",
@@ -756,9 +770,23 @@
      "default": 8,
      "description": "Gap between controls in px."
     },
+    {
+     "name": "align",
+     "type": "\"center\" | \"end\" | \"start\"",
+     "required": false,
+     "default": "center",
+     "description": "Cross-axis alignment of the row's items. `center` (the default) centres\nthem, for a row of controls without visible labels such as\nfilter-toolbar. `end` and `start` are for a row of Fields with visible\nlabels beside an unlabelled button.\n`end` (D87) lines items up on their bottom edge. It lines up each item's\n*last* line, so a Field in an end-aligned row must end on its control —\nno description or error line under it; use `start` for one.\n`start` (D92) lines up the controls: items share their top edge, and a\n*direct* `button` or `a` child drops by `--psi-toolbar-action-offset`\n(one Field label line plus the Field gap) onto the control line. Only a\ndirect child is offset: a wrapped trigger (a Tooltip-wrapped button, a\nMenu trigger) is not. A Field's description or error line hangs below\nits control and moves nothing else. Every label in the row must fit on\none line; a label that wraps pushes its control below the others."
+    },
+    {
+     "name": "as",
+     "type": "\"div\" | \"form\"",
+     "required": false,
+     "default": "div",
+     "description": "Root element. `form` renders a real `<form>`, so a submit Button\nsubmits it and Enter in a field does too; with `aria-label` it is a\nnamed form landmark, so it takes no `role=\"group\"` (D87). Wire\n`onSubmit`."
+    },
     {
      "name": "ref",
-     "type": "Ref<HTMLDivElement>",
+     "type": "Ref<HTMLDivElement | HTMLFormElement>",
      "required": false,
      "default": null,
      "description": "Forwarded ref to the root element."
@@ -779,7 +807,7 @@
      "order": 1
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Toolbar\n\nHorizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\".\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The controls. |\n| `gap` | `8 \\| 12 \\| 16` | 8 | no | Gap between controls 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 | Moves through the controls in DOM order — no roving tabindex (deliberately not role=toolbar, D52). |\n\nWith aria-label it renders role=group so the control cluster announces with a name; unlabeled it is a plain layout div.\n\n## Theming\n\nOverride `--psi-toolbar-*` 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).\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# Toolbar\n\nHorizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\"; as a form, as a named form landmark instead (D87).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | The controls. |\n| `gap` | `8 \\| 12 \\| 16` | 8 | no | Gap between controls in px. |\n| `align` | `\"center\" \\| \"end\" \\| \"start\"` | center | no | Cross-axis alignment of the row's items. `center` (the default) centres them, for a row of controls without visible labels such as filter-toolbar. `end` and `start` are for a row of Fields with visible labels beside an unlabelled button. `end` (D87) lines items up on their bottom edge. It lines up each item's *last* line, so a Field in an end-aligned row must end on its control — no description or error line under it; use `start` for one. `start` (D92) lines up the controls: items share their top edge, and a *direct* `button` or `a` child drops by `--psi-toolbar-action-offset` (one Field label line plus the Field gap) onto the control line. Only a direct child is offset: a wrapped trigger (a Tooltip-wrapped button, a Menu trigger) is not. A Field's description or error line hangs below its control and moves nothing else. Every label in the row must fit on one line; a label that wraps pushes its control below the others. |\n| `as` | `\"div\" \\| \"form\"` | div | no | Root element. `form` renders a real `<form>`, so a submit Button submits it and Enter in a field does too; with `aria-label` it is a named form landmark, so it takes no `role=\"group\"` (D87). Wire `onSubmit`. |\n| `ref` | `Ref<HTMLDivElement \\| HTMLFormElement>` | — | 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 | Moves through the controls in DOM order — no roving tabindex (deliberately not role=toolbar, D52). |\n\nWith aria-label it renders role=group so the control cluster announces with a name; unlabeled it is a plain layout div.\n\n## Theming\n\nOverride `--psi-toolbar-*` 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": "Tooltip",
@@ -808,7 +836,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).\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 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"
   },
   {
    "name": "NavBar",
@@ -833,7 +861,21 @@
      "type": "ReactNode",
      "required": false,
      "default": null,
-     "description": "Nav links."
+     "description": "Nav links. The `<nav>` renders only when there are children, so a bar with\na brand and actions and no links has no empty landmark (D88)."
+    },
+    {
+     "name": "navLabel",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name of the links' `<nav>` (its `aria-label`). Rest props land\non the `<header>`, so this is the only way to label the `<nav>` (D88)."
+    },
+    {
+     "name": "fluid",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": "Lay the row out at full width: it drops `psi-container` (the centred\nmax-width column) and keeps the `--psi-gutter` side padding. For an\napplication header over a full-width frame (D88)."
     },
     {
      "name": "ref",
@@ -850,33 +892,52 @@
      "description": "Additional CSS class name(s) merged onto the component's root element."
     }
    ],
-   "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# NavBar\n\nTop navigation bar with brand, nav-link, and trailing-action slots.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `brand` | `ReactNode` | — | no | Brand slot (wordmark / logo link), leading edge. |\n| `actions` | `ReactNode` | — | no | Trailing actions slot (theme switch, CTA). |\n| `children` | `ReactNode` | — | no | Nav links. |\n| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the header element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nOverride `--psi-navbar-*` 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).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "slots": [
+    {
+     "name": "brand",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 1
+    },
+    {
+     "name": "actions",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 2
+    },
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 3
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# NavBar\n\nTop navigation bar with brand, nav-link, and trailing-action slots.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `brand` | `ReactNode` | — | no | Brand slot (wordmark / logo link), leading edge. |\n| `actions` | `ReactNode` | — | no | Trailing actions slot (theme switch, CTA). |\n| `children` | `ReactNode` | — | no | Nav links. The `<nav>` renders only when there are children, so a bar with a brand and actions and no links has no empty landmark (D88). |\n| `navLabel` | `string` | — | no | Accessible name of the links' `<nav>` (its `aria-label`). Rest props land on the `<header>`, so this is the only way to label the `<nav>` (D88). |\n| `fluid` | `boolean` | false | no | Lay the row out at full width: it drops `psi-container` (the centred max-width column) and keeps the `--psi-gutter` side padding. For an application header over a full-width frame (D88). |\n| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the header element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nOverride `--psi-navbar-*` 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": "AspectRatio",
-   "description": "Fixed-aspect-ratio box that sizes its child media.",
+   "name": "SkipLink",
+   "description": "A link to the page's main content, invisible until it takes keyboard focus and then fixed at the inline-start top corner on a surface, drawing the shared focus ring (D88). Render it first in the document. No script: native fragment navigation moves focus to a target that is focusable, so the next *Tab* continues from inside it. `AppShell`'s `main` is one (`tabIndex={-1}`); a bare `<main>` is not, so give it one. A modal `Dialog` makes the rest of the document inert, so the link never needs to beat one. A `ToastRegion` is on the native top layer, which paints above everything whatever its `z-index`: do not place one at `top-start` (its default is `bottom-end`) in an app with a skip link, or it covers the focused link.",
    "props": [
     {
-     "name": "children",
-     "type": "ReactNode",
-     "required": false,
+     "name": "href",
+     "type": "string",
+     "required": true,
      "default": null,
-     "description": "Content constrained to the ratio."
+     "description": "Fragment of the element to skip to, such as `\"#main\"`. The target must be\nfocusable (`tabIndex={-1}` is enough), or focus does not move."
     },
     {
-     "name": "ratio",
-     "type": "number",
+     "name": "children",
+     "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "Width/height ratio, e.g. 16/10 or 4/5."
+     "description": "Visible text, such as \"Skip to content\"."
     },
     {
      "name": "ref",
-     "type": "Ref<HTMLDivElement>",
+     "type": "Ref<HTMLAnchorElement>",
      "required": false,
      "default": null,
-     "description": "Forwarded ref to the frame element."
+     "description": "Forwarded ref to the anchor."
     },
     {
      "name": "className",
@@ -887,53 +948,25 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# AspectRatio\n\nFixed-aspect-ratio box that sizes its child media.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Content constrained to the ratio. |\n| `ratio` | `number` | — | yes | Width/height ratio, e.g. 16/10 or 4/5. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the frame element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-aspect-ratio-*` 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).\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# SkipLink\n\nA link to the page's main content, invisible until it takes keyboard focus and then fixed at the inline-start top corner on a surface, drawing the shared focus ring (D88). Render it first in the document. No script: native fragment navigation moves focus to a target that is focusable, so the next *Tab* continues from inside it. `AppShell`'s `main` is one (`tabIndex={-1}`); a bare `<main>` is not, so give it one. A modal `Dialog` makes the rest of the document inert, so the link never needs to beat one. A `ToastRegion` is on the native top layer, which paints above everything whatever its `z-index`: do not place one at `top-start` (its default is `bottom-end`) in an app with a skip link, or it covers the focused link.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `href` | `string` | — | yes | Fragment of the element to skip to, such as `\"#main\"`. The target must be focusable (`tabIndex={-1}` is enough), or focus does not move. |\n| `children` | `ReactNode` | — | yes | Visible text, such as \"Skip to content\". |\n| `ref` | `Ref<HTMLAnchorElement>` | — | no | Forwarded ref to the anchor. |\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 | Takes focus and becomes visible at the inline-start top corner, drawing the shared focus ring. Put it first in the document so it is the first tab stop. |\n| Enter | Follows the fragment href: focus moves to the target, and the next Tab continues from inside it. |\n\nA native anchor, visually hidden until it is focused (:focus-visible) and with no script (D88). Fragment navigation moves focus only to a focusable target, so the element named by href must be focusable: tabIndex={-1} is enough, and AppShell's main has it. A modal Dialog makes the link inert, so it never needs to beat one. A ToastRegion is on the native top layer and paints over the focused link whatever its z-index: do not place one at top-start in an app with a skip link.\n\n## Theming\n\nOverride `--psi-skip-link-*` 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": "Menu",
-   "description": "Action 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.",
+   "name": "NavTree",
+   "description": "A navigation tree (D88): a `<nav aria-label>` around a `<ul>` of `NavItem`s and `NavGroup`s. Native elements only — *Tab* moves through the group buttons and the links of open groups; there is no roving focus and no `role=\"menu\"` or `role=\"tree\"`, because site navigation is a list of links, not a widget. Router-agnostic: pass your router's link inside each `NavItem`, with `aria-current=\"page\"` on the current one.",
    "props": [
-    {
-     "name": "open",
-     "type": "boolean",
-     "required": true,
-     "default": null,
-     "description": "Controlled open state; syncs to showPopover()/hidePopover()."
-    },
-    {
-     "name": "onClose",
-     "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => 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."
-    },
-    {
-     "name": "trigger",
-     "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
-     "required": true,
-     "default": null,
-     "description": "The trigger element. Must be a single React element that spreads unknown\nprops onto a focusable node (a Psi `Button`, say): Menu clones it to add\n`aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates\nthe menu with the control users actually focus."
-    },
-    {
-     "name": "placement",
-     "type": "\"bottom-start\" | \"bottom-end\" | \"top-start\" | \"top-end\"",
-     "required": false,
-     "default": "bottom-start",
-     "description": "Placement relative to the trigger."
-    },
     {
      "name": "aria-label",
      "type": "string",
-     "required": false,
+     "required": true,
      "default": null,
-     "description": "Accessible name for the menu when there is no visible label."
+     "description": "Accessible name of the navigation landmark, such as \"Main\". Required: an\napp has more than one `<nav>` (a header's, a sidebar's), and an unnamed\none is indistinguishable from the rest. Declared here rather than\ninherited so docgen keeps it in the manifest (D60)."
     },
     {
      "name": "children",
      "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "MenuItem and MenuSeparator children."
+     "description": "`NavItem`s and `NavGroup`s — each renders an `<li>`."
     },
     {
      "name": "className",
@@ -944,146 +977,172 @@
     },
     {
      "name": "ref",
-     "type": "Ref<HTMLDivElement>",
+     "type": "Ref<HTMLElement>",
      "required": false,
      "default": null,
-     "description": "Forwarded ref to the popover element."
+     "description": "Forwarded ref to the `<nav>`."
     }
    ],
    "slots": [
-    {
-     "name": "trigger",
-     "accepts": {
-      "contracts": [
-       "interactive"
-      ]
-     },
-     "cardinality": "1..1",
-     "order": 1
-    },
     {
      "name": "body",
      "accepts": {
       "components": [
-       "MenuItem",
-       "MenuSeparator"
+       "NavGroup",
+       "NavItem"
       ]
      },
      "cardinality": "1..*",
-     "order": 2
+     "order": 1
     }
    ],
-   "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| `children` | `ReactNode` | — | yes | MenuItem and MenuSeparator 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).\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# NavTree\n\nA navigation tree (D88): a `<nav aria-label>` around a `<ul>` of `NavItem`s and `NavGroup`s. Native elements only — *Tab* moves through the group buttons and the links of open groups; there is no roving focus and no `role=\"menu\"` or `role=\"tree\"`, because site navigation is a list of links, not a widget. Router-agnostic: pass your router's link inside each `NavItem`, with `aria-current=\"page\"` on the current one.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `aria-label` | `string` | — | yes | Accessible name of the navigation landmark, such as \"Main\". Required: an app has more than one `<nav>` (a header's, a sidebar's), and an unnamed one is indistinguishable from the rest. Declared here rather than inherited so docgen keeps it in the manifest (D60). |\n| `children` | `ReactNode` | — | yes | `NavItem`s and `NavGroup`s — each renders an `<li>`. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the `<nav>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab / Shift+Tab | Moves through the group buttons and the links of open groups in document order. There is no roving focus and no arrow-key model: it is a list of links, not a menu or a tree widget. |\n\nA native <nav> around a <ul>, named by the required aria-label (an app has more than one navigation landmark). No role=\"menu\" or role=\"tree\" is used (D88). Router-agnostic: the consumer passes its router's link inside each NavItem.\n\n## Theming\n\nOverride `--psi-nav-tree-*` 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",
-   "description": "One action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).",
+   "name": "NavGroup",
+   "description": "A collapsible group of `NavItem`s in a `NavTree` (D88). Controlled-only, like `Tabs` (D67): `open` and `onOpenChange` are required and nothing is remembered. Renders a native `<button aria-expanded aria-controls>` over a `<ul>` that is `hidden` when closed, so the items leave the layout and the accessibility tree while `aria-controls` keeps naming an element. The chevron turns with the state and is `aria-hidden`: the label and `aria-expanded` carry the meaning.",
    "props": [
     {
-     "name": "children",
+     "name": "label",
      "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "Item label."
+     "description": "The group's visible label, such as \"Reports\"."
     },
     {
-     "name": "onSelect",
-     "type": "() => void",
+     "name": "open",
+     "type": "boolean",
      "required": true,
      "default": null,
-     "description": "Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50)."
+     "description": "Whether the group's items are shown. Controlled."
     },
     {
-     "name": "variant",
-     "type": "\"neutral\" | \"danger\"",
-     "required": false,
-     "default": "neutral",
-     "description": "danger is for destructive actions only (house rule)."
+     "name": "onOpenChange",
+     "type": "(open: boolean) => void",
+     "required": true,
+     "default": null,
+     "description": "Called with the next state when the button is pressed. The group never\nchanges `open` itself."
     },
     {
-     "name": "disabled",
-     "type": "boolean",
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "`NavItem`s of the group."
+    },
+    {
+     "name": "className",
+     "type": "string",
      "required": false,
-     "default": false,
-     "description": ""
+     "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# MenuItem\n\nOne action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | Item label. |\n| `onSelect` | `() => void` | — | yes | Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50). |\n| `variant` | `\"neutral\" \\| \"danger\"` | neutral | no | danger is for destructive actions only (house rule). |\n| `disabled` | `boolean` | false | no |  |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter / Space | Activates; Menu reports onClose(\"item-select\") but does not close itself. |\n\nRenders a real <button>. disabled sets aria-disabled (not the disabled attribute) so the item stays discoverable to assistive tech while being skipped by roving navigation. variant=\"danger\" is for destructive actions only.\n\n## Theming\n\nThis component has no `--psi-menu-item-*` 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## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
-  },
-  {
-   "name": "MenuSeparator",
-   "description": "Hairline rule between Menu item groups. No props by design (D53).",
-   "props": [],
-   "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# MenuSeparator\n\nHairline rule between Menu item groups. No props by design (D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n\n\nNon-interactive rule with role=\"separator\" — exposed to assistive tech as a separator, never focusable, and skipped by roving navigation.\n\n## Theming\n\nThis component has no `--psi-menu-separator-*` 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).\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# NavGroup\n\nA collapsible group of `NavItem`s in a `NavTree` (D88). Controlled-only, like `Tabs` (D67): `open` and `onOpenChange` are required and nothing is remembered. Renders a native `<button aria-expanded aria-controls>` over a `<ul>` that is `hidden` when closed, so the items leave the layout and the accessibility tree while `aria-controls` keeps naming an element. The chevron turns with the state and is `aria-hidden`: the label and `aria-expanded` carry the meaning.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `label` | `ReactNode` | — | yes | The group's visible label, such as \"Reports\". |\n| `open` | `boolean` | — | yes | Whether the group's items are shown. Controlled. |\n| `onOpenChange` | `(open: boolean) => void` | — | yes | Called with the next state when the button is pressed. The group never changes `open` itself. |\n| `children` | `ReactNode` | — | yes | `NavItem`s of the group. |\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| Enter / Space | Activates the group's native button, which asks the parent to open or close the group through onOpenChange. |\n\nControlled-only: open and onOpenChange are required and the group never changes its own state. Renders a <button type=\"button\"> with aria-expanded and aria-controls naming its <ul>, which carries `hidden` when closed, so the links leave the layout and the accessibility tree while aria-controls still resolves. The chevron is aria-hidden and turns on a duration token; the label and aria-expanded carry the meaning.\n\n## Theming\n\nOverride `--psi-nav-tree-*` 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": "Table",
-   "description": "Data table on native table semantics. Holds no state: sorting, selection and pagination are the consumer's (D62, extending D50/D53).",
+   "name": "NavItem",
+   "description": "One entry of a `NavTree` (D88): an `<li>` that styles the single anchor inside it. Router apps pass their own link as the child, so it keeps its `href` and handlers; with `current`, `NavItem` clones it to add `aria-current=\"page\"` (D93), as `Menu` clones its trigger. `href` is for plain links and for presets, where the compose tree can hold only manifest components and a raw `<a>` is not one. The current page is never marked by colour alone: medium weight, a raised surface and a bar at the inline start.",
    "props": [
     {
-     "name": "size",
-     "type": "32 | 40 | 48",
-     "required": false,
-     "default": 40,
-     "description": "Row height in px."
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "Without `href`: one anchor, your router's link. With `href`: the link's\ntext."
     },
     {
-     "name": "stickyHeader",
-     "type": "boolean",
+     "name": "href",
+     "type": "string",
      "required": false,
      "default": null,
-     "description": "Pins the header while the body scrolls."
+     "description": "Render the anchor yourself (D88), for a plain link or a preset: the\n`<li>` holds `<a href>` with `children` as its text. Router apps leave it\nout and pass their own link as the child, so the link keeps its own\nhandlers."
     },
     {
-     "name": "sortable",
+     "name": "current",
      "type": "boolean",
      "required": false,
-     "default": false,
-     "description": "Enables the sort affordance on header cells that declare a `sortKey`."
+     "default": null,
+     "description": "Mark the link as the current page (`aria-current=\"page\"`): on the\nanchor `href` renders, or on the single element you pass as a child (D93).\nWithout `current`, a child's own `aria-current` is left alone, so a router\nthat marks its active link keeps working."
     },
     {
-     "name": "sort",
-     "type": "TableSortState | null",
+     "name": "className",
+     "type": "string",
      "required": false,
      "default": null,
-     "description": "Controlled sort state; `null` when nothing is sorted."
+     "description": "Additional CSS class name(s) merged onto the component's root element."
     },
     {
-     "name": "onSortChange",
-     "type": "((sort: TableSortState) => void)",
+     "name": "ref",
+     "type": "Ref<HTMLLIElement>",
      "required": false,
      "default": null,
-     "description": "Called with the **next** sort state, already toggled — store it as given\nand do not toggle again. A fresh column arrives `\"asc\"`; an active `\"asc\"`\ncolumn emits `\"desc\"`; an active `\"desc\"` column emits `\"asc\"`.\n\nOptional in the type because `sortable` may be false; a discriminated union\nexpressing the real contract does not survive docgen's flat prop\nextraction, which would strip these props from the manifest entirely (D62)."
-    },
+     "description": "Forwarded ref to the `<li>`."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# NavItem\n\nOne entry of a `NavTree` (D88): an `<li>` that styles the single anchor inside it. Router apps pass their own link as the child, so it keeps its `href` and handlers; with `current`, `NavItem` clones it to add `aria-current=\"page\"` (D93), as `Menu` clones its trigger. `href` is for plain links and for presets, where the compose tree can hold only manifest components and a raw `<a>` is not one. The current page is never marked by colour alone: medium weight, a raised surface and a bar at the inline start.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | Without `href`: one anchor, your router's link. With `href`: the link's text. |\n| `href` | `string` | — | no | Render the anchor yourself (D88), for a plain link or a preset: the `<li>` holds `<a href>` with `children` as its text. Router apps leave it out and pass their own link as the child, so the link keeps its own handlers. |\n| `current` | `boolean` | — | no | Mark the link as the current page (`aria-current=\"page\"`): on the anchor `href` renders, or on the single element you pass as a child (D93). Without `current`, a child's own `aria-current` is left alone, so a router that marks its active link keeps working. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLLIElement>` | — | no | Forwarded ref to the `<li>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter | Follows the link inside it (native anchor behavior); the link is the consumer's router link. |\n\nAn <li> that styles the one anchor inside it. Router apps pass their own link as the child; current clones it with aria-current=\"page\" (D93), and without current the child keeps its own aria-current; with href the NavItem renders the anchor itself (for plain links and presets) and current sets aria-current=\"page\" on it. The current page is marked by weight, a raised surface and an inline-start bar, never by colour alone, and the focus ring is drawn inset on the anchor.\n\n## Theming\n\nOverride `--psi-nav-tree-*` 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": "AppShell",
+   "description": "The frame of an application (D88): a header row over a sidebar and a `<main>` that each scroll on their own, filling the viewport (`100dvh`). Because the header has a row of its own and `main` is its own scroller, nothing scrolls under the header, so a focused element is never obscured by it (WCAG 2.2 *Focus Not Obscured*) without `scroll-padding`. `main` carries `id={mainId}` and `tabIndex={-1}`: the target of a `SkipLink`, not a tab stop; focused by the skip link it draws the shared focus ring inside its box. A closed sidebar is `hidden`, not narrowed to icons; there is no responsive drawer and no stored open state, so this is a desktop frame. A page whose document must scroll as a whole does not use `AppShell`. Mount it at the root of the page with no margin or padding around it: it is `100dvh` tall, so anything around it makes the document scroll and slides the frame. Do not place a `ToastRegion` at `top-start` in an app with a skip link: the native top layer paints over the focused link.",
+   "props": [
     {
-     "name": "selectable",
-     "type": "boolean",
+     "name": "skipLink",
+     "type": "ReactNode",
      "required": false,
-     "default": false,
-     "description": "Renders the row-selection checkbox column."
+     "default": null,
+     "description": "A `SkipLink` (D88), rendered first so it is the first tab stop. Point its\n`href` at `#` plus `mainId`."
     },
     {
-     "name": "selected",
-     "type": "ReadonlySet<string>",
+     "name": "header",
+     "type": "ReactNode",
      "required": false,
-     "default": "new Set<string>()",
-     "description": "Controlled selection, keyed by each `TableRow`'s `rowId`."
+     "default": null,
+     "description": "The header row, usually a `NavBar` (D88). It sits in a row of its own\nabove the sidebar and `main`, so nothing scrolls under it."
     },
     {
-     "name": "onSelectionChange",
-     "type": "((selected: ReadonlySet<string>) => void)",
+     "name": "sidebar",
+     "type": "ReactNode",
      "required": false,
      "default": null,
-     "description": "Called with the next selection. See `onSortChange` on why it is optional."
+     "description": "The sidebar's content, usually a `NavTree` (D88). The shell wraps it in a\n`<div>`, not an `<aside>`: a `NavTree` is already the landmark."
     },
     {
      "name": "children",
      "type": "ReactNode",
-     "required": true,
+     "required": false,
      "default": null,
-     "description": "TableHead and TableBody."
+     "description": "The page, rendered inside `<main>` (D88)."
+    },
+    {
+     "name": "sidebarOpen",
+     "type": "boolean",
+     "required": false,
+     "default": true,
+     "description": "Whether the sidebar is shown. Controlled: wire your Menu toggle's\n`aria-expanded` and this to one piece of state. Closed, the sidebar is\n`hidden`, so it leaves the layout and the accessibility tree, and stays in\nthe DOM so the toggle's `aria-controls` keeps naming an element (D88)."
+    },
+    {
+     "name": "sidebarTheme",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "A theme name for the sidebar alone, such as `\"dark\"`: sets\n`data-psi-theme` on the sidebar element, so every token inside re-resolves\nunder that theme while the rest of the page keeps its own (D88). The\nsidebar paints `--psi-bg-primary` itself; a theme paints no background."
+    },
+    {
+     "name": "sidebarId",
+     "type": "string",
+     "required": false,
+     "default": "sidebar",
+     "description": "`id` of the sidebar element, which a toggle names with `aria-controls`\n(D88)."
+    },
+    {
+     "name": "mainId",
+     "type": "string",
+     "required": false,
+     "default": "main",
+     "description": "`id` of `<main>`, which a `SkipLink`'s `href` names (D88)."
     },
     {
      "name": "className",
@@ -1094,26 +1153,314 @@
     },
     {
      "name": "ref",
-     "type": "Ref<HTMLTableElement>",
+     "type": "Ref<HTMLDivElement>",
      "required": false,
      "default": null,
-     "description": "Forwarded ref to the underlying `<table>` element."
+     "description": "Forwarded ref to the root `<div>`."
     }
    ],
    "slots": [
     {
-     "name": "body",
+     "name": "skipLink",
      "accepts": {
       "components": [
-       "TableHead",
-       "TableBody"
+       "SkipLink"
       ]
      },
-     "cardinality": "1..*",
+     "cardinality": "0..1",
      "order": 1
+    },
+    {
+     "name": "header",
+     "accepts": {
+      "components": [
+       "NavBar"
+      ]
+     },
+     "cardinality": "0..1",
+     "order": 2
+    },
+    {
+     "name": "sidebar",
+     "accepts": {
+      "components": [
+       "NavTree"
+      ]
+     },
+     "cardinality": "0..1",
+     "order": 3
+    },
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 4
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Table\n\nData table on native table semantics. Holds no state: sorting, selection and pagination are the consumer's (D62, extending D50/D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `size` | `32 \\| 40 \\| 48` | 40 | no | Row height in px. |\n| `stickyHeader` | `boolean` | — | no | Pins the header while the body scrolls. |\n| `sortable` | `boolean` | false | no | Enables the sort affordance on header cells that declare a `sortKey`. |\n| `sort` | `TableSortState \\| null` | — | no | Controlled sort state; `null` when nothing is sorted. |\n| `onSortChange` | `((sort: TableSortState) => void)` | — | no | Called with the **next** sort state, already toggled — store it as given and do not toggle again. A fresh column arrives `\"asc\"`; an active `\"asc\"` column emits `\"desc\"`; an active `\"desc\"` column emits `\"asc\"`. Optional in the type because `sortable` may be false; a discriminated union expressing the real contract does not survive docgen's flat prop extraction, which would strip these props from the manifest entirely (D62). |\n| `selectable` | `boolean` | false | no | Renders the row-selection checkbox column. |\n| `selected` | `ReadonlySet<string>` | new Set<string>() | no | Controlled selection, keyed by each `TableRow`'s `rowId`. |\n| `onSelectionChange` | `((selected: ReadonlySet<string>) => void)` | — | no | Called with the next selection. See `onSortChange` on why it is optional. |\n| `children` | `ReactNode` | — | yes | TableHead and TableBody. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableElement>` | — | no | Forwarded ref to the underlying `<table>` element. |\n\n## Theming\n\nOverride `--psi-table-*` 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).\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# AppShell\n\nThe frame of an application (D88): a header row over a sidebar and a `<main>` that each scroll on their own, filling the viewport (`100dvh`). Because the header has a row of its own and `main` is its own scroller, nothing scrolls under the header, so a focused element is never obscured by it (WCAG 2.2 *Focus Not Obscured*) without `scroll-padding`. `main` carries `id={mainId}` and `tabIndex={-1}`: the target of a `SkipLink`, not a tab stop; focused by the skip link it draws the shared focus ring inside its box. A closed sidebar is `hidden`, not narrowed to icons; there is no responsive drawer and no stored open state, so this is a desktop frame. A page whose document must scroll as a whole does not use `AppShell`. Mount it at the root of the page with no margin or padding around it: it is `100dvh` tall, so anything around it makes the document scroll and slides the frame. Do not place a `ToastRegion` at `top-start` in an app with a skip link: the native top layer paints over the focused link.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `skipLink` | `ReactNode` | — | no | A `SkipLink` (D88), rendered first so it is the first tab stop. Point its `href` at `#` plus `mainId`. |\n| `header` | `ReactNode` | — | no | The header row, usually a `NavBar` (D88). It sits in a row of its own above the sidebar and `main`, so nothing scrolls under it. |\n| `sidebar` | `ReactNode` | — | no | The sidebar's content, usually a `NavTree` (D88). The shell wraps it in a `<div>`, not an `<aside>`: a `NavTree` is already the landmark. |\n| `children` | `ReactNode` | — | no | The page, rendered inside `<main>` (D88). |\n| `sidebarOpen` | `boolean` | true | no | Whether the sidebar is shown. Controlled: wire your Menu toggle's `aria-expanded` and this to one piece of state. Closed, the sidebar is `hidden`, so it leaves the layout and the accessibility tree, and stays in the DOM so the toggle's `aria-controls` keeps naming an element (D88). |\n| `sidebarTheme` | `string` | — | no | A theme name for the sidebar alone, such as `\"dark\"`: sets `data-psi-theme` on the sidebar element, so every token inside re-resolves under that theme while the rest of the page keeps its own (D88). The sidebar paints `--psi-bg-primary` itself; a theme paints no background. |\n| `sidebarId` | `string` | sidebar | no | `id` of the sidebar element, which a toggle names with `aria-controls` (D88). |\n| `mainId` | `string` | main | no | `id` of `<main>`, which a `SkipLink`'s `href` names (D88). |\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 root `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | The first stop is the skip link (when given), then the header, the sidebar's links and buttons, and the links of main, in document order. The shell adds no stop of its own: main has tabIndex={-1}. |\n| Enter (on the skip link) | Follows the fragment href: focus moves to main, drawing the shared focus ring inside its box, and the next Tab continues from main's first link. |\n\nA grid filling the viewport: the header sits in a row of its own and main is its own scroller, so nothing scrolls under the header and a focused element is never obscured by it (WCAG 2.2 Focus Not Obscured) without scroll-padding, which does nothing on a main that is not the document's scroller (D88). main carries id={mainId} and tabIndex={-1}, the skip link's target. A closed sidebar is `hidden`, so it leaves the layout and the accessibility tree while its id stays in the DOM for a toggle's aria-controls; the toggle's aria-expanded and sidebarOpen are wired by the consumer, since the shell is controlled and stores nothing. The sidebar is a div, not an aside: the NavTree inside is already the navigation landmark. sidebarTheme sets data-psi-theme on the sidebar alone, so its tokens re-resolve under that theme in a page that keeps its own; the sidebar paints --psi-bg-primary itself. Desktop frame only: no responsive drawer. Do not place a ToastRegion at top-start in an app with a skip link.\n\n## Theming\n\nOverride `--psi-app-shell-*` 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": "AspectRatio",
+   "description": "Fixed-aspect-ratio box that sizes its child media.",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Content constrained to the ratio."
+    },
+    {
+     "name": "ratio",
+     "type": "number",
+     "required": true,
+     "default": null,
+     "description": "Width/height ratio, e.g. 16/10 or 4/5."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the frame element."
+    },
+    {
+     "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# AspectRatio\n\nFixed-aspect-ratio box that sizes its child media.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | no | Content constrained to the ratio. |\n| `ratio` | `number` | — | yes | Width/height ratio, e.g. 16/10 or 4/5. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the frame element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-aspect-ratio-*` 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": "Menu",
+   "description": "Action 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.",
+   "props": [
+    {
+     "name": "open",
+     "type": "boolean",
+     "required": true,
+     "default": null,
+     "description": "Controlled open state; syncs to showPopover()/hidePopover()."
+    },
+    {
+     "name": "onClose",
+     "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => 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."
+    },
+    {
+     "name": "trigger",
+     "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
+     "required": true,
+     "default": null,
+     "description": "The trigger element. Must be a single React element that spreads unknown\nprops onto a focusable node (a Psi `Button`, say): Menu clones it to add\n`aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates\nthe menu with the control users actually focus."
+    },
+    {
+     "name": "placement",
+     "type": "\"bottom-start\" | \"bottom-end\" | \"top-start\" | \"top-end\"",
+     "required": false,
+     "default": "bottom-start",
+     "description": "Placement relative to the trigger."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name for the menu when there is no visible label."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "MenuItem and MenuSeparator children."
+    },
+    {
+     "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<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the popover element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "trigger",
+     "accepts": {
+      "contracts": [
+       "interactive"
+      ]
+     },
+     "cardinality": "1..1",
+     "order": 1
+    },
+    {
+     "name": "body",
+     "accepts": {
+      "components": [
+       "MenuItem",
+       "MenuSeparator"
+      ]
+     },
+     "cardinality": "1..*",
+     "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| `children` | `ReactNode` | — | yes | MenuItem and MenuSeparator 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"
+  },
+  {
+   "name": "MenuItem",
+   "description": "One action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "Item label."
+    },
+    {
+     "name": "onSelect",
+     "type": "() => void",
+     "required": true,
+     "default": null,
+     "description": "Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50)."
+    },
+    {
+     "name": "variant",
+     "type": "\"neutral\" | \"danger\"",
+     "required": false,
+     "default": "neutral",
+     "description": "danger is for destructive actions only (house rule)."
+    },
+    {
+     "name": "disabled",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": ""
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# MenuItem\n\nOne action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | Item label. |\n| `onSelect` | `() => void` | — | yes | Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50). |\n| `variant` | `\"neutral\" \\| \"danger\"` | neutral | no | danger is for destructive actions only (house rule). |\n| `disabled` | `boolean` | false | no |  |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter / Space | Activates; Menu reports onClose(\"item-select\") but does not close itself. |\n\nRenders a real <button>. disabled sets aria-disabled (not the disabled attribute) so the item stays discoverable to assistive tech while being skipped by roving navigation. variant=\"danger\" is for destructive actions only.\n\n## Theming\n\nThis component has no `--psi-menu-item-*` 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## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "MenuSeparator",
+   "description": "Hairline rule between Menu item groups. No props by design (D53).",
+   "props": [],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# MenuSeparator\n\nHairline rule between Menu item groups. No props by design (D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n\n\nNon-interactive rule with role=\"separator\" — exposed to assistive tech as a separator, never focusable, and skipped by roving navigation.\n\n## Theming\n\nThis component has no `--psi-menu-separator-*` 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": "Table",
+   "description": "Data table on native table semantics. Holds no state: sorting, selection and pagination are the consumer's (D62, extending D50/D53).",
+   "props": [
+    {
+     "name": "size",
+     "type": "32 | 40 | 48",
+     "required": false,
+     "default": 40,
+     "description": "Row height in px."
+    },
+    {
+     "name": "stickyHeader",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "Pins the header while the body scrolls."
+    },
+    {
+     "name": "sortable",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": "Enables the sort affordance on header cells that declare a `sortKey`."
+    },
+    {
+     "name": "sort",
+     "type": "TableSortState | null",
+     "required": false,
+     "default": null,
+     "description": "Controlled sort state; `null` when nothing is sorted."
+    },
+    {
+     "name": "onSortChange",
+     "type": "((sort: TableSortState) => void)",
+     "required": false,
+     "default": null,
+     "description": "Called with the **next** sort state, already toggled — store it as given\nand do not toggle again. A fresh column arrives `\"asc\"`; an active `\"asc\"`\ncolumn emits `\"desc\"`; an active `\"desc\"` column emits `\"asc\"`.\n\nOptional in the type because `sortable` may be false; a discriminated union\nexpressing the real contract does not survive docgen's flat prop\nextraction, which would strip these props from the manifest entirely (D62)."
+    },
+    {
+     "name": "selectable",
+     "type": "boolean",
+     "required": false,
+     "default": false,
+     "description": "Renders the row-selection checkbox column."
+    },
+    {
+     "name": "selected",
+     "type": "ReadonlySet<string>",
+     "required": false,
+     "default": "new Set<string>()",
+     "description": "Controlled selection, keyed by each `TableRow`'s `rowId`."
+    },
+    {
+     "name": "onSelectionChange",
+     "type": "((selected: ReadonlySet<string>) => void)",
+     "required": false,
+     "default": null,
+     "description": "Called with the next selection. See `onSortChange` on why it is optional."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "TableHead and TableBody."
+    },
+    {
+     "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<HTMLTableElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<table>` element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {
+      "components": [
+       "TableCaption",
+       "TableHead",
+       "TableBody"
+      ]
+     },
+     "cardinality": "1..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Table\n\nData table on native table semantics. Holds no state: sorting, selection and pagination are the consumer's (D62, extending D50/D53).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `size` | `32 \\| 40 \\| 48` | 40 | no | Row height in px. |\n| `stickyHeader` | `boolean` | — | no | Pins the header while the body scrolls. |\n| `sortable` | `boolean` | false | no | Enables the sort affordance on header cells that declare a `sortKey`. |\n| `sort` | `TableSortState \\| null` | — | no | Controlled sort state; `null` when nothing is sorted. |\n| `onSortChange` | `((sort: TableSortState) => void)` | — | no | Called with the **next** sort state, already toggled — store it as given and do not toggle again. A fresh column arrives `\"asc\"`; an active `\"asc\"` column emits `\"desc\"`; an active `\"desc\"` column emits `\"asc\"`. Optional in the type because `sortable` may be false; a discriminated union expressing the real contract does not survive docgen's flat prop extraction, which would strip these props from the manifest entirely (D62). |\n| `selectable` | `boolean` | false | no | Renders the row-selection checkbox column. |\n| `selected` | `ReadonlySet<string>` | new Set<string>() | no | Controlled selection, keyed by each `TableRow`'s `rowId`. |\n| `onSelectionChange` | `((selected: ReadonlySet<string>) => void)` | — | no | Called with the next selection. See `onSortChange` on why it is optional. |\n| `children` | `ReactNode` | — | yes | TableHead and TableBody. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableElement>` | — | no | Forwarded ref to the underlying `<table>` element. |\n\n## Theming\n\nOverride `--psi-table-*` 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": "TableHead",
@@ -1124,7 +1471,336 @@
      "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "The header TableRow."
+     "description": "The header TableRow."
+    },
+    {
+     "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<HTMLTableSectionElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the `<thead>`."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableHead\n\n`<thead>`. When the table is selectable, prepends the select-all cell to the FIRST header row so the header's column count matches the body's — the checkbox column is Table's, not the consumer's schema. Clones the row rather than rebuilding it, so the consumer's own props on that `TableRow` survive.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | The header TableRow. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableSectionElement>` | — | no | Forwarded ref to the `<thead>`. |\n\n## Theming\n\nThis component has no `--psi-table-head-*` 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": "TableBody",
+   "description": "`<tbody>` wrapper. Remaining attributes land on it (D85) — `aria-busy` while a page of rows loads, say.",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The body TableRows."
+    },
+    {
+     "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<HTMLTableSectionElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the `<tbody>`."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableBody\n\n`<tbody>` wrapper. Remaining attributes land on it (D85) — `aria-busy` while a page of rows loads, say.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | The body TableRows. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableSectionElement>` | — | no | Forwarded ref to the `<tbody>`. |\n\n## Theming\n\nThis component has no `--psi-table-body-*` 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": "TableRow",
+   "description": "`<tr>`. `rowId` is the key the `selected` set holds.",
+   "props": [
+    {
+     "name": "rowId",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Stable identity for selection. Required for selectable tables (D62)."
+    },
+    {
+     "name": "selectLabel",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name for this row's selection checkbox."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The row's cells."
+    },
+    {
+     "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<HTMLTableRowElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the `<tr>`."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableRow\n\n`<tr>`. `rowId` is the key the `selected` set holds.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `rowId` | `string` | — | no | Stable identity for selection. Required for selectable tables (D62). |\n| `selectLabel` | `string` | — | no | Accessible name for this row's selection checkbox. |\n| `children` | `ReactNode` | — | yes | The row's cells. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableRowElement>` | — | no | Forwarded ref to the `<tr>`. |\n\n## Theming\n\nThis component has no `--psi-table-row-*` 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": "TableHeaderCell",
+   "description": "`<th scope=\"col\">`. `aria-sort` belongs on the th, never on the inner button — assistive tech reads the sort state from the column header.",
+   "props": [
+    {
+     "name": "sortKey",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Sort key this column emits. Enables the sort control when the table is `sortable`."
+    },
+    {
+     "name": "numeric",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "Right-aligns and renders tabular figures (D62)."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Header label."
+    },
+    {
+     "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<HTMLTableCellElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the `<th>`."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableHeaderCell\n\n`<th scope=\"col\">`. `aria-sort` belongs on the th, never on the inner button — assistive tech reads the sort state from the column header.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `sortKey` | `string` | — | no | Sort key this column emits. Enables the sort control when the table is `sortable`. |\n| `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |\n| `children` | `ReactNode` | — | no | Header label. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableCellElement>` | — | no | Forwarded ref to the `<th>`. |\n\n## Theming\n\nThis component has no `--psi-table-header-cell-*` 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": "TableCell",
+   "description": "`<td>`, or `<th scope=\"row\">` with `rowHeader`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose. Remaining attributes land on the cell (D85).",
+   "props": [
+    {
+     "name": "numeric",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "Right-aligns and renders tabular figures (D62)."
+    },
+    {
+     "name": "colSpan",
+     "type": "number",
+     "required": false,
+     "default": null,
+     "description": "Columns the cell spans — an empty-state row spanning the table (D85)."
+    },
+    {
+     "name": "rowHeader",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "Renders `<th scope=\"row\">` instead of `<td>`: the cell that names its\nrow, an identifier say, so a screen reader reads it with every cell in\nthe row (D85). Styled as a cell, at medium weight."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Cell content."
+    },
+    {
+     "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<HTMLTableCellElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the cell element."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableCell\n\n`<td>`, or `<th scope=\"row\">` with `rowHeader`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose. Remaining attributes land on the cell (D85).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |\n| `colSpan` | `number` | — | no | Columns the cell spans — an empty-state row spanning the table (D85). |\n| `rowHeader` | `boolean` | — | no | Renders `<th scope=\"row\">` instead of `<td>`: the cell that names its row, an identifier say, so a screen reader reads it with every cell in the row (D85). Styled as a cell, at medium weight. |\n| `children` | `ReactNode` | — | no | Cell content. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableCellElement>` | — | no | Forwarded ref to the cell element. |\n\n## Theming\n\nThis component has no `--psi-table-cell-*` 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": "TableCaption",
+   "description": "`<caption>` — the table's name, above it, and an optional detail line (D85). It names the table for assistive tech, which an `aria-label` on the `Table` would also do, but a caption is visible. A token-paged list has no page numbers to land on, so after a page change the consumer moves focus here: give it `tabIndex={-1}`, put the range in `detail`, and call `focus()` on the ref. The ring is the shared one (D82), drawn inside the caption's box. Remaining attributes land on the element.",
+   "props": [
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The name line — what the table lists. Also the table's accessible name."
+    },
+    {
+     "name": "detail",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "An optional second line: the range shown, say — \"Rows 51–100 of more\nthan 100,000\"."
+    },
+    {
+     "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<HTMLTableCaptionElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the `<caption>`, so focus can be moved to it."
+    }
+   ],
+   "slots": [],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableCaption\n\n`<caption>` — the table's name, above it, and an optional detail line (D85). It names the table for assistive tech, which an `aria-label` on the `Table` would also do, but a caption is visible. A token-paged list has no page numbers to land on, so after a page change the consumer moves focus here: give it `tabIndex={-1}`, put the range in `detail`, and call `focus()` on the ref. The ring is the shared one (D82), drawn inside the caption's box. Remaining attributes land on the element.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | The name line — what the table lists. Also the table's accessible name. |\n| `detail` | `ReactNode` | — | no | An optional second line: the range shown, say — \"Rows 51–100 of more than 100,000\". |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLTableCaptionElement>` | — | no | Forwarded ref to the `<caption>`, so focus can be moved to it. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Not a tab stop. With tabIndex={-1} the consumer moves focus to it after a page change, and the shared ring is drawn inside the caption. |\n\nRenders <caption>, which names the table for assistive tech and is visible, unlike an aria-label on Table. Put the range in `detail` (\"Rows 51–100 of more than 100,000\") so that moving focus to the caption after a token-paged page change reads the new range (D85). Remaining attributes land on the element.\n\n## Theming\n\nThis component has no `--psi-table-caption-*` 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": "Pagination",
+   "description": "Numbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.",
+   "props": [
+    {
+     "name": "page",
+     "type": "number",
+     "required": true,
+     "default": null,
+     "description": "Current page, 1-based. A value outside `[1, pageCount]` (including\nnon-finite values like `NaN`) is clamped for rendering and logs a\n`console.warn` in development. `pageCount < 1` renders no page buttons."
+    },
+    {
+     "name": "pageCount",
+     "type": "number",
+     "required": true,
+     "default": null,
+     "description": "Total number of pages."
+    },
+    {
+     "name": "onPageChange",
+     "type": "(page: number) => void",
+     "required": true,
+     "default": null,
+     "description": "Called with the requested page. Required — unlike Table's `onSortChange`/\n`onSelectionChange`, which are optional because `sortable`/`selectable`\ngate whether they're meaningful, `Pagination` has no such gating boolean:\nthe prop is unconditionally meaningful, so a `Pagination` without it is a\ndead control (final review finding, D62)."
+    },
+    {
+     "name": "siblingCount",
+     "type": "number",
+     "required": false,
+     "default": 1,
+     "description": "Pages shown either side of the current one before truncating."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": "Pagination",
+     "description": "Accessible name for the nav landmark."
+    },
+    {
+     "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# Pagination\n\nNumbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `page` | `number` | — | yes | Current page, 1-based. A value outside `[1, pageCount]` (including non-finite values like `NaN`) is clamped for rendering and logs a `console.warn` in development. `pageCount < 1` renders no page buttons. |\n| `pageCount` | `number` | — | yes | Total number of pages. |\n| `onPageChange` | `(page: number) => void` | — | yes | Called with the requested page. Required — unlike Table's `onSortChange`/ `onSelectionChange`, which are optional because `sortable`/`selectable` gate whether they're meaningful, `Pagination` has no such gating boolean: the prop is unconditionally meaningful, so a `Pagination` without it is a dead control (final review finding, D62). |\n| `siblingCount` | `number` | 1 | no | Pages shown either side of the current one before truncating. |\n| `aria-label` | `string` | Pagination | no | Accessible name for the nav landmark. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-pagination-*` 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": "CursorPagination",
+   "description": "A pager for a list that pages by cursor (D85): a backend that returns a `nextPageToken` and no page count. Two `ghost` Buttons with visible words in a `<nav>`; the chevrons only reinforce them. A direction that is not available is disabled. It holds no state and knows nothing about pages — the consumer holds the tokens and answers `hasPrevious` / `hasNext`. A sibling of `Pagination`, not a mode of it: `Pagination`'s contract is a page count and numbers, and this one has neither.",
+   "props": [
+    {
+     "name": "hasPrevious",
+     "type": "boolean",
+     "required": true,
+     "default": null,
+     "description": "Whether a previous page exists — the consumer knows, from its tokens."
+    },
+    {
+     "name": "hasNext",
+     "type": "boolean",
+     "required": true,
+     "default": null,
+     "description": "Whether a next page exists."
+    },
+    {
+     "name": "onPrevious",
+     "type": "() => void",
+     "required": true,
+     "default": null,
+     "description": "Called when the user asks for the previous page."
+    },
+    {
+     "name": "onNext",
+     "type": "() => void",
+     "required": true,
+     "default": null,
+     "description": "Called when the user asks for the next page."
+    },
+    {
+     "name": "previousLabel",
+     "type": "string",
+     "required": false,
+     "default": "Previous",
+     "description": "Visible text of the previous button."
+    },
+    {
+     "name": "nextLabel",
+     "type": "string",
+     "required": false,
+     "default": "Next",
+     "description": "Visible text of the next button."
+    },
+    {
+     "name": "size",
+     "type": "32 | 40",
+     "required": false,
+     "default": 32,
+     "description": "Button height in px."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": "Pagination",
+     "description": "Accessible name for the nav landmark."
     },
     {
      "name": "className",
@@ -1135,18 +1811,53 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableHead\n\n`<thead>`. When the table is selectable, prepends the select-all cell to the FIRST header row so the header's column count matches the body's — the checkbox column is Table's, not the consumer's schema. Clones the row rather than rebuilding it, so the consumer's own props on that `TableRow` survive.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | The header TableRow. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-table-head-*` 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).\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# CursorPagination\n\nA pager for a list that pages by cursor (D85): a backend that returns a `nextPageToken` and no page count. Two `ghost` Buttons with visible words in a `<nav>`; the chevrons only reinforce them. A direction that is not available is disabled. It holds no state and knows nothing about pages — the consumer holds the tokens and answers `hasPrevious` / `hasNext`. A sibling of `Pagination`, not a mode of it: `Pagination`'s contract is a page count and numbers, and this one has neither.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `hasPrevious` | `boolean` | — | yes | Whether a previous page exists — the consumer knows, from its tokens. |\n| `hasNext` | `boolean` | — | yes | Whether a next page exists. |\n| `onPrevious` | `() => void` | — | yes | Called when the user asks for the previous page. |\n| `onNext` | `() => void` | — | yes | Called when the user asks for the next page. |\n| `previousLabel` | `string` | Previous | no | Visible text of the previous button. |\n| `nextLabel` | `string` | Next | no | Visible text of the next button. |\n| `size` | `32 \\| 40` | 32 | no | Button height in px. |\n| `aria-label` | `string` | Pagination | no | Accessible name for the nav landmark. |\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 | Reaches the Previous and Next buttons in order; a disabled direction is skipped. |\n| Enter / Space | Activates the focused button (native button behavior). |\n\nA <nav> named \"Pagination\" (override with aria-label) holding two ghost Buttons with visible words — Previous and Next, translatable through previousLabel/nextLabel — each with a chevron that only reinforces the word (D85). A direction that is unavailable is disabled, not hidden. It holds no state: the consumer holds the page tokens and answers hasPrevious/hasNext. Pair it with a TableCaption whose detail states the range, and move focus there after a page change.\n\n## Theming\n\nThis component has no `--psi-cursor-pagination-*` 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": "TableBody",
-   "description": "`<tbody>` wrapper.",
+   "name": "Toast",
+   "description": "A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. `politeness` (D83) only tells the region which wrapper to use. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.",
    "props": [
+    {
+     "name": "variant",
+     "type": "\"neutral\" | \"success\" | \"warning\" | \"danger\"",
+     "required": false,
+     "default": "neutral",
+     "description": "Status variant."
+    },
     {
      "name": "children",
      "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "The body TableRows."
+     "description": "The message."
+    },
+    {
+     "name": "action",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "Trailing affordance — a ghost Button (Undo, Retry, View)."
+    },
+    {
+     "name": "onDismiss",
+     "type": "(() => void)",
+     "required": false,
+     "default": null,
+     "description": "When provided, renders the dismiss button and calls this. Toast does not\nremove itself; the owner disposes."
+    },
+    {
+     "name": "politeness",
+     "type": "\"polite\" | \"assertive\"",
+     "required": false,
+     "default": null,
+     "description": "Which live wrapper ToastRegion routes this toast into (D83). Unset, the\nvariant decides: neutral and success are polite, warning and danger\nassertive. Set it when the kind of event, not its tone, decides — the\noutcome of the user's own action may interrupt even when it succeeded."
+    },
+    {
+     "name": "statusLabel",
+     "type": "string | null",
+     "required": false,
+     "default": null,
+     "description": "The visually hidden status word (D83). A string replaces the default\n(\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null`\ndrops it. Unset keeps the default, and `neutral` has none."
     },
     {
      "name": "className",
@@ -1154,35 +1865,62 @@
      "required": false,
      "default": null,
      "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<div>`."
     }
    ],
-   "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableBody\n\n`<tbody>` wrapper.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `children` | `ReactNode` | — | yes | The body TableRows. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-table-body-*` 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).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "1..*",
+     "order": 1
+    },
+    {
+     "name": "action",
+     "accepts": {
+      "components": [
+       "Button"
+      ],
+      "contracts": [
+       "inline-content"
+      ]
+     },
+     "cardinality": "0..1",
+     "order": 2
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Toast\n\nA single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. `politeness` (D83) only tells the region which wrapper to use. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"neutral\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Status variant. |\n| `children` | `ReactNode` | — | yes | The message. |\n| `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Undo, Retry, View). |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders the dismiss button and calls this. Toast does not remove itself; the owner disposes. |\n| `politeness` | `\"polite\" \\| \"assertive\"` | — | no | Which live wrapper ToastRegion routes this toast into (D83). Unset, the variant decides: neutral and success are polite, warning and danger assertive. Set it when the kind of event, not its tone, decides — the outcome of the user's own action may interrupt even when it succeeded. |\n| `statusLabel` | `string \\| null` | — | no | The visually hidden status word (D83). A string replaces the default (\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null` drops it. Unset keeps the default, and `neutral` has none. |\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 underlying `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Reaches the action and the dismiss button in DOM order. Esc is not a dismissal — a toast is not modal and traps nothing. |\n| Enter / Space | Activates the focused action or dismiss button. |\n\nPresentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word (\"Success:\", \"Warning:\", \"Error:\"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. statusLabel replaces that word with a translated one, or drops it with null (D83). politeness tells ToastRegion which wrapper speaks the toast; unset, the variant decides. The dismiss button requires no props — it is labelled \"Dismiss notification\".\n\n## Theming\n\nOverride `--psi-toast-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "TableRow",
-   "description": "`<tr>`. `rowId` is the key the `selected` set holds.",
+   "name": "ToastRegion",
+   "description": "The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `politeness`, then `variant`, off each child — the same Children.map technique Table uses for select-all injection. `politeness` wins (D83): the owner of an announcement knows what kind of event it is, and tone is only the default. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group. Remaining HTML attributes, `data-*` included, are spread onto the root element (D83). That is how an application marks the region `data-react-aria-top-layer`, so that a React Aria overlay — which hides everything outside itself with `aria-hidden` — leaves the two live regions exposed. The region's own attributes always win — `role` included. **The region is a landmark, and the wrappers speak only what is new (D90).** `role=\"region\"` makes the `aria-label` legal (a name on a role-less `div` is prohibited) and gives the stack a place in the landmark list. Both wrappers set `aria-atomic=\"false\"` explicitly: `role=\"status\"` and `role=\"alert\"` carry an implicit `true`, which lets a screen reader re-speak everything already in the wrapper whenever one message is added beside it.",
    "props": [
     {
-     "name": "rowId",
-     "type": "string",
+     "name": "placement",
+     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
      "required": false,
-     "default": null,
-     "description": "Stable identity for selection. Required for selectable tables (D62)."
+     "default": "bottom-end",
+     "description": "Corner the stack occupies."
     },
     {
-     "name": "selectLabel",
+     "name": "aria-label",
      "type": "string",
      "required": false,
-     "default": null,
-     "description": "Accessible name for this row's selection checkbox."
+     "default": "Notifications",
+     "description": "Accessible name for the region landmark."
     },
     {
      "name": "children",
      "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "The row's cells."
+     "description": "The stack — `Toast` and `Announcement` elements, each routed to a live\nwrapper by its `politeness`, or by a Toast's variant when it names none."
     },
     {
      "name": "className",
@@ -1190,114 +1928,149 @@
      "required": false,
      "default": null,
      "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the region element."
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableRow\n\n`<tr>`. `rowId` is the key the `selected` set holds.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `rowId` | `string` | — | no | Stable identity for selection. Required for selectable tables (D62). |\n| `selectLabel` | `string` | — | no | Accessible name for this row's selection checkbox. |\n| `children` | `ReactNode` | — | yes | The row's cells. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-table-row-*` 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).\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# ToastRegion\n\nThe positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `politeness`, then `variant`, off each child — the same Children.map technique Table uses for select-all injection. `politeness` wins (D83): the owner of an announcement knows what kind of event it is, and tone is only the default. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group. Remaining HTML attributes, `data-*` included, are spread onto the root element (D83). That is how an application marks the region `data-react-aria-top-layer`, so that a React Aria overlay — which hides everything outside itself with `aria-hidden` — leaves the two live regions exposed. The region's own attributes always win — `role` included. **The region is a landmark, and the wrappers speak only what is new (D90).** `role=\"region\"` makes the `aria-label` legal (a name on a role-less `div` is prohibited) and gives the stack a place in the landmark list. Both wrappers set `aria-atomic=\"false\"` explicitly: `role=\"status\"` and `role=\"alert\"` carry an implicit `true`, which lets a screen reader re-speak everything already in the wrapper whenever one message is added beside it.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `placement` | `\"top-start\" \\| \"top-end\" \\| \"bottom-start\" \\| \"bottom-end\"` | bottom-end | no | Corner the stack occupies. |\n| `aria-label` | `string` | Notifications | no | Accessible name for the region landmark. |\n| `children` | `ReactNode` | — | yes | The stack — `Toast` and `Announcement` elements, each routed to a live wrapper by its `politeness`, or by a Toast's variant when it names none. |\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 region element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Moves into the stacked toasts' controls in DOM order; the region itself is not focusable. |\n\nIs itself a role=\"region\" landmark named by aria-label (default \"Notifications\"; a caller's role never replaces it, D90), and renders two always-present live wrappers — role=\"status\"/aria-live=\"polite\" and role=\"alert\"/aria-live=\"assertive\", both aria-atomic=\"false\" so a screen reader speaks only the message that was added, not what is already there (D90) — and routes each child into one. A Toast or an Announcement that names its politeness goes where it says (D83); a Toast that names none is routed by variant (neutral/success polite, warning/danger assertive). Whatever it holds, the region contains exactly two live regions. Remaining HTML attributes, data-* included, land on the root element, so it can be marked data-react-aria-top-layer and stay exposed while a React Aria overlay is open. Both stay in the DOM when the queue is empty: a live region announces mutations to a subtree that already existed, so a wrapper mounting with its first toast would leave that toast unannounced. Sits on the native top layer via popover=\"manual\", so a toast raised from inside a modal Dialog is still painted above the backdrop and still announced — though showModal() makes everything outside the dialog inert, so it cannot be clicked until the dialog closes; manual (not auto) means no light dismiss, so the click that raised the toast cannot close it. The region is click-through (pointer-events: none) and each toast takes its own clicks back.\n\n## Theming\n\nThis component has no `--psi-toast-region-*` 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": "TableHeaderCell",
-   "description": "`<th scope=\"col\">`. `aria-sort` belongs on the th, never on the inner button — assistive tech reads the sort state from the column header.",
+   "name": "ToastProvider",
+   "description": "Owns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse. **Announcements share the queue, not the limit (D91).** `announce()` adds a speech-only Announcement to the same region — never a live region of its own — and it leaves after a one-second dwell. A later announcement does not remove an earlier one early: removing a node just after it was added can cut its speech, and with non-atomic wrappers (D90) each added node is spoken on its own. Announcements live in their own list, so they never evict a visible toast; their timers live in the same map, so `dismiss`, `clear()` and unmount dispose them as they do a toast's, and they pause with the region. Remaining props go to the ToastRegion (D91): its `aria-label`, a `ref` to the region element, a `className`, and `data-*` attributes such as `data-react-aria-top-layer`.",
    "props": [
     {
-     "name": "sortKey",
-     "type": "string",
+     "name": "limit",
+     "type": "number",
      "required": false,
-     "default": null,
-     "description": "Sort key this column emits. Enables the sort control when the table is `sortable`."
+     "default": 3,
+     "description": "Max simultaneous toasts; the oldest is evicted first."
     },
     {
-     "name": "numeric",
-     "type": "boolean",
+     "name": "duration",
+     "type": "number",
      "required": false,
-     "default": null,
-     "description": "Right-aligns and renders tabular figures (D62)."
+     "default": 5000,
+     "description": "Auto-dismiss for toasts with no action, in ms."
+    },
+    {
+     "name": "actionDuration",
+     "type": "number",
+     "required": false,
+     "default": 10000,
+     "description": "Auto-dismiss for toasts carrying an action, in ms. An affordance that\nvanishes before it can be reached is not an affordance."
+    },
+    {
+     "name": "placement",
+     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+     "required": false,
+     "default": "bottom-end",
+     "description": "Corner the stack occupies."
     },
     {
      "name": "children",
      "type": "ReactNode",
-     "required": false,
+     "required": true,
      "default": null,
-     "description": "Header label."
+     "description": "The subtree that may call `useToast()`. The region is rendered alongside it."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": "\"Notifications\"",
+     "description": "Accessible name for the region landmark, forwarded to ToastRegion."
     },
     {
      "name": "className",
      "type": "string",
      "required": false,
      "default": null,
-     "description": "Additional CSS class name(s) merged onto the component's root element."
+     "description": "Forwarded to the region element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the region element."
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableHeaderCell\n\n`<th scope=\"col\">`. `aria-sort` belongs on the th, never on the inner button — assistive tech reads the sort state from the column header.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `sortKey` | `string` | — | no | Sort key this column emits. Enables the sort control when the table is `sortable`. |\n| `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |\n| `children` | `ReactNode` | — | no | Header label. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-table-header-cell-*` 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).\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# ToastProvider\n\nOwns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse. **Announcements share the queue, not the limit (D91).** `announce()` adds a speech-only Announcement to the same region — never a live region of its own — and it leaves after a one-second dwell. A later announcement does not remove an earlier one early: removing a node just after it was added can cut its speech, and with non-atomic wrappers (D90) each added node is spoken on its own. Announcements live in their own list, so they never evict a visible toast; their timers live in the same map, so `dismiss`, `clear()` and unmount dispose them as they do a toast's, and they pause with the region. Remaining props go to the ToastRegion (D91): its `aria-label`, a `ref` to the region element, a `className`, and `data-*` attributes such as `data-react-aria-top-layer`.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `limit` | `number` | 3 | no | Max simultaneous toasts; the oldest is evicted first. |\n| `duration` | `number` | 5000 | no | Auto-dismiss for toasts with no action, in ms. |\n| `actionDuration` | `number` | 10000 | no | Auto-dismiss for toasts carrying an action, in ms. An affordance that vanishes before it can be reached is not an affordance. |\n| `placement` | `\"top-start\" \\| \"top-end\" \\| \"bottom-start\" \\| \"bottom-end\"` | bottom-end | no | Corner the stack occupies. |\n| `children` | `ReactNode` | — | yes | The subtree that may call `useToast()`. The region is rendered alongside it. |\n| `aria-label` | `string` | \"Notifications\" | no | Accessible name for the region landmark, forwarded to ToastRegion. |\n| `className` | `string` | — | no | Forwarded to the region element. |\n| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the region element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Focus entering the region pauses every auto-dismiss timer; leaving resumes them. |\n\nOwns the queue, the auto-dismiss timers and the single ToastRegion (D65). Timers pause while the pointer or focus is inside the region and resume with the time remaining, satisfying WCAG 2.2.1 for content that disappears on a timer. Toasts carrying an action get a longer default lifetime, so the affordance cannot vanish before it is reached. useToast() throws outside a provider rather than silently no-opping. announce(message, { politeness }) speaks through the same region without showing anything (D91): it renders an Announcement into the wrapper its politeness names (default polite), never a live region of its own, so the application keeps one announcer. An announcement leaves after a one-second dwell, is not removed early by a later one, and never counts against limit, so it cannot evict a visible toast. Its timer pauses with the region and is disposed by dismiss, clear() and unmount like a toast's. Remaining props (aria-label, ref, className, data-* such as data-react-aria-top-layer) are forwarded to the region element.\n\n## Theming\n\nThis component has no `--psi-toast-provider-*` 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": "TableCell",
-   "description": "`<td>`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose.",
+   "name": "Announcement",
+   "description": "Text for a screen reader only, spoken through ToastRegion (D83). **It is not a live region.** It renders no `role` and no `aria-live`, and outside a ToastRegion it announces nothing — the region's two persistent wrappers are the only live regions, and an Announcement is content for one of them. Do not use it as a second announcer. Use it where an event must be spoken and there is nothing to show: a state change of the object on screen, or field errors the form already displays. `politeness` is not read here. ToastRegion reads it off the element to pick a wrapper, the same way it reads a Toast's. The usual way to render one is `useToast().announce(message)` (D91), which puts it in ToastProvider's region and gives it a lifetime: it leaves one second (the dwell) after it was added, and a later announcement does not remove it early — removing a node just after it was added can cut its speech, and the region's non-atomic wrappers (D90) speak each added node on its own. It never counts against the provider's toast `limit`. Rendered by hand, it is controlled, like Toast: it holds no state and never removes itself, so follow the same rule — remove it after a one-second dwell, not before. To announce the same text again, remove it and render it again with a new `key` — a live region speaks changes, and an unchanged node is not one. It takes no `className`: the one thing a class could do to it is make it visible, and then it is a Toast.",
    "props": [
     {
-     "name": "numeric",
-     "type": "boolean",
+     "name": "politeness",
+     "type": "\"polite\" | \"assertive\"",
      "required": false,
-     "default": null,
-     "description": "Right-aligns and renders tabular figures (D62)."
+     "default": "\"polite\"",
+     "description": "Which of ToastRegion's two live wrappers speaks it."
     },
     {
      "name": "children",
      "type": "ReactNode",
-     "required": false,
-     "default": null,
-     "description": "Cell content."
-    },
-    {
-     "name": "className",
-     "type": "string",
-     "required": false,
+     "required": true,
      "default": null,
-     "description": "Additional CSS class name(s) merged onto the component's root element."
+     "description": "The text to announce."
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TableCell\n\n`<td>`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |\n| `children` | `ReactNode` | — | no | Cell content. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-table-cell-*` 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).\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# Announcement\n\nText for a screen reader only, spoken through ToastRegion (D83). **It is not a live region.** It renders no `role` and no `aria-live`, and outside a ToastRegion it announces nothing — the region's two persistent wrappers are the only live regions, and an Announcement is content for one of them. Do not use it as a second announcer. Use it where an event must be spoken and there is nothing to show: a state change of the object on screen, or field errors the form already displays. `politeness` is not read here. ToastRegion reads it off the element to pick a wrapper, the same way it reads a Toast's. The usual way to render one is `useToast().announce(message)` (D91), which puts it in ToastProvider's region and gives it a lifetime: it leaves one second (the dwell) after it was added, and a later announcement does not remove it early — removing a node just after it was added can cut its speech, and the region's non-atomic wrappers (D90) speak each added node on its own. It never counts against the provider's toast `limit`. Rendered by hand, it is controlled, like Toast: it holds no state and never removes itself, so follow the same rule — remove it after a one-second dwell, not before. To announce the same text again, remove it and render it again with a new `key` — a live region speaks changes, and an unchanged node is not one. It takes no `className`: the one thing a class could do to it is make it visible, and then it is a Toast.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `politeness` | `\"polite\" \\| \"assertive\"` | \"polite\" | no | Which of ToastRegion's two live wrappers speaks it. |\n| `children` | `ReactNode` | — | yes | The text to announce. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n\n\nNot a live region: it renders no role and no aria-live, and outside a ToastRegion it announces nothing. It is visually hidden text that ToastRegion places in its polite or assertive wrapper, by the politeness prop (default polite) — for an event that must be spoken and has nothing to show. Keep one ToastRegion as the application's only announcer and put every Announcement inside it; never use an Announcement as a second one. Rendered by useToast().announce() (D91), it gets a lifetime: it leaves after a one-second dwell, a later announcement does not remove it early, and it never counts against the toast limit. Rendered by hand it is controlled like Toast and never removes itself — remove it after the same one-second dwell, not before. To announce the same text again, remove it and render it again with a new key — a live region speaks changes, and an unchanged node is not one. Not focusable, and it takes no space in the toast stack.\n\n## Theming\n\nThis component has no `--psi-announcement-*` 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": "Pagination",
-   "description": "Numbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.",
+   "name": "Banner",
+   "description": "A full-width, page-level status message (D86). It is not a live region: it renders no `role` and no `aria-live`, so mounting one announces nothing, and announcing stays the application's — route the same event through a `ToastRegion` or an `Announcement` if it must be spoken. Controlled and presentational: it holds no state and never removes itself; `onDismiss` reports and the owner disposes. A tinted strip with no radius and no border, it is meant to span the page edge to edge, above the content. For the same message inside content, use `InlineAlert`.",
    "props": [
     {
-     "name": "page",
-     "type": "number",
-     "required": true,
+     "name": "variant",
+     "type": "\"neutral\" | \"success\" | \"warning\" | \"danger\"",
+     "required": false,
+     "default": "neutral",
+     "description": "Status variant."
+    },
+    {
+     "name": "title",
+     "type": "ReactNode",
+     "required": false,
      "default": null,
-     "description": "Current page, 1-based. A value outside `[1, pageCount]` (including\nnon-finite values like `NaN`) is clamped for rendering and logs a\n`console.warn` in development. `pageCount < 1` renders no page buttons."
+     "description": "A short heading, rendered before the body in the medium weight."
     },
     {
-     "name": "pageCount",
-     "type": "number",
+     "name": "children",
+     "type": "ReactNode",
      "required": true,
      "default": null,
-     "description": "Total number of pages."
+     "description": "The message."
     },
     {
-     "name": "onPageChange",
-     "type": "(page: number) => void",
-     "required": true,
+     "name": "action",
+     "type": "ReactNode",
+     "required": false,
      "default": null,
-     "description": "Called with the requested page. Required — unlike Table's `onSortChange`/\n`onSelectionChange`, which are optional because `sortable`/`selectable`\ngate whether they're meaningful, `Pagination` has no such gating boolean:\nthe prop is unconditionally meaningful, so a `Pagination` without it is a\ndead control (final review finding, D62)."
+     "description": "Trailing affordance — a ghost Button (Review, Retry, Learn more)."
     },
     {
-     "name": "siblingCount",
-     "type": "number",
+     "name": "onDismiss",
+     "type": "(() => void)",
      "required": false,
-     "default": 1,
-     "description": "Pages shown either side of the current one before truncating."
+     "default": null,
+     "description": "When provided, renders the dismiss button and calls this. Banner does not\nremove itself; the owner disposes."
     },
     {
-     "name": "aria-label",
-     "type": "string",
+     "name": "statusLabel",
+     "type": "string | null",
      "required": false,
-     "default": "Pagination",
-     "description": "Accessible name for the nav landmark."
+     "default": null,
+     "description": "The visually hidden status word (D83). A string replaces the default\n(\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null`\ndrops it. Unset keeps the default, and `neutral` has none."
     },
     {
      "name": "className",
@@ -1305,14 +2078,47 @@
      "required": false,
      "default": null,
      "description": "Additional CSS class name(s) merged onto the component's root element."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the underlying `<div>`."
     }
    ],
-   "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Pagination\n\nNumbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `page` | `number` | — | yes | Current page, 1-based. A value outside `[1, pageCount]` (including non-finite values like `NaN`) is clamped for rendering and logs a `console.warn` in development. `pageCount < 1` renders no page buttons. |\n| `pageCount` | `number` | — | yes | Total number of pages. |\n| `onPageChange` | `(page: number) => void` | — | yes | Called with the requested page. Required — unlike Table's `onSortChange`/ `onSelectionChange`, which are optional because `sortable`/`selectable` gate whether they're meaningful, `Pagination` has no such gating boolean: the prop is unconditionally meaningful, so a `Pagination` without it is a dead control (final review finding, D62). |\n| `siblingCount` | `number` | 1 | no | Pages shown either side of the current one before truncating. |\n| `aria-label` | `string` | Pagination | no | Accessible name for the nav landmark. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Theming\n\nThis component has no `--psi-pagination-*` 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).\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "slots": [
+    {
+     "name": "title",
+     "accepts": {},
+     "cardinality": "0..1",
+     "order": 1
+    },
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "1..*",
+     "order": 2
+    },
+    {
+     "name": "action",
+     "accepts": {
+      "components": [
+       "Button"
+      ],
+      "contracts": [
+       "inline-content"
+      ]
+     },
+     "cardinality": "0..1",
+     "order": 3
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Banner\n\nA full-width, page-level status message (D86). It is not a live region: it renders no `role` and no `aria-live`, so mounting one announces nothing, and announcing stays the application's — route the same event through a `ToastRegion` or an `Announcement` if it must be spoken. Controlled and presentational: it holds no state and never removes itself; `onDismiss` reports and the owner disposes. A tinted strip with no radius and no border, it is meant to span the page edge to edge, above the content. For the same message inside content, use `InlineAlert`.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"neutral\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Status variant. |\n| `title` | `ReactNode` | — | no | A short heading, rendered before the body in the medium weight. |\n| `children` | `ReactNode` | — | yes | The message. |\n| `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Review, Retry, Learn more). |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders the dismiss button and calls this. Banner does not remove itself; the owner disposes. |\n| `statusLabel` | `string \\| null` | — | no | The visually hidden status word (D83). A string replaces the default (\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null` drops it. Unset keeps the default, and `neutral` has none. |\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 underlying `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Reaches the action and the dismiss button, in that order, when present. The banner itself is not focusable. |\n| Enter / Space | Activates the focused action or the dismiss button. |\n\nNot a live region: it renders no role and no aria-live, so mounting a Banner announces nothing; announcing stays the application's (route the same event through a ToastRegion or an Announcement if it must be spoken). Presentational and controlled (D86): onDismiss reports and the owner disposes; Banner never removes itself. The variant's meaning is carried by a visually hidden status word (\"Success:\", \"Warning:\", \"Error:\"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no word. statusLabel replaces that word with a translated one, or drops it with null (D83). The dismiss button is labelled \"Dismiss\". Put it first in the page content so it is met before the content it qualifies.\n\n## Theming\n\nOverride `--psi-banner-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "Toast",
-   "description": "A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.",
+   "name": "InlineAlert",
+   "description": "Not `role=\"alert\"`, despite its name. It is not a live region: it renders no `role` and no `aria-live`, so mounting one announces nothing, and announcing stays the application's — route the same event through a `ToastRegion` or an `Announcement` if it must be spoken. A status message that sits inside content (D86): above a form, in a panel. A tinted surface with a 1px border in the variant's colour and a radius; it fills the width of its container rather than setting its own. Presentational and stateless, with no dismiss button. For a page-wide strip, use `Banner`.",
    "props": [
     {
      "name": "variant",
@@ -1321,6 +2127,13 @@
      "default": "neutral",
      "description": "Status variant."
     },
+    {
+     "name": "title",
+     "type": "ReactNode",
+     "required": false,
+     "default": null,
+     "description": "A short heading, rendered before the body in the medium weight."
+    },
     {
      "name": "children",
      "type": "ReactNode",
@@ -1333,14 +2146,14 @@
      "type": "ReactNode",
      "required": false,
      "default": null,
-     "description": "Trailing affordance — a ghost Button (Undo, Retry, View)."
+     "description": "Trailing affordance — a ghost Button (Review, Retry, Learn more)."
     },
     {
-     "name": "onDismiss",
-     "type": "(() => void)",
+     "name": "statusLabel",
+     "type": "string | null",
      "required": false,
      "default": null,
-     "description": "When provided, renders the dismiss button and calls this. Toast does not\nremove itself; the owner disposes."
+     "description": "The visually hidden status word (D83). A string replaces the default\n(\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null`\ndrops it. Unset keeps the default, and `neutral` has none."
     },
     {
      "name": "className",
@@ -1358,11 +2171,17 @@
     }
    ],
    "slots": [
+    {
+     "name": "title",
+     "accepts": {},
+     "cardinality": "0..1",
+     "order": 1
+    },
     {
      "name": "body",
      "accepts": {},
      "cardinality": "1..*",
-     "order": 1
+     "order": 2
     },
     {
      "name": "action",
@@ -1375,35 +2194,35 @@
       ]
      },
      "cardinality": "0..1",
-     "order": 2
+     "order": 3
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Toast\n\nA single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"neutral\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Status variant. |\n| `children` | `ReactNode` | — | yes | The message. |\n| `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Undo, Retry, View). |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders the dismiss button and calls this. Toast does not remove itself; the owner disposes. |\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 underlying `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Reaches the action and the dismiss button in DOM order. Esc is not a dismissal — a toast is not modal and traps nothing. |\n| Enter / Space | Activates the focused action or dismiss button. |\n\nPresentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word (\"Success:\", \"Warning:\", \"Error:\"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. The dismiss button requires no props — it is labelled \"Dismiss notification\".\n\n## Theming\n\nOverride `--psi-toast-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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).\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# InlineAlert\n\nNot `role=\"alert\"`, despite its name. It is not a live region: it renders no `role` and no `aria-live`, so mounting one announces nothing, and announcing stays the application's — route the same event through a `ToastRegion` or an `Announcement` if it must be spoken. A status message that sits inside content (D86): above a form, in a panel. A tinted surface with a 1px border in the variant's colour and a radius; it fills the width of its container rather than setting its own. Presentational and stateless, with no dismiss button. For a page-wide strip, use `Banner`.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"neutral\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Status variant. |\n| `title` | `ReactNode` | — | no | A short heading, rendered before the body in the medium weight. |\n| `children` | `ReactNode` | — | yes | The message. |\n| `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Review, Retry, Learn more). |\n| `statusLabel` | `string \\| null` | — | no | The visually hidden status word (D83). A string replaces the default (\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null` drops it. Unset keeps the default, and `neutral` has none. |\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 underlying `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Reaches the action when present. The alert itself is not focusable. |\n| Enter / Space | Activates the focused action. |\n\nNot a live region, and not role=\"alert\" despite its name: it renders no role and no aria-live, so mounting an InlineAlert announces nothing; announcing stays the application's (route the same event through a ToastRegion or an Announcement if it must be spoken). Presentational (D86): it holds no state and has no dismiss button. The variant's meaning is carried by a visually hidden status word (\"Success:\", \"Warning:\", \"Error:\"), never by colour, border and icon shape alone; the icon is aria-hidden. neutral has no status and gets no word. statusLabel replaces that word with a translated one, or drops it with null (D83). Place it in reading order before the content it qualifies, such as above the form it is about.\n\n## Theming\n\nOverride `--psi-inline-alert-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "ToastRegion",
-   "description": "The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `variant` off each child, the same Children.map technique Table uses for select-all injection. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group.",
+   "name": "Skeleton",
+   "description": "A loading placeholder. It is not a live region: it renders no `role` and no `aria-live`, and it is always `aria-hidden=\"true\"`, so assistive tech skips it entirely. Put `aria-busy` on the region the skeleton stands for — that is what tells a screen reader the content is coming. Its width fills the container; size the container, not the skeleton. The pulse is an opacity animation that stops under `prefers-reduced-motion: reduce` (D86).",
    "props": [
     {
-     "name": "placement",
-     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+     "name": "variant",
+     "type": "\"text\" | \"block\"",
      "required": false,
-     "default": "bottom-end",
-     "description": "Corner the stack occupies."
+     "default": "text",
+     "description": "`text` renders `lines` stacked bars; `block` one box."
     },
     {
-     "name": "aria-label",
-     "type": "string",
+     "name": "lines",
+     "type": "number",
      "required": false,
-     "default": "Notifications",
-     "description": "Accessible name for the region."
+     "default": 1,
+     "description": "Number of text lines; the last of several is shorter. Text only."
     },
     {
-     "name": "children",
-     "type": "ReactNode",
-     "required": true,
-     "default": null,
-     "description": "The toast stack — `Toast` elements, routed to a live wrapper by variant."
+     "name": "size",
+     "type": "24 | 32 | 40 | 48",
+     "required": false,
+     "default": 40,
+     "description": "Height of a block, from the size scale. Block only."
     },
     {
      "name": "className",
@@ -1417,54 +2236,61 @@
      "type": "Ref<HTMLDivElement>",
      "required": false,
      "default": null,
-     "description": "Forwarded ref to the region element."
+     "description": "Forwarded ref to the underlying `<div>`."
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# ToastRegion\n\nThe positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `variant` off each child, the same Children.map technique Table uses for select-all injection. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `placement` | `\"top-start\" \\| \"top-end\" \\| \"bottom-start\" \\| \"bottom-end\"` | bottom-end | no | Corner the stack occupies. |\n| `aria-label` | `string` | Notifications | no | Accessible name for the region. |\n| `children` | `ReactNode` | — | yes | The toast stack — `Toast` elements, routed to a live wrapper by variant. |\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 region element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Moves into the stacked toasts' controls in DOM order; the region itself is not focusable. |\n\nRenders two always-present live wrappers — role=\"status\"/aria-live=\"polite\" and role=\"alert\"/aria-live=\"assertive\" — and routes each toast into one by variant (neutral/success polite, warning/danger assertive). Both stay in the DOM when the queue is empty: a live region announces mutations to a subtree that already existed, so a wrapper mounting with its first toast would leave that toast unannounced. Sits on the native top layer via popover=\"manual\", so a toast raised from inside a modal Dialog is still painted above the backdrop and still announced — though showModal() makes everything outside the dialog inert, so it cannot be clicked until the dialog closes; manual (not auto) means no light dismiss, so the click that raised the toast cannot close it. The region is click-through (pointer-events: none) and each toast takes its own clicks back.\n\n## Theming\n\nThis component has no `--psi-toast-region-*` 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).\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# Skeleton\n\nA loading placeholder. It is not a live region: it renders no `role` and no `aria-live`, and it is always `aria-hidden=\"true\"`, so assistive tech skips it entirely. Put `aria-busy` on the region the skeleton stands for — that is what tells a screen reader the content is coming. Its width fills the container; size the container, not the skeleton. The pulse is an opacity animation that stops under `prefers-reduced-motion: reduce` (D86).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"text\" \\| \"block\"` | text | no | `text` renders `lines` stacked bars; `block` one box. |\n| `lines` | `number` | 1 | no | Number of text lines; the last of several is shorter. Text only. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 40 | no | Height of a block, from the size scale. Block only. |\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 underlying `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n\n\nNot a live region: it renders no role and no aria-live, and it is always aria-hidden=\"true\", so assistive tech skips it entirely. Put aria-busy=\"true\" on the region the skeleton stands for (a table body, a card, a list) and remove it when the content arrives; that, not the skeleton, is what tells a screen reader the content is loading. Not focusable. The pulse is an opacity animation that stops under prefers-reduced-motion: reduce, because zeroing the duration of an infinite alternating animation flickers instead of stopping (D86).\n\n## Theming\n\nOverride `--psi-skeleton-*` custom properties at any scope.\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "ToastProvider",
-   "description": "Owns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse.",
+   "name": "CopyButton",
+   "description": "Not a live region: it renders no role and no `aria-live`, never changes its label or icon after a copy, and announces nothing. The application speaks the result — route `onCopy` through its announcer or a Toast (D86). Copies `value` to the clipboard when pressed. A `Button` with a leading `IconCopy` and a visible label; the icon only reinforces the word.",
    "props": [
     {
-     "name": "limit",
-     "type": "number",
+     "name": "value",
+     "type": "string",
+     "required": true,
+     "default": null,
+     "description": "The text written to the clipboard."
+    },
+    {
+     "name": "label",
+     "type": "string",
      "required": false,
-     "default": 3,
-     "description": "Max simultaneous toasts; the oldest is evicted first."
+     "default": "Copy",
+     "description": "Visible text of the button."
     },
     {
-     "name": "duration",
-     "type": "number",
+     "name": "size",
+     "type": "24 | 32 | 40 | 48",
      "required": false,
-     "default": 5000,
-     "description": "Auto-dismiss for toasts with no action, in ms."
+     "default": 32,
+     "description": "Button height in px."
     },
     {
-     "name": "actionDuration",
-     "type": "number",
+     "name": "variant",
+     "type": "\"accent\" | \"accent-subtle\" | \"neutral\" | \"neutral-subtle\" | \"ghost\" | \"danger\" | \"danger-subtle\" | \"outline\"",
      "required": false,
-     "default": 10000,
-     "description": "Auto-dismiss for toasts carrying an action, in ms. An affordance that\nvanishes before it can be reached is not an affordance."
+     "default": "ghost",
+     "description": "Button variant."
     },
     {
-     "name": "placement",
-     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+     "name": "onCopy",
+     "type": "((result: \"copied\" | \"failed\") => void)",
      "required": false,
-     "default": "bottom-end",
-     "description": "Corner the stack occupies."
+     "default": null,
+     "description": "Called with the outcome once the clipboard write settles. `\"failed\"` covers\na rejected write and an environment with no clipboard API."
     },
     {
-     "name": "children",
-     "type": "ReactNode",
-     "required": true,
+     "name": "className",
+     "type": "string",
+     "required": false,
      "default": null,
-     "description": "The subtree that may call `useToast()`. The region is rendered alongside it."
+     "description": "Additional CSS class name(s) merged onto the component's root element."
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# ToastProvider\n\nOwns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `limit` | `number` | 3 | no | Max simultaneous toasts; the oldest is evicted first. |\n| `duration` | `number` | 5000 | no | Auto-dismiss for toasts with no action, in ms. |\n| `actionDuration` | `number` | 10000 | no | Auto-dismiss for toasts carrying an action, in ms. An affordance that vanishes before it can be reached is not an affordance. |\n| `placement` | `\"top-start\" \\| \"top-end\" \\| \"bottom-start\" \\| \"bottom-end\"` | bottom-end | no | Corner the stack occupies. |\n| `children` | `ReactNode` | — | yes | The subtree that may call `useToast()`. The region is rendered alongside it. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Focus entering the region pauses every auto-dismiss timer; leaving resumes them. |\n\nOwns the queue, the auto-dismiss timers and the single ToastRegion (D65). Timers pause while the pointer or focus is inside the region and resume with the time remaining, satisfying WCAG 2.2.1 for content that disappears on a timer. Toasts carrying an action get a longer default lifetime, so the affordance cannot vanish before it is reached. useToast() throws outside a provider rather than silently no-opping.\n\n## Theming\n\nThis component has no `--psi-toast-provider-*` 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).\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# CopyButton\n\nNot a live region: it renders no role and no `aria-live`, never changes its label or icon after a copy, and announces nothing. The application speaks the result — route `onCopy` through its announcer or a Toast (D86). Copies `value` to the clipboard when pressed. A `Button` with a leading `IconCopy` and a visible label; the icon only reinforces the word.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | The text written to the clipboard. |\n| `label` | `string` | Copy | no | Visible text of the button. |\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Button height in px. |\n| `variant` | `\"accent\" \\| \"accent-subtle\" \\| \"neutral\" \\| \"neutral-subtle\" \\| \"ghost\" \\| \"danger\" \\| \"danger-subtle\" \\| \"outline\"` | ghost | no | Button variant. |\n| `onCopy` | `((result: \"copied\" \\| \"failed\") => void)` | — | no | Called with the outcome once the clipboard write settles. `\"failed\"` covers a rejected write and an environment with no clipboard API. |\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| Enter / Space | Copies the value to the clipboard. |\n\nNot a live region: it renders no role and no aria-live, announces nothing, and does not change its label or icon after a copy, so a screen reader hears the same button before and after. The application speaks the result: onCopy reports \"copied\" or \"failed\" (a rejected write, or no clipboard API), and the application routes that through its announcer or a Toast (D86). The label is visible text; the icon is aria-hidden and only reinforces it. Focus stays on the button.\n\n## Theming\n\nThis component has no `--psi-copy-button-*` 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## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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": "Tabs",
@@ -1475,7 +2301,7 @@
      "type": "string",
      "required": true,
      "default": null,
-     "description": "Controlled selected tab, matched against each `Tab`/`TabPanel` value."
+     "description": "Controlled selected tab, matched against each `Tab`/`TabPanel` value. A\nvalue that matches no tab selects nothing, and the first enabled\ntab holds the list's tab stop (D93); development builds warn."
     },
     {
      "name": "onValueChange",
@@ -1526,7 +2352,7 @@
      "order": 1
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tabs\n\nTab set root (D67) — holds no selection state of its own, following D50, D53 and D62: `value` and `onValueChange` are required and there is no `defaultValue`. Values are strings rather than indices because an index breaks the moment a tab is inserted, and real tab sets map to ids. `Tab` and `TabPanel` pair by value, so their source order need not match. Activation is automatic: arrow keys move focus and selection together. That is the APG default where panel content is already available, and manual activation is deliberately not offered as a mode — a consumer for whom activating a panel is expensive already controls what the panel renders.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Controlled selected tab, matched against each `Tab`/`TabPanel` value. |\n| `onValueChange` | `(value: string) => void` | — | yes | Fires with the newly selected value; the consumer flips `value`. |\n| `orientation` | `\"horizontal\" \\| \"vertical\"` | horizontal | no | Axis of the tab list, which also picks the arrow keys. |\n| `children` | `ReactNode` | — | yes | A `TabList` and one `TabPanel` per tab. |\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 wrapper `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Enters the tab list at its selected tab (one stop for the whole list), then moves on to the active panel. |\n\nControlled-only (D67): value and onValueChange are required and Tabs never selects itself. Tab and TabPanel pair by string value, not index, so their source order need not match. Every panel renders and unselected ones carry `hidden`, so aria-controls always resolves and panel DOM state survives a switch.\n\n## Theming\n\nOverride `--psi-tabs-*` 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).\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# Tabs\n\nTab set root (D67) — holds no selection state of its own, following D50, D53 and D62: `value` and `onValueChange` are required and there is no `defaultValue`. Values are strings rather than indices because an index breaks the moment a tab is inserted, and real tab sets map to ids. `Tab` and `TabPanel` pair by value, so their source order need not match. Activation is automatic: arrow keys move focus and selection together. That is the APG default where panel content is already available, and manual activation is deliberately not offered as a mode — a consumer for whom activating a panel is expensive already controls what the panel renders.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Controlled selected tab, matched against each `Tab`/`TabPanel` value. A value that matches no tab selects nothing, and the first enabled tab holds the list's tab stop (D93); development builds warn. |\n| `onValueChange` | `(value: string) => void` | — | yes | Fires with the newly selected value; the consumer flips `value`. |\n| `orientation` | `\"horizontal\" \\| \"vertical\"` | horizontal | no | Axis of the tab list, which also picks the arrow keys. |\n| `children` | `ReactNode` | — | yes | A `TabList` and one `TabPanel` per tab. |\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 wrapper `<div>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Enters the tab list at its selected tab (one stop for the whole list), then moves on to the active panel. When value matches no tab, the first enabled tab holds the stop (the first tab if all are disabled) and none is selected; a selected disabled tab keeps the stop (D93). |\n\nControlled-only (D67): value and onValueChange are required and Tabs never selects itself. Tab and TabPanel pair by string value, not index, so their source order need not match. Every panel renders and unselected ones carry `hidden`, so aria-controls always resolves and panel DOM state survives a switch.\n\n## Theming\n\nOverride `--psi-tabs-*` 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": "TabList",
@@ -1562,7 +2388,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TabList\n\nThe `role=\"tablist\"` container (D67). Owns the roving tabindex: the whole list is one Tab stop, and the arrow keys move between tabs inside it.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `aria-label` | `string` | — | no | Accessible name for the tab set. Declared here rather than inherited so docgen keeps it in the manifest (D60) — a tablist without a name is announced as an unlabelled group, and the prop would otherwise be invisible to an agent reading the manifest. |\n| `children` | `ReactNode` | — | yes | One `Tab` per view. |\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 tablist element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Arrow Left / Arrow Right | Horizontal orientation: moves to the previous/next enabled tab, wrapping at both ends. Selection follows focus (automatic activation). |\n| Arrow Up / Arrow Down | Vertical orientation: the same, on the block axis. The cross-axis arrows are ignored rather than swallowed. |\n| Home / End | Jumps to the first or last enabled tab. |\n\nRenders role=\"tablist\" with aria-orientation. Requires an accessible name — pass aria-label, which is promoted onto its own props interface (D60) so the manifest shows it. Owns the roving tabindex: exactly one tab is in the page tab order at a time.\n\n## Theming\n\nThis component has no `--psi-tab-list-*` 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).\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# TabList\n\nThe `role=\"tablist\"` container (D67). Owns the roving tabindex: the whole list is one Tab stop, and the arrow keys move between tabs inside it.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `aria-label` | `string` | — | no | Accessible name for the tab set. Declared here rather than inherited so docgen keeps it in the manifest (D60) — a tablist without a name is announced as an unlabelled group, and the prop would otherwise be invisible to an agent reading the manifest. |\n| `children` | `ReactNode` | — | yes | One `Tab` per view. |\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 tablist element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Arrow Left / Arrow Right | Horizontal orientation: moves to the previous/next enabled tab, wrapping at both ends. Selection follows focus (automatic activation). |\n| Arrow Up / Arrow Down | Vertical orientation: the same, on the block axis. The cross-axis arrows are ignored rather than swallowed. |\n| Home / End | Jumps to the first or last enabled tab. |\n\nRenders role=\"tablist\" with aria-orientation. Requires an accessible name — pass aria-label, which is promoted onto its own props interface (D60) so the manifest shows it. Owns the roving tabindex: exactly one tab is in the page tab order at a time.\n\n## Theming\n\nThis component has no `--psi-tab-list-*` 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": "Tab",
@@ -1605,7 +2431,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tab\n\nOne `role=\"tab\"` (D67). Renders a real `<button>`. `disabled` sets `aria-disabled` rather than the `disabled` attribute, so the tab stays discoverable to assistive tech while being skipped by roving navigation — the same choice MenuItem made in D53.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Pairs this tab with the `TabPanel` of the same value. |\n| `children` | `ReactNode` | — | yes | Label — keep it to one or two words. |\n| `disabled` | `boolean` | false | no | Skipped by arrow navigation and not selectable, but still announced. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLButtonElement>` | — | no | Forwarded ref to the underlying `<button>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter / Space | Activates (native button behavior); arrow keys already select on focus. |\n\nRenders a real <button> with role=\"tab\", aria-selected and aria-controls. disabled sets aria-disabled (not the disabled attribute) so the tab stays discoverable to assistive tech while being skipped by roving navigation and refused for selection — the same choice MenuItem made in D53.\n\n## Theming\n\nThis component has no `--psi-tab-*` 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).\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# Tab\n\nOne `role=\"tab\"` (D67). Renders a real `<button>`. `disabled` sets `aria-disabled` rather than the `disabled` attribute, so the tab stays discoverable to assistive tech while being skipped by roving navigation — the same choice MenuItem made in D53.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Pairs this tab with the `TabPanel` of the same value. |\n| `children` | `ReactNode` | — | yes | Label — keep it to one or two words. |\n| `disabled` | `boolean` | false | no | Skipped by arrow navigation and not selectable, but still announced. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n| `ref` | `Ref<HTMLButtonElement>` | — | no | Forwarded ref to the underlying `<button>`. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Enter / Space | Activates (native button behavior); arrow keys already select on focus. |\n\nRenders a real <button> with role=\"tab\", aria-selected and aria-controls. disabled sets aria-disabled (not the disabled attribute) so the tab stays discoverable to assistive tech while being skipped by roving navigation and refused for selection — the same choice MenuItem made in D53.\n\n## Theming\n\nThis component has no `--psi-tab-*` 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": "TabPanel",
@@ -1641,7 +2467,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# TabPanel\n\nOne `role=\"tabpanel\"` (D67). Every panel renders; unselected ones carry `hidden`. Returning null instead would leave `aria-controls` on every unselected tab pointing at an element that does not exist, and would throw away DOM state — a half-filled form in a panel would lose its values on each tab switch. The cost is a heavier DOM when panels are large; the answer to that is rendering less inside the panel, not unmounting it behind the consumer's back. `tabIndex={0}` because a panel whose content has no focusable element would otherwise be unreachable by keyboard.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Pairs this panel with the `Tab` of the same value. |\n| `children` | `ReactNode` | — | yes | The view for this tab. Rendered even when unselected, then `hidden`. |\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 panel element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | The panel itself is a tab stop (tabIndex=0), so a panel whose content has no focusable element is still reachable. |\n\nRenders role=\"tabpanel\" with aria-labelledby pointing back at its tab. Unselected panels stay in the DOM with `hidden`.\n\n## Theming\n\nThis component has no `--psi-tab-panel-*` 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).\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# TabPanel\n\nOne `role=\"tabpanel\"` (D67). Every panel renders; unselected ones carry `hidden`. Returning null instead would leave `aria-controls` on every unselected tab pointing at an element that does not exist, and would throw away DOM state — a half-filled form in a panel would lose its values on each tab switch. The cost is a heavier DOM when panels are large; the answer to that is rendering less inside the panel, not unmounting it behind the consumer's back. `tabIndex={0}` because a panel whose content has no focusable element would otherwise be unreachable by keyboard.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `value` | `string` | — | yes | Pairs this panel with the `Tab` of the same value. |\n| `children` | `ReactNode` | — | yes | The view for this tab. Rendered even when unselected, then `hidden`. |\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 panel element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | The panel itself is a tab stop (tabIndex=0), so a panel whose content has no focusable element is still reachable. |\n\nRenders role=\"tabpanel\" with aria-labelledby pointing back at its tab. Unselected panels stay in the DOM with `hidden`.\n\n## Theming\n\nThis component has no `--psi-tab-panel-*` 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"
   }
  ],
  "tokens": [
@@ -3194,6 +4020,233 @@
    "blocked": false,
    "preset": "<Toast action={<Button variant=\"ghost\">Undo</Button>} variant=\"success\">[what just happened]</Toast>\n"
   },
+  {
+   "id": "announcer",
+   "intent": "Under a ToastProvider, do not render this — call useToast().announce() (D91). For an application with its own ToastRegion and no provider: one region holding visible toasts and speech-only Announcements, each routed by politeness rather than by tone. For a single confirmation toast, use action-feedback.",
+   "match": [
+    "announcer",
+    "live region",
+    "screen reader announcement",
+    "aria-live",
+    "status message",
+    "announce without a toast",
+    "polite and assertive"
+   ],
+   "compose": {
+    "component": "ToastRegion",
+    "slots": {
+     "body": [
+      {
+       "component": "Toast",
+       "props": {
+        "variant": "success",
+        "politeness": "{param:outcome-politeness}"
+       },
+       "slots": {
+        "body": [
+         "{content:outcome}"
+        ]
+       }
+      },
+      {
+       "component": "Announcement",
+       "props": {
+        "politeness": "polite"
+       },
+       "slots": {
+        "body": [
+         "{content:state-change}"
+        ]
+       }
+      },
+      {
+       "component": "Announcement",
+       "props": {
+        "politeness": "assertive"
+       },
+       "slots": {
+        "body": [
+         "{content:field-errors}"
+        ]
+       }
+      }
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "outcome-politeness",
+     "ask": "Should the outcome of the user's own action interrupt, success included?",
+     "options": [
+      "assertive",
+      "polite"
+     ],
+     "default": "assertive"
+    }
+   ],
+   "content": {
+    "outcome": "[the outcome of the action the user just took]",
+    "state-change": "[a change to the object on screen, spoken and not shown]",
+    "field-errors": "[how many fields need attention, spoken after a failed submission]"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<ToastRegion>\n  <Toast politeness=\"assertive\" variant=\"success\">[the outcome of the action the user just took]</Toast>\n  <Announcement politeness=\"polite\">[a change to the object on screen, spoken and not shown]</Announcement>\n  <Announcement politeness=\"assertive\">[how many fields need attention, spoken after a failed submission]</Announcement>\n</ToastRegion>\n"
+  },
+  {
+   "id": "app-shell",
+   "intent": "An application frame: a skip link, a full-width header with a Menu toggle that names the sidebar (aria-expanded and aria-controls — wire both and sidebarOpen to one piece of state), a dark sub-themed sidebar holding a NavTree, and a main region that scrolls on its own so nothing hides under the header. A closed sidebar is hidden, not narrowed. A desktop frame, not a responsive drawer. Put a link of your own router in each NavItem instead of href, and aria-current=\"page\" on the current one",
+   "match": [
+    "app shell",
+    "application shell",
+    "sidebar layout",
+    "admin layout",
+    "side navigation"
+   ],
+   "compose": {
+    "component": "AppShell",
+    "props": {
+     "sidebarOpen": true,
+     "sidebarTheme": "dark"
+    },
+    "slots": {
+     "skipLink": [
+      {
+       "component": "SkipLink",
+       "props": {
+        "href": "#main"
+       },
+       "content": "skip-label"
+      }
+     ],
+     "header": [
+      {
+       "component": "NavBar",
+       "props": {
+        "fluid": true
+       },
+       "slots": {
+        "brand": [
+         {
+          "component": "Button",
+          "props": {
+           "variant": "ghost",
+           "size": 32,
+           "aria-expanded": true,
+           "aria-controls": "sidebar"
+          },
+          "content": "menu-label"
+         },
+         "{content:brand}"
+        ],
+        "actions": [
+         {
+          "component": "Button",
+          "props": {
+           "variant": "neutral",
+           "size": 32
+          },
+          "content": "account-label"
+         }
+        ]
+       }
+      }
+     ],
+     "sidebar": [
+      {
+       "component": "NavTree",
+       "props": {
+        "aria-label": "{content:nav-label}"
+       },
+       "slots": {
+        "body": [
+         {
+          "component": "NavItem",
+          "props": {
+           "href": "#overview",
+           "current": true
+          },
+          "content": "overview-label"
+         },
+         {
+          "component": "NavGroup",
+          "props": {
+           "label": "{content:group-1-label}",
+           "open": true
+          },
+          "slots": {
+           "body": [
+            {
+             "component": "NavItem",
+             "props": {
+              "href": "#group-1-first"
+             },
+             "content": "group-1-first-label"
+            },
+            {
+             "component": "NavItem",
+             "props": {
+              "href": "#group-1-second"
+             },
+             "content": "group-1-second-label"
+            }
+           ]
+          }
+         },
+         {
+          "component": "NavGroup",
+          "props": {
+           "label": "{content:group-2-label}",
+           "open": true
+          },
+          "slots": {
+           "body": [
+            {
+             "component": "NavItem",
+             "props": {
+              "href": "#group-2-first"
+             },
+             "content": "group-2-first-label"
+            },
+            {
+             "component": "NavItem",
+             "props": {
+              "href": "#group-2-second"
+             },
+             "content": "group-2-second-label"
+            }
+           ]
+          }
+         }
+        ]
+       }
+      }
+     ],
+     "body": [
+      "{content:page}"
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "skip-label": "Skip to content",
+    "menu-label": "Menu",
+    "brand": "[product name]",
+    "account-label": "[account]",
+    "nav-label": "Main",
+    "overview-label": "Overview",
+    "group-1-label": "[group name]",
+    "group-1-first-label": "[page name]",
+    "group-1-second-label": "[page name]",
+    "group-2-label": "[group name]",
+    "group-2-first-label": "[page name]",
+    "group-2-second-label": "[page name]",
+    "page": "[the page; it scrolls on its own]"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<AppShell\n  header={<NavBar\n    actions={<Button size={32} variant=\"neutral\">[account]</Button>}\n    brand={<>\n      <Button aria-controls=\"sidebar\" aria-expanded={true} size={32} variant=\"ghost\">Menu</Button>\n      [product name]\n    </>}\n    fluid={true}\n  />}\n  sidebar={<NavTree\n    aria-label=\"Main\"\n  >\n    <NavItem current={true} href=\"#overview\">Overview</NavItem>\n    <NavGroup\n      label=\"[group name]\"\n      open={true}\n    >\n      <NavItem href=\"#group-1-first\">[page name]</NavItem>\n      <NavItem href=\"#group-1-second\">[page name]</NavItem>\n    </NavGroup>\n    <NavGroup\n      label=\"[group name]\"\n      open={true}\n    >\n      <NavItem href=\"#group-2-first\">[page name]</NavItem>\n      <NavItem href=\"#group-2-second\">[page name]</NavItem>\n    </NavGroup>\n  </NavTree>}\n  sidebarOpen={true}\n  sidebarTheme=\"dark\"\n  skipLink={<SkipLink href=\"#main\">Skip to content</SkipLink>}\n>\n  [the page; it scrolls on its own]\n</AppShell>\n"
+  },
   {
    "id": "bulk-action-bar",
    "intent": "Bar that appears when table rows are selected: selection count, bulk actions, and a clear-selection control",
@@ -3226,36 +4279,137 @@
        "content": "export-label"
       },
       {
-       "component": "Button",
-       "props": {
-        "variant": "danger-subtle"
-       },
-       "content": "delete-label"
+       "component": "Button",
+       "props": {
+        "variant": "danger-subtle"
+       },
+       "content": "delete-label"
+      },
+      {
+       "component": "Button",
+       "props": {
+        "variant": "ghost"
+       },
+       "content": "clear-label"
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "count-label": "[n] selected",
+    "export-label": "Export",
+    "delete-label": "Delete",
+    "clear-label": "Clear selection"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toolbar\n  gap={12}\n>\n  <Tag subtle={true} variant=\"accent\">[n] selected</Tag>\n  <Button variant=\"neutral\">Export</Button>\n  <Button variant=\"danger-subtle\">Delete</Button>\n  <Button variant=\"ghost\">Clear selection</Button>\n</Toolbar>\n"
+  },
+  {
+   "id": "copyable-id",
+   "intent": "A labelled identifier with a button that copies it; the button announces nothing, the application speaks the result",
+   "match": [
+    "copy id",
+    "copyable identifier",
+    "copy to clipboard",
+    "reference number",
+    "request id"
+   ],
+   "compose": {
+    "component": "DescriptionList",
+    "props": {
+     "layout": "inline"
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "DescriptionItem",
+       "props": {
+        "term": "{content:term}"
+       },
+       "slots": {
+        "body": [
+         "{content:value}",
+         {
+          "component": "CopyButton",
+          "props": {
+           "value": "{content:value}",
+           "size": 24
+          }
+         }
+        ]
+       }
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "term": "[identifier name]",
+    "value": "[the identifier — set it in a mono class such as psi-text-mono-14-20-regular]"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<DescriptionList\n  layout=\"inline\"\n>\n  <DescriptionItem\n    term=\"[identifier name]\"\n  >\n    [the identifier — set it in a mono class such as psi-text-mono-14-20-regular]\n    <CopyButton size={24} value=\"[the identifier — set it in a mono class such as psi-text-mono-14-20-regular]\" />\n  </DescriptionItem>\n</DescriptionList>\n"
+  },
+  {
+   "id": "cursor-pagination",
+   "intent": "Page-size selector and previous/next control beneath a list that pages by opaque token — no page count, no page numbers; pair with a TableCaption whose detail states the range and takes focus after a page change",
+   "match": [
+    "cursor pagination",
+    "token pagination",
+    "next page token",
+    "previous next",
+    "load more",
+    "keyset pagination",
+    "page size"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "props": {
+     "gap": 12,
+     "align": "end"
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Field",
+       "slots": {
+        "label": [
+         "{content:page-size-label}"
+        ],
+        "body": [
+         {
+          "component": "Select",
+          "props": {
+           "size": 32
+          }
+         }
+        ]
+       }
       },
       {
-       "component": "Button",
+       "component": "CursorPagination",
        "props": {
-        "variant": "ghost"
-       },
-       "content": "clear-label"
+        "hasPrevious": true,
+        "hasNext": true
+       }
       }
      ]
     }
    },
    "parameters": [],
    "content": {
-    "count-label": "[n] selected",
-    "export-label": "Export",
-    "delete-label": "Delete",
-    "clear-label": "Clear selection"
+    "page-size-label": "Rows per page"
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Toolbar\n  gap={12}\n>\n  <Tag subtle={true} variant=\"accent\">[n] selected</Tag>\n  <Button variant=\"neutral\">Export</Button>\n  <Button variant=\"danger-subtle\">Delete</Button>\n  <Button variant=\"ghost\">Clear selection</Button>\n</Toolbar>\n"
+   "preset": "<Toolbar\n  align=\"end\"\n  gap={12}\n>\n  <Field\n    label=\"Rows per page\"\n  >\n    <Select size={32} />\n  </Field>\n  <CursorPagination hasNext={true} hasPrevious={true} />\n</Toolbar>\n"
   },
   {
    "id": "data-table",
-   "intent": "Sortable, selectable table of records with numeric columns and a per-row actions menu — compose the row menu from the row-actions pattern",
+   "intent": "Sortable, selectable table of records with a caption stating the range, numeric columns and a per-row actions menu — compose the row menu from the row-actions pattern",
    "match": [
     "data table",
     "transactions table",
@@ -3271,6 +4425,13 @@
     },
     "slots": {
      "body": [
+      {
+       "component": "TableCaption",
+       "props": {
+        "detail": "{content:range}"
+       },
+       "content": "caption"
+      },
       {
        "component": "TableHead",
        "slots": {
@@ -3352,6 +4513,8 @@
    },
    "parameters": [],
    "content": {
+    "caption": "[what the table lists — its visible name]",
+    "range": "[the rows shown, e.g. Rows 1–50 of 1,204; focus moves here after a page change]",
     "date-label": "Date",
     "payee-label": "Payee",
     "amount-label": "Amount",
@@ -3363,7 +4526,7 @@
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Table\n  selectable={true}\n  sortable={true}\n>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell sortKey=\"date\">Date</TableHeaderCell>\n      <TableHeaderCell sortKey=\"payee\">Payee</TableHeaderCell>\n      <TableHeaderCell numeric={true} sortKey=\"amount\">Amount</TableHeaderCell>\n      <TableHeaderCell>[a visible \"Actions\" header — the column needs an accessible name, so never an empty th]</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow\n      rowId=\"row-id\"\n    >\n      <TableCell>[one row per record]</TableCell>\n      <TableCell>[the record's payee]</TableCell>\n      <TableCell numeric={true}>[numeric columns align right and use tabular figures]</TableCell>\n      <TableCell>[the row-actions menu — compose it from the row-actions pattern]</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
+   "preset": "<Table\n  selectable={true}\n  sortable={true}\n>\n  <TableCaption detail=\"[the rows shown, e.g. Rows 1–50 of 1,204; focus moves here after a page change]\">[what the table lists — its visible name]</TableCaption>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell sortKey=\"date\">Date</TableHeaderCell>\n      <TableHeaderCell sortKey=\"payee\">Payee</TableHeaderCell>\n      <TableHeaderCell numeric={true} sortKey=\"amount\">Amount</TableHeaderCell>\n      <TableHeaderCell>[a visible \"Actions\" header — the column needs an accessible name, so never an empty th]</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow\n      rowId=\"row-id\"\n    >\n      <TableCell>[one row per record]</TableCell>\n      <TableCell>[the record's payee]</TableCell>\n      <TableCell numeric={true}>[numeric columns align right and use tabular figures]</TableCell>\n      <TableCell>[the row-actions menu — compose it from the row-actions pattern]</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
   },
   {
    "id": "date-range-filter",
@@ -3613,9 +4776,85 @@
    "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"
   },
+  {
+   "id": "filter-form",
+   "intent": "Labelled filters above a list, submitted together with a Find button: a Toolbar rendered as a named form (as=\"form\", so Find and Enter submit — wire onSubmit), aligned to the start so every control sits on one line under its visible Field label and Find drops onto that line. A field's description or error line hangs below its control and moves nothing else; the error line is the Field's own, with its usual aria-describedby wiring — set error on the Field, not beside the row. Every label in the row must be one line: a label that wraps pushes its control off the shared line. Add IconSearch before the Find label. For filters that apply as they change, named without a visible label, use filter-toolbar instead; never name a control by its placeholder alone",
+   "match": [
+    "filter form",
+    "search form",
+    "labelled filters",
+    "filters with labels",
+    "find button",
+    "submit filters"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "props": {
+     "as": "form",
+     "align": "start",
+     "gap": 12,
+     "aria-label": "{content:form-label}"
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Field",
+       "slots": {
+        "label": [
+         "{content:text-label}"
+        ],
+        "body": [
+         {
+          "component": "Input",
+          "props": {
+           "size": 32
+          }
+         }
+        ]
+       }
+      },
+      {
+       "component": "Field",
+       "slots": {
+        "label": [
+         "{content:select-label}"
+        ],
+        "body": [
+         {
+          "component": "Select",
+          "props": {
+           "size": 32
+          }
+         }
+        ]
+       }
+      },
+      {
+       "component": "Button",
+       "props": {
+        "type": "submit",
+        "variant": "accent",
+        "size": 32
+       },
+       "content": "find-label"
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "form-label": "Filters",
+    "text-label": "[field name]",
+    "select-label": "[field name]",
+    "find-label": "Find"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toolbar\n  align=\"start\"\n  aria-label=\"Filters\"\n  as=\"form\"\n  gap={12}\n>\n  <Field\n    label=\"[field name]\"\n  >\n    <Input size={32} />\n  </Field>\n  <Field\n    label=\"[field name]\"\n  >\n    <Select size={32} />\n  </Field>\n  <Button size={32} type=\"submit\" variant=\"accent\">Find</Button>\n</Toolbar>\n"
+  },
   {
    "id": "filter-toolbar",
-   "intent": "Toolbar of filter controls: search, category select, active-filter tags — controls are named by aria-label/placeholder, not a visible label, so no Field (contrast table-pagination)",
+   "intent": "Toolbar of filter controls that apply as they change: search, category select, active-filter tags — controls are named by aria-label/placeholder, not a visible label, so no Field (contrast table-pagination). For filters with visible labels, submitted together with a Find button, use filter-form",
    "match": [
     "filter toolbar",
     "filter bar",
@@ -3658,6 +4897,261 @@
    "blocked": false,
    "preset": "<Toolbar>\n  <Input aria-label=\"Search transactions\" placeholder=\"Search transactions\" type=\"search\" />\n  <Select aria-label=\"Category\" />\n  <Tag>[active filter]</Tag>\n</Toolbar>\n"
   },
+  {
+   "id": "form-feedback",
+   "intent": "A message above a form after a rejected submission, holding the reason and a copyable identifier; not a live region — the application speaks it",
+   "match": [
+    "form error summary",
+    "submission failed",
+    "rejected form",
+    "error id",
+    "support reference"
+   ],
+   "compose": {
+    "component": "InlineAlert",
+    "props": {
+     "variant": "danger"
+    },
+    "slots": {
+     "title": [
+      "{content:title}"
+     ],
+     "body": [
+      "{content:message}",
+      {
+       "component": "CopyButton",
+       "props": {
+        "value": "{content:identifier}",
+        "label": "{content:copy-label}"
+       }
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "title": "[what was rejected]",
+    "message": "[why, and what to change]",
+    "identifier": "[the request or error id, for support]",
+    "copy-label": "Copy id"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<InlineAlert\n  title=\"[what was rejected]\"\n  variant=\"danger\"\n>\n  [why, and what to change]\n  <CopyButton label=\"Copy id\" value=\"[the request or error id, for support]\" />\n</InlineAlert>\n"
+  },
+  {
+   "id": "loading-table",
+   "intent": "A table whose rows are still loading — Skeleton lines in the cells, aria-busy on the body; the skeletons are hidden from assistive tech, the busy state is what it reads",
+   "match": [
+    "loading table",
+    "table skeleton",
+    "placeholder rows",
+    "loading state",
+    "busy table"
+   ],
+   "compose": {
+    "component": "Table",
+    "props": {
+     "aria-label": "{content:table-label}"
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "TableHead",
+       "slots": {
+        "body": [
+         {
+          "component": "TableRow",
+          "slots": {
+           "body": [
+            {
+             "component": "TableHeaderCell",
+             "content": "col-1"
+            },
+            {
+             "component": "TableHeaderCell",
+             "content": "col-2"
+            },
+            {
+             "component": "TableHeaderCell",
+             "content": "col-3"
+            }
+           ]
+          }
+         }
+        ]
+       }
+      },
+      {
+       "component": "TableBody",
+       "props": {
+        "aria-busy": "true"
+       },
+       "slots": {
+        "body": [
+         {
+          "component": "TableRow",
+          "slots": {
+           "body": [
+            {
+             "component": "TableCell",
+             "slots": {
+              "body": [
+               {
+                "component": "Skeleton"
+               }
+              ]
+             }
+            },
+            {
+             "component": "TableCell",
+             "slots": {
+              "body": [
+               {
+                "component": "Skeleton"
+               }
+              ]
+             }
+            },
+            {
+             "component": "TableCell",
+             "slots": {
+              "body": [
+               {
+                "component": "Skeleton"
+               }
+              ]
+             }
+            }
+           ]
+          }
+         }
+        ]
+       }
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "table-label": "[what the table lists], loading",
+    "col-1": "[first column]",
+    "col-2": "[second column]",
+    "col-3": "[third column]"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Table\n  aria-label=\"[what the table lists], loading\"\n>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>[first column]</TableHeaderCell>\n      <TableHeaderCell>[second column]</TableHeaderCell>\n      <TableHeaderCell>[third column]</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody\n    aria-busy=\"true\"\n  >\n    <TableRow>\n      <TableCell>\n        <Skeleton />\n      </TableCell>\n      <TableCell>\n        <Skeleton />\n      </TableCell>\n      <TableCell>\n        <Skeleton />\n      </TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
+  },
+  {
+   "id": "page-banner",
+   "intent": "A full-width, page-level message above the content, with a Refresh action; it is what the page shows, and announcing stays the application's (route the same event through the announcer)",
+   "match": [
+    "page banner",
+    "site-wide message",
+    "stale data",
+    "service notice",
+    "maintenance banner"
+   ],
+   "compose": {
+    "component": "Banner",
+    "props": {
+     "variant": "{param:variant}"
+    },
+    "slots": {
+     "title": [
+      "{content:title}"
+     ],
+     "body": [
+      "{content:message}"
+     ],
+     "action": [
+      {
+       "component": "Button",
+       "props": {
+        "variant": "ghost",
+        "size": 32
+       },
+       "content": "action-label"
+      }
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "variant",
+     "ask": "What kind of message is this?",
+     "options": [
+      "neutral",
+      "warning",
+      "danger",
+      "success"
+     ],
+     "default": "neutral"
+    }
+   ],
+   "content": {
+    "title": "[what changed, in a few words]",
+    "message": "[what it means for the user and what to do]",
+    "action-label": "Refresh"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Banner action={<Button size={32} variant=\"ghost\">Refresh</Button>} title=\"[what changed, in a few words]\" variant=\"neutral\">[what it means for the user and what to do]</Banner>\n"
+  },
+  {
+   "id": "required-field",
+   "intent": "A required field that says so in text, not by a glyph alone: a Field with required and requiredText around an Input, with a description",
+   "match": [
+    "required field",
+    "mandatory field",
+    "required in text",
+    "required label",
+    "(Required)"
+   ],
+   "compose": {
+    "component": "Field",
+    "props": {
+     "required": true,
+     "requiredText": "{content:required-text}"
+    },
+    "slots": {
+     "label": [
+      "{content:label}"
+     ],
+     "body": [
+      {
+       "component": "Input",
+       "props": {
+        "size": "{param:size}"
+       }
+      }
+     ],
+     "description": [
+      "{content:description}"
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "size",
+     "ask": "Control size?",
+     "options": [
+      32,
+      40
+     ],
+     "default": 32
+    }
+   ],
+   "content": {
+    "label": "[field name]",
+    "required-text": "(Required)",
+    "description": "[why it is needed]"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Field\n  description=\"[why it is needed]\"\n  label=\"[field name]\"\n  required={true}\n  requiredText=\"(Required)\"\n>\n  <Input size={32} />\n</Field>\n"
+  },
   {
    "id": "row-actions",
    "intent": "List or table row with an icon-only actions menu, including a destructive item — hand the destructive item's confirmation off to the destructive-confirm pattern",
@@ -4001,6 +5495,11 @@
     "tooltip": 1100
    }
   },
+  "focusRing": {
+   "width": 2,
+   "offset": 2,
+   "offsetInset": -2
+  },
   "scopes": {
    "space": [
     "gap"
@@ -4063,14 +5562,14 @@
    "Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.",
    "--psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).",
    "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.",
-   "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).",
+   "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).",
    "Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group."
   ],
   "states": {
    "hover": "L - 0.04",
    "active": "L - 0.08",
    "disabled": "element opacity 0.4 (keeps hue)",
-   "focus": "2px ring var(--psi-{component}-focus-ring)"
+   "focus": "outline: var(--psi-focus-ring-width) solid var(--psi-{component}-focus-ring) on :focus-visible, at --psi-focus-ring-offset (outside) or --psi-focus-ring-offset-inset (inside) — D82"
   },
   "typographyDefaults": {
    "body": "16-24-regular",
@@ -4802,6 +6301,11 @@
      "tooltip": 1100
     }
    },
+   "focusRing": {
+    "width": 2,
+    "offset": 2,
+    "offsetInset": -2
+   },
    "scopes": {
     "space": [
      "gap"