@grampro/kit 2.6.2 → 2.7.0

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

@@ -4,7 +4,7 @@ description: Builds UI with the GramproKit component library (@grampro/kit). Use
 autoAttach: ["src/**/*.tsx", "src/**/*.jsx", "app/**/*.tsx", "components/**/*.tsx"]
 ---
 
-# GBS components (2.0 beta)
+# GBS components (2.x)
 
 ## If the MCP server is connected
 
@@ -30,8 +30,9 @@ Not an npm dependency — the CLI **copies source into the repo**:
 npx @grampro/kit add Button,Input,Modal
 ```
 
-Writes `component-lib/<folder>/` plus `component-lib/shared/`. Always pass
-`--beta`. Import the barrel in your component:
+Writes `component-lib/<folder>/` plus `component-lib/shared/`. No flag is
+needed: the 2.x components are the default. Import the barrel in your
+component:
 
 ```ts
 import { Button } from "component-lib/button";
@@ -195,7 +196,7 @@ a bigger model.
 
 ## Details (in `references/`)
 
-- `install.md` — CLI flags, folders, 1.x vs beta.
+- `install.md` — CLI flags, folders, 1.x vs 2.x.
 - `forms.md` — fields, controlled state, form posting.
 - `pickers.md` — Select, MultiSelect, DatePicker, Uploader.
 - `overlays.md` — Modal, dialog, Popover, Menu, Tooltip.

package/.gbs/skills/gbs-components/references/install.md

@@ -10,7 +10,7 @@ imported from `node_modules` at runtime, and the copied files are yours to edit.
 `bin: { "@grampro/kit": "index.cjs" }` and `files: ["index.cjs", "source",
 ".gbs"]`. There is nothing to `import "@grampro/kit"` from.
 
-Peer dependencies: `react@^19` and `react-dom@^19`. The beta components have no
+Peer dependencies: `react@^19` and `react-dom@^19`. The components have no
 other runtime dependencies.
 
 ## Commands
@@ -18,11 +18,11 @@ other runtime dependencies.
 ```bash
 npx @grampro/kit add Button                 # one component
 npx @grampro/kit add Button,Input,Modal     # several
-npx @grampro/kit -i --beta                        # interactive picker
-npx @grampro/kit -l --beta                        # list available
+npx @grampro/kit -i                         # interactive picker
+npx @grampro/kit -l                         # list available
 npx @grampro/kit add Button --force         # overwrite edited shared/ files
-npx @grampro/kit skill                           # install this skill
-npx @grampro/kit skill --for claude              # only the Claude Code copy
+npx @grampro/kit skill                      # install this skill
+npx @grampro/kit skill --for claude         # only the Claude Code copy
 ```
 
 | Flag | Alias | Meaning |
@@ -30,16 +30,19 @@ npx @grampro/kit skill --for claude              # only the Claude Code copy
 | `--add` | `-a` | Component, or comma-separated list. Case-insensitive. |
 | `--interactive` | `-i` | Pick from a menu. |
 | `--list` | `-l` | Print available components. |
-| `--beta` | — | Install the 2.0 redesigned components. `-beta` also works. |
+| `--legacy` | — | Install from the 1.x set instead. Unmaintained; see below. |
 | `--skill` | — | Install this skill at the project root. `-skill` and `-a skill` also work. |
 | `--for` | — | With `--skill`: which agents to write adapters for (`claude`, `codex`, `antigravity`, or `none`). Default: all. |
 | `--force` | — | Replace files you have edited locally in `shared/` or `.gbs/`. |
 
-**Always pass `--beta`.** Without it you get the 1.x set (`Select`, `SideBar`,
-`FormRenderer`, `MaterialInput`, `ContextMenu`, `Navbar`, `Bargraph`,
-`DarkMode`, `Toast`, `Uploader`, `UsePaginatedData`, `UseUploader` and others),
-which is a different, older API with different props. The two sets are not
-interchangeable.
+**Pass no flag.** The 2.x components are what `add` installs. `--beta` used
+to opt in to them and now does nothing but print a notice, so do not pass it.
+
+`--legacy` reaches the 1.x set (`Select`, `SideBar`, `FormRenderer`,
+`MaterialInput`, `ContextMenu`, `Navbar`, `Bargraph`, `DarkMode`, `Toast`,
+`Uploader`, `UsePaginatedData`, `UseUploader` and others). That is a different,
+older API with different props, it is no longer maintained, and the two sets
+are not interchangeable. Do not reach for it unless asked to.
 
 ## Installing this skill
 
@@ -78,7 +81,7 @@ CLI from the repo root (or move the folder afterwards and fix the imports).
 
 ```
 component-lib/
-  shared/          installed with every beta component
+  shared/          installed with every component
   button/
   data-grid/
   input/
@@ -105,7 +108,7 @@ Note the mismatch between the install name and the import name for two of them:
 - Install `Toaster`; import `toast` and `Toaster` from `component-lib/toaster`.
 - Install `Dialog`; import `dialog` and `DialogHost` from `component-lib/dialog`.
 
-## Available beta components
+## Available components
 
 `DataGrid`, `Combobox`, `DatePicker`, `Toaster`, `FileUploader`, `Dialog`,
 `Input`, `Modal`, `Textarea`, `Button`, `Breadcrumb`, `Checkbox`, `Tabs`,
@@ -132,7 +135,7 @@ project has no reason to have.
 
 ## The shared folder
 
-Every beta component imports `../../shared`. The CLI installs it alongside
+Every component imports `../../shared`. The CLI installs it alongside
 whatever you picked, and it is versioned independently (`shared/version.json`).
 
 Rules the installer enforces:

package/CHANGELOG.md

@@ -1,29 +1,172 @@
 # Changelog
 
-## 2.6.2
+## 2.7.0
+
+### Added
+
+**A design read from a URL now names its components.** An instance built
+from a library is the most valuable thing a design can contain — it says
+"this is a Button" instead of leaving an agent to infer it from a layer
+name and a fill. The URL route recorded `instanceOf: "1:234"`, an opaque
+id nothing could be done with, and discarded the maps that name it, which
+Figma sends in the same response.
+
+It resolves them now, preferring the component set's name over the
+variant's: a variant is called `Size=md, Variant=primary` and its set is
+called `Button`, and Button is what the agent is going to write. An
+instance whose master is not in the response keeps its id rather than
+guessing.
+
+**Every component now says what it is for.** A passport had two halves: the
+derived one, generated from the TypeScript, and the authored one — `purpose`,
+`intentDomains`, `accessibility`, `composition`, `safeMutations`. The generator
+emits empty shells for the authored half because none of it is in the types,
+and only Button and DataGrid had ever been filled in. The other 25 are written
+now.
+
+`safeMutations` is the one an agent acts on: which props it may change without
+altering behaviour, and which it may not, with the reason. An agent restyling a
+FileUploader should be free to change `size` and `preview` and nowhere near
+`endpoint`, `headers` or `transport` — that component is the one where a wrong
+prop sends someone's data somewhere. `get_component` now returns all of it;
+until this release it served `purpose` and dropped the rest, so the authored
+half reached nobody.
+
+Where no value in the schema's `intentDomains` enum honestly describes a
+component, the list is left empty rather than filled for symmetry. Nine of them
+are presentational, and a wrong routing hint is worse than none.
+
+**A field runtime, so nine components are agent-operable instead of one.**
+`setValue`, `clear`, `focus`, and `open`/`close` for the two that have
+something to disclose, on Input, Textarea, NumberInput, Checkbox, Switch,
+RadioGroup, Combobox and DatePicker.
+
+The grid earned a runtime of its own because its operations are a language:
+filter, sort, pin, paginate, export. A field has one verb, so the verb lives in
+`shared/core/agent` once rather than eight times, and each component supplies
+only a contract built from its own props. The same five layers rule on it —
+schema, reference, coercion, policy, plausibility — so a write to a read-only
+field is refused by name, an option that does not exist comes back with the
+nearest one that does, and a number outside `min`/`max` is told which bound it
+crossed rather than being silently clamped.
+
+The open question was whether the executor abstraction generalised. A grid is
+driven through an imperative API and a field is not, and the architecture notes
+had flagged that as unproven. It holds: Combobox and DatePicker are driven
+through their handles, the other six through the element their ref already
+returns, and nothing above the executor knows which. `setValue` joins
+`ComboboxHandle` and `DatePickerHandle` as a public method; the six that expose
+the DOM element needed no API change at all, because the technique
+`Input.clear()` has always used — the prototype setter plus a real event — is
+the same write with a value in it.
+
+`useFieldAgent` binds a contract to a ref. No component grew a prop for this.
+
+**The authored passports had no schema of their own.** A `passport.manual.json`
+pointed at `passport-v1.schema.json`, which describes the *merged* passport —
+so an editor validating one reported all eight generated fields as missing
+(`passportVersion`, `identity`, `source`, `props`, `events`, `slots`, `states`,
+`coverage`), and `additionalProperties: false` made errors of the four keys only
+an overlay has: `component`, `propNotes`, `notImplemented`, `$operationsNote`.
+
+It was wrong on the two files that had it before and merely quiet; at
+twenty-seven it is the thing that teaches people to ignore squiggles.
+`schema/passport-overlay-v1.schema.json` describes what an overlay may
+actually contain, referencing the merged schema for the fields they share so
+the two cannot drift. A test holds every overlay to it, which also catches a
+mistyped key — previously a silent no-op, since the merge only reads the names
+it knows.
+
+### Security
+
+**A failed JSON parse quoted the file back.** V8 puts the first ten or so
+characters of its input into the error it throws, so pointing `designFile` at
+something that was not JSON returned a slice of it:
+
+    That is not JSON: Unexpected token 's', "sk-proj-RE"... is not valid JSON
+
+Ten bytes is not an extraction, but it is enough to confirm that a path
+exists and what kind of file sits there, and an agent can be pointed at paths
+in a loop. The server runs with your own authority and the agent could read
+the file directly, so this was hygiene rather than a hole — and it cost
+nothing to close. The three parse sites in `figma.cjs`, `design.cjs` and
+`install.cjs` now name the file and say what was expected, without quoting
+any of it.
+
+**The package no longer installs a build toolchain.**
+`@grampro/headless-helpers` declared `rollup`, its plugins and `typescript`
+as runtime dependencies, so installing the kit pulled a compiler and a
+bundler into `node_modules` and carried their advisories — an arbitrary file
+write in Rollup and two ReDoS in picomatch, none of which any of this code
+runs. Requiring `^1.0.22`, which moved them to devDependencies, removes 84
+packages from a clean install and leaves the package at zero advisories.
+
+**Mermaid rendered with sanitisation off.** The diagram component ran with
+`securityLevel: "loose"`, which permits HTML in labels and click handlers,
+and its output goes through `dangerouslySetInnerHTML`. Nothing was
+exploitable: the only diagram text comes from our own MDX at build time, and
+in fact no page renders one. But the two together are a trap for whoever
+first renders a diagram from anything else, so it is `"strict"` now.
 
 ### 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 docs lead with the URL route.** Pasting a Figma link is one step;
+the plugin route is five, and every one is a place to stop. The reason it
+was necessary for designs built from a component library is now gone, so
+the page says plainly: use the URL for a screen, and the plugin when you
+want a whole product in one pass, or have no token, or are rate limited.
+
+**`figma_frame` describes the URL route first.** Its own description still
+said `designFile` was "the one to use for a whole screen", which was true
+only while the URL route could not resolve component names. An agent reads
+that description before it picks a route, so it was steering towards the long
+way round. It now leads with the URL and keeps the file export for what the
+file export is actually better at: a whole product in one pass, or no usable
+token. The `llms.txt` preamble said nothing about the URL route at all, and
+now says it is the shortest path from a design to a screen.
+
+**The components are out of beta.** Only the MCP server still carries the
+label, and it carries it in both places that matter: the docs page and the
+`figma_frame` tool description an agent reads.
+
+The one that was doing damage was in the agent skill, which is always in an
+agent's context. It said **"Always pass `--beta`"** and explained that without
+it you get the 1.x set. That had inverted: `--beta` became a no-op that prints
+a deprecation notice, 2.x is what `add` installs, and `--legacy` is what
+reaches 1.x. An agent following the skill was passing a dead flag and being
+told the opposite of what the CLI does. The flag table now documents
+`--legacy` instead, and says plainly that the 1.x set is unmaintained.
+
+Also gone from the CLI's own output ("Redesigned beta components" when a name
+does not match), the `llms.txt` preamble, which told every model that read the
+site that the components were beta and their APIs might change, and the README
+and architecture notes. `--beta` is still accepted, because scripts use it.
 
-The only previous mention of "MCP" in the skill was WebMCP, the DataGrid's
-browser-agent surface, which is a different thing entirely.
+### Fixed
 
-**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.
+**Headings on the translated pages had meaningless ids.** The slugger kept
+only `[a-z0-9\s-]`, which leaves a Malayalam heading with nothing but its
+spaces — so every heading fell through to `section` or to the `-` its spaces
+became, and then took its id from the duplicate counter:
 
-The two pages now read in the order they are used — Theming, Agent skill,
-MCP server.
+    id="-"  id="--1"  id="--2"  id="-structured-data"  id="section-2"
+
+That counter is positional, so adding a heading renumbered every anchor below
+it: no link to one could be relied on, and four prop-table links on
+`ml/breadcrumb` and `ml/button` pointed at the English anchors and had never
+resolved. The class keeps letters, digits and combining marks in any script
+now, so those headings slug to their own text. `\p{M}` matters as much as
+`\p{L}` here: Malayalam vowel signs are combining marks, and dropping them
+mangles the text rather than emptying it. Every ASCII heading slugs to the
+same string as before, so no existing anchor moved.
+
+`pnpm check:anchors` in `docs-site` now checks every in-site fragment against
+the headings its target page actually offers, because a dead anchor does not
+404 — the page loads and ignores it.
+
+## 2.6.3
+
+### Fixed
 
 **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
@@ -40,11 +183,51 @@ 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.
 
+**The Figma plugin's listing is in review**, which Figma is quoting at a
+few weeks. Every place that links it now says so and gives the interim
+path: clone the repository and import `figma-plugin/manifest.json` through
+**Plugins → Development → Import plugin from manifest...** in the desktop
+app. The build is committed, so there is nothing to compile.
+
+**Six links in the docs went nowhere.** `datagrid.mdx` and
+`fileuploader.mdx` pointed at `#column-options`, `#grid-api-ref`,
+`#server-side-pagination`, `#upload-protocol`, `#custom-transport` and
+`#server-implementation` as same-page anchors. Those sections moved to
+child pages when the docs were split and the links were never updated, so
+they had been doing nothing since. They point at the child pages now.
+
+### Changed
+
 **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.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.
+
 ## 2.6.1
 
 ### Changed

package/README.md

@@ -141,6 +141,11 @@ Details in [`tools/mcp/README.md`](tools/mcp/README.md).
 
 [**Grampro Kit on the Figma Community**](https://www.figma.com/community/plugin/1692828324805361551)
 
+> In review — Figma is quoting a few weeks. Until it clears, clone this
+> repository and import `figma-plugin/manifest.json` through **Plugins →
+> Development → Import plugin from manifest...** in the Figma desktop app.
+> The build is committed, so there is nothing to compile.
+
 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.
@@ -192,10 +197,16 @@ have edited is never replaced without `--force`.
 The 2.x line is in active development and the next release will be a major
 version. What is built and tested:
 
-- 27 beta components, source-first, zero runtime dependencies
-- Passports for all 27, generated and drift-checked
+- 27 components, source-first, zero runtime dependencies
+- Passports for all 27, generated and drift-checked, and all 27 now carry the
+  authored half too: what the component is for, what it supplies to assistive
+  technology, and which props an agent may change without altering behaviour
 - The DataGrid agent runtime: 21 operations, five validation layers, snapshot
   undo, and a frozen 231-case evaluation corpus
+- The field runtime: `setValue`, `clear`, `focus` and, where there is something
+  to disclose, `open` and `close` — on Input, Textarea, NumberInput, Checkbox,
+  Switch, RadioGroup, Combobox and DatePicker. The same five layers, written
+  once in `shared/core/agent` rather than eight times
 - **`<DataGrid ai />`** — a natural-language box, driven by an adapter the
   application supplies. No model is bundled, downloaded or named.
 - **WebMCP** — one tool, `operate_grid`, exposing the same validated boundary to
@@ -206,10 +217,17 @@ Every producer — a model, a browser agent, a form — proposes. The validator
 authorizes. The executor mutates state. That boundary is the architecture, and
 it is why no AI path gets a second route into the component.
 
-Still open: operations for DatePicker and Combobox (both are controlled
-components with no imperative write API, which the executor abstraction is meant
-to solve but has not yet proven), and the remaining authored passport metadata.
-The roadmap and its unresolved questions are in
+Nine of the 27 are agent-operable. The executor abstraction was the open
+question — a grid is driven through an imperative API, and a field is not — and
+it is settled: Combobox and DatePicker are driven through their handles,
+Input, Textarea, NumberInput, Checkbox, Switch and RadioGroup through the
+element their ref already hands back. Neither the contract, the schemas, the
+validator nor the refusals know which.
+
+Still open: the components whose value is in what they contain rather than what
+they hold — Menu, Tabs, Accordion, Modal, FileUploader — and the question of
+whether a form is better driven field by field or as one composite assembled
+from several passports. The roadmap and its unresolved questions are in
 [`docs/agent-native-architecture.md`](docs/agent-native-architecture.md).
 
 ## Styles