basalt-ui 1.25.0 → 1.27.0

package/MIGRATING.md

@@ -32,13 +32,755 @@ at 1.3.0, `./agent-chat` at 1.10.0.
 
 ## Unreleased
 
-**The heading has no number on purpose.** Three rounds running, the newest heading here named a
-version npm never served — `1.20.1`, then `1.21.1` — because this file is written before
-`semantic-release` computes the number, and a `feat:` in the batch turns the guess into a phantom.
-`shipped-versions.test.ts` now fails any file `init`/`sync` copy into a consumer that names a
-version `CHANGELOG.md` does not record. This file is not in that set; the same discipline applies
-by convention. Rename the section at release, or leave it — a reader can resolve `Unreleased`
-against `CHANGELOG.md`, and could never resolve `1.21.1`.
+**Nothing removed. Two exports added (`NumberFilter`, and three members on the number handle),
+one member added to every `FieldHandle` (`clear()`), four `StatCard` props added, and enforcement
+tightened: five oxlint rules plus one guard kind became `error`.** The store half of this minor also
+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.
+
+### 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.28.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.
+
+## 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
+(`docs/CONTROLS-SPEC.md` §1) is the new law behind both: a grace entry now carries `{ since,
+promote, why }` (semver strings) instead of a bare promotion-note string, and a version-gated test
+fails the build once `package.json`'s version reaches an entry's `promote` while the entry is still
+in the ledger — and `make release` refuses to cut a release whose COMPUTED version has reached one,
+which is the half that fires before the release rather than one minor after it. That is what stops a
+rule sitting at `warn` for five minors with nothing tracking the promise, which is exactly what
+happened to the nine rows below.
+
+**`PLUGIN_RULE_GRACE`** (`configs/oxlint-plugin.js`) **and `GRACE_PERIOD_KINDS`**
+(`src/guard/index.ts`) no longer carry any PRE-EXISTING entry — every one either promoted to `error`
+(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 forced to promote or be deleted at 1.27.0. Five rules and one kind promoted there;
+the C1 pair was re-dated to 1.28.0 against a measurement (see `## Unreleased` above). A theme-allow escape written against
+any of these still works unchanged; only the SEVERITY of an unwaived finding moves from `warn` to
+`error`.
+
+| Rule / kind (promoted)                 | What now errors                                                                                                                                                  | Escape hatch                                                                                                                                |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `basalt/hand-rolled-plot`              | An unwaived chart-assembly node (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`) outside a file composing `CartesianChart` | `theme-allow hand-rolled-plot — <why>` per node, or `theme-allow-file hand-rolled-plot — <why>` for a declared exception                    |
+| `basalt/chart-legend-literal`          | A hand-written array literal passed to `ChartLegend`'s `items`                                                                                                   | Derive the legend from `series` (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it), or `theme-allow chart-legend-literal — <why>` |
+| `basalt/hand-rolled-shell`             | A hand-rolled app-shell assembly node instead of `BasaltShell`                                                                                                   | `theme-allow hand-rolled-shell — <why>`, or `theme-allow-file` for the whole file                                                           |
+| `theme-allow-unscoped` (guard kind)    | A bare `// theme-allow` with no rule id                                                                                                                          | Name the kind(s): `theme-allow <kind> — <why>`                                                                                              |
+| `surface-shadow-override` (guard kind) | A hand-composed `boxShadow` reaching a `--vx-*` token                                                                                                            | Use the shipped shadow tokens, or waive with a reason                                                                                       |
+| `css-raw-surface` (guard kind)         | A raw surface color in kebab CSS (`.module.css`)                                                                                                                 | Same remedy as the JS/TSX form — a `--vx-*` var, or waive                                                                                   |
+| `inline-font-size` (guard kind)        | A hardcoded numeric font size in an inline `style` object                                                                                                        | `VX.text.*` / `--vx-text-*`, or waive                                                                                                       |
+| `hidden-inline-style` (guard kind)     | A style object defined once and spread into `style={...}` (evades the guard's inline-object scan)                                                                | Inline the object at the call site, or waive                                                                                                |
+
+**`basalt/shadow-basalt-export` is unaffected** — it moves ledgers (`PLUGIN_RULE_GRACE` →
+`PLUGIN_RULE_ADVISORY`), not severity. It stays `warn` in the shipped preset, permanently, and is
+never subject to the C16 gate: see "Lint and guard rules that tightened" below for why.
+
+Consumers who never overrode `basalt.severity` for any of the eight kinds/rules above and never
+waived them see these findings for the first time as `error`; measure against the shipped preset
+before upgrading if that's a concern (`basalt-ui check-theme --audit-allows`, `oxlint .`).
+
+### Composers — WidgetHeader-backed renames (docs/CONTROLS-SPEC.md §2.2)
+
+`StatCard`, `ChartCard`, `Section` (new), `SettingsSection`/`DangerZone` and `BasaltDataTable` now
+each compose the wave-1 `WidgetHeader` primitive for their title row instead of hand-rolling one —
+several props renamed or were added to line up with it.
+
+| Component                        | Removed / renamed                                          | Replacement                                                                                                                                                                                                                                                                              |
+| -------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `StatCard`                       | `label`                                                    | `title`                                                                                                                                                                                                                                                                                  |
+| `StatCard`                       | `menu`                                                     | `actions` (wrapped in `CtlSlot`)                                                                                                                                                                                                                                                         |
+| `StatCard`                       | —                                                          | adds `icon`, `info`, `subtitle` (forwarded to the composed `WidgetHeader` — the info glyph beside the title, the muted unit line under the hero row), `sparklinePlacement?: 'bleed' \| 'right'` (default `'bleed'`, collapses to it below `sm`)                                          |
+| `ChartCard`                      | `tooltip`                                                  | `info`                                                                                                                                                                                                                                                                                   |
+| `ChartCard`                      | `extra`                                                    | `actions` (carries `data-basalt-tier="widget"`, no `CtlSlot` — `./charts` stays Mantine-free)                                                                                                                                                                                            |
+| `ChartCard`                      | `title: string` (required)                                 | `title?: string` — the header now renders only when title/info/value/actions/icon/count is set                                                                                                                                                                                           |
+| `ChartCard`                      | —                                                          | adds `icon`, `value`, `delta`, `deltaPeriod`, `count`                                                                                                                                                                                                                                    |
+| `SettingsSection` / `DangerZone` | `description`                                              | `subtitle`                                                                                                                                                                                                                                                                               |
+| `SettingsSection` / `DangerZone` | —                                                          | adds `actions` (wrapped in `CtlSlot`)                                                                                                                                                                                                                                                    |
+| `BasaltDataTable`                | `toolbarActions`                                           | `actions?: ReactNode` — the toolbar (search + facets + `actions`) is now wrapped in `CtlSlot`. Typed `ReactNode`, not `BarAction[]` — a table toolbar is not a `PageBar`/`Section`, and `ActionGroup`'s shell-extras semantics (primary/secondary, mobile folding) must not leak into it |
+| `BasaltDataTable`                | fixed `w={220/200/180/110}` on toolbar/pagination controls | removed — the controls size by content                                                                                                                                                                                                                                                   |
+| `BasaltDataTable`                | —                                                          | adds `title`, `icon`, `subtitle` — when `title` is set, renders `WidgetHeader tier="widget"` above the toolbar, `count` always `table.getRowCount()` (C11)                                                                                                                               |
+| `BasaltDataTable`                | `facets` rendered as raw `Select`/`MultiSelect`            | rendered as `EnumFilter`/`MultiSelectFilter` pills inside a `FilterSet` (`docs/CONTROLS-SPEC.md` §3) — a synthetic `"All"` option stands in for a single-select facet's cleared state, since a closed enum field has no member for "unset"                                               |
+
+New export: **`Section`** (`.`, Mantine-coupled) — `WidgetHeaderProps` minus `tier`, plus `tabs?`,
+`collapsible?`, `persistKey?`, `defaultOpen?`, `summary?`, `id?`, `children`. No `variant`, no
+border/background — one shaded container level per page belongs to the cards inside a `Section`, not
+to `Section` itself. Fold state persists at `basalt:section:<persistKey>` via `createPersistedState`
+when `persistKey` is given, else local `useState`; the header stays drawn when collapsed, only the
+body unmounts. `defaultOpen` (default `true`) picks the state a FIRST visit lands on and is outranked
+by a persisted value, so a section the reader closed stays closed. `summary` renders under the header
+and survives a collapse — a folded section still states its headline figures, which is what makes
+folding it a real option rather than a way to lose the numbers.
+
+### Homes — `PageBar` replaces the page-action portal
+
+**Three exports removed with no deprecation window, one prop retyped, three tokens and one CSS
+class deleted.** `PageActions` gave a page a `ReactNode` slot in the header and nothing else: no
+second row, no overflow policy, no mobile projection. Every consumer then hand-rolled the rest —
+a sticky filter row measured into a `--lw-header-h`, a horizontally scrolling action strip, a
+responsive twin under `visibleFrom`/`hiddenFrom`. `PageBar` is that whole shape, typed
+(`docs/CONTROLS-SPEC.md` §2.1).
+
+| Removed / changed                                                                                  | Replacement                                                                                                |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `PageActions`                                                                                      | `<PageBar actions={{ primary, secondary }} sync={…} tabs={…} filters={…} filtersEnd={…} />`                |
+| `PageActionsOutlet`                                                                                | none — the outlet is internal to `BasaltShell` now                                                         |
+| `PageHeaderProvider`                                                                               | none — the provider is internal to `BasaltShell` now                                                       |
+| `BasaltShellProps.globalActions: ReactNode`                                                        | `GlobalAction[]` — `{ key, node, mobile?: 'bar' \| 'more' \| 'hidden' }`; the first two default to `'bar'` |
+| tokens `appShellHeaderMobileHeight`, `appHeaderMobileActionsHeight`, `stickyHeaderClearanceMobile` | `appShellHeaderHeight` / `stickyHeaderClearance` — one value at every viewport                             |
+| vars `--vx-space-app-header-mobile-actions-height`, `--vx-space-sticky-header-clearance-mobile`    | `--vx-space-sticky-header-clearance`                                                                       |
+| CSS `.pageActions` (`shell/app-header.module.css`) and its `nowrap` override                       | none — the portal target no longer scrolls; overflow folds into `ActionGroup`'s `More`/kebab               |
+
+What changes at runtime even if you only rename:
+
+- **The app-shell header is 48px on a phone too.** It used to wrap to two rows (97px) and reserve
+  the second one on every route, empty or not (law C14). A page-level filter/tab row now renders
+  in the page FLOW, sticky under the header, so a route with no filters is 49px shorter on mobile.
+- **The header never scrolls sideways.** Actions past three fold into a `More` menu on desktop and
+  into one kebab below `sm` — computed from `BarAction[]`, which is why the slot had to become data
+  (law C7). There is exactly ONE kebab per header, and `PageBar`'s ROW 1 owns it: the shell's
+  `mobile: 'more'` global actions land there, and so do `filtersEnd`'s items (row 2 shows those on
+  desktop only — below `sm` row 2 is tabs + the first pill + `Filters (n)`, per spec §2.1). A route
+  with no `PageBar` row-1 actions gets the kebab from the shell instead. An `ActionGroup` you mount
+  yourself — in a `Section` or `ChartCard` `actions` slot — never inherits the global rows.
+- **`--basalt-page-bar-h` is published on `documentElement`** (ResizeObserver where available,
+  `height > 0` guard)
+  whenever a row 2 renders, and removed when it unmounts. It is written in the LAYOUT phase, so it
+  exists at the first paint — a cold load of `/page#anchor` lands below the bar rather than under
+  it. A `100dvh` body becomes
+  `calc(100dvh - var(--app-shell-header-height) - var(--basalt-page-bar-h, 0px))` — delete any
+  hand-rolled measure-and-publish effect and any hardcoded header-height fallback.
+- **A shell-less app reads `title`/`icon`.** Inside a `BasaltShell` the breadcrumb names the page
+  and both are ignored; outside one they lead row 1, and the whole bar sticks at `top: 0`.
+- **`className` lands on the bar ROOT in both forms** — the shell-less
+  `[data-basalt-page-bar="standalone"]`, or row 2's sticky wrapper `[data-basalt-page-bar="shell"]`.
+  It is the seam for the two things only the consumer's own layout knows: bleeding the sticky bar
+  across a container's gutters, and a hairline under it. Scope that CSS through the class; a global
+  `[data-basalt-page-bar]` rule reaches every page in the app, including the ones wanting neither.
+
+`ActionGroup`, `OverflowMenu` and `SyncButton` ship on the new `basalt-ui/controls` subpath; only
+the TYPES a `PageBar`/`BasaltShell` prop mentions (`BarAction`, `ActionGroupProps`, `GlobalAction`)
+are re-exported from the root.
+
+### Stores — `createSearchStore` replaces the enum-only pair
+
+`createSearchParamStore` and `createMultiSearchParamStore` still work: both are now `@deprecated`
+thin wrappers over `createSearchStore`, returning the same four members
+(`validateSearch`, `useStore`, `readStored`, `linkSearch`) with the same signatures and reading the
+same single-value localStorage envelope. **They are removed in 1.29.0.**
+
+| Removed / deprecated                                       | Replacement                                                                                                      |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `createSearchParamStore({ key, param, values, fallback })` | `createSearchStore({ key, fields: { <param>: field.enum(values, fallback) } })` — `@deprecated`, removed 1.29.0  |
+| `createMultiSearchParamStore({ key, param, values })`      | `createSearchStore({ key, fields: { <param>: field.multi(values, fallback) } })` — `@deprecated`, removed 1.29.0 |
+| `<store>.useStore()`                                       | `<store>.field.<name>.use()` — reads the URL FIRST, then the mirror; writes both lanes                           |
+| `useOnlineStatus` (`.` and `./state`)                      | `useConnectivity()` (`.`, auto-mounted by `BasaltProvider`) — **removed, not deprecated** (A12)                  |
+| `createSearchSchemaStore`                                  | never shipped; `createSearchStore` is what those "planned" paragraphs were waiting for                           |
+
+New on `./router-tanstack`: `createSearchStore`, `field` (`enum` / `multi` / `range` / `number` /
+`boolean` / `string`), and the `FieldHandle` / `AnyField` / `FieldValue` / `RangeValue` / lane types.
+New on `./state` (router-free, same field vocabulary): `createLocalStore`, `field`, those same types.
+`FieldHandle` is what every 1.26.0 control takes instead of `value`/`onChange`
+(`docs/CONTROLS-SPEC.md` §3–§4).
+
+Three things to know when you migrate a real store:
+
+- **A deep link now wins over the mirror.** `?range=7d` reads back `7d` even when localStorage says
+  `30d`. The old `useStore` read localStorage, so a shared link opened on the wrong window — the bug
+  three consumers shipped (A8). If you were compensating for that by hand, delete the compensation.
+- **The storage layout changed for the NEW factory only.** `createSearchStore` keeps one entry per
+  STORE (`basalt:<key>` = `{ fieldName: value }`); the old factories kept one bare value per param.
+  A store migrated from a wrapper to `createSearchStore` therefore ignores whatever the browser
+  already had for that key and starts on its fallback once. The wrappers themselves keep the old
+  layout byte-for-byte, so an un-migrated consumer sees no reset — including a stored EMPTY multi
+  selection, which still reads back as empty: "an empty array means absent" is a URL rule in the
+  deprecated store, never a storage rule, so a deliberately cleared filter stays cleared.
+- **A write from outside the owning route persists only** — it no longer needs a hand-rolled
+  `navigate` beside it, and it no longer silently writes a param the route does not validate.
+  `validateSearch` picks the persisted value up on the next visit (A1). The one combination with
+  nowhere to go — a `persist: false` field written from a route that does not validate it — warns
+  once per field in dev rather than dropping the write silently.
+
+**Every navigate a store issues carries `resetScroll: false`** — a field write and `useReset`
+alike. A filter lives halfway down a page as often as it lives in the bar, and the router treats a
+same-route search write as a navigation, so the default scrolled the reader back to the top on every
+change. Delete any `resetScroll: false` you were passing beside a hand-rolled `navigate`.
+
+Lanes are declared once per field: `{ url: false }` is the local-only lane (per-chart selects, a
+compact toggle — or use `createLocalStore`), `{ persist: false }` the URL-only lane (pagination, a
+deliberately unpersisted threshold), `{ history: 'push' }` opts one field into a history entry.
+**`{ url: false, persist: false }` is the IN-MEMORY lane** rather than the one combination that
+dropped its write: shared across every mount of that store for the session, gone on reload, never
+written to or read from localStorage. It behaves identically in both factories — `createSearchStore`
+counts such a field in `useActiveCount()` and clears it in `useReset()`, and it never appears in
+`useValues()`/`validateSearch`, which are the URL lane by definition. In a `createLocalStore` the
+`url` flag is ignored, so `{ persist: false }` alone lands there. The dev warning about a write with
+nowhere to go now fires only for its remaining real case: a `{ persist: false }` field that IS on the
+URL lane, written from a route that does not validate the param. `createLocalStore` also carries **`labels()`**,
+chainable and identical to `createSearchStore`'s, so `SelectFilter`/`ViewTabs` read option labels off
+a local store too.
+A `field.range` keeps THREE URL params (preset + `from` + `to`, renamable via `params`), so existing
+deep links and loaders keep their shape, and `field.<name>.toWindow(v)` replaces a hand-rolled
+`presetToParams`.
+
+### Sidebar — `sidebarBlocks` replaces the two `ReactNode` extras
+
+**Two props removed with no deprecation window, and two widened.** `sidebarNavExtra` and
+`mobileNav.moreExtra` were the same gap solved twice and badly: the first rendered on desktop only
+and vanished in the collapsed rail, the second was one anonymous row at the bottom of the More
+surface, and neither could be projected because basalt could not see inside a `ReactNode`. Every
+consumer that wanted an "Awaiting action" list therefore wrote it twice, once per prop, and got no
+rail badge either way. `SidebarBlock[]` is that whole shape as data (law C13,
+`docs/CONTROLS-SPEC.md` §2.3).
+
+| Removed / changed                  | Replacement                                                                                                                                                                            |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BasaltShellProps.sidebarNavExtra` | `sidebarBlocks={[{ kind: 'custom', key, node }]}` — same DOM position (last child of the nav scroll region), same CSS-only hiding in the rail, still desktop-only                      |
+| `AppSidebarProps.navExtra`         | `blocks={[{ kind: 'custom', key, node }]}`                                                                                                                                             |
+| `MobileNavConfig.moreExtra`        | `sidebarBlocks={[{ kind: 'list', key, label, items }]}` — one More-sheet row (`Awaiting action · 3`) opening a nested sheet of its items, instead of one unlabelled row of raw content |
+| `useNav(NAV, { moreExtra })`       | drop the option; declare the block on `BasaltShell`                                                                                                                                    |
+| `BasaltShellProps.brand`           | widened to `BrandConfig & { menu?: AccountMenuItem[] }` — additive; `menu` makes the brand row a `Name ▾` workspace switcher                                                           |
+| `BasaltShellProps.search`          | widened to `SidebarSearchConfig & { actions?: SidebarSearchActions }` — additive; one or two icon-only buttons right of the ⌘K row                                                     |
+
+What changes at runtime even if you declare no blocks at all:
+
+- **Nav-section folds are now PERSISTED**, at `basalt:sidebar-section:<label-slug>` (e.g.
+  `basalt:sidebar-section:tools`). They were a `useState` keyed by label, so every reload re-opened
+  a section the user had closed. `defaultCollapsed` is now the SEED for that key rather than a value
+  that overrides the user on every mount. Block folds live at `basalt:sidebar-block:<key>`; both are
+  the standard `createPersistedState` envelope (`{ v: 1, value: boolean }`), readable with
+  `readPersistedValue` from `basalt-ui/state`. A "Show more" toggle is deliberately NOT persisted.
+- **`settingsMenuItems` renders FLAT at three entries or fewer** — one link row each, instead of a
+  gear "Settings" menu you had to open to see two rows. Four or more keeps the menu. `brand.version`
+  rides the flat rows as a faint label and the dropdown as a `Menu.Label`, as before. New
+  `BasaltShellProps.settingsMenu?: 'auto' | 'flat' | 'menu'` (`AppSidebarProps` too, default
+  `'auto'` = that count rule) forces the form: pass `'menu'` when the three rows are CONTROLS rather
+  than destinations — a theme radio group and a devtools switch read as a widget pile flat, and the
+  count cannot tell them from three links.
+- **The footer is one wrapper deeper.** `settingsMenuItems` without `account` used to render its
+  `Group` as the footer element itself; both now sit inside one footer `Stack` alongside any
+  `placement: 'bottom'` block. No visual change — relevant only to a stylesheet reaching in by
+  structure.
+- **`useNav` now marks exactly one destination `active`** — the deepest matching route wins, instead
+  of every prefix-matching row (a parent AND its child) reading active at once. A parent on the
+  winner's path gets the new `SidebarItem.ancestor` instead: never active, never `aria-current`, only
+  a `data-ancestor` hook for CSS. A consumer that styled off two simultaneously-active rows will now
+  see one.
+
+New types on `.`: `SidebarBlock`, `SidebarListBlock`, `SidebarProgressBlock`, `SidebarCustomBlock`,
+`SidebarBlockItem`, `SidebarBlockTone`, `SidebarSearchActions`. `SidebarItem` gained `ancestor?:
+boolean`.
+
+### `DeltaBadge` — plain-element DOM, same props
+
+Nothing removed or renamed — a DOM contract change only, ahead of `WidgetHeader`
+(`docs/CONTROLS-SPEC.md` §2.2) composing it Mantine-free.
+
+| Component    | What changed                                                                            | Why it matters                                                                                       |
+| ------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `DeltaBadge` | Renders a plain `<span>`, no `mantine-Badge-root`/`mantine-Badge-label` classes anymore | Same props, tone and format API — but a selector or snapshot keyed on Mantine's Badge classes breaks |
+
+### Controls — `ArticleFilterBar` replaced by store-bound controls
+
+Two new subpaths, `basalt-ui/controls` and `basalt-ui/controls-dates`, and ONE removal. The removed
+component was controlled (`value`/`onChange`, its own `visibleFrom`/`hiddenFrom` twin); its
+replacements take a `FieldHandle` and own the URL write, the localStorage mirror and the responsive
+swap themselves (`docs/CONTROLS-SPEC.md` §3, laws C2/C9).
+
+| Removed                 | Replacement                                                           | Import                                                       |
+| ----------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `ArticleFilterBar`      | `FilterSet` + `ViewTabs` (category axis) + `MultiSelectFilter` (tags) | `basalt-ui/controls`, and unchanged from `basalt-ui/content` |
+| `ArticleFilterBarProps` | `FilterSetProps` / `ViewTabsProps` / `MultiSelectFilterProps`         | same                                                         |
+
+All three replacements are re-exported from `basalt-ui/content` as well, so a content-only consumer
+changes the component names and the props, not the import path.
+
+Porting one call site:
+
+```tsx
+// before — the page owned the state, the labels and the mobile swap
+const [category, setCategory] = useState('all')
+<ArticleFilterBar categories={CATEGORIES} category={category} onCategoryChange={setCategory}
+                  tags={ARTICLE_TAGS} selectedTags={tags} onTagsChange={setTags} />
+
+// after — one store, two controls, no useState and no responsive branch
+const articles = createSearchStore({
+  key: 'articles',
+  fields: { category: field.enum(CATEGORY_VALUES, 'all'), tags: field.multi(ARTICLE_TAGS, []) },
+}).labels({ category: CATEGORY_LABELS })
+
+<ViewTabs field={articles.field.category} />
+<FilterSet>
+  <MultiSelectFilter field={articles.field.tags} label="All tags" />
+</FilterSet>
+```
+
+New on `basalt-ui/controls`: `FilterSet`, `RangeFilter`, `CompareFilter`, `SelectFilter`,
+`MultiSelectFilter`, `SearchFilter`, `ToggleFilter`, `ViewTabs`, `COMPARE_VALUES`, and the
+action/sync family. New on `basalt-ui/controls-dates`: `DateRangePicker`.
+
+**`SyncButton`'s `scope` now decides the SHAPE, not only where you mount it.** `scope: 'global'`
+renders icon-only at every viewport (an `ActionIcon` with the spinning glyph, age and error in the
+tooltip, `label` as the accessible name) — the shell header shares 48px with the breadcrumb and
+`PageBar` row 1, and a labelled button there is what pushes a page's own actions into the kebab.
+`scope: 'page'` is unchanged on desktop (labelled, age inline) and drops to icon-only below `sm`,
+which is what `docs/CONTROLS-SPEC.md` §3 always specified. One mount either way, CSS-only swap (law
+C9). Consequence to know: the accessible name is now `aria-label` in BOTH forms, so a test asserting
+the name as `Sync 2m ago` (the age used to land in it) now reads `Sync`. Nothing to change at a call
+site.
+
+**`SelectFilter` and `MultiSelectFilter` take `options?: readonly FilterOption[]`** — a runtime
+catalogue (`{ value, label, disabled? }`) that OVERRIDES `field.options` whole rather than merging,
+so a value the catalogue has dropped loses its row. It is what a label carrying live data needs
+(`EUR · 1.08`), and on `SelectFilter` it also opens a second field shape: a `FieldHandle<StringField>`
+is legal WITH `options` — an id set no enum can close over, a project picker fed from a query — and
+a type error without it. `FilterOption` is new on `basalt-ui/controls`. Additive; nothing to change.
+
+**`FilterSet` renders the mobile `Filters (n)` pill only when a child is actually folded.** With
+every child inside the `inline` budget (one filter at the default `inline: 1`) the sheet would hold a
+copy of what is already on screen, so neither the trigger nor the drawer mounts. Nothing to change —
+but a mobile test asserting the pill exists on a one-filter page now has to fold something
+(`inline={0}`) or drop the assertion. `RangeFilter.label` (default `'Range'`) names the sheet heading
+and the preset track's aria name; the pill itself still reads the VALUE.
+
+**`data-numeric` is now a package-wide law, not a per-component rule.** `basalt-ui/styles.css`
+declares `[data-numeric] { font-family: var(--basalt-font-mono); font-variant-numeric: tabular-nums }`
+inside `@layer basalt`, so the attribute works on ANY element — `<Text data-numeric>`, a table cell,
+a count tag — and not only on a `SegmentedControl`, where it was previously a module-scoped rule that
+made the attribute look broken everywhere else. Nothing to change: adding the attribute is opt-in,
+and the two module rules that also set a component `font-size` still apply on top. This retires the
+per-consumer `theme-allow` + inline `fontFamily`/`fontSize` hack for numeric labels.
+
+**`@mantine/dates` is a new OPTIONAL peer, and only `basalt-ui/controls-dates` needs it.**
+`basalt-ui/controls` resolves and renders without it — proven from the packed tarball by
+`scripts/pack-test.sh`. Pass the picker into `RangeFilter` rather than importing it from a shared
+module:
+
+```tsx
+import { DateRangePicker } from 'basalt-ui/controls-dates'
+;<RangeFilter field={analytics.field.range} customPicker={DateRangePicker} />
+```
+
+A consumer that uses `DateRangePicker` installs `@mantine/dates` and imports
+`@mantine/dates/styles.layer.css` with the other Mantine layer bundles, before `basalt-ui/styles.css`.
+
+### Guards — the control rules (docs/CONTROLS-SPEC.md §6)
+
+**Nothing removed. Eight new oxlint rules and two new guard kinds. `Ships` below is the level as of
+THIS minor** — eight land `error`, and the C1 pair (`control-outside-home` and its text lane) is the
+only grace left, re-dated to 1.28.0 on a measurement (see § Guards — the promotions).\*\* Every one honours `theme-allow <id> — <why>` on the
+node and `theme-allow-file <id> — <why>` on the file, the same grammar as the rest.
+
+| Rule / kind                          | Fires on                                                                                                                                                                                                                               | Ships         |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `basalt/hand-rolled-filter`          | A raw Mantine `Select`/`SegmentedControl`/… handed to a TIERED home slot (`actions`/`filters`/`tabs`/`sync`/`filtersEnd` on `PageBar`/`Section`/`WidgetHeader`/`ChartCard`/`StatCard`/`BasaltDataTable`/`SettingsSection`/`FilterSet`) | error         |
+| `basalt/page-bar-budget`             | A second `PageBar` in the SAME returned tree, >4 `actions.secondary`, >3 `Section` actions, a second filled `Button`/`ActionIcon` in one slot (outside an overlay)                                                                     | error         |
+| `basalt/control-outside-home`        | The same raw control with no home at all — exempt under a settings row / overlay / composer, in an `@mantine/form` file, in a file that DEFINES a basalt control, or in a file basenamed `*-{modal,drawer,popover,panel,form}.tsx`     | warn → 1.28.0 |
+| `basalt/control-size-literal`        | `size`/`w`/`fullWidth`/`visibleFrom`/`hiddenFrom` on anything inside a home slot (the slot sets the tier)                                                                                                                              | **error**     |
+| `basalt/in-body-page-title`          | `<Title order={1\|2}>` outside prose/overlay context and outside a `content/` path                                                                                                                                                     | **error**     |
+| `basalt/responsive-twin`             | The same control mounted twice, one `visibleFrom="X"` and one `hiddenFrom="X"`                                                                                                                                                         | **error**     |
+| `basalt/search-literal-link`         | A `search:` object literal in a `linkOptions()` inside `defineNav()`/`navGroup()`                                                                                                                                                      | **error**     |
+| `basalt/use-search-from-literal`     | `useSearch({ from: '<route>' })`                                                                                                                                                                                                       | **error**     |
+| `in-body-page-title` (guard kind)    | The text lane of the same law — SAME id, so one annotation waives both lanes                                                                                                                                                           | **error**     |
+| `raw-selection-control` (guard kind) | The text lane of `control-outside-home`, approximated by a 12-line host-tag window, plus the same overlay-basename exemption                                                                                                           | warn → 1.28.0 |
+
+**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
+(`controlHeight` 42, unchanged). A raw `Select`/`Switch`/`Button` bound to a setting is correct
+there, and its `size` prop is what holds the row at the form tier, so neither `hand-rolled-filter`
+nor `control-size-literal` reaches into it; `control-outside-home` treats a settings row as a home
+and stays silent as well. Consumer settings pages need no change.
+
+**Three scoping facts, because each one is a rule NOT firing on code you already have.** The home
+tag must resolve to a component imported from `basalt-ui` (or a basalt subpath) — your own
+`Section`, `PageBar` or `StatCard` is not a tiered home, and nothing in this table reads it as one;
+the one accepted gap is basalt's `Section` re-exported through your own barrel, which the rules
+cannot see. An OVERLAY colocated in a slot (`Modal`, `Drawer`, `Popover.Dropdown`, `Menu.Dropdown`,
+`SettingsRow`) is exempt — a `New` button beside the `<Modal>` it opens is how both are written, and
+the overlay's own controls are not in the bar. And `control-size-literal` only reaches what the
+slot's theme actually re-tiers: the raw filters, the basalt controls, and Mantine's
+`Button`/`ActionIcon`/`Input`/`TextInput`/`Select`/`MultiSelect`/`SegmentedControl`/`NativeSelect` —
+an icon's `size`, a count `Badge`, a `Loader`, an `Avatar` or a `Modal size="lg"` never report.
+
+**Two existing rules widened, neither with a new id.** `basalt/raw-scroll-container` now also fires
+on `overflowX: 'auto' \| 'scroll'` and on `<ScrollArea scrollbars="x">` **inside a home SLOT**
+(`actions`/`filters`/`tabs`/`sync`/`filtersEnd`) — law C7, overflow folds into a `More` menu or a
+`Filters (n)` sheet rather than scrolling sideways. A home's BODY is out of scope: a wide table, a
+pinned-column grid or a horizontally scrolling code block in a `Section`/`ChartCard` is page
+content, not a sideways-scrolling row of controls, and outside a slot `overflowX` is still not
+policed at all.
+oxlint severities are per rule ID, not per branch, so this widening inherits the rule's existing
+`error` level with no grace runway of its own — the honest limitation, and the reason it is scoped to
+homes rather than shipped repo-wide. `basalt/shadow-basalt-export` gains a rename table
+(`PageHeader`/`FilterBar` → `PageBar`, `WindowSelector`/`RangeSelector`/`DateFilter` →
+`RangeFilter`, `PageSection`/`SectionTitle`/`SectionHeading` → `Section`, `ViewSwitch`/`ViewToggle`
+→ `ViewTabs`, `RefreshButton`/`SyncControl`/`SyncStatusButton` → `SyncButton`, `HeroCard`/`HeroStats`
+→ `StatCard`), so a fork that RENAMED the export is visible too. It stays a permanent advisory
+`warn`.
+
+**`profile: 'tokens-only'` now disables 19 kinds, not 17** — both new kinds are Mantine-coupled.
+
+**`SURFACES` gains `pluginRules`** (`src/surfaces.ts`, internal — not a published subpath): every
+doctrine surface names the oxlint rules that enforce it, every registered rule maps to exactly one
+surface, every guard KIND maps to at least one, and `basalt-ui check-coverage` asserts all three —
+so a generated coverage header can neither over- nor under-report its lane. `check-coverage` also
+takes `--write` / `--check` for the generated `<!-- basalt:coverage -->` header of each
+`agent/rules/*.md` file; a rule file with no block yet is reported, not failed.
+
+### Controls — the pill reads the VALUE, and four defaults moved
+
+**A filter pill's TEXT is now always the selected option's label, at the field's default value too.**
+It used to fall back to the filter's NAME while `field.isDefault(value)` held, which is how a bar
+could read `Compare` over a field holding `'previous'` while the popover showed `Previous period`
+selected. `label` is the popover/sheet heading and the accessible name; it is never printed on the
+pill. Affects `SelectFilter`, `CompareFilter` and every control built on the shared enum body;
+`RangeFilter` already read its value, and `MultiSelectFilter` keeps its own law (the group label
+while the selection is empty or complete, `N <noun>` otherwise).
+
+**Nothing to change at a call site.** What changes is the string a test or a screenshot sees: a
+`SelectFilter field={currency} label="Currency"` at fallback `USD` now reads `USD`, not `Currency`.
+If a bar reads badly at rest, the fix is the OPTION label (`store.labels()`), not the filter's name.
+
+| Component / prop                                  | Was                                         | Now                                                                                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `CompareFilter` option labels                     | the raw values until `store.labels()`       | `No comparison` / `Previous period` / `Same period last year`, exported as `COMPARE_LABELS`. A label a consumer set (`label !== value`) still wins.                      |
+| `BasaltDataTable` → `withTableBorder`             | `true`                                      | `false`. Pass `true` for a table that needs a frame. The head rule and the between-row rules are untouched; the LAST row's rule is now dropped (it was an outer border). |
+| `BasaltDataTable` single-select facet's "all" row | `All`                                       | `Any <facet.label lowercased>` — the pill now reads it, and three facets all reading `All` said nothing.                                                                 |
+| `ViewTabs` phone `Select` (past 3 options)        | greedy (216px measured, truncating a title) | capped at 9rem                                                                                                                                                           |
+
+**New: `ControlGroup`** (`basalt-ui/controls`) — joins adjacent controls that act on ONE thing
+(`‹ Today ›`, `− 1 +`) into a single box: no gap, one shared hairline per pair, radius on the outer
+ends only. `gap?: 'none' | 'tight'`. `BarActionItem` gains `group?: true`, and a run of adjacent
+`group: true` actions in an `ActionGroup` renders as one `ControlGroup`; a joined member that ships an
+`icon` renders ICON-ONLY with its label demoted to the accessible name. `ActionGroup` also joins
+adjacent ICON-ONLY entries on the mobile bar with no flag. `basalt/shadow-basalt-export` now names
+`ButtonGroup` / `ButtonRow` / `JoinedButtons` as renamed forks of it.
+
+### The `ctl` tier now covers Radio, Checkbox and Switch
+
+All three defaulted to Mantine's `sm` — a 20px indicator beside the tier's 13.5px option label — in
+every filter popover and in the mobile sheet. They are now in `CTL_THEME` (with their `.Group`s) and
+`cssVariablesResolver` declares their `-ctl` vars: 16px indicator, 18×30 switch.
+
+**One consequence worth knowing.** Mantine resolves a Radio's size as `props.size ? props.size :
+ctx.size`, and a theme `defaultProps.size` is indistinguishable from an explicit prop to that check
+— so inside a `<CtlSlot>` (any home's slot) a `<Radio.Group size="lg">` no longer sizes its children;
+they stay `ctl`. A group that genuinely needs another size belongs in a BODY, which no slot wraps.
+
+`basalt/control-size-literal` widened to cover the six new tags, so a `size` on a Radio/Checkbox/
+Switch inside a home slot now reports. It is still `warn` on its 1.26.0 → 1.27.0 runway (it has never
+shipped at any level, so widening it restarts nothing).
+
+### Icons — one box, no call-site geometry
+
+Every `icon` prop in the framework (`BarAction`, the filter pills and their trailing affordance,
+`WidgetHeader`/`StatCard`, `SyncButton`, sidebar-block rows, the overflow fold's own glyphs) now
+renders through ONE internal slot: a fixed `--vx-space-icon-size` (16px default) square that restates
+the glyph's `width`/`height` at 100% and takes it off the text baseline. **No API change** — but a
+consumer's `<svg width="24">` that used to set a control's row height now renders at 16px, and an
+`<svg>` with no `width`/`viewBox` at all no longer paints at 300×150. Per-tier sizes come from the
+box var (`WidgetHeader` sets 14px at `tier="widget"`), never from a prop.
+
+### Mobile nav — at most ONE slot is active
+
+A slot's activeness now reads exactly the destinations it COVERS. It used to roll up over `children`
+unconditionally while an item slot covered only its own key, so at `/dashboard/sessions` the
+`Dashboard` tab lit through the rollup and the `More` tab lit for `Sessions` sitting in its overflow
+— two `aria-current="page"` tabs at once. A SECTION tab still lights for a nested destination (it
+covers its whole tree); an ITEM tab with children no longer does, and the overflow slot that can
+actually reach the open route lights instead.
+
+`useNav`'s anchors now pass `activeOptions: { exact: true }` to TanStack's `Link`. A `Link` spreads
+`{ 'data-status': 'active', 'aria-current': 'page' }` last — after `activeProps` and after every
+caller prop — so its own fuzzy match could not be overridden from outside and re-created the very
+double-highlight `useNav`'s resolver exists to prevent. basalt's own law is unchanged: an item whose
+exact route is never visited still lights on a descendant route.
+
+### Layout — two collisions and a gap
+
+- **The app header**: exactly one side of row 1 is elastic, and it is the breadcrumb (the side whose
+  content can ellipsize). The control side is `flex: 0 0 auto` with no `min-width: 0` below it. Both
+  sides were shrinkable, and at 390px the sync button overflowed 30px INTO the page title, because a
+  `justify-content: flex-end` flex container overflows towards its start.
+- **`WidgetHeader`'s hero row**: the value → `DeltaBadge` gap is the 8px rhythm step
+  (`--vx-space-stack-sm`), not 4px, and the badge is centred on the value rather than baseline-aligned
+  to it.
+- **`WidgetHeader`'s title row** wraps below `sm`, so an `actions` slot too wide to sit beside the
+  title takes its own line instead of squeezing the heading to an ellipsis. A 30px kebab still fits
+  and still sits on the row. **Its metric row wraps too**: in a 2-up card grid at 390px
+  `$1294.9k ▲18.9%` rendered as `$129… ▲18.9%`, and truncating the number to protect the delta about
+  that number is the wrong way round. A short value still keeps its badge on the line.
+- **`StatCard`'s `actions` slot is the 24px tier now, not 30px.** `CtlSlot` gained `tier?: 'ctl' |
+'widget'` (default `'ctl'`, so no existing call site changes), and `StatCard` mounts its header slot
+  at `'widget'` — the `size="icon"` step `--vx-space-control-height-widget` has always named as
+  "`WidgetHeader tier="widget"` actions". A raw `ActionIcon` there rendered at the 30px `ctl` tier
+  inside a 28px header row and grew it to 30, so a KPI card WITH a kebab sat 2px below the card
+  beside it and every number in it with it. A consumer passing `<ActionIcon size="ctl">` explicitly
+  still gets 30px — and its card is 2px taller than its neighbours again, which is now visible rather
+  than accidental. The slot's `data-basalt-tier` marker reads `widget` there, the same value
+  `ChartCard` already writes by hand.
+- **The breadcrumb's ANCESTOR crumbs are hidden below `sm`** — only the page crumb renders. At 390px
+  the elastic side truncated `Overview / Dashboard` to `O… / D…`: two ellipses and a separator in
+  place of the one word that says where the reader is. CSS-only (law C9), so no flash and no hook.
+  `AppBreadcrumbs` gained one wrapper element around those crumbs; its props are unchanged.
+
+### Cursor — the shared cursor now partitions by x-domain kind, automatically
+
+Nothing removed. `CursorState` gained one field.
+
+| Component     | What changed                     | Why it matters                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CursorState` | gains `kind: DomainKind \| null` | No consumer action needed. The shared cursor now classifies each chart's x-domain (`'time' \| 'linear' \| 'band'`, derived from its own keys) and a broadcast whose kind differs from a chart's own is invisible to it — a categorical chart can no longer be mistaken for a time chart. `ChartCursorScope` is no longer required to keep a categorical chart from following a time chart; it still isolates two charts that share the same domain kind but are semantically unrelated. |
+
+## 1.24.0 — `QueryState`, table body chrome, four false greens
 
 **Nothing removed or renamed. Twelve new runtime exports on `.`/`./query`, plus table props.** Every
 API entry is additive; the behaviour changes are in the guard and the CLI, listed after them.
@@ -170,6 +912,32 @@ scaffold a second consumer: the refusal is keyed on the RESOLVED project and run
   and no other consumer holds a single `.astro`, `.vue` or `.jsx` file, so grace would have covered
   zero incumbent violations.
 
+## 1.25.0 — `manualPagination` imposes a contract
+
+**Nothing removed or renamed — a behaviour change, additive props only.** `manualPagination` made
+`data` one server page but left every other client-side control armed: sorting reordered that page
+under a header chevron while "Showing 1–25 of 412" presented it as a sort of all 412 — a plausible,
+wrong answer with nothing on screen to give it away. argo found it on 1.24.0 and worked around it
+with an explicit `enableSorting={false}`.
+
+Adopting `manualPagination` now imposes a contract, checked from props at render:
+
+| With `manualPagination`   | Resolve it with                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| the pagination bar itself | `enablePagination` (without it `manualPagination` is inert) + `rowCount`/`pageCount` |
+| sorting                   | the new `manualSorting` + sort in `onSortingChange`, or `enableSorting={false}`      |
+| `enableGlobalFilter`      | the new `manualFiltering` + filter in `onGlobalFilterChange`                         |
+| `facets`                  | `manualFiltering` + the new `onColumnFiltersChange`                                  |
+
+Unresolved, it **throws in dev** naming every breach at once; a production bundle degrades instead —
+no sort headers, no filter controls, no "of N" it cannot stand behind, plus one `console.error`. A
+bare `<BasaltDataTable data columns />` (no `manualPagination`) is byte-identical — no opt-out
+needed for a client-side table.
+
+Sibling defect fixed with it: the empty-state branch keyed off `data.length`, so a search or page
+index matching nothing left `data` non-empty and rendered a `<tbody>` with no rows AND no message.
+It now keys off the rendered row model.
+
 ## 1.23.1 — the band-state throw, the tag gate, a CLI that answers
 
 **One type widened, nothing removed or renamed.** `BandStripSeries.formatValue` is now
@@ -231,7 +999,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.**
 
@@ -402,7 +1170,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
@@ -410,7 +1178,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                                     |
 | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
@@ -583,7 +1351,7 @@ with the whole lint half off).
 
 | Surface                                                          | Note                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt.profile: 'tokens-only'` / `--tokens-only`                | disables the 17 kinds whose remedy is a Mantine component, prop or the React theme factory. `check-theme` requires it DECLARED; `doctor` infers it, because its profile only changes advice, never enforcement                                                                                                                                                                                                                               |
+| `basalt.profile: 'tokens-only'` / `--tokens-only`                | disables the 19 kinds whose remedy is a Mantine component, prop or the React theme factory. `check-theme` requires it DECLARED; `doctor` infers it, because its profile only changes advice, never enforcement                                                                                                                                                                                                                               |
 | `basalt.include: [...]`                                          | scan a named file outside `roots` — and the only route to a `.json`, which is never blanket-scanned                                                                                                                                                                                                                                                                                                                                          |
 | `basalt.roots` + a `lint:basalt` script                          | written by `init` from the real layout; `init` on an existing app is a lint-debt event, not a no-op                                                                                                                                                                                                                                                                                                                                          |
 | `tokens:css --check`, `--selector-class <c>` (+ `--light-class`) | drift gate; the Tailwind `<html class="dark">` convention. There is no `scheme: { class }` API — the class form is CLI-only                                                                                                                                                                                                                                                                                                                  |
@@ -697,23 +1465,47 @@ 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.15.0 as `warn` | still `warn` — widened again at 1.21.0; grace restarts with the widening |
-| `basalt/chart-legend-literal`      | 1.15.0 as `warn` | still `warn` — widened at 1.20.0                                         |
-| `basalt/shadow-basalt-export`      | 1.20.0 as `warn` | may stay `warn` permanently — widened at 1.21.0, narrowed at 1.22.0      |
-| `basalt/hand-rolled-shell`         | 1.20.0 as `warn` | —                                                                        |
+| 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.28.0'` — re-dated on 9 measured cross-file overlay warns in argo |
+| `raw-selection-control` (guard kind)   | 1.26.0 as `warn` | still `warn`, `promote: '1.28.0'` — the text lane of the row above                          |
 
 `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 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
+"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.
+
 **Rule-id rename at 1.1.0:** `basalt/import-boundary` split into `basalt/visx-boundary`,
 `basalt/visx-tooltip` and `basalt/token-layer-boundary` (the last is repo-local and deliberately not
 in the shipped preset). A config still naming `import-boundary` after 1.1.0 disables nothing.