basalt-ui 1.41.0 → 2.0.0

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/basalt-ui.svg)](https://www.npmjs.com/package/basalt-ui)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/jkrumm/basalt-ui/blob/master/LICENSE)
 
-> Opinionated framework for Mantine v9 + visx React apps — theme, app shell, chart system, and the agentic layer to drive them.
+> Opinionated framework for Mantine v9 + TanStack Charts React apps — theme, app shell, chart system, and the agentic layer to drive them.
 
 **[Documentation](#quick-start)** · **[GitHub](https://github.com/jkrumm/basalt-ui)** · **[npm](https://www.npmjs.com/package/basalt-ui)**
 
-Building a dashboard app means wiring a Mantine theme, a visx chart system, a typed token layer, and an app shell — each with its own opinions, and none of them talking to each other.
+Building a dashboard app means wiring a Mantine theme, a TanStack Charts chart system, a typed token layer, and an app shell — each with its own opinions, and none of them talking to each other.
 
 Basalt UI is the extraction of that setup from a production app. Install once, get a coherent system.
 
@@ -19,29 +19,25 @@ Basalt UI is the extraction of that setup from a production app. Install once, g
 
 ```bash
 bun add basalt-ui
-bun add react react-dom @mantine/core @mantine/hooks @tanstack/react-query
+bun add react react-dom @mantine/core @mantine/hooks @mantine/modals @mantine/notifications @mantine/spotlight \
+  @tanstack/react-router @tanstack/react-query \
+  @fontsource-variable/hubot-sans @fontsource-variable/jetbrains-mono @fontsource-variable/nunito-sans
 ```
 
-The root `.` entry needs all five: `react` / `react-dom` `^19`, `@mantine/core` +
-`@mantine/hooks` `^9.3`, and `@tanstack/react-query` (`BasaltProvider` hard-requires it at build
-time). **Install them yourself — every peer is declared `optional`**, so no package manager adds
-them for you and a missing one surfaces as an unresolved import when you build, not as a warning
-when you install. That optionality is what lets the Mantine-free subpaths cost nothing (below);
-version mismatches on an installed peer still warn.
+That is the **required** set: `BasaltProvider` mounts the router, Query, Modals, Notifications and
+Spotlight, and `basalt-ui/styles.css` imports the three fonts. Install the peers yourself — a
+missing one surfaces as an unresolved import at build time, not as an install warning. A real app
+also needs `@types/react @types/react-dom` (dev) and a standard Vite `vite-env.d.ts`. Exact
+versions: `peerDependencies` in `package.json`.
 
-A real app also needs `@types/react @types/react-dom` (dev) and a standard Vite `vite-env.d.ts`
-for `tsc --noEmit` to pass.
+| Class            | Peers                                                                                                                                                                                                                                                                                                     | Rule                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Required         | `react`, `react-dom`, `@mantine/{core,hooks,modals,notifications,spotlight}`, `@tanstack/react-router`, `@tanstack/react-query`, the three `@fontsource-variable/*`                                                                                                                                       | every consumer; `.` or `./styles.css` imports or names it                                                |
+| Subpath-required | `./charts`: `@tanstack/charts`, `d3-scale` · `./commands`: `@tanstack/react-hotkeys` · `./agent`: `ai`, `@ai-sdk/provider`, `motion` · `./table`: `@tanstack/react-table` · `./forms`: `@mantine/form` · `./controls-dates`: `@mantine/dates`, `dayjs` · `./content`: `react-markdown` · `./vite`: `vite` | needed only by consumers of that subpath; declared `optional` in `peerDependenciesMeta`                  |
+| Optional         | `remend`, `shiki`, `@shikijs/*`, `beautiful-mermaid`, `remark-gfm`, `rehype-sanitize`, `@tanstack/react-query-devtools`, `@tanstack/react-router-devtools`, `vite-plugin-pwa`                                                                                                                             | reached through `import()` only; absent, the feature degrades (dev devtools panels, plain-text markdown) |
 
-Two more peers are needed by specific named exports of the root `.` entry, not by
-`BasaltProvider` itself: `bun add motion` if you use `ThemeToggle`, `ThreadFeed` or
-`ThreadDetailPanel`, and the three `@fontsource-variable` packages
-(`bun add @fontsource-variable/hubot-sans @fontsource-variable/jetbrains-mono
-@fontsource-variable/nunito-sans`, all exact-pinned — see `packages/basalt-ui/package.json` for the
-versions) if you import `basalt-ui/styles.css`, which `@import`s them for the three-font system.
-Both are optional peers, so neither installs automatically.
-
-**No React?** `./tokens`, `./charts`, `./state` and `./guard` resolve with none of the five
-installed, and the token system is consumable with no package at all:
+**No React?** `./tokens` imports no `@mantine/*`, and the token system is consumable with no package
+at all:
 
 ```bash
 bunx basalt-ui tokens:css --selector-attribute data-theme --only core --out src/tokens.css
@@ -71,7 +67,7 @@ That's the whole install — there is no plugin, no marketplace, and no second v
 whole oxlint plugins the repo was never linted against, so previously-clean code lands with real
 findings on the first run. `init` names those plugins, and names every file it kept along with what
 keeping it costs — an `.oxlintrc.json` that does not extend the preset means the entire basalt lint
-half is inert and nothing else says so (`--merge-lint` splices the `extends` in; it refuses on a
+half is inert and nothing else says so (`init` now splices the `extends` in by default, `--no-merge-lint` opts out; it refuses on a
 commented config rather than deleting the comments). Run `oxlint .` and triage before your next
 commit.
 
@@ -83,75 +79,60 @@ reported — exactly the files Claude reads, which cannot load from `node_module
 
 ## Wire the runtime
 
-After `bunx basalt-ui init`, wire the provider, overlays, and vite preset. This mirrors the canonical
-reference, `apps/playground/src/main.tsx`:
+After `bunx basalt-ui init`, two files wire the app. `BasaltProvider` owns the whole provider tree —
+Mantine + theme, Query, Modals (wrapping the router), the router, Notifications, Spotlight, the root
+error boundary, command hotkeys, and in dev the dev dock. Canonical reference:
+`apps/playground/src/main.tsx`.
 
 ```tsx
-// main.tsx — plain Vite CSR entry. BasaltProvider defaults to the dark color scheme and reads any
-// stored scheme from localStorage before mount, so a client-only app needs no ColorSchemeScript.
-import '@mantine/core/styles.layer.css'
-import '@mantine/notifications/styles.layer.css'
-import '@mantine/spotlight/styles.layer.css'
+// src/main.tsx
 import 'basalt-ui/styles.css'
-import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
-import { BasaltOverlays } from 'basalt-ui/commands'
-import { applyOverrides, loadOverrides } from 'basalt-ui/theme-lab'
 import { createRoot } from 'react-dom/client'
-import { App } from './App'
-import { paletteGroups } from './theme/series'
-
-// The theme lab owns only the editing UI — the host re-applies any persisted overrides at boot, so
-// a tuning session survives a refresh. `applyOverrides`/`loadOverrides` (and `readVar`) live in
-// `theme-lab/boot.ts`, a Mantine-free, SSR-safe module re-exported through this same
-// `basalt-ui/theme-lab` subpath — no `document` guard needed at the call site, and it never throws
-// under SSR. A production bundler that tree-shakes unused named exports drops `ThemeLabControls`'s
-// Mantine imports when a prod entry (like this one) only ever names these three functions; an
-// unbundled dev build still evaluates the whole subpath module.
-applyOverrides(loadOverrides())
-
-const theme = createBasaltTheme({
-  /* app deltas only */
-})
+import { BasaltProvider, createBasaltRouter } from 'basalt-ui'
+import { routeTree } from './routeTree.gen'
+import { telemetry } from './lib/telemetry'
+import './lib/commands'
+
+const router = createBasaltRouter({ routeTree })
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
 
 createRoot(document.getElementById('root')!).render(
-  <BasaltProvider theme={theme} paletteOptions={{ groups: paletteGroups }}>
-    <BasaltOverlays>
-      <App />
-    </BasaltOverlays>
-  </BasaltProvider>,
+  <BasaltProvider router={router} telemetry={telemetry} />,
 )
 ```
 
-> Use the **layered** `*.layer.css` bundles, never the plain ones — Mantine's unlayered bundle
-> outranks basalt's `@layer basalt` styles (including the iOS 16px input floor) regardless of
-> specificity. Only import `@mantine/notifications/styles.layer.css` /
-> `@mantine/spotlight/styles.layer.css` if you install those optional-peer batteries
-> (`./notifications` / `./commands` — see [Adapter batteries](#adapter-batteries) below).
-
-### Composition order
+```tsx
+// src/routes/__root.tsx
+import { Outlet, createRootRouteWithContext } from '@tanstack/react-router'
+import { BasaltShell, type BasaltRouterContext } from 'basalt-ui'
+import { NAV } from '../lib/nav'
+
+export const Route = createRootRouteWithContext<BasaltRouterContext>()({
+  component: () => (
+    <BasaltShell brand={{ name: 'Argo' }} nav={NAV}>
+      <Outlet />
+    </BasaltShell>
+  ),
+})
+```
 
-The canonical stack, once a router and a query client join the example above:
+`createBasaltRouter({ routeTree, context?, query? })` creates one `QueryClient` per call (1.x
+defaults, `query` merges over them) and carries it on `context.queryClient`; extra context extends
+`BasaltRouterContext`. `BasaltProvider` takes `router` (required), `theme` (defaults to
+`createBasaltTheme()`), `telemetry` (typed `BasaltEvent`s, no sink → no events) and `fallback` (the
+root error boundary's UI).
 
-```tsx
-<BasaltProvider theme={theme}>
-  <QueryClientProvider client={queryClient}>
-    <BasaltOverlays>
-      <RouterProvider router={router} />
-    </BasaltOverlays>
-  </QueryClientProvider>
-</BasaltProvider>
-```
-
-The order is load-bearing, not stylistic: `BasaltProvider` auto-mounts `ConnectivityProvider`
-(C1: absorbed onto the root barrel from the dropped `./connectivity`), which aggregates
-React-Query's own status and so must sit **above** the query client; `BasaltOverlays` must sit **inside** the theme, since Modals/Spotlight/Notifications
-resolve `--vx-*` tokens through Mantine's context; the router goes **last** so every route
-component renders with the theme, the data layer and the overlay layer already mounted above it.
-`agent/rules/basalt-mantine.md` points here rather than restating the tree.
+> Use the **layered** `*.layer.css` bundles, never the plain ones — Mantine's unlayered bundle
+> outranks basalt's `@layer basalt` styles (including the iOS 16px input floor) regardless of
+> specificity. `basalt-ui/styles.css` already imports the core layer bundle.
 
 **No `'use client'` directive ships anywhere in the package.** A Next.js App Router consumer wraps
-this whole composition in its own client file (`'use client'` at the top) and renders that from a
-server layout — basalt stays framework-agnostic and does not guess at the boundary.
+the provider in its own client file and renders that from a server layout — basalt stays
+framework-agnostic and does not guess at the boundary.
 
 ### Theming
 
@@ -160,9 +141,7 @@ bounded knobs, with contrast guaranteed by derivation rather than hand-tuning:
 
 ```ts
 const theme = createBasaltTheme(
-  {
-    /* app deltas only */
-  },
+  {/* app deltas only */},
   { derive: { accent: '#7c3aed', neutral: 'zinc', vibrancy: 1 } },
 )
 ```
@@ -171,22 +150,18 @@ const theme = createBasaltTheme(
 `lightLevel` / `darkLevel` / `vibrancy` / `accentBrightness` (`-5..5`, all optional — omitted knobs
 keep the shipped default). Never hand-edit a palette hex to retune the identity.
 
-`BasaltOverlays` (from `basalt-ui/commands`) is the composable overlay mount: it bundles
-`ModalsProvider`, `Spotlight`, and `Notifications` into a single mount point — it is the one
-notifications mount. `paletteOptions={{ groups: paletteGroups }}` emits your
-app-specific series colors (see
-[Consumer-series extensibility](#consumer-series-extensibility) below) alongside the framework
-palette. Skip both — `BasaltOverlays` and `paletteGroups` — if you don't use those batteries yet.
+`paletteOptions={{ groups: paletteGroups }}` on `BasaltProvider` emits your app-specific series
+colors (see [Consumer-series extensibility](#consumer-series-extensibility) below) alongside the
+framework palette. Skip it if you have no app-specific series yet.
 
 > **SSR only:** Next.js / React Router (SSR) consumers must additionally render
 > `<ColorSchemeScript defaultColorScheme="dark" />` (matching `BasaltProvider`'s default) in the
 > document `<head>` to avoid a flash of the wrong theme during hydration. Plain Vite CSR apps don't
-> need it — there is no hydration to mismatch. See `docs/MANTINE-THEMING.md`.
+> need it — there is no hydration to mismatch. See [`MANTINE-THEMING.md`](https://github.com/jkrumm/basalt-ui/blob/master/docs/MANTINE-THEMING.md) (repo, not in the package).
 
 ```tsx
-// Shell — sidebar / mobile nav / breadcrumbs / PageBar; router-agnostic
-import { BasaltShell, NavCountBadge, PageBar } from 'basalt-ui'
-import type { SidebarBlock, SidebarSection } from 'basalt-ui'
+// Shell — sidebar / mobile nav / breadcrumbs / PageBar; resolved against the router from `nav`
+import { BasaltShell, PageBar } from 'basalt-ui'
 ```
 
 ```ts
@@ -250,7 +225,7 @@ guard, and this sentence described a check that did not exist.) Each root's **pa
 contributes its `index.html` and its `public/` tree — the Vite layout `basaltViteConfig` assumes,
 and where a raw `theme-color` or webmanifest `background_color` actually lives. `.json` is never
 blanket-scanned; `include` names one explicitly and is the only route to it. `profile:
-"tokens-only"` turns off the 18 kinds whose remedy is a Mantine component or prop, and must be
+"tokens-only"` turns off the 16 kinds whose remedy is a Mantine component or prop, and must be
 declared (or `--tokens-only`) — it is deliberately never inferred from a missing `@mantine/core`,
 which would silence half the guard on any repo keeping Mantine in a different workspace package.
 Other keys (`exempt`, `severity`, `spacingSteps`, `forbiddenAccents`, …) are documented on the
@@ -298,7 +273,7 @@ nothing, so a typo is never the blanket form.
 what it still suppresses, proved by re-running the scan with that one waiver neutralized. Exits 1 on
 a dead waiver, so it is usable as a CI gate. Since 1.22.0 it runs **both** halves — `checkSource` for
 a guard kind, oxlint over one neutralized sibling file for a plugin rule — so a waiver naming
-`hand-rolled-plot` is judged rather than skipped. **It needs oxlint reachable**; where it is not, the
+a plugin rule is judged rather than skipped. **It needs oxlint reachable**; where it is not, the
 verdict is "cannot judge", never "dead". The report prints the scope it audited, because `0 dead`
 over `basalt.roots` is not `0 dead anywhere`. Two known gaps: `basalt.exempt` is not audited at all,
 and the `scoped to …` line does not distinguish `theme-allow` from `theme-allow-file`.
@@ -327,41 +302,37 @@ deleted rather than silently surviving into the next real skew.
 
 ## Subpath exports
 
-| Subpath             | Mantine? | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`                 | coupled  | `BasaltProvider`, `createBasaltTheme` / `baseTheme` / `cssVariablesResolver`, `BasaltShell` + sidebar / mobile nav / breadcrumbs / `PageBar` / `PageAside`, `Section` / `WidgetHeader`, `NavCountBadge`, `SidebarAccount` + the provider-agnostic account contract (`BasaltAccountProps`/`State`/`Actions`), `ThreadWorkspace` + thread-chat components, dashboard composites (`DeltaBadge`, `StatCard`, `EmptyState`, `SettingsSection`/`SettingsRow`/`DangerZone`), the query-branch trio `QueryState` / `LoadingState` / `ErrorState`, `createBasaltQueryClient` / `unwrap` / `toErrorMessage` / `errorStatus` / `BasaltQueryDevtools` (C1: absorbed from the dropped `./query`), `ConnectivityProvider` (auto-mounted) / `useConnectivity` / `ConnectivityIndicator` (C1: absorbed from the dropped `./connectivity`), shell types — the root entry still re-exports the thread-chat components; `./agent-chat` takes the same components standalone, without `BasaltProvider`, the shell, or the dashboard composites |
-| `./charts`          | **free** | `CartesianChart` + visx primitives, kinds, sparklines, hooks, token re-exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `./tokens`          | **free** | `VX` token refs, `buildPaletteCss`, `defineSeries`, `seriesTokens`, `groupTokens`, `alpha`, `ColorPair` / `SeriesMap` types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `./theme-lab`       | coupled  | `ThemeLabControls`, `applyOverrides`, `loadOverrides`, `COLOR_GROUPS` for live theme inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `./vite`            | —        | `basaltViteConfig(opts)` — Vite preset for basalt-ui consumer apps; `basaltAppPlugin(opts)` — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `./guard`           | **free** | `checkSource`, `GUARD_RULES`, `Finding` types — the headless theme-guard core; plus the annotation reader `--audit-allows` is built on: `findAllowAnnotations`, `neutralizeAllowAnnotation`, `NEUTRALIZED_ALLOW_TOKEN`, `PLUGIN_RULE_IDS`, `AllowAnnotationSite`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `./format`          | **free** | `Intl`-backed, Mantine-free, React-free formatting: `money`/`percent`/`integer`/`compact`/`deltaPct`, `duration`/`durationClock`/`clock`/`weekday`/`relativeTime`, `km`/`kcal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `./router-tanstack` | **free** | TanStack Router bridge: `defineNav`/`navGroup`/`navTarget`/`flattenNav` + `useNav` (→ `{ sections, mobileNav }`), `useBasaltNav` (active route), `useRouterBreadcrumbs`, and `createSearchStore` + the `field.*` vocabulary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `./forms`           | coupled  | Mantine form adapter: `useBasaltForm`, `inputProps`, `FormErrorSummary`, `useFormDraft` (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `./notifications`   | coupled  | Mantine notifications: `notify` helpers, typed registry, persisted history, `NotificationBell`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `./commands`        | coupled  | Typed command bus + overlay controller, `toSpotlightActions`, `ShortcutsHelp`, `BasaltOverlays`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `./data/table`      | coupled  | `BasaltDataTable` — sortable data table over TanStack Table, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `./data/virtual`    | coupled  | `BasaltVirtualList` — windowed virtual list over TanStack Virtual, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `./agent`           | **free** | Headless streaming layer (`useAgentStream`, `PartList`) + multi-thread `createThreadsStore` / `useAgentThreadRuns` / outcome seam                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `./agent-chat`      | coupled  | Mantine-styled thread-chat components over `./agent`: `ThreadWorkspace`, `ThreadFeed` (`variant`/`renderRow`), `ThreadFeedRow` (inline-expanding Slack row, lazily mounted + kept mounted), `ThreadOutcomeCard`, `ThreadDetailPanel`, `Composer`, `ThreadTranscript` (`groupConsecutive`/`affordances`/`virtualize` — windowed transcripts open at the newest message unless `initialScroll: 'start'`; `virtualize` is enabled by the optional `@tanstack/react-virtual` peer, absent it degrades to an unwindowed, height-bound pane), `threadPartRenderers` — **requires `motion`**, not merely an optional peer; see [Requirements](#requirements)                                                                                                                                                                                                                                                                                                                                                                      |
-| `./content`         | coupled  | `Prose`, `CodeBlock`, `Callout`, `TableOfContents`, `ReadingProgress`, `Markdown`, `MermaidDiagram`, `ArticleLayout`, `ArticleCard` / `ArticleGrid`, `GuideLink` / `GuideDrawer`, `mdxComponents`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `./controls`        | coupled  | The control tier: `FilterSet` + the `FieldHandle`-bound filters (`RangeFilter`/`CompareFilter`/`SelectFilter`/`MultiSelectFilter`/`NumberFilter`/`SearchFilter`/`ToggleFilter`), `ViewTabs`, `ActionGroup`/`OverflowMenu`/`SyncButton`, plus the aside's `PanelRow`/`SliderControl` row primitives — `pill`/`sheet`/`panel` surfaces, picked by the home, never a prop                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `./controls-dates`  | coupled  | `DateRangePicker` — the `@mantine/dates` implementation of `RangeFilter`'s `customPicker` seam; its own subpath so `./controls` resolves and renders with no `@mantine/dates` installed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `./state`           | **free** | createPersistedState (versioned localStorage) + the store field vocabulary (field.enum/multi/range/number/boolean/string, FieldHandle, lanes) + createLocalStore, the router-free store — Mantine-free state primitives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `./styles.css`      | —        | `@layer basalt` base styles, iOS input safety net, font stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `./tokens.css`      | **free** | Prebuilt `--vx-*` stylesheet — the default `buildPaletteCss()` output as a plain file, for a consumer with a bundler but no React or Mantine. **With no bundler, use the `basalt-ui tokens:css` CLI instead** and commit the emitted file: importing this subpath needs bare-specifier resolution. See [`docs/FRAMEWORK-FREE.md`](https://github.com/jkrumm/basalt-ui/blob/master/docs/FRAMEWORK-FREE.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `./configs/*`       | —        | Raw toolchain presets — oxlint, oxfmt, tsconfig (base/react-app/node), lefthook                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `./llms.txt`        | —        | Machine-readable surface map — one entry per published subpath with import specifier, description, layer, and optional peers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-
-Named exports only — no default exports.
+15 subpaths. One import path per symbol; named exports only — no default exports.
+
+| Subpath            | Purpose                                                                                                                                                                                                                                                                 |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`                | Wiring (`BasaltProvider`, `createBasaltTheme`, `createBasaltRouter`, `unwrap`), shell + nav (`BasaltShell`, `PageBar`, `PageAside`, `defineNav`, `navGroup`, `flattenNav`, `useBasaltNav`), dashboard atoms (`Section`, `StatCard`, `EmptyState`, `SettingsSection`, …) |
+| `./tokens`         | **Mantine-free.** `VX` token refs, `alpha`, `defineSeries`, `seriesTokens`, `groupTokens`, `buildPaletteCss`, layout (`BP`, `p`, `CONTAINER_*`)                                                                                                                         |
+| `./charts`         | **Mantine-free.** `CartesianChart` + the `Lines`/`Bars` kinds, `ChartCard`, `chartCursor` on `@tanstack/charts`                                                                                                                                                         |
+| `./controls`       | `FilterSet` + the `FieldHandle`-bound filters, `ViewTabs`, `SyncButton`, `FormRow`, `FormGroup`                                                                                                                                                                         |
+| `./controls-dates` | `DateRangePicker` — its own subpath so `./controls` resolves with no `@mantine/dates`                                                                                                                                                                                   |
+| `./forms`          | `useBasaltForm`, `inputProps`, `fieldKey` on `@mantine/form`                                                                                                                                                                                                            |
+| `./state`          | `field`, `createSearchStore`, `createLocalStore`, `createPersistedState`                                                                                                                                                                                                |
+| `./table`          | `BasaltDataTable`, `createColumnHelper<Row>()` over TanStack Table                                                                                                                                                                                                      |
+| `./format`         | `Intl`-backed, React-free formatting: `integer`, `money`, `percent`, `durationClock`, `relativeTime`, `weekday`, `km`, `kcal`                                                                                                                                           |
+| `./commands`       | `defineCommands`, `defineOverlays`, `overlays`, `setColorScheme`, `toggleSidebar`, `ShortcutsHelp`, `defineNotifications`, `emit`, `NotificationBell`                                                                                                                   |
+| `./agent`          | Streaming-chat runtime (`aiSdkTransport`, `useAgentThreadRuns`, `parseAgentPart`) and its Mantine chat UI (`ThreadFeed`, `ThreadFeedRow`, `Composer`, `ToolChip`)                                                                                                       |
+| `./content`        | `Prose`, `Markdown`, `Callout`, `TableOfContents`, `ArticleLayout`, `GuideLink`                                                                                                                                                                                         |
+| `./vite`           | `basaltViteConfig(opts)` preset, `basaltAppPlugin(opts)` PWA head / manifest / icons                                                                                                                                                                                    |
+| `./styles.css`     | The one stylesheet: `@layer basalt` base styles, iOS input floor, fonts                                                                                                                                                                                                 |
+| `./configs/*`      | Raw toolchain presets — oxlint, oxfmt, tsconfig (base/react-app/node), lefthook                                                                                                                                                                                         |
+
+The theme lab and the dev dock are mounted by `BasaltProvider` in dev only; `basalt-ui tokens:css`
+emits the prebuilt `--vx-*` stylesheet. Every dropped 1.x subpath and its new home:
+[`MIGRATING.md`](./MIGRATING.md) § 2.0.0.
 
 ---
 
 ## Mantine-free boundary
 
-`./charts` and `./tokens` import zero `@mantine/*`. `@visx/*` is only allowed inside `src/charts/**`. The root barrel (`.`) does not re-export `./charts` or `./tokens`.
+`./charts` and `./tokens` import zero `@mantine/*`. `@visx/*` is banned everywhere, and `@tanstack/charts/react` is imported by `src/charts/host.tsx` alone. The root barrel (`.`) does not re-export `./charts` or `./tokens`.
 
-The Mantine-free part protects two things. First, layering: `tokens` is pure data that `cssVariablesResolver` reads to bind Mantine's surfaces to the same `--vx-*` vars charts use, so an `@mantine/*` import in either would cycle back through the theme layer or let a chart bypass `--vx-*` and fork chrome/charts apart. Second, packaging: `./charts` and `./tokens` resolve and render with **no `@mantine/*` installed** — a charts/tokens-only consumer never pulls Mantine into their bundle. This is real and CI-tested (`scripts/pack-test.sh`'s "charts/tokens-only (no-Mantine) resolution + render" step scratch-installs the tarball with only `react`/`react-dom` and SSR-renders `basalt-ui/charts`; `scripts/check-dist-layering.mjs` walks the built dist graph and fails if those entries reach `@mantine/*`; the root barrel not re-exporting them is the third leg). The LAYER is Mantine-free — the FRAMEWORK is not: `.` requires Mantine (`@mantine/core`/`@mantine/hooks` are required, non-optional peers); only `./charts`/`./tokens` don't. Both consequences are a basalt-internal invariant enforced by the repo-local-only `basalt/token-layer-boundary` oxlint plugin rule — not a consumer contract, so it is deliberately absent from the shipped consumer preset. The `@visx/*`-only-in-charts part (`basalt/visx-boundary`) IS shipped, so that constraint holds downstream too.
+The Mantine-free part protects two things. First, layering: `tokens` is pure data that `cssVariablesResolver` reads to bind Mantine's surfaces to the same `--vx-*` vars charts use, so an `@mantine/*` import in either would cycle back through the theme layer or let a chart bypass `--vx-*` and fork chrome/charts apart. Second, packaging: `./charts` and `./tokens` resolve and render with **no `@mantine/*` installed** — a charts/tokens-only consumer never pulls Mantine into their bundle. This is real and CI-tested (`scripts/pack-test.sh`'s "charts/tokens-only (no-Mantine) resolution + render" step scratch-installs the tarball with only `react`/`react-dom` and SSR-renders `basalt-ui/charts`; `scripts/check-dist-layering.mjs` walks the built dist graph and fails if those entries reach `@mantine/*`; the root barrel not re-exporting them is the third leg). The LAYER is Mantine-free — the FRAMEWORK is not: `.` requires Mantine (`@mantine/core`/`@mantine/hooks` are required, non-optional peers); only `./charts`/`./tokens` don't. Both consequences are a basalt-internal invariant enforced by the repo-local-only `basalt/token-layer-boundary` oxlint plugin rule — not a consumer contract, so it is deliberately absent from the shipped consumer preset. The chart-engine part (`basalt/chart-engine-boundary`: no `@visx/*`, and `@tanstack/charts` only through an allowlist of mark subpaths) IS shipped, so that constraint holds downstream too.
 
 ---
 
@@ -425,15 +396,12 @@ export const paletteGroups = { [`${GROUP}-`]: SERIES }
 
 ```tsx
 // main.tsx — wire paletteGroups into BasaltProvider
-import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
+import { BasaltProvider } from 'basalt-ui'
 import { paletteGroups } from './theme/series'
+import { router } from './router'
 
 export function App() {
-  return (
-    <BasaltProvider theme={createBasaltTheme()} paletteOptions={{ groups: paletteGroups }}>
-      {/* app */}
-    </BasaltProvider>
-  )
+  return <BasaltProvider router={router} paletteOptions={{ groups: paletteGroups }} />
 }
 ```
 
@@ -445,176 +413,91 @@ Every `defineX` factory is const-generic and exact-keyed — the return type mir
 
 Seven optional-peer batteries extend the core. Install only what you use — core resolves without them.
 
-### `./charts` — visx chart primitives
+### `./charts` — TanStack Charts
 
 ```bash
-bun add @visx/axis @visx/curve @visx/event @visx/grid @visx/group @visx/responsive @visx/scale @visx/shape @visx/threshold
+bun add @tanstack/charts d3-scale
 ```
 
 `./charts` is Mantine-free (see [Mantine-free boundary](#mantine-free-boundary) above) but not
-dependency-free: it needs the nine `@visx/*` packages, all pinned exact at `4.0.0`. They ship as
-optional peers, not bundled dependencies, so a `./tokens`-only consumer never installs them.
-
-`CartesianChart` is the entry point: it owns the measured margins, both y scales and their
-domains, the axes, grid, the page-shared cursor, the crosshair and the derived tooltip, so a chart
-supplies its `series` and draws only marks. Legends toggle series, margins size themselves from
-the tick labels actually painted, and charts share a cursor with no provider.
+dependency-free: it needs `@tanstack/charts` and `d3-scale`, both pinned exact (`1.1.0` and
+`4.0.2`). They ship as optional peers, not bundled dependencies, so a `./tokens`-only consumer never
+installs them. visx is gone: no dependency, peer or re-export.
+
+`CartesianChart` is the entry point: it compiles one engine definition and owns the measured
+margins, both y domains, the x scale, the grid, zones, the page-shared cursor, the crosshair,
+keyboard focus, the legend and the derived tooltip, so a chart supplies its `series` and returns
+only marks. `ariaLabel` is required. The x scale follows the value `x` returns: a `Date` is a
+proportional time axis, a `number` is linear, a `string` is a point (lines) or band (bars) scale.
+Marks come straight from `@tanstack/charts/*` subpaths (`basalt/chart-engine-boundary` allowlists
+them); `basalt-ui/charts` re-exports none, and tokens and formatters live in `basalt-ui/tokens` and
+`basalt-ui/format`.
 
 ```tsx
-import { CartesianChart, LinePath, VX } from 'basalt-ui/charts'
+import { lineY } from '@tanstack/charts/line'
+import { CartesianChart } from 'basalt-ui/charts'
+import { VX } from 'basalt-ui/tokens'
 ;<CartesianChart
+  ariaLabel="Sessions"
   data={rows}
-  chartId="sessions"
-  getX={(d) => d.date}
-  series={[
-    {
-      key: 'sessions',
-      label: 'Sessions',
-      color: VX.accent,
-      mark: 'line',
-      getValue: (d) => d.sessions,
-    },
-  ]}
+  x={(d) => d.date}
+  series={[{ key: 'sessions', label: 'Sessions', color: VX.accent, getValue: (d) => d.sessions }]}
   y={{ format: (v) => v.toFixed(0) }}
   height={260}
->
-  {({ visible, xScale, yScale }) =>
-    visible.map((s) => (
-      <LinePath
-        key={s.key}
-        data={rows}
-        x={(d) => xScale(d.date) ?? 0}
-        y={(d) => yScale(s.getValue(d) ?? 0)}
-        stroke={s.color}
-      />
-    ))
+  marks={(plot) =>
+    plot.visible.map((s) =>
+      lineY(plot.rows(s.key), { x: (row) => row.x, y: 'y', z: 'series', stroke: s.color }),
+    )
   }
-</CartesianChart>
-```
-
-Shipped kinds (`Bars`, `MultiLine`, `StackedArea`, `ZonedLine`, `Donut`, `DualPanel`, `Heatmap`,
-`BandStrip`, `MirroredBars`) are that same composition, pre-wired. The last five compose
-`ChartFrame` directly, because a ring, a matrix, two panes or a strip is not a single plot rect:
-**`BandStrip`** draws 1-D categorical bands with no y dimension at all (`CartesianChart` renders a
-left numeric axis unconditionally, so it could never host one), and **`MirroredBars`** draws two
-bar panes over one x scale and one baseline, each in its own domain. Both fold their domain by
-width, hatch the share of a slot nothing measured, and share the page cursor like every other
-chart.
-
-On a strip, `series` IS the state set, so a `state` naming no entry has no colour, no legend entry
-and no tooltip row. It **throws in dev**, naming the key and the valid set; in production it draws a
-dashed neutral outline band — a treatment no legend entry and no state fill uses — plus an
-`Unknown state` tooltip row. Drawing nothing was the old behaviour and the wrong one: on a
-measured/not-measured strip a missing band claims a coverage gap. `absentState` and `MirroredBars`'
-`up.key`/`down.key` are PROPS rather than data, so those throw in every environment; an
-unresolvable pane key used to hide the pane and its axis, which reads as a measured zero.
-`BandStripSeries.formatValue` returns `string | null`, `null` rendering an em dash — an absent
-reading, distinct from `''`, which is a state whose label is the whole row.
-
-Which x ticks get painted is `xTickValues?: (keys, xMax) => readonly string[]`, on
-`CartesianChart` and forwarded by `Bars`/`MultiLine`/`StackedArea`/`ZonedLine` and both band kinds.
-It resolves ahead of the `xTicks` COUNT, which is unchanged; omit both and ticks are chosen to fit.
-Reach for values on a dense time axis — the tick chooser appends the final key unconditionally, so
-a count that misses the last index collides two labels at the right edge at every count.
-
-### Query — `createBasaltQueryClient` / `unwrap` (root barrel)
-
-`./query` was dropped in 1.29.0 (C1 consolidation) — its two exports moved onto the root barrel,
-which already requires `@tanstack/react-query` as a peer. TanStack itself
-(`QueryClientProvider`, hooks, `queryOptions`) is imported straight from `@tanstack/react-query`,
-never re-exported by basalt.
-
-```bash
-bun add @tanstack/react-query @tanstack/react-query-devtools
+/>
 ```
 
-```tsx
-import { createBasaltQueryClient } from 'basalt-ui'
-import { QueryClientProvider } from '@tanstack/react-query'
+Shipped kinds are that same composition, pre-wired: `Lines` (n series, `area`, `thresholds`, zones,
+reference lines, `y2`) and `Bars` (stacked, grouped or normalised, ± bars, overlay lines), plus `StackedArea`,
+`DualPanel`, `MirroredBars`, `BandStrip`, `Donut`, `Heatmap` and `Sparkline`. The
+[`MIGRATING.md`](./MIGRATING.md) § 2.0.0 Charts table maps every 1.x chart export.
 
-const [client] = useState(() => createBasaltQueryClient())
-// queryFn: () => unwrap(api.users.get())
-```
+Charts share a cursor with no provider (`cursorGroup="…"` isolates one; `chartCursor(group?)` reads
+it for app code), and only the chart under the pointer or keyboard focus shows a tooltip
+(`tooltip.onFollow` opts a follower in). `x` ticks are `xTicks` (a count or the values) and
+collision is the engine's `tickLabels.thin`; labels never rotate.
 
-`toErrorMessage(err, fallback?)` and `errorStatus(err)` also live on the root barrel — decode an
-unknown thrown value into something renderable, folding an HTTP status into the fallback when the
-body decodes to nothing usable (`''`, `'{}'`, `'[object Object]'`, …). `BasaltQueryDevtools` (lazy)
-is there too.
+### Query — `unwrap` (root barrel)
 
-#### Rendering a query — `QueryState`
+`createBasaltRouter` owns the `QueryClient` (one per call, `context.queryClient`); there is no
+separate client factory. `unwrap` turns an Eden-style `{ data, error }` envelope into a thrown error
+so `useQuery` sees it. TanStack itself (`useQuery`, `queryOptions`) is imported straight from
+`@tanstack/react-query`, never re-exported by basalt.
 
 ```tsx
-import { QueryState } from 'basalt-ui'
-
-function Library() {
-  const q = useQuery(imageQueries.list()) // { data, isError, error, fetchStatus, refetch }
-  return (
-    <QueryState
-      query={q}
-      variant="page" // or "section"
-      errorTitle="Could not load images"
-      errorFallback="The request failed."
-      errorAction={<Button onClick={openSupport}>Get help</Button>}
-      empty={{ title: 'No images yet', description: 'Upload one to get started.' }}
-      isEmpty={(d) => d.items.length === 0}
-    >
-      {(data) => <ImageGrid items={data.items} />}
-    </QueryState>
-  )
-}
+// queryFn: () => unwrap(api.users.get())
 ```
 
-**Ship it instead of writing the switch yourself.** Rendering only the empty branch is the mistake
-this exists to retire: a consumer's library showed `No images` on a **500** and a share detail
-showed `Share not found` on a dropped connection, because "nothing here" is what an app renders when
-nobody wrote the other three branches. `LoadingState` and `ErrorState` ship beside it as the escape
-hatch for a page that must place its branches in different DOM positions.
-
-Branch precedence, in the order it is evaluated:
-
-| Condition                           | Renders                                                                   |
-| ----------------------------------- | ------------------------------------------------------------------------- |
-| `isError` and no `data`             | `ErrorState` — `errorTitle` / `errorFallback` / `errorAction`, with Retry |
-| no `data`, `fetchStatus === 'idle'` | the `empty` copy (or nothing, if `empty` is omitted)                      |
-| no `data`                           | `loading`, else `LoadingState`                                            |
-| `data`, `isEmpty(data)`             | the `empty` copy                                                          |
-| `data`                              | `children` — a node, or `(data) => node`                                  |
-| `data` **and** `isError`            | a section-variant _stale data_ banner above `children`                    |
-
-The stale-data banner carries its own fixed copy (`Showing cached data`); `errorTitle` /
-`errorFallback` / `errorAction` apply to the no-data error branch only.
+Dev only: the dock `BasaltProvider` mounts holds the router and query devtools; open them from
+Spotlight (`dev.router`, `dev.query`, `dev.theme`). Install the optional
+`@tanstack/react-router-devtools` / `@tanstack/react-query-devtools` to get those panels.
 
-`query` is typed as a five-field structural subset, not TanStack's `UseQueryResult` — a
-hand-composed object is legal, and basalt couples to no query-library version. That subset removes
-the compiler, so **the shape is checked at runtime and a missing `isError` throws**, naming the
-field. That is deliberate: a missing `isError` is exactly the bug above, and degrading quietly would
-reproduce it.
-
-### `./router-tanstack` — TanStack Router bridge
-
-```bash
-bun add @tanstack/react-router
-```
+### Nav and stores — `.` and `./state`
 
 ```tsx
-import { createSearchStore, defineNav, field, useNav } from 'basalt-ui/router-tanstack'
+import { defineNav, navGroup } from 'basalt-ui'
+import { createSearchStore, field } from 'basalt-ui/state'
 
 export const NAV = defineNav({
-  groups: [
-    /* navGroup(...) */
-  ],
+  groups: [/* navGroup(...) */],
 })
 export const analytics = createSearchStore({
   key: 'analytics',
   fields: { range: field.range({ presets: ['7d', '30d'], fallback: '30d' }) },
 })
 
-const nav = useNav(NAV) // spread onto <BasaltShell {...nav} />
+// <BasaltShell nav={NAV} /> resolves the sidebar, mobile bar and breadcrumb
 // route: validateSearch: analytics.validateSearch — nav link: search: analytics.linkSearch
 ```
 
-`useBasaltNav` (active route) and `useRouterBreadcrumbs` ship here too. A control binds to
-`analytics.field.range`, never to `value`/`onChange` — see `basalt-ui/controls`.
+`defineNav` needs the `Register` augmentation from `main.tsx` (it validates links against the route
+tree); `useBasaltNav` returns the active route. A control binds to `analytics.field.range`, never to
+`value`/`onChange` — see `basalt-ui/controls`.
 
 ### `./forms` — Mantine form adapter
 
@@ -623,53 +506,39 @@ bun add @mantine/form
 ```
 
 ```tsx
-import { useBasaltForm, inputProps, FormErrorSummary } from 'basalt-ui/forms'
+import { useBasaltForm, inputProps } from 'basalt-ui/forms'
 
 const form = useBasaltForm({ initialValues: { email: '' } })
 ```
 
-### `./notifications` — Mantine notifications
+### `./commands` — command bus, overlays, notifications
 
 ```bash
-bun add @mantine/notifications
-```
-
-```tsx
-import { notifySuccess, notifyError } from 'basalt-ui/notifications'
-import { BasaltOverlays } from 'basalt-ui/commands'
-
-// in main.tsx: <BasaltProvider><BasaltOverlays notifications><App /></BasaltOverlays></BasaltProvider>
-notifySuccess('Saved')
-notifyError('Upload failed', { title: 'Error' })
+bun add @tanstack/react-hotkeys
 ```
 
-### `./commands` — command bus + Spotlight overlay
-
-```bash
-bun add @mantine/spotlight @mantine/modals @mantine/notifications @tanstack/react-hotkeys
-```
+`BasaltProvider` mounts `ModalsProvider`, `Notifications` and `Spotlight`, and binds every
+`defineCommands` shortcut (the hotkeys runtime loads lazily; absent the peer, shortcuts simply do not
+bind). The subpath is only what an app declares and calls:
 
 ```tsx
-import { defineCommands, runCommand, BasaltOverlays } from 'basalt-ui/commands'
+import { defineCommands, defineNotifications, emit, overlays } from 'basalt-ui/commands'
 
 export const COMMANDS = defineCommands({
   'file:save': { label: 'Save', group: 'File', shortcut: 'Mod+S', run: () => save() },
 })
-// in main.tsx: <BasaltProvider><BasaltOverlays><App /></BasaltOverlays></BasaltProvider>
-runCommand('file:save')
+// commands appear in Spotlight (Mod+K) alongside the `defineNav` destinations
+await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
 ```
 
-### `./data/table` + `./data/virtual` — TanStack Table + Virtual
-
-Two subpaths, one per peer group (C1: there is no bare `./data` barrel) — install only what you
-use.
+### `./table` — TanStack Table
 
 ```bash
-bun add @tanstack/react-table @tanstack/react-virtual
+bun add -E @tanstack/react-table@9.2.8
 ```
 
 ```tsx
-import { BasaltDataTable, createColumnHelper } from 'basalt-ui/data/table'
+import { BasaltDataTable, createColumnHelper } from 'basalt-ui/table'
 
 const col = createColumnHelper<Row>()
 const columns = [
@@ -699,26 +568,6 @@ longer. Column defs cost more than JSX rows when every cell is bespoke. Adopt th
 they actually buy — the `type="native"` footgun, alignment stated once instead of on both `th` and
 `td`, and sorting/filtering/pagination owned by basalt — not for a line count.
 
-#### `./data/table` — BasaltDataTable only
-
-```bash
-bun add @tanstack/react-table
-```
-
-```tsx
-import { BasaltDataTable, createColumnHelper } from 'basalt-ui/data/table'
-```
-
-#### `./data/virtual` — BasaltVirtualList only
-
-```bash
-bun add @tanstack/react-virtual
-```
-
-```tsx
-import { BasaltVirtualList } from 'basalt-ui/data/virtual'
-```
-
 ### `./content` — prose + markdown
 
 ````bash
@@ -757,49 +606,23 @@ otherwise exfiltrate via a remote image URL. Any surface rendering agent/model o
 ### `./agent` — streaming-chat layer
 
 ```bash
-bun add ai use-stick-to-bottom
+bun add ai @ai-sdk/provider motion use-stick-to-bottom
 ```
 
-Ships no markdown renderer — `agent/** -> content` is lint-blocked by design, so `PartList` takes
-a consumer-supplied `components.text`. Basalt's own is [`./content`](#content--prose--markdown)'s
-`Markdown`, already wired in by `ThreadWorkspace`.
-
-Single conversation — headless streaming primitives, `aiSdkTransport` (recommended default, optional
-peer: `ai`):
+`aiSdkTransport` (over the `ai` package) is the one transport and `useAgentThreadRuns` the one
+runner: it streams one turn per thread, concurrently, over a consumer-owned `ThreadsStore`. The chat
+UI (`ThreadFeed`, `ThreadFeedRow`, `Composer`, `ToolChip`) ships from the same subpath.
 
 ```tsx
-import { useAgentStream, aiSdkTransport, PartList } from 'basalt-ui/agent'
+import { aiSdkTransport, useAgentThreadRuns, ThreadFeed, Composer } from 'basalt-ui/agent'
 
 const transport = aiSdkTransport({ api: '/api/chat' })
-const { parts, send, status } = useAgentStream({ transport })
-```
-
-Many short chats — the `ThreadWorkspace` composite (a distilled-outcome feed + a detail panel).
-The headless multi-thread layer lives in `./agent`; the Mantine chrome ships from
-`basalt-ui/agent-chat` (also re-exported from the root entry):
-
-```tsx
-import { ThreadWorkspace } from 'basalt-ui/agent-chat'
-import { createThreadsStore, heuristicOutcome } from 'basalt-ui/agent'
-
-// Once at module scope:
-const useThreads = createThreadsStore({ key: 'main-threads', version: 1 })
-
-function Inbox() {
-  return (
-    <ThreadWorkspace
-      useThreads={useThreads}
-      transport={transport}
-      resolveOutcome={heuristicOutcome} // swap for your LLM-backed {title, summary} resolver
-      newThreadPlaceholder="Ask anything…"
-    />
-  )
-}
+const { runs, start, stop } = useAgentThreadRuns({ transport, store, resolveOutcome })
 ```
 
-`useAgentThreadRuns` streams each thread concurrently in the background; the feed shows only the
-distilled `{ title, summary }` outcome, never the raw prompt or thinking. See
-`agent/rules/basalt-agent.md` for the full doctrine.
+The feed shows only the distilled `{ title, summary }` outcome, never the raw prompt or thinking. It
+ships no markdown renderer — pass `./content`'s `Markdown` where a part needs one. Doctrine:
+`agent/rules/basalt-agent.md`.
 
 ### `./vite` — PWA / head metadata (optional peer)
 
@@ -845,7 +668,7 @@ declare module 'basalt-ui' {
 }
 ```
 
-Current slots: `series` (read by `./charts` + `./tokens`), `commands` (read by `./commands`), and `overlays` / `notifications` (read by `./commands` / `./notifications`). An un-augmented slot defaults to a never-keyed `{}` — augment only the slots you use.
+Current slots: `series` (read by `./charts` + `./tokens`), `commands` (read by `./commands`), and `overlays` / `notifications` (both read by `./commands`). An un-augmented slot defaults to a never-keyed `{}` — augment only the slots you use.
 
 ---
 
@@ -908,27 +731,9 @@ straight back into it.
 
 ## Requirements
 
-| Peer                      | Version        | Notes                                                                                                                                                                                                                                         |
-| ------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `react` / `react-dom`     | `^19`          | required                                                                                                                                                                                                                                      |
-| `@mantine/core`           | `^9.3`         | required                                                                                                                                                                                                                                      |
-| `@mantine/hooks`          | `^9.3`         | required                                                                                                                                                                                                                                      |
-| `@tanstack/react-query`   | —              | required for the root `.` entry — `BasaltProvider` hard-requires it at build time; NOT required by `./agent-chat`, which doesn't touch it                                                                                                     |
-| `motion`                  | `12.42.0`      | required for both the root `.` entry and `./agent-chat` — both export `ThreadFeed`/`ThreadDetailPanel` (`agent-chat/thread-feed.tsx` / `thread-detail-panel.tsx`), which import `motion/react` eagerly; the root's `ThemeToggle` also uses it |
-| `@tanstack/react-virtual` | `>=3.13.26 <4` | optional for `./agent-chat` — enables `ThreadTranscript`'s `virtualize` windowing mode via a lazy `import()`; absent it degrades to an unwindowed, height-bound pane                                                                          |
-
-`remend` was required through 1.10.x — `content/markdown.tsx` imported it at the top of the module,
-so both the root `.` entry and `./agent-chat`'s `ThreadWorkspace`/`ThreadTranscript` hard-required it
-transitively. It is now a genuinely optional, lazy peer (dynamic `import()`); see
-[`./content`](#content--prose--markdown) below.
-
-`./agent-chat`'s `optionalPeers` in `llms.txt`/`surfaces.ts` lists `remend`, `motion`, and
-`@tanstack/react-virtual` (npm has no per-subpath optionality in `peerDependenciesMeta`) — only
-`motion` needs to be treated as required when installing just this subpath; `remend` and
-`@tanstack/react-virtual` are accurately optional there too, both reached only through a lazy
-`import()` (the latter behind `ThreadTranscript`'s `virtualize` option).
-
-Optional peer batteries and their packages are listed per battery above.
+Peers by class — required, subpath-required and optional — are listed under
+[Install](#1-install); exact ranges are in `packages/basalt-ui/package.json`. Optional peers that a
+subpath uses are named in that subpath's section above.
 
 ---