@handamade/psi-mcp 0.8.0 → 0.9.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, 4 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 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.
 
 ## Connect
 

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.8.0",
+ "version": "0.9.0",
  "themes": [
   "light",
   "dark",
@@ -68,6 +68,13 @@
    "name": "IconButton",
    "description": "Square icon-only button; same variant/size/href contract as Button. Give it an accessible name (`aria-label`).",
    "props": [
+    {
+     "name": "aria-label",
+     "type": "string",
+     "required": true,
+     "default": null,
+     "description": "Accessible name for the icon-only control. Required: an IconButton has\nno text to name it, so omitting this ships an unnameable button (D60).\nIf you also pass `aria-labelledby`, that wins per the accname algorithm."
+    },
     {
      "name": "variant",
      "type": "\"accent\" | \"neutral\" | \"ghost\" | \"danger\"",
@@ -119,7 +126,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| `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- 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| `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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "Card",
@@ -204,6 +211,13 @@
    "name": "Input",
    "description": "Single-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).",
    "props": [
+    {
+     "name": "type",
+     "type": "\"number\" | \"text\" | \"search\" | \"email\" | \"tel\" | \"url\" | \"password\" | \"date\"",
+     "required": false,
+     "default": "text",
+     "description": "Input type."
+    },
     {
      "name": "size",
      "type": "24 | 32 | 40 | 48",
@@ -241,7 +255,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| `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- 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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "Select",
@@ -717,7 +731,7 @@
      "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."
+     "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",
@@ -778,7 +792,7 @@
      "order": 2
     }
    ],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Menu\n\nAction menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showPopover()/hidePopover(). |\n| `onClose` | `(reason: \"item-select\" \\| \"esc\" \\| \"outside\") => void` | — | yes | Called when a dismissal is *requested*; the consumer flips `open`. Menu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays open until `open` becomes false (D50). `\"outside\"` is the one exception: light dismiss is performed by the browser before it tells us, so by the time that reason is reported the popover is already closed. Flipping `open` to false is still required, to keep React's state in step. |\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| `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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Menu\n\nAction menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `open` | `boolean` | — | yes | Controlled open state; syncs to showPopover()/hidePopover(). |\n| `onClose` | `(reason: \"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| `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- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
    "name": "MenuItem",
@@ -2316,6 +2330,216 @@
   }
  ],
  "patterns": [
+  {
+   "id": "action-feedback",
+   "intent": "Transient confirmation after a completed action, with an optional undo affordance",
+   "match": [
+    "toast",
+    "snackbar",
+    "action feedback",
+    "confirmation message",
+    "undo toast"
+   ],
+   "compose": {
+    "component": "Toast",
+    "props": {
+     "variant": "{param:variant}"
+    },
+    "slots": {
+     "body": [
+      "{content:message}"
+     ],
+     "action": [
+      {
+       "component": "Button",
+       "props": {
+        "variant": "ghost"
+       },
+       "content": "undo-label"
+      }
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "variant",
+     "ask": "What kind of outcome is being confirmed?",
+     "options": [
+      "success",
+      "danger",
+      "neutral"
+     ],
+     "default": "success"
+    }
+   ],
+   "content": {
+    "message": "[what just happened]",
+    "undo-label": "Undo"
+   },
+   "gaps": [
+    "Toast"
+   ],
+   "blocked": true,
+   "preset": null
+  },
+  {
+   "id": "bulk-action-bar",
+   "intent": "Bar that appears when table rows are selected: selection count, bulk actions, and a clear-selection control",
+   "match": [
+    "bulk actions",
+    "selection bar",
+    "batch actions",
+    "selected rows toolbar"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "props": {
+     "gap": 12
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Tag",
+       "props": {
+        "variant": "accent",
+        "subtle": true
+       },
+       "content": "count-label"
+      },
+      {
+       "component": "Button",
+       "props": {
+        "variant": "neutral"
+       },
+       "content": "export-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": "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",
+   "match": [
+    "data table",
+    "transactions table",
+    "sortable table",
+    "records table",
+    "list of transactions"
+   ],
+   "compose": {
+    "component": "Table",
+    "props": {
+     "selectable": true,
+     "sortable": true
+    },
+    "slots": {
+     "head": [
+      "{content:columns-note}"
+     ],
+     "body": [
+      "{content:rows-note}"
+     ]
+    }
+   },
+   "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]"
+   },
+   "gaps": [
+    "Table"
+   ],
+   "blocked": true,
+   "preset": null
+  },
+  {
+   "id": "date-range-filter",
+   "intent": "From/to date pair for narrowing a dated list — native date inputs, no calendar widget",
+   "match": [
+    "date range filter",
+    "from to date",
+    "date filter",
+    "period filter",
+    "filter by date"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "props": {
+     "gap": 12
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Field",
+       "slots": {
+        "label": [
+         "{content:from-label}"
+        ],
+        "body": [
+         {
+          "component": "Input",
+          "props": {
+           "type": "date",
+           "size": 32
+          }
+         }
+        ]
+       }
+      },
+      {
+       "component": "Field",
+       "slots": {
+        "label": [
+         "{content:to-label}"
+        ],
+        "body": [
+         {
+          "component": "Input",
+          "props": {
+           "type": "date",
+           "size": 32
+          }
+         }
+        ]
+       }
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "from-label": "From",
+    "to-label": "To"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toolbar\n  gap={12}\n>\n  <Field\n    label=\"From\"\n  >\n    <Input size={32} type=\"date\" />\n  </Field>\n  <Field\n    label=\"To\"\n  >\n    <Input size={32} type=\"date\" />\n  </Field>\n</Toolbar>\n"
+  },
   {
    "id": "destructive-confirm",
    "intent": "Dialog confirming a destructive action",
@@ -2375,6 +2599,108 @@
    "blocked": false,
    "preset": "<Dialog\n  footer={<>\n    <Button size={32} variant=\"ghost\">Cancel</Button>\n    <Button size={32} variant=\"danger\">[verb the object]</Button>\n  </>}\n  title=\"[Delete the object?]\"\n>\n  [what is permanently lost]\n</Dialog>\n"
   },
+  {
+   "id": "detail-drawer",
+   "intent": "Side sheet showing one record's detail, opened from a table row, with its primary actions in a footer",
+   "match": [
+    "detail drawer",
+    "side sheet",
+    "row detail",
+    "slide-over",
+    "record detail panel"
+   ],
+   "compose": {
+    "component": "Drawer",
+    "props": {
+     "side": "{param:side}"
+    },
+    "slots": {
+     "title": [
+      "{content:title}"
+     ],
+     "body": [
+      "{content:body-note}"
+     ],
+     "footer": [
+      {
+       "component": "Button",
+       "props": {
+        "variant": "accent"
+       },
+       "content": "primary-label"
+      },
+      {
+       "component": "Button",
+       "props": {
+        "variant": "neutral"
+       },
+       "content": "dismiss-label"
+      }
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "side",
+     "ask": "Which edge should the drawer open from?",
+     "options": [
+      "end",
+      "start"
+     ],
+     "default": "end"
+    }
+   ],
+   "content": {
+    "title": "[record title]",
+    "body-note": "[key-value summary of the selected record]",
+    "primary-label": "Save",
+    "dismiss-label": "Close"
+   },
+   "gaps": [
+    "Drawer"
+   ],
+   "blocked": true,
+   "preset": null
+  },
+  {
+   "id": "empty-state",
+   "intent": "Placeholder shown when a list has no results, distinguishing an empty filter from an empty dataset",
+   "match": [
+    "empty state",
+    "no results",
+    "nothing here",
+    "zero state",
+    "no data"
+   ],
+   "compose": {
+    "component": "Panel",
+    "props": {
+     "padding": 24
+    },
+    "slots": {
+     "body": [
+      "{content:headline}",
+      "{content:explanation}",
+      {
+       "component": "Button",
+       "props": {
+        "variant": "neutral"
+       },
+       "content": "reset-label"
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "headline": "[nothing matches these filters]",
+    "explanation": "[say whether the dataset is empty or the filters are too narrow]",
+    "reset-label": "Clear filters"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Panel\n  padding={24}\n>\n  [nothing matches these filters]\n  [say whether the dataset is empty or the filters are too narrow]\n  <Button variant=\"neutral\">Clear filters</Button>\n</Panel>\n"
+  },
   {
    "id": "filter-toolbar",
    "intent": "Toolbar of filter controls: search, category select, active-filter tags",
@@ -2411,7 +2737,7 @@
   },
   {
    "id": "row-actions",
-   "intent": "List or table row with a labelled actions menu, including a destructive item — hand the destructive item's confirmation off to the destructive-confirm pattern. The trigger is a text Button, not an icon-only kebab: IconButton cannot carry an accessible name through the manifest, so it is not composable in a pattern yet",
+   "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",
    "match": [
     "row actions",
     "per-row actions",
@@ -2428,11 +2754,12 @@
     "slots": {
      "trigger": [
       {
-       "component": "Button",
+       "component": "IconButton",
        "props": {
-        "variant": "ghost"
+        "variant": "ghost",
+        "aria-label": "{content:trigger-label}"
        },
-       "content": "trigger-label"
+       "content": "trigger-icon"
       }
      ],
      "body": [
@@ -2470,13 +2797,14 @@
    ],
    "content": {
     "trigger-label": "Actions",
+    "trigger-icon": "[icon]",
     "edit-label": "Edit",
     "duplicate-label": "Duplicate",
     "delete-label": "Delete"
    },
    "gaps": [],
    "blocked": false,
-   "preset": "<Menu\n  aria-label=\"Actions\"\n  placement=\"bottom-end\"\n  trigger={<Button variant=\"ghost\">Actions</Button>}\n>\n  <MenuItem>Edit</MenuItem>\n  <MenuItem>Duplicate</MenuItem>\n  <MenuSeparator />\n  <MenuItem variant=\"danger\">Delete</MenuItem>\n</Menu>\n"
+   "preset": "<Menu\n  aria-label=\"Actions\"\n  placement=\"bottom-end\"\n  trigger={<IconButton aria-label=\"Actions\" variant=\"ghost\">[icon]</IconButton>}\n>\n  <MenuItem>Edit</MenuItem>\n  <MenuItem>Duplicate</MenuItem>\n  <MenuSeparator />\n  <MenuItem variant=\"danger\">Delete</MenuItem>\n</Menu>\n"
   },
   {
    "id": "settings-form-row",
@@ -2517,6 +2845,142 @@
    "gaps": [],
    "blocked": false,
    "preset": "<Field\n  description=\"[one-line consequence of the setting]\"\n  group={true}\n  label=\"[setting name]\"\n>\n  <Switch>[what turning it on does]</Switch>\n</Field>\n"
+  },
+  {
+   "id": "summary-tiles",
+   "intent": "Row of headline figures above a ledger — balances or totals, one Card per figure",
+   "match": [
+    "summary tiles",
+    "stat cards",
+    "kpi row",
+    "balance cards",
+    "totals row"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "props": {
+     "gap": 16
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Card",
+       "props": {
+        "variant": "stacked"
+       },
+       "content": "tile-note"
+      },
+      {
+       "component": "Card",
+       "props": {
+        "variant": "stacked"
+       },
+       "content": "tile-note"
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "tile-note": "[label above, figure below]"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Toolbar\n  gap={16}\n>\n  <Card variant=\"stacked\">[label above, figure below]</Card>\n  <Card variant=\"stacked\">[label above, figure below]</Card>\n</Toolbar>\n"
+  },
+  {
+   "id": "tabbed-workspace",
+   "intent": "Tab set switching between sibling views of the same workspace, such as accounts or saved filters",
+   "match": [
+    "tabs",
+    "tabbed view",
+    "switch between accounts",
+    "tab bar",
+    "segmented views"
+   ],
+   "compose": {
+    "component": "Tabs",
+    "props": {
+     "orientation": "{param:orientation}"
+    },
+    "slots": {
+     "list": [
+      "{content:tabs-note}"
+     ],
+     "panels": [
+      "{content:panels-note}"
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "orientation",
+     "ask": "How should the tab list be laid out?",
+     "options": [
+      "horizontal",
+      "vertical"
+     ],
+     "default": "horizontal"
+    }
+   ],
+   "content": {
+    "tabs-note": "[one tab per view; keep labels to one or two words]",
+    "panels-note": "[one panel per tab, in the same order]"
+   },
+   "gaps": [
+    "Tabs"
+   ],
+   "blocked": true,
+   "preset": null
+  },
+  {
+   "id": "table-pagination",
+   "intent": "Page-size selector and page range control beneath a data table",
+   "match": [
+    "pagination",
+    "table pagination",
+    "page controls",
+    "rows per page",
+    "paging"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "props": {
+     "gap": 12
+    },
+    "slots": {
+     "body": [
+      {
+       "component": "Field",
+       "slots": {
+        "label": [
+         "{content:page-size-label}"
+        ],
+        "body": [
+         {
+          "component": "Select",
+          "props": {
+           "size": 32
+          }
+         }
+        ]
+       }
+      },
+      {
+       "component": "Pagination"
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "page-size-label": "Rows per page"
+   },
+   "gaps": [
+    "Pagination"
+   ],
+   "blocked": true,
+   "preset": null
   }
  ],
  "scales": {

package/dist/store.js

@@ -9,7 +9,11 @@ const RESPONSE_BUDGET = 6000;
  *   topics   — a fixed, slow-growing set of terse briefs (~90 chars each).
  *              Carries the rules an agent cannot guess, `getting-started`
  *              (the five required CSS imports) above all.
- *   patterns — a handful of composition recipes, moderately sized.
+ *   patterns — composition recipes; their stored summaries carry match
+ *              phrases for keyword ranking and can run long, so the
+ *              overview projects a trimmed copy (see overviewBrief) capped
+ *              near topic size — the stored, untrimmed brief is still what
+ *              score() ranks against.
  *   components — verbose (up to 220 chars each) and the only axis that grows
  *              with every release. Also the axis a keyword query recovers
  *              best: search("menu") finds Menu; no query re-derives a house
@@ -57,7 +61,52 @@ function patternSummary(p) {
         summary += `, blocked (gaps: ${p.gaps.join(", ")})`;
     return summary;
 }
+/** Overview-only cap on the *intro* portion of a pattern summary (intent +
+ * match phrases + parameter count), comparable to a topic brief (~100
+ * bytes). The stored `Brief.summary` built by patternSummary() above stays
+ * full-length — score() reads it for keyword ranking (the match phrases are
+ * what let "delete confirmation" find destructive-confirm) — so this only
+ * shapes a copy used when search("") projects the overview list.
+ *
+ * The `, blocked (gaps: …)` tail is never subject to this cap: it is the
+ * backlog signal this cycle exists to publish, and patternSummary() puts it
+ * at the END of the string — a length-based slice of the assembled summary
+ * would silently drop it for every one of the 13 patterns (all longer than
+ * 120 chars), which is exactly the bug this trims to avoid. So the overview
+ * projects a pattern's summary from the underlying PatternEntry directly:
+ * trim the intro, then always append the tail. */
+const OVERVIEW_PATTERN_INTRO_LIMIT = 100;
+/** Trims `s` to at most `limit` chars, backing off to the last word boundary
+ * and marking the cut with an ellipsis — never a mid-word fragment that
+ * could read as a complete (if coincidental) match phrase. */
+function truncateAtWord(s, limit) {
+    if (s.length <= limit)
+        return s;
+    const cut = s.slice(0, limit);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${lastSpace > 0 ? cut.slice(0, lastSpace) : cut}…`;
+}
+function overviewPatternSummary(p) {
+    const intro = truncateAtWord(`${p.intent} — ${p.match.join(", ")}, ${p.parameters.length} parameters`, OVERVIEW_PATTERN_INTRO_LIMIT);
+    return p.blocked ? `${intro}, blocked (gaps: ${p.gaps.join(", ")})` : intro;
+}
 export function createStore(index) {
+    const patternsById = new Map(index.patterns.map((p) => [p.id, p]));
+    /** Overview-only projection: returns `b` unchanged for every kind except
+     * pattern, where it re-derives the summary from the underlying
+     * `PatternEntry` (via `overviewPatternSummary`) rather than slicing the
+     * already-assembled, full-length `Brief.summary` — so the `blocked (gaps:
+     * …)` tail always survives the overview's trim. Always a shallow copy for
+     * patterns: the stored brief kept in `briefs` (and used by score()) is
+     * never mutated. */
+    function overviewBrief(b) {
+        if (b.kind !== "pattern")
+            return b;
+        const pattern = patternsById.get(b.title);
+        if (!pattern)
+            return b;
+        return { ...b, summary: overviewPatternSummary(pattern) };
+    }
     const briefs = [
         ...index.components.map((c) => ({
             id: `component:${c.name}`,
@@ -108,7 +157,7 @@ export function createStore(index) {
             const candidates = OVERVIEW_KIND_ORDER.flatMap((kind) => briefs.filter((b) => b.kind === kind));
             const out = [];
             for (const brief of candidates) {
-                out.push(brief);
+                out.push(overviewBrief(brief));
                 if (JSON.stringify(out).length > RESPONSE_BUDGET) {
                     out.pop();
                     break;

package/llms.txt

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-mcp",
-  "version": "0.8.0",
+  "version": "0.9.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-react": "0.8.0",
-    "@handamade/psi-tokens": "0.8.0"
+    "@handamade/psi-tokens": "0.9.0",
+    "@handamade/psi-react": "0.9.0"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"