@grampro/kit 2.4.4 → 2.5.0

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/navigation.ts",
@@ -21,7 +21,7 @@
       "react/Tabs.tsx",
       "react/context.ts"
     ],
-    "sourceHash": "sha256:af648a096e1a1c4e3f61c57b4e61a6c115c3d2351d5f2c8c6b4519348ae80dfc"
+    "sourceHash": "sha256:3d8e29857c59101e547f234c45735db68cc87ee143cc87d841372ec612e2c663"
   },
   "props": [
     {
@@ -124,7 +124,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "An icon before the tab's text.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -155,7 +157,9 @@
       "type": "function",
       "signature": "((value: string) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The newly selected tab. Not fired when the same tab is clicked again.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "orientation",
@@ -305,9 +309,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 25,
-    "propsDescribed": 7,
-    "describedPct": 28,
+    "propsTotal": 11,
+    "propsDescribed": 9,
+    "describedPct": 82,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/tabs/react/Tabs.tsx

@@ -33,6 +33,7 @@ export interface TabsProps extends Omit<
   value?: string;
   /** Selected tab at first. Without either, the first enabled tab is selected. */
   defaultValue?: string;
+  /** The newly selected tab. Not fired when the same tab is clicked again. */
   onValueChange?(value: string): void;
   /** Default `horizontal`. */
   orientation?: TabsOrientation;
@@ -221,6 +222,7 @@ export interface TabProps extends Omit<
 > {
   /** Identifies the tab and its panel. */
   value: string;
+  /** An icon before the tab's text. */
   icon?: ReactNode;
   /** A small count or label after the text, e.g. unread items. */
   badge?: ReactNode;

package/source/components/textarea/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/count.ts",
       "core/index.ts",
@@ -19,7 +19,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:35a538fdd2522c310be181bbb598fdc6eebb99fc5dd1a0ffab3cccf8d84ac43a"
+    "sourceHash": "sha256:a586004558fc7c4059756daa252c36028f3f9b1f4cf55fcccb9b5af2ce1e21e9"
   },
   "props": [
     {
@@ -93,7 +93,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the field's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -137,7 +139,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The field's name, shown above it and linked to it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "localeText",
@@ -267,7 +271,9 @@
       "typeText": "FieldSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "style",
@@ -372,9 +378,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 35,
-    "propsDescribed": 8,
-    "describedPct": 23,
+    "propsTotal": 12,
+    "propsDescribed": 10,
+    "describedPct": 83,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/textarea/react/Textarea.tsx

@@ -28,10 +28,13 @@ export interface TextareaProps
   defaultValue?: string;
   /** The new text on every change. The native `onChange` fires as well. */
   onValueChange?(value: string): void;
+  /** The field's name, shown above it and linked to it. */
   label?: ReactNode;
+  /** A hint under the label, linked as the field's description. */
   description?: ReactNode;
   /** Message below the field; also marks it invalid. */
   error?: ReactNode;
+  /** Default `md`. */
   size?: FieldSize;
   /** Grow and shrink with the text, between `minRows` and `maxRows`. Default false. */
   autoResize?: boolean;

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/api.ts",
       "core/index.ts",
@@ -26,7 +26,7 @@
       "react/props.ts",
       "react/useToasts.ts"
     ],
-    "sourceHash": "sha256:ac828195f4d7ced89c99eb2bd78bb2581ba7a81d62dcfb892b9acef75bddda77"
+    "sourceHash": "sha256:976553d5d606c12b441caba76badad73812eea6dde400b51eb3ee17d05db7871"
   },
   "props": [
     {
@@ -63,7 +63,9 @@
       ],
       "typeText": "'ltr' | 'rtl' | 'auto' | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Writing direction, which decides which corner `position` means.\nDefault `auto`, taken from the document.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "duration",
@@ -211,9 +213,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 12,
-    "propsDescribed": 7,
-    "describedPct": 58,
+    "propsTotal": 8,
+    "propsDescribed": 8,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/toaster/react/Toaster.tsx

@@ -36,6 +36,10 @@ export interface ToasterProps {
   icons?: Partial<Record<ToastType, ReactNode>>;
   /** A store from `createToastStore()`. Defaults to the one behind `toast()`. */
   store?: ToastStore;
+  /**
+   * Writing direction, which decides which corner `position` means.
+   * Default `auto`, taken from the document.
+   */
   dir?: "ltr" | "rtl" | "auto";
   className?: string;
   classNames?: Partial<Record<ToasterSlot, string>>;

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -160,9 +160,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 12,
+    "propsTotal": 9,
     "propsDescribed": 7,
-    "describedPct": 58,
+    "describedPct": 78,
     "authoredSections": [
       "accessibility"
     ]

package/tools/mcp/README.md

@@ -4,31 +4,90 @@ Serves the component catalogue to a coding agent, so it writes against the
 real contract instead of recalling one.
 
 > **Beta.** The tools work and are tested, but their names and shapes may
-> change before this settles. The Figma token handling in particular is not
-> where it should be — see *Credentials* below.
+> change before this settles.
+
+## Setup
+
+```bash
+npx @grampro/kit mcp install
+```
+
+That writes the configuration for every agent it knows about — Claude Code,
+Codex and Cursor — and tells you which files it touched. Restrict it with
+`--for codex` (or `claude`, `cursor`, or a comma-separated list).
+
+It is worth using rather than editing the files by hand: it writes UTF-8
+without a byte-order mark and with LF endings, which is the one thing that
+reliably goes wrong. PowerShell's `Out-File -Encoding utf8` adds a BOM, and
+every JSON parser then rejects the file with an error that names the first
+character and explains nothing.
+
+Running it again is safe. It merges into whatever is already there, leaves
+other servers alone, and says `unchanged` when there is nothing to do.
+
+It writes to the project root — the nearest folder up from you with a `.git`
+or a `package.json` — and prints which one it chose, because an agent reads
+these files from the folder it has open and writing to a subdirectory is the
+one way this can quietly do nothing.
+
+### If the server does not appear
+
+The file being written is not the same as the server being loaded, and in
+Claude Code two things stand between them.
+
+**It needs approving.** A `.mcp.json` server is project-scoped, and Claude
+Code asks before trusting one — until you say yes it sits at `Pending
+approval`, and nothing asks twice. `claude mcp reset-project-choices` brings
+the prompt back if it was dismissed.
+
+**It needs a fresh session.** The configuration is read when a session
+starts, so an editor window that was already open sees nothing. In the VS
+Code extension, run *Developer: Reload Window*.
+
+`/mcp` lists the servers and their state, which is the quickest way to tell
+"not configured" from "configured, not approved".
+
+To skip both, install it for yourself rather than for the project:
+
+```bash
+claude mcp add -s user grampro -- npx -y @grampro/kit mcp
+```
+
+User scope lives in `~/.claude.json`, loads in every project, and needs no
+approval because it is yours rather than the repository's. Project scope is
+the better choice when you want the rest of the team to get it from a commit.
+
+### What it writes
+
+| agent | file | format |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` | `mcpServers.grampro` |
+| Codex | `.codex/config.toml` | `[mcp_servers.grampro]` |
+| Cursor | `.cursor/mcp.json` | `mcpServers.grampro` |
+
+The Codex config is project-scoped. For every project instead, put the same
+`[mcp_servers.grampro]` block in `~/.codex/config.toml`.
+
+A project that already has the package installed gets a direct `node`
+invocation; anywhere else the config uses `npx -y @grampro/kit mcp`, which
+works without an install but re-resolves the package on every start.
+
+### By hand, if you prefer
 
 ```bash
 claude mcp add grampro -- npx -y @grampro/kit mcp
 ```
 
-Codex, Cursor and anything else that speaks MCP take the same command; it is
-a stdio server with no configuration. Without the CLI, write `.mcp.json` in
-your project:
-
-```json
-{
-  "mcpServers": {
-    "grampro": {
-      "command": "node",
-      "args": ["node_modules/@grampro/kit/index.cjs", "mcp"]
-    }
-  }
-}
+```toml
+# ~/.codex/config.toml
+[mcp_servers.grampro]
+command = "npx"
+args = ["-y", "@grampro/kit", "mcp"]
 ```
 
 MCP servers are not invoked by name. There is no `/grampro`; the model calls
-the tools itself when they are relevant. Use `/mcp` to check the server is
-connected.
+the tools itself when they are relevant. In Claude Code, `/mcp` shows whether
+the server connected.
 
 ## Why
 
@@ -72,12 +131,14 @@ Two routes, and the second needs no credentials.
 
 **By URL.** Pass a `figma.com/design/...` link. Called with just the URL it
 lists the frames in the file; called again with `frame` it returns that
-screen. Needs a token.
+screen. A link that already carries a `node-id` — which is what Figma copies
+when you right-click a frame — skips straight to that frame in one call.
+Needs a token.
 
 **By plugin export.** In Figma, run **Grampro Kit → Export selection for an
 agent**, then pass the JSON as `design`. The plugin reads the scene graph
-directly, so this works on any file you can open and asks for no token at
-all.
+directly, so this works on any file you can open, asks for no token, and
+never touches the REST API — which also means it cannot be rate limited.
 
 Either way the answer is the same shape: the structure, the text, the
 regions whose names repeat — eight `Status cell` nodes are a column — and
@@ -94,21 +155,51 @@ is the body text, and a near-black navy scores high on saturation, so both
 "most common" and "most saturated" pick the wrong thing. Lightness and
 saturation together find the accent.
 
+### Rate limits
+
+Figma's limits on file reads are cost-based, and the cost is the size of the
+response. Asking for a whole file to answer a question about one frame is
+what earns a 429, and the lockout is long — a `Retry-After` of 395274 has
+been observed on a single token.
+
+So nothing here fetches a whole file. Listing the frames uses `depth=1`,
+which returns the document's outline rather than its contents, and the frame
+itself is then fetched by id. A URL carrying a `node-id` skips the listing
+altogether. Responses are held for five minutes, so the natural two-call
+flow — list, then read — costs one listing and one frame.
+
+If a token is already locked out, the plugin export route still works.
+
 ## Credentials
 
-**This is the weakest part of the current design, and it is temporary.**
+The URL route needs a Figma personal access token. Store it where the
+operating system keeps credentials:
 
-The URL route reads `FIGMA_TOKEN` from the environment, or from a `.env`
-file beside the project. That means a long-lived credential sitting in a
-file, which is not where it belongs.
+```bash
+npx @grampro/kit secret set figma
+```
 
-A future release will keep it in the editor's own secret storage — VS Code's
-`SecretStorage` for the extension, and the equivalent elsewhere — so the
-token is held by the host rather than the repository. Until then:
+It prompts, with the echo off, and never takes the value as an argument —
+arguments land in shell history and in every process listing on the machine.
+Piping works too, for a script: `echo "$TOKEN" | npx @grampro/kit secret set figma`.
 
-- prefer the plugin export route, which needs no token at all;
-- if you do use a token, give it only `File content: read`;
-- keep `.env` out of version control.
+| platform | where it goes |
+| --- | --- |
+| Windows | Data Protection API, tied to your Windows account |
+| macOS | the keychain |
+| Linux | Secret Service (GNOME Keyring, KWallet) |
+| anything else | a 0600 file in your config directory, and it says so |
+
+`secret list` shows what is stored, masked, and names the backend in use.
+`secret remove figma` deletes it. Create the token at Figma → Settings →
+Security → Personal access tokens, with `File content: read` and nothing
+else.
+
+The token is read from `FIGMA_TOKEN` in the environment first, then the
+store, then a `.env` — the last only so that an upgrade does not break a
+project set up the old way. Reading from a `.env` prints a note saying to
+move it. A credential in a file inside a working tree is one `git add -A`
+away from being published, which is why this moved.
 
 ## Suggested use
 
@@ -123,10 +214,11 @@ No dependencies. MCP is newline-delimited JSON-RPC over stdio, which is a
 few hundred lines, and a server shipped inside a library that every consumer
 installs should not drag an SDK along with it.
 
+Start-up is about the cost of an empty Node process. An agent spawns the
+server once per session, and `index.cjs` routes `mcp` before loading the
+CLI's own dependencies, which are no use to a JSON-RPC loop and cost around
+70ms. The passports are indexed on the first question and not re-read after.
+
 The catalogue it serves is the one in this package, not the components
 copied into your project — so an agent can see a component before you
 install it, and `install_component` puts it in place.
-
-A Figma file is fetched once and held for five minutes. The natural flow is
-two calls, list then read, and refetching a large file in between is what
-earns a rate limit.

package/tools/mcp/figma.cjs

@@ -24,18 +24,33 @@ const MAX_DEPTH = 10;
 // ------------------------------------------------------------------ token
 
 /**
- * The token, from the environment or a .env beside the project.
+ * The token, from the environment, the OS secret store, or a `.env`.
  *
- * MCP clients pass environment through unevenly, so a .env is the fallback
- * that works everywhere. It is read, never logged.
+ * The store is where it belongs and `.env` is kept only so that anyone who
+ * set it up that way is not broken by an upgrade. Reading from a `.env` says
+ * so once, on stderr — stdout carries JSON-RPC and nothing else may touch it.
  */
+let warnedAboutDotenv = false;
+
 function figmaToken() {
   if (process.env.FIGMA_TOKEN) return process.env.FIGMA_TOKEN.trim();
+
+  const stored = require("./secret.cjs").getSecret("figma");
+  if (stored) return stored;
+
   for (const dir of [process.cwd(), path.join(__dirname, "..", "..")]) {
     const file = path.join(dir, ".env");
     if (!fs.existsSync(file)) continue;
     const match = fs.readFileSync(file, "utf8").match(/^\s*FIGMA_TOKEN\s*=\s*(.+)$/m);
-    if (match) return match[1].trim().replace(/^["']|["']$/g, "");
+    if (!match) continue;
+    if (!warnedAboutDotenv) {
+      warnedAboutDotenv = true;
+      process.stderr.write(
+        "grampro-kit: read FIGMA_TOKEN from .env. Move it out of the repository with " +
+          "`npx @grampro/kit secret set figma`, then delete the line.\n",
+      );
+    }
+    return match[1].trim().replace(/^["']|["']$/g, "");
   }
   return null;
 }
@@ -73,8 +88,27 @@ async function figmaGet(pathname, token) {
       );
     }
     if (res.status === 429) {
+      /*
+       * Figma's file-read limit is cost-based, and once a token is over it the
+       * window is long — tens of minutes, not the "try again shortly" that
+       * this message used to promise. The plugin route is the honest advice,
+       * because it does not touch the API at all.
+       */
+      /*
+       * Retry-After is meant to be seconds, and Figma has been seen to return
+       * 395274 on a file read — four and a half days, or six minutes if the
+       * value is milliseconds. Rather than state a figure that may be wrong by
+       * three orders of magnitude, the number is passed through as given.
+       */
+      const after = res.headers.get("retry-after");
+      const when = after
+        ? `Figma's Retry-After says ${after} (nominally seconds).`
+        : "That window is usually tens of minutes, not seconds.";
       throw new Error(
-        "Figma is rate limiting this token. Wait a minute and try again; the file is cached for five minutes once it arrives.",
+        `Figma is rate limiting this token. ${when} Nothing here can shorten it. ` +
+          "To carry on now, use the kit's Figma plugin → 'Export selection for an agent' " +
+          "and pass the result as `design` — that route reads the file from inside Figma " +
+          "and never calls the API.",
       );
     }
     throw new Error(`Figma returned ${res.status}: ${body.slice(0, 160)}`);
@@ -300,27 +334,63 @@ async function figmaFrame({ url, design, frame, depth }) {
   if (!token) {
     return {
       error:
-        "No FIGMA_TOKEN. Either run the kit's Figma plugin → 'Export selection for an agent' and pass the result as `design`, or create a token at Figma → Settings → Security → Personal access tokens (scope: File content, read) and set FIGMA_TOKEN.",
+        "No Figma token. Two ways forward, and the first needs no credentials: " +
+        "run the kit's Figma plugin → 'Export selection for an agent' and pass the result as `design`. " +
+        "Otherwise create a token at Figma → Settings → Security → Personal access tokens " +
+        "(scope: File content, read) and store it with `npx @grampro/kit secret set figma`.",
     };
   }
 
   const { fileKey, nodeId, error } = parseFigmaUrl(url);
   if (error) return { error };
 
+  /*
+   * Three shapes of request, cheapest first.
+   *
+   * A URL carrying a node-id — which is what Figma gives you when you copy a
+   * link to a frame — is one targeted call and nothing else. Otherwise the
+   * frames are listed with depth=1, which returns the outline of the document
+   * rather than the document, and the chosen frame is then fetched by id.
+   * Figma's limits are cost-based and the cost is the payload, so pulling the
+   * whole file to answer either question is what earns a 429.
+   */
   let file;
+  let roots;
   try {
-    file = nodeId
-      ? await figmaGet(`/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`, token)
-      : await figmaGet(`/files/${fileKey}`, token);
+    if (nodeId) {
+      file = await figmaGet(`/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`, token);
+      roots = Object.values(file.nodes || {}).filter(Boolean).map((n) => n.document);
+    } else {
+      const outline = await figmaGet(`/files/${fileKey}?depth=1`, token);
+      const tops = (outline.document.children || []).flatMap((page) => page.children || []);
+
+      if (!frame) {
+        return {
+          file: outline.name,
+          frames: tops.map((f) => ({
+            name: f.name,
+            id: f.id,
+            size: f.absoluteBoundingBox
+              ? [Math.round(f.absoluteBoundingBox.width), Math.round(f.absoluteBoundingBox.height)]
+              : undefined,
+          })),
+          next: "Call again with `frame` set to the one you want to build. Passing a URL that already carries a node-id skips this step.",
+        };
+      }
+
+      const match = tops.find((f) => f.name.toLowerCase() === String(frame).toLowerCase());
+      if (!match) {
+        return { error: `No frame called "${frame}".`, frames: tops.map((f) => f.name) };
+      }
+      file = await figmaGet(`/files/${fileKey}/nodes?ids=${encodeURIComponent(match.id)}`, token);
+      roots = Object.values(file.nodes || {}).filter(Boolean).map((n) => n.document);
+      file.name = outline.name;
+    }
   } catch (e) {
     return { error: e.message };
   }
 
-  const roots = nodeId
-    ? Object.values(file.nodes || {}).filter(Boolean).map((n) => n.document)
-    : (file.document.children || []).flatMap((page) => page.children || []);
-
-  if (roots.length === 0) return { error: "Nothing to read at that URL." };
+  if (!roots || roots.length === 0) return { error: "Nothing to read at that URL." };
 
   /*
    * Without a frame named, the whole file would arrive at once — hundreds of
@@ -331,19 +401,6 @@ async function figmaFrame({ url, design, frame, depth }) {
     ? roots.filter((r) => r.name.toLowerCase() === String(frame).toLowerCase())
     : roots;
 
-  if (!frame && roots.length > 1) {
-    return {
-      file: file.name,
-      frames: roots.map((r) => ({
-        name: r.name,
-        size: r.absoluteBoundingBox
-          ? [Math.round(r.absoluteBoundingBox.width), Math.round(r.absoluteBoundingBox.height)]
-          : undefined,
-      })),
-      next: "Call again with `frame` set to the one you want to build.",
-    };
-  }
-
   if (wanted.length === 0) {
     return { error: `No frame called "${frame}".`, frames: roots.map((r) => r.name) };
   }