basalt-ui 1.24.0 → 1.26.0

package/MIGRATING.md

@@ -32,13 +32,497 @@ 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`.
+**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 forces to promote or be deleted at 1.27.0. 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; two of the ten land `error`, the
+rest `warn` under a dated C16 grace entry.** 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 |
+
+**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.
@@ -85,7 +569,7 @@ New: `maxHeight`, `minWidth`, `stickyHeader`, `stickyHeaderOffset`, `verticalSpa
 defaults to `true` in basalt, overriding Mantine's `false`; every other one is a conditional
 pass-through, so omitting it keeps Mantine's default.
 
-**Porting argo's three tables onto them made them 341 → 370 lines. 29 LONGER.** argo named these
+**Porting argo's three tables onto them made them 341 → 370–379 lines. 29–38 LONGER.** argo named these
 props as the reason the tables stayed hand-rolled, and adding them shortened nothing: column defs
 cost more than JSX rows when every cell is bespoke — eight accessor blocks at 4–6 lines each against
 an eight-`<Table.Td>` row at ~3. **The ask was mis-specified.** Adopt them for what they buy —
@@ -170,6 +654,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
@@ -583,7 +1093,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 +1207,39 @@ 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` | **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**                                                        |
 
 `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
+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,
+`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.