basalt-ui 1.27.0 → 1.28.0

package/MIGRATING.md

@@ -32,13 +32,457 @@ at 1.3.0, `./agent-chat` at 1.10.0.
 
 ## Unreleased
 
-**Nothing removed. Two exports added (`NumberFilter`, and three members on the number handle),
-one member added to every `FieldHandle` (`clear()`), four `StatCard` props added, and enforcement
-tightened: five oxlint rules plus one guard kind became `error`.** The store half of this minor also
+**Nothing removed, and ONE thing changed shape: `inputProps` no longer returns `key`** — a silent
+behaviour change at every field call site, caught by the new `basalt/forms-field-key` and described
+in its own § below. Read that one before upgrading; the rest of the minor is additive, with
+enforcement tightened: five oxlint rules plus one guard
+kind became `error`, and new rule ids shipped at `warn`. The store half of this minor also
 fixed four inference and notification defects consumers hit while porting, plus two ways a fallback
 got pinned into localStorage — see § Stores below. Every level change honours the `theme-allow`
 grammar unchanged; only the severity of an unwaived finding moves.
 
+**One behaviour change with a blast radius past this package: `AppShell.Main` is now the
+scrollport, and the WINDOW no longer scrolls inside a `BasaltShell`.** Nothing was removed or
+renamed, but four things a consumer may be doing stop working, and all four have a one-line remedy —
+see § The shell scrollport below.
+
+What is new, one line each — nothing here renames or removes anything:
+
+- **`scrollParentOf` / `SCROLLPORT_ATTRIBUTE`** (`basalt-ui`) — resolve which box actually scrolls an
+  element (`null` = the document). The seam behind the shell scrollport change below.
+- **`PageAside`** (`basalt-ui`) — the right-hand aside REGION a route claims, with the panel filter
+  surface in its body and a mobile projection into `PageBar` row 2 (`docs/ASIDE-SPEC.md`).
+- **`PanelRow`** (`basalt-ui/controls`) — the aside's inspector/facet row: label above, control
+  below, `end` for a control that rides the label line. Every bound control renders one on the
+  `panel` surface.
+- **`SliderControl`** (`basalt-ui/controls`) — a `field.number`-bound track for a weight or a
+  threshold. It always renders a `PanelRow`, so unlike the pill filters a `Section` body is a
+  legitimate home for it and `basalt/bound-control-outside-home` does not police it.
+- **`MultiSelectFilter.counts` / `.max`** — per-option counts (a mono number plus a proportional
+  bar) and the panel facet cut-off before the `Show more` fold. Both optional; omitted is today's
+  rendering.
+- **`field.number({ step })`** — the declared grain, republished on the handle. `field.number`
+  resolves `1` for an `int: true` field that declared none, so `NumberFilter` and `SliderControl`
+  cannot answer it differently.
+- **`basalt/bound-control-outside-home`** — a NEW rule id at `warn` (grace to 1.30.0): a bound
+  basalt control written into a `Section` body or a page stack renders as a stray pill.
+  `control-outside-home` matches raw Mantine tags only, so this half of law C1 was unguarded. Homes
+  are the slot props plus the `FilterSet` / `PageAside` / `PanelRow` subtrees; the escape is
+  `theme-allow bound-control-outside-home — <why>`.
+- **The chart phone tier** (`basalt-ui/charts`) — `resolveChartTier` / `chartTierMetrics` /
+  `useChartTier` / `useChartTierMetrics`, plus `VX.phoneChartWidth` (480). Below that MEASURED
+  container width (never a media query — a chart in a narrow grid cell on a desktop is as narrow as
+  one on a phone) a chart drops the legend and tick fonts one type step, tightens the `VX.margin`
+  FLOORS to 0.75×, shrinks the crosshair dot, narrows the tooltip 140 → 110, and caps the legend at
+  two entries with a `+N more` rollup. **This moves rendering, but only below 480px of measured
+  width** — nothing at desktop width changes. Opt back out per chart with an explicit
+  `legend.maxRows` / `margin` override. `docs/CHARTS-SPEC.md` §8.
+- **`xLabelRotate` accepts `0`**, and left UNSET now auto-rotates to 45 at the phone tier when the
+  measured labels cannot fit three ticks side by side. `0` is the documented opt-out. Also on every
+  rotated axis, at every width: the LEFT margin now clears the rotated label's leftward projection
+  (`width × cos(angle)`), which previously ran the first label off the plot, and `smartTicks` drops
+  the grid tick before an appended final one when the two would overlap. Both are corrections to
+  §1's measured-gutter law, so a rotated or a densely-labelled axis will lay out slightly
+  differently; an explicit `margin` / `xTicks` / `xTickValues` still wins.
+- **`SeriesStyle.curve`** (`basalt-ui/charts`) — `'monotone' | 'linear' | 'step' | 'stepAfter' |
+'stepBefore'`, plus the `curveFor` mapper and the newly re-exported `curveStep`/`curveStepBefore`.
+  Default `'monotone'`, which is what every kind hard-coded, so an omitted `curve` moves nothing.
+  Honoured by `MultiLine`, `DualPanel`, `ZonedLine`, `StackedArea` and `BarsLine.curve`. Two of
+  those read ONE curve for a whole shape rather than one per series: `ZonedLine` takes the PRIMARY
+  series' (its band, area and line are one reading), and `StackedArea` takes the TOPMOST VISIBLE
+  band that declares one — the last such entry in your `series` array (`AreaStack`'s bands share
+  their boundaries, so two curves would leave gaps between them). A hidden band's curve is ignored
+  either way, so a legend toggle can hand a stack to the next declarer down.
+- **Single-series legend suppressed by default** (`basalt-ui/charts`) — since commit `5e0ade1`, a
+  chart with exactly one visible series and no `legend` prop renders no legend. Pass `legend={{}}`
+  (or any explicit config) to keep it.
+- **`Bars`' baseline is now the axis' domain floor**, not `yScale(0)` — previously a y domain that
+  did not reach 0 drew the bar off the bottom of the plot; now it stops at the domain's own floor,
+  which also makes a log y-axis usable on `Bars`. A domain that includes 0 is unchanged.
+- **Number formatters** (`basalt-ui/charts`) — `fmtCompact`, `fmtPercent`, `fmtCurrency`, `fmtInt`
+  and the `formatters` bundle, all `Intl`-backed with an explicit `locale` defaulting to the
+  runtime's. `utils/format.ts` shipped only two DATE formatters, so every call site hand-rolled
+  `` `$${v}k` ``. **Every formatter — the two date ones included — now returns an em dash for
+  non-finite input** (`NaN`, `±Infinity`, an `Invalid Date`) instead of `Intl`'s own `NaN` / `∞`.
+  A collapsed domain therefore stops painting its arithmetic accident as a tick label.
+- **`ChartEmpty` / `ChartError` / `state` / `resolveChartState`** (`basalt-ui/charts`) — the chart
+  layer's own three-state placeholder set. `state?: { pending?, error?, empty? }` on
+  `CartesianChart` / `ChartFrame` / every kind resolves pending → error → empty, so a consumer no
+  longer needs the Mantine-coupled `QueryState` (unreachable from `./charts`) to tell a 500 apart
+  from an empty result. **`isPending` still works and is not deprecated** — it is an alias for
+  `state={{ pending: true }}`. `ChartError` announces as `role="alert"`; `ChartPending` and
+  `ChartEmpty` as `role="status"`, so a screen reader hears the resolution and not only the failure.
+- **`BasaltProps` on every exported chart component** — `className` and `style` now reach the root
+  element of every kind, sparkline and primitive; `ChartCard` also takes
+  `classNames={{ root, header, body }}`. Additive: a component that ignored `className` now honours
+  it, so a stylesheet that previously had no effect starts having one.
+- **`ChartTooltipFloat` server-renders.** It was the one `renderToString` casualty in the package
+  (an unconditional `createPortal`); it now emits nothing on the server and is unchanged in the
+  browser. Consumers carrying an SSR workaround around a chart tooltip can drop it.
+- **`BREAKPOINTS`** (`basalt-ui/tokens`) — `{ article: 1200 }`. The one `@media` literal in the
+  package that was not derived from anything now has a named, testable counterpart; a `@media`
+  condition cannot read a custom property, so the literal stays and a test holds the two together.
+- **`theme-lab/boot.ts`** — `applyOverrides`/`loadOverrides`/`readVar` moved into their own
+  Mantine-free, SSR-safe module (no-op / empty result with no `document`, instead of throwing).
+  `basalt-ui/theme-lab` still resolves all three, unchanged, alongside `ThemeLabControls` and
+  `DeriveControls` — nothing renamed or removed, and no new subpath was added.
+- **`basalt/raw-size-literal` / `basalt/no-raw-font-size`** — no longer exempt a consumer's own
+  `src/tokens/` directory. The exemption was basalt-internal (the derive engine's own hardcoded
+  scale values) and leaked to any package with a same-named directory. Consumers with raw sizes
+  there move them to `--vx-*` tokens, or add a `theme-allow` waiver.
+- **`BasaltProvider connectivity` prop** — `Omit<ConnectivityProviderProps, 'children'>`, threaded
+  straight through to the auto-mounted `ConnectivityProvider`. Reaches `override` for the first
+  time (the only prior route was mounting a second, shadowing `ConnectivityProvider`) — see
+  § BasaltProvider below.
+- **Six new oxlint rule ids, all `warn`** — `basalt/provider-above-router`,
+  `basalt/duplicate-notifications-mount`, `basalt/query-dual-import`, `basalt/query-fn-unwrap`,
+  `basalt/forms-field-key` (grace to 1.30.0) and `basalt/deprecated-export` (permanently
+  advisory). `forms-field-key` is the one that matters most in this minor — it is the only thing
+  that reports the `inputProps` call sites below, which a compiler cannot see; see § `inputProps`.
+  The first four guard
+  four doctrines that shipped stated-but-unguarded under a `not guarded:` banner — the provider/
+  router mount order, the `BasaltOverlays` XOR `BasaltNotifications` double-mount, the
+  `basalt-ui/query` import seam, and `queryFn` wrapping in `unwrap()`. Each is honest about its
+  reach in its own message and its grace entry: all four read ONE file, and the two query rules
+  carry a documented text heuristic. Escape with `theme-allow <rule> — <why>` as usual. Nothing
+  fails a build: every one is `warn` in the shipped preset.
+- **`basalt/deprecated-export`** — nudges an import or a prop basalt has deprecated but still ships,
+  reading the `DEPRECATED_EXPORTS` ledger beside the plugin. Today that is `field` from
+  `basalt-ui/forms` (autofixed to `inputProps as field`, so no call site moves) and the three
+  flattened `BasaltProvider` connectivity props. Permanently `warn` — a deprecation is a schedule,
+  not a defect. **On the `field` row, take the two fixes in order**: that rename lands the new
+  `inputProps` shape, which has no `key`, and `basalt/forms-field-key` then reports the same line
+  and inserts the `key`. Two `--fix` passes, or one manual edit writing both.
+- **Dev-only duplicate-mount warnings** — `BasaltProvider` now warns when a second instance mounts
+  while the first is still mounted; `<BasaltOverlays notifications />` and `<BasaltNotifications />`
+  now warn when BOTH are mounted at once (previously prose-only in both cases). Both are
+  `console.warn`, dev builds only, no behavior change.
+- **`WidgetGrid` + `WidgetGrid.Item` and `StatGroup`** (`basalt-ui`) — the dashboard column law,
+  owned once. `cols` is the DESKTOP count and the only number you state: `WidgetGrid` resolves
+  `base 1 → sm min(cols, 2) → lg cols`; `StatGroup` (the KPI row) resolves
+  `base 2 → sm min(cols, 3) → lg cols`. `<WidgetGrid.Item span={2}>` widens one cell and is clamped
+  to the live count at each breakpoint. `StatGroup divided` swaps the column gap for a hairline rail. **These two are the only
+  place `lg` exists in the package** — `sm` remains the only breakpoint a consumer writes
+  (`docs/CONTROLS-SPEC.md` §2). Replaces hand-written `SimpleGrid cols={{ base, md }}` /
+  `Grid.Col span={{ base: 12, md: 8 }}`; Mantine's responsive `cols` object is deliberately not a
+  prop.
+- **`StatCard.query`** — `QueryStateLike`, the same structural subset `QueryState` takes. Supplied,
+  the card renders its pending / error / empty branch through `QueryState` at the `'section'` tier
+  INSIDE the body, directly under the header, which stays put. Omitted, nothing changes. `value` is
+  still yours to format — pass a placeholder while the query is pending.
+- **`WidgetHeaderTitleProps` / `WidgetHeaderMetricProps` / `WidgetHeaderDeltaProps`** (`basalt-ui`)
+  — the named `Pick` slices of `WidgetHeaderProps` its composers share, cut along the three rows the
+  header paints. `StatCardProps` and `SettingsSectionProps` now compose them instead of re-declaring
+  props one at a time; **both gained props as a result** — `SettingsSection`/`DangerZone` now accept
+  and FORWARD `icon` and `info`. Nothing was removed from either (pinned by
+  `src/dashboard/stat-card-props.test.ts`). `Section` and `ChartCard` still cut their own subsets.
+- **`tier` replaces `variant` on `QueryState` / `LoadingState` / `ErrorState` / `EmptyState`** —
+  `tier` is the package's word for "how loud is this" (`WidgetHeader`, `CtlSlot`), and `'section'`
+  meant two different things across the two spellings. `variant` is `@deprecated` and still
+  honoured; resolution is `tier ?? variant ?? 'page'`, so nothing moves until you change the prop.
+  `QueryStateTier` is the new type name; `QueryStateVariant` stays exported as an alias. No removal
+  is scheduled — this is a preferred spelling, not a sunset.
+- **`WidgetHeader` and `QueryState` gained slot classes** — `classNames={{ root, title, metric,
+icon }}` on the first, `classNames={{ root }}` on the second (the branch that is live). Additive.
+  `Section` now OMITS `classNames` from the `WidgetHeaderProps` it re-publishes, so its slot union
+  stays exactly `root | header | body` — a `<Section classNames={{ metric: … }}>` that used to
+  type-check (and do nothing) is now a compile error. Reach the header's own slots on a
+  `WidgetHeader`.
+- **`Callout` extends `BasaltProps`** — `className`/`style` were already accepted and are now the
+  shared members, so `exactOptionalPropertyTypes` consumers can forward an `string | undefined`
+  through. No rendering change.
+- **`PageAside` throws on a missing `title`** — it is both the header text and the region's
+  `aria-label`, so an omitted one shipped a nameless landmark rather than a crash. Now
+  `[basalt] PageAside: prop "title" is required — …`, in every build. `title` was never optional in
+  the type; this only reaches untyped JS and runtime-built props objects.
+- **`BasaltDataTable` warns (dev only) when `stickyHeaderOffset` meets `maxHeight`/`minWidth`** —
+  the offset has always been DROPPED there (the sticky `<thead>` anchors to the scroll container's
+  own top edge, not the window). The behaviour is unchanged; it just says so now.
+- **`query` on `Section`, `BasaltDataTable` and `BasaltVirtualList`** — law C3's uniform container
+  contract. Pass a `QueryStateLike` (a TanStack `UseQueryResult` is one) and the container resolves
+  the body: pending → its own placeholder (`QueryState`'s section-tier spinner / the table's
+  skeleton rows / the list's skeleton rows), error with no data → an `ErrorState` with the query's
+  own `refetch` behind Retry, anything else → the content, or the empty branch. **The table and the
+  list had NO error branch at all**, so a 500 rendered _No data to display._ / a blank box — the
+  false claim `QueryState` exists to delete. Additive: omit `query` and nothing changes.
+  `Section` also gains `empty?: QueryEmptyCopy` (copy for that branch, `QueryState`'s own type) and
+  `BasaltVirtualList` gains `emptyState?: ReactNode` (which works with or without `query`).
+  `isLoading` still works on both containers and is NOT deprecated; passing it beside `query` lets
+  `query` win and warns once in dev. The chrome stays drawn through every branch — a table keeps its
+  `<thead>`, toolbar and pagination bar, a `Section` keeps its header, chevron and `summary` — which
+  is why this is not `QueryState` wrapped around the container. A refetch that fails over rows
+  already on screen keeps the rows with no banner; compose `QueryState` AROUND the container for
+  that.
+- **`BasaltDataTable.onRowActivate`** — `(row: T) => void`, fired by a click on the row and by Enter
+  on a focused one. The row → detail hook that pairs with `PageAside`. The row keeps its native
+  `<tr>` semantics and takes `tabIndex=0` + `data-activatable` rather than `role="button"` (a role
+  swap costs the column-header announcement that is the reason the data is in a table); the cursor
+  and focus ring come from a module class. A click originating inside the selection checkbox does
+  not activate.
+- **`BasaltDataTable` row selection** — `enableRowSelection` prepends a checkbox column (header =
+  select-all on the page) and arms TanStack's row-selection feature; `rowSelection` /
+  `onRowSelectionChange` are the controlled pair over TanStack's own `RowSelectionState` (now
+  re-exported from `basalt-ui/data` and `basalt-ui/data/table`), and `getRowId` makes a selection
+  survive a re-sort or a refetch (the default id is the row INDEX). `bulkActions` renders a bar
+  above the table while ≥1 row is selected — the count, then the actions, through the SAME
+  `BarAction[]` vocabulary `PageBar` uses, so the ≤3-inline fold and the mobile kebab are basalt's
+  here too. **Its signature is `(rows: T[]) => BarAction[]`, a function and not a bare array**, and
+  deliberately: `BarActionItem.onClick` stays `() => void` (one unforked vocabulary across every
+  home), so the selected rows reach a handler through the closure you write — and an UNCONTROLLED
+  table can offer bulk actions at all, since the selection lives inside it.
+- **`Section.actions` and `BasaltDataTable.actions` accept `BarAction[] | ReactNode`** — law C15.
+  Handed typed data, basalt owns the C6 budget and the C7 overflow fold (≤3 inline, the rest behind
+  `More`, one kebab below `sm`) exactly as `PageBar` does; handed a node, rendering is byte-for-byte
+  what it was. Every entry lands in `secondary` — a `BarAction[]` carries no primary marker, and C6's
+  "exactly one primary" stays the page bar's rule. `Section`'s ≤3 dev warning now counts an array
+  EXACTLY (`Children.count` read one as a single child). Both slots were `ReactNode` before, so no
+  call site moves.
+- **`overlays.confirm` / `overlays.confirmDelete`** (`basalt-ui/commands`) — the two-button dialog
+  every consumer was registering as a `defineOverlays` entry with its own button pair, now
+  registry-free: `confirm({ title, body?, confirmLabel?, cancelLabel?, danger?, onConfirm,
+onCancel? })` resolves `true`/`false` and fires exactly one callback, whichever exit the user takes
+  (cancel, escape, click-outside and the close button all count as `false`). `danger` paints the
+  confirm button in the theme's derived destructive family. `confirmDelete({ subject, count?,
+onConfirm })` is the counted one-liner over it ("Delete 3 items?"). Both REJECT with a named
+  `[basalt] overlays.confirm: …` error when the `@mantine/modals` peer is absent, or when no
+  `ModalsProvider` is live — previously either returned a promise nothing would ever settle, because
+  the imperative API is a window event bus with nothing subscribed. `@mantine/modals` stays lazily
+  imported, so the peer is still optional. Additive: `defineOverlays` and `overlays.open` are
+  unchanged.
+- **`registerModalsProvider()`** (`basalt-ui/commands`) — how a consumer who mounts
+  `<ModalsProvider>` THEMSELVES (with `<BasaltOverlays modals={false}>`, or with no `BasaltOverlays`
+  at all) tells `overlays.confirm` the layer is up. `<BasaltOverlays>` registers its own provider, so
+  the default path needs nothing. Call it from an effect and return its result as the cleanup:
+
+  ```tsx
+  useEffect(() => registerModalsProvider(), [])
+  ```
+
+  Availability is a COUNTER of live providers, not a flag, so two overlapping mounts (a route swap
+  mounting the next shell before unmounting the last) never report "no layer" while one is serving.
+  There is no way to detect the provider from outside React — its context is only readable through
+  `useModals()`, and `confirm` is an imperative call with no component to read it from — so the
+  registration is explicit and unregistered is indistinguishable from absent.
+
+- **`notifyUndo` / `notifyUndoable`** (`basalt-ui/notifications`) — an undo window on top of the
+  existing toast machinery: `notifyUndo({ message, onUndo, window = 6000, onExpire })` shows a toast
+  carrying an `Undo` button and returns `{ id, dismiss() }`. The affordance and the grace period are
+  ONE number (`autoClose === window`), and exactly one of `onUndo` / `onExpire` runs, exactly once —
+  `onExpire` is where the optimistic mutation COMMITS. `dismiss()` settles the window immediately
+  (running `onExpire`), so a dismissed toast can never strand an uncommitted change.
+  `notifyUndoable(mutate, undo, opts)` is the same thing spelled for the optimistic shape. No new
+  store — the toast is recorded to the notification history like any other.
+- **`NotifyOptions.historyMessage`** — what the persisted history records when `message` is a
+  composed ReactNode the store cannot stringify (`String(<Group/>)` is `[object Object]`). Defaults
+  to today's `String(message)`, so nothing moves unless you pass it. `notifyUndo` uses it.
+- **`missingLayer`** (`basalt-ui`) — a message builder beside `requiredProp`/`oneOf`/`duplicateMount`
+  for "this call needs a layer that is not mounted or not installed". Additive.
+- **`emit`'s payload now narrows per kind** (`basalt-ui/notifications`) — `NotificationSpec<P>` and
+  `NotificationAction<P>` are generic, `P` inferred from `toMessage`/`action.run`'s parameter, the
+  same mechanism `Overlay<P>` uses for `render`. Annotate the payload shape and `emit('kind', …)`
+  requires it, a wrong shape is a tsc error. A kind that annotates neither function keeps today's
+  `payload?: unknown` — additive, no existing `defineNotifications` call needs a change.
+- **The form layer** (`basalt-ui/forms`) — `./forms` was an adapter with no layout, no submit
+  lifecycle, no array helper and no disabled propagation (audit B #5). Seven new exports, all
+  additive; `useBasaltForm`, `FormErrorSummary` and `useFormDraft`'s existing signature are
+  untouched. `inputProps` is the one exception, and it is not additive — see § `inputProps` no
+  longer returns `key` below.
+  - **`FormSection` / `FormRow` / `FormGroup` / `FormActions`** — the layout. `FormRow` IS law C1's
+    third home, the form row: label left / control right, label above below `sm`, the swap in CSS
+    (law C9). It does NOT replace `SettingsRow` — that stays the settings-page variant, and both
+    keep Mantine's `md` tier rather than mounting a `CtlSlot`. `FormActions` takes the same
+    `BarAction[] | ReactNode` union law C15 gave `Section.actions`.
+  - **`useFormSubmit(form, handler, options?)`** — `{ submit, isSubmitting, submitError, reset }`.
+    Catches the handler's throw and decodes it through `toErrorMessage` (override with `mapError`),
+    routes a thrown `{ fieldErrors }` envelope onto the fields via `form.setErrors`, and focuses the
+    first errored field on BOTH failure paths. `isSubmitting` is Mantine's own `form.submitting`,
+    not a second flag beside it.
+  - **`options.validateAsync`** — the async validation rule `useBasaltForm` has no room for:
+    `schemaResolver(schema, { sync: true })` is still hard-coded, so `validate()`/`isValid()` stay
+    synchronous, and the async rule runs at submit time after the schema and before the handler.
+  - **`FormStateProvider` / `useFormState`** — `{ disabled, submitting }`. The layout primitives
+    read it and disable their control region through a native `<fieldset disabled>`, so nothing has
+    to be threaded to each input and no child is cloned. Nesting ORs; it cannot re-enable.
+  - **`useFieldArray(form, path)`** — `{ items, append, remove, move, key }` over
+    `insertListItem`/`removeListItem`/`reorderListItem` + `form.key`. `key(index)` is POSITIONAL
+    (Mantine's list actions do not rotate the form key generation) — a user-reorderable list still
+    wants an id on the item.
+  - **`useFormDraft(form, { autosave })`** — `true`, or `{ debounceMs }`. The hook now owns its own
+    `form.watch` subscription, replacing the documented `saveDraftRef` + `onValuesChange` dance. It
+    is OFF by default and READ ONCE at mount (the watch set is a hook count), so every existing call
+    site behaves exactly as before. `DEFAULT_AUTOSAVE_DEBOUNCE_MS` is exported.
+  - **Still subpath-only.** The root barrel re-exports none of this, so a consumer without
+    `@mantine/form` is unaffected by importing `basalt-ui`.
+- **Mobile "More" sheet rows now 40px with the sidebar's own insets** — `--vx-space-mobile-nav-row-
+height` 44 → 40 (WCAG 2.5.5 AA touch floor, not the AAA figure the bar's own `mobileNavBarHeight`
+  still holds to). The rows themselves no longer force a bespoke touch padding over the theme's
+  `NavLink` styling; they now render with the SAME `--vx-space-row-inset-y`/`-x` padding and
+  `VX.text.md` the desktop sidebar row does. A nested (child) row gains the sidebar's own child
+  indent — a 1px `--vx-divider` left guide. Purely visual; no prop, export or behaviour changed.
+- **`NotificationCenter` defaults to `width: '100%'`, not a hardcoded `320`** — it now sizes to its
+  host instead of assuming it always sits inside its own 320px popover. `NotificationBell` fixes the
+  320px width at the `Popover` itself (`<Popover width={320}>`) instead, so nothing changes for that
+  call path; a consumer mounting `NotificationCenter` directly (a Drawer, an inline card) now gets a
+  component that shrinks to its container rather than overflowing it. `style` still merges over the
+  default, so `style={{ width: 280 }}` still wins.
+
+### `inputProps` no longer returns `key` — pair it with the new `fieldKey`
+
+**This is the one thing in the minor that needs a code change at every call site, and the compiler
+will not tell you about a single one of them.** It is a one-line-per-field edit:
+
+```tsx
+/* before (1.27) */ <TextInput {...inputProps(form, 'email')} />
+/* after          */ <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} />
+```
+
+**Exactly what changed.** In 1.27 `inputProps(form, path)` returned `form.getInputProps(path)` **and
+`key`** in one object, so a single spread covered both. It now returns `form.getInputProps(path)`
+and nothing else; `fieldKey(form, path)` is the other half, written as a real JSX `key` attribute.
+The bundle was basalt's own invention, and React 19 logs `A props object containing a "key" prop is
+being spread into JSX` on every render of it — three fields, three warnings per page.
+`key={form.key(path)} {...form.getInputProps(path)}` is Mantine's own documented idiom; `fieldKey` +
+`inputProps` is that idiom with basalt's names.
+
+**What breaks if you only upgrade and do nothing.** Nothing type-checks differently, nothing throws
+and no warning is logged — the 1.27 call site is still a valid spread of a valid object. The element
+simply has no `key` any more, so React reuses the DOM node and an uncontrolled input keeps its old
+text through `form.reset()`, `form.setValues()` and a removed list row. That is the entire failure
+mode: a form that stops resetting, with no signal anywhere.
+
+**What catches it: `basalt/forms-field-key`**, new in this minor at `warn` (grace to 1.30.0). It
+reports every `{...inputProps(…)}` spread whose element carries no sibling `key`, and it
+**autofixes** — inserting `key={fieldKey(<same args>)}` and adding `fieldKey` to the existing
+`basalt-ui/forms` import. Run `oxlint --fix` over the app and read the diff; the escape hatch for an
+element genuinely remounted by its parent is `theme-allow forms-field-key — <why>`.
+
+**The deprecated `field` alias did NOT follow `inputProps` here.** It is no longer
+`export const field = inputProps`: it keeps the 1.27 return shape, `key` included, so
+`{...field(form, 'x')}` behaves in 1.28.0 byte for byte as it did in 1.27 — including the React 19
+key-spread warning. An alias would have changed what every existing call site DOES without changing
+whether it compiles, and a deprecation is a schedule, not a behaviour change. `forms-field-key`
+reports the `field(` spread too, with its own message pointing here; the alias itself is removed in
+`1.29.0`.
+
+### `BasaltDataTable` — the root is a `<div>`, not a Fragment
+
+**One structural change, no prop change.** The component returned a Fragment, so the header row, the
+table (or its scroll container) and the pagination bar were DIRECT CHILDREN of whatever the caller
+rendered it into. It now always renders a wrapper:
+
+```html
+<div class="{classNames.root} {className}" style="{style}">
+  …header row… …table / Table.ScrollContainer… …pagination bar…
+</div>
+```
+
+A `className` needs a root to live on (`common/props.ts`), and a Fragment has none — so the wrapper
+is what `className`, `style` and `classNames.root` all resolve against. It is unconditional: a table
+with no title, no toolbar and no pagination still renders it.
+
+**What breaks:** any CSS or test selector written against the OLD flat structure. A
+`.page-grid > table`, a `:first-child` rule aimed at the table, an `:nth-child` counting the header
+row and the pagination bar as siblings of your own content, or a flex/grid parent that laid those
+three boxes out itself — all now see one child. Target the wrapper instead, and give it the layout:
+
+```css
+/* before */ .page-grid > table { … }
+/* after  */ .page-grid > div > table { … }   /* or: <BasaltDataTable classNames={{ root: 'my-table' }} /> */
+```
+
+Pinned by `src/data/data-table.test.tsx` ("the root is one div carrying classNames.root, wrapping
+the table and the pagination bar"), so it cannot revert silently.
+
+### BasaltProvider — a `connectivity` object replaces three flattened props
+
+`sseUrl` / `healthUrl` / `healthIntervalMs` on `BasaltProvider` are now `@deprecated` aliases for
+the corresponding fields on the new `connectivity` prop — **removed in 1.29.0**. `connectivity`
+wins WHOLESALE once supplied, not per-key: passing `connectivity` at all makes basalt ignore the
+three deprecated props entirely, even ones `connectivity` itself leaves unset. Supplying both logs a
+dev-only warning. Move every deprecated field to `connectivity` in one pass, not one field at a time.
+
+| Removed / deprecated                      | Replacement                                                                                                                         |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `<BasaltProvider sseUrl={…} />`           | `<BasaltProvider connectivity={{ sseUrl: … }} />` — `@deprecated`, removed 1.29.0                                                   |
+| `<BasaltProvider healthUrl={…} />`        | `<BasaltProvider connectivity={{ healthUrl: … }} />` — `@deprecated`, removed 1.29.0                                                |
+| `<BasaltProvider healthIntervalMs={…} />` | `<BasaltProvider connectivity={{ healthIntervalMs: … }} />` — `@deprecated`, removed 1.29.0                                         |
+| (unreachable before this minor)           | `<BasaltProvider connectivity={{ override: {…} }} />` — simulate a signal for testing/demo, no second `ConnectivityProvider` needed |
+
+**`cssVariablesResolver` can no longer reach `BasaltProvider` through the passthrough
+`MantineProviderProps` rest** — it was silently spreadable and would override basalt's own resolver
+(the one thing the provider exists to install). `Omit`ted from the accepted prop type; pass any
+palette customization through `createBasaltTheme(overrides, { derive, fonts, radius, density })`
+instead.
+
+### `basalt-ui/connectivity` — `queryOnline` narrowed to `boolean`
+
+`ConnectivitySnapshot['details'].queryOnline` and `ConnectivityOverride.queryOnline` drop the
+`| null` arm. The JSDoc used to claim null meant "QueryClient not mounted", but `onlineManager` is a
+module-level singleton read with no such check — the only null this field ever carried was the
+pre-hydration SSR snapshot, which now reports an optimistic `true` (matching `browserOnline`'s own
+SSR default) instead. Code branching on `queryOnline === null` was already dead; delete it.
+
+### `basalt-ui/state` — eight internal symbols dropped from the barrel
+
+| Removed / renamed                                                                                                | Replacement | Note                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createStoreCore`, `resolveFieldCodec` (`basalt-ui/state`)                                                       | none        | Both were `@internal` — the seam `createSearchStore` is built on, not a consumer API — and were never meant to be a public contract. No replacement needed.           |
+| `FieldCodec`, `StoreEntry`, `StoreCoreOptions`, `StoreCore`, `FieldUse`, `FieldWrite` (types, `basalt-ui/state`) | none        | Also `@internal` — the supporting types behind `createStoreCore`/`resolveFieldCodec`, dropped alongside the two functions for the same reason. No replacement needed. |
+
+### `basalt-ui/forms` — `field` renamed to `inputProps`
+
+Two unrelated exports shared the name `field`: the forms adapter's `getInputProps`+`key` bundler and
+the `field.enum/multi/range/number/boolean/string` store-field builder in `basalt-ui/state` and
+`basalt-ui/router-tanstack`. A page combining a form and a filter store had to alias one on import.
+
+| Removed / renamed           | Replacement  | Note                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `field` (`basalt-ui/forms`) | `inputProps` | Same signature — `inputProps(form, path)`. `field` still resolves from `basalt-ui/forms` as a `@deprecated` alias, so nothing breaks; the alias goes away the next time the forms surface changes, and that removal ships as a plain `feat:`, never a major. **Since the Unreleased minor the two are no longer the same function**: `inputProps` dropped `key` from its return and `field` did not — see § `inputProps` no longer returns `key`. |
+
+The `field.*` store builder (`basalt-ui/state`, `basalt-ui/router-tanstack`) is untouched.
+
+### Shell — region seams, and what moved with them
+
+**Every `AppShell` region now ends in a real, themed 1px `--vx-divider` line on its Main-facing
+edge, with no opt-out** (`docs/DESIGN-SPEC.md` §5 "Region seams", §8 inversion #12): sidebar|main
+(full height, under `layout="alt"` it owns the top-left corner), header|main (main column only),
+main|aside (full height, absent when the aside is unclaimed), main|mobile-nav (below `sm`). Mantine
+draws all four itself through `[data-with-border]`; the colour is one theme var,
+`AppShell.extend({ vars: () => ({ root: { '--app-shell-border-color': 'var(--vx-divider)' } }) })`.
+The aside's shell-form header also carries its own `border-bottom: 1px solid var(--vx-divider)`, so
+the top belt's seam closes across the panel instead of dead-ending at the aside column.
+**Delete any hand-drawn twin**: a `border-left` on your own aside-shaped panel, a `border-bottom`
+under `PageBar` via `className`, a `withBorder` or a `--app-shell-border-color` override on your own
+`AppShell` sections — the theme only pins the COLOUR; `withBorder` still adds or removes the edge
+per section (Mantine gates the border CSS on `[data-with-border]`), so a leftover `withBorder={false}`
+still suppresses the seam and must be deleted to get it, and a leftover `withBorder={true}` is
+redundant (Mantine's own default).
+
+- **`--vx-divider` moved.** Light is now `rgba(<derived ink>, 0.09)` (was
+  `color-mix(in srgb, #e5e5e5 65%, transparent)`) — visibly darker on light, tracks a non-default
+  `neutral`/`lightLevel` where the old hex did not, and never flips polarity at `lightLevel <= -3`
+  the way the fixed hex did. Dark moved too: `color-mix(in srgb, #ffffff 6%, transparent)` →
+  `rgba(255, 255, 255, 0.08)`.
+- **The header's horizontal inset moved from `md` to `sm`**, so the breadcrumb's left edge and the
+  global actions' right edge land on the card column's edges. The sidebar brand row and the aside's
+  header now sit at the SAME `appShellHeaderHeight` band, so their centrelines meet the header's
+  across the seams. `SPACE_STEP.sidebarBrandInsetTop` / `--vx-space-sidebar-brand-inset-top` are
+  deleted with no replacement — the row IS the band now, not an inset inside it.
+  `PageAside`'s title renders the head-font `--vx-text-md`/550/ink title treatment, not the old mono
+  micro-label.
+- **[S2] `PageBar` row 2 below `sm`** is two declared lines — the tabs, then the pill row — instead
+  of one overflowing `nowrap` line. `--basalt-page-bar-h` grows to match, and the `className` JSDoc
+  no longer suggests drawing a hairline under the bar.
+- **[S3] `DeltaBadge.polarity` and `deltaPolarity`** on `WidgetHeader`/`StatCard`/`ChartCard` —
+  `'up-good'` (default, today's tone), `'up-bad'`, `'neutral'`. And `WidgetHeader tier="group"` — a
+  `Section` mounted inside `PageAside` now resolves it automatically and renders a mono micro-label
+  `h3` with a zero-gap row body; outside an aside nothing changes.
+- **[S4] `AxisConfig.scale: 'log'`** on `CartesianChart` — 1-2-5 mantissa ticks, `autoMinCeil`
+  ignored on a log axis. Honoured by every kind whose domain isn't anchored at zero (`MultiLine`,
+  `ZonedLine`, un-stacked `Bars`); `StackedArea` and stacked `Bars` install a domain function with a
+  hard `0` floor and their marks anchor at the baseline, so a log scale on either yields `NaN`
+  geometry — don't opt in there. Additive; omitted stays linear.
+
 ### Stores — the `custom` flag, patched writes, lazy fallbacks, derived windows
 
 **Additive, except one type that got narrower on purpose.** `field.range({ presets, fallback })`
@@ -262,7 +706,7 @@ renders in a tiered slot, and keying the exemption on a single owner made the ve
 attribute came later in the file.
 
 **`basalt/control-outside-home` and `raw-selection-control` did NOT promote. They are re-dated to
-1.28.0, and the reason is a measurement rather than caution:** the wave-7 consumer run left 9 warns
+1.30.0, and the reason is a measurement rather than caution:** the wave-7 consumer run left 9 warns
 in argo, and every one is a control inside a modal/form module whose `<Modal>` is rendered by the
 PARENT route — law C1's cross-file case, which is advisory by declaration because no scan of one
 file can see it. Both lanes now exempt a file whose BASENAME matches
@@ -286,6 +730,155 @@ half is deliberately NOT exempted the same way — a local `StatCard` beside an
 `import { StatCard as Base }` kept the name AND a piece of the original, which is the fork shape this
 rule most wants to see.
 
+### `basalt-ui/data` — a typed facet id, and a required `getItemKey`
+
+**`BasaltDataTable`: a mistyped `facets[].columnId` used to render no pill, silently — `if
+(!column) return null`.** It now throws in dev, naming the id and every known column id
+(`facet columnId "…" matches no column`); production still degrades to no pill for that one facet.
+`DataTableFacet` also gained a type parameter — `DataTableFacet<T = unknown>` — so `columnId` is
+typed off the row shape wherever TanStack's `accessor`/manual `id` inference allows it
+(`Extract<keyof T, string> | (string & {})`); the default keeps a bare `DataTableFacet[]`
+compiling unchanged. `BasaltDataTableProps.facets` is now `DataTableFacet<T>[]`, and
+`initialColumnPinning` moved from TanStack's own `ColumnPinningState` to a new, `T`-derived
+`DataTableColumnPinning<T>` (structurally assignable to `ColumnPinningState`, so no cast is
+needed at either end). Both are additive for existing call sites — an id that was already a real
+column keeps compiling and rendering exactly as before.
+
+**`BasaltVirtualList.getItemKey` is now required.** The index fallback hid stale rows across a
+mutation: an insert/delete shifts every index below it, so the OLD item kept rendering at each
+shifted index until an unrelated re-render happened to catch it up — in the one component whose
+job is a long mutable list. Pass a real per-item key (`(item) => item.id`); there is no
+replacement for the index fallback.
+
+**`BasaltVirtualList` gained a ref.** `ref?: Ref<BasaltVirtualListHandle>` exposes
+`scrollToIndex`/`scrollToOffset`/`scrollToEnd` (delegating to the internal
+`@tanstack/react-virtual` instance) plus `getVirtualizer()` as the full escape hatch — mirrors
+`./data/table`'s `useReactTable` re-export as the table's own. Additive; omitting `ref` changes
+nothing.
+
+### `basalt-ui/commands` — `BasaltOverlays` no longer WRAPS your app in `ModalsProvider`
+
+**Same props, same imperative API, one structural change: every layer — `ModalsProvider`
+included — now renders as a SIBLING of `children` instead of an ancestor.** The old shape put the
+whole app under a `React.lazy` Suspense boundary (`<Suspense fallback={<>{app}</>}>
+<LazyModalsProvider>{app}</LazyModalsProvider></Suspense>`), and `React.lazy` suspends on its first
+render even when the module is already warm. Two consequences, both real: the app's FIRST COMMIT was
+deferred past a microtask — long enough for TanStack Router's async `loadMatches` to `setState` onto
+a not-yet-mounted fiber ("Can't perform a React state update on a component that hasn't mounted
+yet", once per full page load) — and the app tree mounted TWICE, once inside the fallback and once
+resolved, so every effect in the app ran twice on boot.
+
+Nothing to change for the overlay APIs. `modals.open` / `modals.openConfirmModal` (and so basalt's
+own `overlays.open` / `overlays.close`) go through `@mantine/modals`' window CustomEvent bus, which
+`ModalsProvider` subscribes to — being inside it was never a requirement, and the provider renders
+its own managed `Modal` regardless of where it sits.
+
+**The one thing a sibling cannot serve is React CONTEXT**: `useModals()` from `@mantine/modals`
+called inside your app now throws its "was called outside of context" error. If you use it (or
+`openContextModal`, which needs the provider's `modals` map that `BasaltOverlays` never passed
+anyway), mount your own provider and turn basalt's off — two providers would both answer the event
+bus and open every modal twice:
+
+```tsx
+<BasaltOverlays modals={false}>
+  <ModalsProvider modals={CONTEXT_MODALS}>
+    <App />
+  </ModalsProvider>
+</BasaltOverlays>
+```
+
+### `basalt-ui/controls` — the mobile `Filters (n)` sheet renders panel rows, not its own list
+
+**The sheet's `SheetOptionList` (44px rows, a hairline between them, one per option) is gone.**
+`useFilterSurface() === 'sheet'` now resolves to the SAME `PanelRow`/`PanelChoice`/facet-list body
+`'panel'` already renders (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a Drawer") — label
+above, full-width control below, folding past `PANEL_TRACK_MAX` (3, a `Select`) or `max` (a
+`MultiSelectFilter`'s `Show N more`) the same way the aside already did. A set with many options no
+longer grows the sheet to a full column of option rows. `RangeFilter`'s sheet form is the panel's one
+`Select` (presets plus a `Custom range…` row revealing the injected picker) instead of a
+`SheetOptionList` with the picker behind a separate disclosure row.
+
+Also fixed in the same pass: a `fullWidth` `SegmentedControl` (`PanelChoice`'s ≤3-option form, and
+`ViewTabs`) now splits its options EVENLY — Mantine's own `.control` carries no `min-width`
+override, so the initial `auto` floored each option at its content width and a `fullWidth` track
+split unevenly; a long label now ellipsizes inside its equal share instead of forcing the column
+wide. The active segment's fill is a second ink-mix step
+(`color-mix(in srgb, var(--vx-ink) 12%, var(--vx-surface-panel))`), not a flat `--vx-surface-panel`,
+so it stays visible against its own track when the whole control sits on a panel-coloured surface (a
+`PanelRow`), where a flat panel fill read as barely-there next to the 6%-tinted track around it.
+
+| Removed                                                                                                                      | Replacement                                                 | Note                                                                                                                                                                                                                                                                                                                                           |
+| ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SheetOptionList`, `SheetField`, `SheetDisclosure` (`basalt-ui/controls`)                                                    | `PanelRow` / `PanelChoice` (already exported)               | Were never part of the public `./controls` barrel — internal to `filter-sheet.tsx` — so this only breaks a consumer test that imported them directly out of `basalt-ui/controls/filter-sheet` or hooked a `role="radio"` `<fieldset>` DOM shape inside the sheet (now a `PanelChoice` `SegmentedControl`, `role="radiogroup"`, or a `Select`). |
+| `SheetRow`, `sheetRowClassNames` (`basalt-ui/controls`)                                                                      | none                                                        | Also internal-only. `ToggleFilter`'s sheet form is now a `PanelRow` whose `Switch` rides the label line, the same shape the panel surface always used.                                                                                                                                                                                         |
+| `.sheetOption` / `.sheetList` / `.sheetField` / `.sheetRow` / `.sheetDisclosureBody` / `.sheetLabel` (`controls.module.css`) | `panel-row.module.css`'s `.row`/`.head`/`.control`/`.label` | CSS-module classes were never a public contract; named for a consumer that vendored a copy of the sheet's old CSS.                                                                                                                                                                                                                             |
+
+### The shell scrollport — Main scrolls, not the window
+
+`BasaltShell` dropped Mantine's `layout="alt"` (the header now spans the full viewport width, above
+the sidebar and the aside, instead of being inset beside the sidebar) and gave `AppShell.Main` a
+bounded height with `overflow: auto`. Main is therefore THE scrolling element: the document's
+`scrollHeight` equals the viewport height, the browser scrollbar sits on Main's own right edge
+(inside the aside, where the content is) instead of at the far edge of the window, and
+`window.scrollY` is pinned at 0.
+
+Main carries two handles: `data-basalt-scrollport` (basalt's own, and what `scrollParentOf` looks
+for) and `data-scroll-restoration-id="basalt-main"` (the attribute `@tanstack/router-core`'s scroll
+restoration reads, so a router-driven app restores this element rather than the window).
+
+What to change in a consumer:
+
+| If your app…                                                        | Do this                                                                                                                                                                                                     |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| reads `window.scrollY` / listens for `scroll` on `window`           | `const port = scrollParentOf(el)` and read `port.scrollTop` / listen on `port` — `null` still means the window, so shell-less code is unchanged                                                             |
+| scrolls with `window.scrollTo` / `document.scrollingElement`        | target `document.querySelector('[data-basalt-scrollport]')` first, with the document as the fallback                                                                                                        |
+| uses window-based scroll restoration                                | point it at `[data-scroll-restoration-id="basalt-main"]`; TanStack Router picks it up with no config                                                                                                        |
+| overrides `--vx-space-sticky-header-clearance`                      | the token NO LONGER includes the app-shell header height — it is `anchors.stackMd` (12px at level 0), pure breathing room, because BOTH the header and the page-bar band are regions outside the scrollport |
+| passes `BasaltDataTable stickyHeaderOffset` inside a shell          | drop it entirely. Nothing overhangs the scrollport any more, so a sticky table head wants `top: 0`, which is the default                                                                                    |
+| computes a viewport-filling body from `--basalt-page-bar-h`         | inside a shell that is just `100%` now — the band is outside Main rather than scrolling with it. The var is still published                                                                                 |
+| passes `mobileNav.getScrollElement` only to reach the page scroller | you can drop it — the default resolves the scrollport now                                                                                                                                                   |
+
+Three rendering changes ride along, all visible without any code change:
+
+- **The brand moved out of the sidebar and into the header.** The header spans the full viewport
+  width now, so the sidebar's `appShellHeaderHeight` brand row painted as a SECOND 48px band under
+  the header seam. It is the header's leading zone instead — `--app-shell-navbar-offset` wide, so it
+  still tracks the rail collapse and still ends on the sidebar\|main seam — and the sidebar column
+  starts at `SidebarSearch`. `brand`, `brand.menu` and the collapse toggle are unchanged; only the
+  markup's home moved. Two consequences for a consumer mounting `AppSidebar` DIRECTLY (rather than
+  through `BasaltShell`, which is the supported path): it no longer paints a brand row, and its
+  `onToggleCollapse` prop is no longer read there — `BasaltShell` feeds it to the header instead.
+- **`PageBar` row 2 is a shell-owned BAND**, not a row in the page: it portals into an outlet
+  `BasaltShell` renders between the header and the scrollport, exactly as row 1 portals into the
+  header. It spans Main's width, carries `--vx-surface-bg` and one `--vx-divider` hairline, and is a
+  zero-height, seam-less box on a route with no `PageBar`. It is no longer sticky and no longer
+  depends on where you wrote `<PageBar>` — nested in a `Stack` or written as Main's direct child now
+  produce identical geometry. Its padding-block tightened from `--vx-space-stack-sm` to
+  `--vx-space-stack-xs`, so the bar is 8px shorter.
+- **`BasaltDataTable` contains itself horizontally by default.** A table with neither `maxHeight`
+  nor `minWidth` used to render a bare `<table>`, which sizes to its own min-content — a five-column
+  table measured 448px inside a 390px viewport and dragged the whole page sideways. Every table now
+  renders inside `Table.ScrollContainer type="native"` (`minWidth: 0` when you set none), so a wide
+  table scrolls inside its own card. `stickyHeader` with neither prop cannot take that container —
+  an `overflow-x` box computes `overflow-y` to `auto` and becomes the header's scrollport, and with
+  no height cap it has no scroll range, so the header would go inert — so it takes a wrapper whose
+  overflow is **measured** instead: while the table fits its container the wrapper declares no
+  overflow at all and the page-sticky header sticks exactly as before; once the table is wider the
+  wrapper flips to `overflow-x: auto`, the columns stay reachable, and the header is inert at that
+  width. The flip is a live `ResizeObserver` reading in both directions, so the wrapper goes back to
+  bare when the space returns (the window widened, the sidebar collapsed, the aside closed), and it
+  publishes `data-contained="true|false"`. The dev warning on that shape now states the trade rather
+  than a defect and points at `maxHeight` for a table that must both scroll and stick. Pinning takes
+  the same wrapper: the `overflow-x: auto` `Box` a pinned, uncapped, sticky table used to get is
+  gone, because it was the inert-header shape it was meant to avoid. **The TOOLBAR was the other
+  half of the same defect and is fixed with it**: the toolbar `Group` is the header row's flex item
+  (`CtlSlot` between them is `display: contents`) and carried `flex: 0 0 auto`, so a 220px search
+  beside a 230px facet pill row was an unshrinkable 461px box in a 302px column — `AppShell.Main`
+  measured `scrollWidth` 505 against `clientWidth` 390 at 390x844. It is now `flex: 0 1 auto` with
+  `min-width: 0`, and the search's `w={220}` became a flex BASIS (`flex: 0 1 220px`, floored at
+  `12ch`, capped at `100%`). The field still resolves to 220px wherever 220 fits and still never
+  grows with the table; below that the search and the pills wrap onto their own lines.
+
 ## 1.26.0 — the control tier, the page bar and the store
 
 **One export removed and two deprecated — see § Stores below; two shell PROPS removed — see
@@ -305,7 +898,7 @@ happened to the nine rows below.
 (`shadow-basalt-export`). Both ledgers now hold only the wave-6 control guards listed under
 § Guards — six plugin rules and two guard kinds, each `{ since: '1.26.0', promote: '1.27.0' }` —
 which the C16 gate forced to promote or be deleted at 1.27.0. Five rules and one kind promoted there;
-the C1 pair was re-dated to 1.28.0 against a measurement (see `## Unreleased` above). A theme-allow escape written against
+the C1 pair was re-dated to 1.30.0 against a measurement (see `## Unreleased` above). A theme-allow escape written against
 any of these still works unchanged; only the SEVERITY of an unwaived finding moves from `warn` to
 `error`.
 
@@ -616,21 +1209,21 @@ A consumer that uses `DateRangePicker` installs `@mantine/dates` and imports
 
 **Nothing removed. Eight new oxlint rules and two new guard kinds. `Ships` below is the level as of
 THIS minor** — eight land `error`, and the C1 pair (`control-outside-home` and its text lane) is the
-only grace left, re-dated to 1.28.0 on a measurement (see § Guards — the promotions).\*\* Every one honours `theme-allow <id> — <why>` on the
+only grace left, re-dated to 1.30.0 on a measurement (see § Guards — the promotions).\*\* Every one honours `theme-allow <id> — <why>` on the
 node and `theme-allow-file <id> — <why>` on the file, the same grammar as the rest.
 
-| Rule / kind                          | Fires on                                                                                                                                                                                                                               | Ships         |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `basalt/hand-rolled-filter`          | A raw Mantine `Select`/`SegmentedControl`/… handed to a TIERED home slot (`actions`/`filters`/`tabs`/`sync`/`filtersEnd` on `PageBar`/`Section`/`WidgetHeader`/`ChartCard`/`StatCard`/`BasaltDataTable`/`SettingsSection`/`FilterSet`) | error         |
-| `basalt/page-bar-budget`             | A second `PageBar` in the SAME returned tree, >4 `actions.secondary`, >3 `Section` actions, a second filled `Button`/`ActionIcon` in one slot (outside an overlay)                                                                     | error         |
-| `basalt/control-outside-home`        | The same raw control with no home at all — exempt under a settings row / overlay / composer, in an `@mantine/form` file, in a file that DEFINES a basalt control, or in a file basenamed `*-{modal,drawer,popover,panel,form}.tsx`     | warn → 1.28.0 |
-| `basalt/control-size-literal`        | `size`/`w`/`fullWidth`/`visibleFrom`/`hiddenFrom` on anything inside a home slot (the slot sets the tier)                                                                                                                              | **error**     |
-| `basalt/in-body-page-title`          | `<Title order={1\|2}>` outside prose/overlay context and outside a `content/` path                                                                                                                                                     | **error**     |
-| `basalt/responsive-twin`             | The same control mounted twice, one `visibleFrom="X"` and one `hiddenFrom="X"`                                                                                                                                                         | **error**     |
-| `basalt/search-literal-link`         | A `search:` object literal in a `linkOptions()` inside `defineNav()`/`navGroup()`                                                                                                                                                      | **error**     |
-| `basalt/use-search-from-literal`     | `useSearch({ from: '<route>' })`                                                                                                                                                                                                       | **error**     |
-| `in-body-page-title` (guard kind)    | The text lane of the same law — SAME id, so one annotation waives both lanes                                                                                                                                                           | **error**     |
-| `raw-selection-control` (guard kind) | The text lane of `control-outside-home`, approximated by a 12-line host-tag window, plus the same overlay-basename exemption                                                                                                           | warn → 1.28.0 |
+| Rule / kind                          | Fires on                                                                                                                                                                                                                                                                                                           | Ships         |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
+| `basalt/hand-rolled-filter`          | A raw Mantine `Select`/`SegmentedControl`/… handed to a TIERED home slot (`actions`/`filters`/`tabs`/`sync`/`filtersEnd` on `PageBar`/`Section`/`WidgetHeader`/`ChartCard`/`StatCard`/`BasaltDataTable`/`SettingsSection`/`FilterSet`)                                                                             | error         |
+| `basalt/page-bar-budget`             | A second `PageBar` in the SAME returned tree, >4 `actions.secondary`, >3 `Section` actions, a second filled `Button`/`ActionIcon` in one slot (outside an overlay)                                                                                                                                                 | error         |
+| `basalt/control-outside-home`        | The same raw control with no home at all — exempt under a settings row / overlay / composer, in an `@mantine/form` file, in a file that DEFINES a basalt control (and imports no `basalt-ui`), or in a file basenamed `*-{modal,drawer,popover,panel,form}.tsx` / `<Subject>{Modal,Drawer,Popover,Panel,Form}.tsx` | warn → 1.30.0 |
+| `basalt/control-size-literal`        | `size`/`w`/`fullWidth`/`visibleFrom`/`hiddenFrom` on anything inside a home slot (the slot sets the tier)                                                                                                                                                                                                          | **error**     |
+| `basalt/in-body-page-title`          | `<Title order={1\|2}>` outside prose/overlay context and outside a `content/` path                                                                                                                                                                                                                                 | **error**     |
+| `basalt/responsive-twin`             | The same control mounted twice, one `visibleFrom="X"` and one `hiddenFrom="X"`                                                                                                                                                                                                                                     | **error**     |
+| `basalt/search-literal-link`         | A `search:` object literal in a `linkOptions()` inside `defineNav()`/`navGroup()`                                                                                                                                                                                                                                  | **error**     |
+| `basalt/use-search-from-literal`     | `useSearch({ from: '<route>' })`                                                                                                                                                                                                                                                                                   | **error**     |
+| `in-body-page-title` (guard kind)    | The text lane of the same law — SAME id, so one annotation waives both lanes                                                                                                                                                                                                                                       | **error**     |
+| `raw-selection-control` (guard kind) | The text lane of `control-outside-home`, approximated by a 12-line host-tag window, plus the same overlay-basename exemption                                                                                                                                                                                       | warn → 1.30.0 |
 
 **A `SettingsRow`'s `control` is not a tiered slot, so nothing in this table fires inside one.**
 It is law C1's third home — the form row — and a form keeps Mantine's `md` tier
@@ -1488,8 +2081,8 @@ deleting an entry forces the level flip in the same commit.
 | `basalt/responsive-twin`               | 1.26.0 as `warn` | **1.27.0**                                                                                  |
 | `basalt/search-literal-link`           | 1.26.0 as `warn` | **1.27.0**                                                                                  |
 | `basalt/use-search-from-literal`       | 1.26.0 as `warn` | **1.27.0**                                                                                  |
-| `basalt/control-outside-home`          | 1.26.0 as `warn` | still `warn`, `promote: '1.28.0'` — re-dated on 9 measured cross-file overlay warns in argo |
-| `raw-selection-control` (guard kind)   | 1.26.0 as `warn` | still `warn`, `promote: '1.28.0'` — the text lane of the row above                          |
+| `basalt/control-outside-home`          | 1.26.0 as `warn` | still `warn`, `promote: '1.30.0'` — re-dated on 9 measured cross-file overlay warns in argo |
+| `raw-selection-control` (guard kind)   | 1.26.0 as `warn` | still `warn`, `promote: '1.30.0'` — the text lane of the row above                          |
 
 `card-with-border`, `inline-display`, `raw-html-layout`, `raw-form-control`, `raw-font-family` and
 the other original guard kinds have been `error` since before 1.2.0 — they never had a grace minor.