@grampro/kit 2.6.0 → 2.6.2

package/.gbs/skills/gbs-components/SKILL.md

@@ -6,6 +6,22 @@ autoAttach: ["src/**/*.tsx", "src/**/*.jsx", "app/**/*.tsx", "components/**/*.ts
 
 # GBS components (2.0 beta)
 
+## If the MCP server is connected
+
+This file is a summary. The `grampro` MCP server answers from passports
+generated from the component source, so where the two differ it is right
+and this is stale. When its tools are available:
+
+- **`get_component <Name>`** before writing a component — every prop with
+  its type, the values a union accepts, which props are required, handler
+  signatures. Do not write a prop you have not read there.
+- **`validate_usage`** on the JSX before reporting back. It catches props
+  invented from memory, which is the one failure a passport cannot prevent.
+- **`figma_frame`** to read a design, from a `designFile` path or a Figma
+  URL, when building from one.
+
+Neither needs the other installed. Without the server this file is what
+you have, and everything below still applies.
 ## Install before you import
 
 Not an npm dependency — the CLI **copies source into the repo**:

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 2.6.2
+
+### Changed
+
+**The agent skill now knows the MCP server exists.** It described the
+component library and never mentioned the server, so an agent holding both
+had nothing to tell it which to trust. The skill is a summary; the server
+answers from passports generated from the source, so where they differ the
+server is right and the skill is stale — and it now says so, along with
+calling `get_component` before writing a component and `validate_usage`
+before reporting back.
+
+The only previous mention of "MCP" in the skill was WebMCP, the DataGrid's
+browser-agent surface, which is a different thing entirely.
+
+**Neither needs the other, and the docs now say so.** The server carries
+its own copy of the guidance inside the package, so `get_guidance` answers
+in a project with no `.gbs/` folder at all. What they do together is the
+useful part: the skill is always in an agent's context and the server is
+not, so the skill is what tells an agent to ask and the server is what it
+asks.
+
+The two pages now read in the order they are used — Theming, Agent skill,
+MCP server.
+
+**The text LLMs read was teaching a deprecated command.** `llms.txt` has a
+hand-written preamble, so it lagged behind the CLI: it told every model
+that reached the site to run `npx @grampro/kit -a <Component>`, a spelling
+the CLI itself marks "Deprecated. Use: add". It now says `add`, and names
+the Figma plugin, the whole-design export and `designFile`, none of which
+it mentioned.
+
+**The plugin's install link was invisible to every LLM.** It is rendered by
+a component, and the Markdown conversion passed that through verbatim — so
+`llms-full.txt` and every `.md` page carried a dangling `<FigmaPlugin />`
+tag where the URL should have been, and the plugin's address appeared
+nowhere a model could read it. The conversion emits a Markdown link now,
+and the URL lives in one place so the button and the converter cannot
+disagree about it.
+
+**Every command is listed in one place.** `list` and `passport` appeared
+in no user-facing documentation at all, and the rest were scattered across
+three pages, so there was nowhere to look to find out what the CLI does.
+The README now carries the lot in a table.
+
+## 2.6.1
+
+### Changed
+
+**A screen costs about half what it did to read.** Measured on a real
+purchase-orders design: 42.9 KB to 23.9 KB, roughly 13,300 tokens to
+7,400.
+
+Eight table rows exported as eight sibling subtrees of identical shape
+whose text differed — 48% of that screen was the same row said seven
+more times. The first is now given in full, because the agent builds from
+its shape, and the rest become `repeatedText`: one array of strings per
+row, which is closer to what a DataGrid's `data` prop wants than the
+subtrees were.
+
+Runs are matched on structure rather than appearance. Keyed on style, the
+rows never matched at all: a striped table alternates its background, so
+every consecutive pair looked like a different shape and nothing
+collapsed. Where the fills do vary across a run they come back as
+`repeatedFills`, which is how the striping and the per-status badge
+colours stay legible.
+
+Only runs of three or more collapse, and only where there is depth to
+save: two of a thing is a pair, not a list, and a row of labels has
+nothing inside it worth folding.
+
+### Fixed
+
+**`depth` is honoured on the plugin and file routes.** The tool has always
+offered it — "Lower it if the payload is large" — and only ever applied
+it to a design fetched from a URL. A caller who read the schema and
+lowered it to cut a large payload got the large payload back. The same
+screen at `depth: 3` is now 3.5 KB, and what was dropped says so rather
+than going quiet.
+
+**Selecting several frames exports several screens.** It used to produce
+one pseudo-frame called "3 selected nodes" holding all of them, which
+`design` then wrote as a single file under that name — a folder whose
+whole point is one file per screen, with one file for three. The screens
+were in there, but nothing said where one ended and the next began.
+
+A selection of several frames now produces the same shape the whole-file
+export does, so the split, the index and `figma_frame` treat them
+identically. One frame selected is still one screen.
+
+This is also the scoping the all-screens command lacks: a file with forty
+frames in it need not be exported entire to build two of them. Select the
+screens you want and export those.
+
+
 ## 2.6.0
 
 ### Added

package/README.md

@@ -80,6 +80,21 @@ Each component also has a **framework-free core** — `createDialogStore()`,
 `createGridEngine()` — with no React imports, usable on a server. That part is
 genuinely headless, and the component READMEs document it under "Headless use".
 
+## Commands
+
+| | |
+| --- | --- |
+| `add <Component>...` | Copy components into the project. `--dest` chooses where; `--legacy` reaches the 1.x set. |
+| `list` | What is available to add. |
+| `skill` | Install the agent skill. `--for claude,codex,antigravity` narrows it. |
+| `mcp` | Run the MCP server. Agents start this themselves; you rarely type it. |
+| `mcp install` | Write the server's configuration for Claude Code, Codex and Cursor. |
+| `secret set figma` | Store a Figma token in the OS credential store. Also `get`, `list`, `remove`. |
+| `design <file>` | Split a whole-design Figma export into a folder of screens. |
+| `passport --check` | Fail if a passport has drifted from its source. For CI, and after forking a component. |
+
+`npx @grampro/kit <command>`, or `grampro-kit` once it is a dev dependency.
+
 ## Documentation
 
 [kit.gramproindia.com](https://kit.gramproindia.com) — usage and props per
@@ -122,6 +137,33 @@ takes. Full walkthrough, including a prompt to paste:
 [kit.gramproindia.com/mcp-server](https://kit.gramproindia.com/mcp-server).
 Details in [`tools/mcp/README.md`](tools/mcp/README.md).
 
+## Figma plugin
+
+[**Grampro Kit on the Figma Community**](https://www.figma.com/community/plugin/1692828324805361551)
+
+Two jobs. It generates the whole design system inside Figma — 53 variables
+across light and dark, 13 text styles, 38 component sets — and it exports
+screens as JSON a coding agent can build from.
+
+```bash
+# in Figma: Grampro Kit → Export all screens for an agent → Save .json
+npx @grampro/kit design ./design.json
+```
+
+```text
+design/
+  purchase-orders.json
+  suppliers.json
+  index.json          every screen, the shared theme, the regions that repeat
+```
+
+The agent reads `index.json` to plan, then builds one screen at a time
+against `figma_frame`, `get_component` and `validate_usage`. It needs no
+Figma API token and makes no network requests of any kind.
+
+Source is in [`figma-plugin/`](figma-plugin/); the published listing is
+what to install.
+
 ## Agent skill
 
 Install the skill once per project so a coding agent uses these components

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "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.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/open.ts",

package/source/components/alert/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/live.ts",

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/identity.ts",
       "core/index.ts",

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/trail.ts",

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/state.ts",

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/trend.ts",

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/group.ts",
       "core/index.ts",

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/filter.ts",
       "core/index.ts",

package/source/components/data-grid/passport.json

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",

package/source/components/date-picker/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/calendar.ts",
       "core/format.ts",

package/source/components/dialog/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/api.ts",
       "core/dialog.ts",

package/source/components/file-uploader/passport.json

@@ -13,7 +13,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/input/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/menu/passport.json

@@ -16,7 +16,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/modal/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/dismiss.ts",
       "core/index.ts",

package/source/components/number-input/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/popover/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/source/components/progress/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/progress.ts",

package/source/components/radio-group/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/group.ts",
       "core/index.ts",

package/source/components/skeleton/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/lines.ts",

package/source/components/spinner/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/source/components/switch/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/toggle.ts",

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/textarea/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/api.ts",
       "core/index.ts",

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.0",
+    "libraryVersion": "2.6.2",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/tools/mcp/README.md

@@ -127,7 +127,8 @@ invention, and this catches it:
 
 ## A whole design at once
 
-In Figma, **Grampro Kit → Export all screens for an agent** walks every
+Install [Grampro Kit from the Figma Community](https://www.figma.com/community/plugin/1692828324805361551). Then
+**Grampro Kit → Export all screens for an agent** walks every
 page and exports each top-level frame, with one set of theme values read
 across the whole design rather than guessed per frame. Save it, then:
 

package/tools/mcp/figma.cjs

@@ -265,6 +265,123 @@ function repeatedNames(node, counts) {
 
 // ------------------------------------------------------------------- tool
 
+/*
+ * Repetition is the point, and sending it in full is the waste.
+ *
+ * A table of eight rows exports as eight siblings of identical shape whose
+ * text differs. The agent needs the shape once and the values eight times;
+ * on a real screen the other seven copies were 48% of the payload.
+ */
+
+/**
+ * A node's structure: names, types, nesting and layout.
+ *
+ * Style is deliberately not part of it. Table rows are zebra-striped, so
+ * consecutive rows differ by a background colour and nothing else — keying
+ * on style meant every pair looked distinct and no run was ever found. The
+ * variation is reported instead of being treated as a different shape.
+ */
+function shapeKey(node) {
+  return JSON.stringify([
+    node.name,
+    node.type,
+    node.layout,
+    (node.children || []).map(shapeKey),
+  ]);
+}
+
+/** The fills down a subtree, so a collapsed run can say how they alternate. */
+function fillsOf(node, into = []) {
+  if (node.style && node.style.fill) into.push(node.style.fill);
+  for (const child of node.children || []) fillsOf(child, into);
+  return into;
+}
+
+/** Every string in a subtree, in order: what one row of a table actually says. */
+function textsOf(node, into = []) {
+  if (node.text) into.push(node.text);
+  for (const child of node.children || []) textsOf(child, into);
+  return into;
+}
+
+/** How many levels deep a subtree goes. */
+const depthOf = (node) =>
+  1 + Math.max(0, ...(node.children || []).map(depthOf));
+
+/**
+ * Collapse runs of same-shaped siblings, and trim to `limit` levels.
+ *
+ * Only runs of three or more are collapsed: two of a thing is a pair, not a
+ * list, and the saving would not pay for the indirection. A run that is only
+ * one level deep is left alone too — there is nothing to save in a row of
+ * labels, and collapsing it would cost the agent the order they appear in.
+ */
+function condenseTree(nodes, limit, level = 1) {
+  const out = [];
+  let i = 0;
+
+  while (i < nodes.length) {
+    const node = nodes[i];
+    const key = shapeKey(node);
+    let run = 1;
+    while (i + run < nodes.length && shapeKey(nodes[i + run]) === key) run += 1;
+
+    const worthIt = run >= 3 && depthOf(node) > 1;
+    const trimmed = trim(node, limit, level);
+
+    if (!worthIt) {
+      for (let n = 0; n < run; n += 1) out.push(trim(nodes[i + n], limit, level));
+      i += run;
+      continue;
+    }
+
+    /*
+     * The first in full, then the rest as what they say. `repeats` is the
+     * count including this one, so an agent reading only this node knows how
+     * many rows to render.
+     */
+    const rest = [];
+    for (let n = 1; n < run; n += 1) rest.push(textsOf(nodes[i + n]));
+
+    /*
+     * Fills are reported only where they actually differ across the run.
+     * Where they do it is nearly always zebra striping, and two colours
+     * said once is the whole of it.
+     */
+    const fills = [];
+    for (let n = 0; n < run; n += 1) fills.push(fillsOf(nodes[i + n]).join(","));
+    const varies = new Set(fills).size > 1;
+
+    out.push({
+      ...trimmed,
+      repeats: run,
+      repeatsNote:
+        `${run} siblings share this structure. The first is given in full; ` +
+        "`repeatedText` holds what each of the others says, in the same order " +
+        "as the text in this one." +
+        (varies ? " `repeatedFills` gives each one's colours, which alternate." : ""),
+      repeatedText: rest,
+      ...(varies ? { repeatedFills: fills.map((f) => f.split(",")) } : {}),
+    });
+    i += run;
+  }
+
+  return out;
+}
+
+/** Drop everything below `limit` levels, saying what was dropped. */
+function trim(node, limit, level) {
+  if (!node.children || node.children.length === 0) return node;
+  if (level >= limit) {
+    const inside = node.children.reduce(
+      (n, child) => n + 1 + (child.children ? child.children.length : 0),
+      0,
+    );
+    const { children, ...rest } = node;
+    return { ...rest, truncated: `${inside}+ nodes below this, not shown` };
+  }
+  return { ...node, children: condenseTree(node.children, limit, level + 1) };
+}
 /*
  * A selection exported by the plugin, which has already done the condensing
  * inside Figma. The work left is the part that needs no file access: giving
@@ -273,7 +390,7 @@ function repeatedNames(node, counts) {
  * This is the path for anyone who would rather not hold an API token, and
  * for files the token cannot reach.
  */
-function fromPluginExport(design) {
+function fromPluginExport(design, depth) {
   let parsed;
   try {
     parsed = typeof design === "string" ? JSON.parse(design) : design;
@@ -311,6 +428,14 @@ function fromPluginExport(design) {
   };
   for (const node of parsed.nodes) findInstances(node);
 
+  /*
+   * `depth` was offered on this tool and only ever honoured for a URL. A
+   * caller who read the schema and lowered it to cut a large payload got
+   * the large payload back.
+   */
+  const limit = Math.min(Number(depth) || MAX_DEPTH, MAX_DEPTH);
+  const tree = condenseTree(parsed.nodes, limit);
+
   return {
     source: "figma plugin export",
     frame: parsed.frame,
@@ -322,7 +447,7 @@ function fromPluginExport(design) {
       .map(([name, n]) => ({ name, times: n })),
     builtFromLibrary: instances.length > 0,
     componentsNamed: [...new Set(instances)],
-    tree: parsed.nodes,
+    tree,
     /*
      * The same closing instruction the URL route gives. Without it an agent
      * arriving by the plugin — now the route the documentation leads with —
@@ -349,7 +474,7 @@ function fromPluginExport(design) {
  * has already condensed it; there is nothing further to drop that the
  * screen does not need.
  */
-function fromFile(file) {
+function fromFile(file, depth) {
   let resolved;
   try {
     resolved = path.resolve(file);
@@ -371,14 +496,14 @@ function fromFile(file) {
   }
   // A byte-order mark survives a round trip through some editors and is not
   // valid JSON, so it goes before parsing rather than after a confusing throw.
-  return fromPluginExport(body.replace(/^\uFEFF/, ""));
+  return fromPluginExport(body.replace(/^\uFEFF/, ""), depth);
 }
 
 async function figmaFrame({ url, design, designFile, frame, depth }) {
   // Both export routes need no token, so they are offered before one is
   // demanded. The file comes first: it is the one that scales.
-  if (designFile) return fromFile(designFile);
-  if (design) return fromPluginExport(design);
+  if (designFile) return fromFile(designFile, depth);
+  if (design) return fromPluginExport(design, depth);
 
   const token = figmaToken();
   if (!token) {