basalt-ui 1.20.0 → 1.21.0

package/AGENTS.md

@@ -79,11 +79,15 @@ Register `guard-hook` in `.claude/settings.json` under `hooks.PreToolUse` with m
 `Write|Edit|MultiEdit` and command `bunx basalt-ui guard-hook` 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. It is honoured
-on the reported line, on a comment-only line directly above it, and — in CSS — from a trailing
-comment back over the declaration it terminates. A bare `theme-allow` still waives everything but
-reports `theme-allow-unscoped`. A word in the id slot that names no rule waives nothing — only a
-genuinely bare comment is the blanket form.
+**The escape hatch is `theme-allow <rule-id> — <reason>`**, scoped to that one kind and to that one
+node/line. It must START its comment (after `//`, `/*`, `<!--`, a block gutter `*`, or whitespace),
+and is honoured on the reported line, on a comment-only line directly above it (reaching the first
+CODE line below, through the rest of its comment block), and — in CSS — from a trailing comment back
+over the declaration it terminates. Whole-file scope is `theme-allow-file <id>… — <why>`; a bare
+`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.
 
 > **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,22 @@
+# [1.21.0](https://github.com/jkrumm/basalt-ui/compare/v1.20.0...v1.21.0) (2026-08-22)
+
+
+### Bug Fixes
+
+* delete a waiver that stopped covering anything ([3984281](https://github.com/jkrumm/basalt-ui/commit/3984281fff6313c225bdf1e185de4a427d2ef4df))
+* emit 0.1, not 0.10, from the shadow palette itself ([48adfff](https://github.com/jkrumm/basalt-ui/commit/48adfffcc9ad7713cacc07c1fc090b219fd175fa))
+* let the real color scheme win, and keep <meta charset> in its window ([8708c85](https://github.com/jkrumm/basalt-ui/commit/8708c85f1488b25e6a059ee879dcadf6350278a2))
+* make an annotation start its comment, and let it scope to one node ([a4cf78c](https://github.com/jkrumm/basalt-ui/commit/a4cf78c546d291c33a27bf94d7636758072a1005))
+* persist sidebar collapse through basalt's own state primitive ([c576040](https://github.com/jkrumm/basalt-ui/commit/c576040172dfeb8d66b52909bbcf55b7b1f91c70))
+* resolve the paths the wiring checks only matched, and audit the waivers ([c595181](https://github.com/jkrumm/basalt-ui/commit/c5951817ed01d7729f031bba2f3da50c3bf60666))
+* restore the palette fixture to emitter bytes ([605e240](https://github.com/jkrumm/basalt-ui/commit/605e240387a417f57ae8070f97bad79d97545d60))
+
+
+### Features
+
+* give the type ladder the two rungs consumers could only waive ([29b9ef3](https://github.com/jkrumm/basalt-ui/commit/29b9ef3767282dffb51fb52138d6ae4f1d24dd62))
+* make the search-param store's reader reachable from the API ([6924970](https://github.com/jkrumm/basalt-ui/commit/6924970f410b82ba5cfc65fd1d5088124934fc8f))
+
 # [1.20.0](https://github.com/jkrumm/basalt-ui/compare/v1.19.1...v1.20.0) (2026-08-22)
 
 

package/MIGRATING.md

@@ -6,8 +6,11 @@ nav definition" does not say `ChartHoverSync` was deleted. This file is that hal
 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. Verified 2026-08-22; the
-1.20.0 section below is written from the commits on `master` that produce it.
+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.
 
 **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
@@ -22,11 +25,86 @@ at 1.3.0, `./agent-chat` at 1.10.0.
 
 ---
 
+## 1.20.1 — 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 —
+the exact shape the rule's own message asks for — was promoted to a whole-file declaration, which is
+why per-node scoping never actually shipped. The two forms are now distinct:
+
+```text
+theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
+theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules
+theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules; a bare one waives NOTHING
+"basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON / .webmanifest
+```
+
+**The migration is one word per file declaration.** Measured across the consumer sweep: linewatch
+0 → 11 findings, argo 0 → 6, rb 0 → 0 — all `warn`, so **no build changes colour**.
+
+```diff
+-// theme-allow hand-rolled-plot — two panes over one x scale
++// theme-allow-file hand-rolled-plot — two panes over one x scale
+```
+
+**An annotation must now START its comment** — after `//`, `/*`, `<!--`, a block-comment gutter `*`,
+or nothing but whitespace. Both parsers used a bare substring search, so a comment that merely
+_mentioned_ the token parsed as the legacy blanket form and switched every rule off on the line
+below. linewatch documented its own waivers in a docblock and thereby disarmed the file — a false
+NEGATIVE, and the reason this ships as a break rather than a grace period. Every annotation anyone
+actually writes still qualifies; a sentence about the escape hatch no longer waives anything.
+
+**A comment-only annotation now reaches the first CODE line below it**, walking through the rest of
+its own comment block. Before, a reason that wrapped onto a second line, or a docblock's `*/`,
+absorbed the waiver and the natural shape silently waived nothing — argo hit that three times in one
+upgrade. A blank line still ends the block.
+
+**`.json` / `.webmanifest` finally have a waiver.** They have been scanned since 1.20.0 and cannot
+hold a comment, so their findings were unwaivable and the printed remedy prescribed something
+impossible; both consumers fell back to a blanket `exemptRules`. Use a member key — but for a
+manifest, `basaltAppPlugin` is the first remedy, since a hand-copied hex drifts from the palette:
+
+```json
+{ "basalt:theme-allow-file": "raw-hex — a PWA manifest theme_color must be a literal hex" }
+```
+
+**Two API-shaped fixes worth acting on:**
+
+| 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                                         |
+
+**New, additive:**
+
+| Surface                                              | Note                                                                                                                                                                                                                                          |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check-theme --audit-allows`                         | every waiver and every `exemptRules` entry with what it still suppresses, proved by re-running the guard with that one occurrence neutralized. Exits 1 on a dead waiver — wire it into CI                                                     |
+| `basalt.exemptRules` takes paths, globs and a reason | relative paths and directory prefixes (`public/site.webmanifest`, `src/agent`), globs (`*` stops at `/`, `**` does not, a slash-free glob also matches the basename), and `{ paths, reason }`. Entries that suppress nothing are now reported |
+| `doctor` → `lefthook-preset`                         | hard-fails a broken `extends` target. lefthook merges a missing target into ZERO commands and exits 0, so a stale path leaves a repo with no pre-commit gate and a clean `lefthook dump`. `sync` reports the same seam                        |
+| `basaltAppPlugin({ colorScheme })`                   | `'dark'` (default) / `'light'` / `'auto'` / `false`. Set it to whatever the app passes as `defaultColorScheme` — before this, a light-scheme consumer got dark native controls permanently                                                    |
+| `VX.text.nano` (10px) + `VX.text.display` (30px)     | the two rungs `inline-font-size` could previously only be waived for. A 20px rung was rejected: 21/20 = 1.05 is below the ladder's 1.06×–1.17× band, so `h2` is the remedy                                                                    |
+| `sync` backfills `basalt.roots`                      | only `init` wrote it, so every existing consumer sat on the undeclared `src` default while `guard-scan` passed. A declared value is never overwritten                                                                                         |
+| `basalt/shadow-basalt-export` reads all nine barrels | the charts layer included. Still exact-name-only — a **tripwire, not coverage**                                                                                                                                                               |
+
+Also: `check-theme`'s `inline-spacing` no longer reads a unitless number in a plain options bag as
+CSS (`fitBounds({ padding: 48 })` stops reporting); the shipped `oxfmt` pre-commit job drops back to
+`*.{ts,tsx,js,jsx,css}` and gains `--no-error-on-unmatched-pattern`; `tokens:css` emits `0.1` rather
+than `0.10`, so a committed sheet stops failing prettier — re-run the command to pick it up.
+
+**The lefthook preset overrides YOU, not the other way round.** An `extends` target wins on a
+colliding key: declare `pre-commit.commands.oxfmt.run` (or `glob:`) in your own file and **yours**
+is the one silently discarded. Only keys the preset does not define merge in. The guard job runs
+`${BASALT_BIN:-bunx --no-install basalt-ui}`; that shell default is the sanctioned seam, set via
+`env:`, which does merge.
+
 ## 1.20.0 — enforcement
 
 **No export removed or renamed.** The whole delta is that things which used to pass now report. If
-your build goes red on this upgrade, that is the release working; every new kind and rule lands
-`warn`, so nothing here fails a build on its own.
+your build goes red on this upgrade, that is the release working. Every new **kind** and **rule**
+lands `warn` — but two other changes in this release do fail a build: `basalt/raw-size-literal`
+promotes to `error`, and the widened markup scan reads `index.html` / `.webmanifest`, where a raw
+hex is an `error`-severity colour kind. Two consumers exited 1 on exactly that.
 
 | Change                                                           | What you'll see                                                                                                 | What to do                                                                                |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
@@ -69,9 +147,18 @@ line is usually a multi-line opening tag or a `{expr}` child), and in CSS a trai
 reaching back over the declaration it terminates, which is what survives the shipped `oxfmt`
 reflowing a long `background-color` so the hex lands above the comment.
 
-**`basalt/hand-rolled-plot` no longer grants whole-file immunity.** Every assembly node is reported
-and waived individually. A file-scoped exception now needs a written declaration naming the rule and
-giving a reason, anywhere in the file: `// theme-allow hand-rolled-plot — two panes over one x scale`.
+**`basalt/hand-rolled-plot` waivers must now be written deliberately.** Every assembly node is
+reported individually, and a waiver is no longer picked up off whatever comment happened to sit on
+the file's first assembly node — it needs a written declaration naming the rule and giving a reason,
+anywhere in the file: `// theme-allow hand-rolled-plot — two panes over one x scale`.
+
+**But the waiver is still whole-file, and per-node scoping is not expressible at 1.20.0.** Naming
+the rule AND giving a reason is what `hasFileDeclaration` matches, at any line — so a comment
+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** —
+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
 its own — "All checks passed" is only printable when every check RAN. Three new hard checks:
@@ -98,18 +185,18 @@ each root's PARENT now contributes its `index.html` and `public/` tree.
 
 ## 1.19.0 — nav
 
-| Removed / renamed                                                 | Replacement                                                                             | Note                                                                |
-| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `NavLinkRenderer` (type)                                          | `defineNav` + `{...useNav(NAV)}` (`basalt-ui/router-tanstack`), or `SidebarItem.Anchor` | basalt now paints every nav pixel                                   |
-| `BasaltShellProps.renderNavLink`, `AppSidebarProps.renderNavLink` | same                                                                                    |                                                                     |
-| `BreadcrumbLinkRenderer` (type)                                   | `AppBreadcrumbs.parentAnchor`                                                           |                                                                     |
-| `BasaltShellProps.renderBreadcrumbLink`                           | same                                                                                    |                                                                     |
-| `BasaltShellProps.sidebarFooterExtra`                             | `mobileNav.moreExtra`                                                                   | its only host was the mobile drawer; it rendered nowhere on desktop |
-| `AppSidebarProps.footerExtra`, `AppSidebarProps.onClose`          | —                                                                                       | the full-height mobile sidebar drawer is deleted                    |
-| `MobileNavItem` (type)                                            | `MobileNavSlot`                                                                         |                                                                     |
-| `MobileNavSection` (type)                                         | `MobileNavGroup`                                                                        |                                                                     |
-| `MobileNavLinkRenderer` (type)                                    | `MobileNavModel`                                                                        |                                                                     |
-| `SidebarSection.mobileTab`                                        | `SidebarSection.mobile`: `'tab' \| 'more' \| 'hidden'` (`true`/`false` still accepted)  |                                                                     |
+| Removed / renamed                                                 | Replacement                                                                                                                      | Note                                                                                                                                                        |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NavLinkRenderer` (type)                                          | `defineNav` + `{...useNav(NAV)}` (`basalt-ui/router-tanstack`), or `SidebarItem.Anchor`                                          | basalt now paints every nav pixel                                                                                                                           |
+| `BasaltShellProps.renderNavLink`, `AppSidebarProps.renderNavLink` | same                                                                                                                             |                                                                                                                                                             |
+| `BreadcrumbLinkRenderer` (type)                                   | `AppBreadcrumbs.parentAnchor`                                                                                                    |                                                                                                                                                             |
+| `BasaltShellProps.renderBreadcrumbLink`                           | same                                                                                                                             |                                                                                                                                                             |
+| `BasaltShellProps.sidebarFooterExtra`                             | `mobileNav.moreExtra`                                                                                                            | its only host was the mobile drawer; it rendered nowhere on desktop                                                                                         |
+| `AppSidebarProps.footerExtra`, `AppSidebarProps.onClose`          | —                                                                                                                                | the full-height mobile sidebar drawer is deleted                                                                                                            |
+| `MobileNavItem` (type)                                            | `MobileNavSlot`                                                                                                                  |                                                                                                                                                             |
+| `MobileNavSection` (type)                                         | `MobileNavGroup`                                                                                                                 |                                                                                                                                                             |
+| `MobileNavLinkRenderer` (type)                                    | `MobileNavModel`                                                                                                                 |                                                                                                                                                             |
+| `SidebarSection.mobileTab`                                        | `SidebarSection.mobile?: false \| NavSectionMobile` — an OBJECT (`{ tab: true, label?, icon? }`), or `false` to hide the section | `'tab' \| 'more' \| 'hidden'` is `SidebarItem.mobile` (`NavMobilePlacement`, `true` ≡ `'tab'`, `false` ≡ `'hidden'`) — a different prop on a different type |
 
 A consumer with no router needs no migration — `href` + `onClick` still work.
 
@@ -130,20 +217,21 @@ never `search: true`.
 
 The largest delta in the 1.x line. No shims were shipped.
 
-| Removed / renamed                                                                                                                                                    | Replacement                                                                                       | Note                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `ChartHoverSync`, `ChartHoverSyncProps`                                                                                                                              | `globalCursorStore` / `createCursorStore` / `useChartCursor` / `useCursorState` — **no provider** | `ChartCursorScope` now _isolates_ a subtree; it is the inverse of the old provider, not a rename |
-| `HoverContext`, `HoverCtx`, `useHoverSync`, `DEFAULT_NO_OP_SET_HOVER`                                                                                                | `useChartCursor`, `useCursorState`, `CursorState`, `CursorStore`                                  | context → `useSyncExternalStore`                                                                 |
-| `ResponsiveChart`, `ResponsiveChartProps`                                                                                                                            | `CartesianChart` / `CartesianChartProps` (+ `autoMargin`, `PlotContext`, `PlotRect`)              | now mandatory for every single-plot cartesian chart, enforced by `basalt/hand-rolled-plot`       |
-| `ChartTooltip` (tip-based), `useChartTooltip`, `useTooltipStyles`                                                                                                    | `ChartTooltipFloat` + the `tooltip: CartesianTooltipConfig` prop                                  | portal / flip / clamp done once                                                                  |
-| `BarsAxisConfig`                                                                                                                                                     | `AxisConfig` + `resolveAxisDomain`                                                                |                                                                                                  |
-| `ZonedLineTooltipLabel`                                                                                                                                              | `tooltip` config on the kind                                                                      |                                                                                                  |
-| `ZonedLine`/`MultiLine`: `yDomain`, `yAutoPad`, `yAutoMaxFloor`, `yAutoMinCeil`, `numTicksY`, `formatYTick`                                                          | one `y?: AxisConfig<T>`                                                                           | `y` is **optional** where `yDomain` was required                                                 |
-| `ZonedLine`/`MultiLine`: `formatValue`, `tooltipLabel`, `renderExtraTooltipRows`                                                                                     | `tooltip?: CartesianTooltipConfig`                                                                | **not** `y` — these are tooltip concerns                                                         |
-| `ZonedLine`/`MultiLine`: `numTicksX`                                                                                                                                 | `xTicks`                                                                                          | `xZones` added alongside                                                                         |
-| `Bars`: `formatValue`, `hideBarTooltipRows`, `leftAxis`, `rightAxis`, `marginLeft`, `numTicksX`, `tooltipLabel`, `renderExtraTooltipRows`, `renderPrefixTooltipRows` | `y` / `y2` (`AxisConfig`), `tooltip`, `SeriesStyle.tooltip`, measured `autoMargin`                | passing `y2` is what makes a chart dual-axis; `chartMargin({ rightAxis })` is gone               |
-| `StackedArea`: `formatValue`, `numTicksX`, `numTicksY`, `yAutoMaxFloor`, `yLabel`                                                                                    | `y`, `tooltip`, `xTicks`                                                                          |                                                                                                  |
-| `Heatmap.width`                                                                                                                                                      | measures itself; takes `height` / `aspectRatio` / `fill`                                          |                                                                                                  |
+| Removed / renamed                                                                                                                                                    | Replacement                                                                                                                                                | Note                                                                                                                                                                                                                                         |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ChartHoverSync`, `ChartHoverSyncProps`                                                                                                                              | `globalCursorStore` / `createCursorStore` / `useChartCursor` / `useCursorState` — **no provider**                                                          | `ChartCursorScope` now _isolates_ a subtree; it is the inverse of the old provider, not a rename                                                                                                                                             |
+| `HoverContext`, `HoverCtx`, `useHoverSync`, `DEFAULT_NO_OP_SET_HOVER`                                                                                                | `useChartCursor`, `useCursorState`, `CursorState`, `CursorStore`                                                                                           | context → `useSyncExternalStore`                                                                                                                                                                                                             |
+| `ResponsiveChart`, `ResponsiveChartProps`                                                                                                                            | `CartesianChart` / `CartesianChartProps` (+ `autoMargin`, `PlotContext`, `PlotRect`)                                                                       | now mandatory for every single-plot cartesian chart, enforced by `basalt/hand-rolled-plot`                                                                                                                                                   |
+| `ChartTooltip` (tip-based), `useChartTooltip`, `useTooltipStyles`                                                                                                    | `ChartTooltipFloat` + the `tooltip: CartesianTooltipConfig` prop                                                                                           | portal / flip / clamp done once                                                                                                                                                                                                              |
+| `BarsAxisConfig`                                                                                                                                                     | `AxisConfig` + `resolveAxisDomain`                                                                                                                         |                                                                                                                                                                                                                                              |
+| `ZonedLineTooltipLabel`                                                                                                                                              | `tooltip` config on the kind                                                                                                                               |                                                                                                                                                                                                                                              |
+| `ZonedLine`/`MultiLine`: `yDomain`, `yAutoPad`, `yAutoMaxFloor`, `yAutoMinCeil`, `numTicksY`, `formatYTick`                                                          | one `y?: AxisConfig<T>`                                                                                                                                    | `y` is **optional** where `yDomain` was required                                                                                                                                                                                             |
+| `ZonedLine`/`MultiLine`: `tooltipLabel`, `renderExtraTooltipRows`                                                                                                    | `tooltip.label`, `tooltip.extraRows` (`CartesianTooltipConfig`)                                                                                            | there is no `appendRows`; the field is `extraRows`                                                                                                                                                                                           |
+| `ZonedLine`/`MultiLine`: `formatValue`                                                                                                                               | **`y.format`** — or per-series `ChartSeries.formatValue` for one row                                                                                       | `CartesianTooltipConfig` has no value formatter: the axis format IS the tooltip value format                                                                                                                                                 |
+| `ZonedLine`/`MultiLine`: `numTicksX`                                                                                                                                 | `xTicks`                                                                                                                                                   | `xZones` added alongside                                                                                                                                                                                                                     |
+| `Bars`: `formatValue`, `hideBarTooltipRows`, `leftAxis`, `rightAxis`, `marginLeft`, `numTicksX`, `tooltipLabel`, `renderExtraTooltipRows`, `renderPrefixTooltipRows` | `y` / `y2` (`AxisConfig`), `xTicks`, `tooltip.{label,extraRows,prependRows}`, per-bar `BarsBar.formatValue` / `.tooltip`, measured `autoMargin` + `margin` | passing `y2` is what makes a chart dual-axis. `chartMargin({ rightAxis })` is **not** removed — it is still exported from `basalt-ui` and `basalt-ui/charts`; it is simply no longer needed, since the right gutter follows from measurement |
+| `StackedArea`: `formatValue`, `numTicksX`, `numTicksY`, `yAutoMaxFloor`, `yLabel`                                                                                    | `y` (incl. `y.format`), `xTicks`; per-series `ChartSeries.formatValue`                                                                                     | `StackedAreaProps` has **no** `tooltip` prop — its tooltip is entirely derived from `series`                                                                                                                                                 |
+| `Heatmap.width`                                                                                                                                                      | measures itself; takes `height` / `aspectRatio` / `fill`                                                                                                   |                                                                                                                                                                                                                                              |
 
 ## 1.12.0 — agent-chat, behaviour only
 
@@ -176,6 +264,12 @@ Names that have no 1.x equivalent: the `--chart-blue-1..8` sequential ramp (1.x
 `--vx-fill-*` only), the default font stacks as a token (they live in `styles.css`), `purple` as a
 text color, `black`, `blue-400`/`green-400`.
 
+**The typefaces changed at 1.0, not just their delivery.** 0.4.2 shipped Instrument Sans; 1.x ships
+Nunito Sans (body) + Hubot Sans (condensed headings), mono unchanged at JetBrains Mono. `fonts:css`
+emits the 1.x stacks — for a 0.4.2 migrant that is a **rebrand**, not a restoration. It also emits
+`--basalt-font-head-stretch: 88%`, tuned for Hubot Sans specifically; pointed at another face it
+silently condenses it.
+
 ## 1.0.1 — CLI binary renamed
 
 `basalt` → **`basalt-ui`**. Never `bunx basalt`.
@@ -191,18 +285,18 @@ live in `configs/oxlint.json`, and since 1.20.0 their grace is tracked by `PLUGI
 named export beside the plugin — a test asserts it against the shipped preset in both directions, so
 deleting an entry forces the level flip in the same commit.
 
-| Rule                               | Landed           | Became `error`                     |
-| ---------------------------------- | ---------------- | ---------------------------------- |
-| `mantine-shade-index` (guard kind) | 1.7.0 as `warn`  | **1.11.0**                         |
-| `basalt/raw-scroll-container`      | ≤1.2.0 as `off`  | `warn` 1.10.0 → **`error` 1.13.0** |
-| `basalt/ai-sdk-major`              | 1.10.0 as `warn` | **1.13.0**                         |
-| `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 at 1.20.0   |
-| `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        |
-| `basalt/hand-rolled-shell`         | 1.20.0 as `warn` | —                                  |
+| Rule                               | Landed           | Became `error`                                                           |
+| ---------------------------------- | ---------------- | ------------------------------------------------------------------------ |
+| `mantine-shade-index` (guard kind) | 1.7.0 as `warn`  | **1.11.0**                                                               |
+| `basalt/raw-scroll-container`      | ≤1.2.0 as `off`  | `warn` 1.10.0 → **`error` 1.13.0**                                       |
+| `basalt/ai-sdk-major`              | 1.10.0 as `warn` | **1.13.0**                                                               |
+| `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/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/hand-rolled-shell`         | 1.20.0 as `warn` | —                                                                        |
 
 `card-with-border`, `inline-display`, `raw-html-layout`, `raw-form-control`, `raw-font-family` and
 the other original guard kinds have been `error` since before 1.2.0 — they never had a grace minor.
@@ -214,7 +308,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.0**.
+The 32 camelCase `--vx-*` aliases deprecated in 1.5.0 are **still emitted at 1.20.1**.
 `buildPaletteCss({ legacyAliases: false })` / `tokens:css --no-legacy-aliases` opts out now; a later
 minor flips the default.
 
@@ -223,6 +317,10 @@ minor flips the default.
 - Props declared inline on a component (`function X({ a }: { a: string })`) rather than on an
   exported type are outside the diff method used here. Spot checks on the shell and charts modules
   found none, but the negative is unproven.
-- `AppBreadcrumbs.parentAnchor` as the replacement for `renderBreadcrumbLink` comes from the 1.19.0
-  commit body, not from a diffable exported type — `AppBreadcrumbsProps` is not in the public export
-  set at either tag.
+- The 0.4.2 `./css` line counts in the 1.0.0 table (877 lines / 307 custom props / 19 utilities) come
+  from the removal commit, not from a re-read of the 0.4.2 tarball.
+
+`AppBreadcrumbs.parentAnchor` was listed here through 1.20.0 and is now verified: it is declared on
+the shipped `dist/shell/app-breadcrumbs.d.ts` (`parentAnchor?: NavAnchor`, with `parentHref` as the
+no-router fallback). The type is inline on the component rather than an exported `AppBreadcrumbsProps`,
+which is why the export-surface diff never saw it.

package/README.md

@@ -193,12 +193,19 @@ and everything derives from it — the guard's scan, the seeded CI `oxfmt` globs
 exemption:
 
 ```json
-// package.json — `roots` is written by init; the rest are yours to add
+// package.json — `roots` is written by init and backfilled by sync; the rest are yours to add
 {
   "basalt": {
     "roots": ["apps/web/src"],
     "include": ["app/manifest.json"],
-    "profile": "tokens-only"
+    "profile": "tokens-only",
+    "exemptRules": {
+      "inline-display": ["agent"],
+      "raw-hex": {
+        "paths": ["public/site.webmanifest"],
+        "reason": "a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var"
+      }
+    }
   }
 }
 ```
@@ -214,6 +221,19 @@ which would silence half the guard on any repo keeping Mantine in a different wo
 Other keys (`exempt`, `severity`, `spacingSteps`, `forbiddenAccents`, …) are documented on the
 `BasaltConfig` type.
 
+**`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
+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`.
+
+`sync` **backfills `roots`** when the key is absent — only `init` used to write it, so every
+existing consumer stayed on the undeclared `src` default while `guard-scan` passed anyway. A
+declared value is never overwritten; a layout it does not cover is reported as one line, because
+`roots` being a subset is the normal case in a monorepo, not drift.
+
 Basalt-emitted LINES are skipped, not whole files. The file has to earn it first — a `.css` path,
 the `@generated basalt-ui` header verbatim on line 1, the version + invocation line on line 2 — and
 then each line does too: at brace depth 0 a selector or a self-closing comment, inside a block only
@@ -222,12 +242,26 @@ 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.** `theme-allow <rule-id> — <reason>` waives that one kind, on the
-reported line, on a comment-only line directly above it (the only form JSX can express), or — in
-CSS — from a trailing comment back over the declaration it terminates. A bare `theme-allow` still
-waives everything but reports `theme-allow-unscoped`. The id slot is read strictly: a word there
-that names no rule waives nothing, so an annotation covers exactly the ids it got right and a typo
-is never the blanket form.
+**The escape hatch is scoped, and since 1.20.1 the two scopes are spelled apart:**
+
+```text
+theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
+theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules
+theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules; a bare one waives NOTHING
+"basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON / .webmanifest
+```
+
+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,
+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
+the declaration it terminates. The id slot is read strictly: a word there that names no rule waives
+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.
 
 `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

package/agent/rules/basalt-app.md

@@ -96,6 +96,25 @@ refuses on a commented config rather than deleting the comments.
 Run `basalt-ui doctor` afterwards to confirm the wiring took. A check that cannot RUN is reported as
 `SKIPPED` and exits non-zero on its own — "All checks passed" is only printable when every check ran.
 
+### 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.
+
+**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
+keys the preset does not define merge in. So `env:`, `exclude:`, `skip:` and a differently-named
+command of your own are yours; `run:` and `glob:` on a shipped command are not. The sanctioned seam
+is therefore `BASALT_BIN`: the guard job runs `${BASALT_BIN:-bunx --no-install basalt-ui}`, and the
+shell default is the whole reason the seam exists at all. `init` renders it with the resolved local
+bin. `--no-install` is deliberate — a bare `bunx basalt-ui` in a repo where basalt is not resolvable
+from the root silently downloads a different copy from npm and gates the commit with a version
+nobody pinned.
+
 ## `index.html` and `public/` are scanned
 
 `check-theme` resolves `.html` / `.webmanifest` / `.json` as markup (colour kinds only), and each
@@ -133,6 +152,28 @@ they track the palette automatically. It also injects the `apple-mobile-web-app-
 `viewport-fit=cover` (skipped when the consumer's own `index.html` already declares one), and
 site-wide OG/Twitter defaults from `options.seo`.
 
+**Set `colorScheme` to whatever the app passes as `defaultColorScheme`** — `'dark'` (the default),
+`'light'`, `'auto'` (declares `color-scheme: light dark` and picks the pre-boot background off
+`prefers-color-scheme`), or `false` (paint the background, declare no `color-scheme`).
+
+```ts
+plugins: [react(), ...basaltAppPlugin({ name: 'Argo', colorScheme: 'auto' })]
+```
+
+Before 1.20.1 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
+resolves the real scheme. A mismatched `colorScheme` is therefore a flash of the wrong surface, not
+a stuck one.
+
+**The plugin hoists your `<meta charset>`.** Every injected tag defaults to `head-prepend`, which
+landed ~20 tags ahead of the consumer's own encoding declaration — measured at byte 1653 on a
+realistic shell, past the 1024-byte window the HTML spec gives it, with no consumer-side fix
+available. The plugin now re-emits the declaration as its own first head-prepend tag (46 bytes after
+the fix) and runs `order: 'pre'` so nothing else can land ahead of it. The legacy `http-equiv` form
+is detected and left verbatim.
+
 Icons are **bring-your-own** — basalt-ui takes no `sharp`/image-processing dependency. The plugin
 expects these filenames under `public/` (or `icons.dir` if customized):
 

package/agent/rules/basalt-charts.md

@@ -57,12 +57,14 @@ radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
   `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`) in a file that does not
   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. A genuinely non-single-plot shape (multi-pane, radial, matrix) declares
-  itself with a written file declaration — a `theme-allow` that both names the rule and gives a
-  reason, anywhere in the file (`theme-allow hand-rolled-plot — two panes over one x scale`);
-  `DualPanel` carries the repo's only one. The file that DEFINES `CartesianChart` is exempt
-  definitionally (detected by declaration, not by path), since a rule saying "compose X" cannot
-  fire inside X.
+  file went unpoliced. To waive ONE node, put `theme-allow hand-rolled-plot — <why>` on it (or on a
+  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix)
+  declares the whole file with `theme-allow-file hand-rolled-plot — two panes over one x scale`,
+  anywhere in it; `DualPanel` carries the repo's only one. **`theme-allow-file` is the 1.20.1
+  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
   `items`; **since 1.20.0 also a `.map()` over a non-`series` array**, because deriving from AN
   array is not deriving from THE series. The legend must come from the same `series` the chart
@@ -93,12 +95,13 @@ ships no map kind.
 - **Want `@visx/geo` anyway?** Install it yourself — basalt doesn't pin it — and keep it under a
   `charts/` segment like every other visx import, same as any bespoke chart.
 - **Style map chrome with `--vx-*` tokens** (`VX.*`/`alpha()`) so it matches the rest of the app.
-- **The guard trap:** `check-theme`'s `inline-spacing` kind is a per-line regex over raw source, not
-  an AST pass — it flags any `padding:`/`gap:`/`margin:` followed by a number in _any_ object
-  literal, in any file. A map's pixel geometry (`fitBounds({ padding: 48 })`, marker offsets) trips
-  it even though it isn't spacing, and hoisting the value to a module-scope const doesn't help — the
-  regex sees the line, not the binding. Scope a `theme-allow inline-spacing — map geometry` comment
-  to it; that's the sanctioned answer, not a bug to file.
+- **The guard trap, narrowed at 1.20.1:** `check-theme`'s `inline-spacing` kind is a per-line regex
+  over raw source, not an AST pass. A **unitless** number now only reports inside a style-object
+  context (a `style=`/`sx=`/`css=` attribute, or a const whose name or type says styles), so a map's
+  pixel geometry — `fitBounds({ padding: 48 })`, marker offsets — no longer trips it: an options bag
+  is not CSS. A value carrying a unit is CSS wherever it was written and still reports. Where it
+  does fire on genuine map chrome, scope a `theme-allow inline-spacing — map geometry` comment to
+  it; that's the sanctioned answer, not a bug to file.
 
 ## Every chart has
 

package/agent/rules/basalt-content.md

@@ -208,6 +208,10 @@ axes AND together — matching the existing multi-facet `filterFn` semantics in
 
 **Filter state is URL state.** Single-select axes (category) use `createSearchParamStore`;
 multi-select axes (tags) use `createMultiSearchParamStore` — both from `basalt-ui/router-tanstack`.
+That holds for the enum-shaped axes an article filter has. **It is not a general URL-state mandate**:
+a route whose `validateSearch` is a real Zod object is hand-written, and `createSearchSchemaStore`
+is planned, not shipped — see `basalt-router.md` → "validateSearch".
+
 Two stores compose on one route by spreading both `validateSearch` results:
 
 ```ts