@handamade/psi-mcp 0.8.1 → 0.9.1

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.1",
+ "version": "0.9.1",
  "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",
@@ -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

@@ -3,24 +3,32 @@ const MAX_RESULTS = 20;
  * (~1.5k tokens)" (docs/superpowers/plans/2026-07-18-agent-access-plan.md),
  * asserted by __tests__/store.test.ts's "stays within the response budget". */
 const RESPONSE_BUDGET = 6000;
-/** Order the empty-query overview is filled in. Guidance first, catalog last,
- * because the two grow and cost very differently:
+/** How the empty-query overview divides its budget across kinds. Topics,
+ * patterns, and components grow and cost very differently:
  *
  *   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.
+ *              (the five required CSS imports) above all. Takes its full
+ *              cost, unconditionally.
  *   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
- *              rule an agent doesn't know exists.
+ *              rule an agent doesn't know exists. Reserved a floor of
+ *              `COMPONENT_FLOOR` items before patterns spend the remainder,
+ *              so catalog growth cannot starve them below the floor.
+ *   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) at a *derived*
+ *              per-call cap — the largest that lets every pattern fit
+ *              alongside topics and the component floor. The stored,
+ *              untrimmed brief is still what score() ranks against.
  *
- * Capping by item *count* (the previous scheme) evicted the tail, and since
- * components were emitted first the tail was always topics — so registering
- * D53's Menu components silently dropped eight topics including
- * `getting-started`. Filling by serialized *length* in this order instead
- * degrades only the component tail, which is the cheap thing to lose. */
-const OVERVIEW_KIND_ORDER = ["topic", "pattern", "component"];
+ * Previously the overview filled topics, then patterns, then components
+ * until the budget ran out, so whichever kind was filled last absorbed all
+ * catalog growth — three more patterns was enough to starve components from
+ * six down to four (D61). Allocating by kind first means catalog growth
+ * shortens pattern summaries instead of evicting items off the tail. */
+const COMPONENT_FLOOR = 8;
 const TOPIC_SUMMARIES = {
     variants: "Variant intent and typical use for all 8 flat variants",
     rules: "House rules: accent budget, sizing, color binding",
@@ -57,7 +65,53 @@ function patternSummary(p) {
         summary += `, blocked (gaps: ${p.gaps.join(", ")})`;
     return summary;
 }
+/** Most an overview pattern intro (intent + match phrases + parameter count)
+ * may cost. The effective limit is derived per-call (see the empty-query
+ * branch): patterns take whatever the budget leaves after topics and the
+ * component floor, so a growing catalog shortens summaries instead of
+ * evicting items (D61).
+ *
+ * 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_MAX = 120;
+/** 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, limit) {
+    const intro = truncateAtWord(`${p.intent} — ${p.match.join(", ")}, ${p.parameters.length} parameters`, 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. `limit` is derived per-call by the empty-query branch
+     * (D61), not a module constant, so a growing catalog shortens summaries
+     * instead of evicting items. */
+    function overviewBrief(b, limit) {
+        if (b.kind !== "pattern")
+            return b;
+        const pattern = patternsById.get(b.title);
+        if (!pattern)
+            return b;
+        return { ...b, summary: overviewPatternSummary(pattern, limit) };
+    }
     const briefs = [
         ...index.components.map((c) => ({
             id: `component:${c.name}`,
@@ -101,14 +155,25 @@ export function createStore(index) {
     function search(query) {
         const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
         if (terms.length === 0) {
-            // Overview: topics, then patterns, then as many components as the
-            // response budget still affords (tokens are discoverable via query).
-            // Filled by serialized length, not item count, so the thing that gets
-            // dropped is always the component tail — never the guidance surface.
-            const candidates = OVERVIEW_KIND_ORDER.flatMap((kind) => briefs.filter((b) => b.kind === kind));
-            const out = [];
-            for (const brief of candidates) {
-                out.push(brief);
+            // D61: allocate before filling. Topics take their full cost, components
+            // are reserved a floor, and patterns take the remainder via a derived
+            // cap — so catalog growth shortens summaries instead of evicting the
+            // tail. Whichever kind was filled last used to absorb all growth;
+            // that was the bug. (Tokens are omitted; they are discoverable via
+            // query.)
+            const topics = briefs.filter((b) => b.kind === "topic");
+            const patterns = briefs.filter((b) => b.kind === "pattern");
+            const components = briefs.filter((b) => b.kind === "component");
+            const reserve = JSON.stringify(components.slice(0, COMPONENT_FLOOR)).length;
+            const fits = (limit) => JSON.stringify([...topics, ...patterns.map((b) => overviewBrief(b, limit))]).length +
+                reserve <=
+                RESPONSE_BUDGET;
+            let limit = OVERVIEW_PATTERN_INTRO_MAX;
+            while (limit > 0 && !fits(limit))
+                limit -= 10;
+            const out = [...topics, ...patterns.map((b) => overviewBrief(b, limit))];
+            for (const component of components) {
+                out.push(component);
                 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.1",
+  "version": "0.9.1",
   "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.8.1",
-    "@handamade/psi-react": "0.8.1"
+    "@handamade/psi-tokens": "0.9.1",
+    "@handamade/psi-react": "0.9.1"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"