basalt-ui 1.22.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.
@@ -88,7 +96,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,22 @@
+# [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,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.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. 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
@@ -20,12 +24,115 @@ 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`.
+
+**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,
@@ -74,14 +181,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 +491,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,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
 
@@ -644,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`.
 
 ---
 
@@ -689,17 +708,32 @@ 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.
+"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.
+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.

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.
@@ -195,8 +195,32 @@ 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 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.
 

package/agent/rules/basalt-charts.md

@@ -58,11 +58,13 @@ radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
   compose `CartesianChart`. **Since 1.20.0 every assembly node is reported and waived on its own**
   — one comment no longer grants the whole file permanent immunity, which is how a 604-line chart
   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.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
+  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix, or a
+  strip with no y dimension) declares the whole file with `theme-allow-file hand-rolled-plot —
+<why>`, anywhere in it; basalt's own tree carries three, on `DualPanel`, `BandStrip` and
+  `MirroredBars`. `Donut` and `Heatmap` are non-single-plot too and carry none — they render no
+  assembly primitive, so the rule never fires and there is nothing to waive.
+  **`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"
   cannot fire inside X.
 - **`basalt/chart-legend-literal`** — a hand-written array literal passed to `ChartLegend`'s
@@ -160,6 +162,13 @@ ships no map kind.
    onto one domain value, silently dropping one from the plot (see #6 below for why that's the
    cursor's problem too). `Heatmap` is deliberately excluded: its existing `colLabel`/`rowLabel`
    already are that seam, and a second prop over one concern would fork them.
+   **Which x ticks get painted is a separate seam**, `xTickValues?: (keys, xMax) => readonly
+string[]`, on `CartesianChart` and forwarded by `Bars`/`MultiLine`/`StackedArea`/`ZonedLine`
+   plus both band kinds. Resolution order is explicit VALUES → explicit COUNT (`xTicks`, unchanged)
+   → as many as fit (`smartTicks`); omit both and nothing moves. Reach for it on a dense time axis,
+   because **a count cannot express one**: `smartTicks`/`smartTicksEvery` append the final key
+   unconditionally, so any count that does not land exactly on the last index paints two labels on
+   top of each other at the right edge — at every count, not at an unlucky one.
    **The x axis is CATEGORICAL, and this is not inferable from the API.** `CartesianChart` builds
    its x scale as `scalePoint<string>`, so N points are N evenly spaced positions whatever the
    values behind the keys — there is no linear or time x scale. Correct and invisible for a domain
@@ -332,6 +341,24 @@ per-series `getValue` accessors on `ChartSeries<T>`):
   wrapper.
 - **`Donut`** — proportional donut with an optional center-content overlay. Composes `ChartFrame`
   directly (radial, not cartesian).
+- **`BandStrip`** — 1-D categorical bands over a shared x axis, **no y dimension at all**: one rect
+  per slot, `getBand(d) => { state, fill?, absentFraction?, marker? }`. `series` IS the state set —
+  it drives the legend, each band's fill and the one derived tooltip row, so a strip cannot name a
+  state it does not draw. `absentFraction` paints the share of a folded slot nothing measured as a
+  hatch; `marker` carries a fact that must not be readable off the `fill` ramp. `cursorResolution`
+  defaults `'leading'` here (a band IS a bucket), not `'nearest'`. Composes `ChartFrame` directly —
+  `CartesianChart` renders `AxisLeftNumeric` unconditionally, so this shape could never use it.
+- **`MirroredBars`** — two BAR panes over one x scale, mirrored around one baseline, each pane in
+  its own domain. `up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`; `upFraction`
+  (default 0.35) is the up pane's share of the band height, which is where the shared baseline sits;
+  `getAbsentFraction` hatches an unmeasured slot and `getBarOpacity` dims one. A sibling of
+  `DualPanel`, not an extension: `DualPanel`'s top pane is a LINE pane and its bottom takes one
+  SIGNED `getBar` over a symmetric domain. Two independent magnitudes are not one signed quantity.
+  Composes `ChartFrame` directly.
+
+Both band kinds fold their domain by width (`fold: { minBandPx?, merge }`), and `foldBands` is
+exported so a consumer can test their merge against the grouping that will actually run.
+`HatchPattern` / `hatchFill` / `hatchSizeFor` ship the absence fill.
 
 `ZonedLine` and `MultiLine` also accept `xZones?: XZoneSpec[]` — the vertical counterpart to a
 kind's horizontal zone bands, for marking a time window rather than a value range. Each
@@ -477,6 +504,14 @@ margin. Passing `y2` to get a dual-axis chart no longer needs a manual margin nu
 The escape hatch is `margin={{ left: n }}` (`Partial<ChartMargin>`) on `CartesianChart` — a per-side
 override applied LAST, after measurement, so it always wins.
 
+**A band plot has one extra law, because a band axis puts its FIRST tick on the plot's left edge.**
+With no left axis to measure, `autoMargin` stops at `VX.margin.left` and half the first x label
+hangs off the canvas — so `BandStrip` floors its left gutter at half the widest x label, mirroring
+what `autoMargin` already does on the right. Both terminal gutters are then capped (14% of width
+left, 12% right): uncapped, half a `DD.MM HH:MM` label is 48px of a 338px chart. `MirroredBars`
+probes real tick labels from both panes, so it takes the plain measured margin and neither the
+floor nor the cap applies.
+
 `chartMargin(opts?)` (`basalt-ui/tokens`, also re-exported from `basalt-ui/charts`) still exists,
 but only matters for a bespoke chart that composes `ChartFrame` directly (not `CartesianChart`) and
 needs a right-axis-sized margin without running its own measurement pass — `DualPanel` and `Heatmap`

package/agent/rules/basalt-tokens.md

@@ -96,6 +96,22 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
   still ends the block; that is how you say "this comment is not about the next statement".
 - **`basalt/hand-rolled-plot` grants whole-file immunity only through `theme-allow-file`.** Every
   assembly node is otherwise waived on its own.
+- **Eight shapes are asserted NOT to waive, in both halves.** They are pinned as unsupported rather
+  than merely left out, so "unsupported" and "silently broken" stop reading the same. Don't write
+  them:
+
+  | Shape                                                                                                                              | Why it does not waive                                                                                               |
+  | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+  | a blank line between the annotation and the code — after `//`, after `{/* */}`, or after a `{/*` whose closer sits on its own line | 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, when the finding sits on a later attribute line                                                    | a waiver reaches the first line below its comment, not an arbitrary line further down — put it beside the attribute |
+
+  The whole grid — four axes, comment style × token position × where the closer falls × what
+  follows — is pinned row for row in `src/guard/check-source.test.ts` (37 supported + these 8) and
+  `configs/oxlint-plugin.test.ts` (32 + 8; five of the guard's rows are CSS/HTML/JSON dialects
+  oxlint never sees). Zero disagreements between the two, and no waiver tally moved in any of the
+  seven consumer repos.
 
 ### Audit them: `basalt-ui check-theme --audit-allows`
 
@@ -141,7 +157,7 @@ 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: basalt consumers only, and component-shaped declarations only.** Since 1.21.1 the rule
+- **Scope: basalt consumers only, and component-shaped declarations only.** Since 1.22.0 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/agent/skills/basalt-charts/SKILL.md

@@ -16,9 +16,9 @@ everything below assumes — composing `CartesianChart` (single-plot) or `ChartF
 Before writing chart code, decide which of three paths you are on:
 
 1. **Reuse a shipped kind.** basalt-ui ships `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`,
-   `DualPanel`, `Heatmap`, `Donut`. If the shape matches, use it — props are declarative (`data`,
-   `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per axis, zones/thresholds/refLines
-   as plain arrays). Done.
+   `DualPanel`, `Heatmap`, `Donut`, `BandStrip`, `MirroredBars`. If the shape matches, use it —
+   props are declarative (`data`, `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per
+   axis, zones/thresholds/refLines as plain arrays). Done.
    - **`ZonedLine`** — a single-series line with zone bands, thresholds, x-zones, refLines.
    - **`Bars`** — 1+ stacked positive/negative bar series, optional line overlays, dual-axis config.
    - **`StackedArea`** — opaque stacked bands, auto cumulative-top y-domain.
@@ -33,6 +33,13 @@ Before writing chart code, decide which of three paths you are on:
    - **`Heatmap`** — category×category intensity grid (`color-mix` alpha), per-cell tooltip,
      optional gradient legend strip. Replaces bespoke time-of-day.
    - **`Donut`** — proportional donut, optional `centerContent` overlay.
+   - **`BandStrip`** — 1-D categorical bands, no y dimension: one rect per slot,
+     `getBand(d) => { state, fill?, absentFraction?, marker? }`. `series` is the state set and
+     drives legend, fill and the one derived tooltip row. Replaces a bespoke state/availability
+     strip.
+   - **`MirroredBars`** — two BAR panes over one x scale and one baseline, each in its own domain
+     (`up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`). Not `DualPanel`, whose top
+     pane is a LINE and whose bottom takes one SIGNED accessor.
 2. **Extract a new kind (second instance of a pattern).** When you are about to build the _second_
    chart of a shape that has no shipped kind, extract a kind. Don't extract on the first; don't
    wait past the third. A new kind lives in the consumer's chart kinds dir (or, if generic enough
@@ -43,6 +50,12 @@ Before writing chart code, decide which of three paths you are on:
    genuinely different scales that don't fit any kind's config surface) composes `CartesianChart`
    or `ChartFrame` directly in the page's chart file — not in `kinds/`.
 
+**Extracting a kind? Prove it by porting.** A kind is proven by moving a real consumer's call
+sites onto it and reporting what it could NOT express — not by a demo page, which is written
+against the API that already exists. The two band kinds were built that way (linewatch, 1884 → 957
+source lines, 11 `hand-rolled-plot` waivers retired, two live `NaN`-geometry bugs found). Ship the
+"still cannot express" list with the kind.
+
 > Anti-pattern: a single `<Chart type="..." config={...} />` god-component that switches by kind.
 > That is the Recharts trap. Prefer N small kinds. **If a chart doesn't fit the primitives, add a
 > kind — don't loosen the primitives.**
@@ -109,8 +122,9 @@ Theme tuning of these series happens in the theme lab — pass them as `groups`
 ## Compose the primitives (never hand-roll)
 
 Every chart — kind or bespoke — composes `CartesianChart` for a single plot rect, or `ChartFrame`
-directly for a multi-pane / non-cartesian shape (`DualPanel`'s two panes, `Heatmap`'s grid,
-`Donut`'s ring). Either way the contract is the same: the primitive owns margin, scales, grid,
+directly for a multi-pane / non-cartesian shape — five of them ship: `DualPanel`'s two panes,
+`MirroredBars`' two bar panes, `BandStrip`'s missing y dimension, `Heatmap`'s grid, `Donut`'s ring.
+Either way the contract is the same: the primitive owns margin, scales, grid,
 axes, legend, the shared cursor, and the tooltip; you supply `series` and draw ONLY marks. This is
 mandatory, not a convention — `basalt/hand-rolled-plot` fails the build on a bypass (see "Respect
 the boundary" below); it is easier to compose it than to work around it.
@@ -212,9 +226,10 @@ import { ChartCursorScope } from 'basalt-ui/charts'
   primitive (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`)
   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.21.0 spelling and it is required. The file that defines
-  `CartesianChart` is exempt definitionally.
+<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `MirroredBars`,
+  `BandStrip`; `Heatmap` and `Donut` render no assembly primitive and need none) 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
   (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it) so it can't name a series the plot no

package/agent/templates/DESIGN.md.tpl

@@ -1,6 +1,8 @@
 # {{APP_NAME}} — Design
 
-> Managed by basalt-ui ({{BASALT_VERSION}}). This is a **thin** instantiation — it records this
+> Managed by basalt-ui — run `basalt-ui doctor` for the version, never trust a number written into
+> a file (this one is a seed: written once at `init`, then owned by you, so any version stamped
+> here would be frozen at scaffold time). This is a **thin** instantiation — it records this
 > app's **deltas only** on top of the shipped `basalt-*` rules. The universal law (earned color,
 > neutral-by-default, three-tier `--vx-*` tokens, theme-is-data, the chart primitive contract, the
 > elevation/density/shape doctrine) lives in those rules and the `/basalt:design` skill, and is