basalt-ui 1.26.0 → 1.28.0

package/MIGRATING.md

@@ -32,6 +32,855 @@ at 1.3.0, `./agent-chat` at 1.10.0.
 
 ## Unreleased
 
+**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 })`
+written INLINE inside `createSearchStore({ fields })` used to infer `custom` as `boolean` — the
+contextual `AnyField` return type won over the argument — so every value and search type carried a
+`'custom'` preset the field itself rejects at runtime, and `RangeFilter field={…}` needed a cast or
+an explicit `custom: false`. `field.range` is now three overloads: an omitted or `false` flag is
+`false`, a literal `true` is `true`, a value typed `boolean` stays widened.
+
+- **Delete the workaround, not the field.** An explicit `custom: false` still works (same
+  overload); a cast on `<RangeFilter field={…} />` can go, and `RangeFilterProps<P, C>` is generic
+  over the flag so a preset-only handle binds directly.
+- **What can newly type-error:** code that read `'custom'` out of a range whose field never declared
+  it — `if (search.range === 'custom')` on a preset-only field, or a `RangeValue<P | 'custom'>`
+  annotation over one. That branch was always dead at runtime; the type just stopped pretending.
+- **…and one more, in a consumer's own WRAPPER.** A prop typed `FieldHandle<RangeField<P>>` — `C`
+  defaulting to `boolean` — no longer accepts a handle from a `field.range` without `custom: true`,
+  because that handle's setter is now `RangeValue<P>`-typed and a setter is contravariant. Pin
+  `FieldHandle<RangeField<P, false>>` for the preset-only shape, `RangeField<P, true>` for a
+  picker-backed one, or make the wrapper generic over the flag
+  (`<P extends string, C extends boolean>` + `FieldHandle<RangeField<P, C>>`), which is what
+  `RangeFilter` does. An existing `as FieldHandle<RangeField<P>>` cast keeps compiling.
+
+**`toWindow()` resolves derived presets.** `field.range({ window: { '3m': (now) => ({ from, to }) } })`
+makes `toWindow({ preset: '3m' })` return `{ from, to }` (ISO dates, resolved at call time with the
+current `Date`) while `3m` stays one preset in the URL. A preset with no resolver keeps
+`{ window: preset }`, in the same field — which is what retires the last hand-rolled
+`presetToParams` a consumer kept beside the store for `3m` / `6m` / `1y` / `ytd`.
+
+**The resolved presets are gone from the return TYPE too**, which is the half that decides whether
+the switch is deleted or the cast just moves: the field now carries its resolver keys (`RangeField`'s
+fifth type parameter, inferred from `window`), and `toWindow` returns
+`{ window: Exclude<P, W> } | { from; to }`. A `resolveWindow` whose target is
+`{ window: '7d' | '30d' | '90d' | 'all' } | { from; to }` becomes a one-line delegation with no
+`as`. One guard survives on a `custom: true` field: a `'custom'` preset that arrives WITHOUT dates
+resolves to `{ window: 'custom' }`, so `'custom'` stays in the union by construction.
+
+**A field setter takes an optional second argument.** `set(next, { patch })` merges extra search
+params into the SAME navigate — URL lane only, for keys the store does not own (`{ patch: {
+detailDate: undefined } }` clears a sibling param the page put there). The field's own params always
+win over the patch, so it cannot corrupt the value being set. A local/memory-lane write has no
+navigate to merge into and ignores it.
+
+Two limits are now enforced rather than documented. A patch key **another field of the same store
+owns** is refused — it would reach the URL while the store's own write path never touched the mirror,
+so the next paramless visit and every `linkSearch` link resolve the OLD value: `createSearchStore`
+throws in dev, and in production keeps the write and logs it once. Write that field through its own
+setter instead. And a patched write **from a route that does not validate the field** persists (A1)
+but drops the patch with it — there is no navigate to merge into — which now warns once per field in
+dev instead of doing nothing.
+
+**A fallback may be a thunk.** `field.*({ fallback: () => T })` (every kind — `field.number`'s codec
+froze its thunk at store definition in the first cut of this minor and does not now) is resolved at
+READ time and re-resolved while nothing is written, and is never persisted on its own — a write
+stores what the control produced, as before. **Local and memory lanes only:** `createSearchStore` now
+THROWS at definition for a thunk on a URL-lane field, because `validateSearch` would evaluate it on
+every navigation and pin the result into the URL. Move the field off the URL lane (`{ url: false }`,
+or `createLocalStore`) or pass a value.
+
+**`FieldHandle` gained `clear()`, and a reset now UNSETS.** `useReset()` used to write
+`entry.codec.fallback` into the mirror for every persisted field, and every control's reset called
+`setValue(field.fallback)` — both of which pin a RESOLVED thunk: pressing `Reset all` over
+`field.string({ fallback: () => todayIso() }, { url: false })` stored today's date, so tomorrow the
+field read a value nobody chose and counted as active in `Filters (n)`. Both paths now delete the
+key instead (the memory lane always did), and `clear()` is the per-field door: the persist lane
+deletes its key, the memory lane drops its value, the URL lane navigates back to the fallback
+params.
+
+Nothing to change at a call site — every shipped control's reset calls it. A consumer that
+hand-rolled a reset should swap `setValue(field.fallback)` for `field.clear()`; a hand-built
+`FieldHandle` (a facet column, a test double) must add the member, which is the one type-error this
+adds.
+
+**`createPersistedState` notifies across instances (bug fix).** Two instances over one key — a
+page's store and a widget's own state naming the same key, or a store re-exported from two modules —
+kept per-instance listener sets, so a write through one left the other's components rendering the
+stale value **in the same tab** while the cross-tab `storage` path worked. Subscribers are now
+registered per storage key. No API change; if you were re-rendering something by hand to work around
+this, delete it.
+
+**`RangeFilter` warns once in dev** when the field declares `custom: true` and no `customPicker` was
+injected: the custom window is then unreachable (no popover picker, no `Custom range…` row in the
+sheet). Preset-only remains a legal configuration — the picker is injected precisely because
+`@mantine/dates` may be absent — so this is a warning, not a type error.
+
+### Controls — `NumberFilter`, the `field.number` lane
+
+**One export added, nothing removed.** `field.number` has existed since the store landed and had no
+control, so both consumers that needed one wrote around it in opposite directions: linewatch kept a
+raw `SegmentedControl` over `minDuration` (a `control-outside-home` warn, law C1), and argo widened
+`nights` into a string enum — which puts `'3'` in the URL and makes every downstream comparison a
+parse.
+
+```tsx
+import { NumberFilter } from 'basalt-ui/controls'
+
+// A preset set — a pill plus a radio list, the same body every enum filter renders.
+<NumberFilter field={booking.field.nights} label="Nights"
+  options={[{ value: 1, label: '1 night' }, { value: 7, label: 'A week' }]} />
+
+// No `options` → a pill whose popover holds a `ctl` NumberInput; the sheet renders it full-width.
+<NumberFilter field={lines.field.minDuration} label="Min duration" step={30} />
+```
+
+Three properties worth knowing before porting a call site:
+
+- **The URL keeps a NUMBER.** `options` takes `{ value: number; label: string }`, and a numeral
+  STRING there is a type error — the whole reason to stop widening a threshold into an enum.
+- **The stepper applies on blur or Enter, never per keystroke.** A number is typed digit by digit, so
+  a live write would navigate on `4`, `42`, `420` — three loader runs for one intended threshold,
+  two of them values nobody meant. `SearchFilter` debounces; a number has an explicit commit point.
+- **`min`/`max`/`int` come off the HANDLE, not the call site.** They are deliberately not props: the
+  field is what validates the URL, and a second copy at the call site is a second answer to the same
+  question. The number handle republishes all three (see § Stores — the number handle below), so the
+  stepper stops at the field's limit and an `int` field refuses decimals outright. A TYPED value is
+  clamped to those bounds when it commits, so the box reads what the store holds even when the store
+  does not move — a second out-of-range `9999` against `max: 600` over a stored `600` writes nothing,
+  and the readout still corrects itself to `600`. The codec's clamp stays the backstop for a value
+  that never came through the box at all — a hand-typed URL, a stale deep link.
+
+### Stores — the number handle republishes its bounds
+
+**Three members added to `FieldHandle<NumberField>`, nothing removed.** `min`, `max` and `int` now
+sit on the handle, filled from the field declaration (`NumberHandleExtras`, the shape
+`RangeHandleExtras`/`toWindow` already had). A control never sees the field descriptor — only the
+handle — so before this the only way one could learn its own limits was for the call site to pass
+them a second time.
+
+```ts
+const nights = store.field.nights // field.number({ fallback: 2, min: 1, max: 14, int: true })
+nights.min // 1        — `undefined` when the field declared none
+nights.max // 14
+nights.int // true     — `false`, never `undefined`, on a number handle
+```
+
+Non-number handles carry all three as `undefined`, the same way `toWindow` is `undefined` off a
+range handle. That is a type-level fact, not just a runtime one, and it matters for one collision in
+particular: `StringField` has its own `max`, which is NOT republished — a string handle's `max` is
+`undefined`.
+
+Nothing about the clamp changed. The codec has always clamped a number to the declared bounds on
+write, and still does; the handle is a readout of that law, which is what lets `NumberFilter` bound
+its stepper instead of letting the user watch the correction happen.
+
+### `StatCard` — `unit`, `breakdown` and the delta's own format
+
+**Four props added, nothing removed or renamed; every one defaults to today's rendering when
+omitted.**
+`value` is a pre-formatted `string`, so a card had exactly one text channel under the hero row
+(`subtitle`) and three consumers wanting a unit AND a basis AND a split hand-rolled the card instead
+— which is the fork `shadow-basalt-export` reports as a `HeroCard`.
+
+| Prop          | Type                                                               | Renders                                                                       |
+| ------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `unit`        | `string`                                                           | after the value on the hero row — muted, mono, `--vx-text-sm`                 |
+| `breakdown`   | `readonly { label: string; value: string; tone?: StatCardTone }[]` | compact rows under the hero, one `controlHeightTag` line each                 |
+| `deltaFormat` | `(delta: number) => string`                                        | the delta chip's label. Default unchanged: `Math.abs(delta).toFixed(1) + '%'` |
+| `deltaGlyph`  | `boolean`                                                          | the chip's ▲/▼. Default `true`; a zero delta never shows one                  |
+
+`unit` is forwarded to `WidgetHeader`, which gained the same prop, so `ChartCard` and `Section`
+headers get it too. It is NOT the basis: `412` + `TSS` is the pair, and `7-day rolling` is still
+`subtitle`. A thousands separator, a currency symbol or a `%` still belong in `value`.
+
+`breakdown` draws **no hairlines** — §2.1 puts a horizontal rule between OPTION rows and nowhere
+else, and `theme/divider-law.test.ts` inventories every one basalt draws. The rows separate by
+weight (muted label, mono ink value) instead. Keep it to two or three: past that the card is a
+table, and a table is `BasaltDataTable` in a `Section`. A row's `tone` reads the same per-scheme
+`--vx-status-*` solid the card's own rail does, and omitting it is untinted, never `'good'`.
+
+`deltaFormat` exists because **a delta is not always a percentage, and `StatCard` claimed it was**:
+`delta={0.3}` on a pace or speed card rendered `▲0.3%`, a wrong unit on a KPI — worse than no chip —
+so the one consumer that needed it kept the card hand-rolled and took the `shadow-basalt-export` warn
+instead. `DeltaBadge` had `format` all along; neither `WidgetHeader` nor `StatCard` forwarded it. Both now do.
+`ChartCard`/`Section` are unchanged: each declares its own header props and forwards them one by
+one, so a delta-bearing `ChartCard` or `Section` still prints the percentage — ask if you need it
+there.
+
+```tsx
+// A percentage, unchanged — no prop, no move.
+<StatCard title="Volume" value="1,204" delta={4.2} deltaPeriod="WoW" />
+
+// An absolute delta. The formatter gets the SIGNED number, so it may print the sign itself;
+// `deltaGlyph={false}` then stops the ▼ saying the same thing twice. No `deltaLabel` prop exists —
+// the function IS the escape hatch, and `delta` stays the number that drives the tone.
+<StatCard title="Pace" value="5:31" unit="/km" delta={-12} deltaGlyph={false}
+  deltaFormat={(s) => `${s < 0 ? '−' : '+'}0:${String(Math.abs(s)).padStart(2, '0')} /km`} />
+```
+
+### Guards — the 1.27.0 promotions, one narrowing and one new exemption
+
+**Five plugin rules and one guard kind became `error` in the shipped preset.** Their
+`PLUGIN_RULE_GRACE` / `GRACE_PERIOD_KINDS` entries are deleted, which IS the promotion (C16). A
+`theme-allow` written against any of them still works unchanged; only the severity of an UNWAIVED
+finding moves.
+
+| Promoted to `error`              | Waiver, if the finding is deliberate                                                          |
+| -------------------------------- | --------------------------------------------------------------------------------------------- |
+| `basalt/control-size-literal`    | `theme-allow control-size-literal — <why>` above the node, or `theme-allow-file` for the file |
+| `basalt/in-body-page-title`      | `theme-allow in-body-page-title — <why>` — ONE id, so it waives the guard kind's lane too     |
+| `in-body-page-title` (kind)      | the same annotation; the two lanes share the id by construction                               |
+| `basalt/responsive-twin`         | `theme-allow responsive-twin — <why>`; the real fix is deleting one mount                     |
+| `basalt/search-literal-link`     | `theme-allow search-literal-link — <why>`; the real fix is `search: <store>.linkSearch`       |
+| `basalt/use-search-from-literal` | `theme-allow use-search-from-literal — <why>`; the real fix is the param as a prop            |
+
+The commonest in-body-title case that is NOT a defect: **a shell-less surface naming itself** — an
+auth gate, an error boundary, a print view. There is no breadcrumb to carry the name, so write
+`theme-allow in-body-page-title — shell-less surface`.
+
+**`control-size-literal` also gained one exemption in the same minor, and it removes a waiver rather
+than adding one: a slot owned by `ChartCard` no longer reports.** `ChartCard` lives inside the
+Mantine-free chart layer, so its `actions` slot writes `data-basalt-tier` by hand and cannot mount
+the tier theme at all — a `Switch` there with no `size` renders at Mantine's default, not at `ctl`.
+The rule's message ("the HOME sets the tier, drop the prop") was simply false in that one slot, and
+because the rule fires on the `size` ATTRIBUTE it could not tell a correct `size="ctl"` from the
+`size="xs"` it exists to catch. Every other home still reports, and the owner test reads the
+IMPORTED name so `ChartCard as Card` is exempt too. `hand-rolled-filter` is deliberately NOT
+exempted there: a raw `Select` in `ChartCard.actions` is still a filter that should take a `field`.
+A HOISTED binding is exempt only when EVERY basalt home it was handed to is `ChartCard` — one
+`const acts = <Button size="xs"/>` given to both `<ChartCard actions>` and `<Section actions>` still
+renders in a tiered slot, and keying the exemption on a single owner made the verdict depend on which
+attribute came later in the file.
+
+**`basalt/control-outside-home` and `raw-selection-control` did NOT promote. They are re-dated to
+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
+`*-{modal,drawer,popover,panel,form}.tsx`, which is the convention those nine already follow.
+Outside the convention, an overlay body declares itself:
+`theme-allow-file control-outside-home — overlay`. The trade is stated plainly: a whole file goes
+unscanned on a naming convention, so a `Select` that genuinely belongs in a page bar goes unreported
+if it lives in `filters-panel.tsx` — the same bargain the `@mantine/form` exemption already buys,
+and a smaller one than promoting a rule with 9 known false positives.
+
+**`basalt/shadow-basalt-export` narrowed, and it stays a permanent advisory `warn`.** An ALIAS hit is
+now skipped when the file imports the basalt export it renames **and REFERENCES that binding as a
+value**: a `HeroCard` that composes `StatCard` is a wrapper, not a fork, and it was already following
+the advice the message gives. Composition, not import — three shapes stay reported, and they are the
+ones a fork actually writes: a type-only `import type { StatCard }` (or an inline `type` specifier)
+feeding `ComponentProps<typeof StatCard>`, a VALUE import used only in a type position, and a dead
+import left behind after the body was re-rolled. None of them render anything. A reference does not
+have to be a JSX tag — `component={StatCard}` and `createElement(StatCard)` compose it too. The
+provenance test reads the IMPORTED name, so `import { StatCard as Base }` counts. The name-COLLISION
+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
 § Sidebar. Two other behaviour changes: the grace ledgers changed shape, and nine
 long-stale entries (D4, `docs/archive/CONTROLS-SYNTHESIS.md`) are promoted.** C16
@@ -48,7 +897,8 @@ happened to the nine rows below.
 (the table below) or moved to the new, permanent `PLUGIN_RULE_ADVISORY` ledger
 (`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 forces to promote or be deleted at 1.27.0. A theme-allow escape written against
+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.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`.
 
@@ -357,22 +1207,23 @@ A consumer that uses `DateRangePicker` installs `@mantine/dates` and imports
 
 ### Guards — the control rules (docs/CONTROLS-SPEC.md §6)
 
-**Nothing removed. Eight new oxlint rules and two new guard kinds; two of the ten land `error`, the
-rest `warn` under a dated C16 grace entry.** Every one honours `theme-allow <id> — <why>` on the
+**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.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, or in a file that DEFINES a basalt control                                                                    | warn → 1.27.0 |
-| `basalt/control-size-literal`        | `size`/`w`/`fullWidth`/`visibleFrom`/`hiddenFrom` on anything inside a home slot (the slot sets the tier)                                                                                                                              | warn → 1.27.0 |
-| `basalt/in-body-page-title`          | `<Title order={1\|2}>` outside prose/overlay context and outside a `content/` path                                                                                                                                                     | warn → 1.27.0 |
-| `basalt/responsive-twin`             | The same control mounted twice, one `visibleFrom="X"` and one `hiddenFrom="X"`                                                                                                                                                         | warn → 1.27.0 |
-| `basalt/search-literal-link`         | A `search:` object literal in a `linkOptions()` inside `defineNav()`/`navGroup()`                                                                                                                                                      | warn → 1.27.0 |
-| `basalt/use-search-from-literal`     | `useSearch({ from: '<route>' })`                                                                                                                                                                                                       | warn → 1.27.0 |
-| `in-body-page-title` (guard kind)    | The text lane of the same law — SAME id, so one annotation waives both lanes                                                                                                                                                           | warn → 1.27.0 |
-| `raw-selection-control` (guard kind) | The text lane of `control-outside-home`, approximated by a 12-line host-tag window                                                                                                                                                     | warn → 1.27.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
@@ -741,7 +1592,7 @@ instead of dumping help and letting the dump read like a choice.
 - **`tokens:css --check` blanks the provenance line (line 2) before comparing**, so a version bump
   alone no longer forces a no-op commit in a tokens-only consumer, where the gate is byte-equality.
   A stale provenance line is now a note on an otherwise-passing check. The `@generated` header is
-  still emitted byte-identical — the line stays, it just stops gating. **Superseded in `Unreleased`:
+  still emitted byte-identical — the line stays, it just stops gating. **Superseded at 1.26.0:
   blanking the WHOLE line also stopped gating the regeneration command it carries. Only the version
   token is neutralized now.**
 
@@ -912,7 +1763,7 @@ icons — it is not yet **sufficient**. If you went hybrid over the 404s, droppi
 half here costs you every icon unless your `public/` matches basalt's six filenames: at this
 release `icons` was still `false | { dir?: string }` over those six, so an app whose icon is
 `favicon.svg` could pick between a manifest naming two PNGs it never builds and a manifest with no
-`icons` member at all. The array form that fixes it is in `## Unreleased`. The option's JSDoc said
+`icons` member at all. The array form that fixes it is in `## 1.26.0`. The option's JSDoc said
 "skips the head `<link>` icons"; it now says what the option does.
 
 **Two `theme-allow` comment shapes were silently broken and now work.** Plainly: this is the fourth
@@ -920,7 +1771,7 @@ hole found in this one contract in three rounds. A thirteen-shape matrix — eve
 had been SEEN to write — is pinned in both halves, `src/guard/check-source.test.ts` and
 `configs/oxlint-plugin.test.ts`. **The claim that followed it here, that the two parsers could
 therefore no longer disagree, was false when it was written**: a list of collected anecdotes cannot
-close a contract. Three more holes were open at this release. See `## Unreleased`.
+close a contract. Three more holes were open at this release. See `## 1.26.0`.
 
 | Shape                                         | What it did                                                                                                                | Now                                     |
 | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
@@ -1207,35 +2058,43 @@ live in `configs/oxlint.json`, and since 1.20.0 their grace is tracked by `PLUGI
 named export beside the plugin — a test asserts it against the shipped preset in both directions, so
 deleting an entry forces the level flip in the same commit.
 
-| Rule                                   | Landed           | Became `error`                                                        |
-| -------------------------------------- | ---------------- | --------------------------------------------------------------------- |
-| `mantine-shade-index` (guard kind)     | 1.7.0 as `warn`  | **1.11.0**                                                            |
-| `basalt/raw-scroll-container`          | ≤1.2.0 as `off`  | `warn` 1.10.0 → **`error` 1.13.0**                                    |
-| `basalt/ai-sdk-major`                  | 1.10.0 as `warn` | **1.13.0**                                                            |
-| `basalt/agent-no-raw-usechat`          | 1.10.0 as `warn` | **1.13.0**                                                            |
-| `basalt/agent-resume-guard`            | 1.10.0 as `warn` | **1.13.0**                                                            |
-| `basalt/raw-size-literal`              | 1.7.0 as `warn`  | **1.20.0**                                                            |
-| `basalt/hand-rolled-plot`              | 1.21.0 as `warn` | **Unreleased** (grace had restarted at the 1.21.0 widening)           |
-| `basalt/chart-legend-literal`          | 1.20.0 as `warn` | **Unreleased**                                                        |
-| `basalt/shadow-basalt-export`          | 1.20.0 as `warn` | ADVISORY — permanent `warn`, see below, never subject to the C16 gate |
-| `basalt/hand-rolled-shell`             | 1.20.0 as `warn` | **Unreleased**                                                        |
-| `theme-allow-unscoped` (guard kind)    | 1.20.0 as `warn` | **Unreleased**                                                        |
-| `surface-shadow-override` (guard kind) | 1.20.0 as `warn` | **Unreleased**                                                        |
-| `css-raw-surface` (guard kind)         | 1.20.0 as `warn` | **Unreleased**                                                        |
-| `inline-font-size` (guard kind)        | 1.20.0 as `warn` | **Unreleased**                                                        |
-| `hidden-inline-style` (guard kind)     | 1.20.0 as `warn` | **Unreleased**                                                        |
+| Rule                                   | Landed           | Became `error`                                                                              |
+| -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
+| `mantine-shade-index` (guard kind)     | 1.7.0 as `warn`  | **1.11.0**                                                                                  |
+| `basalt/raw-scroll-container`          | ≤1.2.0 as `off`  | `warn` 1.10.0 → **`error` 1.13.0**                                                          |
+| `basalt/ai-sdk-major`                  | 1.10.0 as `warn` | **1.13.0**                                                                                  |
+| `basalt/agent-no-raw-usechat`          | 1.10.0 as `warn` | **1.13.0**                                                                                  |
+| `basalt/agent-resume-guard`            | 1.10.0 as `warn` | **1.13.0**                                                                                  |
+| `basalt/raw-size-literal`              | 1.7.0 as `warn`  | **1.20.0**                                                                                  |
+| `basalt/hand-rolled-plot`              | 1.21.0 as `warn` | **1.26.0** (grace had restarted at the 1.21.0 widening)                                     |
+| `basalt/chart-legend-literal`          | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `basalt/shadow-basalt-export`          | 1.20.0 as `warn` | ADVISORY — permanent `warn`, see below, never subject to the C16 gate                       |
+| `basalt/hand-rolled-shell`             | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `theme-allow-unscoped` (guard kind)    | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `surface-shadow-override` (guard kind) | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `css-raw-surface` (guard kind)         | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `inline-font-size` (guard kind)        | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `hidden-inline-style` (guard kind)     | 1.20.0 as `warn` | **1.26.0**                                                                                  |
+| `basalt/control-size-literal`          | 1.26.0 as `warn` | **1.27.0**                                                                                  |
+| `basalt/in-body-page-title`            | 1.26.0 as `warn` | **1.27.0**                                                                                  |
+| `in-body-page-title` (guard kind)      | 1.26.0 as `warn` | **1.27.0** — same id as the rule above, so one waiver covers both                           |
+| `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.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.
 Guard findings only gained a severity field at all in 1.4.0; before that every finding was fatal.
 
-**Both ledgers changed shape in the Unreleased minor (C16, `docs/CONTROLS-SPEC.md` §1).** An entry
+**Both ledgers changed shape at 1.26.0 (C16, `docs/CONTROLS-SPEC.md` §1).** An entry
 used to be a bare promotion-note string with no expiry a machine could check — which is exactly how
 the nine rows above sat at `warn` for five minors although the doctrine below says "one minor". Both
 `PLUGIN_RULE_GRACE` (`configs/oxlint-plugin.js`) and `GRACE_PERIOD_KINDS` (`src/guard/index.ts`) now
 hold `{ since, promote, why }` (semver strings), and a version-gated test fails the build once
 `package.json`'s version reaches an entry's `promote` while the entry is still there — see
-"Unreleased" above for the full change. `shadow-basalt-export` moved to a sibling ledger,
+"1.26.0" above for the full change. `shadow-basalt-export` moved to a sibling ledger,
 `PLUGIN_RULE_ADVISORY`, which the gate never checks: it was already documented as a possible
 permanent `warn`, and the version-gate doctrine only fits an entry that has an honest promotion
 date.