basalt-ui 1.28.0 → 1.29.0

package/agent/rules/basalt-controls.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 — raw-selection-control · oxlint rules — basalt/bound-control-outside-home, basalt/control-outside-home, basalt/control-size-literal, basalt/hand-rolled-filter, basalt/responsive-twin -->
 <!-- not guarded: C1 as a cross-file law (a control placed in one file, its home declared in another) -->
 <!-- not guarded: hand-rolled section headings (argo writes `<Text fw={600} size="sm">` + children, which no AST heuristic matches without false positives) -->
@@ -55,21 +55,16 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `SettingsRow`                                                                     | `control`                                          | Mantine `md` | ONE form field, bound to a setting         |
 | `FormRow` / `FormGroup` (`basalt-ui/forms`)                                       | children                                           | Mantine `md` | ONE form field or a labelled cluster       |
 
-- **Inside `BasaltShell`** both `PageBar` rows are portals — row 1 into the header, row 2 into the
-  shell's band above the scrollport — so where you write `<PageBar>` never moves it and nothing in
-  the scrollport has chrome to clear: a sticky table head takes no offset. Without a shell both rows
-  render in flow, sticky, with `title` + `icon` leading. The header height is a token, never state.
-- **The form row is a real home, and it keeps Mantine's own `md` tier.** A raw `Select` bound to a
-  setting is the right answer in `SettingsRow.control`, and the `size` prop there is load-bearing
-  rather than redundant. `SettingsRow` is not a tiered slot, and no filter or size rule applies to it.
-  `FormRow`/`FormGroup` are the same home written for a `<form>` rather than a settings page — a
-  control nested in either never reports either.
-- **A control's home is a decision about reach**: it belongs next to what it acts on. If it affects
-  more than one widget it is promoted to the page bar; if it formats one widget it stays in that
-  widget's header.
-- **An overlay rendered by the PARENT is exempt by FILENAME**: `control-outside-home` and
-  `raw-selection-control` skip a file basenamed `*-{modal,drawer,popover,panel,form}.tsx`, since no
-  scan of it sees the `<Modal>`. Outside that: `theme-allow-file control-outside-home — overlay`.
+- **Inside `BasaltShell`** both `PageBar` rows are portals (header / the band above the scrollport)
+  — where you write `<PageBar>` never moves it. Without a shell both rows render in flow, sticky.
+  The header height is a token, never state.
+- **The form row keeps Mantine's own `md` tier** — a raw `Select` in `SettingsRow.control` is the
+  right answer, `size` there is load-bearing. Neither `SettingsRow` nor `FormRow`/`FormGroup` is a
+  tiered slot; no filter or size rule applies to them.
+- **A control's home is a decision about reach**: affects more than one widget → promote to the
+  page bar; formats one widget → stays in that widget's header.
+- **An overlay rendered by the PARENT is exempt by FILENAME** — `*-{modal,drawer,popover,panel,form}.tsx`.
+  Outside that: `theme-allow-file control-outside-home — overlay`.
 
 ## The `ctl` tier — the home sizes the control
 
@@ -81,13 +76,11 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `touchControlHeight`  | hit area below `sm`                                        | every home                                          |
 | `controlHeight`       | `size="md"`                                                | forms — unchanged                                   |
 
-Each home wraps its **slot** — never its body — in a hoisted theme provider that defaults every
-Mantine control inside it to `size="ctl"`, plus a `data-basalt-tier` attribute. So a raw `Button`
-dropped into `PageBar.actions` is already the right height with no prop, and a `size="xs"` typed
-there is law C5 (`basalt/control-size-literal`). Mantine's own `sm`/`xs` are NOT re-pointed: a
-`size="sm"` in a modal or a form keeps Mantine's height. One exception, by boundary:
-`ChartCard.actions` lives inside the Mantine-free chart layer, so it cannot mount the slot theme —
-it carries only the tier attribute, and the basalt controls placed there size themselves.
+Each home wraps its **slot** — never its body — in a hoisted theme provider defaulting every
+Mantine control inside it to `size="ctl"`. A raw `Button` in `PageBar.actions` is already the right
+height with no prop; a `size="xs"` typed there is law C5 (`basalt/control-size-literal`). Mantine's
+own `sm`/`xs` are NOT re-pointed elsewhere. Exception: `ChartCard.actions` is Mantine-free, so it
+carries only the tier attribute and its controls size themselves.
 
 ## Binding a control to a store
 
@@ -106,24 +99,21 @@ import { DateRangePicker } from 'basalt-ui/controls-dates'
 ```
 
 The store, its fields and their lanes are basalt-state.md. What this file adds: **the control takes
-`field` and nothing else about state.** No `value`, no `onChange`, no `size` — those props do not
-exist, so a wrong call site is a tsc error rather than a review comment. `ActionGroup`,
-`OverflowMenu` and `SyncButton` sit on the same subpath and take typed action DATA, never children.
+`field` and nothing else about state** — no `value`, no `onChange`, no `size`, so a wrong call site
+is a tsc error. `ActionGroup`/`OverflowMenu`/`SyncButton` take typed action DATA, never children.
 
-**The date picker is injected, never imported.** `basalt-ui/controls` resolves and renders with no
-`@mantine/dates` installed, which is what lets a consumer without a date picker use every other
-control; `DateRangePicker` comes from `basalt-ui/controls-dates` through `RangeFilter.customPicker`.
-Never import `@mantine/dates` from a shared module, and never reach for `DateInput`/`DatePickerInput`
-inside a home slot.
+**The date picker is injected, never imported.** `basalt-ui/controls` resolves with no
+`@mantine/dates` installed; `DateRangePicker` comes from `basalt-ui/controls-dates` through
+`RangeFilter.customPicker`. Never import `@mantine/dates` from a shared module or reach for
+`DateInput`/`DatePickerInput` inside a home slot.
 
 ## `FilterSet` owns the responsive story
 
 Do not build one at the call site. Above `sm`, `FilterSet` measures its own children and folds the
-tail into a `+N` pill rather than wrapping or scrolling. Below `sm`, the first `inline` children stay
-pills and one `Filters (n)` pill opens a bottom sheet where every child renders full-width, applies
-immediately, and answers one `Reset all`. **`n` and `Reset all` are DERIVED** from whether each field
-differs from its fallback — so adding a filter is one JSX line, with no count to maintain and no
-reset handler to extend.
+tail into a `+N` pill. Below `sm`, the first `inline` children stay pills and one `Filters (n)`
+pill opens a sheet where every child renders full-width and answers one `Reset all`. **`n` and
+`Reset all` are DERIVED** from whether each field differs from its fallback — adding a filter is
+one JSX line, no count or reset handler to maintain.
 
 | Below `sm`       | What basalt does                                                                                                                   |
 | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -132,16 +122,14 @@ reset handler to extend.
 | a section header | title · count · one inline action, the rest in a kebab; tabs past three become a `Select`                                          |
 | a widget header  | value + delta wrap under the title; the sparkline drops to bleed; one `⋯` action                                                   |
 
-Every swap is CSS inside the control (one mount), never a JS media query — a media-query hook renders
-differently on the server than on the first client paint. Two mounts under
+Every swap is CSS inside the control (one mount), never a JS media query. Two mounts under
 `visibleFrom`/`hiddenFrom` is `basalt/responsive-twin`.
 
 ## The aside
 
 `PageAside` is a shell REGION, not a fourth home — C1 still names three. Its body IS a home: it
-scopes its children to the `panel` surface, so the same `SelectFilter` that is a pill in the page
-bar is a ROW in the aside. Never two components and never a prop to pick between them — the surface
-is read from where the control is mounted.
+scopes children to the `panel` surface, so the same `SelectFilter` that is a pill in the page bar
+is a ROW in the aside — never two components, the surface is read from where it's mounted.
 
 | In the aside     | Write                                                                             |
 | ---------------- | --------------------------------------------------------------------------------- |
@@ -151,35 +139,16 @@ is read from where the control is mounted.
 | a group of rows  | `Section` — flush inside the aside, which draws the rhythm itself                 |
 | a choice         | `PanelChoice` — a track only while ≤3 options AND every label fits, else `Select` |
 
-- ONE `PageAside` per page, written AFTER the main content: it portals into the region from `sm` up,
-  so its place in the tree is reading order, not layout.
-- Below `sm` it projects into `PageBar` row 2 as one `Panel` pill opening a sheet; with no row 2 —
-  and in a shell-less app — it renders in flow where the page wrote it. One node either way (C9).
-- A bound control written outside all of this (a `Section` body, a bare page stack) is
-  `basalt/bound-control-outside-home` — it renders as a stray pill. A slot prop, a `FilterSet`, a
-  `PageAside` or a `PanelRow` is a home; nothing else is.
+- ONE `PageAside` per page, written AFTER the main content — it portals into the region from `sm`
+  up, its tree position is reading order, not layout.
+- Below `sm` it projects into `PageBar` row 2 as one `Panel` pill; with no row 2 — or shell-less —
+  it renders in flow. One node either way (C9).
+- A bound control outside all of this is `basalt/bound-control-outside-home` — a slot prop, a
+  `FilterSet`, a `PageAside` or a `PanelRow` is a home; nothing else is.
 
 ## Sidebar blocks
 
 A non-destination list, a progress meter or a bespoke node in the sidebar is a `SidebarBlock` —
-declared data, three kinds (`list` / `progress` / `custom`), placed `'nav'` or `'bottom'`. Because it
-is data, basalt owns what a `ReactNode` slot could not express: a rail dot or ring when the desktop
-sidebar is collapsed, a persisted fold, and one More-sheet row per block on mobile opening a sheet of
-its items. A `custom` block is desktop-only, by design.
-
-## Anti-patterns
-
-| Instead of                                                   | Write                                                 |
-| ------------------------------------------------------------ | ----------------------------------------------------- |
-| `useState` + a `SegmentedControl` in the page body           | a store field + `ViewTabs` in the home's `tabs` slot  |
-| a raw `Select`/`MultiSelect`/`Chip.Group` as a filter        | `SelectFilter` / `MultiSelectFilter`                  |
-| a numeric threshold widened into a string enum               | `field.number` + `NumberFilter`                       |
-| `<X visibleFrom="sm"/>` beside `<X hiddenFrom="sm"/>`        | one control — the swap is already inside it           |
-| `size="xs"` on a button in a home slot                       | nothing; the home sets the tier                       |
-| a hand-written `presetToParams`                              | `field.toWindow(value)`                               |
-| a hand-counted `Filters (3)` badge                           | nothing; `FilterSet` derives it                       |
-| `overflowX: 'auto'` on a filter row                          | nothing; the fold is basalt's                         |
-| a local `Section` / `PageHeader` / `RefreshButton`           | `Section` / `PageBar` / `SyncButton`                  |
-| an in-body `<Title order={1}>`                               | the route's breadcrumb title                          |
-| the same on a shell-less surface (auth gate, error boundary) | `theme-allow in-body-page-title — shell-less surface` |
-| a hand-built joined button row                               | `ControlGroup` (or `group: true` on the actions)      |
+declared data, three kinds (`list`/`progress`/`custom`), placed `'nav'`/`'bottom'`. Because it's
+data, basalt owns what a `ReactNode` slot couldn't: a rail dot/ring when collapsed, a persisted
+fold, one More-sheet row per block. A `custom` block is desktop-only, by design.

package/agent/rules/basalt-mantine.md

@@ -7,8 +7,8 @@ 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/deprecated-export, basalt/duplicate-notifications-mount, basalt/hand-rolled-shell, basalt/in-body-page-title, basalt/page-bar-budget, basalt/provider-above-router, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
+<!-- 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 -->
 
@@ -30,15 +30,13 @@ 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`. `ModalsProvider` mounts as
-a **sibling** of `children`, not a wrapper — the imperative `modals.*`/`overlays.*` API works
-untouched (it runs over a window `CustomEvent` bus `ModalsProvider` subscribes to), but `useModals()`
-and `openContextModal` need real React context, which a sibling cannot provide: pass `modals={false}`
-and mount your own `ModalsProvider` instead when you need either. 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).
@@ -64,104 +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. Region edges come from `BasaltShell` itself — Mantine's `[data-with-border]`, coloured by
-`--app-shell-border-color` → `--vx-divider` through the theme — never draw a border on a shell
-region, a page-bar row or an aside panel, never pass `withBorder` to an `AppShell` section, and
-never set `--app-shell-border-color` yourself. `--vx-divider` is the only layout-line token; the
-sidebar's own internals still carry zero horizontal rules.
+  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.