basalt-ui 1.21.0 → 1.23.0

package/AGENTS.md

@@ -75,6 +75,14 @@ bunx basalt-ui info --json       # stable JSON surface map
 bunx basalt-ui guard-hook        # PreToolUse theme-guard adapter: reads a Write/Edit payload on stdin, denies off-palette writes
 ```
 
+`check-theme`, `doctor` and `sync` resolve their project identically: `BASALT_CWD` wins, then the
+cwd, then the workspace packages the root declares, then a two-level layout scan (which is what a
+repo with no `workspaces` field and the install one level down needs). Two candidates is ambiguous
+and reported, never guessed. `sync` on a `tokens-only` consumer prints `n/a` and exits 0.
+
+**Checking what an upgrade actually does? Run the local bin, not `bunx`.** `bunx` does not
+re-resolve a cached package, so it can execute the version you just upgraded away from.
+
 Register `guard-hook` in `.claude/settings.json` under `hooks.PreToolUse` with matcher
 `Write|Edit|MultiEdit` and command `bunx basalt-ui guard-hook` so the agent can't write off-palette
 colors without a `theme-allow` comment.
@@ -87,7 +95,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.22.0), 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,36 @@
+# [1.23.0](https://github.com/jkrumm/basalt-ui/compare/v1.22.0...v1.23.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* make sync resolve, and report, what the other two commands already do ([fcc5d3b](https://github.com/jkrumm/basalt-ui/commit/fcc5d3b862e90db03be9ae3daddbde56da15e415))
+* make the two annotation parsers agree, and pin the whole shape grid ([5a25825](https://github.com/jkrumm/basalt-ui/commit/5a25825342930236e35a4c8ecd1157fc6c3c8eda))
+* stop a non-finite absent share painting a band that never renders ([e8fae5b](https://github.com/jkrumm/basalt-ui/commit/e8fae5b205a9f74b31289591f8948f50a3e647eb))
+* teach chart-in-raw-surface the two new kinds ([fc34a3b](https://github.com/jkrumm/basalt-ui/commit/fc34a3bed4e05083288dcd22fc1e4b2cc81a1863))
+* teach unframed-chart the two new kinds too ([cb4e5b7](https://github.com/jkrumm/basalt-ui/commit/cb4e5b7977ff8a141bc4ec78d3c18b515fc41fed))
+
+
+### Features
+
+* give CartesianChart the x tick-VALUES seam its band siblings already have ([d94137d](https://github.com/jkrumm/basalt-ui/commit/d94137d20d496e8da1e0e0869c01d2d4c1577560))
+* let basaltAppPlugin's icons option name a real icon file ([c0b182e](https://github.com/jkrumm/basalt-ui/commit/c0b182e580c6289b5018be9d840a588e29dea5d3))
+* playground routes for BandStrip and MirroredBars ([ba6172d](https://github.com/jkrumm/basalt-ui/commit/ba6172d9ad40cf7b1e3c183e2598e79b5326c2e7))
+* two banded chart kinds — BandStrip and MirroredBars ([0e4f5f7](https://github.com/jkrumm/basalt-ui/commit/0e4f5f7107e71be92eb3b6bec6ebf5587d5c607b))
+
+# [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,13 @@ 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, 1.22.0 and
+`Unreleased` sections were written against source, not against their commit messages. Check the
+types, not this table, if the two disagree.
+
+**The newest section is headed `## Unreleased`, and stays that way until npm serves it.** This file
+is written before `semantic-release` picks the number, so a number written here is a guess — and it
+was wrong three rounds running.
 
 **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
@@ -25,7 +29,199 @@ at 1.3.0, `./agent-chat` at 1.10.0.
 
 ---
 
-## 1.20.1 — the `theme-allow` grammar
+## Unreleased
+
+**The heading has no number on purpose.** Three rounds running, the newest heading here named a
+version npm never served — `1.20.1`, then `1.21.1` — because this file is written before
+`semantic-release` computes the number, and a `feat:` in the batch turns the guess into a phantom.
+`shipped-versions.test.ts` now fails any file `init`/`sync` copy into a consumer that names a
+version `CHANGELOG.md` does not record. This file is not in that set; the same discipline applies
+by convention. Rename the section at release, or leave it — a reader can resolve `Unreleased`
+against `CHANGELOG.md`, and could never resolve `1.21.1`.
+
+**No export removed or renamed; six new runtime exports and nine new types.** Nothing you wrote
+changed. Every entry is additive, and the batch runs the other way from the last three: those made
+the guard stricter, this one makes the framework more expressive.
+
+**Two chart kinds `CartesianChart` structurally could not host.** It renders `AxisLeftNumeric`
+unconditionally and builds x as `scalePoint` — positions, no widths. `BandStrip` has no y dimension
+to axis; `MirroredBars` has two, and needs band widths. Both compose `ChartFrame` directly and
+declare themselves with `theme-allow-file hand-rolled-plot`, alongside `DualPanel`.
+
+| New on `basalt-ui/charts`                                                | Note                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BandStrip` (+ `BandStripProps`, `BandStripSeries`, `BandSpan`)          | 1-D categorical bands. `getBand(d) => { state, fill?, absentFraction?, marker? }`; `series` IS the state set, so a strip cannot name a state it does not draw. `cursorResolution` defaults `'leading'`                                                    |
+| `MirroredBars` (+ `MirroredBarsProps`, `MirroredBarPane`)                | two bar panes, one x scale, one baseline, independent domains. `up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`; plus `upFraction` (the up pane's share of the band height, where the baseline sits), `getAbsentFraction`, `getBarOpacity` |
+| `foldBands` (+ `BandFold`, `BandTooltipConfig`, `BandTooltipRowContext`) | the width-driven fold both kinds run, exported so a consumer can test their `merge` against the real grouping                                                                                                                                             |
+| `HatchPattern`, `hatchFill`, `hatchSizeFor`                              | the absence fill                                                                                                                                                                                                                                          |
+
+The shared choreography lives in an internal `useBandPlot` — **not exported**, deliberately: it is
+the kinds' contract with each other, not a public seam.
+
+**`MirroredBars` reverses a recorded decision, and the recorded reason for it was wrong.** The old
+entry in `docs/CHARTS-SPEC.md` read _"no two-bar-pane kind with independent per-pane scales"_, with
+_"a second consumer asks"_ as its trigger. That trigger never fired. Round 4 framed the blocker as
+independent SCALES; `DualPanel` already had `topYDomain`/`bottomYDomain`, so that was never it. The
+real blockers are that `DualPanel`'s top pane is a LINE pane and its bottom takes one SIGNED
+`getBar` over a symmetric domain. A decision recorded against the wrong blocker outlives its own
+refutation.
+
+**`xTickValues?: (keys, xMax) => readonly string[]` on `CartesianChart`**, forwarded by `Bars`,
+`MultiLine`, `StackedArea`, `ZonedLine` and both band kinds. It resolves AHEAD of `xTicks`, which is
+unchanged and still works; omit both and ticks are chosen to fit (`smartTicks`), exactly as before.
+Reach for it on a dense time axis: the tick choosers append the final key unconditionally, so a
+COUNT that does not land on the last index paints two labels on top of each other at the right edge
+— at every count, not at an unlucky one. On the consumer that reported it, the local tick helper
+went 200 → 160 lines; it shrinks, it does not disappear.
+
+**`basaltAppPlugin`'s `icons` takes an array now.**
+
+```ts
+icons?: false | { dir?: string } | readonly BasaltAppIcon[]
+// BasaltAppIcon = { src, sizes?, type?, purpose?, rel? }
+icons: [{ src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' }]
+```
+
+Every entry becomes a manifest icon; an entry reaches the head only when it names a `rel` (`'icon' |
+'shortcut icon' | 'apple-touch-icon' | 'mask-icon'`) — which is what lets an app whose `index.html`
+already links its favicon take the generated manifest without a duplicate tag. An empty array reads
+as `false`, i.e. no `icons` member rather than an empty one. `{ dir }` and the default are
+byte-identical to before. **If you kept a hand-written `manifest.webmanifest` because the plugin
+could not name your icon, you can delete it now** — with its permanent `theme-allow-file` — the
+generated manifest reproduces it member for member, plus an `id` a hand-written copy usually lacks.
+
+**CLI: a repo root with no `workspaces` field was invisible to everything.** With the install one
+level down and nothing declaring it, `check-theme` printed "no off-palette colors" having scanned
+**zero files** and `doctor` inferred `tokens-only` for a full Mantine consumer. `resolveProjectDir`
+now falls back to a bounded two-level layout scan when there is nothing declared to read; a declared
+`workspaces` still wins, and 2+ candidates stays ambiguous. `BASALT_CWD` is honoured by all three
+commands now, not two.
+
+- **`sync` is profile-aware.** A `"basalt": { "profile": "tokens-only" }` consumer has no scaffold
+  to reconcile, so `sync` prints `n/a` and exits 0 — `sync --check` is now wirable into a
+  tokens-only repo's CI. It used to refuse and prescribe `basalt-ui init`, the one command that
+  would have written a competing install.
+- **`DESIGN.md` version rot is healed, not re-stamped.** The stamp was never a constant: `DESIGN.md`
+  is a **seed**, written once and never reconciled, so the same line read 1.0.0 / 1.9.0 / 1.21.0 /
+  1.22.0 under one install. Reported as four doc bugs over three rounds; it was one. The template
+  names no version and `sync` rewrites openers already written.
+
+**The `theme-allow` shape grid is enumerated, not collected.** The reported fifth hole was three:
+the closer-alone-on-its-line shape that got reported, a `MAX_COMMENT_BLOCK_LINES = 8` budget
+truncating the walk inside a ~12-line docblock (not a JSX shape at all), and the plugin requiring
+the annotation's comment to be the LAST one above the node — so a reason wrapped onto a second `//`,
+a shape argo writes, reported under oxlint while the guard waived it. The grid now runs the four
+axes that vary (comment style × token position × where the closer falls × what follows), pinned row
+for row in `src/guard/check-source.test.ts` (37 supported + 8 asserted-unsupported) and
+`configs/oxlint-plugin.test.ts` (32 + 8; the guard's extra five rows are CSS/HTML/JSON dialects
+oxlint never sees). Zero disagreements, down from five — **and no waiver tally moved in any of the
+seven consumer repos.**
+
+Asserting the unsupported cells is the point: it stops "unsupported" and "silently broken" reading
+the same. What does NOT waive, in both halves:
+
+| Shape                                                                                                            | Why                                                                                       |
+| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| a blank line between annotation and code — after `//`, after `{/* */}`, or after a `{/*` whose closer sits alone | a blank line is how you say "this comment is not about the next statement"                |
+| the token mid-sentence in a line comment, a docblock gutter, or a JSX expression comment                         | prose that MENTIONS the token is not an annotation — the reason it must START its comment |
+| the token inside a string literal                                                                                | same                                                                                      |
+| above a multi-line OPENING tag, with the finding on a later attribute line                                       | a waiver reaches the first line below its comment, not an arbitrary line further down     |
+
+**Corrected consumer findings.** _"`sync` scaffolds 19–20 files into a consumer root"_ **did not
+reproduce** — those runs used a stale `bunx` cache of 1.20.0, and `bunx` does not re-resolve a
+package it already has. Check an upgrade against the local bin. Round 6's _"`doctor` exits 0 on hard
+failures"_ was a pipe artifact (`$?` read after `| tail`) and was already withdrawn.
+
+## 1.22.0 — 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. The manifest is now **honest** about
+icons — it is not yet **sufficient**. If you went hybrid over the 404s, dropping the hand-written
+half here costs you every icon unless your `public/` matches basalt's six filenames: at this
+release `icons` was still `false | { dir?: string }` over those six, so an app whose icon is
+`favicon.svg` could pick between a manifest naming two PNGs it never builds and a manifest with no
+`icons` member at all. The array form that fixes it is in `## Unreleased`. 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. A thirteen-shape matrix — every shape a consumer
+had been SEEN to write — is pinned in both halves, `src/guard/check-source.test.ts` and
+`configs/oxlint-plugin.test.ts`. **The claim that followed it here, that the two parsers could
+therefore no longer disagree, was false when it was written**: a list of collected anecdotes cannot
+close a contract. Three more holes were open at this release. See `## Unreleased`.
+
+| 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 +269,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 +353,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 +489,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.22.0      |
 | `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 +504,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.22.0 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)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -436,8 +441,20 @@ import { CartesianChart, LinePath, VX } from 'basalt-ui/charts'
 </CartesianChart>
 ```
 
-Shipped kinds (`Bars`, `MultiLine`, `StackedArea`, `ZonedLine`, `Donut`, `DualPanel`, `Heatmap`)
-are that same composition, pre-wired.
+Shipped kinds (`Bars`, `MultiLine`, `StackedArea`, `ZonedLine`, `Donut`, `DualPanel`, `Heatmap`,
+`BandStrip`, `MirroredBars`) are that same composition, pre-wired. The last five compose
+`ChartFrame` directly, because a ring, a matrix, two panes or a strip is not a single plot rect:
+**`BandStrip`** draws 1-D categorical bands with no y dimension at all (`CartesianChart` renders a
+left numeric axis unconditionally, so it could never host one), and **`MirroredBars`** draws two
+bar panes over one x scale and one baseline, each in its own domain. Both fold their domain by
+width, hatch the share of a slot nothing measured, and share the page cursor like every other
+chart.
+
+Which x ticks get painted is `xTickValues?: (keys, xMax) => readonly string[]`, on
+`CartesianChart` and forwarded by `Bars`/`MultiLine`/`StackedArea`/`ZonedLine` and both band kinds.
+It resolves ahead of the `xTicks` COUNT, which is unchanged; omit both and ticks are chosen to fit.
+Reach for values on a dense time axis — the tick chooser appends the final key unconditionally, so
+a count that misses the last index collides two labels at the right edge at every count.
 
 ### `./query` — TanStack Query adapter
 
@@ -639,8 +656,15 @@ bun add -D vite-plugin-pwa workbox-build workbox-window   # only if serviceWorke
 Without the peer installed, `serviceWorker: true` degrades to a one-line console warning (no
 service worker, no crash) — everything else (theme-color meta, anti-FOUC background,
 `site.webmanifest`, favicon/apple-touch-icon links, OG/Twitter defaults) works with zero extra
-dependencies. Full doctrine, plugin ordering, and the bring-your-own icon filenames:
-`agent/rules/basalt-app.md`.
+dependencies.
+
+`icons` takes `false | { dir?: string } | readonly BasaltAppIcon[]`. The array form names the icons
+the app actually has, with the manifest's own field names (`src`, `sizes`, `type`, `purpose`) plus
+an optional `rel` — every entry becomes a manifest icon, and only an entry naming a `rel` reaches
+the head. `icons: [{ src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' }]` is a complete,
+installable icon set for a single-page app. An empty array reads as `false`; `{ dir }` and the
+default are byte-identical to what they always emitted. Full doctrine, plugin ordering, and the six
+default icon filenames: `agent/rules/basalt-app.md`.
 
 ---
 
@@ -684,12 +708,35 @@ bunx basalt-ui help              # full usage; every subcommand also takes --hel
 ```
 
 `doctor` reports **`SKIPPED`** as a third outcome beside pass/warn/fail and exits non-zero on it —
-"All checks passed" is only printable when every check actually ran. `check-theme` and `doctor`
-honour `BASALT_CWD`, and relocate to the single workspace package carrying a basalt config when
-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.
+"All checks passed" is only printable when every check actually ran. **`check-theme`, `doctor` and
+`sync` all resolve their project the same way**: `BASALT_CWD` wins, then the cwd itself, then the
+workspace packages the root declares, then a two-level layout scan. Two candidates is reported as
+ambiguous, never guessed. The scan is what a repo declaring **no `workspaces` field** needs — with
+the install one level down and nothing declaring it, every command answered about the root and
+found nothing there: `check-theme` printed "no off-palette colors" having scanned zero files, and
+`doctor` inferred `tokens-only` for a full Mantine consumer. `tokens:css` and `fonts:css` both take
+`--check` as a CI drift gate.
+
+**Verify an upgrade against the local bin, not `bunx`.** `bunx` does not re-resolve a package it
+has already cached, so a `bunx basalt-ui …` run can execute a version you upgraded away from —
+which is exactly how a fixed defect gets re-reported. Prefer `./node_modules/.bin/basalt-ui` (or
+`bun run` a script that does) when the point of the run is to check what the installed version
+does.
+
+`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. On a
+`"basalt": { "profile": "tokens-only" }` consumer there is no scaffold to reconcile, so `sync`
+prints `n/a` and exits 0 — `sync --check` is wirable into a tokens-only repo's CI without a
+special case. `sync` also heals a `DESIGN.md` opener that still names a version: the file is a
+**seed**, written once and never reconciled, so any number stamped into it was stale by the next
+release.
+
+**`sync` refreshes an existing install; it does not create one.** It resolves its project exactly as
+`check-theme` and `doctor` do, and since 1.22.0 **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.22.0 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
@@ -190,9 +195,34 @@ Generate the set with `@vite-pwa/assets-generator` (or realfavicongenerator.net)
 source image — it lives in the CONSUMER's own devDependencies, not basalt-ui's. `basalt-ui doctor`
 warns (does not fail) when `public/` exists but is missing one of these files.
 
+**If your `public/` does not match those six filenames, name your icons instead.** `icons` takes
+`false | { dir?: string } | readonly BasaltAppIcon[]`, and an array uses the manifest's own field
+names verbatim:
+
+```ts
+basaltAppPlugin({
+  name: 'rb',
+  icons: [{ src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' }],
+})
+```
+
+`BasaltAppIcon` is `{ src, sizes?, type?, purpose?, rel? }`, `rel` being one of `'icon'`,
+`'shortcut icon'`, `'apple-touch-icon'`, `'mask-icon'`. **Every entry becomes a manifest icon; an
+entry reaches the head only when it names a `rel`** — which is what lets an app whose `index.html`
+already links its favicon take the generated manifest without a duplicate tag. An empty array reads
+as `false` (no `icons` member, rather than an empty one). `{ dir }` and the default are byte-identical
+to what they always emitted.
+
+One SVG at `sizes: 'any'` is a complete, installable icon set for a single-page app — and it is the
+shape every non-scaffolded consumer already has. If you keep a hand-written `manifest.webmanifest`
+only because the plugin could not name your icon, delete it: the generated manifest reproduces it
+member for member, including the two hexes derived from `SURFACE.bg` rather than hand-copied, and it
+takes the permanent `theme-allow-file` on that file with it.
+
 `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.22.0
+`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)