@grampro/kit 2.4.3 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,174 @@
 # Changelog
 
+## 2.5.0
+
+### Added
+
+**Every prop this library declares now carries a description.**
+
+117 did not, and the passports are what an agent reads instead of the
+source, so an undescribed prop is one it has to guess at. The worst of them
+were not obscure: `DataGrid`'s `columns` and `data` had no description at
+all, and `label`, `error`, `description` and `onChange` were bare on
+Checkbox, Switch and RadioGroup.
+
+Where reading the code turned up something a type cannot say, that is in
+the description now:
+
+- `onCellEdit` fires only when the value actually changed, and returning a
+  promise makes the edit optimistic - the cell reverts and shows the
+  rejection's message if it fails, so reject with the reason you want read.
+- `CheckboxGroup`'s values accumulate in the order they were checked, not
+  the order the options are declared, so sort before comparing selections.
+- `Checkbox.onCheckedChange` never fires with `"indeterminate"`.
+- `FileUploader` treats name, size and last-modified time as a file's
+  identity when rejecting duplicates.
+- `NumberInput`'s `min` and `max` apply on blur rather than per keystroke,
+  unless `clampBehavior` says otherwise.
+- `DatePicker.onChange` always hands back a `Date` at local midnight, even
+  though `value` accepts a string or a number.
+**The Figma token belongs to your operating system now, not to a file in
+your repository.**
+
+```bash
+npx @grampro/kit secret set figma
+```
+
+It prompts with the echo off and stores the token where the platform keeps
+credentials: the Data Protection API on Windows, the keychain on macOS, the
+Secret Service on Linux. Anywhere else it falls back to a 0600 file in your
+config directory and says so rather than implying otherwise. The value is
+never passed as an argument, because arguments land in shell history and in
+every process listing on the machine; pipe it instead if you need to script
+it.
+
+`secret list` shows what is stored, masked, and names the backend. `secret
+remove figma` deletes it.
+
+The old `.env` route still works, so upgrading breaks nothing, but reading
+from one now prints a note telling you to move it. A credential sitting in a
+working tree is one `git add -A` away from being published, which is the
+whole reason for the change.
+
+**`mcp install` writes the configuration for you.**
+
+```bash
+npx @grampro/kit mcp install            # every agent it knows
+npx @grampro/kit mcp install --for codex
+```
+
+Claude Code, Codex and Cursor each take the same stdio server and differ
+only in where the configuration lives and what format it is in. This writes
+`.mcp.json`, `.codex/config.toml` and `.cursor/mcp.json` respectively,
+merging into whatever is already there and leaving other servers alone.
+
+It is worth preferring over editing those files by hand, which is how this
+goes wrong: PowerShell's `Out-File -Encoding utf8` adds a byte-order mark,
+and every JSON parser then rejects the file with an error naming the first
+character and explaining nothing. This writes UTF-8 without a BOM and with
+LF endings, and strips a BOM from a file that already has one.
+
+It writes to the project root — the nearest folder above you with a `.git`
+or a `package.json` — and prints which one it chose. An agent reads these
+files from the folder it has open, so running the command from a
+subdirectory would have written somewhere nothing ever looks while still
+reporting success.
+
+It also now says what has to happen next, because writing the file is not
+the same as loading the server. A `.mcp.json` server is project-scoped and
+Claude Code asks before trusting one, so it sits at `Pending approval` until
+you agree; and the configuration is read when a session starts, so an editor
+window that was already open sees nothing until it reloads. Installing at
+user scope — `claude mcp add -s user grampro -- npx -y @grampro/kit mcp` —
+skips both, at the cost of not being shareable through a commit.
+
+### Changed
+
+**Reading a Figma design no longer downloads the whole file.**
+
+Figma charges for file reads by the size of the response, and the frame
+listing was fetching the entire document — 710 KB on the file this was
+tested against — to answer a question about one screen. Two of those in a
+row is what earns a 429, and the lockout is long: a `Retry-After` of 395274
+was observed on a single token.
+
+The listing now uses `depth=1`, which returns the document's outline rather
+than its contents, and the chosen frame is fetched by id. A URL that already
+carries a `node-id` — what Figma copies when you right-click a frame — goes
+straight there in one call. Responses are still held for five minutes, so
+the usual list-then-read flow costs one outline and one frame.
+
+If a token is already rate limited, the Figma plugin export route still
+works; it reads the scene graph from inside Figma and never calls the API.
+
+**The MCP server starts in about the time an empty Node process takes.**
+
+An agent spawns the server once per session, and it was loading the CLI's
+own dependencies first — `fs-extra` and `yargs`, roughly 70ms, and of no use
+to a JSON-RPC loop. The `mcp` command is now routed before they load.
+
+The passports are also indexed on the first question rather than re-read
+from disk for each one.
+
+### Fixed
+
+**`Select`'s `closeOnSelect` was documented backwards, in both directions.**
+Its description read "Keep the list open after choosing. Default false."
+while the code defaults it to `true` and closing is what the prop does. An
+agent reading that passport would have had both the behaviour and the
+default inverted - the failure mode that makes a wrong description worse
+than a missing one. MultiSelect's was already right.
+
+**Description coverage was measured against a denominator nobody could
+move.** It counted every prop, including the HTML and ARIA attributes that
+arrive through `extends ButtonHTMLAttributes` - 390 of the 507 undescribed
+props were those. So Button sat at 31% with its entire own API documented
+bar one prop, and eleven components stayed under the 40% threshold with
+nothing left to write. A gate that cannot be satisfied by doing the work it
+asks for gets ignored.
+
+It now measures the props the library authors, excluding inherited
+attributes and the handful whose meaning is library-wide (`className`,
+`style`, `ref` and friends) rather than restating them 27 times. On that
+measure the library is at 87% and the weakest component at 75%, so the
+threshold moves from 40 to 75 - a floor rather than an aspiration.
+**The rate-limit message no longer promises that waiting a minute will
+help.** It said to try again shortly, which is wrong for a cost-based limit
+whose window runs to tens of minutes or longer. It now passes Figma's own
+`Retry-After` through as given, without asserting a unit — the value has
+been seen in a range where seconds and milliseconds differ by three orders
+of magnitude — and points at the plugin route, which cannot be rate limited.
+
+## 2.4.4
+
+### Added
+
+**An MCP server, so an agent can ask about a component instead of recalling
+it.**
+
+```bash
+npx @grampro/kit mcp
+```
+
+Seven tools: `list_components`, `get_component`, `get_example`,
+`get_guidance`, `figma_frame`, `install_component` and `validate_usage`. The
+catalogue is 280 KB of passports and a page needs two or three components,
+which is the argument for answering on demand rather than pasting a document
+into the prompt.
+
+`validate_usage` is the one that earns its place. A page written from
+passports alone compiled on the first attempt apart from a single prop the
+model had remembered from elsewhere — every type, union value and handler
+signature the passports carried came out right. So the remaining failure
+mode is invention, and that is what this checks.
+
+No dependencies: MCP is newline-delimited JSON-RPC over stdio, and a server
+shipped inside a library every consumer installs should not drag an SDK
+along with it.
+
+Marked beta — the tools work and are tested, but their names and shapes may
+change.
+
 ## 2.4.3
 
 ### Fixed

package/README.md

@@ -90,6 +90,18 @@ In this repository:
 | [`docs/grid-agent-evaluation.md`](docs/grid-agent-evaluation.md) | the 230-case corpus and how a model gets measured against it |
 | [`docs/agent-native-architecture.md`](docs/agent-native-architecture.md) | where this is going, and which parts are still proposal |
 
+## MCP server (beta)
+
+For agents that speak MCP, the catalogue is also served on demand:
+
+```bash
+claude mcp add grampro -- npx -y @grampro/kit mcp
+```
+
+It reads a Figma design, installs what it needs, answers what exists, each component's full contract, working examples, and
+whether the JSX an agent just wrote actually matches the component it used.
+No dependencies, no configuration. See `tools/mcp/README.md`.
+
 ## Agent skill
 
 Install the skill once per project so a coding agent uses these components

package/index.cjs

@@ -1,5 +1,24 @@
 #!/usr/bin/env node
 
+/*
+ * The MCP server starts before the CLI does, and deliberately.
+ *
+ * An agent spawns the server once per session, and this file's own
+ * dependencies — fs-extra and yargs — cost about 70ms to load and are of no
+ * use to a JSON-RPC loop. Routing here first takes the server's start-up down
+ * to roughly what an empty Node process costs. A top-level `return` is valid
+ * in CommonJS, where a module body is already wrapped in a function.
+ *
+ * Only bare `mcp` is the server. Anything with a word after it — `install`,
+ * or a misspelling of it — is the CLI's business and falls through, so that a
+ * typo gets an answer instead of silently becoming a server waiting on stdin.
+ */
+if (process.argv[2] === "mcp" && !process.argv.slice(3).some((arg) => !arg.startsWith("-"))) {
+  // From here stdout carries JSON-RPC; nothing else may write to it.
+  require("./tools/mcp/server.cjs").main();
+  return;
+}
+
 const fs = require("fs-extra");
 const path = require("path");
 const crypto = require("crypto");
@@ -1171,7 +1190,7 @@ const validateComponents = (components, beta = false) => {
  * projects a week install this; breaking their scripts to tidy an argument
  * parser is not a trade worth making.
  */
-const COMMANDS = new Set(["add", "list", "skill", "passport"]);
+const COMMANDS = new Set(["add", "list", "skill", "passport", "mcp", "secret"]);
 
 /**
  * Flags that take a separate value, so the token after one is that value and
@@ -1244,7 +1263,7 @@ const main = async () => {
     })
     .option("for", {
       describe:
-        "With skill: which agents to write adapters for (claude, codex, antigravity, or none)",
+        "With skill or mcp install: which agents (claude, codex, antigravity, cursor, all)",
       type: "string",
     })
     .option("passport", {
@@ -1274,6 +1293,10 @@ const main = async () => {
     .example("$0 passport --check", "Fail if a passport is stale (CI)")
     .example("$0 add Select --legacy", "Install from the 1.x set")
     .example("$0 add Button --dest app/ui", "Choose where they go")
+    .example("$0 mcp", "Serve the catalogue to a coding agent over MCP")
+    .example("$0 mcp install", "Register the MCP server with every agent found")
+    .example("$0 mcp install --for codex", "Only write the Codex config")
+    .example("$0 secret set figma", "Store a Figma token in the OS credential store")
     .example("$0 -i", "Interactive selection")
     .help().argv;
 
@@ -1291,6 +1314,25 @@ const main = async () => {
     );
   }
 
+  if (parsed && parsed.command === "mcp") {
+    // Bare `mcp` never reaches this far: it is handled at the top of the file,
+    // before the CLI's dependencies load. What arrives here is `mcp install`,
+    // and anything else is a typo worth naming.
+    if (parsed.operands[0] === "install") {
+      require("./tools/mcp/install.cjs").main(parsed.operands.slice(1), { for: argv.for });
+      return;
+    }
+    console.log(
+      `Did you mean \`${CLI_NAME} mcp\` (run the server) or \`${CLI_NAME} mcp install\` (configure an agent)?`,
+    );
+    return;
+  }
+
+  if (parsed && parsed.command === "secret") {
+    await require("./tools/mcp/secret-cli.cjs").main(parsed.operands);
+    return;
+  }
+
   if (parsed) {
     if (parsed.command === "list") argv.list = true;
     if (parsed.command === "skill") argv.skill = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "GramproKit \u2014 an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
   "type": "module",
   "files": [

package/source/components/accordion/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/open.ts",
@@ -21,7 +21,7 @@
       "react/context.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:719b5c18a3e0f3f7479cd1c4f59d729b335053fc47708cc5ab5763b6d69a206a"
+    "sourceHash": "sha256:c04b9c09e8661f463e2a808ecd45a7c080c236bc7b398efc1b3505a45e245f00"
   },
   "props": [
     {
@@ -60,7 +60,9 @@
       "type": "other",
       "typeText": "string[] | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Panels open to begin with, when you are not controlling `value`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "description",
@@ -135,7 +137,9 @@
       "type": "function",
       "signature": "((value: string[]) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The open panels after a change, always an array even with `multiple`\r\noff - where it holds one value, or none once a panel is closed.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "ref",
@@ -249,9 +253,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 19,
-    "propsDescribed": 10,
-    "describedPct": 53,
+    "propsTotal": 15,
+    "propsDescribed": 12,
+    "describedPct": 80,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/accordion/react/Accordion.tsx

@@ -22,7 +22,12 @@ import { cx, type AccordionSlot } from "./props";
 export interface AccordionProps {
   /** Open panels, by value (controlled). */
   value?: string[];
+  /** Panels open to begin with, when you are not controlling `value`. */
   defaultValue?: string[];
+  /**
+   * The open panels after a change, always an array even with `multiple`
+   * off - where it holds one value, or none once a panel is closed.
+   */
   onValueChange?(value: string[]): void;
   /** Render these panels, or pass `<AccordionItem>` children. */
   items?: readonly AccordionItemData[];

package/source/components/alert/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/live.ts",
@@ -240,9 +240,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 19,
+    "propsTotal": 8,
     "propsDescribed": 6,
-    "describedPct": 32,
+    "describedPct": 75,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/identity.ts",
       "core/index.ts",
@@ -20,7 +20,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:2e50d4901b3c6a436a1c8ee35fb43eb11488e305b0466874f007ee325aa02896"
+    "sourceHash": "sha256:541aa6ca5c99e64fba414881c07cc3c29244e03c09b665a4934690d633cc20e1"
   },
   "props": [
     {
@@ -186,7 +186,9 @@
       "type": "string",
       "typeText": "string | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The image. If it fails to load, the avatar falls back to the initials\nrather than showing a broken image, so `name` is worth setting too.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "status",
@@ -284,9 +286,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 23,
-    "propsDescribed": 9,
-    "describedPct": 39,
+    "propsTotal": 10,
+    "propsDescribed": 10,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/avatar/react/Avatar.tsx

@@ -22,6 +22,10 @@ export interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, "chil
    * for the colour, so the same person is always the same colour.
    */
   name?: string;
+  /**
+   * The image. If it fails to load, the avatar falls back to the initials
+   * rather than showing a broken image, so `name` is worth setting too.
+   */
   src?: string;
   /** Overrides the text derived from `name`. */
   initials?: string;

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/count.ts",
       "core/index.ts",
@@ -20,7 +20,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:f6db45647bfab522ced894c388fb16f6a7fac5ebd20a7114d351b812a1f73d34"
+    "sourceHash": "sha256:16f626a94da3bac9b1a105718010edd7e1ce5a6118823ed8a53c97d658d89a3e"
   },
   "props": [
     {
@@ -128,7 +128,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "An icon before the label, in place of `dot`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -322,9 +324,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 26,
-    "propsDescribed": 10,
-    "describedPct": 38,
+    "propsTotal": 13,
+    "propsDescribed": 11,
+    "describedPct": 85,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/badge/react/Badge.tsx

@@ -23,6 +23,7 @@ export interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "child
   formatValue?(value: number): string;
   /** A small filled circle before the label, for a status. */
   dot?: boolean;
+  /** An icon before the label, in place of `dot`. */
   icon?: ReactNode;
   classNames?: Partial<Record<BadgeSlot, string>>;
   ref?: Ref<HTMLSpanElement>;

package/source/components/badge/react/Tag.tsx

@@ -11,6 +11,7 @@ export interface TagProps extends Omit<HTMLAttributes<HTMLSpanElement>, "onRemov
   variant?: BadgeVariant;
   appearance?: BadgeAppearance;
   size?: BadgeSize;
+  /** An icon before the label. */
   icon?: ReactNode;
   /** Show a remove button. Without it a Tag is a Badge with a bit more padding. */
   onRemove?(): void;

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/trail.ts",
@@ -18,7 +18,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:ea18a9023e99fd751d8295a40f257e4471948a5cc9878d808501471718da32aa"
+    "sourceHash": "sha256:3b7fef8f48d1a1290c25a263d2e92ef5dcb706b1a06899ffe5a4df1cdab663e1"
   },
   "props": [
     {
@@ -151,7 +151,9 @@
       "typeText": "'sm' | 'md' | 'lg' | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "structuredData",
@@ -233,9 +235,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 20,
-    "propsDescribed": 7,
-    "describedPct": 35,
+    "propsTotal": 8,
+    "propsDescribed": 8,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/breadcrumb/react/Breadcrumb.tsx

@@ -32,6 +32,7 @@ export interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "chil
    * `{ baseUrl }` so relative links become absolute, as search engines require.
    */
   structuredData?: boolean | { baseUrl: string };
+  /** Default `md`. */
   size?: "sm" | "md" | "lg";
   classNames?: Partial<Record<BreadcrumbSlot, string>>;
   localeText?: Partial<BreadcrumbLocaleText>;

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/state.ts",
@@ -18,7 +18,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:7666d0807d7131796ced32c99da380d3a6db2cf011fd2dcfa7904878799c1871"
+    "sourceHash": "sha256:8d6f65f9bdb461e0ce0c6e7fc4850141ca641f9c01e81be60fe826a62ee24669"
   },
   "purpose": "Trigger an action. Not for navigation unless `render` supplies a link element.",
   "props": [
@@ -84,7 +84,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Fill the width of the container, for forms and narrow screens.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "hidden",
@@ -388,9 +390,9 @@
   },
   "examples": [],
   "coverage": {
-    "propsTotal": 29,
-    "propsDescribed": 9,
-    "describedPct": 31,
+    "propsTotal": 10,
+    "propsDescribed": 10,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility",
       "composition",

package/source/components/button/react/Button.tsx

@@ -30,6 +30,7 @@ export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement
   trailing?: ReactNode;
   /** An icon-only button. Give it an `aria-label`. */
   icon?: ReactNode;
+  /** Fill the width of the container, for forms and narrow screens. */
   fullWidth?: boolean;
   /** Return a promise to show the loading state until it settles. */
   onClick?(event: MouseEvent<HTMLElement>): unknown;

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/trend.ts",
@@ -22,7 +22,7 @@
       "react/Stat.tsx",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:ef4320f169eb618584b31671b65838e1406de0bf944458079b383dcfd40c2e52"
+    "sourceHash": "sha256:5b40d5a873d8c4bd0ea3423f5a9b0ca06f2515aa1ea45149d36be3b2b4aa63e1"
   },
   "props": [
     {
@@ -81,7 +81,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A line under the heading, for context the title cannot carry.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "help",
@@ -113,7 +115,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "An icon beside the figure, to identify the metric at a glance.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -179,7 +183,9 @@
       "type": "string",
       "typeText": "string | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Passed through when `href` is set. Worth setting to\n`noopener noreferrer` on any card linking off-site.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "role",
@@ -225,7 +231,9 @@
       "type": "other",
       "typeText": "StatTrend | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The change beside the figure: direction, a formatted label, and\nwhether down is the good outcome. Left out, no arrow is shown.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "value",
@@ -327,9 +335,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 27,
-    "propsDescribed": 10,
-    "describedPct": 37,
+    "propsTotal": 16,
+    "propsDescribed": 14,
+    "describedPct": 88,
     "authoredSections": [
       "accessibility"
     ]