basalt-ui 1.30.2 → 1.31.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 
 | Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useBreakpoint, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass (useBreakpoint on notice), NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `basalt-ui/charts`          | headless        | CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+# [1.31.0](https://github.com/jkrumm/basalt-ui/compare/v1.30.2...v1.31.0) (2026-09-28)
+
+
+### Bug Fixes
+
+* card and legend correctness — hysteresis, dots fit, slot ownership ([890658f](https://github.com/jkrumm/basalt-ui/commit/890658fc6ac5d2ffac1e04b79f6ec8d33f73e583))
+* close responsive-guard gaps and dedupe measured-fold/hit-floor internals ([d37d9c2](https://github.com/jkrumm/basalt-ui/commit/d37d9c29151a65ffc83a9cce9344e602b223bfce))
+* economise chart axis space with a shared y-placement ladder ([05562c7](https://github.com/jkrumm/basalt-ui/commit/05562c748bff5b6f2bf62b020e6d112463e615d1))
+* give the plot its space — inside-y floor, wrap law, height clamp ([16e3e18](https://github.com/jkrumm/basalt-ui/commit/16e3e189c62170151d72014000140726c94a2204))
+* keep a committed chart pin through a cancelled second press ([53e0264](https://github.com/jkrumm/basalt-ui/commit/53e0264343ffd2c06fe666bc916d6159c28ab16d))
+* make chart touch presses provisional and dismiss on scroll ([c0ee0ae](https://github.com/jkrumm/basalt-ui/commit/c0ee0ae17cb6ecaf91183107b26c7f35a026b83f))
+* resolve the pre-release review findings ([a33b6dd](https://github.com/jkrumm/basalt-ui/commit/a33b6ddd58519912698f3dc5b7a6a2c7ff5adf92))
+* thin rotated x labels by projected width, default charts to regular ([105b12d](https://github.com/jkrumm/basalt-ui/commit/105b12d36900846212c7cf91eb6361fe4a554ae5))
+* touch floors, filter hit gap, form-row container width, composer padding ([a12f230](https://github.com/jkrumm/basalt-ui/commit/a12f230963270a8785070b6711768204548fe02d))
+
+
+### Features
+
+* adopt the pointer-tier hit area, gate hover reveals, sheet the modal ([3a63850](https://github.com/jkrumm/basalt-ui/commit/3a63850b489190927d221eaea62d67dd1a8d1f62))
+* drop the dead chart-tier API and consolidate media-query hooks ([b255dcf](https://github.com/jkrumm/basalt-ui/commit/b255dcf5d408b34bec76a4b6a9e5da712e27fa52))
+* fit chart legends by measured width, fold donut and label line ends ([5f0c5bd](https://github.com/jkrumm/basalt-ui/commit/5f0c5bd16cd3abd0b7772da991321ceaff8a1477))
+* fold chart-card headers by height, not width alone ([9d7fc88](https://github.com/jkrumm/basalt-ui/commit/9d7fc889c5981b08db8bd47908a6598c94a55999))
+* fold DataTable columns, warn short rows, sheet the TOC, pin composer keys ([f3bd775](https://github.com/jkrumm/basalt-ui/commit/f3bd775a57411bcb42a0ff49cfc3ae3a80d5a162))
+* fold short-card chart legends to dots, ship the raw-breakpoint guards ([2557d9d](https://github.com/jkrumm/basalt-ui/commit/2557d9dc88438cbb88e0b7a90c572c69dd79c827))
+* key card chrome on the card's own width ([aa407b8](https://github.com/jkrumm/basalt-ui/commit/aa407b866a0d9b343ce5b48f2b3c8f2b60341888))
+* pin chart tooltips on tap, add keyboard parity to donut and heatmap ([a9cc50a](https://github.com/jkrumm/basalt-ui/commit/a9cc50aa6dd0626e3d312eba068cf95bbf50817b))
+* resolve chart layout from the container class, height from width ([ae9632c](https://github.com/jkrumm/basalt-ui/commit/ae9632c010f58c02f49659cec1343bb8c1e23540))
+* size-class shell docking, measured page-bar fold and toast bottom inset ([1fd619d](https://github.com/jkrumm/basalt-ui/commit/1fd619db7f58d81b60b20832b6353968b957c905))
+* spend compact-width axes on the plot, not the gutters ([b0d5b49](https://github.com/jkrumm/basalt-ui/commit/b0d5b49f442a471f1a53b2fb57c90144efb66095))
+* three-axis responsive foundations and --vx-hit ([6609ec1](https://github.com/jkrumm/basalt-ui/commit/6609ec1d62d189184dd512c12334963fb8fe0b84))
+
 ## [1.30.2](https://github.com/jkrumm/basalt-ui/compare/v1.30.1...v1.30.2) (2026-09-09)
 
 

package/MIGRATING.md

@@ -66,18 +66,18 @@ There is one row per SURFACE, not per export, and a surface earns a row once any
 shipped lefthook preset both changed in 1.30.0 with no row that owned them — which is how a
 consumer read this index, found nothing, and diffed a KPI row that had silently gone 4-up → 2-up.
 
-| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | Unreleased |
-| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ---------- |
-| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | —          |
-| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | —          |
-| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | —          |
-| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —          |
-| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —          |
-| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —          |
-| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —          |
-| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —          |
-| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —          |
-| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —          |
+| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                    | Unreleased |
+| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | ---------- |
+| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ Unreleased)                                         | —          |
+| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ Unreleased)                                                       | —          |
+| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ Unreleased) | —          |
+| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
+| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
+| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
+| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                         | —          |
+| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                         | —          |
+| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
+| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                         | —          |
 
 ---
 
@@ -86,6 +86,166 @@ consumer read this index, found nothing, and diffed a KPI row that had silently
 _Nothing yet. Author the next section under this heading as `## Unreleased — <title>`; the
 release renames it and opens a new one here._
 
+## 1.31.0 — size classes and the pointer tier
+
+`theme.breakpoints` is now derived from `SIZE_CLASSES` (compact < 840, medium 840–1199, expanded
+≥ 1200) and **no longer overridable** — `createBasaltTheme` drops a `breakpoints` override and types
+it out. Mapping: `xs` = `sm` = 52.5em (medium opens), `md` = `lg` = `xl` = 75em (expanded opens) — the
+keys collapse. So `xs` moves 36em → 52.5em, `sm` 48em → 52.5em (an iPad portrait is now bottom-bar chrome), `md`
+62em → 75em, `lg` stays 75em and `xl` 88em → 75em. Check every `visibleFrom`/`hiddenFrom`/`useBreakpoint`
+on those keys: `xs` no longer differs from `sm`, and `md`/`lg`/`xl` now switch at the same width.
+
+| Removed                                                                                                                     | Replacement                                                                                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VX.spaceTouchTarget`, `--vx-space-touch-target`                                                                            | `VX.hit`, `--vx-hit` (24px on fine pointers, 44px under `(pointer: coarse)`)                                                                                                          |
+| `VX.space.touchControlHeight`, `--vx-space-touch-control-height`                                                            | `VX.hit`; density-exempt, so it no longer tracks the knob                                                                                                                             |
+| `DESKTOP_SECONDARY_MAX` (`./controls`)                                                                                      | none — `PageBar` row 1 folds secondary actions by its measured width (icon-only, then into `More`); removed with no grace window because nothing but the row's own count read it      |
+| `resolveChartTier`, `chartTierMetrics`, `useChartTier`, `useChartTierMetrics`, `ChartTier`, `ChartTierMetrics` (`./charts`) | none — removed, no grace: zero consumers. Chart chrome sizes follow the measured container class internally; there is no public tier API to read it from                              |
+| `VX.phoneChartWidth`                                                                                                        | `CONTAINER_CLASSES.regular` (`basalt-ui/tokens`) — removed, no grace: zero consumers, and the constant no longer drove any resolution                                                 |
+| `ResponsiveChartHeight.sm/md/lg`                                                                                            | `regular` / `wide` — removed, no grace: zero consumers                                                                                                                                |
+| `legend.mode` (every kind's `ChartLegendConfig`, `ChartFrameLegend`)                                                        | none — the resolver's own 'dots'/'chips' pick is the law; a speculative escape hatch with zero consumers that could silently re-open the plot-eating legend the wave-11 chain removed |
+| `BasaltProvider host`                                                                                                       | none — `<html data-basalt-host>` is now always auto-detected (`pwa`/`web`); re-add when a Capacitor/Tauri consumer is named                                                           |
+
+| Changed                                                                                                                   | Notes                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Themed `Modal` is a bottom sheet below the `medium` size class; `./content` hover-reveal affordances are visible on touch | Opt out of the sheet by overriding `classNames.inner`/`content`/`body`. A consumer `attributes` (Switch/Checkbox/Radio) or `closeButtonProps` (Modal) replaces the shipped `data-basalt-hit` shallowly — re-add `'data-basalt-hit': true` where needed. |
+
+`--vx-space-mobile-nav-row-height` is 44px (was 40). A hit overlay is `[data-basalt-hit]` in
+`styles.css`; the home controls' overlays now key on `(pointer: coarse)` instead of width.
+
+**A touch press on a chart is now PROVISIONAL, not pinned on contact** (behaviour change; `useChartCursor`'s exported `ChartCursor<T>` type gains a required `onPointerUp` field and widens `onPointerLeave` to take the pointer event — source-compatible for the normal `{...cursor}`/JSX-prop usage every shipped kind and consumer chart uses, but a manual `cursor.onPointerLeave()` call with no argument now throws). `pointerdown` still resolves and shows immediately; `pointerup` for that pointer commits the pin; a `pointercancel`/`pointerleave` before commit (the browser taking the gesture as a scroll) clears the readout instead of leaving it pinned. A pinned tooltip is now also dismissed by a `document` scroll and by Escape from anywhere in the document, not just an overlay that holds focus. A bespoke chart wired directly to `HoverOverlay` (the five declared non-`CartesianChart` shapes, or a consumer's own) needs to pass through the hook's new `onPointerUp`/`onUp` the same way it already passes `onDown`/`onMove`.
+
+**Chart axes economise space at `compact`/`micro` container width** (behaviour change, no API change).
+Y labels draw inside the plot over the grid, on a solid background chip (wave 8: was a thin surface
+halo stroke, which still let the digits visually blend into a bar's fill — a bar/band chart's first
+and last ticks sit directly over drawn ink with no clear region the way a line/area chart's do) and
+the left gutter drops to its floor; `micro` drops the y axis and keeps two x terminals; terminal x
+labels anchor inward; multi-word x labels wrap before they rotate (rotate only past 2x what fits). A
+tick within one line-height of the plot's top edge flips its label below the tick line instead of
+above it, so it no longer clips against the chart's own SVG viewBox (wave 8). At every width y labels
+over 4 chars compact (`12.5k`, `1.2M`) and the y tick count is one per ~44px of plot height (min 2).
+Opt out with explicit props: `margin.left` (keeps y labels outside), `y.format`, `y.ticks`,
+`xLabelRotate`.
+
+**`useSizeClass()` (`.`) is added** — `'compact' | 'medium' | 'expanded'`, `useSyncExternalStore`
+over one `MediaQueryList` per boundary. Its server snapshot is the new `<BasaltProvider
+sizeClassHint>` (default `'compact'`). `PageAside` and `ThreadWorkspace` now read it: the first
+server/hydration frame is `compact` unless a hint says otherwise, so an SSR app that used to get the
+desktop `PageAside` projection first should pass `sizeClassHint`. `ThreadWorkspace`'s narrow layout
+follows the compact class (< 840px, was < `sm` 48em).
+
+**`<html data-basalt-host="web|pwa">`** is set by `BasaltProvider` (`pwa` when
+`(display-mode: standalone)` matches, else `web` — always auto-detected; the `host="native"` force
+had zero consumers and is removed). The shell's safe-area padding keys on a non-`web` host instead
+of a raw `display-mode` query.
+
+**`PageAside`'s `defaultFolded` default now depends on whether the aside can dock.** Where an open
+aside would push main (`expanded`, main keeps its floor width) it starts open; everywhere else it
+would overlay main, so it starts folded on the rail. An explicit choice — a persisted or toggled fold —
+always wins. Opt out with `defaultFolded={false}` (open everywhere) or `defaultFolded` (folded
+everywhere).
+
+**The navbar defaults to the rail in the `medium` class** while nothing is persisted under
+`storageKey`. Opt out with a controlled `collapsed` prop; a persisted `false` (the user opened it
+once) pins it open.
+
+**On notice — `useBreakpoint` (removed next minor).** `@deprecated`, still works. Replace
+`useBreakpoint('sm')` with `useSizeClass() !== 'compact'`, and `useBreakpoint('lg')` with
+`useSizeClass() === 'expanded'`. A `max`-edge or non-shell width read is a container concern: use
+`@container` in CSS.
+
+**Card chrome keys on the card's own width, not the viewport.** `ChartCard`, `StatCard` and `Section`
+are now `container: basalt-card / inline-size` (`container-type: inline-size` — layout and inline-size
+containment). That has two consequences: a card needs a **definite inline size** (a block child, a
+grid `1fr` track or an explicit width — it can no longer shrink-to-fit inside a flex row or an `auto`
+grid track, where it would collapse to 0), and it becomes the containing block for `position: fixed`
+and absolute descendants. What moved onto the card's width (`CONTAINER_CLASSES`: micro < 240,
+compact 240–479, regular 480–799, wide ≥ 800):
+
+- **Under 480px, or under 280px of the card's own HEIGHT regardless of width (wave 8), `subtitle`
+  folds into the info glyph** and the visible line is hidden. A card with a `subtitle` and no `info`
+  now renders a `More information` button (hidden past both floors); with both, the one glyph's
+  bubble reads `info`, then `subtitle`. A test asserting the subtitle is visible in a narrow OR short
+  card, or that no `More information` button exists without `info`, needs updating. The height half
+  is JS-measured (`ChartCard` only, via a `data-basalt-card-short` attribute it sets from its own
+  rendered height) rather than a `@container` size query — `container-type: size` collapses an
+  auto-height card to 0, so there is no CSS-only way to query a card's own height without an
+  explicit size. `StatCard`/`Section` do not (yet) set the attribute, so only `ChartCard` folds by
+  height today.
+- **From 480px (was 800px in 1.30.x — wave 8), `value` + `delta` sit on the title row**, before
+  `actions`, instead of on their own row. The KPI value never ellipsizes any more: it shrinks with
+  the card (`cqi`, `kpi` → 16px) and breaks a pathological string rather than clipping it. A short
+  `ChartCard` (see above) also shrinks the value to the `lg` step and trims the header's own top
+  inset, so a short-but-wide chart card's header stays at or under a fifth of the card's height.
+- **`StatCard` `sparklinePlacement="right"` collapses to the stacked layout** when the card is under
+  480px wide (it keyed to the viewport's `sm` before). Two-up cards on a
+  desktop that kept the sparkline beside the value now stack when the card itself is narrow.
+- **`StatGroup` is one column under 260px** of its own width, with no leading rail hairline.
+- `ChartCard` is a flex column (`display: flex`, body `flex: 1 1 auto`): in a stretched grid row the
+  spare height goes to the body.
+- **The chart tier is the measured container class** (`micro`/`compact` < 480px keep the old phone
+  metrics; `regular`/`wide` the desktop ones). **Hard removal, no grace window: `resolveChartTier`,
+  `chartTierMetrics`, `useChartTier`, `useChartTierMetrics`, `ChartTier`, `ChartTierMetrics` and
+  `VX.phoneChartWidth`.** Zero consumers, so these ship straight to removed rather than carrying a
+  deprecated forwarder for one more minor — there is no replacement export; chart chrome sizes
+  follow the measured container class internally, with no public tier API to read it from.
+  `ChartTierMetrics.legendMaxRows` (the field a stated `legend.maxRows` could never actually reach,
+  since the tier no longer caps a legend) goes with the type; state a cap with `legend.maxRows`
+  directly where one is wanted. **Before the first measurement the class follows the viewport**
+  (`<BasaltProvider sizeClassHint>`, default `compact`), so an unmeasured first frame is
+  phone-shaped unless a hint says otherwise. With no `BasaltProvider` at all (a charts-only
+  consumer) it is `regular`, never phone chrome.
+- **`ResponsiveChartHeight` keys are `base` / `regular` / `wide`** (from 480 / 800px of the frame's
+  measured width). **Hard removal, no grace window: the `sm`/`md`/`lg` aliases.** Zero consumers, so
+  the old keys are gone outright rather than warning for a minor first — `sm` was `regular` (768 →
+  480px), `md`/`lg` were `wide` (992/1200 → 800px, one step). A `height={{ sm: … }}` object now
+  fails `tsc` on the unknown key; rename to `regular`/`wide` and re-check any object that relied on
+  the old widths. **On notice (adopt-or-delete): the whole object form.** Nothing under
+  `~/SourceRoot` uses `{ base, regular, wide }` over a plain number — the derived height law
+  (`ChartFrame` with no `height`, next bullet) already covers the common case a per-step height
+  existed for. A future minor may drop it for a plain number plus an explicit override, unless a
+  consumer names a need for it first.
+- **`ChartFrame` with no `height` derives one** from its measured width (≈0.62 / 0.5 / 0.4 × width by
+  class, clamped 160–420, and to 0.45 × viewport height on a coarse pointer) instead of 240. A
+  numeric `height` is an override and warns once in dev when it leaves the plot under
+  `VX.minPlotHeight`. Inside a `ChartCard` the height is a minimum: the frame grows into a taller
+  card body.
+- **The legend fits by measured width, and `legend.maxRows` is `@deprecated`** (dev-warns once,
+  removed in 1.32.0; an explicit value still wins this release, as an entry count). Overflow folds
+  into an **`All N`** chip (was `+N more` / `Show less`) that opens every entry, toggles included, in
+  a popover on a fine pointer and a bottom sheet on a coarse one — it never grows the band. A legend
+  never rolls up fewer than 2 entries and left-aligns (was centred) with a 6px row gap. Inside a
+  `ChartCard` with a header the legend now renders in the header slot instead of under the plot; a
+  frame under 240px (micro) draws no legend. The phone tier no longer caps a legend at two entries
+  by default.
+- **Hard removal, no grace window: `legend.mode`.** A speculative escape hatch back to labels for a
+  chart in a short card, added with zero consumers — the resolver's own `'dots'`/`'chips'` pick is
+  now the only law, with no override.
+- **Selectors and text matching the old rollup move.** Anything matching `+N more` / `Show less`
+  (tests, e2e selectors, screenshots' text) now matches the `All N` chip and the disclosure it opens
+  (`role="dialog"`, name `Legend`, `data-basalt-legend-disclosure`); there is no in-place expand.
+- **Standalone `ChartLegend` no longer applies a tier entry cap.** It renders every entry unless
+  `maxRows` is passed; only `ChartFrame` derives a cap (from the measured fit).
+
+**`BasaltDataTable` folds low-priority columns instead of only scrolling, once the table no
+longer fits its wrapper (behaviour change, no API change beyond the new `meta.priority`).** The
+same measured fit `stickyHeader` already used (`useMeasuredContainment`) now also drives an
+analytic fold: the lowest-priority data columns move into a per-row disclosure (a chevron toggle
+in a new leading cell, revealing the folded columns as label/value pairs directly under the row)
+until the rest fit, rather than forcing `Table.ScrollContainer` into horizontal scroll. **With no
+`meta.priority` set anywhere — every existing `<BasaltDataTable data columns />` — the LAST
+declared column folds first**, so a table that already fit its container renders exactly as
+before; only a table that would otherwise have scrolled changes. Order it explicitly via
+`meta.priority` on a column (a higher number folds before a lower one). Never engages beside an
+explicit `maxHeight`/`minWidth` (a declared scroll box), and never folds the selection column.
+
+**`Composer` pins itself above the on-screen keyboard, and its root is now a wrapper (behaviour
+change, no API change).** `className`, `style` and `classNames.root` land on an outer wrapper that
+also holds a keyboard-inset spacer (`--vx-keyboard-inset`, 0px when no keyboard is open), and the
+input row plus actions sit in an inner stack. Padding, margin, border and background on the root
+behave as before; a flex/`gap` override on the root no longer reaches the input row. Style the row
+through `classNames.actions` or wrap the Composer instead.
+
 ## 1.30.2 — the `legendWins` collapse, and two things `ChartFrame` never said out loud
 
 **A patch. Nothing is added, renamed or removed.** One rendering regression 1.30.1 shipped is

package/agent/rules/basalt-controls.md

@@ -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`. 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`.                                                           |
+| #   | 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 `--vx-hit` (44px under a coarse pointer). 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`.                                                          |
 
 A green lint run is not evidence the advisory laws the generated header above lists hold.
 
@@ -70,7 +70,7 @@ A green lint run is not evidence the advisory laws the generated header above li
 | `controlHeightTag`    | count-tag `Badge`                                          | inline chip, table cell                             |
 | `controlHeightWidget` | `--ai-size-icon` (explicit `size="icon"`, ActionIcon only) | sidebar search actions — no home defaults to it     |
 | `controlHeightCtl`    | `size="ctl"`                                               | `PageBar`, `Section`, table toolbar, sidebar blocks |
-| `touchControlHeight`  | hit area below `sm`                                        | every home                                          |
+| `--vx-hit`            | hit area, 44px under `(pointer: coarse)`                   | every home                                          |
 | `controlHeight`       | `size="md"`                                                | forms — unchanged                                   |
 
 A home sizes its **slot**, never its body: a raw `Button` in `PageBar.actions` is already the right

package/agent/rules/basalt-mantine.md

@@ -8,7 +8,7 @@ paths:
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — card-with-border, hidden-inline-style, in-body-page-title, inline-display, inline-spacing, mantine-shade-index, raw-form-control, raw-html-layout, raw-motion-value, raw-spacing, sub-16-input-font · oxlint rules — basalt/card-inset, basalt/deprecated-export, basalt/hand-rolled-shell, basalt/in-body-page-title, basalt/no-import-meta-env, basalt/page-bar-budget, basalt/provider-above-router, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
+<!-- backed by: guard kinds — card-with-border, hidden-inline-style, in-body-page-title, inline-display, inline-spacing, mantine-shade-index, raw-form-control, raw-html-layout, raw-media-query, raw-motion-value, raw-spacing, sub-16-input-font · oxlint rules — basalt/card-inset, basalt/deprecated-export, basalt/hand-rolled-shell, basalt/in-body-page-title, basalt/no-import-meta-env, basalt/page-bar-budget, basalt/provider-above-router, basalt/raw-breakpoint, basalt/raw-scroll-container, basalt/shadow-basalt-export -->
 <!-- not guarded: no second cssVariablesResolver — don't hand-build createTheme or re-add the resolver basalt already installs -->
 <!-- /basalt:coverage -->