basalt-ui 1.32.1 → 1.33.0

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+# [1.33.0](https://github.com/jkrumm/basalt-ui/compare/v1.32.1...v1.33.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* audit-allows asks oxlint about dual-lane and mixed waivers ([9e0a3d5](https://github.com/jkrumm/basalt-ui/commit/9e0a3d5a43cd9e27625801dd28c3360975f155ed))
+* audit-allows probes bare line-scope waivers through oxlint ([b5d53f9](https://github.com/jkrumm/basalt-ui/commit/b5d53f9c8e3ac1712e455dd0fd7310d88358104f))
+* break the audit-allows → index → check-theme → audit-allows cycle ([98d746c](https://github.com/jkrumm/basalt-ui/commit/98d746cd13e36b7cbf5fa809e120c91cd9d23c53))
+* count only real declaration positions as a local --vx declaration ([4b5b723](https://github.com/jkrumm/basalt-ui/commit/4b5b723c994c6f6c2b01612f5a303649881f3cc2))
+* gate the lab store on the dotted NODE_ENV form, record the fold matrix ([7d336b5](https://github.com/jkrumm/basalt-ui/commit/7d336b5209aa7be846ba11faa935e31e5aa8f795))
+* gen-vx-names reads CSS declarations in ts/tsx and says what QUOTED admits ([238cdb9](https://github.com/jkrumm/basalt-ui/commit/238cdb9fb887b6b703e61c684d0c657d3a9a6a5c))
+* harden the provider-only budget's build, dist and externals handling ([8a20d0f](https://github.com/jkrumm/basalt-ui/commit/8a20d0f49784e496b7db9634a2ac83f97c01903d))
+* judge a resets write against the URL at navigate time, not the render ([74a6dc7](https://github.com/jkrumm/basalt-ui/commit/74a6dc762965e470525e9aabe14e9f5e0972b07b))
+* judge only the vx names basalt claims — removed names and bare roots ([bf15dab](https://github.com/jkrumm/basalt-ui/commit/bf15dab0704858022ec2c157b74e8183dda71586))
+* keep the page when clear() leaves a field where it was ([2a6b40f](https://github.com/jkrumm/basalt-ui/commit/2a6b40faebb38011b2203b10382411c97fb6d551))
+* keep the page when Reset all moves no field ([c12d01a](https://github.com/jkrumm/basalt-ui/commit/c12d01ae7fa998f569369b3fb347bc941c56cf6c))
+* print a failed provider-only build as a budget row, not a stack ([66361ef](https://github.com/jkrumm/basalt-ui/commit/66361ef1a41019b6f096e33ffc0d13d28913e639))
+* resolve the CONTAINER_GRID_BREAKPOINTS trust through the scope manager ([26f664b](https://github.com/jkrumm/basalt-ui/commit/26f664b6c5af662ce89f09ff1d839fd8fc34830e))
+* see a --vx reference a formatter wrapped across lines ([ba469b1](https://github.com/jkrumm/basalt-ui/commit/ba469b12cc7513d90fbc5171e570cfacc83312bf))
+* stop NumberFilter's Clear from committing the draft on its way ([04e3156](https://github.com/jkrumm/basalt-ui/commit/04e315682571ad9cca24cadd451accce0a312134))
+* trust CONTAINER_GRID_BREAKPOINTS read off a namespace import ([cc15f76](https://github.com/jkrumm/basalt-ui/commit/cc15f760fbcafa041404b750f1e588c712108745))
+* word the bare-waiver oxlint verdict by what it waives, not a fake id ([3b5e3b2](https://github.com/jkrumm/basalt-ui/commit/3b5e3b2757b0ff7b875dc1a337f4a8137e8c4bc3))
+
+
+### Features
+
+* add clearable to NumberFilter for parity with SelectFilter ([a46d805](https://github.com/jkrumm/basalt-ui/commit/a46d805f97c1b60b93017ade2f6edb5a293fd302))
+* add resets to createSearchStore for sibling params like page ([e809fd7](https://github.com/jkrumm/basalt-ui/commit/e809fd78e0b397f1ea52bb860b68bda5353c4943))
+* promote the C1 and breakpoint twin pairs to error ([d49a5e2](https://github.com/jkrumm/basalt-ui/commit/d49a5e22b4f678f82f2377485f15ce6bc65c1be6))
+* report removed and misspelled --vx-* names as unknown-vx-token ([6405f1a](https://github.com/jkrumm/basalt-ui/commit/6405f1af265cb7659026c1806bead121a22253f6))
+* ship CONTAINER_GRID_BREAKPOINTS and let raw-breakpoint trust it ([4e3addb](https://github.com/jkrumm/basalt-ui/commit/4e3addbf50d1d358d8037389ad679d434ba00d98))
+
+
+### Performance Improvements
+
+* budget the provider-only first paint in check-budgets ([d36bed2](https://github.com/jkrumm/basalt-ui/commit/d36bed2c9c898490fddde0de126a36541ee25860))
+* fold every dev-only gate out of production bundles ([25f94b7](https://github.com/jkrumm/basalt-ui/commit/25f94b79e81b045c05fe5eefb9479edebe195c43))
+* keep the theme lab's store out of production first paint ([4e7512b](https://github.com/jkrumm/basalt-ui/commit/4e7512b41846e54fbb3d196ec157435c03b1c582))
+
 ## [1.32.1](https://github.com/jkrumm/basalt-ui/compare/v1.32.0...v1.32.1) (2026-09-30)
 
 

package/MIGRATING.md

@@ -66,18 +66,18 @@ There is one row per SURFACE, not per export, and a surface earns a row once any
 shipped lefthook preset both changed in 1.30.0 with no row that owned them — which is how a
 consumer read this index, found nothing, and diffed a KPI row that had silently gone 4-up → 2-up.
 
-| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                | 1.32.0                                                                    | 1.32.1                                                                                                          | Unreleased |
-| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- |
-| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | —          |
-| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ 1.31.0)                                                       | —                                                                         | `ResponsiveChartHeight` `sm` → key (§ Container recipes)                                                        | —          |
-| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | —          |
-| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
-| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `FormGroup` row no longer stretches (§ Fixes)                                                                   | —          |
-| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `renderCard` documented (§ `renderCard`)                                                                        | —          |
-| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
-| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
-| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
-| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                     | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes)                                      | —          |
+| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                | 1.32.0                                                                    | 1.32.1                                                                                                          | 1.33.0                                                                        | Unreleased |
+| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------- |
+| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0)           | —          |
+| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ 1.31.0)                                                       | —                                                                         | `ResponsiveChartHeight` `sm` → key (§ Container recipes)                                                        | —                                                                             | —          |
+| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | —                                                                             | —          |
+| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | —          |
+| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `FormGroup` row no longer stretches (§ Fixes)                                                                   | —                                                                             | —          |
+| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `renderCard` documented (§ `renderCard`)                                                                        | —                                                                             | —          |
+| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —          |
+| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —          |
+| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —          |
+| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                     | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes)                                      | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards)         | —          |
 
 ---
 
@@ -86,6 +86,105 @@ consumer read this index, found nothing, and diffed a KPI row that had silently
 _Nothing yet. Author the next section under this heading as `## Unreleased — <title>`; the
 release renames it and opens a new one here._
 
+## 1.33.0 — the 1.33.0 minor
+
+### `CONTAINER_GRID_BREAKPOINTS` — the `Grid type="container"` map ships
+
+`basalt-ui/tokens` exports the five-key map the 1.32.0 recipe had every consumer hand-write
+(`xs` compact 240px · `sm` regular 480px · `md`/`lg`/`xl` wide 800px), derived from
+`CONTAINER_CLASSES`. `basalt/raw-breakpoint` trusts it by name: before, it read an IMPORTED map as
+unresolvable and flagged every `Grid.Col` span under it, so each route file declared its own
+same-file literal (argo: five identical copies).
+
+```tsx
+import { CONTAINER_GRID_BREAKPOINTS } from 'basalt-ui/tokens'
+;<Grid type="container" breakpoints={CONTAINER_GRID_BREAKPOINTS}>
+  <Grid.Col span={{ base: 12, md: 4 }}>…</Grid.Col>
+</Grid>
+```
+
+| Delete                                                                               | Replace with                                 |
+| ------------------------------------------------------------------------------------ | -------------------------------------------- |
+| a same-file `const GRID_BREAKPOINTS = { xs: …, sm: …, md: …, lg: …, xl: … }` literal | `breakpoints={CONTAINER_GRID_BREAKPOINTS}`   |
+| a shared map you export yourself (flagged when imported)                             | the shipped one, or keep a same-file literal |
+
+The trust is provenance-gated: the import must name `CONTAINER_GRID_BREAKPOINTS` from
+`basalt-ui/tokens` (an alias `{ CONTAINER_GRID_BREAKPOINTS as bp }`, a namespace member
+`tokens.CONTAINER_GRID_BREAKPOINTS` on `import * as tokens`, and a same-file `const bp = …` of
+either all count; a parameter or inner `const` that shadows the name does not). A map of your own
+that deviates from it — a 1200px `xl`, say — stays a same-file literal. `SimpleGrid type="container"` is unchanged: its keys
+are CSS lengths, so ``[`${CONTAINER_CLASSES.regular}px`]`` stays the form.
+
+### State and controls — `resets: ['page']`, `NumberFilter clearable`
+
+Additive; nothing to change unless you carry one of the two workarounds below.
+
+**`createSearchStore({ …, resets: ['page'] })`** drops the named sibling params — ones the store does
+NOT own — in the same navigate as every URL-lane write that moves a value (setter, `clear()`,
+`useReset()`); a `url: false` field makes no navigate and keeps the page. The route's own `validateSearch` resolves the default (`page` → 1). An explicit
+`set(v, { patch: { page } })` still wins; naming a param the store owns throws at definition.
+Store-wide by design: every filter of a list narrows the same list, sort included.
+
+```ts
+// before — an effect per page, which also snapped Back/Forward onto page 1
+useEffect(() => { if (filtersChanged && search.page !== 1) navigate({ search: (p) => ({ ...p, page: 1 }) }) }, [filterKey])
+
+// after — the store owns it; Back restores filter AND page, because they were one write
+export const b2Filters = createSearchStore({ key: 'b2-filters', fields: { … }, resets: ['page'] })
+```
+
+**`NumberFilter clearable`** — parity with `SelectFilter`/`EnumFilter`: a `Clear` in the popover that
+writes the fallback back, in both the `options` and the stepper form. "No filter" is the FALLBACK,
+not a row: with `clearable`, drop an `{ value: 0, label: 'Any …' }` option — the pill reads the
+filter's `label` while no preset matches.
+
+### Guards — four ids promote to `error`
+
+The last two twin pairs leave grace together, one law per pair and one promotion for both lanes:
+
+| Law                   | oxlint rule (JSX)             | `check-theme` kind (text/CSS) | In grace since |
+| --------------------- | ----------------------------- | ----------------------------- | -------------- |
+| C1 — a control's home | `basalt/control-outside-home` | `raw-selection-control`       | 1.26.0         |
+| the breakpoint law    | `basalt/raw-breakpoint`       | `raw-media-query`             | 1.31.0         |
+
+Measured before flipping, 2026-10-01: all nine consumers on 1.32.1 — argo, rb, image-gen,
+image-share, email-gateway, linewatch, rollhook, obsidian, weatherorb — at 0 for all four ids.
+basalt's own tree and the playground are at 0 too, after two reasoned waivers in the package
+(`legend-disclosure.tsx` clamps a fixed panel with `window.innerWidth`, a position rather than a
+breakpoint; `ArticleGrid`'s `cols` is documented per viewport `lg`, so moving it to container keys
+would re-flow every consumer's grid and ships opt-in instead).
+
+If one fires after upgrading, it is code written since the measurement: the remedies are unchanged
+(§ 1.31.0 for C1's homes, § 1.32.0 `basalt/raw-breakpoint` for the container recipe), or a
+`theme-allow <id> — <why>`. `basalt.severity` still turns a kind down per repo; the shipped oxlint
+preset's level can be overridden in your own `.oxlintrc.json`.
+
+### `unknown-vx-token` — a removed `--vx-*` name is a finding (`warn`, `error` at 1.34.0)
+
+A `var(--vx-*)` naming a token basalt does not emit resolves to its fallback — or to nothing — with
+no error from tsc, oxlint or the browser. obsidian lost its 44px touch floor that way, to
+`var(--vx-space-touch-target)`. `check-theme` now reports it, in every scanned file type. It ships
+`warn` for this minor and promotes at 1.34.0. Measured at ship time: all nine consumers at 0.
+
+| Removed name                                  | Replacement                                               |
+| --------------------------------------------- | --------------------------------------------------------- |
+| `--vx-space-touch-target`                     | `--vx-hit`                                                |
+| `--vx-space-touch-control-height`             | `--vx-hit`                                                |
+| `--vx-space-app-header-mobile-actions-height` | `--vx-space-sticky-header-clearance`                      |
+| `--vx-space-sticky-header-clearance-mobile`   | `--vx-space-sticky-header-clearance`                      |
+| `--vx-space-sidebar-brand-inset-top`          | none — the brand row is the header band (§ 1.30.0 Chrome) |
+
+- **Judged: a removed name** (the table) **and a bare family root nothing emits** —
+  `var(--vx-surface)`, `var(--vx-space)`, `var(--vx-status)`: basalt only writes `<root>-<key>`,
+  and so does `groupTokens`. The live set is exactly `basalt-ui/tokens.css` plus three
+  component-scoped names (`--vx-hit-gap`, `--vx-space-icon-size`, `--vx-keyboard-inset`).
+- **Not judged: any other unknown name**, even under a basalt prefix. `groupTokens('surface', …)`
+  emits `--vx-surface-<key>` from a file a per-file scan cannot see, so `--vx-surface-2` could be
+  your group or a typo, and the guard does not guess. Check such a name against
+  `basalt-ui/tokens.css` yourself. Your `defineSeries`/`groupTokens` series (argo's `--vx-lp-*`,
+  rb's `--vx-confidence-*`), a computed name (`var(--vx-fill-${hue})`) and a name the same file
+  declares are never reported.
+
 ## 1.32.1 — the 1.32.0 recipe resolves, and the gaps consumers hit upgrading to it
 
 A patch: no new API beyond restoring what 1.31.0/1.32.0 already documented. Eight consumers
@@ -109,8 +208,10 @@ const-resolved prop value (`span={wide ? { base: 12, md: 4 } : 12}` used to slip
 warnings.)
 
 **After any guard narrows, audit your waivers:** `basalt-ui check-theme --audit-allows` lists every
-`theme-allow` and whether it still suppresses anything. Dead ones (rb carried five
-`in-body-page-title`, linewatch one `bound-control-outside-home`) go.
+`theme-allow` and whether it still suppresses anything. Dead ones (rb carried three
+`in-body-page-title`, linewatch one `bound-control-outside-home`) go. Before 1.33.0 the audit also
+called an `in-body-page-title` waiver dead when only the oxlint lane still needed it — if deleting
+one makes `oxlint` fail, restore it.
 
 **Scope — the breakpoint law is Mantine/CSS-scoped.** `raw-breakpoint` is an oxlint rule over JSX
 and `raw-media-query` a `check-theme` kind over `.css`. A tokens-only (Tailwind) consumer has only
@@ -147,12 +248,12 @@ swap to a list inside a `min-width` query. `BasaltDataTable` needs the optional
 **Layouts that need a step above `wide` (800px).** There is no fifth class; one ships when two named
 consumers need the same width. Until then, verified against the 1.32.0 plugin:
 
-| Where                                                                    | Off-class width (e.g. `1200px`)                                                                                         |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `SimpleGrid type="container"` px key — `cols={{ base: 1, '1200px': 5 }}` | passes: `raw-breakpoint` does not judge px keys, only theme names (`sm`)                                                |
-| `Grid type="container"` `breakpoints` map value — `xl: '1200px'`         | passes: the map's values are not judged                                                                                 |
-| `@container basalt-card` or unnamed, in CSS                              | flagged — `theme-allow raw-media-query — <why this layout needs 1200px>`                                                |
-| `@container <your-own-name>` or `basalt-grid`, in CSS                    | passes today; a later minor may judge `basalt-grid` — prefer a reasoned `theme-allow` over relying on the unjudged name |
+| Where                                                                    | Off-class width (e.g. `1200px`)                                                                                                                   |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SimpleGrid type="container"` px key — `cols={{ base: 1, '1200px': 5 }}` | passes: `raw-breakpoint` does not judge px keys, only theme names (`sm`)                                                                          |
+| `Grid type="container"` `breakpoints` map value — `xl: '1200px'`         | passes: the map's values are not judged                                                                                                           |
+| `@container basalt-card` or unnamed, in CSS                              | flagged — `theme-allow raw-media-query — <why this layout needs 1200px>`                                                                          |
+| `@container <your-own-name>` or `basalt-grid`, in CSS                    | passes — the name is unjudged, so write no waiver (`--audit-allows` reports one dead); a minor that starts judging `basalt-grid` will say so here |
 
 Either way, write the reason next to the width: it is the evidence the fifth class is waiting on.
 
@@ -246,11 +347,10 @@ source, which is what the rule's exemption is built on:
 <Grid><Grid.Col span={{ base: 12, lg: 4 }}>…</Grid.Col></Grid>
 
 // after — the grid's own width
-import { CONTAINER_CLASSES as C } from 'basalt-ui/tokens'
+import { CONTAINER_CLASSES as C, CONTAINER_GRID_BREAKPOINTS } from 'basalt-ui/tokens'
 <SimpleGrid type="container" cols={{ base: 1, [`${C.regular}px`]: 3 }}>…</SimpleGrid>
-const px = (n: number) => `${n}px`
-const containerBreakpoints = { xs: px(C.compact), sm: px(C.regular), md: px(C.wide), lg: px(C.wide), xl: px(C.wide) }
-<Grid type="container" breakpoints={containerBreakpoints}>
+// the shipped map (§ 1.33.0); on 1.32.x, a same-file literal of the same five keys
+<Grid type="container" breakpoints={CONTAINER_GRID_BREAKPOINTS}>
   <Grid.Col span={{ base: 12, md: 4 }}>…</Grid.Col>
 </Grid>
 ```

package/agent/rules/basalt-state.md

@@ -76,8 +76,8 @@ export const analytics = createSearchStore({
   hand-count either.
 - **A reset UNSETS.** `useReset()`/`field.clear()` DELETE the persisted key, never write
   `fallback` (which would pin a thunk fallback as a value nobody chose).
-- **`set(next, { patch })`** merges sibling params the store does NOT own into the same navigate; a
-  key another field of the same store owns throws in dev.
+- **`set(next, { patch })`** merges params the store does NOT own into the same navigate; store-level
+  `resets: ['page']` does it on every URL-lane write (never a `useEffect`: it snaps Back/Forward).
 
 ## Nav links carry the store BY REFERENCE
 

package/agent/rules/basalt-tokens.md

@@ -9,7 +9,7 @@ paths:
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — css-raw-surface, inline-font-size, off-identity-accent, off-system-surface-var, raw-color-fn, raw-font-family, raw-hex, raw-radius, raw-surface, surface-shadow-override, theme-allow-unscoped · oxlint rules — basalt/no-raw-font-size, basalt/raw-size-literal, basalt/token-layer-boundary -->
+<!-- backed by: guard kinds — css-raw-surface, inline-font-size, off-identity-accent, off-system-surface-var, raw-color-fn, raw-font-family, raw-hex, raw-radius, raw-surface, surface-shadow-override, theme-allow-unscoped, unknown-vx-token · oxlint rules — basalt/no-raw-font-size, basalt/raw-size-literal, basalt/token-layer-boundary -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 

package/configs/oxlint-plugin.js

@@ -177,6 +177,7 @@ export const KNOWN_RULE_IDS = new Set([
   'in-body-page-title',
   'raw-selection-control',
   'raw-media-query',
+  'unknown-vx-token',
   // Retired guard kinds — no longer in GUARD_RULES, but a `theme-allow` naming one must still
   // parse as a real (dead) waiver rather than an unknown-id typo. See RETIRED_RULE_IDS above.
   ...RETIRED_RULE_IDS,
@@ -2702,9 +2703,8 @@ const CONTROL_OUTSIDE_HOME_MESSAGE =
 
 /**
  * The cross-file half of C1, and the one rule here that is openly a HEURISTIC: "this control has
- * no home" is a claim about layout intent, which no AST can see. It ships `warn` for that reason
- * and stays warn until the playground and the five consumer repos run it with ≤3 waivers
- * (docs/CONTROLS-SPEC.md §9 wave 7).
+ * no home" is a claim about layout intent, which no AST can see. That is why it sat in grace from
+ * 1.26.0 to 1.33.0, promoting only once basalt's tree and nine consumers measured at zero.
  *
  * Four exemptions carry the false-positive load: an overlay/settings-row/form-row ancestor
  * ({@link CONTROL_HOST_TAGS}, `FormRow`/`FormGroup` included), an {@link isOverlayConventionFile}
@@ -2712,7 +2712,7 @@ const CONTROL_OUTSIDE_HOME_MESSAGE =
  * `@mantine/form` (a form is the third home and its inputs are not filters), and the owner
  * exemption — a file DEFINING a basalt control cannot be told to use one.
  */
-// Ships: warn (grace → 1.33.0)
+// Ships: error
 const controlOutsideHome = {
   meta: {
     type: 'suggestion',
@@ -4066,8 +4066,9 @@ const CONTAINER_ROUTED_PROPS = {
  * `type` has to be the string literal `"container"`; a dynamic value is not a decision this rule
  * can read. `Grid.Col` takes its grid's mode by walking to the nearest enclosing `Grid` element.
  * `consts` is the rule's same-file name→object map, so `breakpoints={map}` resolves like any value.
+ * The one IMPORTED map trusted is basalt's own `CONTAINER_GRID_BREAKPOINTS` ({@link isShippedGridMap}).
  */
-function containerGridMode(opening, mantineImports, consts) {
+function containerGridMode(opening, mantineImports, consts, sourceCode) {
   let tag = resolveMantineTag(opening.name, mantineImports)
   let grid = opening
   if (tag === 'Grid.Col') {
@@ -4096,12 +4097,69 @@ function containerGridMode(opening, mantineImports, consts) {
   const breakpoints = attr('breakpoints')
   if (breakpoints === undefined) return 'fallback'
   let map = attrValue(breakpoints)
+  if (isShippedGridMap(sourceCode, map)) return 'container'
   if (map?.type === 'Identifier') map = consts.get(map.name)
   const nonEmpty =
     map?.type === 'ObjectExpression' && map.properties.some((prop) => prop.type === 'Property')
   return nonEmpty ? 'container' : 'fallback'
 }
 
+/**
+ * Whether `node` reads basalt's own `CONTAINER_GRID_BREAKPOINTS` — its value is known, so it is
+ * the one imported `breakpoints` map trusted. Resolved through the scope manager to the BINDING the
+ * identifier reads, never by local name: a parameter or inner `const` shadowing the import is not
+ * the import. The binding has to be an `ImportSpecifier` naming it from `basalt-ui/tokens` (any
+ * alias, not type-only), a `.CONTAINER_GRID_BREAKPOINTS` member of that module's namespace import,
+ * or a `const` whose initializer resolves the same way. Without a scope manager nothing is trusted
+ * — reported, the conservative answer.
+ */
+function isShippedGridMap(sourceCode, node, seen = new Set()) {
+  if (node?.type === 'MemberExpression') return isShippedGridMapMember(sourceCode, node)
+  if (node?.type !== 'Identifier' || seen.has(node)) return false
+  seen.add(node)
+  const def = soleDefinition(sourceCode, node)
+  if (def?.type === 'ImportBinding') {
+    const spec = def.node
+    const decl = def.parent
+    if (decl?.type !== 'ImportDeclaration' || decl.importKind === 'type') return false
+    if (decl.source?.value !== 'basalt-ui/tokens') return false
+    if (spec.type !== 'ImportSpecifier' || spec.importKind === 'type') return false
+    const imported = spec.imported
+    const importedName = imported.type === 'Identifier' ? imported.name : imported.value
+    return importedName === 'CONTAINER_GRID_BREAKPOINTS'
+  }
+  if (def?.type === 'Variable' && def.parent?.kind === 'const')
+    return isShippedGridMap(sourceCode, def.node.init, seen)
+  return false
+}
+
+/** `tokens.CONTAINER_GRID_BREAKPOINTS` (or `tokens['CONTAINER_GRID_BREAKPOINTS']`) on `import * as tokens from 'basalt-ui/tokens'`. */
+function isShippedGridMapMember(sourceCode, node) {
+  const property = node.property
+  const name = node.computed
+    ? isStringLiteral(property) && property.value
+    : property?.type === 'Identifier' && property.name
+  if (name !== 'CONTAINER_GRID_BREAKPOINTS' || node.object?.type !== 'Identifier') return false
+  const def = soleDefinition(sourceCode, node.object)
+  return (
+    def?.type === 'ImportBinding' &&
+    def.node.type === 'ImportNamespaceSpecifier' &&
+    def.parent?.importKind !== 'type' &&
+    def.parent?.source?.value === 'basalt-ui/tokens'
+  )
+}
+
+/** The one definition of the variable `identifier` reads, or `undefined` (unresolved, or more than one). */
+function soleDefinition(sourceCode, identifier) {
+  if (typeof sourceCode?.getScope !== 'function') return undefined
+  for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+    const variable = scope.set.get(identifier.name)
+    if (variable === undefined) continue
+    return variable.defs.length === 1 ? variable.defs[0] : undefined
+  }
+  return undefined
+}
+
 /**
  * The shell components that are `visibleFrom`/`hiddenFrom`'s legitimate home — the size-class
  * axis's one JSX escape hatch, alongside overlays. Matched by DECLARATION name, the same
@@ -4134,7 +4192,7 @@ const RAW_BREAKPOINT_EXEMPT_FILE = /(?:^|[\\/])(?:use-media-query\.ts|ChartToolt
 export const RAW_BREAKPOINT_RECIPE =
   'A page’s own layout keys on its container: <SimpleGrid type="container" cols={{ base: 1, ' +
   "'480px': 2, '800px': 3 }}> (px keys = CONTAINER_CLASSES, basalt-ui/tokens), or <Grid " +
-  'type="container" breakpoints={…}> mapping all five xs–xl onto those px widths, with Grid.Col ' +
+  'type="container" breakpoints={CONTAINER_GRID_BREAKPOINTS}> (basalt-ui/tokens), with Grid.Col ' +
   'span={{ base: 12, sm: 6 }} keyed through that map; a Flex direction swap becomes that SimpleGrid (equal ' +
   'columns), a wrapping Group, or a CSS-module @container basalt-grid rule. useSizeClass() is for ' +
   'shell chrome only. Recipes: basalt-ui MIGRATING.md § basalt/raw-breakpoint.'
@@ -4204,7 +4262,7 @@ const RAW_BREAKPOINT_HOOK_NAMES = new Set(['useMediaQuery', 'useMatches', 'useVi
  * declares a shell home (or a control's own C9 swap) is exempt for all four shapes uniformly — the
  * shell's own responsive chrome is the sanctioned use, whatever shape it takes.
  */
-// Ships: warn (grace → 1.33.0)
+// Ships: error
 const rawBreakpoint = {
   meta: {
     type: 'suggestion',
@@ -4238,6 +4296,7 @@ const rawBreakpoint = {
     // apart), so it is dropped from the map entirely rather than guessed at last-wins.
     const responsiveObjectConsts = new Map()
     const seenDeclaratorNames = new Set()
+    const sourceCode = context.sourceCode ?? context.getSourceCode?.()
 
     const noteShellHomeOwner = (name) => {
       if (typeof name === 'string' && SHELL_HOME_NAMES.has(name)) definesShellHome = true
@@ -4322,7 +4381,7 @@ const rawBreakpoint = {
             ? CONTAINER_ROUTED_PROPS[tag]
             : undefined
           const mode = routed?.has(node.name.name)
-            ? containerGridMode(owner, mantineImports, responsiveObjectConsts)
+            ? containerGridMode(owner, mantineImports, responsiveObjectConsts, sourceCode)
             : undefined
           if (mode === 'container') continue
           if (!containsResponsiveObjectValue(value, responsiveObjectConsts, mode !== undefined))
@@ -4373,59 +4432,7 @@ const rawBreakpoint = {
  *
  * @type {Record<string, GraceEntry>}
  */
-export const PLUGIN_RULE_GRACE = {
-  'control-outside-home': {
-    since: '1.26.0',
-    promote: '1.33.0',
-    why:
-      "Extended 1.32.0 -> 1.33.0 at the 1.32.0 release, the last extension: basalt's own tree is at 0 (consumer-loop r1 dogfood) and argo is at 2, but RE-MEASURED 2026-09-30 the fleet carries ~33 (image-gen 11, rb 7, image-share 6, weatherorb 5, email-gateway 4, argo 2). The 1.32.0 fleet upgrade clears them while they warn, together with raw-breakpoint, so 1.33.0 promotes all four ids against a measured-clean fleet. " +
-      'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
-      'the wave-6 control guards (docs/CONTROLS-SPEC.md §6). The one openly HEURISTIC rule of the ' +
-      'set — "this control has no home" is a claim about layout intent, so its false-positive load ' +
-      'is carried by four exemptions (overlay/settings-row ancestor, the overlay FILENAME ' +
-      'convention below, @mantine/form, owner definition) rather than by certainty. The other five ' +
-      'wave-6 rules promoted at 1.27.0; this one has not, across three re-datings. ' +
-      'RE-MEASURED 2026-09-09, every consumer freshly migrated to 1.29.2 and basalt built from ' +
-      'master: 29 incumbents across five repos — image-gen 10, rb 8, image-share 6, the playground ' +
-      '3, argo 2 — and zero in linewatch, meteo and obsidian. The 1.28.0 prediction held: ' +
-      "{@link isOverlayConventionFile} took argo's 9 cross-file overlay warns down to 2, which is " +
-      'the part of the remainder that was ever going to fall to an exemption. ' +
-      'Extended to 1.31.0, and the argument is NOT the count — it is that 1.30.0 is the first ' +
-      'release in which this rule names an answer the 29 can reach. Every home it listed was a ' +
-      'shell slot (PageBar / Section / WidgetHeader), so a consumer that mounts `BasaltProvider` ' +
-      'and no `BasaltShell` had no reachable home at all: image-gen is a Tauri window with a ' +
-      'hand-rolled header and carries 10 of the 29 by itself, and `bound-control-outside-home` ' +
-      'closed the `ViewTabs` escape it would otherwise have taken. 1.30.0 adds the missing ' +
-      'sentence to both messages ({@link SHELL_LESS_HOME_HINT} — a `PageBar` outside a shell ' +
-      'renders in flow, sticky, with its own title, which is what `src/shell/page-bar.tsx` ' +
-      'actually does). Promoting a rule to `error` in the same minor that first makes it ' +
-      'satisfiable hands a consumer zero minors to act on the answer, which is exactly the failure ' +
-      'the grace mechanism exists to prevent. 1.31.0 is when the 29 have been through the new home ' +
-      'and the remainder is measured against that number. A file outside the convention that is ' +
-      "still an overlay's own body declares it with " +
-      '`theme-allow-file control-outside-home — overlay`.',
-  },
-  'raw-breakpoint': {
-    since: '1.31.0',
-    promote: '1.33.0',
-    why:
-      'New in the wave-11 responsive/touch guards. Catches four independent shapes at once — a ' +
-      'responsive-object Mantine prop, visibleFrom/hiddenFrom outside the three shell homes, the ' +
-      'three raw viewport hooks, and window.matchMedia/innerWidth — none of which basalt policed ' +
-      'before this wave, so every consumer on an earlier minor has a green build with all four ' +
-      "shapes already in it. basalt-ui/content's own article-card.tsx (a `SimpleGrid cols={{ base: " +
-      "1, sm: 2, lg }}`) was one incumbent measured in basalt's own tree at ship time — a real " +
-      'number, not zero, so it shipped warn rather than error. ' +
-      'Extended 1.32.0 -> 1.33.0: 1.31.0 shipped the rule naming "a container query" but no ' +
-      'primitive, and MIGRATING never mentioned it (argo: 42 warns, no documented target). 1.32.0 ' +
-      'is the first minor with a reachable, documented answer (Mantine type="container" grids keyed ' +
-      'on CONTAINER_CLASSES, exempted here), and promoting in the minor that first makes a rule ' +
-      'satisfiable hands a consumer zero minors to act on it — the control-outside-home ' +
-      "extension's reasoning. 1.33.0 is when the incumbents are expected to have moved to a " +
-      'container grid or a theme-allow with a stated reason. Promotes together with its CSS twin, ' +
-      'the `raw-media-query` guard kind.',
-  },
-}
+export const PLUGIN_RULE_GRACE = {}
 
 /**
  * Plugin rules that stay `warn` in the shipped preset PERMANENTLY — outside the C16 version gate,