basalt-ui 1.27.0 → 1.28.0

package/README.md

@@ -101,7 +101,12 @@ import { App } from './App'
 import { paletteGroups } from './theme/series'
 
 // The theme lab owns only the editing UI — the host re-applies any persisted overrides at boot, so
-// a tuning session survives a refresh.
+// a tuning session survives a refresh. `applyOverrides`/`loadOverrides` (and `readVar`) live in
+// `theme-lab/boot.ts`, a Mantine-free, SSR-safe module re-exported through this same
+// `basalt-ui/theme-lab` subpath — no `document` guard needed at the call site, and it never throws
+// under SSR. A production bundler that tree-shakes unused named exports drops `ThemeLabControls`'s
+// Mantine imports when a prod entry (like this one) only ever names these three functions; an
+// unbundled dev build still evaluates the whole subpath module.
 applyOverrides(loadOverrides())
 
 const theme = createBasaltTheme({
@@ -123,6 +128,31 @@ createRoot(document.getElementById('root')!).render(
 > `@mantine/spotlight/styles.layer.css` if you install those optional-peer batteries
 > (`./notifications` / `./commands` — see [Adapter batteries](#adapter-batteries) below).
 
+### Composition order
+
+The canonical stack, once a router and a query client join the example above:
+
+```tsx
+<BasaltProvider theme={theme}>
+  <QueryClientProvider client={queryClient}>
+    <BasaltOverlays>
+      <RouterProvider router={router} />
+    </BasaltOverlays>
+  </QueryClientProvider>
+</BasaltProvider>
+```
+
+The order is load-bearing, not stylistic: `BasaltProvider` auto-mounts `ConnectivityProvider`
+(`./connectivity`), which aggregates React-Query's own status and so must sit **above** the query
+client; `BasaltOverlays` must sit **inside** the theme, since Modals/Spotlight/Notifications
+resolve `--vx-*` tokens through Mantine's context; the router goes **last** so every route
+component renders with the theme, the data layer and the overlay layer already mounted above it.
+`agent/rules/basalt-mantine.md` points here rather than restating the tree.
+
+**No `'use client'` directive ships anywhere in the package.** A Next.js App Router consumer wraps
+this whole composition in its own client file (`'use client'` at the top) and renders that from a
+server layout — basalt stays framework-agnostic and does not guess at the boundary.
+
 ### Theming
 
 The shipped palette isn't a fixed set of hexes — it's **generated** from one accent seed + five
@@ -302,7 +332,7 @@ deleted rather than silently surviving into the next real skew.
 | `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core; plus the annotation reader `--audit-allows` is built on: `findAllowAnnotations`, `neutralizeAllowAnnotation`, `NEUTRALIZED_ALLOW_TOKEN`, `PLUGIN_RULE_IDS`, `AllowAnnotationSite`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `./query`           | **free** | `createBasaltQueryClient`, transport-agnostic `unwrap`, lazy `BasaltQueryDevtools`, `toErrorMessage` / `errorStatus` — the only route to those two; the root barrel does not re-export them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `./router-tanstack` | **free** | TanStack Router bridge: `defineNav`/`navGroup`/`navTarget`/`flattenNav` + `useNav` (→ `{ sections, mobileNav }`), `useBasaltNav` (active route), `useRouterBreadcrumbs`, and `createSearchStore` + the `field.*` vocabulary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `field`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `inputProps`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `./notifications`   | coupled  | Mantine notifications: `notify` helpers, typed registry, persisted history, `NotificationBell`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `./commands`        | coupled  | Typed command bus + overlay controller, `toSpotlightActions`, `ShortcutsHelp`, `BasaltOverlays`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `./data`            | coupled  | Convenience barrel pulling both peer groups: `BasaltDataTable`, `BasaltVirtualList` (Mantine-rendered) — prefer `./data/table` / `./data/virtual` for per-feature opt-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -568,7 +598,7 @@ bun add @mantine/form
 ```
 
 ```tsx
-import { useBasaltForm, field, FormErrorSummary } from 'basalt-ui/forms'
+import { useBasaltForm, inputProps, FormErrorSummary } from 'basalt-ui/forms'
 
 const form = useBasaltForm({ initialValues: { email: '' } })
 ```

package/agent/rules/basalt-batteries.md

@@ -10,7 +10,7 @@ paths:
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --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 -->
+<!-- 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-dual-import, basalt/query-fn-unwrap -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
@@ -60,17 +60,26 @@ Check these three first whenever Eden types regress.
 - **`useBasaltForm` is the entry**: `mode: 'uncontrolled'` by default (no per-keystroke re-render)
   and `schemaResolver(schema, { sync: true })` when a `schema` is passed. Type a schema param as
   `StandardSchemaV1` from `basalt-ui`, never `ZodSchema` — Valibot, Zod 4, ArkType and Effect all
-  satisfy it structurally.
-- **`validate` is deliberately omitted** from its options — a cross-field or async rule that the
-  schema cannot express drops to a raw `useForm`.
-- **`field(form, path)` is the one spread** every uncontrolled Mantine field needs (it bundles
-  `getInputProps` + `key`); writing the two by hand is how one gets forgotten.
+  satisfy it. `validate` stays off its options: a cross-field rule drops to a raw `useForm`, an
+  async one to `useFormSubmit`'s `validateAsync`.
+- **A field is TWO calls on one line**, never one object — a spread `key` is a React 19 warning:
+  `<TextInput key={fieldKey(form, 'x')} {...inputProps(form, 'x')} />`. Dropping it is worse: the
+  field keeps its old text through `form.reset()` and nothing type-checks differently, so
+  **`basalt/forms-field-key`** guards it and autofixes it in. `field` is `@deprecated` (it
+  collides with `basalt-ui/state`'s) and NOT an alias — it still bundles `key`.
+- **`FormRow` is law C1's form row** (label left, control right, label above below `sm`) inside a
+  **`FormSection`**, clusters in a **`FormGroup`**, **`FormActions`** at the end. `SettingsRow` is
+  the settings-page variant — pick by page, never fork a third.
+- **`useFormSubmit` owns the submit**, not a hand-rolled `try`/`catch`: it decodes the throw into
+  the form-level `submitError`, routes a `{ fieldErrors }` envelope back onto the fields as inline
+  errors and focuses the first. Hand its `isSubmitting` to **`FormStateProvider`** and the layout
+  disables itself — never thread `disabled` per input; a custom control reads **`useFormState`**.
+- **`useFieldArray` is the list field**; `key(index)` is positional — reorder by an item id.
 - **`FormErrorSummary` goes at the TOP of the form** so assistive tech lands on it after a failed
   submit. It renders `null` on a clean form, so include it unconditionally.
-- **`useFormDraft` persists through `createPersistedState`** — wire `saveDraft` into
-  `onValuesChange` for autosave, call `clearDraft()` in the success path, keep `key` stable across
-  renders (changing it recreates the store and loses the draft) and bump `version` on a shape change.
-- Errors are inline field errors; a toast is for submit-level failure only.
+- **`useFormDraft` persists through `createPersistedState`** — `autosave: true` owns its own
+  subscription, `clearDraft()` on success, keep `key` stable (changing it loses the draft), bump
+  `version` on a shape change.
 
 ## `./notifications` — `@mantine/notifications`
 
@@ -86,6 +95,9 @@ Check these three first whenever Eden types regress.
 - **Colors beyond the four intents live OUTSIDE the registry** — call Mantine's raw
   `notifications.show({ color })` directly, and accept the stated cost: a raw toast is invisible to
   the persisted history, the bell and the center, because only `notify`/`notifyPromise` record.
+- **`notifyUndo` is the undo window**, not a toast plus your own `setTimeout`: one number is both
+  the `Undo` affordance and the commit delay, `onExpire` is where the optimistic mutation commits,
+  `onUndo` reverts, and exactly one of the two ever runs.
 - History is a module-level persisted ring buffer; `useNotificationHistory` reads it, and
   `NotificationBell` (built for the shell's `globalActions`) opens a `NotificationCenter`, which also
   mounts standalone in any Drawer or panel.
@@ -105,6 +117,9 @@ Check these three first whenever Eden types regress.
   the live keys. Never hand-author a second list of the same commands.
 - Reach for `openSpotlight`/`closeSpotlight` from `basalt-ui/commands`, not Mantine's global
   `spotlight` — `BasaltOverlays` mounts against basalt's own store.
+- **A confirm dialog is not an overlay you define**: `overlays.confirm` / `overlays.confirmDelete`
+  need no registry entry and resolve to the answer. `defineOverlays` is for an overlay with a
+  payload and a body of its own.
 - **Imperative overlay vs route**: `overlays.open` for an ephemeral confirm or quick edit; a route
   for anything that must be shareable, refreshable or back-button-addressable.
 

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, control-size-literal, responsive-twin and page-bar-budget.
+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.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
@@ -8,7 +8,7 @@ paths:
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — raw-selection-control · oxlint rules — basalt/control-outside-home, basalt/control-size-literal, basalt/hand-rolled-filter, basalt/responsive-twin -->
+<!-- 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) -->
 <!-- not guarded: C11 — a table/list stating its count when it is not a BasaltDataTable -->
@@ -23,24 +23,24 @@ size tier and one persistence binding, and basalt owns all three. The API is in
 
 ## The laws
 
-| #   | 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 the `touchControlHeight` floor below `sm`; sheet rows use `sheetRowHeight`.                                                 |
-| 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`.                    |
+| #   | 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 the `touchControlHeight` floor below `sm`. 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`.                                                           |
 
 C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTable` and C12 are
 **advisory** — the generated header above says so. A green lint run is not evidence they hold.
@@ -53,14 +53,17 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `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`                                                                     | `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`**, `PageBar` row 1 portals into the header (the breadcrumb stays the lead)
-  and row 2 renders in-flow, sticky, publishing its measured height as `--basalt-page-bar-h` for a
-  sticky table or a full-height pane to offset against. Without a shell, both rows render in flow with
-  `title` + `icon` leading. The header height is a token on every viewport — never React state.
+- **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.
@@ -122,18 +125,40 @@ immediately, and answers one `Reset all`. **`n` and `Reset all` are DERIVED** fr
 differs from its fallback — so adding a filter is one JSX line, with no count to maintain and no
 reset handler to extend.
 
-| Below `sm`       | What basalt does                                                                          |
-| ---------------- | ----------------------------------------------------------------------------------------- |
-| `PageBar` row 1  | breadcrumb · the `primary` action as an icon · ONE kebab holding every `more` action      |
-| `PageBar` row 2  | `ViewTabs` full-width (a `Select` past three options) · one inline pill · `Filters (n)`   |
-| 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          |
-| a sheet row      | full-width, `sheetRowHeight`, applies immediately                                         |
+| 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 `Panel` pill |
+| 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
 `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.
+
+| In the aside     | Write                                                                             |
+| ---------------- | --------------------------------------------------------------------------------- |
+| 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 `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.
+
 ## Sidebar blocks
 
 A non-destination list, a progress meter or a bespoke node in the sidebar is a `SidebarBlock` —

package/agent/rules/basalt-mantine.md

@@ -8,8 +8,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/hand-rolled-shell, basalt/in-body-page-title, basalt/page-bar-budget, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
-<!-- not guarded: — -->
+<!-- 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 -->
+<!-- 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,11 +22,19 @@ 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
+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
@@ -83,8 +91,11 @@ bugs and are not: the active indicator is a **neutral** ink tint behind the ICON
 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.
+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.
 
 ## Surfaces, depth and shape
 

package/agent/rules/basalt-tokens.md

@@ -65,7 +65,7 @@ theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
 ## 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`. Plus `VX.divider` — NOT a surface, the ONE seam/line token (every `AppShell` region edge + between-rows rule, ink-/white-alpha, holds under the derive knobs); `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,