basalt-ui 1.27.0 → 1.29.0

package/agent/rules/basalt-mantine.md

@@ -7,9 +7,9 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — card-with-border, hidden-inline-style, in-body-page-title, inline-display, inline-spacing, mantine-shade-index, raw-form-control, raw-html-layout, raw-motion-value, raw-spacing, sub-16-input-font · oxlint rules — basalt/card-inset, basalt/hand-rolled-shell, basalt/in-body-page-title, basalt/page-bar-budget, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
-<!-- not guarded: — -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
+<!-- backed by: guard kinds — card-with-border, hidden-inline-style, in-body-page-title, inline-display, inline-spacing, mantine-shade-index, raw-form-control, raw-html-layout, raw-motion-value, raw-spacing, sub-16-input-font · oxlint rules — basalt/card-inset, basalt/deprecated-export, basalt/hand-rolled-shell, basalt/in-body-page-title, basalt/no-import-meta-env, basalt/page-bar-budget, basalt/provider-above-router, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
+<!-- not guarded: no second cssVariablesResolver — don't hand-build createTheme or re-add the resolver basalt already installs -->
 <!-- /basalt:coverage -->
 
 # Basalt Mantine — provider, shell, surfaces
@@ -22,15 +22,21 @@ live in basalt-tokens.md — not restated here.
 
 Mount `BasaltProvider` at the top of the tree, **above the router** (Mantine's context must exist
 before any route renders), with `theme={createBasaltTheme(overrides)}`. Then the data layer, then
-`RouterProvider`. Don't hand-build `createTheme` and don't add a second `cssVariablesResolver`.
+`RouterProvider`. Don't hand-build `createTheme` and don't add a second `cssVariablesResolver`. The
+canonical composition — `BasaltProvider > QueryClientProvider > BasaltOverlays > RouterProvider`,
+and why that order is load-bearing — is the README's "Composition order" section; don't restate the
+tree here. No `'use client'` directive ships in the package; a Next.js App Router consumer wraps
+the composition in its own client file.
 
 **Overlays mount exactly once, through `BasaltOverlays`** (`basalt-ui/commands`), inside
 `BasaltProvider`: it composes `ModalsProvider`, Spotlight (against basalt's own store), the command
-hotkeys and `<Notifications>` in one place, each disableable with `false`. A standalone
-`<BasaltNotifications />` (`basalt-ui/notifications`) is the alternative for an app with no commands
-layer — **never both in one tree**, which double-mounts `<Notifications>`. Import the **layered**
-style bundles for every `@mantine/*` battery, then `basalt-ui/styles.css` last; an unlayered Mantine
-import outranks `@layer basalt` regardless of specificity.
+hotkeys and `<Notifications>` in one place, each disableable with `false`. `ModalsProvider` mounts
+as a **sibling** of `children`, not a wrapper — the imperative `modals.*`/`overlays.*` API works
+untouched, but `useModals()`/`openContextModal` need real React context, which a sibling cannot
+provide: pass `modals={false}` and mount your own `ModalsProvider` when you need either.
+`<BasaltOverlays notifications />` is the ONE notifications mount; there is no standalone
+component any more. Import the **layered** style bundle for every `@mantine/*` battery, then
+`basalt-ui/styles.css` last.
 
 Color scheme is read and written through `useMantineColorScheme()` only — never a client store,
 never `localStorage.getItem('theme')` (guard-enforced; see basalt-state.md).
@@ -56,101 +62,61 @@ projection:
 | `account`           | `BasaltAccountProps`                 | the footer row, below the settings menu                                                |
 
 - **The router seam is ONE component, not a render callback.** `SidebarItem.Anchor` (a `NavAnchor`)
-  is the consumer's `<Link>`; basalt renders every pixel around it — desktop row, mobile slot, sheet
-  row. Absent, the row falls back to `<a href>` + `onClick`. The breadcrumb's equivalent is
-  `parentAnchor`. There is no `renderNavLink` / `renderBreadcrumbLink` surface.
-- **`AppBreadcrumbs` is prop-driven** (`section` / `parent` / `parentAnchor` / `parentHref` /
-  `page`) and renders `null` without `page`. `BasaltShell` derives those props from the active item;
-  `useRouterBreadcrumbs` (basalt-state.md) is the router-side source for a custom trail.
-- **Collapse persists through basalt's own `createPersistedState`**, keyed `basalt:<storageKey>` —
-  read it with `readPersistedValue`, never a bare `localStorage.getItem`. Pass `collapsed` +
-  `onCollapsedChange` to own it instead (e.g. from your own hotkey — basalt binds none).
-- **The `.` entry is router-agnostic; a router adapter DOES ship**, at `./router-tanstack`. Badge /
-  active / navigate wiring stays consumer-side either way; `NavCountBadge` is the count pattern.
-- **The account row is presentational over a provider-agnostic contract** — basalt has no auth
-  dependency and ships no `./auth`. The authenticated row leads with initials derived from
-  `identity.name` (never an avatar image); the unauthenticated row falls back to a person glyph.
-  No separating hairline: the row's own top padding is the separation. The email is hidden unless
-  `showEmail` is passed.
-
-**Mobile is a tab bar, not a menu.** A slot is a destination, so a tap navigates with nothing to
-dismiss; there is no full-height mobile drawer, and everything it used to hold reaches the trailing
-More slot. `projectMobileNav` is a PURE projection and infers the surface from row count — 0 drops
-the slot, 1 collapses to a plain link (a group of one IS a destination), up to `menuMax` is a menu,
-more is a bottom sheet. `SidebarItem.mobile` (`'tab'` / `'more'` / `'hidden'`) is the per-destination
-placement; `MobileNavConfig` is the escape hatch, not the interface. Two bar rules that look like
-bugs and are not: the active indicator is a **neutral** ink tint behind the ICON only (never the
-identity blue, never a full-tab fill — the desktop sidebar's accent-icon rule does not apply here),
-and the bar carries **no** `env(safe-area-inset-bottom)` padding, because Mantine's own
-`AppShell.Footer` rule already grows the box by the inset. Search lives in the SIDEBAR, not the
-header; the header carries no bottom rule. "Zero horizontal rules" is not true of the mobile bar,
-which has a top border by design.
+  is the consumer's `<Link>`; absent, the row falls back to `<a href>` + `onClick`. The
+  breadcrumb's equivalent is `parentAnchor`. No `renderNavLink`/`renderBreadcrumbLink` surface.
+- **`AppBreadcrumbs` is prop-driven** (`section`/`parent`/`parentAnchor`/`parentHref`/`page`),
+  renders `null` without `page`; `useRouterBreadcrumbs` (basalt-state.md) sources a custom trail.
+- **Collapse persists through `createPersistedState`**, keyed `basalt:<storageKey>` — read with
+  `readPersistedValue`, never a bare `localStorage.getItem`.
+- **The account row is presentational, provider-agnostic** — no `./auth`. Authenticated leads with
+  initials from `identity.name` (never an avatar image); unauthenticated falls back to a glyph.
+
+**Mobile is a tab bar, not a menu.** A slot is a destination — a tap navigates with nothing to
+dismiss, no full-height drawer. `projectMobileNav` is a PURE projection inferring the surface from
+row count (0 drops the slot, 1 is a plain link, up to `menuMax` is a menu, more is a sheet).
+`SidebarItem.mobile` (`'tab'`/`'more'`/`'hidden'`) is the per-destination placement. The active
+indicator is a **neutral** ink tint behind the icon only (never the identity blue); the bar carries
+**no** `env(safe-area-inset-bottom)` (Mantine's `AppShell.Footer` already grows the box). Region
+edges come from `BasaltShell` itself (`--app-shell-border-color` → `--vx-divider`) — never draw a
+border or pass `withBorder` to a shell region yourself.
 
 ## Surfaces, depth and shape
 
-- **Never pass `withBorder` to a `Card`/`Paper`.** Card depth is `VX.shadowCard`, which bakes its 1px
-  ring into the shadow value; the theme pins bg/shadow/radius but does not clear `border`, so
-  `withBorder` draws a second real edge and the card reads heavy. It is on-token, so only the
-  `card-with-border` guard kind catches it. `<Card.Section withBorder>` is a section divider and fine.
-- **Three depth tiers, split control-vs-panel-vs-floating**, and the dividing line is that split —
-  never component-by-component. `shadowCard` for surfaces that HOLD content (Card, Paper,
-  Notification, ChartCard, SettingsSection): an outset ring on light, a deeper drop + inset rim on
-  dark. `shadowRaised` for anything you click or type into: **never an outset ring**, because an
-  outset ring paints in the color of whatever it is drawn over, so one value can ride a saturated
-  fill, a tint and a panel alike. `shadowOverlay` for detached floating surfaces (Tooltip, Popover,
-  Menu, Combobox, Modal, Drawer). Focus is a fourth tier and LAYERS over the resting depth.
-- **Emphasis is fill weight, not depth.** Every box-owning Button/ActionIcon variant takes the same
-  resting depth; `outline` takes the ring-free `shadowCtrl` (its border is its edge) and `subtle` is
-  **flat in both states** — a text affordance, with a neutral ink tint as its hover and nothing more.
-  **Depth is static**: no variant lifts or gains a shadow on hover or press. A hover lift and a
-  materializing `subtle` shadow were both tried and reverted.
-- **The ring must land on the box that carries the surface's `border-radius`** — it is drawn by that
-  box's own corners. `ChartCard` legitimately puts the shadow on a box with no background (an inner
-  box paints the fill, because `overflow: hidden` on the shadowed box would clip the shadow).
-- **Use Mantine primitives, not raw HTML** — `Box`/`Flex`/`Grid`/`SimpleGrid`/`Stack`/`Group`/
-  `Paper`/`Card` instead of a `<div>` with an inline `style`. **The second sanctioned fix is a CSS
-  module**, and in row code it is the right one: what the guard objects to is the inline literal, not
-  the `<div>`, and a class reading `var(--vx-*)` costs no component instance per row. `check-theme`
-  scans `.css`, so the tokens stay policed there. Only the Mantine-free `src/charts/**` may use raw
-  `<div>` freely — still with `VX.*`.
-- **Inputs come from `@mantine/core`**, never a native `<select>`; the theme defaults them to the
-  form tier, whose font size clears the iOS zoom threshold, and the floor in `styles.css` is
-  `!important` (`sub-16-input-font` flags a smaller one as dead code against it).
-- **Charts measure themselves** — pass `height` / `aspectRatio` / `fill` and nothing else. Never
-  `useElementSize` inside a chart file (Mantine is banned there), never raw `@visx/responsive`
-  outside `charts/**`.
+Depth-tier law (which token for which surface, why static, why the ring is inset) is
+`docs/DESIGN-CORE.md` § Layout, elevation, shapes — not restated here. Mantine-specific facts only:
+
+- **Never pass `withBorder` to a `Card`/`Paper`** — the theme pins bg/shadow/radius but does not
+  clear `border`, so `withBorder` draws a second real edge (`card-with-border` guard kind).
+  `<Card.Section withBorder>` is a section divider and fine.
+- **The ring lands on the box carrying the surface's `border-radius`** — `ChartCard` puts the
+  shadow on a box with no background (an inner box paints the fill; `overflow: hidden` on the
+  shadowed box would clip the shadow otherwise).
+- **Use Mantine primitives, not raw HTML** — `Box`/`Flex`/`Grid`/`Stack`/`Group`/`Paper`/`Card`
+  over a `<div>` with an inline style; a CSS module reading `var(--vx-*)` is the sanctioned second
+  fix in row code. Only Mantine-free `src/charts/**` uses raw `<div>` freely.
+- **Inputs come from `@mantine/core`**, never a native `<select>` — the form tier's font size
+  clears the iOS zoom threshold via an `!important` floor (`sub-16-input-font` flags a smaller one).
+- **Charts measure themselves** — pass `height`/`aspectRatio`/`fill` only; never `useElementSize`
+  in a chart file (Mantine is banned there), never raw `@visx/responsive` outside `charts/**`.
 
 ## Scroll regions
 
-**A scroll region inside app chrome is a Mantine `ScrollArea`, not a raw `overflow: auto` box** — it
-draws its own bar inside a `position: relative; overflow: hidden` root, so the bar floats instead of
-reserving gutter width and reflowing the column. `AppSidebar`'s nav is the reference (`type="hover"`,
-`scrollbars="y"`, the flex fill on the ScrollArea root). `styles.css` re-hides the native bar on the
-viewport, so **one overlay bar** is the framework-wide outcome — do not re-theme it.
-
-Raw `overflow: auto` stays correct where a library owns the scroll node (`BasaltStickToBottom`,
-`BasaltVirtualList`) and for a table body, which is `Table.ScrollContainer type="native"` — a
-`ScrollArea` viewport is the positioning context a sticky `<thead>` resolves against, so the default
-type pins the header to the page viewport instead of the table's box.
+**A scroll region inside app chrome is a Mantine `ScrollArea`, not a raw `overflow: auto` box** —
+it draws its own bar inside its root, so the bar floats instead of reflowing the column
+(`AppSidebar`'s nav is the reference: `type="hover"`, `scrollbars="y"`). Raw `overflow: auto` stays
+correct only where a library owns the node (`BasaltStickToBottom`, `BasaltVirtualList`) and for a
+table body (`Table.ScrollContainer type="native"` — a `ScrollArea` viewport would break a sticky
+`<thead>`'s positioning context).
 
 ## Interaction feedback and motion
 
-Every action button must confirm itself — silent success reads as broken. Three layers, together:
-the `loading` prop while in flight; a brief flip on the trigger itself (label `Save → Saved`,
-`color="green"`, a check revealed through Mantine's `<Transition>`), held about a second; and a toast
-ONLY for an outcome the user might miss (an off-screen write, an error, background work). The user's
-eye is on the thing they clicked. Destructive actions confirm through `modals.openConfirmModal`
-first; form errors are inline, and a toast covers only submit-level failure.
-
-- **Timing is a token, never a literal.** `MOTION_DURATION` / `MOTION_SPRING` /
-  `MOTION_EASE_STANDARD` from `basalt-ui`; the duration cap is the same interaction-feedback ceiling
-  above (`raw-motion-value` enforces it). Never animate a layout-shifting property — move
-  `transform`, `opacity`, `color`, `background`.
-- **Import from `motion/react`, never `framer-motion`** (`no-restricted-imports`, repo and shipped).
-  `motion` is an exact-pinned optional PEER, not a bundled dependency. Reach for Mantine's own
-  `<Transition>` for a simple mount fade; reach for `motion` when the interaction needs a crossfade
-  between two elements, spring physics or a gesture.
-- **Always branch on `useReducedMotion`** (`@mantine/hooks`) with a real unanimated code path — no
-  `motion.*` wrapper at all, not just `duration: 0`. `ThemeToggle` is the pattern.
-- **Restraint applies to motion too.** A state change earns a transition; idle chrome does not.
-  Never a looping or pulsing idle animation.
+Every action button confirms itself: the `loading` prop in flight, a brief label flip
+(`Save → Saved`) via Mantine's `<Transition>`, and a toast ONLY for an outcome the user might miss.
+Destructive actions confirm through `modals.openConfirmModal` first.
+
+- **Timing is a token, never a literal** — `MOTION_DURATION`/`MOTION_SPRING`/`MOTION_EASE_STANDARD`
+  (`raw-motion-value` enforces it). Animate `transform`/`opacity`/`color`, never a layout property.
+- **Import from `motion/react`, never `framer-motion`** — exact-pinned optional PEER. Mantine's
+  `<Transition>` for a mount fade; `motion` for a crossfade, spring or gesture.
+- **Always branch on `useReducedMotion`** with a real unanimated path, not just `duration: 0`
+  (`ThemeToggle` is the pattern). Restraint applies to motion too — no looping idle animation.

package/agent/rules/basalt-state.md

@@ -7,7 +7,7 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
 <!-- backed by: guard kinds — localstorage-theme · oxlint rules — basalt/search-literal-link, basalt/use-search-from-literal -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
@@ -49,45 +49,35 @@ export const analytics = createSearchStore({
 ```
 
 - **The URL is the truth; the localStorage mirror is a fallback UNDER it.** Every field resolves
-  URL ⊳ localStorage ⊳ fallback, identically for every field kind (law C4). A deep link therefore
-  wins over the mirror — that is the whole difference from the enum-only pair it replaced, whose
-  reader WAS the localStorage state, so a shared link opened on the wrong window.
-- **Lanes are declared once, at definition**: `{ url, persist, history }`. `url: false` is the
-  local-only lane (a per-card select, a compact toggle); `persist: false` is the URL-only lane
-  (pagination, a tab that should not follow you to another feature). `createLocalStore`
-  (`basalt-ui/state`) is the same field vocabulary with no router at all.
-- **Option LABELS come from `.labels()`, once, at definition** — never a per-control prop and never a
-  lookup table in the page.
-- **`validateSearch: store.validateSearch`** on the route, in the function form. It returns every
-  URL-lane param unconditionally, which is what makes the store's "does this route own the field"
-  check exact. A route with a genuinely wider search shape hand-writes `validateSearch` and COMPOSES
-  the store into it (`{ ...store.validateSearch(raw), ...rest }`) — there is no schema-backed store
-  variant, and none is coming.
-- **A write from outside the owning route persists only**, and `validateSearch` picks it up on the
-  next visit. Two different stores using one param name on overlapping routes read as one owner;
-  presence in the search is all a store can see without the router naming the declarer.
-- **`field.range` keeps its three URL params** (preset + from/to, renamable) so existing loaders and
-  deep links keep their shape; `handle.toWindow(value)` is the projection into query params — never a
-  hand-written `presetToParams`.
+  URL ⊳ localStorage ⊳ fallback, identically for every field kind (law C4) — a deep link wins over
+  the mirror.
+- **Lanes are declared once, at definition**: `{ url, persist, history }`. `url: false` is
+  local-only (a per-card select); `persist: false` is URL-only (pagination, a tab that shouldn't
+  follow you elsewhere). `createLocalStore` is the same field vocabulary with no router.
+- **Option LABELS come from `.labels()`, once, at definition** — never a per-control prop.
+- **`validateSearch: store.validateSearch`** on the route, function form — it returns every
+  URL-lane param unconditionally. A route with a wider search shape COMPOSES the store instead
+  (`{ ...store.validateSearch(raw), ...rest }`) — there is no schema-backed store variant.
+- **A write from outside the owning route persists only**; `validateSearch` picks it up next visit.
+- **`field.range` keeps its three URL params** (preset + from/to); `handle.toWindow(value)` is the
+  projection into query params — never a hand-written `presetToParams`.
 
 ## Reading and writing
 
 - **A page reads `store.useValues()`, or takes the value as a PROP.** Never
-  `useSearch({ from: '<literal>' })` — a sibling or child route fails that `from`, and it is
-  `basalt/use-search-from-literal`. Basalt's own controls read through the `FieldHandle`, which uses
-  the non-strict search internally, so a control renders on any matched route with no `from` at all.
-- **A `FieldHandle` is the whole read/write surface** a control needs: `use()` returns
-  `[value, setValue]` and the setter owns the navigate AND the persist. So a control never receives
-  `value`/`onChange` (law C2) and a page never writes a navigate for a store field. Where you DO hand-write
-  one — a route with its own search shape — use the reducer form, `navigate({ search: (prev) => ({ ...prev, … }) })`,
-  so unrelated params survive.
-- **`useActiveCount()` / `useReset()`** are what a `Filters (n)` pill and its `Reset all` derive
-  from. Never hand-count either.
-- **A reset UNSETS.** `useReset()` and `field.clear()` DELETE the persisted key; they never write
-  `fallback`, which would pin a thunk fallback (`() => todayIso()`) as a value nobody chose. A
-  hand-rolled reset calls `field.clear()`, never `setValue(field.fallback)`.
-- **`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 — write it through that field's setter.
+  `useSearch({ from: '<literal>' })` (`basalt/use-search-from-literal`) — a sibling/child route
+  fails that `from`. Basalt controls read through `FieldHandle`, which uses the non-strict search
+  internally.
+- **A `FieldHandle` is the whole read/write surface**: `use()` returns `[value, setValue]` and the
+  setter owns the navigate AND the persist — a control never receives `value`/`onChange` (law C2).
+  Hand-writing a navigate (a route with its own search shape) uses the reducer form,
+  `navigate({ search: (prev) => ({ ...prev, … }) })`, so unrelated params survive.
+- **`useActiveCount()`/`useReset()`** back a `Filters (n)` pill and its `Reset all` — never
+  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.
 
 ## Nav links carry the store BY REFERENCE
 
@@ -96,11 +86,9 @@ link: linkOptions({ to: '/dashboard', search: analytics.linkSearch })
 ```
 
 **Pass the function, never call it, never inline an object.** It is a click-time thunk, so arriving
-from anywhere restores the last selection; a module-scope literal (`search: { range: '30d' }`) pins
-the fallback on every click and is why one consumer's reader had zero call sites while every
-individual piece looked correct. `search: true` is a type error against a store-backed route.
-`basalt/search-literal-link` catches the literal, and in dev `validateSearch` warns once when the URL
-pins the fallback, something else is persisted, and no reader has ever been called.
+from anywhere restores the last selection; a module-scope literal (`search: { range: '30d' }`)
+pins the fallback on every click — `basalt/search-literal-link` catches it. `search: true` is a
+type error against a store-backed route.
 
 ## The typed nav definition
 
@@ -113,27 +101,21 @@ spread it. `navTarget(NAV, id)` is one destination's link options, typed per id,
 the nav into Spotlight in one `.map()`).
 
 - **Route options live under `link:`, wrapped in TanStack's own `linkOptions`** — never spread flat
-  onto the item. A flat shape validates `to` by assignability, which does no excess-property
-  checking, so a typo'd metadata key compiles silently. `id`/`label`/`short`/`icon`/`mobile`/
-  `disabled`/`exact` ride outside `link`.
+  onto the item (a flat shape validates `to` by assignability, no excess-property checking, so a
+  typo'd metadata key compiles silently). `id`/`label`/`short`/`icon`/`mobile`/`disabled`/`exact`
+  ride outside `link`.
 - **Nesting is `children`**; `mobile` places the destination on the bar (basalt-mantine.md).
 - **Without the `Register` module augmentation, `defineNav` validates NOTHING and reports zero
-  errors** — `RegisteredRouter` falls back to `AnyRouter`, every `to` widens to `string`, and the API
-  looks like it is working while catching nothing. Verify it once by changing a `to` to garbage and
-  confirming the compile error lists the real route paths. The router's errors here are large; read
-  the union for the intended path and fix the string. **Never reach for `as never`** to quiet one —
-  the checking is the entire point.
-- Whether a MISSING `search` is caught depends on the schema's OUTPUT type: with every key required
-  (what a store or a defaulted Zod object produces) TanStack raises and the compiler catches it. With
-  every key optional, a forgotten `search` compiles — diff the target table by hand there.
-- `staticData` (`title` / `icon` / `navSection`) drives `useRouterBreadcrumbs` and needs the
-  generated route tree; everything else in the bridge works against a hand-written router.
+  errors** — `RegisteredRouter` falls back to `AnyRouter`, every `to` widens to `string`. Verify
+  once by changing a `to` to garbage and confirming the compile error. **Never reach for
+  `as never`** to quiet one — the checking is the entire point.
+- `staticData` (`title`/`icon`/`navSection`) drives `useRouterBreadcrumbs` and needs the generated
+  route tree.
 
 ## `createPersistedState` — the localStorage primitive
 
-Call it once at module scope; use the returned hook anywhere, with no provider. SSR-safe, cross-tab
-through the `storage` event, versioned — bump `version` when the shape changes and stale values fall
-back to `initial`. Keys are namespaced `basalt:<key>` automatically, and `readPersistedValue(key, v)`
-is the non-React read (how you mirror the shell's own collapse state). Pass a Standard Schema to
-validate what comes back. Every basalt module that persists — the shell's collapse, a `Section`
-fold, a sidebar block, a form draft, the notification history — persists through this one primitive.
+Call it once at module scope; use the returned hook anywhere, no provider. SSR-safe, cross-tab via
+the `storage` event, versioned (bump `version` on a shape change, stale values fall back to
+`initial`). Keys are namespaced `basalt:<key>` automatically; `readPersistedValue(key, v)` is the
+non-React read. Every basalt module that persists — shell collapse, `Section` fold, a sidebar
+block, a form draft, notification history — goes through this one primitive.

package/agent/rules/basalt-tokens.md

@@ -8,7 +8,7 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
+<!-- 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 -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
@@ -32,10 +32,9 @@ The accent is **split by ROLE**, and this is the one thing an author gets wrong:
   control always reads white on either page. **Never fill with `VX.accent`.**
 
 **The palette is DERIVED, not authored** (`tokens/derive.ts` from one seed + five bounded knobs), and
-a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })`.
-That is why no hex, no shade index and no pixel constant belongs in a rule, a doc or a component:
-every one of them is an output of a config the consumer may move. Read the values off `VX.*` and the
-theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
+a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })` —
+no hex, shade index or pixel constant belongs in a rule, doc or component. Read values off `VX.*`
+and the theme; read raw numbers, if you need them, off `tokens/palette.ts`.
 
 ## Color — never a raw literal
 
@@ -44,28 +43,26 @@ theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
   in non-component files) or through the Mantine theme (`color` / `c` / `bg`, `theme.colors`).
 - **Opacity is `alpha(token, a)`** (`color-mix`), never `rgba()` — so the hue keeps resolving per
   scheme.
-- **No off-identity Mantine accents.** `teal`/`violet`/`grape`/`indigo`/`pink` still render
-  on-palette (the theme reskins every family), and are rejected anyway because they signal
-  off-identity intent. Allowed: **`blue`** (the one earned hue), **`gray`**, and the status names
-  `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
-- **Never pin a shade index** — `c="yellow.7"`, `bg="blue.4"`, `var(--mantine-color-red-6)` each name
-  one fixed swatch that is identical in both schemes, so the shade that is legible on dark is the one
-  that fails on light. Use `VX.status.*` for a verdict, or the bare hue name and let the theme pick.
+- **No off-identity Mantine accents** — allowed: **`blue`** (the earned hue), **`gray`**, and the
+  status names `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
+- **Never pin a shade index** (`c="yellow.7"`, `var(--mantine-color-red-6)`) — one fixed swatch is
+  identical in both schemes, so what's legible on dark fails on light. Use `VX.status.*` or the
+  bare hue name.
 - **"Ink earns its color."** Default to neutral. A hue is justified by trend, signal/status, or
   genuine multi-series separation. The accent lands on the single primary CTA per view, focus rings,
   links and small status pops — never on borders, large fills, routine icons or secondary buttons.
 - **Categorical/series color is consumer data**, declared once through `defineSeries` →
-  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop and
-  never an inline pair. `groupTokens(GROUP, MAP)` assumes the same map reaches
-  `BasaltProvider`'s `paletteOptions.groups` under the key `` `${GROUP}-` `` — **with the trailing
-  dash**, which is a CSS-var prefix and not a group name. Derive both from one `GROUP` constant;
-  a mismatch emits refs to variables the stylesheet never declares, with no tsc error and no
-  runtime throw — just unstyled charts.
+  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop.
+  `groupTokens(GROUP, MAP)` assumes the map reaches `BasaltProvider`'s `paletteOptions.groups`
+  under the key `` `${GROUP}-` `` — **with the trailing dash**. Derive both from one `GROUP`
+  constant; a mismatch emits refs to variables the stylesheet never declares, silently.
 
 ## Surfaces — one collapsed token set
 
 `VX.surface` is exactly: `bg` · `panel` · `panelHover` · `elevated` · `subtle` · `overlay` ·
-`field` · `border` · `hairline`. Plus `VX.divider` for layout separators, which is NOT a surface.
+`field` · `border` · `hairline`. `VX.divider` is NOT a surface — the one seam/line token (every
+`AppShell` region edge + between-rows rule); `hairline` is the card ring, `border` the
+control/overlay line — neither is ever a seam.
 
 The theme **collapses Mantine's raw ramp steps onto those tokens** (`cssVariablesResolver` + theme
 `styles`), so every Mantine component — AppShell, Table, Input, Divider, Tabs, Popover, Accordion,
@@ -79,13 +76,12 @@ and never reach for a raw ramp-step var (`var(--mantine-color-gray-N)`).
   the integer that happens to equal `md` today; `radius="sm"`, never a numeric radius.
 - **Card radius has one source**, `VX.radiusCard` / `--vx-radius-card`: the Mantine chrome and the
   Mantine-free `ChartCard` resolve to the same token. Cards must never diverge.
-- **Sub-scale micro-spacing is legitimate and allowed raw** — a tight cluster below the scale's
-  first step has no token, so use the raw number rather than inventing a micro-token or peppering
-  `theme-allow`. The same permission holds in CSS modules: a declaration whose every literal is
-  micro does not fire. One non-micro value makes the whole declaration a finding, and an inline
-  style OBJECT in TSX still fires, because there the Mantine prop existed.
-- **Dense by default** — the framework targets compact surfaces; reach for the tighter step.
-- **Icons size through the icon's own `size` prop**, which is not spacing.
+- **Sub-scale micro-spacing is legitimate and allowed raw** — below the scale's first step, use the
+  raw number rather than inventing a micro-token. A CSS-module declaration whose every literal is
+  micro does not fire; one non-micro value makes it a finding, and an inline style OBJECT in TSX
+  still fires (there the Mantine prop existed).
+- **Dense by default** — reach for the tighter step. Icons size through their own `size` prop,
+  which is not spacing.
 
 ## Type
 
@@ -113,48 +109,31 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
 <Widget style={{ borderRadius: 3 }} />
 ```
 
-- **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block gutter `*`, or
-  nothing but whitespace. Prose that merely MENTIONS the token waives nothing; a file documenting
-  its own waivers used to disarm itself.
-- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the file.
-  A bare `theme-allow-file` waives nothing at all.
-- **A typo waives nothing.** A word in the id slot naming no rule is recorded as unknown; the
-  annotation still covers the ids it got right. Because the id slot is read strictly, a bare reason
-  needs a separator — `theme-allow: <why>` or `theme-allow <id> — <why>`, never `theme-allow <why>`.
-- **Three placements work, and both engines agree on all three**: the reported line, a comment-ONLY
-  line directly above it (reaching the first CODE line below, through the rest of its comment
-  block), and in CSS a trailing annotation reaching back over the declaration it terminates. A blank
-  line ends the reach — that is how you say "this comment is not about the next statement".
-- **JSON and `.webmanifest` take a member key**, since they cannot hold a comment. For a manifest
-  the first remedy is `basaltAppPlugin`, not a waiver: a hand-copied hex drifts from the palette.
-- **The three import-boundary rules honour no escape at all** (`visx-boundary`, `visx-tooltip`,
-  `token-layer-boundary`) — an architecture boundary a stray comment can switch off is the bypass
-  they exist to prevent. The agent-chat guards honour `basalt-agent-allow`, a separate token that
-  never waives a `theme-allow` finding, or the reverse.
-
-Unsupported shapes are asserted as unsupported in both engines' test grids (`src/guard/
-check-source.test.ts`, `configs/oxlint-plugin.test.ts`), so "unsupported" and "silently broken"
-cannot read the same. **Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
-neutralized, one at a time, and **exits 1 on a waiver that suppresses nothing** — a dead waiver
-silently covers the next real finding on that line. It judges plugin-rule waivers too, by re-running
-oxlint; where oxlint is unreachable the verdict is "cannot judge", never "dead". Its scope line is
-part of the report: `0 dead` is not `0 dead anywhere`.
+- **An annotation must START its comment** (`//`, `/*`, `<!--`, a `*` gutter, or bare whitespace) —
+  a mention mid-prose waives nothing.
+- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the
+  file; a bare one waives nothing.
+- **A typo waives nothing** — an unrecognized id is recorded unknown, the rest of the annotation
+  still covers the ids it got right.
+- **Three placements agree in both engines**: the reported line, a comment-only line directly
+  above it, and (CSS) a trailing annotation reaching back over the declaration it terminates. A
+  blank line ends the reach.
+- **JSON/`.webmanifest` take a member key** — first remedy is `basaltAppPlugin`, not a waiver.
+- **The three import-boundary rules honour no escape at all**; the agent-chat guards honour
+  `basalt-agent-allow`, a separate token that never waives a `theme-allow` finding, or the reverse.
+
+**Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
+neutralized and **exits 1 on a waiver that suppresses nothing**; it judges plugin-rule waivers too
+by re-running oxlint. Scope is part of the report — `0 dead` is not `0 dead anywhere`.
 
 ## Wiring the guard
 
 `check-theme` reads `package.json`'s `"basalt"` key (`roots`, `exempt`, `include`, `profile`,
-`severity`, `exemptRules`, …). **`roots` is not optional in practice** — omitted, it falls back to
-`src` relative to cwd, which is zero files for anything under `apps/*/src`; `init` writes a real one
-and `doctor`'s `guard-scan` fails when it resolves to nothing. The scan also reaches each root's
-PARENT for its `index.html` and `public/` tree, because that is where a `theme-color` meta and a
-webmanifest's `background_color` live. Wire it as `oxlint . && basalt-ui check-theme` — what `init`
-seeds as `lint:basalt`.
-
-**When it fires, fix the source** — the right token first. `theme-allow` is for a documented
-exception; a palette-definition file belongs in `exempt`, not behind a comment.
-
-**The guard sees palette, not vocabulary.** A fork written by a token-fluent author uses exactly the
-right tokens, so no palette guard can see it — `basalt/shadow-basalt-export` catches an exact name
-collision and nothing else, and renaming the fork is what a fork's author does anyway. It is a
-tripwire, not coverage. The habit is the control: **check whether basalt already ships the thing
-before building it.**
+`severity`, `exemptRules`). **`roots` is not optional in practice** — omitted, it falls back to
+`src` relative to cwd (zero files under `apps/*/src`); `init` writes a real one. Wire it as
+`oxlint . && basalt-ui check-theme` — what `init` seeds as `lint:basalt`.
+
+**When it fires, fix the source** — the right token first; a palette-definition file belongs in
+`exempt`, not behind a comment. **The guard sees palette, not vocabulary** — a token-fluent fork
+uses exactly the right tokens, so `basalt/shadow-basalt-export` (an exact name collision) is a
+tripwire, not coverage. Check whether basalt already ships the thing before building it.

package/agent/skills/basalt-app/SKILL.md

@@ -36,6 +36,8 @@ own `.oxlintrc.json` costs.
 ```tsx
 // main.tsx — CSS order is load-bearing: every @mantine/*/styles.layer.css, THEN basalt's
 import '@mantine/core/styles.layer.css'
+import '@mantine/notifications/styles.layer.css' // one per MOUNTED battery: notifications, spotlight…
+import '@mantine/spotlight/styles.layer.css'
 import 'basalt-ui/styles.css'
 import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
 import { BasaltOverlays } from 'basalt-ui/commands'

package/agent/templates/CLAUDE-block.md.tpl

@@ -2,32 +2,29 @@
 
 ## basalt-ui (managed — do not hand-edit)
 
-Placed by `bunx basalt-ui init` and refreshed by `basalt-ui sync` after every upgrade
-(`sync --check` gates drift in CI). Framework-owned: edit `DESIGN.md` or your own files instead —
-changes here are overwritten on the next sync.
+Placed by `bunx basalt-ui init`, refreshed by `basalt-ui sync` (`sync --check` gates drift in CI).
+Framework-owned: edit `DESIGN.md` or your own files — this block is overwritten on the next sync.
 
-**Stack:** React 19 + Mantine v9, themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`), Bun
-runtime, oxlint + oxfmt (no ESLint/Biome/Prettier), no Tailwind. Color comes from the three-tier
-`--vx-*` token system — read `VX.*` or a series token, never a raw hex/`rgb()`/`hsl()`. Charts are
-visx via `basalt-ui/charts`. `basalt-ui check-theme` plus the `basalt/*` oxlint rules are the teeth.
+**Stack:** React 19 + Mantine v9 themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`), Bun,
+oxlint + oxfmt (no ESLint/Biome/Prettier), no Tailwind. Color is the three-tier `--vx-*` token system —
+`VX.*` or a series token, never a raw hex. Charts are visx via `basalt-ui/charts`; `check-theme` + the
+`basalt/*` oxlint rules are the teeth.
 
 **Precedence — the only statement of it.** Highest wins; a lower layer fills gaps and never
 overrides a higher one:
 
 > consumer `DESIGN.md` (app deltas) > the six shipped `basalt-*` rules > the `basalt-*` skills
 
-**All six rules are law** — `basalt-tokens`, `basalt-mantine`, `basalt-charts`, `basalt-state`,
-`basalt-controls`, `basalt-batteries` in `.claude/rules/`, each carrying a generated
-`<!-- basalt:coverage -->` header naming what enforces it and what is only advisory. The skills
-(`/basalt-app`, `/basalt-design`, `/basalt-charts`) are the METHOD that obeys them, never law.
+**All six rules are law** — `basalt-{tokens,mantine,charts,state,controls,batteries}` in
+`.claude/rules/`, each with a generated `<!-- basalt:coverage -->` header naming what enforces it and
+what is only advisory. The skills (`/basalt-app`, `/basalt-design`, `/basalt-charts`) are METHOD, never law.
 
 **Run the LOCAL bin, not `bunx`** — `./node_modules/.bin/basalt-ui`, or a `package.json` script.
 `bunx` does not re-resolve a cached package, so it can answer for a version you upgraded away from;
 `init` is the one legitimate `bunx` invocation, because nothing is installed yet.
 
-**Before guessing an import, read the installed package's machine docs** — `llms.txt` (per-subpath
-import map) and `AGENTS.md`, at the install directory. In a workspace that is under the package that
-depends on basalt, not the repo root; `basalt-ui doctor`'s `basalt-resolves` line prints where.
+**Before guessing an import, read the installed package's `llms.txt` and `AGENTS.md`** — at the
+install directory (in a workspace, under the depending package; `basalt-ui doctor` prints where).
 
 @./DESIGN.md
 
@@ -37,4 +34,7 @@ noise/grain and dramatic motion. Here: the shipped three-font system, depth from
 with a 1px ring, neutral-by-default with the single accent spent only when earned — trend, signal,
 or genuine categorical separation. Restraint **is** the identity.
 
+**Chart-doctrine override.** A global `visx-charts` rule auto-loading on `**/charts/**` is generic
+non-basalt discipline; here `basalt-charts` supersedes it — compose `CartesianChart`.
+
 <!-- basalt:end -->