basalt-ui 1.41.0 → 2.0.1

package/agent/rules/basalt-batteries.md

@@ -1,97 +1,42 @@
 ---
 source: basalt-ui
-description: The adapter batteries — query, forms, notifications, commands, data, content, agent — plus app bootstrapping (vite preset, CSS layer order, init/sync). One doctrine each: use the shipped seam, don't re-roll it.
+description: The adapter batteries — query, forms, table, content, agent. Use the shipped seam.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
-  - '**/vite.config.ts'
-  - '**/index.html'
 ---
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — none · oxlint rules — basalt/agent-no-raw-usechat, basalt/agent-resume-guard, basalt/ai-sdk-major, basalt/forms-field-key, basalt/query-fn-unwrap -->
+<!-- backed by: guard kinds — none · oxlint rules — basalt/agent-no-raw-usechat, basalt/ai-sdk-major, basalt/forms-field-key, basalt/query-fn-unwrap -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
-# Basalt Batteries — the adapter surfaces
+# Basalt Batteries
 
-Each battery is a subpath with **one** doctrine: the shipped seam is the seam, re-rolling it is the
-failure this rule prevents. Every peer is OPTIONAL — install before importing. Full API: the
-shipped types, JSDoc and `llms.txt` at the install directory — this file is only what a reader gets
-wrong without being told.
+`.` requires react, Mantine and TanStack Router/Query; install a battery's own peer before importing its subpath.
 
-**Not guarded, honestly**: `forms`, `notifications`, `commands`, `data` and `content` carry zero
-guard kinds or oxlint rules — the `not guarded: —` line above is real, not aspirational. Nothing
-fails a build if you re-roll one of these seams by hand; follow the doctrine below on trust.
+## Query
 
-**Deprecation, as a consumer sees it.** A `basalt/deprecated-export` warn means the export still
-works but leaves in a stated `removeIn` minor (autofix renames the import, keeps your local
-binding). The replacement and removal minor are always in `MIGRATING.md` § Unreleased the moment
-the deprecation ships — that file, not the warning text, is where you confirm what to migrate to.
-Maintainer notes (`MAINTAINING.md` in the repo, not shipped): § Deprecation lifecycle.
+- Wrap every `queryFn` response in `unwrap()`; it throws on the error branch and on `null` data. [basalt/query-fn-unwrap]
+- The client comes from `createBasaltRouter`; extend it via its `query:` option. [type createBasaltRouter]
 
-## Query — `createBasaltQueryClient`/`unwrap` (root barrel, C1: `./query` dropped)
+## Forms
 
-`unwrap()` throws on the error branch AND on a `null` data with no error — both are caller bugs.
-Render with `QueryState`, never a hand-written switch (precedence: error-without-data → empty →
-loading → children). One factory per resource via `queryOptions`, never a raw string key.
+- A field is two calls: `key={fieldKey(form, path)}` and `{...inputProps(form, path)}`, from `basalt-ui/forms`. [basalt/forms-field-key]
+- `useBasaltForm` takes a Standard Schema validator, not a `ZodSchema`. [type useBasaltForm]
 
-## Eden Treaty — three silent `any`s (stated once)
+## Table
 
-Reaches both `unwrap` and `./agent`'s transport: an un-chained route, mismatched tsconfig path
-aliases, and a response schema on a streaming route (Eden #231) all silently degrade inference to
-`any`. Check these three first when Eden types regress.
+- Tables are `BasaltDataTable` with columns from `createColumnHelper` (`basalt-ui/table`, TanStack Table v9: `sortFn`, not v8's `sortingFn`); column `meta` is `{ align, numeral }`; a streamed table's fallback is the same table with `isLoading` and `skeletonRows`. [type createColumnHelper] [type BasaltDataTable]
 
-## `./forms` — `@mantine/form`
+## Content
 
-`useBasaltForm` (`mode: 'uncontrolled'`, `StandardSchemaV1` never `ZodSchema`) +
-`useFormSubmit`/`useFieldArray`/`FormErrorSummary`/`useFormDraft`. A field is two calls, never one
-object (`basalt/forms-field-key` guards + autofixes it) — dropping `key` keeps stale text through
-`form.reset()`.
+- Render model or agent output with `contentTrust="untrusted"`; `streaming` is a rendering mode, not a trust claim. [type Markdown]
 
-## `./notifications` — `@mantine/notifications`
+## Agent
 
-`notify({ intent, message })` — intent, never a raw color, drives the Mantine color AND the aria
-`role`. `defineNotifications`/`emit` is the typed registry; only persisted-history calls
-(`notify`/`notifyPromise`) reach the bell/center. `notifyUndo` owns the undo-window contract.
-
-## `./commands` — the command bus
-
-`defineCommands`/`runCommand`, `defineOverlays`/`overlays.open` — call each factory once, at app
-boot. Project via `toSpotlightActions`/`toShortcutList`/`toHotkeyBindings`, never a hand-authored
-second list. `overlays.confirm`/`confirmDelete` need no registry entry.
-
-## `./data/table` + `./data/virtual` — TanStack Table + Virtual (C1: no bare `./data`)
-
-Read the props before hand-rolling anything (facets, pagination, `meta.align`/`meta.numeral`).
-`manualPagination` imposes a contract on sorting/filtering/count — unresolved, it throws in dev.
-`BasaltVirtualList` above a few hundred rows only.
-
-## `./content` — prose, markdown, MDX
-
-`Prose`/`Markdown`/`mdxComponents` share one typography layer. `streaming` is a rendering mode, not
-a trust claim — any surface rendering agent/model output pins `contentTrust="untrusted"`. Every
-optional peer degrades gracefully except the sanitizer, which is always on.
-
-## `./agent` + `./agent-chat` — streaming chat
-
-`./agent` is headless/Mantine-free; `./agent-chat` is the chrome. Every `AgentPart` switch ends
-`default: return assertNever(part)`. `useAgentStream` runs one turn, `useAgentThreadRuns` runs N by
-thread id. Stream resumption reconnects a MOUNT (page reload mid-stream), it never continues a
-click — `retry()`/`regenerate()` always start a fresh stream from the cached input.
-
-**Why the three lint guards exist** (a consumer's build fails on one of these; all honour
-`basalt-agent-allow`, never `theme-allow`): `basalt/agent-resume-guard` — an unguarded
-`resumeStream()`/`useChat({ resume: true })` re-fires under StrictMode with no dedup, use
-`useAgentThreadRuns` instead. `basalt/agent-no-raw-usechat` — bypassing the basalt hooks loses the
-unmount-abort and supersede guards. `basalt/ai-sdk-major` (+ `doctor`'s `ai-major-parity`) — a v5
-stream parsed by a v7 reader throws; nothing else pins the `ai` major across packages.
-
-## App bootstrapping — `./vite`, CSS order, `init`
-
-`basaltViteConfig` is config-only; spread `basaltAppPlugin` into your own `plugins`. CSS layer
-order is load-bearing: every `@mantine/*/styles.layer.css` first, then `basalt-ui/styles.css` — an
-unlayered Mantine import outranks `@layer basalt` regardless of specificity. `init` on an existing
-app is a lint-debt event, not a no-op — triage the new findings, don't blanket-disable a plugin.
-Run `doctor` after and read it to the last line (`SKIPPED` exits non-zero on its own).
+- Chat uses `basalt-ui/agent` (`useAgentThreadRuns`, `ThreadFeed`, `Composer`); never `useChat` or `Chat` from `@ai-sdk/react`. [basalt/agent-no-raw-usechat]
+- Keep `ai` and `@ai-sdk/*` on one major across packages. [basalt/ai-sdk-major]
+- End every switch over `AgentPart` with `default: return part satisfies never`. [type AgentPart]
+- An intentional `ai` major split is waived with `basalt-agent-allow`, never `theme-allow`. [basalt/ai-sdk-major]

package/agent/rules/basalt-charts.md

@@ -1,111 +1,37 @@
 ---
 source: basalt-ui
-description: visx chart doctrine — compose CartesianChart (or ChartFrame for a non-single-plot shape), derive legends and tooltip rows from `series`, keep every color in `--vx-*`. Enforced by basalt/hand-rolled-plot, basalt/chart-legend-literal, basalt/chart-in-raw-surface and the two @visx boundary rules.
+description: Charts on TanStack Charts — compose CartesianChart or a shipped kind, never the engine host.
 paths:
   - '**/charts/**'
 ---
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — chart-missing-aria-label, raw-color-fn, raw-hex, raw-visx-axis · oxlint rules — basalt/chart-in-raw-surface, basalt/chart-legend-literal, basalt/hand-rolled-plot, basalt/visx-boundary, basalt/visx-tooltip -->
+<!-- backed by: guard kinds — raw-color-fn, raw-hex · oxlint rules — basalt/chart-engine-boundary, basalt/chart-in-raw-surface -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
-# Basalt Charts — the primitive contract
+# Basalt Charts
 
-basalt-ui owns the chart doctrine: charts are assembled from low-level visx primitives, so without a
-shared assembly every chart drifts from every other one. **This file is the contract; the API is not
-here** — read the shipped types and JSDoc, and `llms.txt` at the install directory, for props.
+Every cartesian chart is `CartesianChart` or a kind built on it; props are in the shipped types.
 
-## The one mandatory primitive
+## Composition
 
-**Every single-plot cartesian chart composes `CartesianChart`, and composes nothing else from its job
-list by hand.** It owns the measured margins, both y scales and their domains, the x scale and tick
-thinning, the grid, zones, the axes, the page-shared cursor, the crosshair and its per-series dots,
-the hover/keyboard overlay and the derived tooltip. The caller supplies `series` and a `children`
-render prop that draws **only marks**.
+- Use a shipped kind (`Lines`, `Bars`, `Sparkline`, …) when one fits; otherwise compose `CartesianChart` with `marks`. [type CartesianChart]
+- `ariaLabel` is required on every chart. [type CartesianChartProps]
+- `marks(plot)` returns engine marks and nothing else; margins, scales, axes, grid, cursor, legend and tooltip are the host's. [type ChartMarks]
+- Supply `series` once; legend entries and tooltip rows derive from it. [type ChartSeries]
+- Draw `plot.rows(key)` and `plot.visible`, never the `series` prop, so a legend toggle hides the mark. [type PlotContext]
+- A second axis is `y2` with a series `axis: 'right'`; there is no margin prop. [type CartesianChartProps]
+- Size is `height` (a number or per container class); the host measures the width. [type ResponsiveChartHeight]
+- A pending, failed or empty query is `state={{ pending, error, empty }}`, never `data ?? []`; a streamed chart's `<Suspense>` fallback is the same chart with `state={{ pending: true }}`, which fills the final box. [type ChartState]
+- Zones, thresholds and reference lines are `zones`, `xZones` and `refLines` data. [type ZoneSpec]
+- Extra tooltip rows are `tooltip.rows` data, never markup. [type ChartTooltipConfig]
+- Charts share one cursor by default; `cursorGroup` isolates one, `chartCursor(group?)` reads it. [type chartCursor]
 
-Reaching past it for an axis, a tooltip or a margin means the chart has drifted. `basalt/hand-rolled-plot`
-enforces this per NODE, waived one node at a time with `theme-allow hand-rolled-plot — <why>`.
+## Boundaries
 
-**Five shipped shapes are the declared exceptions**, by shape, not preference: `DualPanel` (two
-panes), `MirroredBars` (two bar panes, one baseline), `BandStrip` (no y dimension), `Donut`
-(radial), `Heatmap` (matrix). They compose `ChartFrame` + `useChartCursor` + `autoMargin` +
-`ChartTooltipFloat` directly. The first three carry `theme-allow-file hand-rolled-plot — <why>`;
-`Donut`/`Heatmap` render no assembly primitive, so nothing fires. A bespoke non-single-plot shape
-declares itself the same way. `CartesianChart`'s own defining module is exempt definitionally.
-
-**A documented limit:** the rule keys on visx primitives, so a DOM- or hand-`<svg>`-drawn chart is
-structurally invisible to it. Compose the primitive because it's the contract, not because lint
-catches you.
-
-## `series` is the single source of truth
-
-Legend entries and tooltip rows are **DERIVED** from `series` (`deriveLegend` / `deriveTooltipRows`,
-or just let `ChartFrame`/`CartesianChart` do it), so a chart cannot show a row or a key it does not
-draw. A hand-written array literal passed to `ChartLegend`'s `items` — or a `.map()` over some OTHER
-array, because deriving from AN array is not deriving from THE series — is
-`basalt/chart-legend-literal`.
-
-**Corollary for mark renderers: draw `ctx.visible`, never the `series` prop.** `visible` is `series`
-minus whatever the legend has toggled off, and the legend toggles by default at two or more entries
-— hiding a series drops it from the plot, the tooltip AND the auto y-domain together. Drawing
-`series` repaints the mark the reader just hid.
-
-## Boundaries (three independent rules, no escape hatch)
-
-- **`@visx/*` only inside a `charts/` path segment** (`basalt/visx-boundary`, shipped AND
-  repo-local) — import a raw visx primitive from `basalt-ui/charts`'s curated re-export instead.
-- **`@visx/tooltip` is banned everywhere**, charts included (`basalt/visx-tooltip`) — use
-  `ChartTooltipFloat` + `TooltipHeader`/`TooltipRow`/`TooltipBody`. A plain `<div>` inside an
-  `<svg>` mounts in the SVG namespace, typechecks, lints, and never paints.
-- **basalt's own `charts/`+`tokens/` import zero `@mantine/*`** (`basalt/token-layer-boundary`,
-  repo-local — a framework invariant, not an obligation on your app's own `charts/`-named dir). It
-  keeps the token layer upstream of Mantine and lets both subpaths resolve with no Mantine
-  installed.
-- Mantine layout primitives are unreachable in a chart file, so `inline-display`/`raw-html-layout`
-  deliberately don't fire there — raw `<div>` is fine, `VX.*` tokens still mandatory
-  (`ChartCenter` to center).
-- **Maps are not charts** — no map library is `@visx/*`, basalt ships no map kind; build one where
-  the rest of the app's non-chart UI lives, styled with `--vx-*`.
-
-## Color, scheme and margins
-
-- **Never a raw hex in a chart file**, never `localStorage.getItem('theme')`. Theme reactivity is
-  **pure CSS**: `--vx-*` redeclares per scheme, so toggling restyles every chart with no React
-  re-render.
-- **Series color is consumer domain data** — one guard-exempt file per app, `defineSeries` →
-  `seriesTokens`/`groupTokens` → `buildPaletteCss` (basalt-tokens.md), each entry a `{light,dark}`
-  pair.
-- **Margins are MEASURED, not hand-picked** — every axis's tick labels run through
-  `autoMargin`/`measureText` before layout, so `VX.margin` is a floor. Passing `y2` is what makes a
-  chart dual-axis; `margin={{ side: n }}` overrides last. Derive constants from `VX.margin` rather
-  than copying a number into three files.
-- **Never fake an empty dataset for a pending query** — `data ?? []` collapses "not asked yet" into
-  "measured and absent". Pass `isPending`; every kind forwards it to one pending renderer.
-- **`ChartFrame`'s container is `role="group"`, never `role="img"`** — every descendant of a
-  `role="img"` element is presentational, which would erase the hover overlay's `role="slider"`
-  from the accessibility tree silently (jsdom doesn't implement the pruning, so no test catches it).
-
-## Adding a chart
-
-1. **Fits a shipped kind?** Use it — declarative props (`data`, `chartId`, `getX`, `series`, one
-   `AxisConfig` per axis, zones/thresholds/refLines as plain arrays).
-2. **Second instance of a shape with no kind?** Extract a kind (Rule of Three), migrating both call
-   sites; prove it by porting real call sites, ship the "still cannot express" list with it.
-3. **Genuinely unique?** Stay bespoke, composing `CartesianChart`/`ChartFrame` directly in the
-   page's chart file, not in a shared kinds directory.
-
-Sparklines are the one exemption (no legend, no tooltip, no `CartesianChart`) — still `VX.*` only.
-**Anti-pattern:** a single `<Chart type="…" config={…} />` switching by kind — add a kind, don't
-loosen the primitives.
-
-## The x axis is categorical, and the API does not say so
-
-`CartesianChart` builds x as a point scale over domain KEYS — N evenly spaced positions whatever
-the values behind them. Wrong for an event-shaped series: a shared crosshair marks the wrong screen
-x against a regularly-sampled sibling, and two events at the same instant collapse onto one
-position. `getX` returning a date string reads like a time axis and is not one.
-
-The cursor is **shared page-wide by default**, resolved domain-aware (nearest parsed date/number
-within a chart's own step). `ChartCursorScope` ISOLATES a subtree — opts out of sharing, never in.
+- `@visx/*` is banned. [basalt/chart-engine-boundary]
+- Import engine marks only from `@tanstack/charts/{line,area,area-x,bar,rect,rule,dot,tick,text,vector,link,arrow,difference,stack,scales/*,transform/*,mark/decorative,d3/shape,types}`; the bare root and `@tanstack/charts/react` are errors. [basalt/chart-engine-boundary]
+- Wrap a chart kind in `ChartCard`, never a raw `Card` or `Paper`. [basalt/chart-in-raw-surface]
+- Series colors are `{ light, dark }` pairs from the app's series file (`defineSeries`); write no hex or `rgba()` in a chart file. [check-theme raw-hex] [check-theme raw-color-fn]

package/agent/rules/basalt-controls.md

@@ -1,6 +1,6 @@
 ---
 source: basalt-ui
-description: Where an interactive control may live and how it binds — the three homes, the ctl size tier, the store-bound filters and tabs of basalt-ui/controls, the mobile policy, and sidebar blocks. Enforced by basalt/hand-rolled-filter, control-outside-home, bound-control-outside-home, control-size-literal, responsive-twin and page-bar-budget.
+description: Where an interactive control lives and how it binds — homes, slots, store-bound filters and tabs, aside, sidebar blocks.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
@@ -15,140 +15,32 @@ paths:
 <!-- not guarded: C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy -->
 <!-- /basalt:coverage -->
 
-# Basalt Controls — homes, tiers, binding
+# Basalt Controls
 
-Every interactive control — filter, view tab, refresh, action, section header — has one home, one
-size tier and one persistence binding, and basalt owns all three. The API is in the shipped types and
-`llms.txt`; this file is the law. Long form: `docs/CONTROLS-SPEC.md` in the basalt-ui repo.
+A control has one home and takes its state from a store field; the home sets its size.
 
-## The laws
+## Homes
 
-| #   | Law                                                                                                                                                                                                       |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| C1  | A control lives in exactly ONE of three homes — the page bar, a section/widget header, or a form row — entered only through a slot prop.                                                                  |
-| C2  | A basalt filter or tab has no `value`/`onChange`; it takes `field` and owns both the URL write and the localStorage mirror.                                                                               |
-| C3  | Tab and filter state never lives in `useState` — it derives from a store field on the URL lane or the local lane.                                                                                         |
-| C4  | Every field declares its lanes once, at definition, and resolves URL ⊳ localStorage ⊳ fallback uniformly for every field kind.                                                                            |
-| C5  | The HOME sets the size tier; an element inside a home slot carries no `size`, `w`, `fullWidth`, `visibleFrom` or `hiddenFrom`.                                                                            |
-| C6  | A page has one `PageBar`; its `actions` hold ≤5 entries and exactly one `primary`; a `Section` holds ≤3.                                                                                                  |
-| C7  | A home never scrolls horizontally and never wraps — overflow folds into a `More` menu or a `Filters (n)` sheet, computed by basalt from typed data.                                                       |
-| C8  | Every section, card or table title is a `WidgetHeader`; the page title is the breadcrumb (or `PageBar.title` with no shell). An in-body h1/h2 is an error.                                                |
-| C9  | A responsive swap belongs to the control — rendering the same control twice under `visibleFrom`/`hiddenFrom` is an error.                                                                                 |
-| C10 | A nav link carrying a store field passes `store.linkSearch` by reference; a `search:` literal in a nav definition, or a literal `useSearch({ from })`, is an error.                                       |
-| C11 | Every table or list inside a section states its count in its header.                                                                                                                                      |
-| C12 | Refresh/sync has ONE shape, `SyncButton`, whose `scope` picks the home (`global` → the shell header, `page` → `PageBar.sync`).                                                                            |
-| C13 | Sidebar blocks are declared data (`SidebarBlock[]`), never `ReactNode` slots, so rail and More-sheet projection stay basalt's.                                                                            |
-| C14 | An empty home renders nothing, so no route pays for a reserved row.                                                                                                                                       |
-| C15 | Every touch target inside a home clears `--vx-hit` (44px under a coarse pointer). The mobile `Filters (n)` sheet draws no row of its own — it renders the same `PanelRow` the aside's panel surface does. |
-| C16 | A new guard lands `warn` with a dated `promote` version, and the build fails once the package version reaches it while the rule is still `warn`.                                                          |
+- A control lives in exactly one home: a `PageBar` slot (`actions`, `sync`, `filters`, `filtersEnd`, `tabs`), a `Section` slot (`actions`, `tabs`), a `WidgetHeader`/`ChartCard`/`StatCard`/`BasaltDataTable` `actions` slot, or a form row (`SettingsRow.control`, `FormRow`, `FormGroup`). [basalt/control-outside-home]
+- A raw Mantine selection control (`Select`, `SegmentedControl`, …) in a home slot is a filter without a `field`. [basalt/hand-rolled-filter] [check-theme raw-selection-control]
+- A basalt filter outside a slot, `FilterSet`, `PageAside` or form row has no home. [basalt/bound-control-outside-home]
+- `PageBar` `actions` holds at most 5 entries with exactly one `primary`. [type PageBar]
+- A `Section` holds at most 3 `actions`. [type Section]
+- A control in a home slot carries no `size`, `w`, `fullWidth`, `visibleFrom` or `hiddenFrom`; the home sizes it. [basalt/control-size-literal]
+- Never render the same control twice under `visibleFrom`/`hiddenFrom`; the control swaps itself in CSS. [basalt/responsive-twin]
+- A section, card or table title is a `WidgetHeader`; no in-body `<Title order={1|2}>`. [basalt/in-body-page-title]
+- An overlay rendered by the parent lives in a file named `*-{modal,drawer,popover,panel,form}.tsx`, or opts out with `theme-allow-file control-outside-home — overlay`. [basalt/control-outside-home]
 
-A green lint run is not evidence the advisory laws the generated header above lists hold.
+## Binding
 
-## The three homes
+- A filter or tab takes `field={store.field.x}` and nothing else about state; `value`, `onChange` and `size` are type errors. [type ViewTabs]
+- Filters are `RangeFilter`, `MultiSelectFilter`, `SelectFilter`, `SearchFilter`, `NumberFilter`, `ToggleFilter`, inside one `FilterSet` in `PageBar.filters`; `ViewTabs` goes in `PageBar.tabs`. [type FilterSet]
+- `FilterSet` folds overflow and the mobile `Filters (n)` sheet itself; never build either. [type FilterSet]
+- Import `DateRangePicker` from `basalt-ui/controls-dates` and pass it as `RangeFilter` `customPicker`; never import `@mantine/dates` in a shared module. [type RangeFilter]
+- Refresh is `SyncButton`: `scope="page"` in `PageBar.sync`, `scope="global"` in the shell's `globalActions`. [type SyncButton]
+- Actions are typed data (`BarAction[]`), never children. [type BarAction]
 
-| Home                                                                              | Slot props                                         | Tier         | Contents                                   |
-| --------------------------------------------------------------------------------- | -------------------------------------------------- | ------------ | ------------------------------------------ |
-| `PageBar`                                                                         | `actions`, `sync`, `filters`, `filtersEnd`, `tabs` | `ctl`        | the page's filters, tabs, actions, refresh |
-| `Section`                                                                         | `actions`, `tabs`                                  | `ctl`        | that section's own controls and its count  |
-| `WidgetHeader` / `ChartCard` / `StatCard` / `BasaltDataTable` / `SettingsSection` | `actions`                                          | `ctl`        | that widget's own controls and its count   |
-| `SettingsRow` · `FormRow` / `FormGroup` (`basalt-ui/controls`)                    | `control` · children                               | Mantine `md` | ONE form field, or a labelled cluster      |
+## Aside and sidebar
 
-- **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 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
-
-| Anchor                | Mantine size                                               | Where                                               |
-| --------------------- | ---------------------------------------------------------- | --------------------------------------------------- |
-| `controlHeightTag`    | count-tag `Badge`                                          | inline chip, table cell                             |
-| `controlHeightWidget` | `--ai-size-icon` (explicit `size="icon"`, ActionIcon only) | sidebar search actions — no home defaults to it     |
-| `controlHeightCtl`    | `size="ctl"`                                               | `PageBar`, `Section`, table toolbar, sidebar blocks |
-| `--vx-hit`            | hit area, 44px under `(pointer: coarse)`                   | every home                                          |
-| `controlHeight`       | `size="md"`                                                | forms — unchanged                                   |
-
-A home sizes its **slot**, never its body: a raw `Button` in `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. Exception: `ChartCard.actions` is Mantine-free, so it
-carries only the tier attribute and its controls size themselves.
-
-## Binding a control to a store
-
-```tsx
-import { FilterSet, RangeFilter, MultiSelectFilter, ViewTabs } from 'basalt-ui/controls'
-import { DateRangePicker } from 'basalt-ui/controls-dates'
-;<PageBar
-  tabs={<ViewTabs field={analytics.field.tab} />}
-  filters={
-    <FilterSet>
-      <RangeFilter field={analytics.field.range} customPicker={DateRangePicker} />
-      <MultiSelectFilter field={analytics.field.channels} label="All channels" noun="channels" />
-    </FilterSet>
-  }
-/>
-```
-
-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`, 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 with no
-`@mantine/dates`; `DateRangePicker` comes from `basalt-ui/controls-dates` through
-`RangeFilter.customPicker`. Never import it in a shared module or reach for `DatePickerInput`.
-
-## `FilterSet` owns the responsive story
-
-Do not build one at the call site. Above `sm` it measures its own children and folds the tail into
-a `+N` pill. Below `sm` the first `inline` children stay pills and one `Filters (n)` pill opens a
-sheet where every child is full-width and answers one `Reset all`. **`n` and `Reset all` are
-DERIVED** from whether each field differs from its fallback — a filter is one JSX line, no handler.
-
-| Below `sm`      | What basalt does                                                                                                               |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `PageBar` row 1 | breadcrumb · the `primary` action as an icon · ONE kebab holding every `more` action                                           |
-| `PageBar` row 2 | line 1: `ViewTabs` full-width (a `Select` past three options) · line 2: one inline pill · `Filters (n)` · the aside's own pill |
-
-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, and its body IS one:
-children scope to the `panel` surface, so a `SelectFilter` renders its ROW form there, not a pill.
-
-```tsx
-<PageAside title="Composition" persistKey="composition">
-  <PanelRow label="Weight">…</PanelRow>
-</PageAside>
-```
-
-| In a `PageAside` | What it is                                                                        |
-| ---------------- | --------------------------------------------------------------------------------- |
-| `title`          | REQUIRED — the header text AND the region's accessible name; omitted, it THROWS   |
-| `persistKey`     | persists the fold at `basalt:aside:<persistKey>`; omitted the fold is per-mount   |
-| `defaultFolded`  | the fold on first render, honoured only while nothing is persisted                |
-| `classNames`     | the three boxes it paints — `root` / `header` / `body`                            |
-| an inspector row | `PanelRow` — label above, optional `hint`, mono `readout`, `end` slot             |
-| a bound slider   | `SliderControl` — min/max/step come off the handle, never props                   |
-| a facet list     | `MultiSelectFilter` + `counts` (and `max`, past which the tail folds)             |
-| 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 per page, written AFTER the main content — tree position is reading order, not layout.
-- Below `sm` it projects into `PageBar` row 2 as one pill carrying its own `title`, and that row
-  exists ONLY when the bar has `tabs`, `filters` or filter-end actions — without one, or with no
-  shell, it renders in flow at the BOTTOM of the page. 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'`/`'bottom'`; the rail and
-More-sheet projections are basalt's from there (C13). A `custom` block is desktop-only, by design.
+- `PageAside` is the shell's right region; it takes a required `title`. [type PageAside]
+- A sidebar list, progress meter or custom node is a `SidebarBlock` in `BasaltShell sidebarBlocks`, never a `ReactNode`. [type SidebarBlock]

package/agent/rules/basalt-mantine.md

@@ -1,6 +1,6 @@
 ---
 source: basalt-ui
-description: Mantine v9 conventions for basalt-ui apps — provider and overlay mount order, the shell's props, surfaces and depth, scroll regions, motion. Mostly enforced by construction via createBasaltTheme.
+description: Mantine v9 in a basalt-ui app — provider, shell, surfaces, scroll, breakpoints, motion.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
@@ -8,115 +8,42 @@ paths:
 
 <!-- basalt:coverage -->
 <!-- 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-media-query, 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-breakpoint, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
+<!-- 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-media-query, raw-motion-value, raw-spacing, sub-16-input-font · oxlint rules — basalt/card-inset, basalt/hand-rolled-shell, basalt/in-body-page-title, basalt/raw-breakpoint, basalt/raw-scroll-container, basalt/route-view-transition, 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
+# Basalt Mantine
 
-`createBasaltTheme` + `BasaltProvider` encode the theming opinion **by construction**; this rule is
-the part the framework cannot enforce in code. The identity itself and every color/spacing/type law
-live in basalt-tokens.md — not restated here.
+`BasaltProvider` and `BasaltShell` mount the whole app; compose them, never their parts.
 
-## Provider and overlay mount
+## Provider
 
-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`. 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.
+- Mount once: `createBasaltRouter({ routeTree })`, then `<BasaltProvider router={router} />`. It owns Mantine, Query, modals, notifications, Spotlight and the router. [type BasaltProvider]
+- Never pass `cssVariablesResolver` to `BasaltProvider`; retune with `theme={createBasaltTheme(...)}`. [type BasaltProvider]
+- Read and write the color scheme with `useMantineColorScheme()` only. [check-theme localstorage-theme]
 
-**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, 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.
+## Shell
 
-Color scheme is read and written through `useMantineColorScheme()` only — never a client store,
-never `localStorage.getItem('theme')` (guard-enforced; see basalt-state.md).
+- One `BasaltShell nav={NAV}` in `__root.tsx` wraps `<Outlet />`; never build `AppShell.*` parts or a `Burger`, and never wrap `<Outlet />` in `<ViewTransition>` (the router animates route changes in nav order). [basalt/hand-rolled-shell] [basalt/route-view-transition]
+- Shell extensions are typed data props (`globalActions`, `sidebarBlocks`, `brand`, `search`, `settingsMenuItems`, `account`), never `ReactNode` slots. [type BasaltShell]
+- Pass no `renderNavLink`, `renderBreadcrumbLink` or `withBorder`; the shell resolves links against the router and draws region edges. [type BasaltShell]
+- A page is named once, by its nav item's `label` (the breadcrumb), `PageBar.title` (no shell) or `PageTitle` (shell-less screen); no in-body `<Title order={1|2}>`. [basalt/in-body-page-title] [check-theme in-body-page-title]
+- A nav item's mobile placement is its `mobile` field: `'tab'`, `'more'` or `'hidden'`. [type defineNav]
 
-## The shell — one mount, declared data
+## Surfaces
 
-`BasaltShell` composes `AppSidebar` / `MobileNav` / `AppBreadcrumbs` / `PageBar` and is the canonical
-single mount (`basalt/hand-rolled-shell` fires on `AppShell.*` parts or a `Burger` in a file that
-does not render it). The sub-components are exported for a genuinely divergent layout; prefer the
-shell, which already wires collapse persistence, the mobile breakpoint and the breadcrumb.
+- Never pass `withBorder` to `Card` or `Paper`; the theme draws the ring (`<Card.Section withBorder>` is fine). [check-theme card-with-border]
+- Card/Paper insets are `py="xs" px="sm"` with the theme radius; no explicit `p`, `padding` or `radius`. [basalt/card-inset]
+- Lay out with `Box`/`Flex`/`Grid`/`Stack`/`Group`, not a `<div>` with `style`. [check-theme raw-html-layout] [check-theme hidden-inline-style]
+- No inline `display: flex|grid`; no inline spacing; spacing props take `xs..xl`. [check-theme inline-display] [check-theme inline-spacing] [check-theme raw-spacing]
+- Inputs come from `@mantine/core`, never `<input>`, `<select>` or `<textarea>`. [check-theme raw-form-control]
+- Never set a form control's font size below 16. [check-theme sub-16-input-font]
 
-Extension points are **declared data, not `ReactNode` slots**, so basalt owns the mobile projection:
+## Scroll and breakpoints
 
-| Prop                | Shape                                | What basalt then owns                                                                  |
-| ------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
-| `sections`          | `SidebarSection[]`                   | the desktop sidebar AND the mobile bar (`projectMobileNav`) — one definition           |
-| `globalActions`     | `GlobalAction[]`                     | header placement; the first two ride the mobile bar, the rest fold into ONE kebab      |
-| `sidebarBlocks`     | `SidebarBlock[]`                     | rail projection (dot / ring), fold persistence, one More-sheet row per block (law C13) |
-| `brand`             | `BrandConfig & { menu? }`            | a `Name ▾` workspace switcher when `menu` is present                                   |
-| `search`            | `SidebarSearchConfig & { actions? }` | the ⌘K row plus one or two icon buttons (a tuple by type)                              |
-| `settingsMenuItems` | `SettingsMenuItem[]`                 | flat footer rows at three or fewer, one gear menu above that                           |
-| `account`           | `BasaltAccountProps`                 | the footer row, below the settings menu                                                |
+- A scroll region is a Mantine `ScrollArea`, not a raw `overflow: auto` box. [basalt/raw-scroll-container]
+- Never use `visibleFrom`/`hiddenFrom` or a raw `@media` width; chrome follows `useSizeClass()`, page layout follows container queries: `<SimpleGrid type="container" cols={{ base: 1, [CONTAINER_KEYS.regular]: 2 }} />` (`CONTAINER_KEYS` from `basalt-ui/tokens`), never `cols={{ base: 1, lg: 2 }}`. [basalt/raw-breakpoint] [check-theme raw-media-query]
 
-- **The router seam is ONE component, not a render callback.** `SidebarItem.Anchor` (a `NavAnchor`)
-  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.
+## Motion
 
-**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
-
-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/**`.
-- **A page's layout keys on its container, not the viewport** (`type="container"` grids, `CONTAINER_CLASSES`).
-  `useSizeClass()`: shell chrome (and what stands in for it at `compact`), overlay form, `ViewTabs only: 'sm-down'` partners — flash-free under `createRoot`. Recipes: `MIGRATING.md`.
-
-## Scroll regions
-
-**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 breaks a sticky `<thead>`).
-
-## Interaction feedback and motion
-
-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.
+- Animation timing comes from basalt's motion tokens, never a literal duration, spring or easing. [check-theme raw-motion-value]