basalt-ui 1.21.0 → 1.22.0

package/AGENTS.md

@@ -87,7 +87,9 @@ over the declaration it terminates. Whole-file scope is `theme-allow-file <id>
 `theme-allow-file` waives nothing. A bare `theme-allow` still waives everything on its placement but
 reports `theme-allow-unscoped`. A word in the id slot that names no rule waives nothing.
 `.json`/`.webmanifest` use a `"basalt:theme-allow[-file]"` member. Audit them all with
-`basalt-ui check-theme --audit-allows`, which exits 1 on a waiver that suppresses nothing.
+`basalt-ui check-theme --audit-allows`, which exits 1 on a waiver that suppresses nothing. It judges
+plugin-rule waivers too (since 1.21.1), by re-running oxlint — so it needs oxlint reachable;
+otherwise the verdict is "cannot judge", never "dead".
 
 > **Framework-internal only** — `bunx basalt-ui check-coverage` is a self-consistency gate for the
 > basalt-ui repo itself (asserts SURFACES ↔ rule files ↔ skill files ↔ package.json exports). It

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.22.0](https://github.com/jkrumm/basalt-ui/compare/v1.21.0...v1.22.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* let `icons: false` reach the manifest it was only skipping in the head ([58abe27](https://github.com/jkrumm/basalt-ui/commit/58abe27be10e5baf7c4659aa79904a7646ff092d))
+* scope the shadow-export tripwire to basalt consumers, and to components ([60716d4](https://github.com/jkrumm/basalt-ui/commit/60716d4ba00908c1a157f5568e192c6c50e438ec))
+* stop sync scaffolding a second consumer, and give the audit the oxlint half ([45cf3d3](https://github.com/jkrumm/basalt-ui/commit/45cf3d340f081e61f3f10f852d12f79928993d2a))
+
+
+### Features
+
+* give the waiver audit an annotation reader, and fix two shapes ([0dde850](https://github.com/jkrumm/basalt-ui/commit/0dde85052269780a61ead0688005db16e24f009a))
+
 # [1.21.0](https://github.com/jkrumm/basalt-ui/compare/v1.20.0...v1.21.0) (2026-08-22)
 
 

package/MIGRATING.md

@@ -8,9 +8,9 @@ renamed exports per minor, with the replacement.
 Reconstructed from `git diff` over the published export surface across `v1.0.0..v1.19.1`, then
 cross-checked against the repo's `scripts/export-surface.json` snapshot. **Every replacement below
 was re-audited against the built declaration files at 1.20.0 (2026-08-22)** after round 5 caught one
-row that was wrong. That pass corrected 4 table rows and 3 prose claims. The 1.20.1 section was
-written against source, not against its commit messages. Check the types, not this table, if the two
-disagree.
+row that was wrong. That pass corrected 4 table rows and 3 prose claims. The 1.21.0 and 1.21.1
+sections were written against source, not against their commit messages. Check the types, not this
+table, if the two disagree.
 
 **No majors, by policy.** A rename or a removal ships as a plain `feat:` on the 1.x line, so a minor
 bump can require code changes. Skipping several at once is the expensive case — read every section
@@ -20,12 +20,95 @@ between your version and the target.
 > `## [1.` finds only the patches.
 
 **Minors with no public API delta:** 1.1.0, 1.3.0, 1.4.0, 1.5.0, 1.6.0, 1.7.0, 1.8.0, 1.9.0,
-1.10.0, 1.13.0, 1.14.0, 1.16.0, 1.18.0 — and every patch. Additive-only subpaths: `./tokens.css`
+1.10.0, 1.13.0, 1.14.0, 1.16.0, 1.18.0 — and every patch except 1.21.1. Additive-only subpaths: `./tokens.css`
 at 1.3.0, `./agent-chat` at 1.10.0.
 
 ---
 
-## 1.20.1 — the `theme-allow` grammar
+## 1.21.1 — the toolchain stops overclaiming
+
+**No export removed or renamed; four added.** Nothing you wrote changed. Every entry below is a
+check that reported an answer it had not earned, so a green CI on 1.21.0 was, for several of them,
+green over an empty set.
+
+**`sync` refuses where it used to scaffold.** Run from a sub-package that depends on basalt-ui but
+holds no `.basalt/manifest.json` — `apps/dashboard`, `apps/web` — it printed `0 updated, 20
+recreated`, wrote a second `basalt` key, and stood up a complete competing install beside the real
+one at the repo root. argo and rb both reverted it by hand. It now resolves its project exactly as
+`check-theme` and `doctor` do, and **exits 1** when the resolved project has no manifest, naming the
+install it found above instead. The refusal runs before the `basalt.roots` backfill, which was half
+the damage. Two ways to unblock it:
+
+```bash
+cd <the package holding .basalt/manifest.json> && bunx basalt-ui sync
+BASALT_CWD=<that package> bunx basalt-ui sync   # or from anywhere
+```
+
+The summary line gained a `created` counter. **`recreated` now means what it always claimed** — the
+ledger placed that file once and it went missing. Twenty first-time writes were never that.
+
+**`--audit-allows` judges plugin-rule annotations.** They used to print "not a check-theme kind" and
+drop out of the exit-1 gate, so the gate covered an empty set wherever the waivers were plugin
+rules: argo's whole tally was `0 live, 0 dead, 8 outside reach`, and 11 of linewatch's 14 went the
+same way. Each is now probed by re-running oxlint over that one file with the annotation
+neutralized. Judged now: argo 8 of 8, linewatch 14 of 14, basalt's own tree 23 of 23.
+
+**It requires oxlint to be reachable.** The probe writes one neutralized sibling file and re-runs
+oxlint over it (oxlint has no stdin mode), removing it in a `finally`. Where oxlint cannot run, the
+annotation is reported as **"cannot judge"**, never as dead. The report now also prints the scope it
+audited — `0 dead` over `basalt.roots` was reading as `0 dead anywhere`.
+
+**`doctor`'s `lefthook-preset` check asks a different question.** It tested whether the config text
+contained the `extends` string. It now asks whether the gate EXISTS, via `lefthook dump`, which
+resolves `extends`, `include` and per-command `root:`. linewatch wires all three jobs with
+`root: 'web/'` precisely because `extends` merges commands _without_ their working directory — it
+was correctly configured, got warned, and the old advice would have broken it. Three outcomes: a
+broken `extends` target is still a hard fail, a provably absent gate is a warn, and where
+`lefthook dump` could not run you get an advisory warning naming what it could not see.
+
+**`basalt/shadow-basalt-export` narrowed twice.** It now gates on `isBasaltScopedFile` like every
+other rule in the file, and needs a component-SHAPED declaration — a function, an arrow, a
+`memo`/`forwardRef` wrapper, or a class extending one. It had been firing on a `SlugTracker` class
+in a React-free package carrying no basalt-ui dependency, telling it to import from basalt-ui. The
+stated limit is unchanged: exact-name-only, a tripwire, not coverage.
+
+**`basaltAppPlugin({ icons: false })` now omits the manifest's `icons` member too.** It skipped the
+head `<link>` icons and emitted the two PNG manifest entries anyway, so `{ manifest: true, icons:
+false }` shipped an installable app pointing at two 404s. **If you went hybrid over this** — the
+plugin for the head, a hand-written manifest for the rest — **you can drop the hand-written half.**
+The option's JSDoc said "skips the head `<link>` icons"; it now says what the option does.
+
+**Two `theme-allow` comment shapes were silently broken and now work.** Plainly: this is the fourth
+hole found in this one contract in three rounds. The full thirteen-shape matrix is now pinned in
+both halves — `src/guard/check-source.test.ts` and `configs/oxlint-plugin.test.ts` — so the two
+parsers can no longer disagree about what an annotation IS.
+
+| Shape                                         | What it did                                                                                                                | Now                                     |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `/** theme-allow <id> — <why> */` on one line | waived under oxlint, reported under `check-theme`                                                                          | both halves honour it                   |
+| `{/*` + token on the next line + `*/}`        | comment-stripping left a bare `}`, so the line read as CODE and the annotation was classified trailing — scoped to a brace | scoped to the node below it, as written |
+
+**linewatch writes that wrapped shape for every hand-composed chart axis**, so any _guard_ kind
+annotated that way was silently unwaivable. It only appeared to work because the rules it names
+(`hand-rolled-plot`) live in the oxlint plugin, whose placement test is comment-node-based and never
+saw the brace.
+
+**New, additive — `./guard` gains four runtime exports**, the reader half of the audit:
+
+| Export                                       | Note                                                                                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `findAllowAnnotations(text, relPath, cfg)`   | every annotation as written, ids split into `guardKinds` / `pluginRules` / `unknownRules`. Shares `collectAllowAnnotations` with `checkSource`, so it cannot list a line the scan does not honour |
+| `neutralizeAllowAnnotation(text, line, cfg)` | one annotation rewritten to the token below, every other left intact — the probe half of an audit                                                                                                 |
+| `NEUTRALIZED_ALLOW_TOKEN`                    | so a guard probe and an oxlint probe neutralize identically                                                                                                                                       |
+| `PLUGIN_RULE_IDS`                            | the ids only oxlint can judge                                                                                                                                                                     |
+
+The `AllowAnnotationSite` type ships alongside them.
+
+**Known gaps, reported and not fixed:** `--audit-allows` says nothing about `basalt.exempt` — a
+whole file removed from the scan, the broadest exception the config surface has — and its
+`scoped to …` line does not distinguish `theme-allow` from `theme-allow-file`.
+
+## 1.21.0 — the `theme-allow` grammar
 
 **No export removed or renamed.** One break, and it is in the escape hatch itself: **file scope must
 now be spelled `theme-allow-file`.** At 1.20.0 an annotation that named a rule and gave a reason —
@@ -73,7 +156,7 @@ manifest, `basaltAppPlugin` is the first remedy, since a hand-copied hex drifts
 | Change                                                                     | What to do                                                                                                                                                                                                                                                |
 | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `createSearchParamStore` / `createMultiSearchParamStore` gain `linkSearch` | replace every nav link's `search: { <param>: '<literal>' }` with `search: <store>.linkSearch`, passed BY REFERENCE. A module-scope literal pins the fallback on every click — argo's reader had ZERO call sites, so "remember my window" had never worked |
-| `BasaltShell` collapse moves to `createPersistedState`                     | the key is now `basalt:<storageKey>` holding `{ v, value }`; read it with `readPersistedValue(storageKey, 1)`. A one-time migration adopts the raw pre-1.20.1 value, so the sidebar does not re-expand on upgrade                                         |
+| `BasaltShell` collapse moves to `createPersistedState`                     | the key is now `basalt:<storageKey>` holding `{ v, value }`; read it with `readPersistedValue(storageKey, 1)`. A one-time migration adopts the raw pre-1.21.0 value, so the sidebar does not re-expand on upgrade                                         |
 
 **New, additive:**
 
@@ -157,7 +240,7 @@ the rule AND giving a reason is what `hasFileDeclaration` matches, at any line
 intended for one node silences the file. Dropping the reason keeps it node-scoped in the oxlint
 plugin, but then `check-theme` reports `theme-allow-unscoped ("no reason")`. The two halves of the
 contract intersect at exactly one legal shape and that shape is whole-file. Write the declaration in
-the component's docblock, where it reads as the file-level decision it is. **Fixed in 1.20.1** —
+the component's docblock, where it reads as the file-level decision it is. **Fixed in 1.21.0** —
 see that section; the declaration moves to `theme-allow-file`.
 
 **`doctor` will go red.** `SKIPPED` is a third outcome beside pass/warn/fail and exits non-zero on
@@ -293,9 +376,9 @@ deleting an entry forces the level flip in the same commit.
 | `basalt/agent-no-raw-usechat`      | 1.10.0 as `warn` | **1.13.0**                                                               |
 | `basalt/agent-resume-guard`        | 1.10.0 as `warn` | **1.13.0**                                                               |
 | `basalt/raw-size-literal`          | 1.7.0 as `warn`  | **1.20.0**                                                               |
-| `basalt/hand-rolled-plot`          | 1.15.0 as `warn` | still `warn` — widened again at 1.20.1; grace restarts with the widening |
+| `basalt/hand-rolled-plot`          | 1.15.0 as `warn` | still `warn` — widened again at 1.21.0; grace restarts with the widening |
 | `basalt/chart-legend-literal`      | 1.15.0 as `warn` | still `warn` — widened at 1.20.0                                         |
-| `basalt/shadow-basalt-export`      | 1.20.0 as `warn` | may stay `warn` permanently — widened at 1.20.1                          |
+| `basalt/shadow-basalt-export`      | 1.20.0 as `warn` | may stay `warn` permanently — widened at 1.21.0, narrowed at 1.21.1      |
 | `basalt/hand-rolled-shell`         | 1.20.0 as `warn` | —                                                                        |
 
 `card-with-border`, `inline-display`, `raw-html-layout`, `raw-form-control`, `raw-font-family` and
@@ -308,7 +391,7 @@ in the shipped preset). A config still naming `import-boundary` after 1.1.0 disa
 
 ## Deprecated, not yet removed
 
-The 32 camelCase `--vx-*` aliases deprecated in 1.5.0 are **still emitted at 1.20.1**.
+The 32 camelCase `--vx-*` aliases deprecated in 1.5.0 are **still emitted at 1.21.0**.
 `buildPaletteCss({ legacyAliases: false })` / `tokens:css --no-legacy-aliases` opts out now; a later
 minor flips the default.
 

package/README.md

@@ -224,7 +224,7 @@ Other keys (`exempt`, `severity`, `spacingSteps`, `forbiddenAccents`, …) are d
 **`exemptRules`** turns one kind off along a path. A pattern is a relative path
 (`public/site.webmanifest`, or `src/agent` for everything under it), a glob (`*` stops at `/`, `**`
 does not, and a slash-free glob is also tried against the basename, so `*.module.css` works), or a
-bare path segment — the legacy shape, and the one nobody guesses, since before 1.20.1 it was the
+bare path segment — the legacy shape, and the one nobody guesses, since before 1.21.0 it was the
 ONLY shape and a real relative path matched nothing and said nothing. The object form records the
 reason, which is what a `theme-allow` always carried and this key could not. A pattern that
 suppresses nothing is now reported by a normal run and fails `--audit-allows`.
@@ -242,7 +242,7 @@ stylesheet `tokens:css` just wrote is not reported back at you, pasting the mark
 suppresses nothing, and an ordinary declaration smuggled into a sheet wearing the header is
 reported on its own line.
 
-**The escape hatch is scoped, and since 1.20.1 the two scopes are spelled apart:**
+**The escape hatch is scoped, and since 1.21.0 the two scopes are spelled apart:**
 
 ```text
 theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
@@ -252,7 +252,7 @@ theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules
 ```
 
 An annotation must **start** its comment (after `//`, `/*`, `<!--`, a block gutter `*`, or
-whitespace) — before 1.20.1 any comment merely mentioning the token parsed as the bare blanket form,
+whitespace) — before 1.21.0 any comment merely mentioning the token parsed as the bare blanket form,
 so a file documenting its own waivers disarmed itself. Placements: the reported line, a comment-only
 line directly above it (the only form JSX can express, and it reaches the first CODE line below,
 walking through the rest of its comment block), or — in CSS — a trailing comment reaching back over
@@ -260,8 +260,13 @@ the declaration it terminates. The id slot is read strictly: a word there that n
 nothing, so a typo is never the blanket form.
 
 `basalt-ui check-theme --audit-allows` reports every annotation and every `exemptRules` entry with
-what it still suppresses, proved by re-running the guard with that one waiver neutralized. Exits 1
-on a dead waiver, so it is usable as a CI gate.
+what it still suppresses, proved by re-running the scan with that one waiver neutralized. Exits 1 on
+a dead waiver, so it is usable as a CI gate. Since 1.21.1 it runs **both** halves — `checkSource` for
+a guard kind, oxlint over one neutralized sibling file for a plugin rule — so a waiver naming
+`hand-rolled-plot` is judged rather than skipped. **It needs oxlint reachable**; where it is not, the
+verdict is "cannot judge", never "dead". The report prints the scope it audited, because `0 dead`
+over `basalt.roots` is not `0 dead anywhere`. Two known gaps: `basalt.exempt` is not audited at all,
+and the `scoped to …` line does not distinguish `theme-allow` from `theme-allow-file`.
 
 `doctor`'s `ai-major-parity` hard check fails a monorepo where workspace packages declare different
 `ai` package majors — unless the split is intentional and written down. A producer pinned to an
@@ -294,7 +299,7 @@ deleted rather than silently surviving into the next real skew.
 | `./tokens`          | **free** | `VX` token refs, `buildPaletteCss`, `defineSeries`, `seriesTokens`, `groupTokens`, `alpha`, `ColorPair` / `SeriesMap` types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `./theme-lab`       | coupled  | `ThemeLabControls`, `applyOverrides`, `loadOverrides`, `COLOR_GROUPS` for live theme inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `./vite`            | —        | `basaltViteConfig(opts)` — Vite preset for basalt-ui consumer apps; `basaltAppPlugin(opts)` — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core; plus the annotation reader `--audit-allows` is built on: `findAllowAnnotations`, `neutralizeAllowAnnotation`, `NEUTRALIZED_ALLOW_TOKEN`, `PLUGIN_RULE_IDS`, `AllowAnnotationSite`                                                                                                                                                                                                                                                                                                                                                                                      |
 | `./query`           | **free** | `createBasaltQueryClient`, transport-agnostic `unwrap`, lazy `BasaltQueryDevtools`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `./router-tanstack` | **free** | TanStack Router bridge: `useBasaltNav` (active route) + `useRouterBreadcrumbs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `field`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -689,7 +694,15 @@ honour `BASALT_CWD`, and relocate to the single workspace package carrying a bas
 invoked from a repo root that has none (two candidates is reported as ambiguous, never guessed).
 `tokens:css` and `fonts:css` both take `--check` as a CI drift gate.
 
-`sync` strategy per file: unchanged since last write → overwrite; locally edited → skip (show diff); missing → recreate. `--force` overwrites local edits.
+`sync` strategy per file: unchanged since last write → overwrite; locally edited → skip (show diff);
+missing → recreate. `--force` overwrites local edits. The summary counts `created` and `recreated`
+apart: `recreated` means the ledger placed that file once and it went missing.
+
+**`sync` refreshes an existing install; it does not create one.** It resolves its project exactly as
+`check-theme` and `doctor` do, and since 1.21.1 **exits 1** when the resolved project has no
+`.basalt/manifest.json`, naming the install it found above instead of scaffolding a second one
+beside it. Run it at the package that holds the manifest, or point `BASALT_CWD` at that package.
+Creating an install is `basalt-ui init`'s decision.
 
 ---
 

package/agent/rules/basalt-app.md

@@ -98,12 +98,17 @@ Run `basalt-ui doctor` afterwards to confirm the wiring took. A check that canno
 
 ### The lefthook preset overrides YOU, not the other way round
 
-New in 1.20.1: `doctor`'s `lefthook-preset` check hard-fails when the repo-root lefthook config
-`extends` a path that does not resolve. That state is otherwise invisible — lefthook merges a
-missing target into **zero** commands and exits 0, so `lefthook dump` looks clean and the repo has
-no pre-commit gate with nothing anywhere saying so. It warns on a lefthook.yml wiring its own hooks,
-and is n/a with no lefthook at all. `sync` reports the same seam, since it is the command an upgrade
-actually runs and neither file is one basalt owns.
+`doctor`'s `lefthook-preset` check asks whether a pre-commit gate EXISTS — not whether your config
+contains the extends string. Since 1.21.1 it asks `lefthook dump`, which resolves `extends`,
+`include` and per-command `root:`. **Wiring the jobs yourself passes**: linewatch runs all three with
+`root: 'web/'` precisely because `extends` merges commands _without_ their working directory, and the
+old text match warned there and prescribed a change that would have broken it.
+
+A broken `extends` target is still a hard fail — lefthook merges a missing target into **zero**
+commands and exits 0, so `lefthook dump` looks clean and the repo has no gate with nothing saying so.
+A provably absent gate is a warn; a repo where `lefthook dump` could not run gets an advisory warning
+naming what it could not see. n/a with no lefthook at all. `sync` reports the same seam, since it is
+the command an upgrade actually runs and neither file is one basalt owns.
 
 **An `extends` target WINS on a colliding key.** Declare `pre-commit.commands.oxfmt.run` (or
 `glob:`) in your own file and the preset's value is what runs — yours is discarded silently. Only
@@ -160,7 +165,7 @@ site-wide OG/Twitter defaults from `options.seo`.
 plugins: [react(), ...basaltAppPlugin({ name: 'Argo', colorScheme: 'auto' })]
 ```
 
-Before 1.20.1 the anti-FOUC rule emitted `html{color-scheme:dark}` **unlayered**, which outranks
+Before 1.21.0 the anti-FOUC rule emitted `html{color-scheme:dark}` **unlayered**, which outranks
 Mantine's own `@layer mantine` declaration regardless of specificity — a light-scheme consumer got
 dark scrollbars, dark `<select>` popups and dark date pickers permanently, with no opt-out. The rule
 is now scoped to `html:not([data-mantine-color-scheme])`, so it expires the instant MantineProvider
@@ -191,8 +196,9 @@ source image — it lives in the CONSUMER's own devDependencies, not basalt-ui's
 warns (does not fail) when `public/` exists but is missing one of these files.
 
 `basaltAppPlugin` also emits `site.webmanifest` (served in dev too) with explicit `id`/`scope`/
-`start_url` — pass `manifest: false` to skip it, or `icons: false` to skip the icon `<link>` tags
-without touching the manifest.
+`start_url` — pass `manifest: false` to skip it, or `icons: false` to skip the icons. Since 1.21.1
+`icons: false` omits BOTH the head `<link>` tags and the manifest's `icons` member; before that it
+skipped only the head, so a manifest shipped naming two PNGs the app never builds.
 
 ## Service worker (opt-in)
 

package/agent/rules/basalt-charts.md

@@ -60,7 +60,7 @@ radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
   file went unpoliced. To waive ONE node, put `theme-allow hand-rolled-plot — <why>` on it (or on a
   comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix)
   declares the whole file with `theme-allow-file hand-rolled-plot — two panes over one x scale`,
-  anywhere in it; `DualPanel` carries the repo's only one. **`theme-allow-file` is the 1.20.1
+  anywhere in it; `DualPanel` carries the repo's only one. **`theme-allow-file` is the 1.21.0
   spelling** — at 1.20.0 a node-scoped annotation was silently promoted to a file declaration, so
   per-node scoping was not expressible; move the one word. The file that DEFINES `CartesianChart` is
   exempt definitionally (detected by declaration, not by path), since a rule saying "compose X"
@@ -95,7 +95,7 @@ ships no map kind.
 - **Want `@visx/geo` anyway?** Install it yourself — basalt doesn't pin it — and keep it under a
   `charts/` segment like every other visx import, same as any bespoke chart.
 - **Style map chrome with `--vx-*` tokens** (`VX.*`/`alpha()`) so it matches the rest of the app.
-- **The guard trap, narrowed at 1.20.1:** `check-theme`'s `inline-spacing` kind is a per-line regex
+- **The guard trap, narrowed at 1.21.0:** `check-theme`'s `inline-spacing` kind is a per-line regex
   over raw source, not an AST pass. A **unitless** number now only reports inside a style-object
   context (a `style=`/`sx=`/`css=` attribute, or a const whose name or type says styles), so a map's
   pixel geometry — `fitBounds({ padding: 48 })`, marker offsets — no longer trips it: an options bag

package/agent/rules/basalt-router.md

@@ -83,7 +83,7 @@ against it.
 - Update via `navigate({ search: { window: 'all', from: undefined, to: undefined } })` — prefer plain
   objects over reducers to avoid `| undefined` assignability errors when the schema has defaults.
 
-### Wire the reader, or the store does nothing (1.20.1)
+### Wire the reader, or the store does nothing (1.21.0)
 
 `validateSearch` is only half the store. It restores the value when you arrive with **no** param —
 it cannot do anything about a nav link that declares the param itself, and a link written

package/agent/rules/basalt-state.md

@@ -25,7 +25,7 @@ Pick the right home for each kind of state — don't dump everything into one st
 - **UI preferences that must survive navigation but aren't URL-worthy** (sidebar collapsed, panel
   layout, draft filters) → `createPersistedState` from `basalt-ui/state` — the framework's own
   versioned localStorage primitive (see below). `BasaltShell` persists its own collapse state
-  through that same primitive since 1.20.1; use `createPersistedState` for app-level preferences.
+  through that same primitive since 1.21.0; use `createPersistedState` for app-level preferences.
   Reach for a third-party store only when complex cross-component state genuinely warrants it (see
   escape hatch below).
 
@@ -67,7 +67,7 @@ const [layout, setLayout] = usePanelLayout()
 Keys are namespaced `basalt:<key>` automatically and never collide with the theme-scheme guard.
 Pass a `schema` (Standard Schema) to validate persisted values and fall back to `initial` on mismatch.
 
-### Mirroring `BasaltShell`'s collapse (changed key at 1.20.1)
+### Mirroring `BasaltShell`'s collapse (changed key at 1.21.0)
 
 `BasaltShell` used `@mantine/hooks`' `useLocalStorage` while `createPersistedState` was the
 documented house API — so a consumer reading the raw key was complying with the shipped component,
@@ -77,11 +77,11 @@ moves the key:
 ```ts
 import { readPersistedValue } from 'basalt-ui/state'
 
-// 1.20.1: localStorage['basalt:<storageKey>'] === '{"v":1,"value":true}'
+// 1.21.0: localStorage['basalt:<storageKey>'] === '{"v":1,"value":true}'
 const collapsed = readPersistedValue('basalt-sidebar-collapsed', 1)
 ```
 
-A one-time migration adopts the raw pre-1.20.1 value, so an upgrade does not silently re-expand
+A one-time migration adopts the raw pre-1.21.0 value, so an upgrade does not silently re-expand
 every sidebar. It is a bridge, not a format — do not write against it.
 
 ## Zustand escape hatch (complex cross-component stores)

package/agent/rules/basalt-tokens.md

@@ -43,7 +43,7 @@ The scan reaches slightly beyond `roots`: each root's PARENT contributes its `in
 meta and a webmanifest's `background_color` actually live. `.json` is never blanket-scanned — name a
 design-surface JSON in `basalt.include`, the only route to one.
 
-## `theme-allow` — the 1.20.1 contract
+## `theme-allow` — the 1.21.0 contract
 
 The full grammar, in both engines:
 
@@ -63,7 +63,7 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
 ```
 
 - **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block-comment gutter `*`,
-  or nothing but whitespace. Before 1.20.1 any comment that merely _mentioned_ the token parsed as
+  or nothing but whitespace. Before 1.21.0 any comment that merely _mentioned_ the token parsed as
   the bare blanket form and switched every rule off on the line below: linewatch documented its own
   waivers in a docblock and thereby disarmed the file. Prose about the escape hatch no longer waives
   anything; everything a consumer actually writes still qualifies.
@@ -71,7 +71,7 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
   Plain `theme-allow` is the node/line waiver in both engines. At 1.20.0 the two halves of the
   contract intersected at exactly one legal shape and that shape was whole-file — naming a rule and
   giving a reason was read as a file declaration, which is why per-node scoping did not actually
-  ship. **This is the consumer break in 1.20.1**: move each existing file declaration one word.
+  ship. **This is the consumer break in 1.21.0**: move each existing file declaration one word.
 - **A bare `theme-allow` still waives everything on its placement** but reports
   `theme-allow-unscoped` (`warn` for one minor, then `error`). A bare `theme-allow-file` waives
   nothing at all — whole-file blanket immunity off one unnamed comment is the thing this contract
@@ -141,7 +141,12 @@ nothing is forked.
 - **Exact name match only** — the one limit that is structural. Round 5 confirmed the miss rate:
   linewatch's forks are named `Cell` and `Box`, rb's is `Stat`. Rename the fork and the rule goes
   quiet, which is what a fork's author naturally does.
-- **Scope: everything importable.** Since 1.20.1 it reads all nine published barrels, not just
+- **Scope: basalt consumers only, and component-shaped declarations only.** Since 1.21.1 the rule
+  gates on `isBasaltScopedFile` like every other rule in the file, and needs a function, an arrow, a
+  `memo`/`forwardRef` wrapper or a class extending one. A plain data class sharing a name with a
+  shipped export is a collision, not a fork — it fired on a `SlugTracker` class in a React-free
+  package that cannot import basalt-ui.
+- **Scope: everything importable.** Since 1.21.0 it reads all nine published barrels, not just
   `dist/index.d.ts` — so the `basalt-ui/charts` layer, which is where forks actually live, is finally
   covered. Names a barrel merely re-exports from a third party are skipped: `./charts` passes
   `Bar` / `Line` / `Pie` straight through from `@visx/shape`, and a local `Bar` is not a fork of

package/agent/skills/basalt-app/SKILL.md

@@ -120,9 +120,10 @@ Lint wires as `oxlint . && basalt-ui check-theme` (seeded as the `lint:basalt` s
 guard is the teeth behind the token doctrine. Before writing any composite, check whether basalt
 already ships it: round 4 found ~15 forked copies of shipped components across seven repos, all
 passing every gate, because a fork by a token-fluent author uses exactly the right tokens.
-`basalt/shadow-basalt-export` reads all nine published barrels since 1.20.1 (the charts layer
-included), but it warns only on an **exact** name collision — round 5 found the renamed forks
-(`Cell`, `Box`, `Stat`) sail straight past it. It is a tripwire, not coverage; nothing catches the
+`basalt/shadow-basalt-export` reads all nine published barrels since 1.21.0 (the charts layer
+included), but it warns only on an **exact** name collision, in a basalt-scoped file, on a
+component-shaped declaration — round 5 found the renamed forks (`Cell`, `Box`, `Stat`) sail straight
+past it. It is a tripwire, not coverage; nothing catches the
 rest. Ask before you build; do not wait to be told.
 
 The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts` on

package/agent/skills/basalt-charts/SKILL.md

@@ -213,7 +213,7 @@ import { ChartCursorScope } from 'basalt-ui/charts'
   rendered in a file that doesn't compose `CartesianChart`, per NODE. Escape:
   `theme-allow hand-rolled-plot — <why>` on the one node, or `theme-allow-file hand-rolled-plot —
 <why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`,
-  `Donut`) declares itself. `-file` is the 1.20.1 spelling and it is required. The file that defines
+  `Donut`) declares itself. `-file` is the 1.21.0 spelling and it is required. The file that defines
   `CartesianChart` is exempt definitionally.
 - **No hand-authored legends.** `basalt/chart-legend-literal` fails the build on a hand-written
   array literal passed to `ChartLegend`'s `items` — derive it from the same `series` the chart draws

package/configs/oxlint-plugin.js

@@ -1332,11 +1332,37 @@ const chartLegendLiteral = {
 const PACKAGE_ROOT = resolvePath(PLUGIN_DIR, '..')
 
 /**
- * A component-shaped name: starts uppercase and carries a lowercase letter, which excludes the
+ * A component-shaped NAME: starts uppercase and carries a lowercase letter, which excludes the
  * SCREAMING_CASE constants and the two-letter token namespaces in the same barrel.
+ *
+ * A name test alone is not a component test — see {@link isComponentInit}. Every PascalCase binding
+ * passes this, which is how obsidian's `SlugTracker` (a plain data class in a React-free package)
+ * became a "forked component" the moment 1.21.0 widened the rule to all nine barrels.
  */
 const COMPONENT_NAME = /^[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$/
 
+/** The two wrappers a function component is legitimately declared inside. */
+const COMPONENT_WRAPPERS = new Set(['memo', 'forwardRef'])
+
+/**
+ * Is this initializer component-SHAPED — a function, an arrow, or one wrapped in `memo` /
+ * `forwardRef`?
+ *
+ * The second half of the fix for obsidian's false positive. `const Foo = new Map()` and
+ * `class SlugTracker {}` share a name with a basalt export and nothing else; a fork of a component
+ * is a function (or, historically, a class that `extends` one). Narrowing here costs the rule
+ * nothing it was ever meant to catch and removes the whole "PascalCase binding" false-positive
+ * class, which the nine-barrel widening made large.
+ */
+function isComponentInit(init) {
+  if (init === null || init === undefined) return false
+  if (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') return true
+  if (init.type !== 'CallExpression') return false
+  const callee = init.callee
+  const name = callee?.type === 'MemberExpression' ? callee.property?.name : callee?.name
+  return typeof name === 'string' && COMPONENT_WRAPPERS.has(name)
+}
+
 /**
  * The barrels a consumer can import a component FROM. The root one is not the whole surface: a
  * chart-layer fork (`ChartFrame`, `CartesianChart`, `ChartCard`, …) collided with nothing, because
@@ -1428,6 +1454,11 @@ const shadowBasaltExport = {
     // basalt's own source DEFINES these names; a consumer's does not.
     if (BASALT_EXPORTS.size === 0 || filename.startsWith(`${PACKAGE_ROOT}/`)) return {}
     if (isTestFile(context)) return {}
+    // Scoped exactly like `ai-sdk-major`, and for the same reason: a package with no basalt-ui
+    // dependency (or one outside a declared `basalt.roots`) cannot import the export it is accused
+    // of forking, so the advice — "import it from 'basalt-ui' instead" — is not followable there.
+    // obsidian's React-free `obsidian-vault-core` took the report and had to waive it.
+    if (filename.length === 0 || !isBasaltScopedFile(filename)) return {}
 
     const report = (node, name) => {
       if (typeof name !== 'string' || !BASALT_EXPORTS.has(name)) return
@@ -1440,9 +1471,14 @@ const shadowBasaltExport = {
         report(node, node.id?.name)
       },
       VariableDeclarator(node) {
+        if (!isComponentInit(node.init)) return
         report(node, node.id?.name)
       },
+      // A class only counts when it EXTENDS something — a legacy class component. basalt ships no
+      // class components, so a standalone `class X {}` sharing a name with one of its exports is a
+      // collision between two unrelated things, not a fork.
       ClassDeclaration(node) {
+        if (node.superClass === null || node.superClass === undefined) return
         report(node, node.id?.name)
       },
     }