basalt-ui 1.27.0 → 1.29.0

package/agent/rules/basalt-charts.md

@@ -6,8 +6,8 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — chart-missing-aria-label, raw-color-fn, raw-hex, raw-visx-axis, unframed-chart · oxlint rules — basalt/chart-in-raw-surface, basalt/chart-legend-literal, basalt/hand-rolled-plot, basalt/visx-boundary, basalt/visx-tooltip -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
+<!-- backed by: guard kinds — chart-missing-aria-label, raw-color-fn, raw-hex, raw-visx-axis · oxlint rules — basalt/chart-in-raw-surface, basalt/chart-legend-literal, basalt/hand-rolled-plot, basalt/visx-boundary, basalt/visx-tooltip -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
@@ -26,21 +26,18 @@ the hover/keyboard overlay and the derived tooltip. The caller supplies `series`
 render prop that draws **only marks**.
 
 Reaching past it for an axis, a tooltip or a margin means the chart has drifted. `basalt/hand-rolled-plot`
-enforces this per NODE: a chart-assembly primitive rendered in a file that does not compose
-`CartesianChart` is a finding, waived one node at a time with `theme-allow hand-rolled-plot — <why>`.
-
-**Five shipped shapes are the declared exceptions**, by shape, not by preference: `DualPanel` (two
-panes), `MirroredBars` (two bar panes on one baseline), `BandStrip` (no y dimension at all), `Donut`
-(radial) and `Heatmap` (a matrix). They compose `ChartFrame` + `useChartCursor` + `autoMargin` +
-`ChartTooltipFloat` directly. The first three carry a `theme-allow-file hand-rolled-plot — <why>`
-declaration; `Donut` and `Heatmap` render no assembly primitive, so nothing fires and there is
-nothing to waive. A genuinely non-single-plot bespoke shape declares itself the same way — file
-scope, spelled, with a reason. The module that DEFINES `CartesianChart` is exempt definitionally: a
-rule saying "compose X" cannot fire inside X.
-
-**A documented limit:** the rule keys on those visx primitives, so a chart drawn with DOM nodes or a
-hand-assembled `<svg>` is structurally invisible to it. Compose the primitive because it is the
-contract, not because lint will catch you.
+enforces this per NODE, waived one node at a time with `theme-allow hand-rolled-plot — <why>`.
+
+**Five shipped shapes are the declared exceptions**, by shape, not preference: `DualPanel` (two
+panes), `MirroredBars` (two bar panes, one baseline), `BandStrip` (no y dimension), `Donut`
+(radial), `Heatmap` (matrix). They compose `ChartFrame` + `useChartCursor` + `autoMargin` +
+`ChartTooltipFloat` directly. The first three carry `theme-allow-file hand-rolled-plot — <why>`;
+`Donut`/`Heatmap` render no assembly primitive, so nothing fires. A bespoke non-single-plot shape
+declares itself the same way. `CartesianChart`'s own defining module is exempt definitionally.
+
+**A documented limit:** the rule keys on visx primitives, so a DOM- or hand-`<svg>`-drawn chart is
+structurally invisible to it. Compose the primitive because it's the contract, not because lint
+catches you.
 
 ## `series` is the single source of truth
 
@@ -57,74 +54,58 @@ minus whatever the legend has toggled off, and the legend toggles by default at
 
 ## Boundaries (three independent rules, no escape hatch)
 
-- **`@visx/*` only inside a `charts/` path segment** (`basalt/visx-boundary`, shipped AND repo-local).
-  Need a raw visx primitive? Import it from `basalt-ui/charts`, which re-exports the curated set, and
-  keep your bespoke chart file under a `charts/` directory.
+- **`@visx/*` only inside a `charts/` path segment** (`basalt/visx-boundary`, shipped AND
+  repo-local) — import a raw visx primitive from `basalt-ui/charts`'s curated re-export instead.
 - **`@visx/tooltip` is banned everywhere**, charts included (`basalt/visx-tooltip`) — use
-  `ChartTooltipFloat` + `TooltipHeader`/`TooltipRow`/`TooltipBody`. It portals to `document.body`, so
-  it can be authored anywhere including inside an `<svg>`; a plain `<div>` there mounts in the SVG
-  namespace, typechecks, lints, throws nothing, and never paints.
-- **basalt's own `charts/` and `tokens/` import zero `@mantine/*`** (`basalt/token-layer-boundary`,
-  repo-local by design). That is a framework invariant, not an obligation on your app's own
-  `charts/`-named directory: it keeps the token layer upstream of Mantine and lets
-  `basalt-ui/charts` + `basalt-ui/tokens` resolve with no Mantine installed.
-- Because Mantine layout primitives are unreachable inside a chart file, `inline-display` and
-  `raw-html-layout` deliberately do NOT fire there — the finding would be unactionable. Raw `<div>`
-  is fine in a chart file; `VX.*` tokens are still mandatory. Reach for `ChartCenter` to center.
-- **Maps are not charts.** No map library is a `@visx/*` package, basalt ships no map kind, and the
-  boundary says nothing about one — build it wherever the rest of the app's non-chart UI lives, and
-  style its chrome with `--vx-*` so it matches.
+  `ChartTooltipFloat` + `TooltipHeader`/`TooltipRow`/`TooltipBody`. A plain `<div>` inside an
+  `<svg>` mounts in the SVG namespace, typechecks, lints, and never paints.
+- **basalt's own `charts/`+`tokens/` import zero `@mantine/*`** (`basalt/token-layer-boundary`,
+  repo-local — a framework invariant, not an obligation on your app's own `charts/`-named dir). It
+  keeps the token layer upstream of Mantine and lets both subpaths resolve with no Mantine
+  installed.
+- Mantine layout primitives are unreachable in a chart file, so `inline-display`/`raw-html-layout`
+  deliberately don't fire there — raw `<div>` is fine, `VX.*` tokens still mandatory
+  (`ChartCenter` to center).
+- **Maps are not charts** — no map library is `@visx/*`, basalt ships no map kind; build one where
+  the rest of the app's non-chart UI lives, styled with `--vx-*`.
 
 ## Color, scheme and margins
 
-- **Never a raw hex in a chart file**, and never `localStorage.getItem('theme')`. Theme reactivity is
-  **pure CSS**: the `--vx-*` variables are redeclared per scheme, so toggling restyles every chart
-  with no React re-render. Don't branch on the color scheme in JS.
+- **Never a raw hex in a chart file**, never `localStorage.getItem('theme')`. Theme reactivity is
+  **pure CSS**: `--vx-*` redeclares per scheme, so toggling restyles every chart with no React
+  re-render.
 - **Series color is consumer domain data** — one guard-exempt file per app, `defineSeries` →
-  `seriesTokens`/`groupTokens` → `buildPaletteCss` (basalt-tokens.md). A hue keeps its identity and
-  shifts shade across schemes, which is why every entry is a `{ light, dark }` pair.
-- **Margins are MEASURED, not hand-picked.** Every configured axis's tick labels run through
-  `autoMargin`/`measureText` before layout, so `VX.margin` is a floor and a wide label widens its own
-  gutter. Passing `y2` is what makes a chart dual-axis — the right margin widens by measurement, with
-  no manual nudge. `margin={{ side: n }}` is the per-side override, applied last.
-- **Derive constants from `VX.margin`** rather than copying a number into three chart files — those
-  are three silent-drift sites the moment the density scale is retuned.
-- **Never fake an empty dataset for a pending query.** "Nothing to draw" is three states, and
-  `data ?? []` collapses "not asked yet" into "measured and absent", which is a positive claim about
-  data nobody fetched. Pass `isPending`; every kind forwards it to one pending renderer that reserves
-  the plot's footprint and draws nothing that could be mistaken for a measurement.
-- **`ChartFrame`'s container is `role="group"`, never `role="img"`.** Every descendant of a
-  `role="img"` element is presentational, which erases the hover overlay's `role="slider"` from the
-  accessibility tree — silently, and jsdom does not implement the pruning, so no `getByRole` test can
-  catch the regression. Do not "simplify" it back.
+  `seriesTokens`/`groupTokens` → `buildPaletteCss` (basalt-tokens.md), each entry a `{light,dark}`
+  pair.
+- **Margins are MEASURED, not hand-picked** — every axis's tick labels run through
+  `autoMargin`/`measureText` before layout, so `VX.margin` is a floor. Passing `y2` is what makes a
+  chart dual-axis; `margin={{ side: n }}` overrides last. Derive constants from `VX.margin` rather
+  than copying a number into three files.
+- **Never fake an empty dataset for a pending query** — `data ?? []` collapses "not asked yet" into
+  "measured and absent". Pass `isPending`; every kind forwards it to one pending renderer.
+- **`ChartFrame`'s container is `role="group"`, never `role="img"`** — every descendant of a
+  `role="img"` element is presentational, which would erase the hover overlay's `role="slider"`
+  from the accessibility tree silently (jsdom doesn't implement the pruning, so no test catches it).
 
 ## Adding a chart
 
-1. **Fits a shipped kind?** Use it. The kinds are declarative — `data`, `chartId`, `getX`, `series`,
-   one `AxisConfig` per axis, zones/thresholds/refLines as plain arrays.
-2. **Second instance of a shape with no kind?** Extract a kind and migrate both call sites (Rule of
-   Three: not on the first, not past the third). **Prove a new kind by porting real call sites** and
-   shipping the "still cannot express" list with it — a demo page is written against the API that
-   already exists.
-3. **Genuinely unique?** Stay bespoke, composing `CartesianChart` (or `ChartFrame`) directly in the
+1. **Fits a shipped kind?** Use it — declarative props (`data`, `chartId`, `getX`, `series`, one
+   `AxisConfig` per axis, zones/thresholds/refLines as plain arrays).
+2. **Second instance of a shape with no kind?** Extract a kind (Rule of Three), migrating both call
+   sites; prove it by porting real call sites, ship the "still cannot express" list with it.
+3. **Genuinely unique?** Stay bespoke, composing `CartesianChart`/`ChartFrame` directly in the
    page's chart file, not in a shared kinds directory.
 
-Sparklines are the one exemption from the composition contract (no legend, no tooltip, no
-`CartesianChart`) — they still read `VX.*`.
-
-**Anti-pattern:** a single `<Chart type="…" config={…} />` that switches by kind. Prefer N small
-kinds, and if a chart doesn't fit the primitives, **add a kind — don't loosen the primitives.**
+Sparklines are the one exemption (no legend, no tooltip, no `CartesianChart`) — still `VX.*` only.
+**Anti-pattern:** a single `<Chart type="…" config={…} />` switching by kind — add a kind, don't
+loosen the primitives.
 
 ## The x axis is categorical, and the API does not say so
 
-`CartesianChart` builds x as a point scale over domain KEYS: N points are N evenly spaced positions
-whatever the values behind them. Correct and invisible for a regular grid; wrong for an event-shaped
-series, where two consequences are silent — equal spacing means a shared crosshair marks the right
-point at a different screen x than a regularly-sampled sibling, and two events at the same instant
-collapse onto one position with one of them dropped. `getX` returning a date string reads like a time
-axis and is not one. A chart whose x is a measured quantity needs a file declaration today.
-
-The cursor is likewise **shared page-wide by default** with no provider, resolved domain-aware
-(nearest parsed date/number within a chart's own step, not string equality) so a chart that folds its
-domain still tracks a sibling's hover. `ChartCursorScope` ISOLATES a subtree — it opts out of
-sharing, never into it.
+`CartesianChart` builds x as a point scale over domain KEYS — N evenly spaced positions whatever
+the values behind them. Wrong for an event-shaped series: a shared crosshair marks the wrong screen
+x against a regularly-sampled sibling, and two events at the same instant collapse onto one
+position. `getX` returning a date string reads like a time axis and is not one.
+
+The cursor is **shared page-wide by default**, resolved domain-aware (nearest parsed date/number
+within a chart's own step). `ChartCursorScope` ISOLATES a subtree — opts out of sharing, never in.

package/agent/rules/basalt-controls.md

@@ -1,14 +1,14 @@
 ---
 source: basalt-ui
-description: Where an interactive control may live and how it binds — the three homes, the ctl size tier, the store-bound filters and tabs of basalt-ui/controls, the mobile policy, and sidebar blocks. Enforced by basalt/hand-rolled-filter, control-outside-home, control-size-literal, responsive-twin and page-bar-budget.
+description: Where an interactive control may live and how it binds — the three homes, the ctl size tier, the store-bound filters and tabs of basalt-ui/controls, the mobile policy, and sidebar blocks. Enforced by basalt/hand-rolled-filter, control-outside-home, bound-control-outside-home, control-size-literal, responsive-twin and page-bar-budget.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — raw-selection-control · oxlint rules — basalt/control-outside-home, basalt/control-size-literal, basalt/hand-rolled-filter, basalt/responsive-twin -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
+<!-- backed by: guard kinds — raw-selection-control · oxlint rules — basalt/bound-control-outside-home, basalt/control-outside-home, basalt/control-size-literal, basalt/hand-rolled-filter, basalt/responsive-twin -->
 <!-- not guarded: C1 as a cross-file law (a control placed in one file, its home declared in another) -->
 <!-- not guarded: hand-rolled section headings (argo writes `<Text fw={600} size="sm">` + children, which no AST heuristic matches without false positives) -->
 <!-- not guarded: C11 — a table/list stating its count when it is not a BasaltDataTable -->
@@ -23,24 +23,24 @@ size tier and one persistence binding, and basalt owns all three. The API is in
 
 ## The laws
 
-| #   | Law                                                                                                                                                                 |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| C1  | A control lives in exactly ONE of three homes — the page bar, a section/widget header, or a form row — entered only through a slot prop.                            |
-| C2  | A basalt filter or tab has no `value`/`onChange`; it takes `field` and owns both the URL write and the localStorage mirror.                                         |
-| C3  | Tab and filter state never lives in `useState` — it derives from a store field on the URL lane or the local lane.                                                   |
-| C4  | Every field declares its lanes once, at definition, and resolves URL ⊳ localStorage ⊳ fallback uniformly for every field kind.                                      |
-| C5  | The HOME sets the size tier; an element inside a home slot carries no `size`, `w`, `fullWidth`, `visibleFrom` or `hiddenFrom`.                                      |
-| C6  | A page has one `PageBar`; its `actions` hold ≤5 entries and exactly one `primary`; a `Section` holds ≤3.                                                            |
-| C7  | A home never scrolls horizontally and never wraps — overflow folds into a `More` menu or a `Filters (n)` sheet, computed by basalt from typed data.                 |
-| C8  | Every section, card or table title is a `WidgetHeader`; the page title is the breadcrumb (or `PageBar.title` with no shell). An in-body h1/h2 is an error.          |
-| C9  | A responsive swap belongs to the control — rendering the same control twice under `visibleFrom`/`hiddenFrom` is an error.                                           |
-| C10 | A nav link carrying a store field passes `store.linkSearch` by reference; a `search:` literal in a nav definition, or a literal `useSearch({ from })`, is an error. |
-| C11 | Every table or list inside a section states its count in its header.                                                                                                |
-| C12 | Refresh/sync has ONE shape, `SyncButton`, whose `scope` picks the home (`global` → the shell header, `page` → `PageBar.sync`).                                      |
-| C13 | Sidebar blocks are declared data (`SidebarBlock[]`), never `ReactNode` slots, so rail and More-sheet projection stay basalt's.                                      |
-| C14 | An empty home renders nothing, so no route pays for a reserved row.                                                                                                 |
-| C15 | Every touch target inside a home clears the `touchControlHeight` floor below `sm`; sheet rows use `sheetRowHeight`.                                                 |
-| C16 | A new guard lands `warn` with a dated `promote` version, and the build fails once the package version reaches it while the rule is still `warn`.                    |
+| #   | Law                                                                                                                                                                                                        |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| C1  | A control lives in exactly ONE of three homes — the page bar, a section/widget header, or a form row — entered only through a slot prop.                                                                   |
+| C2  | A basalt filter or tab has no `value`/`onChange`; it takes `field` and owns both the URL write and the localStorage mirror.                                                                                |
+| C3  | Tab and filter state never lives in `useState` — it derives from a store field on the URL lane or the local lane.                                                                                          |
+| C4  | Every field declares its lanes once, at definition, and resolves URL ⊳ localStorage ⊳ fallback uniformly for every field kind.                                                                             |
+| C5  | The HOME sets the size tier; an element inside a home slot carries no `size`, `w`, `fullWidth`, `visibleFrom` or `hiddenFrom`.                                                                             |
+| C6  | A page has one `PageBar`; its `actions` hold ≤5 entries and exactly one `primary`; a `Section` holds ≤3.                                                                                                   |
+| C7  | A home never scrolls horizontally and never wraps — overflow folds into a `More` menu or a `Filters (n)` sheet, computed by basalt from typed data.                                                        |
+| C8  | Every section, card or table title is a `WidgetHeader`; the page title is the breadcrumb (or `PageBar.title` with no shell). An in-body h1/h2 is an error.                                                 |
+| C9  | A responsive swap belongs to the control — rendering the same control twice under `visibleFrom`/`hiddenFrom` is an error.                                                                                  |
+| C10 | A nav link carrying a store field passes `store.linkSearch` by reference; a `search:` literal in a nav definition, or a literal `useSearch({ from })`, is an error.                                        |
+| C11 | Every table or list inside a section states its count in its header.                                                                                                                                       |
+| C12 | Refresh/sync has ONE shape, `SyncButton`, whose `scope` picks the home (`global` → the shell header, `page` → `PageBar.sync`).                                                                             |
+| C13 | Sidebar blocks are declared data (`SidebarBlock[]`), never `ReactNode` slots, so rail and More-sheet projection stay basalt's.                                                                             |
+| C14 | An empty home renders nothing, so no route pays for a reserved row.                                                                                                                                        |
+| C15 | Every touch target inside a home clears the `touchControlHeight` floor below `sm`. The mobile `Filters (n)` sheet draws no row of its own — it renders the same `PanelRow` the aside's panel surface does. |
+| C16 | A new guard lands `warn` with a dated `promote` version, and the build fails once the package version reaches it while the rule is still `warn`.                                                           |
 
 C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTable` and C12 are
 **advisory** — the generated header above says so. A green lint run is not evidence they hold.
@@ -53,20 +53,18 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `Section`                                                                         | `actions`, `tabs`                                  | `ctl`        | that section's own controls and its count  |
 | `WidgetHeader` / `ChartCard` / `StatCard` / `BasaltDataTable` / `SettingsSection` | `actions`                                          | `ctl`        | that widget's own controls and its count   |
 | `SettingsRow`                                                                     | `control`                                          | Mantine `md` | ONE form field, bound to a setting         |
-
-- **Inside `BasaltShell`**, `PageBar` row 1 portals into the header (the breadcrumb stays the lead)
-  and row 2 renders in-flow, sticky, publishing its measured height as `--basalt-page-bar-h` for a
-  sticky table or a full-height pane to offset against. Without a shell, both rows render in flow with
-  `title` + `icon` leading. The header height is a token on every viewport — never React state.
-- **The form row is a real home, and it keeps Mantine's own `md` tier.** A raw `Select` bound to a
-  setting is the right answer in `SettingsRow.control`, and the `size` prop there is load-bearing
-  rather than redundant. `SettingsRow` is not a tiered slot, and no filter or size rule applies to it.
-- **A control's home is a decision about reach**: it belongs next to what it acts on. If it affects
-  more than one widget it is promoted to the page bar; if it formats one widget it stays in that
-  widget's header.
-- **An overlay rendered by the PARENT is exempt by FILENAME**: `control-outside-home` and
-  `raw-selection-control` skip a file basenamed `*-{modal,drawer,popover,panel,form}.tsx`, since no
-  scan of it sees the `<Modal>`. Outside that: `theme-allow-file control-outside-home — overlay`.
+| `FormRow` / `FormGroup` (`basalt-ui/forms`)                                       | children                                           | Mantine `md` | ONE form field or a labelled cluster       |
+
+- **Inside `BasaltShell`** both `PageBar` rows are portals (header / the band above the scrollport)
+  — where you write `<PageBar>` never moves it. Without a shell both rows render in flow, sticky.
+  The header height is a token, never state.
+- **The form row keeps Mantine's own `md` tier** — a raw `Select` in `SettingsRow.control` is the
+  right answer, `size` there is load-bearing. Neither `SettingsRow` nor `FormRow`/`FormGroup` is a
+  tiered slot; no filter or size rule applies to them.
+- **A control's home is a decision about reach**: affects more than one widget → promote to the
+  page bar; formats one widget → stays in that widget's header.
+- **An overlay rendered by the PARENT is exempt by FILENAME** — `*-{modal,drawer,popover,panel,form}.tsx`.
+  Outside that: `theme-allow-file control-outside-home — overlay`.
 
 ## The `ctl` tier — the home sizes the control
 
@@ -78,13 +76,11 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `touchControlHeight`  | hit area below `sm`                                        | every home                                          |
 | `controlHeight`       | `size="md"`                                                | forms — unchanged                                   |
 
-Each home wraps its **slot** — never its body — in a hoisted theme provider that defaults every
-Mantine control inside it to `size="ctl"`, plus a `data-basalt-tier` attribute. So a raw `Button`
-dropped into `PageBar.actions` is already the right height with no prop, and a `size="xs"` typed
-there is law C5 (`basalt/control-size-literal`). Mantine's own `sm`/`xs` are NOT re-pointed: a
-`size="sm"` in a modal or a form keeps Mantine's height. One exception, by boundary:
-`ChartCard.actions` lives inside the Mantine-free chart layer, so it cannot mount the slot theme —
-it carries only the tier attribute, and the basalt controls placed there size themselves.
+Each home wraps its **slot** — never its body — in a hoisted theme provider defaulting every
+Mantine control inside it to `size="ctl"`. A raw `Button` in `PageBar.actions` is already the right
+height with no prop; a `size="xs"` typed there is law C5 (`basalt/control-size-literal`). Mantine's
+own `sm`/`xs` are NOT re-pointed elsewhere. Exception: `ChartCard.actions` is Mantine-free, so it
+carries only the tier attribute and its controls size themselves.
 
 ## Binding a control to a store
 
@@ -103,58 +99,56 @@ import { DateRangePicker } from 'basalt-ui/controls-dates'
 ```
 
 The store, its fields and their lanes are basalt-state.md. What this file adds: **the control takes
-`field` and nothing else about state.** No `value`, no `onChange`, no `size` — those props do not
-exist, so a wrong call site is a tsc error rather than a review comment. `ActionGroup`,
-`OverflowMenu` and `SyncButton` sit on the same subpath and take typed action DATA, never children.
+`field` and nothing else about state** — no `value`, no `onChange`, no `size`, so a wrong call site
+is a tsc error. `ActionGroup`/`OverflowMenu`/`SyncButton` take typed action DATA, never children.
 
-**The date picker is injected, never imported.** `basalt-ui/controls` resolves and renders with no
-`@mantine/dates` installed, which is what lets a consumer without a date picker use every other
-control; `DateRangePicker` comes from `basalt-ui/controls-dates` through `RangeFilter.customPicker`.
-Never import `@mantine/dates` from a shared module, and never reach for `DateInput`/`DatePickerInput`
-inside a home slot.
+**The date picker is injected, never imported.** `basalt-ui/controls` resolves with no
+`@mantine/dates` installed; `DateRangePicker` comes from `basalt-ui/controls-dates` through
+`RangeFilter.customPicker`. Never import `@mantine/dates` from a shared module or reach for
+`DateInput`/`DatePickerInput` inside a home slot.
 
 ## `FilterSet` owns the responsive story
 
 Do not build one at the call site. Above `sm`, `FilterSet` measures its own children and folds the
-tail into a `+N` pill rather than wrapping or scrolling. Below `sm`, the first `inline` children stay
-pills and one `Filters (n)` pill opens a bottom sheet where every child renders full-width, applies
-immediately, and answers one `Reset all`. **`n` and `Reset all` are DERIVED** from whether each field
-differs from its fallback — so adding a filter is one JSX line, with no count to maintain and no
-reset handler to extend.
-
-| Below `sm`       | What basalt does                                                                          |
-| ---------------- | ----------------------------------------------------------------------------------------- |
-| `PageBar` row 1  | breadcrumb · the `primary` action as an icon · ONE kebab holding every `more` action      |
-| `PageBar` row 2  | `ViewTabs` full-width (a `Select` past three options) · one inline pill · `Filters (n)`   |
-| a section header | title · count · one inline action, the rest in a kebab; tabs past three become a `Select` |
-| a widget header  | value + delta wrap under the title; the sparkline drops to bleed; one `⋯` action          |
-| a sheet row      | full-width, `sheetRowHeight`, applies immediately                                         |
-
-Every swap is CSS inside the control (one mount), never a JS media query — a media-query hook renders
-differently on the server than on the first client paint. Two mounts under
+tail into a `+N` pill. Below `sm`, the first `inline` children stay pills and one `Filters (n)`
+pill opens a sheet where every child renders full-width and answers one `Reset all`. **`n` and
+`Reset all` are DERIVED** from whether each field differs from its fallback — adding a filter is
+one JSX line, no count or reset handler to maintain.
+
+| Below `sm`       | What basalt does                                                                                                                   |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `PageBar` row 1  | breadcrumb · the `primary` action as an icon · ONE kebab holding every `more` action                                               |
+| `PageBar` row 2  | line 1: `ViewTabs` full-width (a `Select` past three options) · line 2: one inline pill · `Filters (n)` · the aside's `Panel` pill |
+| a section header | title · count · one inline action, the rest in a kebab; tabs past three become a `Select`                                          |
+| a widget header  | value + delta wrap under the title; the sparkline drops to bleed; one `⋯` action                                                   |
+
+Every swap is CSS inside the control (one mount), never a JS media query. Two mounts under
 `visibleFrom`/`hiddenFrom` is `basalt/responsive-twin`.
 
+## The aside
+
+`PageAside` is a shell REGION, not a fourth home — C1 still names three. Its body IS a home: it
+scopes children to the `panel` surface, so the same `SelectFilter` that is a pill in the page bar
+is a ROW in the aside — never two components, the surface is read from where it's mounted.
+
+| In the aside     | Write                                                                             |
+| ---------------- | --------------------------------------------------------------------------------- |
+| an inspector row | `PanelRow` — label above, optional `hint`, mono `readout`, `end` slot             |
+| a bound slider   | `SliderControl` — min/max/step come off the handle, never props                   |
+| a facet list     | `MultiSelectFilter` + `counts` (and `max`, past which the tail folds)             |
+| a group of rows  | `Section` — flush inside the aside, which draws the rhythm itself                 |
+| a choice         | `PanelChoice` — a track only while ≤3 options AND every label fits, else `Select` |
+
+- ONE `PageAside` per page, written AFTER the main content — it portals into the region from `sm`
+  up, its tree position is reading order, not layout.
+- Below `sm` it projects into `PageBar` row 2 as one `Panel` pill; with no row 2 — or shell-less —
+  it renders in flow. One node either way (C9).
+- A bound control outside all of this is `basalt/bound-control-outside-home` — a slot prop, a
+  `FilterSet`, a `PageAside` or a `PanelRow` is a home; nothing else is.
+
 ## Sidebar blocks
 
 A non-destination list, a progress meter or a bespoke node in the sidebar is a `SidebarBlock` —
-declared data, three kinds (`list` / `progress` / `custom`), placed `'nav'` or `'bottom'`. Because it
-is data, basalt owns what a `ReactNode` slot could not express: a rail dot or ring when the desktop
-sidebar is collapsed, a persisted fold, and one More-sheet row per block on mobile opening a sheet of
-its items. A `custom` block is desktop-only, by design.
-
-## Anti-patterns
-
-| Instead of                                                   | Write                                                 |
-| ------------------------------------------------------------ | ----------------------------------------------------- |
-| `useState` + a `SegmentedControl` in the page body           | a store field + `ViewTabs` in the home's `tabs` slot  |
-| a raw `Select`/`MultiSelect`/`Chip.Group` as a filter        | `SelectFilter` / `MultiSelectFilter`                  |
-| a numeric threshold widened into a string enum               | `field.number` + `NumberFilter`                       |
-| `<X visibleFrom="sm"/>` beside `<X hiddenFrom="sm"/>`        | one control — the swap is already inside it           |
-| `size="xs"` on a button in a home slot                       | nothing; the home sets the tier                       |
-| a hand-written `presetToParams`                              | `field.toWindow(value)`                               |
-| a hand-counted `Filters (3)` badge                           | nothing; `FilterSet` derives it                       |
-| `overflowX: 'auto'` on a filter row                          | nothing; the fold is basalt's                         |
-| a local `Section` / `PageHeader` / `RefreshButton`           | `Section` / `PageBar` / `SyncButton`                  |
-| an in-body `<Title order={1}>`                               | the route's breadcrumb title                          |
-| the same on a shell-less surface (auth gate, error boundary) | `theme-allow in-body-page-title — shell-less surface` |
-| a hand-built joined button row                               | `ControlGroup` (or `group: true` on the actions)      |
+declared data, three kinds (`list`/`progress`/`custom`), placed `'nav'`/`'bottom'`. Because it's
+data, basalt owns what a `ReactNode` slot couldn't: a rail dot/ring when collapsed, a persisted
+fold, one More-sheet row per block. A `custom` block is desktop-only, by design.