@grampro/kit 2.6.3 → 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,5 +1,169 @@
 # Changelog
 
+## 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 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.
+
+### Fixed
+
+**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:
+
+    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

package/README.md

@@ -197,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
@@ -211,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