basalt-ui 1.22.0 → 1.23.1

package/AGENTS.md

@@ -62,21 +62,38 @@ duration/spring/ease literal in a `transition={{...}}` prop (enforced by `basalt
 
 ## Key commands
 
+`init` and `tokens:css`/`fonts:css` are the only commands with no install to resolve, so `bunx` is
+correct for them and wrong for everything else — see the note below.
+
 ```bash
-bunx basalt-ui init              # FIRST STEP: scaffold .claude/rules/ + .claude/skills/, managed CLAUDE.md block, DESIGN.md seed, toolchain seeds
-bunx basalt-ui check-theme       # fail on off-palette colors in consumer source
-bunx basalt-ui sync              # reconcile managed files (.claude/rules/, .claude/skills/, CLAUDE.md block)
-bunx basalt-ui sync --check      # CI freshness gate — exits non-zero if any managed file drifted
-bunx basalt-ui doctor            # integration health — SKIPPED is a third outcome and exits non-zero
-bunx basalt-ui tokens:css        # emit the --vx-* stylesheet (no React, no Mantine, no bundler)
-bunx basalt-ui fonts:css         # emit the shipped --basalt-font-* stacks
-bunx basalt-ui info              # print published surface map
-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
+bunx basalt-ui init         # FIRST STEP: scaffold .claude/rules/ + .claude/skills/, managed CLAUDE.md block, DESIGN.md seed, toolchain seeds
+basalt-ui --version         # one bare line, exit 0 — which CLI is actually running (also -v / version)
+basalt-ui check-theme       # fail on off-palette colors in consumer source
+basalt-ui sync              # reconcile managed files (.claude/rules/, .claude/skills/, CLAUDE.md block)
+basalt-ui sync --check      # CI freshness gate — exits non-zero if any managed file drifted
+basalt-ui doctor            # integration health — SKIPPED is a third outcome and exits non-zero
+bunx basalt-ui tokens:css   # emit the --vx-* stylesheet (no React, no Mantine, no bundler)
+bunx basalt-ui fonts:css    # emit the shipped --basalt-font-* stacks
+basalt-ui info --json       # stable JSON surface map
+basalt-ui guard-hook        # PreToolUse theme-guard adapter: reads a Write/Edit payload on stdin, denies off-palette writes
 ```
 
+Every subcommand rejects a flag it does not accept, exiting 1 and naming it; an unknown command says
+so above the usage block. Neither is ever ignored — `doctor --json` used to run doctor and exit 0.
+
+`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.
+
+**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 — one consumer filed a P0 against a 1.20.0 cache while
+believing it was on 1.22.0. `init` and `sync` render every seeded script, CI step and hook with the
+resolved local bin for this reason (`BASALT_BIN` overrides it). `basalt-ui --version` is the
+one-second check.
+
 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
+`Write|Edit|MultiEdit` and command `./node_modules/.bin/basalt-ui guard-hook` (what `init` seeds) so the agent can't write off-palette
 colors without a `theme-allow` comment.
 
 **The escape hatch is `theme-allow <rule-id> — <reason>`**, scoped to that one kind and to that one
@@ -88,7 +105,7 @@ over the declaration it terminates. Whole-file scope is `theme-allow-file <id>
 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. It judges
-plugin-rule waivers too (since 1.21.1), by re-running oxlint — so it needs oxlint reachable;
+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

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [1.23.1](https://github.com/jkrumm/basalt-ui/compare/v1.23.0...v1.23.1) (2026-08-22)
+
+
+### Bug Fixes
+
+* gate the two chart tag rules on where the tag came from ([0075224](https://github.com/jkrumm/basalt-ui/commit/007522416bf9a3269e5f45b7ae7f45203434bae7))
+* make the CLI answer which version ran, and stop it failing open ([0edf50e](https://github.com/jkrumm/basalt-ui/commit/0edf50e1d6f61b349f989fd10fe384d4a91a9af1))
+* stop a typo'd band state from asserting absence ([6c1515c](https://github.com/jkrumm/basalt-ui/commit/6c1515c3ecbf019d9971e5b247e81e5cce3ae316))
+
+# [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)
 
 

package/MIGRATING.md

@@ -8,9 +8,14 @@ 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.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.
+row that was wrong. That pass corrected 4 table rows and 3 prose claims. Every section from 1.21.0
+on was written against source, not against its commit messages — which is not a formality: one
+1.23.0 commit message describes a change it did not make (see `Unreleased` § Corrections). 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
@@ -20,12 +25,196 @@ 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 except 1.21.1. Additive-only subpaths: `./tokens.css`
+1.10.0, 1.13.0, 1.14.0, 1.16.0, 1.18.0 — and every patch. Additive-only subpaths: `./tokens.css`
 at 1.3.0, `./agent-chat` at 1.10.0.
 
 ---
 
-## 1.21.1 — the toolchain stops overclaiming
+## 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`.
+
+**One type widened, nothing removed or renamed.** `BandStripSeries.formatValue` is now
+`(d: T) => string | null`. `null` renders an em dash — an absent READING — which `''` never could:
+`''` is a state whose label is the whole row. Every existing `(d) => string` still typechecks.
+
+**A typo'd `BandSpan.state` no longer renders as absence.** A state naming no `series` entry used to
+be skipped, so the band was simply not drawn — and on a measured/not-measured strip a missing band
+is a claim about the data, not an "unknown". A misspelling asserted a reading nobody took, in a mark
+indistinguishable from a real one.
+
+| Key comes off                                                 | Dev                                      | Production                                                               |
+| ------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
+| the DATUM — `BandSpan.state`, `marker.state`                  | throws, naming the key and the valid set | a dashed neutral outline band + an `Unknown state` / `<key>` tooltip row |
+| a PROP — `absentState`, `MirroredBars`' `up.key` / `down.key` | throws                                   | throws                                                                   |
+
+The split is the whole design. `state` comes off data, so a feed that grows a state basalt has never
+seen must degrade rather than take a dashboard down — while a typo, which is the same input, still
+fails loudly wherever it is being written. The dashed neutral outline belongs to no legend entry and
+no state fill, so it cannot read as data. Pane keys are props, never data-driven, so `assertPaneKey`
+throws in every environment: an unresolvable `up.key` used to hide the pane AND its axis, which
+reads as "that half measured zero" — the one thing `MirroredBars` exists to keep apart from absence.
+
+**`chart-missing-aria-label` and `unframed-chart` are gated on where the tag came from.** Both key
+on a JSX tag NAME, so a consumer's own 235-line `MirroredBars` — sharing nothing with the shipped
+kind but the name — was told to pass an `ariaLabel` prop it does not accept, by a rule that presents
+as a correctness finding. A tag is now skipped only when the file DEFINES a component of that name
+and does not also import it from `basalt-ui`. Deliberately one-directional: a tag imported from
+basalt-ui, one imported from a consumer barrel that re-exports it, and one the scan cannot attribute
+at all still all fire. Verified old-vs-new over **945 source files across six repos: 0 findings
+lost, 0 gained.**
+
+**CLI: `--version` exists, and no subcommand fails open on a flag.** `--version` / `-v` / `version`
+print one bare greppable line and exit 0, resolved BEFORE dispatch so it can never run a command to
+answer "which basalt-ui is this". Six consumer reports reached for it in one round; all six fell
+back to `info --json`.
+
+The larger fix sits underneath it. **Every subcommand validates its flags** and exits 1 naming the
+one it does not accept — `doctor --json` used to run doctor and exit **0**, and `check-theme
+--audit-allow` scanned and reported success. An unknown COMMAND now says so above the usage block
+instead of dumping help and letting the dump read like a choice.
+
+- **`doctor` reads `basaltAppPlugin({ icons })`** out of the consumer's vite config instead of
+  hardcoding six filenames, so adopting 1.23.0's icons array stops producing a warning to generate
+  five files you deliberately lack. A named array is checked against itself (an icon missing from
+  `public/` still warns); an unparseable or absent config falls back to the six-filename check. It
+  can only narrow, never blind.
+- **`doctor` and `sync` share one sentence about a parent install** (`parentInstallAdvice`). Run
+  from a package whose install is above it, `doctor` now names the parent and says `basalt-ui init`
+  is NOT the fix. Following its old advice literally scaffolded the second consumer that 1.22.0
+  exists to prevent.
+- **Every seeded invocation resolves the local bin** (`basaltBinCommand`, overridable via
+  `BASALT_BIN`): the `lint` script, the CI steps, the `.claude` PreToolUse hook and doctor's own
+  advice all render `./node_modules/.bin/basalt-ui`. `bunx` does not re-resolve a package it has
+  cached — that is what made a round-7 report file a P0 against a 1.20.0 cache while believing it
+  was on 1.22.0, and the seed was shipping `bunx` into consumer CI in ten places.
+  `configs/lefthook.yml`'s `${BASALT_BIN:-bunx --no-install basalt-ui}` default is unchanged and
+  deliberate: `--no-install` fails loudly instead of downloading a stranger.
+- **`tokens:css --check` blanks the provenance line (line 2) before comparing**, so a version bump
+  alone no longer forces a no-op commit in a tokens-only consumer, where the gate is byte-equality.
+  A stale provenance line is now a note on an otherwise-passing check. The `@generated` header is
+  still emitted byte-identical — the line stays, it just stops gating.
+
+### Corrections to the record
+
+- **All six round-8 reports said `basalt-ui --version` "exits 0 printing usage". It exited 1, to
+  stderr** — the dispatcher's `default:` branch has always been `console.error(USAGE); return 1`.
+  The real fail-open was an unknown FLAG, which no report tested, and the misdiagnosis was relayed
+  verbatim into the fix brief. Report the symptom you measured, not the one you inferred from it.
+- **`cb4e5b7`'s message is wrong** (`b9b99a6` on `origin/feat/round-7-band-kinds` is the same commit
+  pre-merge), and it is on `master` where it cannot be rewritten. It claims it taught
+  `unframed-chart` the two new kinds; it widened `CHART_ENTRY_POINT_TAG`, which only
+  `chart-missing-aria-label` reads. `unframed-chart` keys on `<ChartLegend items={[` and carries no
+  kind list at all — there was never an asymmetric pair to fix.
+- **Open question, not a plan.** The import gate does not make `CHART_ENTRY_POINT_TAG` or the oxlint
+  plugin's `CHART_TAGS` redundant: that list still answers _which_ tags owe an `ariaLabel`. The gate
+  only converts a kind missing from the list from a false positive into an under-report. Collapsing
+  the two lists is a separate, larger change and has not been made.
+
+## 1.23.0 — two band kinds, an x-tick seam, CLI resolution
+
+**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 → 170 lines; it shrinks, it does not disappear. (The promise was 160. The 10-line miss is
+docblock — the port's own JSDoc grew, because the helper stopped being a fallback and became the one
+seam every chart on the page passes through.)
+
+**`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,
@@ -74,14 +263,20 @@ 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.
+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. 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.
+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                                     |
 | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
@@ -378,7 +573,7 @@ deleting an entry forces the level flip in the same commit.
 | `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.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.21.0, narrowed at 1.21.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

package/README.md

@@ -261,7 +261,7 @@ 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 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 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`
@@ -441,8 +441,30 @@ 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.
+
+On a strip, `series` IS the state set, so a `state` naming no entry has no colour, no legend entry
+and no tooltip row. It **throws in dev**, naming the key and the valid set; in production it draws a
+dashed neutral outline band — a treatment no legend entry and no state fill uses — plus an
+`Unknown state` tooltip row. Drawing nothing was the old behaviour and the wrong one: on a
+measured/not-measured strip a missing band claims a coverage gap. `absentState` and `MirroredBars`'
+`up.key`/`down.key` are PROPS rather than data, so those throw in every environment; an
+unresolvable pane key used to hide the pane and its axis, which reads as a measured zero.
+`BandStripSeries.formatValue` returns `string | null`, `null` rendering an em dash — an absent
+reading, distinct from `''`, which is a state whose label is the whole row.
+
+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
 
@@ -644,8 +666,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`.
 
 ---
 
@@ -675,34 +704,58 @@ Current slots: `series` (read by `./charts` + `./tokens`), `commands` (read by `
 ## CLI
 
 ```bash
-bunx basalt-ui init              # scaffold doctrine into a consumer repo
-bunx basalt-ui sync              # three-way diff against .basalt/manifest.json after a basalt-ui upgrade
-bunx basalt-ui sync --check      # CI drift gate — non-zero exit on any managed-file drift
-bunx basalt-ui check-theme       # palette guard — fails on colors that bypass the central --vx-* system
-bunx basalt-ui doctor            # integration health: basalt-resolves, guard-scan, oxlint-preset, manifest presence, node_modules-vs-manifest version, spacing-scale drift, and a cross-package `ai` major-version parity check (HARD failure — walks every workspace manifest, exemptable via `basalt.aiMajorSkewReason` — see above) + warn on missing basaltAppPlugin icon files under public/
-bunx basalt-ui doctor --tokens-only   # force the Mantine-free profile (auto-detected otherwise; --framework forces the full set)
+bunx basalt-ui init              # scaffold doctrine into a consumer repo — the one command with no install to resolve
+basalt-ui --version              # one bare line, exit 0 (also -v / version) — which CLI is actually running
+basalt-ui sync                   # three-way diff against .basalt/manifest.json after a basalt-ui upgrade
+basalt-ui sync --check           # CI drift gate — non-zero exit on any managed-file drift
+basalt-ui check-theme            # palette guard — fails on colors that bypass the central --vx-* system
+basalt-ui doctor                 # integration health: basalt-resolves, guard-scan, oxlint-preset, lefthook-preset, manifest presence, node_modules-vs-manifest version, spacing-scale drift, and a cross-package `ai` major-version parity check (HARD failure — walks every workspace manifest, exemptable via `basalt.aiMajorSkewReason` — see above) + warn on an icon file basaltAppPlugin references and public/ does not have
+basalt-ui doctor --tokens-only   # force the Mantine-free profile (auto-detected otherwise; --framework forces the full set)
 bunx basalt-ui tokens:css --out src/tokens.css     # emit the --vx-* stylesheet as a file you own
 bunx basalt-ui fonts:css --out src/fonts.css       # emit the shipped --basalt-font-* stacks
-bunx basalt-ui info              # human-readable surface map: subpath, layer, rule, skills, optional peers
-bunx basalt-ui info --json       # same map as stable JSON (InfoOutput shape)
-bunx basalt-ui help              # full usage; every subcommand also takes --help / -h
+basalt-ui info --json            # surface map as stable JSON (InfoOutput shape); bare `info` is the human-readable form
+basalt-ui help                   # full usage; every subcommand also takes --help / -h
 ```
 
+**Nothing fails open.** `--version` resolves before dispatch, so it can never run a command to
+answer which CLI ran. Every subcommand validates its flags and exits 1 naming the first one it does
+not accept — `doctor --json` used to run doctor and exit **0**, and `check-theme --audit-allow`
+scanned and reported success. An unknown command says so above the usage block.
+
 `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.
+"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, comparing everything but the header's provenance line — so a
+basalt-ui version bump alone never forces a no-op commit in a tokens-only consumer.
+
+**Run 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 how one consumer
+filed a P0 against a 1.20.0 cache while pinned to 1.22.0. `init` and `sync` now render every seeded
+script, CI step, hook and piece of doctor advice with the resolved `./node_modules/.bin/basalt-ui`
+(`BASALT_BIN` overrides it, and `configs/lefthook.yml` keeps `bunx --no-install` as a deliberately
+loud fallback). `basalt-ui --version` is the one-second check.
 
 `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.
+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.21.1 **exits 1** when the resolved project has no
+`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.
+Creating an install is `basalt-ui init`'s decision — and `doctor` now says the same sentence from
+the same directory, where it used to prescribe `init` and so recommend the very scaffold that
+refusal exists to prevent.
 
 ---
 

package/agent/rules/basalt-app.md

@@ -99,7 +99,7 @@ Run `basalt-ui doctor` afterwards to confirm the wiring took. A check that canno
 ### The lefthook preset overrides YOU, not the other way round
 
 `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`,
+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.
@@ -193,10 +193,40 @@ web-app-manifest-512x512.png
 
 Generate the set with `@vite-pwa/assets-generator` (or realfavicongenerator.net) from a single
 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.
+warns (does not fail) when `public/` exists but is missing one of these files — and it now
+parses `basaltAppPlugin`'s `icons` option out of your vite config first, so it checks the files you
+declared rather than the six it assumes. `icons: false` or an empty array is "nothing to check"; an
+unparseable or absent config falls back to the six defaults. Adopting the array is no longer a way
+to earn a warning.
+
+**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. **Delete that app's own
+`<link rel="manifest">` in the same change** — the plugin injects its own, so leaving both ships two
+manifest links pointing at different files, one of them a 404 the moment the hand-written file goes.
 
 `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 icons. Since 1.21.1
+`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.