basalt-ui 1.33.0 → 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,29 @@
+# [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)
 
 

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                                                                                                          | 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)         | —          |
+| 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,97 @@ 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
@@ -113,7 +204,8 @@ The trust is provenance-gated: the import must name `CONTAINER_GRID_BREAKPOINTS`
 `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.
+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`
 
@@ -347,8 +439,9 @@ 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, CONTAINER_GRID_BREAKPOINTS } from 'basalt-ui/tokens'
-<SimpleGrid type="container" cols={{ base: 1, [`${C.regular}px`]: 3 }}>…</SimpleGrid>
+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>

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/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"
+  }
+}

package/configs/oxlint-plugin.js

@@ -3623,6 +3623,7 @@ const queryFnUnwrap = {
  *   prop?: string
  *   replacement: string
  *   removeIn: string
+ *   removed?: true
  *   fix?: false
  * }} DeprecatedExport
  */
@@ -3646,7 +3647,12 @@ const queryFnUnwrap = {
  * `removeIn` at least one minor out, add the `MIGRATING.md` row, and this rule starts nudging.
  * `oxlint-plugin.test.ts` scans every `src/**\/index.ts(x)` barrel for a JSDoc `@deprecated` and
  * fails when one has no row here, so the barrel half cannot be forgotten. Removing the export is a
- * separate commit that deletes the row in the same change.
+ * separate commit that either deletes the row (the fix is manual from then on — say so in the
+ * removal's MIGRATING row) or keeps it one minor past the removal with `removed: true` and
+ * `removeIn` set to the removing minor, so the message reads "was removed in X" instead of "still
+ * resolves" — and never autofixes, whatever `fix` says. `scripts/check-grace.ts` refuses a release
+ * at or past a `removeIn` whose export still ships — the gap that let `useBreakpoint` outlive its
+ * date twice.
  *
  * @type {readonly DeprecatedExport[]}
  */
@@ -3662,8 +3668,8 @@ export const DEPRECATED_EXPORTS = [
     name: 'useBreakpoint',
     replacement:
       'useSizeClass() for shell chrome; a page’s own layout swap is a container decision — a type="container" SimpleGrid/Grid or an @container rule',
-    removeIn: '1.33.0',
-    fix: false,
+    removeIn: '1.34.0',
+    removed: true,
   },
 ]
 
@@ -3672,6 +3678,13 @@ function deprecatedExportMessage(row) {
     row.prop === undefined
       ? `\`${row.name}\` from ${row.subpath}`
       : `\`${row.prop}\` on <${row.name}>`
+  if (row.removed === true) {
+    return (
+      `Removed basalt export — ${what} was removed in ${row.removeIn} and no longer resolves; use ` +
+      `\`${row.replacement}\` instead (packages/basalt-ui/MIGRATING.md carries the row). ` +
+      '(basalt/deprecated-export)'
+    )
+  }
   return (
     `Deprecated basalt export — ${what} is superseded by \`${row.replacement}\` and is removed in ` +
     `${row.removeIn}. It still resolves today, so nothing is broken yet; migrate before that minor ` +
@@ -3724,7 +3737,8 @@ const deprecatedExport = {
           context.report({
             node: spec,
             message: deprecatedExportMessage(row),
-            ...(row.fix === false
+            // A removed row's replacement is prose for a gone import, never a drop-in name.
+            ...(row.fix === false || row.removed === true
               ? {}
               : { fix: (fixer) => fixer.replaceText(spec, `${row.replacement} as ${local}`) }),
           })
@@ -4186,12 +4200,13 @@ const RAW_BREAKPOINT_EXEMPT_FILE = /(?:^|[\\/])(?:use-media-query\.ts|ChartToolt
  * (`CONTAINER_CLASSES`, `basalt-ui/tokens`: compact 240 / regular 480 / wide 800), never on the
  * viewport — `useSizeClass()` is the shell's seam, not a page's. Mantine 9's own `type="container"`
  * grids are the primitive: both self-wrap in an `inline-size` container, so they need no ancestor.
- * The px literals are `CONTAINER_CLASSES` written out (the plugin cannot import TS source);
+ * The px literals are `CONTAINER_KEYS` written out (the plugin cannot import TS source);
  * `oxlint-plugin.test.ts` asserts every one against it, and the MIGRATING recipe too.
  */
 export const RAW_BREAKPOINT_RECIPE =
   'A page’s own layout keys on its container: <SimpleGrid type="container" cols={{ base: 1, ' +
-  "'480px': 2, '800px': 3 }}> (px keys = CONTAINER_CLASSES, basalt-ui/tokens), or <Grid " +
+  '[CONTAINER_KEYS.regular]: 2, [CONTAINER_KEYS.wide]: 3 }}> (basalt-ui/tokens; the keys are ' +
+  "the px lengths '480px'/'800px'), or <Grid " +
   'type="container" breakpoints={CONTAINER_GRID_BREAKPOINTS}> (basalt-ui/tokens), with Grid.Col ' +
   'span={{ base: 12, sm: 6 }} keyed through that map; a Flex direction swap becomes that SimpleGrid (equal ' +
   'columns), a wrapping Group, or a CSS-module @container basalt-grid rule. useSizeClass() is for ' +

package/configs/oxlint-plugin.test.ts

@@ -644,7 +644,7 @@ describe('basalt/ai-sdk-major', () => {
 describe('basalt/raw-scroll-container promotion', () => {
   it('ships "error" (not "warn"/"off") in the consumer preset', () => {
     const shipped = JSON.parse(
-      readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8'),
+      readFileSync(resolve(import.meta.dirname, 'oxlint-basalt.json'), 'utf8'),
     ) as { rules: Record<string, unknown> }
     expect(shipped.rules['basalt/raw-scroll-container']).toBe('error')
   })
@@ -682,7 +682,7 @@ describe('basalt agent rules promotion', () => {
     '%s ships "error" (not "warn"/"off") in the consumer preset',
     (rule) => {
       const shipped = JSON.parse(
-        readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8'),
+        readFileSync(resolve(import.meta.dirname, 'oxlint-basalt.json'), 'utf8'),
       ) as { rules: Record<string, unknown> }
       expect(shipped.rules[rule]).toBe('error')
     },
@@ -1402,7 +1402,9 @@ describe('twin lanes share one promotion', () => {
 })
 
 describe('PLUGIN_RULE_GRACE', () => {
-  const shipped = JSON.parse(readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8')) as {
+  const shipped = JSON.parse(
+    readFileSync(resolve(import.meta.dirname, 'oxlint-basalt.json'), 'utf8'),
+  ) as {
     rules: Record<string, unknown>
   }
   const pkgVersion = (
@@ -3357,8 +3359,26 @@ describe('basalt/query-fn-unwrap', () => {
 
 // ── deprecated-export (B4) ───────────────────────────────────────────────────
 
-// deprecated-export's behaviour tests were removed with the last ledger row in 1.29.0; the
-// ledger-shape and barrel-scan assertions below keep the mechanism honest until the next row.
+describe('basalt/deprecated-export', () => {
+  it('reports a removed row as gone, never as "still resolves"', () => {
+    const { code, rules, output } = run(
+      `import { useBreakpoint } from 'basalt-ui'\nexport const x = useBreakpoint\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('deprecated-export')
+    expect(output).toContain('was removed in 1.34.0')
+    expect(output).not.toContain('still resolves')
+  })
+
+  // The row no longer says `fix: false`; `removed` alone must suppress the rewrite, because a
+  // removed row's replacement is prose (`useSizeClass() for shell chrome; …`), not a name.
+  it('never autofixes a removed row', () => {
+    const source = `import { useBreakpoint } from 'basalt-ui'\nexport const x = useBreakpoint\n`
+    writeFileSync(resolve(dir, 'removed-fix.tsx'), source)
+    Bun.spawnSync([OXLINT_BIN, '-c', '.oxlintrc.json', '--fix', 'removed-fix.tsx'], { cwd: dir })
+    expect(readFileSync(resolve(dir, 'removed-fix.tsx'), 'utf8')).toBe(source)
+  })
+})
 
 // ── forms-field-key ──────────────────────────────────────────────────────────
 
@@ -3574,6 +3594,23 @@ describe('basalt/raw-breakpoint', () => {
       ).not.toContain('raw-breakpoint')
     })
 
+    it('does NOT flag CONTAINER_KEYS computed keys (named, aliased, namespace)', () => {
+      const keyed = (imp: string, key: string) =>
+        run(
+          `import { SimpleGrid } from '@mantine/core'\n${imp}\n` +
+            `export const C = () => <SimpleGrid type="container" cols={{ base: 1, [${key}.regular]: 2, [${key}.wide]: 3 }} />\n`,
+        ).rules
+      expect(
+        keyed(`import { CONTAINER_KEYS } from 'basalt-ui/tokens'`, 'CONTAINER_KEYS'),
+      ).not.toContain('raw-breakpoint')
+      expect(keyed(`import { CONTAINER_KEYS as CQ } from 'basalt-ui/tokens'`, 'CQ')).not.toContain(
+        'raw-breakpoint',
+      )
+      expect(
+        keyed(`import * as tokens from 'basalt-ui/tokens'`, 'tokens.CONTAINER_KEYS'),
+      ).not.toContain('raw-breakpoint')
+    })
+
     it('does NOT flag a lone `base` under type="container"', () => {
       expect(grid(`<SimpleGrid type="container" cols={{ base: 2 }} />`).rules).not.toContain(
         'raw-breakpoint',
@@ -3997,16 +4034,39 @@ describe('DEPRECATED_EXPORTS', () => {
     }
   ).version
 
-  it('carries a replacement and a removeIn at least one minor out on every row', () => {
-    const [major, minor] = pkgVersion.split('.').map(Number)
-    const floor = `${major}.${(minor as number) + 1}.0`
+  const [major, minor] = pkgVersion.split('.').map(Number)
+  const floor = `${major}.${(minor as number) + 1}.0`
+  const surface = JSON.parse(
+    readFileSync(resolve(import.meta.dirname, '..', 'scripts', 'export-surface.json'), 'utf8'),
+  ) as Record<string, string[]>
+  const shipped = (row: (typeof DEPRECATED_EXPORTS)[number]) =>
+    surface[row.subpath === 'basalt-ui' ? '.' : row.subpath.replace('basalt-ui', '.')]?.includes(
+      row.name,
+    ) === true
+
+  it('carries a replacement and a well-formed removeIn on every row', () => {
     for (const row of DEPRECATED_EXPORTS) {
       expect([row.name, row.replacement.length > 0]).toEqual([row.name, true])
       expect([row.name, /^\d+\.\d+\.\d+$/.test(row.removeIn)]).toEqual([row.name, true])
+    }
+  })
+
+  // A live row still ships, so its removal is still ahead: at least the next minor.
+  it('dates every live row at least one minor out', () => {
+    for (const row of DEPRECATED_EXPORTS.filter((r) => r.removed !== true)) {
       expect([row.name, compareSemver(row.removeIn, floor) >= 0]).toEqual([row.name, true])
     }
   })
 
+  // A removed row is kept past the removal only for its message: the export must really be gone,
+  // and the removing minor is the next one at the latest — never a date still ahead.
+  it('pins every removed row to an export that no longer ships', () => {
+    for (const row of DEPRECATED_EXPORTS.filter((r) => r.removed === true)) {
+      expect([row.name, compareSemver(row.removeIn, floor) <= 0]).toEqual([row.name, true])
+      if (row.prop === undefined) expect([row.name, shipped(row)]).toEqual([row.name, false])
+    }
+  })
+
   it('names a real published subpath on every row', () => {
     const exports = Object.keys(
       (
@@ -4064,7 +4124,9 @@ describe('DEPRECATED_EXPORTS', () => {
 describe('the `Ships:` line above each rule', () => {
   const source = readFileSync(resolve(import.meta.dirname, 'oxlint-plugin.js'), 'utf8')
   const lines = source.split('\n')
-  const shipped = JSON.parse(readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8')) as {
+  const shipped = JSON.parse(
+    readFileSync(resolve(import.meta.dirname, 'oxlint-basalt.json'), 'utf8'),
+  ) as {
     rules: Record<string, unknown>
   }
   // The registry block maps rule id → the `const` implementing it.
@@ -4077,7 +4139,7 @@ describe('the `Ships:` line above each rule', () => {
   })
 
   for (const { id, binding } of registry) {
-    it(`${id}: the claim matches oxlint.json`, () => {
+    it(`${id}: the claim matches oxlint-basalt.json`, () => {
       const at = lines.indexOf(`const ${binding} = {`)
       expect([id, at]).not.toEqual([id, -1])
       const claim = /^\/\/ Ships: (.+)$/.exec(lines[at - 1] as string)?.[1]
@@ -4102,3 +4164,29 @@ describe('the `Ships:` line above each rule', () => {
     })
   }
 })
+
+// emailgw r4b: wiring the full preset on a repo with history forced unrelated jsx-a11y/unicorn
+// errors before a single basalt/* rule could land. The guards-only preset is the guard lane alone,
+// and the full preset extends it, so every basalt/* level is stated in exactly one file.
+describe('configs/oxlint-basalt.json — the guards-only preset', () => {
+  const read = (file: string) =>
+    JSON.parse(readFileSync(resolve(import.meta.dirname, file), 'utf8')) as Record<string, unknown>
+  const guards = read('oxlint-basalt.json')
+  const full = read('oxlint.json')
+
+  it('carries the plugin and basalt/* rules, nothing from the generic preset', () => {
+    expect(Object.keys(guards).toSorted()).toEqual(['jsPlugins', 'rules'])
+    expect(guards['jsPlugins']).toEqual(['./oxlint-plugin.js'])
+    const ids = Object.keys(guards['rules'] as object)
+    expect(ids.filter((id) => !id.startsWith('basalt/'))).toEqual([])
+    expect(ids.length).toBeGreaterThan(0)
+  })
+
+  it('is extended by the full preset, which states no basalt/* level of its own', () => {
+    expect(full['extends']).toEqual(['./oxlint-basalt.json'])
+    expect(full['jsPlugins']).toBeUndefined()
+    expect(Object.keys(full['rules'] as object).filter((id) => id.startsWith('basalt/'))).toEqual(
+      [],
+    )
+  })
+})

package/configs/oxlint.json

@@ -1,6 +1,6 @@
 {
+  "extends": ["./oxlint-basalt.json"],
   "plugins": ["react", "typescript", "import", "unicorn", "jsx-a11y", "promise", "oxc"],
-  "jsPlugins": ["./oxlint-plugin.js"],
   "categories": {
     "correctness": "error",
     "suspicious": "warn"
@@ -22,35 +22,7 @@
       {
         "allow": ["__APP_VERSION__"]
       }
-    ],
-    "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"
+    ]
   },
   "overrides": [
     {

package/dist/cli/check-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-theme.d.ts","sourceRoot":"","sources":["../../src/cli/check-theme.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,aAAa,GAAE,MAAsB,EACrC,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CAuKR"}
+{"version":3,"file":"check-theme.d.ts","sourceRoot":"","sources":["../../src/cli/check-theme.ts"],"names":[],"mappings":"AA+EA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,aAAa,GAAE,MAAsB,EACrC,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CA6IR"}