@handamade/psi-mcp 0.9.1 → 0.11.0

package/README.md

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

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.9.1",
+ "version": "0.11.0",
  "themes": [
   "light",
   "dark",
@@ -481,6 +481,13 @@
      "default": null,
      "description": "Label text."
     },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Accessible name when there is no visible label — a table's row-selection\ncheckbox, say. Optional, unlike IconButton's required form (D60): a\nlabelled checkbox is still the common case."
+    },
     {
      "name": "ref",
      "type": "Ref<HTMLInputElement>",
@@ -497,7 +504,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| `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- 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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "Switch",
@@ -829,6 +836,412 @@
    "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- 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 when a header's sort control is activated. Optional in the type\nbecause `sortable` may be false; a discriminated union expressing the real\ncontract does not survive docgen's flat prop extraction, which would strip\nthese 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": "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": [
+       "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 when a header's sort control is activated. 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| `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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+  },
+  {
+   "name": "TableHead",
+   "description": "`<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.",
+   "props": [
+    {
+     "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# 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| `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- 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.",
+   "props": [
+    {
+     "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# TableBody\n\n`<tbody>` wrapper.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\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- 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": "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# 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| `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- 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": "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# 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| `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- 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.",
+   "props": [
+    {
+     "name": "numeric",
+     "type": "boolean",
+     "required": false,
+     "default": null,
+     "description": "Right-aligns and renders tabular figures (D62)."
+    },
+    {
+     "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# 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| `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- 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."
+    },
+    {
+     "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. |\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- 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.",
+   "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 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": "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 underlying `<div>`."
+    }
+   ],
+   "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. 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- 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.",
+   "props": [
+    {
+     "name": "placement",
+     "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+     "required": false,
+     "default": "bottom-end",
+     "description": "Corner the stack occupies."
+    },
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": false,
+     "default": "Notifications",
+     "description": "Accessible name for the region."
+    },
+    {
+     "name": "children",
+     "type": "ReactNode",
+     "required": true,
+     "default": null,
+     "description": "The toast stack — `Toast` elements, routed to a live wrapper by variant."
+    },
+    {
+     "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 region element."
+    }
+   ],
+   "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- 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.",
+   "props": [
+    {
+     "name": "limit",
+     "type": "number",
+     "required": false,
+     "default": 3,
+     "description": "Max simultaneous toasts; the oldest is evicted first."
+    },
+    {
+     "name": "duration",
+     "type": "number",
+     "required": false,
+     "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": true,
+     "default": null,
+     "description": "The subtree that may call `useToast()`. The region is rendered alongside it."
+    }
+   ],
+   "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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   }
  ],
  "tokens": [
@@ -2366,6 +2779,7 @@
      "ask": "What kind of outcome is being confirmed?",
      "options": [
       "success",
+      "warning",
       "danger",
       "neutral"
      ],
@@ -2376,11 +2790,9 @@
     "message": "[what just happened]",
     "undo-label": "Undo"
    },
-   "gaps": [
-    "Toast"
-   ],
-   "blocked": true,
-   "preset": null
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toast action={<Button variant=\"ghost\">Undo</Button>} variant=\"success\">[what just happened]</Toast>\n"
   },
   {
    "id": "bulk-action-bar",
@@ -2458,24 +2870,90 @@
      "sortable": true
     },
     "slots": {
-     "head": [
-      "{content:columns-note}"
-     ],
      "body": [
-      "{content:rows-note}"
+      {
+       "component": "TableHead",
+       "slots": {
+        "body": [
+         {
+          "component": "TableRow",
+          "slots": {
+           "body": [
+            {
+             "component": "TableHeaderCell",
+             "props": {
+              "sortKey": "date"
+             },
+             "content": "date-label"
+            },
+            {
+             "component": "TableHeaderCell",
+             "props": {
+              "sortKey": "payee"
+             },
+             "content": "payee-label"
+            },
+            {
+             "component": "TableHeaderCell",
+             "props": {
+              "sortKey": "amount",
+              "numeric": true
+             },
+             "content": "amount-label"
+            }
+           ]
+          }
+         }
+        ]
+       }
+      },
+      {
+       "component": "TableBody",
+       "slots": {
+        "body": [
+         {
+          "component": "TableRow",
+          "props": {
+           "rowId": "row-id"
+          },
+          "slots": {
+           "body": [
+            {
+             "component": "TableCell",
+             "content": "date-cell"
+            },
+            {
+             "component": "TableCell",
+             "content": "payee-cell"
+            },
+            {
+             "component": "TableCell",
+             "props": {
+              "numeric": true
+             },
+             "content": "amount-cell"
+            }
+           ]
+          }
+         }
+        ]
+       }
+      }
      ]
     }
    },
    "parameters": [],
    "content": {
-    "columns-note": "[one header cell per column; numeric columns align right]",
-    "rows-note": "[one row per record; put the row-actions menu in the last cell]"
+    "date-label": "Date",
+    "payee-label": "Payee",
+    "amount-label": "Amount",
+    "date-cell": "[one row per record]",
+    "payee-cell": "[put the row-actions menu in the last cell]",
+    "amount-cell": "[numeric columns align right and use tabular figures]"
    },
-   "gaps": [
-    "Table"
-   ],
-   "blocked": true,
-   "preset": null
+   "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    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow\n      rowId=\"row-id\"\n    >\n      <TableCell>[one row per record]</TableCell>\n      <TableCell>[put the row-actions menu in the last cell]</TableCell>\n      <TableCell numeric={true}>[numeric columns align right and use tabular figures]</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
   },
   {
    "id": "date-range-filter",
@@ -2976,11 +3454,9 @@
    "content": {
     "page-size-label": "Rows per page"
    },
-   "gaps": [
-    "Pagination"
-   ],
-   "blocked": true,
-   "preset": null
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toolbar\n  gap={12}\n>\n  <Field\n    label=\"Rows per page\"\n  >\n    <Select size={32} />\n  </Field>\n  <Pagination />\n</Toolbar>\n"
   }
  ],
  "scales": {
@@ -3040,6 +3516,7 @@
     "gutterNarrow": 24
    },
    "zIndex": {
+    "sticky": 1,
     "nav": 100,
     "overlay": 1000,
     "tooltip": 1100
@@ -3171,6 +3648,7 @@
   },
   "recipes": {
    "mediaTint": "Apply .psi-media-tint to media elements; the brand defines --psi-media-tint (D35). Hover/focus reveals true color over --psi-duration-450 --psi-ease-soft.",
+   "tabularNumerals": "Apply .psi-tabular to numeric content for fixed-width digits; --psi-font-variant-numeric is tabular-nums (D62). Table's numeric columns bind the token directly rather than via the utility class.",
    "sectionHeader": "SectionHeader ships as a recipe, not a component (v1.2 non-goal): baseline-aligned flex row — mono annotation (--psi-text-mono-14-20-regular, --psi-fg-accent) + h2 (.psi-display-32-32-extrabold) + optional trailing meta, border-bottom 1px var(--psi-border-faint), padding-bottom var(--psi-space-20)."
   },
   "tags": {
@@ -3320,6 +3798,7 @@
      "gutterNarrow": 24
     },
     "zIndex": {
+     "sticky": 1,
      "nav": 100,
      "overlay": 1000,
      "tooltip": 1100

package/package.json

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