basalt-ui 1.32.1 → 1.34.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 
 | Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass (useBreakpoint on notice), NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `basalt-ui/charts`          | headless        | CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

package/CHANGELOG.md

@@ -1,3 +1,68 @@
+# [1.34.0](https://github.com/jkrumm/basalt-ui/compare/v1.33.0...v1.34.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* --merge-lint replaces a guards-only extends instead of stacking it ([b2e551b](https://github.com/jkrumm/basalt-ui/commit/b2e551bc1dc431a457f58db2f8727c5f2546a9f2))
+* card-with-border remedy names its card-inset half ([1edfae7](https://github.com/jkrumm/basalt-ui/commit/1edfae79a0366d0f6c4618a7bd07d8c2370a1753))
+* derive basalt's --vx-* families from every emitted name ([07ea183](https://github.com/jkrumm/basalt-ui/commit/07ea1834f4cfc14979bb81e4cd2afc5849f28712))
+* dev-gate the basalt-family ref warning and pin its version ([23396df](https://github.com/jkrumm/basalt-ui/commit/23396df7d4fbb1f7b16f0d2f192c07485b6a4e47))
+* give icon-less nav items a first-letter glyph and a name in the rail ([9095f15](https://github.com/jkrumm/basalt-ui/commit/9095f157d1652316f03e2ff1668faddb406a34ef))
+* name an icon-less row by aria-label only in the collapsed rail ([bc13e09](https://github.com/jkrumm/basalt-ui/commit/bc13e09ff3c12e56be98c5353cf95c5925463ff9))
+* never autofix a removed deprecation row ([0534a28](https://github.com/jkrumm/basalt-ui/commit/0534a287da5252b8699b9bd4eb5ec36c1279b1b9))
+* refuse a release that reaches a deprecation's removeIn while it still ships ([eb55145](https://github.com/jkrumm/basalt-ui/commit/eb5514507011e9b9fdb7f1a23e335bc1c478c3aa))
+* restore check-grace's singular 'grace entry' in the clear line ([6fca61c](https://github.com/jkrumm/basalt-ui/commit/6fca61cb5ec1dae71b1f8b9661817a17919ca9b5))
+* take the rail glyph from a real grapheme via Intl.Segmenter ([ff4e396](https://github.com/jkrumm/basalt-ui/commit/ff4e39637f12cddb8817cd4be9367bb63f0ab5fc))
+* treat a false icon as absent and expose a label-only glyph helper ([323ddbb](https://github.com/jkrumm/basalt-ui/commit/323ddbb0dc28c41b54c1c33271eb7d6a348ab1bd))
+
+
+### Features
+
+* check-theme names an unwired AST lane ([91472ef](https://github.com/jkrumm/basalt-ui/commit/91472efbf87b336716c1871392878e648b355cd0))
+* judge every unemitted name inside a basalt-owned --vx-* family ([4864a9d](https://github.com/jkrumm/basalt-ui/commit/4864a9d78a0a0ef95d1f6caee85043b0d64c75ea))
+* remove useBreakpoint, overdue since 1.33.0 ([d68f538](https://github.com/jkrumm/basalt-ui/commit/d68f538dde34acecda481f567c17ade5a86074d4))
+* ship a guards-only oxlint preset, configs/oxlint-basalt.json ([f96d150](https://github.com/jkrumm/basalt-ui/commit/f96d15097aabf5461b524270eb5ce523928bfab5))
+* ship CONTAINER_KEYS for SimpleGrid type="container" keys ([acb5933](https://github.com/jkrumm/basalt-ui/commit/acb5933cf407cfb203819ad09bb7cf0315f73e79))
+
+# [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                                                                        | 1.34.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)           | `CONTAINER_KEYS` (§ 1.34.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`) | —                                                                             | `useBreakpoint` removed (§ 1.34.0) | —          |
+| **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,197 @@ 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.34.0 — the 1.34.0 minor
+
+### `CONTAINER_KEYS` — the `SimpleGrid type="container"` keys ship
+
+`basalt-ui/tokens` exports `CONTAINER_CLASSES` as the CSS lengths `SimpleGrid type="container"`
+keys take (`compact` 240px · `regular` 480px · `wide` 800px), so the computed key is one import
+instead of a template literal at every call site (argo: 19 sites behind two local `CQ_*` consts).
+`micro` has no key — `base` is that class. `basalt/raw-breakpoint` judges theme names only, so the
+computed key is green; nothing to waive.
+
+```tsx
+import { CONTAINER_KEYS as CQ } from 'basalt-ui/tokens'
+;<SimpleGrid type="container" cols={{ base: 1, [CQ.regular]: 2, [CQ.wide]: 3 }}>
+  …
+</SimpleGrid>
+```
+
+| Delete                                                                                        | Replace with               |
+| --------------------------------------------------------------------------------------------- | -------------------------- |
+| ``[`${CONTAINER_CLASSES.regular}px`]`` (or `.wide` / `.compact`) as a key                     | `[CONTAINER_KEYS.regular]` |
+| a local ``CQ_REGULAR = `${CONTAINER_CLASSES.regular}px` `` const (argo's `container-grid.ts`) | the import above           |
+
+`Grid type="container"` is unchanged: `breakpoints={CONTAINER_GRID_BREAKPOINTS}` (§ 1.33.0) stays
+its answer, and that map is now built from `CONTAINER_KEYS` — same values.
+
+### `useBreakpoint` — removed from `basalt-ui`
+
+| Was                                         | Now                                                                                                                                                                                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useBreakpoint` — removed from `basalt-ui`  | shell chrome: `useSizeClass() !== 'compact'` for `'sm'`, `useSizeClass() === 'expanded'` for `'lg'`; a page's own layout swap: a `type="container"` SimpleGrid/Grid or an `@container` rule (§ 1.32.0 `basalt/raw-breakpoint`) |
+| `BreakpointName` — removed from `basalt-ui` | — (no replacement; `SizeClass` is the shell's vocabulary)                                                                                                                                                                      |
+
+On notice since 1.31.0, dated twice (1.31.0 → 1.33.0) and shipped one minor past that date; measured
+fleet usage at removal was zero. The fix was never autofixable (the replacement is a different
+shape), so `basalt/deprecated-export` keeps its row through 1.34.0 only to say the import is gone
+instead of "still resolves".
+
+### Guards — `unknown-vx-token` judges basalt's families in full (`warn`, `error` moves to 1.35.0)
+
+`var(--vx-surface-2, transparent)` rendered transparent in image-gen since the file was written,
+and 1.33.0 said nothing: it judged only removed names and bare roots, because `groupTokens` could
+emit any name. Now:
+
+- **Judged: every unemitted name inside a basalt-owned family** — the leading lowercase run of the
+  name: `accent`, `fill`, `ink`, `line`, `radius`, `shadow`, `space`, `status`, `surface`, `text`,
+  `tooltip`, … (the full list is in the finding's remedy, generated from what basalt emits). So
+  `--vx-surface-2`, `--vx-ink3`, `--vx-space-gutter` and a bare `--vx-space` are all findings.
+- **Not judged: a name in any other family** (argo's `--vx-activity-*`, rb's `--vx-confidence-*`),
+  a computed name, and a name the same file declares.
+- **`groupTokens` / `seriesTokens` warn** (once per name) on a ref inside a basalt family —
+  `groupTokens('surface', …)`, a series key `ink3` — and **throw from 1.35.0**, when the kind
+  promotes. That refusal is what makes the guard's judgement sound. Rename the group
+  (`groupTokens('app', …)`), and its `buildPaletteCss` `groups` key with it. Measured: no consumer
+  names one. `on` is not judged: the theme emits `--vx-on-<color>` for your own colors too.
+
+Widening restarts the grace: `warn` through 1.34.x, `error` at 1.35.0. Measured at ship time:
+argo, rb, image-gen, image-share, email-gateway, linewatch, obsidian, weatherorb all at 0
+(image-gen's one hit was already fixed by hand in r4).
+
+### `check-theme` says when the AST lane is not wired
+
+When the nearest `.oxlintrc.json` up to the repo root neither extends a shipped preset nor loads
+`configs/oxlint-plugin.js` with `basalt/*` rules on (or the target does not resolve), `check-theme`
+prints one line — `AST lane not enforced — N basalt/* rule ids unguarded (incl. the promoted
+control-outside-home, raw-breakpoint)`. Information only; the exit code is unchanged. `basalt-ui
+doctor` names the fix.
+
+### `card-with-border` names its `card-inset` half
+
+Dropping `withBorder` and keeping `padding="md"` satisfied `check-theme` and then failed oxlint's
+`basalt/card-inset`. The text-lane remedy now says to fix the inset in the same edit.
+
+### `configs/oxlint-basalt.json` — the guard lane without the generic preset
+
+Wiring `configs/oxlint.json` into a repo with history turns on the generic jsx-a11y / unicorn /
+import / promise set alongside the `basalt/*` rules, and email-gateway hit unrelated errors before a
+single guard could land. The new guards-only preset is the `basalt/*` plugin rules at their shipped
+levels and nothing else:
+
+```json
+{ "extends": ["./node_modules/basalt-ui/configs/oxlint-basalt.json"] }
+```
+
+Take it first, move to `configs/oxlint.json` when the generic debt is paid. The full preset now
+`extends` the guards-only one, so every `basalt/*` level lives in one file; extending the full one
+behaves exactly as before. `doctor` and `check-theme` accept either.
+
+The full preset assumes the shipped `tsconfig.react-app.json` base (`lib: ES2023`): its
+`unicorn/no-array-sort` warning steers to `toSorted()`, which an older `lib` does not type. Extend
+that tsconfig rather than waiving the rule.
+
+## 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 (from 1.34.0:
+`[CONTAINER_KEYS.regular]`, § 1.34.0).
+
+### 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 +300,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 +340,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 +439,11 @@ 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'
-<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}>
+import { CONTAINER_KEYS as CQ, CONTAINER_GRID_BREAKPOINTS } from 'basalt-ui/tokens'
+// CONTAINER_KEYS ships from 1.34.0; before it, [`${CONTAINER_CLASSES.regular}px`]
+<SimpleGrid type="container" cols={{ base: 1, [CQ.regular]: 3 }}>…</SimpleGrid>
+// 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/README.md

@@ -872,6 +872,9 @@ The `./configs/*` export gives consumer apps raw presets to `extends` or copy vi
 { "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }
 ```
 
+`configs/oxlint-basalt.json` is the guard lane alone — the `basalt/*` rules, none of the generic
+jsx-a11y / unicorn / import set — for a repo with history to take first; `oxlint.json` extends it.
+
 `tsconfig.json` `extends` resolves the SAME way, through package exports (`bundler`
 `moduleResolution`, CI-verified by `scripts/pack-test.sh`) — three raw presets, `base` (the shared
 strict flags), `react-app` (`base` + DOM/JSX libs) and `node` (`base` + Node types):

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/agent/skills/basalt-app/SKILL.md

@@ -27,9 +27,11 @@ once and yours forever. Claude Code cannot load rules or skills out of `node_mod
 only reason anything is copied at all; everything a MACHINE reads is an `extends` reference into
 `node_modules/basalt-ui/configs/`, so the toolchain auto-updates with the package.
 
-**`init` on an existing app is a lint-debt event, not a no-op** — read
-`.claude/rules/basalt-batteries.md` § "App bootstrapping" for what it turns on and what keeping your
-own `.oxlintrc.json` costs.
+**`init` on an existing app is a lint-debt event, not a no-op** — `.claude/rules/basalt-batteries.md`
+§ "App bootstrapping" says what it turns on. Too much at once? Extend `configs/oxlint-basalt.json`
+(the basalt/\* guards alone, no generic jsx-a11y/unicorn set) first, `configs/oxlint.json` later —
+the full one pairs with the shipped `tsconfig.react-app.json` (ES2023 lib: `unicorn/no-array-sort`
+steers to `toSorted()`).
 
 ## 2. Wire the runtime (the CLI scaffolds files, not your app's composition)
 

package/configs/oxlint-basalt.json

@@ -0,0 +1,33 @@
+{
+  "jsPlugins": ["./oxlint-plugin.js"],
+  "rules": {
+    "basalt/no-raw-font-size": "error",
+    "basalt/raw-size-literal": "error",
+    "basalt/card-inset": "error",
+    "basalt/chart-in-raw-surface": "error",
+    "basalt/hand-rolled-plot": "error",
+    "basalt/chart-legend-literal": "error",
+    "basalt/shadow-basalt-export": "warn",
+    "basalt/hand-rolled-shell": "error",
+    "basalt/raw-scroll-container": "error",
+    "basalt/hand-rolled-filter": "error",
+    "basalt/control-outside-home": "error",
+    "basalt/bound-control-outside-home": "error",
+    "basalt/control-size-literal": "error",
+    "basalt/page-bar-budget": "error",
+    "basalt/in-body-page-title": "error",
+    "basalt/responsive-twin": "error",
+    "basalt/search-literal-link": "error",
+    "basalt/use-search-from-literal": "error",
+    "basalt/provider-above-router": "error",
+    "basalt/query-fn-unwrap": "error",
+    "basalt/deprecated-export": "warn",
+    "basalt/forms-field-key": "error",
+    "basalt/visx-boundary": "error",
+    "basalt/visx-tooltip": "error",
+    "basalt/agent-resume-guard": "error",
+    "basalt/agent-no-raw-usechat": "error",
+    "basalt/ai-sdk-major": "error",
+    "basalt/raw-breakpoint": "error"
+  }
+}