basalt-ui 1.28.0 → 1.29.0

package/agent/rules/basalt-batteries.md

@@ -9,212 +9,89 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
 <!-- backed by: guard kinds — none · oxlint rules — basalt/agent-no-raw-usechat, basalt/agent-resume-guard, basalt/ai-sdk-major, basalt/forms-field-key, basalt/query-dual-import, basalt/query-fn-unwrap -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
 # Basalt Batteries — the adapter surfaces
 
-Each battery is a subpath with **one** doctrine: the shipped seam is the seam, and re-rolling it is
-the failure this rule exists to prevent. Every peer named below is OPTIONAL — install it before
-importing the battery. The API is in the shipped types, the JSDoc and `llms.txt` at the install
-directory; what follows is only what a reader gets wrong without being told.
-
-## `./query` — TanStack Query
-
-`@tanstack/react-query` is a REQUIRED peer (`BasaltProvider` needs it at build time). Import the
-hooks from `basalt-ui/query`, never dual-import from `@tanstack/react-query`.
-
-- **One factory per resource**, keyed `[resource, action, ...params]`, built with `queryOptions`;
-  components import the factory, never a raw string key.
-- **`queryFn` wraps the call in `unwrap()`** — it throws on the error branch AND on a `null` data
-  with no error (a 204, a silent transport failure). Both are caller bugs, so both must surface.
-- **Render a query with `QueryState`, don't write the switch.** Rendering only the empty branch is
-  the bug it retires: a consumer's library showed `No images` on a 500 because nobody wrote the other
-  three branches. Precedence is error-without-data → empty → loading → children, plus a cached-data
-  banner when a refresh fails over existing data. `LoadingState`/`ErrorState` ship beside it for a
-  page that must place the branches in different DOM positions.
-- **`QueryState` takes `useQuery`, not `useSuspenseQuery`** — a suspense read never hands you an
-  undefined `data` or an error branch, so there is nothing to decide. Suspense + an error boundary
-  and `QueryState` are the two ways to render a query; pick ONE per read. Inside a
-  loader-prefetched route, `useSuspenseQuery` + `ensureQueryData` is the pair.
-- **`query` is a structural subset checked at runtime** — a composed or hand-rolled result passes
-  with no cast, and a missing `isError` throws naming the field rather than rendering a false claim.
-- Decode an unknown error with `toErrorMessage(err, fallback?)` / `errorStatus(err)`; invalidate by
-  resource PREFIX after a mutation; `BasaltQueryDevtools` is lazy and production-excluded, so import
-  it unconditionally and never the raw devtools package.
+Each battery is a subpath with **one** doctrine: the shipped seam is the seam, re-rolling it is the
+failure this rule prevents. Every peer is OPTIONAL — install before importing. Full API: the
+shipped types, JSDoc and `llms.txt` at the install directory — this file is only what a reader gets
+wrong without being told.
+
+**Not guarded, honestly**: `forms`, `notifications`, `commands`, `data` and `content` carry zero
+guard kinds or oxlint rules — the `not guarded: —` line above is real, not aspirational. Nothing
+fails a build if you re-roll one of these seams by hand; follow the doctrine below on trust.
+
+**Deprecation, as a consumer sees it.** A `basalt/deprecated-export` warn means the export still
+works but leaves in a stated `removeIn` minor (autofix renames the import, keeps your local
+binding). The replacement and removal minor are always in `MIGRATING.md` § Unreleased the moment
+the deprecation ships — that file, not the warning text, is where you confirm what to migrate to.
+Maintainer mechanics: package `CLAUDE.md` § Deprecation lifecycle.
+
+## Query — `createBasaltQueryClient`/`unwrap` (root barrel, C1: `./query` dropped)
+
+`unwrap()` throws on the error branch AND on a `null` data with no error — both are caller bugs.
+Render with `QueryState`, never a hand-written switch (precedence: error-without-data → empty →
+loading → children). One factory per resource via `queryOptions`, never a raw string key.
 
 ## Eden Treaty — three silent `any`s (stated once)
 
-Stated here because they reach both `./query`'s `unwrap` and `./agent`'s transport. Three
-patterns silently degrade Treaty inference to `any`, with no TypeScript error at the point of
-breakage: a route that is not method-chained back onto the app instance; client and server packages
-whose tsconfig path aliases do not resolve identically; and a `t.Object`/`t.Union` **response schema
-on a streaming route** (Eden #231, still open). For a stream: no response schema, an explicit
-`: AsyncGenerator<AgentPart>` return annotation, and validation at yield time via `parseAgentPart`.
-Check these three first whenever Eden types regress.
+Reaches both `unwrap` and `./agent`'s transport: an un-chained route, mismatched tsconfig path
+aliases, and a response schema on a streaming route (Eden #231) all silently degrade inference to
+`any`. Check these three first when Eden types regress.
 
 ## `./forms` — `@mantine/form`
 
-- **`useBasaltForm` is the entry**: `mode: 'uncontrolled'` by default (no per-keystroke re-render)
-  and `schemaResolver(schema, { sync: true })` when a `schema` is passed. Type a schema param as
-  `StandardSchemaV1` from `basalt-ui`, never `ZodSchema` — Valibot, Zod 4, ArkType and Effect all
-  satisfy it. `validate` stays off its options: a cross-field rule drops to a raw `useForm`, an
-  async one to `useFormSubmit`'s `validateAsync`.
-- **A field is TWO calls on one line**, never one object — a spread `key` is a React 19 warning:
-  `<TextInput key={fieldKey(form, 'x')} {...inputProps(form, 'x')} />`. Dropping it is worse: the
-  field keeps its old text through `form.reset()` and nothing type-checks differently, so
-  **`basalt/forms-field-key`** guards it and autofixes it in. `field` is `@deprecated` (it
-  collides with `basalt-ui/state`'s) and NOT an alias — it still bundles `key`.
-- **`FormRow` is law C1's form row** (label left, control right, label above below `sm`) inside a
-  **`FormSection`**, clusters in a **`FormGroup`**, **`FormActions`** at the end. `SettingsRow` is
-  the settings-page variant — pick by page, never fork a third.
-- **`useFormSubmit` owns the submit**, not a hand-rolled `try`/`catch`: it decodes the throw into
-  the form-level `submitError`, routes a `{ fieldErrors }` envelope back onto the fields as inline
-  errors and focuses the first. Hand its `isSubmitting` to **`FormStateProvider`** and the layout
-  disables itself — never thread `disabled` per input; a custom control reads **`useFormState`**.
-- **`useFieldArray` is the list field**; `key(index)` is positional — reorder by an item id.
-- **`FormErrorSummary` goes at the TOP of the form** so assistive tech lands on it after a failed
-  submit. It renders `null` on a clean form, so include it unconditionally.
-- **`useFormDraft` persists through `createPersistedState`** — `autosave: true` owns its own
-  subscription, `clearDraft()` on success, keep `key` stable (changing it loses the draft), bump
-  `version` on a shape change.
+`useBasaltForm` (`mode: 'uncontrolled'`, `StandardSchemaV1` never `ZodSchema`) +
+`useFormSubmit`/`useFieldArray`/`FormErrorSummary`/`useFormDraft`. A field is two calls, never one
+object (`basalt/forms-field-key` guards + autofixes it) — dropping `key` keeps stale text through
+`form.reset()`.
 
 ## `./notifications` — `@mantine/notifications`
 
-- **`notify({ intent, message })` is the surface**, plus the four `notifySuccess/Error/Warning/Info`
-  wrappers and `notifyPromise` for an async operation. Intent — not a color — is what maps to the
-  Mantine color, the correct aria `role` (polite vs assertive) and the per-intent `autoClose`, so
-  **never pass a raw color instead of an intent**.
-- **`defineNotifications` + `emit` is the typed registry**: augment `BasaltRegister.notifications`
-  once and unknown kinds become tsc errors. `defineNotification` only TYPES a single spec — only
-  `defineNotifications(map)` registers, and `emit` before that registration is a runtime no-op.
-- **A spec carries no `title`/`icon`** by design; those stay per-call so a varying title is not
-  forced into the registry.
-- **Colors beyond the four intents live OUTSIDE the registry** — call Mantine's raw
-  `notifications.show({ color })` directly, and accept the stated cost: a raw toast is invisible to
-  the persisted history, the bell and the center, because only `notify`/`notifyPromise` record.
-- **`notifyUndo` is the undo window**, not a toast plus your own `setTimeout`: one number is both
-  the `Undo` affordance and the commit delay, `onExpire` is where the optimistic mutation commits,
-  `onUndo` reverts, and exactly one of the two ever runs.
-- History is a module-level persisted ring buffer; `useNotificationHistory` reads it, and
-  `NotificationBell` (built for the shell's `globalActions`) opens a `NotificationCenter`, which also
-  mounts standalone in any Drawer or panel.
-- The overlay MOUNT is basalt-mantine.md's — one place, one statement.
+`notify({ intent, message })` — intent, never a raw color, drives the Mantine color AND the aria
+`role`. `defineNotifications`/`emit` is the typed registry; only persisted-history calls
+(`notify`/`notifyPromise`) reach the bell/center. `notifyUndo` owns the undo-window contract.
 
 ## `./commands` — the command bus
 
-- **`defineCommands` + `runCommand`, `defineOverlays` + `overlays.open`** — augment
-  `BasaltRegister` once per registry and unknown ids are tsc errors. The augmentation is type-only
-  and erased, so both factories stash their map at module scope: call the factory once, at app boot,
-  before anything runs a command.
-- **A TS circular-inference footgun**: `overlays.open(...)` inside a `run` in the same module that
-  augments `BasaltRegister.commands` can make the map infer as `any`. Annotate that `run`'s return
-  type explicitly, or split overlay-opening commands into their own file.
-- **Projections, not parallel lists**: `toSpotlightActions()` (respecting each command's `when()`),
-  `toShortcutList()` / `ShortcutsHelp` for display, `toHotkeyBindings()` / `useCommandHotkeys()` for
-  the live keys. Never hand-author a second list of the same commands.
-- Reach for `openSpotlight`/`closeSpotlight` from `basalt-ui/commands`, not Mantine's global
-  `spotlight` — `BasaltOverlays` mounts against basalt's own store.
-- **A confirm dialog is not an overlay you define**: `overlays.confirm` / `overlays.confirmDelete`
-  need no registry entry and resolve to the answer. `defineOverlays` is for an overlay with a
-  payload and a body of its own.
-- **Imperative overlay vs route**: `overlays.open` for an ephemeral confirm or quick edit; a route
-  for anything that must be shareable, refreshable or back-button-addressable.
-
-## `./data` — TanStack Table + Virtual
-
-- **Read the props before hand-rolling anything**: title/icon/subtitle + count, an `actions`
-  toolbar slot, `facets`, global search, client- or server-side pagination, column pinning, sticky
-  header, `maxHeight`/`minWidth`, per-column `meta.align` and `meta.numeral` are all there.
-  `meta.align` is a `ColumnMeta` augmentation, so a typo is a tsc error and a bad VALUE throws naming
-  the column — declare alignment once instead of on both the `th` and the `td`.
-- **Adopt it for ownership, not for a line count.** One consumer's port ran 29–38 lines LONGER:
-  accessor blocks cost more than bespoke `<Table.Td>` rows. What it buys is the `type="native"`
-  scroll footgun, alignment stated once, and sorting/filtering/pagination no longer being yours.
-  A table with no sorting, no pagination, no filter and no alignment to declare is a layout grid —
-  adopting the component there buys nothing.
-- **`manualPagination` imposes a contract on every other prop**: `data` becomes one server page
-  while the bar still claims `of N`, so sorting (`manualSorting` or `enableSorting={false}`),
-  filtering (`manualFiltering`) and the count (`rowCount`) must each be resolved explicitly.
-  Unresolved, it throws in dev naming every breach and degrades to the honest table in production.
-  Read the throw; don't work around it.
-- **The escape hatch is the same subpath**: `useReactTable`/`flexRender`/the row models are
-  re-exported, so a bespoke table needs no direct `@tanstack/react-table` import — and it scrolls
-  through the identical `Table.ScrollContainer type="native"` node.
-- **`BasaltVirtualList` above a few hundred rows**; below that a plain `Stack`/`Table` is cheaper.
-  It sets `useFlushSync: false` for React 19 itself — do not override it.
+`defineCommands`/`runCommand`, `defineOverlays`/`overlays.open` — call each factory once, at app
+boot. Project via `toSpotlightActions`/`toShortcutList`/`toHotkeyBindings`, never a hand-authored
+second list. `overlays.confirm`/`confirmDelete` need no registry entry.
+
+## `./data/table` + `./data/virtual` — TanStack Table + Virtual (C1: no bare `./data`)
+
+Read the props before hand-rolling anything (facets, pagination, `meta.align`/`meta.numeral`).
+`manualPagination` imposes a contract on sorting/filtering/count — unresolved, it throws in dev.
+`BasaltVirtualList` above a few hundred rows only.
 
 ## `./content` — prose, markdown, MDX
 
-- **Three entries, one typography layer**: `Prose` (JSX children), `Markdown` (a string — CMS,
-  files, streamed model output), `mdxComponents` (an MDX pipeline's component map). `Markdown` wraps
-  its own `Prose`; MDX output does not, so wrap it or use `ArticleLayout`.
-- **`streaming` is a RENDERING mode, not a trust claim.** `contentTrust` is the independent security
-  input and the sole input to the image-origin allowlist: **any surface rendering agent or model
-  output must pin `contentTrust="untrusted"`** — an auto-fetched image is the classic
-  prompt-injection exfiltration channel. Link/script hardening is always on, streaming or not, and
-  `sanitizeSchema` only ADDS to the default schema.
-- **Every optional peer degrades, except one.** No `shiki` (or an unknown language) renders a plain
-  mono block; no `beautiful-mermaid` leaves the fence as code; `remend`'s streaming repair and the
-  markdown renderer resolve lazily. Six mermaid diagram types are covered — anything else is a
-  consumer escape hatch outside `Markdown`.
-- **`ArticleLayout` is the docs frame** (meta header, sticky scroll-spy TOC, prev/next); every
-  linking content component takes `renderLink` as the router bridge and defaults to a plain anchor.
-- **The Article model is data + pure operators**, generic over the taxonomy — the app declares which
-  categories and tags exist (`satisfies readonly Article<Cat, Tag>[]`, deliberately no factory).
-  Filter state is store fields, and the filter UI is `FilterSet`/`ViewTabs`/`MultiSelectFilter`,
-  re-exported here so a content-only consumer has one import path (basalt-controls.md).
-- Build-time content tooling (`content-collections`) is a RECIPE, not a dependency; its vite plugin
-  must run FIRST because other transforms resolve its virtual module.
+`Prose`/`Markdown`/`mdxComponents` share one typography layer. `streaming` is a rendering mode, not
+a trust claim — any surface rendering agent/model output pins `contentTrust="untrusted"`. Every
+optional peer degrades gracefully except the sanitizer, which is always on.
 
 ## `./agent` + `./agent-chat` — streaming chat
 
-- **`./agent` is headless and Mantine-free; the chrome is `./agent-chat`.** `./agent` ships no
-  markdown renderer at all (`agent → content` is lint-blocked), so `PartList` takes a
-  consumer-supplied `components.text`; basalt's own is `./content`'s `Markdown`.
-- **Every switch over `AgentPart` ends with `default: return assertNever(part)`** — that is what
-  makes a new variant a compile error instead of a silently dropped part.
-- **`aiSdkTransport` is the recommended default** (optional peer `ai`, resolved lazily on first
-  stream); `edenTransport` is the zero-extra-dependency alternative. Neither is deprecated. The
-  transport is an injected seam, so a mock is just an object with a `stream` generator.
-- **`useAgentStream` runs ONE turn; `useAgentThreadRuns` runs N keyed by thread id.** Reach for the
-  latter for the many-short-chats shape, with `createThreadsStore` as its persisted registry.
-- **basalt ships the outcome-resolver SEAM, never an LLM call.** `heuristicOutcome` is a demo
-  fallback; production derives `{ title, summary, status }` from the finished run. The outcome shape
-  is deliberately DIFFERENT from the transcript so raw prompts and thinking cannot leak into a feed.
-- **Stream resumption is a client contract, not a backend**: a `StartPart` carries the token, the
-  transport implements `resume`, and a mount-time reconnect is attempted before an orphaned thread
-  falls back to interrupted. A transport that does neither behaves exactly as before.
-- **Three lint guards protect this discipline** — an unguarded `resume`, a raw `useChat`, and an `ai`
-  major mismatch — and they honour `basalt-agent-allow`, never `theme-allow`. `doctor`'s
-  `ai-major-parity` is the cross-package counterpart, because a lint run only ever sees one
-  package's manifest.
+`./agent` is headless/Mantine-free; `./agent-chat` is the chrome. Every `AgentPart` switch ends
+`default: return assertNever(part)`. `useAgentStream` runs one turn, `useAgentThreadRuns` runs N by
+thread id. Stream resumption reconnects a MOUNT (page reload mid-stream), it never continues a
+click — `retry()`/`regenerate()` always start a fresh stream from the cached input.
+
+**Why the three lint guards exist** (a consumer's build fails on one of these; all honour
+`basalt-agent-allow`, never `theme-allow`): `basalt/agent-resume-guard` — an unguarded
+`resumeStream()`/`useChat({ resume: true })` re-fires under StrictMode with no dedup, use
+`useAgentThreadRuns` instead. `basalt/agent-no-raw-usechat` — bypassing the basalt hooks loses the
+unmount-abort and supersede guards. `basalt/ai-sdk-major` (+ `doctor`'s `ai-major-parity`) — a v5
+stream parsed by a v7 reader throws; nothing else pins the `ai` major across packages.
 
 ## App bootstrapping — `./vite`, CSS order, `init`
 
-- **`basaltViteConfig` is config-only and always will be; `basaltAppPlugin` is the plugin half** —
-  spread it into your own `plugins` array. Keeping plugins out of the preset is why adopting it never
-  injects one you did not ask for. Position is free (`vite-plugin-pwa` self-orders by `enforce`); the
-  one real caveat is a plugin emitting files from its own `closeBundle` after the PWA plugin's.
-- **CSS layer order is load-bearing**: every `@mantine/*/styles.layer.css` first, then
-  `basalt-ui/styles.css`. An unlayered Mantine import outranks `@layer basalt` regardless of
-  specificity.
-- **Head, manifest and theme colors come from the token palette** — never hand-compute a
-  `theme-color` hex or an anti-FOUC background, and set `colorScheme` to whatever the app passes as
-  `defaultColorScheme` or you ship a flash of the wrong surface. Icons are bring-your-own: either
-  the six default filenames under `public/`, or an `icons` array naming what you actually have (an
-  entry reaches the head only when it names a `rel`; every entry becomes a manifest icon). The
-  service worker is opt-in and degrades to a warning without its peer.
-- **`init` on an existing app is a lint-debt event, not a no-op** — the shipped preset turns on
-  whole oxlint plugins the repo was never linted against, so previously-clean code lands with real
-  findings. Triage them; do not blanket-disable a plugin. It also patches `basalt.roots` (everything
-  derives from it) and a `lint:basalt` script, and it KEEPS an existing `.oxlintrc.json`, which
-  leaves the whole basalt lint half off until you extend the preset.
-- **The lefthook preset overrides YOU on a colliding key** — a `run:`/`glob:` under one of its
-  command names is discarded silently, while `env:`, `exclude:`, `skip:` and your own command names
-  merge; `BASALT_BIN` is the sanctioned seam. A broken `extends` target is a hard fail: lefthook
-  merges a missing target into ZERO commands and still exits 0.
-- **Then run `doctor` and read it to the last line.** `SKIPPED` is a third outcome that exits
-  non-zero on its own — a check that could not run is not a check that passed.
+`basaltViteConfig` is config-only; spread `basaltAppPlugin` into your own `plugins`. CSS layer
+order is load-bearing: every `@mantine/*/styles.layer.css` first, then `basalt-ui/styles.css` — an
+unlayered Mantine import outranks `@layer basalt` regardless of specificity. `init` on an existing
+app is a lint-debt event, not a no-op — triage the new findings, don't blanket-disable a plugin.
+Run `doctor` after and read it to the last line (`SKIPPED` exits non-zero on its own).

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.