basalt-ui 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+# [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)
+
+
+### Bug Fixes
+
+* align guard lanes on FormRow/FormGroup, drop basalt-main ([17e673d](https://github.com/jkrumm/basalt-ui/commit/17e673d421c3e2f93be01c2b8d24e10e56d5b71c))
+* bottom-align FormGroup's row direction so a trailing button isn't stretched ([e5ca2ab](https://github.com/jkrumm/basalt-ui/commit/e5ca2ab5e433e4e3ef15f505913c672b4912f0e9))
+* export the size- and container-class tables from basalt-ui/tokens ([14fb784](https://github.com/jkrumm/basalt-ui/commit/14fb784586c3348a3647280e74ea905b2df0091b))
+* point every § Unreleased reference at the section the release names ([bc17710](https://github.com/jkrumm/basalt-ui/commit/bc1771001048f2883607d6917e6f94cc397865be))
+* resolve consts before unwrapping raw-breakpoint conditionals ([4f9cc79](https://github.com/jkrumm/basalt-ui/commit/4f9cc7912ae0805eb5e574f8ed8a8f9c068e0ddf))
+
 # [1.32.0](https://github.com/jkrumm/basalt-ui/compare/v1.31.0...v1.32.0) (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                                                                        | 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` (§ Unreleased)                                         | —                                                                             | —          |
-| **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 (§ Unreleased)                                                       | —                                                                             | —          |
-| **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 (§ Unreleased) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ Unreleased) | —          |
-| **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)                     | —                                                                                  | —                                                                     | —      | —                                                                                                         | —                                                                             | —          |
-| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                         | —                                                                             | —          |
-| **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 (§ Unreleased) | —          |
+| 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,215 @@ 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
+upgraded to 1.32.0; this section is what they had to find out by reading source.
+
+### Fixes you can now delete a workaround for
+
+| What                                                                                                                                                                                                                                                                                                                                                                  | Delete                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **`SIZE_CLASSES`, `CONTAINER_CLASSES`, `resolveContainerClass`, `ContainerClass` are exported from `basalt-ui/tokens`.** The 1.31.0/1.32.0 sections, the `raw-breakpoint` message and the `BasaltDataTable` JSDoc all named that import; it did not resolve. A test now fails the build when a fenced import in this file names a symbol its subpath does not export. | the local `container-classes.ts` mirror or the literal `'480px'`/`800` — import them                             |
+| **`FormRow` / `FormGroup` are control homes in `check-theme` too.** The oxlint plugin already treated them as homes; the text lane's `raw-selection-control` did not, so a correctly migrated form row warned (and would have errored at 1.33.0). A parity test now pins both lanes' home lists to one set.                                                           | every `theme-allow raw-selection-control — … FormRow/FormGroup …` waiver (grep `WORKAROUND: homed in a FormRow`) |
+| **`basalt-main` is no longer an accepted `@container` name.** Nothing ever declared it, so a query against it never matched. Declare your own container (`container: <name> / inline-size` on the element) or use `basalt-grid` on the parent.                                                                                                                        | `@container basalt-main …` — rewrite against a container you declare                                             |
+| **The `raw-media-query` message no longer over-claims.** Only `basalt-card` and unnamed `@container` queries are judged against the 0/240/480/800 table; any other declared name is accepted at any width. Same behaviour, honest text.                                                                                                                               | —                                                                                                                |
+| **`raw-breakpoint` exempts a `tests?/` directory** (e.g. a `tests/setup/dom.ts` `matchMedia` polyfill), not only `*.test.*`/`__tests__`. The message now says `cols={{ base: 3 }}` is just `cols={3}`, and a `(hover: none)` read gets a pointer-tier hint.                                                                                                           | the polyfill's `theme-allow raw-breakpoint`                                                                      |
+| **`FormGroup direction="row"` no longer stretches a trailing button** (`align-items: flex-end`).                                                                                                                                                                                                                                                                      | a `style={{ alignSelf: … }}` on the button                                                                       |
+
+**This patch also TIGHTENS two checks — expect NEW warnings after upgrading, still `warn` until
+1.33.0:** `raw-breakpoint` now sees a responsive object inside a conditional, logical or
+const-resolved prop value (`span={wide ? { base: 12, md: 4 } : 12}` used to slip through), and
+`raw-media-query` rejects `@container basalt-main`. (The `FormRow`/`FormGroup` change only removes
+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 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
+the `check-theme` lane; nothing here asks it to adopt `type="container"` grids.
+
+### Container recipes 1.32.0 left implicit
+
+**Swap two children at a container width in ONE query** — narrow default, flip both sides inside
+one `min-width` rule. A `max-width: 799.9px` / `min-width: 800px` pair leaves a sub-pixel band where
+both or neither render.
+
+```css
+.root {
+  container: basalt-grid / inline-size;
+}
+.wide {
+  display: none;
+}
+@container basalt-grid (min-width: 800px) {
+  .narrow {
+    display: none;
+  }
+  .wide {
+    display: block;
+  }
+}
+```
+
+**A plain Mantine `Table` (not `BasaltDataTable`)** has no column fold or card projection; the
+sanctioned remedy is the same CSS module — declare the container on the wrapper and hide columns or
+swap to a list inside a `min-width` query. `BasaltDataTable` needs the optional
+`@tanstack/react-table` peer; don't add it only to get the fold.
+
+**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 — 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.
+
+**`ResponsiveChartHeight` `sm` (768px) → which key.** `wide` (800) is 32px later and keeps the old
+step's meaning ("tablet or wider"); `regular` (480) opens 288px earlier. Pick by which side of the old
+width the height was for.
+
+### `BasaltDataTable` `renderCard` (1.32.0, undocumented here until now)
+
+The law lives in the prop's JSDoc (`src/data/data-table.tsx`, shipped in `dist/data/table.d.ts`).
+The points consumers tripped on:
+
+- Swaps at the table's OWN width `< CONTAINER_CLASSES.regular` (480px), not the viewport.
+- Card order is the table's processed order — sort, filter, page. For a domain order, pass
+  `initialSorting` or sort `data`; there is no second sort.
+- `minWidth` disables the COLUMN fold (it declares a horizontal floor) and is ignored by the card
+  list. `stickyHeader` alone keeps the fold; pair it with `maxHeight` to stick at every width.
+- Activation is click or **Enter** — not Space (the browser's page scroll on a focused non-button).
+
+### Shell-less apps and the 1.31.0 breakpoint move
+
+1.31.0 moved `sm` from 48em to **52.5em** (840px). What its checklist missed:
+
+- **Re-key your own literals:** grep `.css` for `47.99375em` / `48em` → `52.49375em` / `52.5em`.
+- **A shell-less app's gutter / sticky-bar CSS belongs under your own `shell/` directory** at
+  52.5em: any `shell/`-pathed CSS may write a width `@media` at a `SIZE_CLASSES` boundary; anywhere
+  else it is `raw-media-query`.
+- **A consumer-owned Mantine `AppShell`** resolves `navbar.breakpoint` / `aside.breakpoint` through
+  `theme.breakpoints`, so `breakpoint: 'sm'` collapses at 840px now, not 768px.
+- **In the `medium` class the sidebar defaults to the rail**, and the rail hides a `kind: 'custom'`
+  block entirely (a list block keeps a dot only with both `icon` and `count`). Anything a
+  `medium`-width user needs must not live only in a custom block.
+- **`PageBar` without a shell:** see the shell-less example in its JSDoc — `title` leads the one
+  sticky bar, and `classNames.root` is where the gutter bleed goes.
+
+### `useSizeClass()` outside the shell — two sanctioned uses
+
+Layout stays a container decision; an overlay's form (`Drawer` side, sheet vs dialog) and content
+paired with a `ViewTabs` option `only: 'sm-down'` may read it. Law and wording:
+`agent/rules/basalt-mantine.md` (a shipped rule, placed by `basalt-ui sync`).
+
 ## 1.32.0 — `basalt/raw-breakpoint` gets its answer
 
 ### The C1 pair (`control-outside-home` / `raw-selection-control`) — `error` at 1.33.0, the last extension
@@ -105,7 +314,7 @@ minor with a documented answer). A `theme-allow raw-breakpoint — <reason>` wai
 
 **Its CSS twin, the `raw-media-query` guard kind** (`basalt-ui check-theme`), enforces the same law
 in `.css`: a width `@media` outside `shell/**`, an `@container` name other than `basalt-card` /
-`basalt-form` / `basalt-main` / `basalt-grid` or at a width off a `CONTAINER_CLASSES` boundary, and
+`basalt-form` / `basalt-grid` (`basalt-main` was listed here too; dropped in 1.32.1, nothing declared it) or at a width off a `CONTAINER_CLASSES` boundary, and
 a pointer query other than `coarse`/`fine`. Same `warn`, and it moved with the rule — **`error` at
 1.33.0** (was 1.32.0). `theme-allow raw-media-query — <reason>` waives one line.
 
@@ -138,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>
 ```
@@ -406,7 +614,7 @@ exactly the case it was restored for. Measured: a 7-entry legend in a 92–150px
 entries at `maxRows` 3, 6 **and** 99, with five series drawn in colours nothing named.
 
 The fit now resolves an ABSENT cap only. When a caller states a number on a `fill` band, the legend
-takes the ENTRIES it asked for (`maxRows` counts entries, not rows — see § Unreleased) and
+takes the ENTRIES it asked for (`maxRows` counts entries, not rows — see § 1.30.1) and
 **`VX.minPlotHeight` stops being a floor** — the plot yields the height instead. Both things that used to trim the number are framework DEFAULTS (the tier's cap,
 and a floor about the plot); the stated number is the only intent in the room.
 
@@ -571,7 +779,7 @@ children is invisible to every rule. Grep for `SimpleGrid` before concluding the
 ### Charts — a responsive `height`, and the legend escape 1.30.0 promised
 
 Both of these landed in 1.30.0 with no row here, and both were only partly reachable. **Read this
-section against 1.30.1, not 1.30.0** — the § Unreleased entries above are what makes them usable.
+section against 1.30.1, not 1.30.0** — the § 1.30.1 entries above are what makes them usable.
 
 - **`height` accepts `{ base, sm?, md?, lg? }`** as well as a plain number, resolved against the
   chart's MEASURED container width (the same width the tier reads), not the viewport. In 1.30.0 the
@@ -583,7 +791,7 @@ section against 1.30.1, not 1.30.0** — the § Unreleased entries above are wha
   measured box, so a 380px inspector panel on a 1440px desktop IS "a phone" and its two-row default
   rolled a six-series legend up to `+4 more` with no way to say no. `margin` and `xLabelRotate`
   always had that escape; the legend did not. Under `fill` a measured cap still applies on top — see
-  § Unreleased for what that actually costs, because "can still roll up FURTHER" understated it.
+  § 1.30.1 for what that actually costs, because "can still roll up FURTHER" understated it.
 
 ### Toolchain — the shipped lefthook preset's `check-theme`, and what it does NOT fix
 

package/agent/rules/basalt-mantine.md

@@ -97,8 +97,8 @@ Depth-tier law (which token for which surface, why static, why the ring is inset
   clears the iOS zoom threshold via an `!important` floor (`sub-16-input-font` flags a smaller one).
 - **Charts measure themselves** — pass `height`/`aspectRatio`/`fill` only; never `useElementSize`
   in a chart file (Mantine is banned there), never raw `@visx/responsive` outside `charts/**`.
-- **A page's own layout keys on its container, not the viewport** — Mantine's `type="container"`
-  grids on `CONTAINER_CLASSES`; `useSizeClass()` is shell chrome only. Recipes: `MIGRATING.md`.
+- **A page's layout keys on its container, not the viewport** (`type="container"` grids, `CONTAINER_CLASSES`).
+  `useSizeClass()`: shell chrome, overlay form, `ViewTabs only: 'sm-down'` partners. Recipes: `MIGRATING.md`.
 
 ## Scroll regions
 

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 -->