basalt-ui 1.28.0 → 1.29.0

package/AGENTS.md

@@ -8,18 +8,16 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 
 | Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useBreakpoint, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `basalt-ui/charts`          | headless        | CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `basalt-ui/vite`            | build-tooling   | basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `basalt-ui/guard`           | headless        | checkSource, GUARD_RULES, Finding types — the headless theme-guard core                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `basalt-ui/query`           | headless        | createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `basalt-ui/router-tanstack` | headless        | TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; deprecated createSearchParamStore/createMultiSearchParamStore wrappers until 1.29.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `basalt-ui/forms`           | mantine-coupled | Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema; deprecated `field` alias for `inputProps` until the surface next changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `basalt-ui/router-tanstack` | headless        | TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; the deprecated createSearchParamStore/createMultiSearchParamStore wrappers were removed in 1.29.0, C1 consolidation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `basalt-ui/forms`           | mantine-coupled | Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `basalt-ui/notifications`   | mantine-coupled | Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `basalt-ui/commands`        | mantine-coupled | typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `basalt-ui/data`            | mantine-coupled | Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) — prefer ./data/table or ./data/virtual for per-feature opt-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `basalt-ui/data/table`      | mantine-coupled | BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `basalt-ui/data/virtual`    | mantine-coupled | BasaltVirtualList: a windowed virtual list over TanStack Virtual, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `basalt-ui/agent`           | headless        | Headless streaming-chat layer: useAgentStream, aiSdkTransport (recommended default) + edenTransport, isResumable/ResumableAgentTransport (stream-resumption seam), PartList, coalesceParts, the ForeignPart/definePartRenderers/narrowAgentPart open part-registry seam, plus the multi-thread createThreadsStore + useAgentThreadRuns + outcome-resolver seam (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -28,7 +26,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 | `basalt-ui/controls`        | mantine-coupled | The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates. |
 | `basalt-ui/controls-dates`  | mantine-coupled | DateRangePicker — the @mantine/dates implementation of RangeFilter's customPicker seam. Its own subpath because @mantine/dates is an optional peer and basaltViteConfig pre-bundles the whole @mantine scope, so a consumer without the peer (linewatch) must never resolve it: nothing under src/controls may import it, statically or lazily (docs/CONTROLS-SPEC.md §3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `basalt-ui/state`           | headless        | 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `basalt-ui/connectivity`    | mantine-coupled | ConnectivityProvider (aggregates browser online/offline, React Query onlineManager, SSE, and health-check pings into one status), useConnectivity, and ConnectivityIndicator — auto-mounted by BasaltProvider                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `basalt-ui/format`          | headless        | money/percent/integer/compact/deltaPct/duration/durationClock/clock/relativeTime/weekday/km/kcal — Intl-backed, Mantine-free, React-free formatting; charts/utils/format.ts re-exports fmtCompact/fmtPercent/fmtCurrency/fmtInt/fmtAxisDate/fmtTooltipDate from here (C5 consolidation, one implementation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ## Hard rules
 
@@ -77,21 +75,16 @@ basalt-ui sync --check      # CI freshness gate — exits non-zero if any manage
 basalt-ui doctor            # integration health — SKIPPED is a third outcome and exits non-zero
 bunx basalt-ui tokens:css   # emit the --vx-* stylesheet (no React, no Mantine, no bundler) — bunx ONLY if basalt is not installed
 bunx basalt-ui fonts:css    # emit the shipped --basalt-font-* stacks — same exception
-basalt-ui info --json       # stable JSON surface map
 basalt-ui guard-hook        # PreToolUse theme-guard adapter: reads a Write/Edit payload on stdin, denies off-palette writes
 ```
 
 Every subcommand rejects a flag it does not accept, exiting 1 and naming it; an unknown command says
 so above the usage block. Neither is ever ignored — `doctor --json` used to run doctor and exit 0.
 
-`check-theme`, `doctor` and `sync` resolve their project identically: `BASALT_CWD` wins, then the
-cwd, then the workspace packages the root declares, then a two-level layout scan (which is what a
-repo with no `workspaces` field and the install one level down needs), then an **ascend** to the
-nearest ancestor carrying a basalt project, bounded by the repo root. Both directions announce the
-relocation in one sentence — `check-theme` used to fabricate `roots: ["src"]` on the ascend path and
-pass silently. Two candidates is ambiguous and reported, never guessed. `sync` on a `tokens-only`
-consumer prints `n/a` and exits 0; from a sub-package it refreshes the parent install rather than
-refusing, and still will not scaffold a second consumer.
+**One resolver (C2, 1.29.0): `BASALT_CWD` → cwd, and a declared `basalt.roots` — nothing inferred.**
+`check-theme`, `doctor` and `sync` all resolve their project the same way; there is no ascend/descend
+guess. Two candidates is ambiguous and reported, never guessed. `sync` on a `tokens-only` consumer
+prints `n/a` and exits 0.
 
 **Run the local bin, not `bunx`.** `bunx` does not re-resolve a cached package, so it can execute
 the version you just upgraded away from — one consumer filed a P0 against a 1.20.0 cache while
@@ -115,9 +108,9 @@ reports `theme-allow-unscoped`. A word in the id slot that names no rule waives
 plugin-rule waivers too (since 1.22.0), by re-running oxlint — so it needs oxlint reachable;
 otherwise the verdict is "cannot judge", never "dead".
 
-> **Framework-internal only** — `bunx basalt-ui check-coverage` is a self-consistency gate for the
-> basalt-ui repo itself (asserts SURFACES ↔ rule files ↔ skill files ↔ package.json exports). It
-> is not a consumer command and will skip assertion 3 outside the framework repo.
+> **Framework-internal only** — `bun scripts/check-coverage.ts` (a script, not a CLI subcommand
+> as of C2/1.29.0) is a self-consistency gate for the basalt-ui repo itself (asserts SURFACES ↔
+> rule files ↔ skill files ↔ package.json exports). Not a consumer command.
 
 ## Machine-readable surface map
 

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [1.29.0](https://github.com/jkrumm/basalt-ui/compare/v1.28.0...v1.29.0) (2026-09-02)
+
+
+### Bug Fixes
+
+* record every 1.29.0 removal, retire the dead notifications rule, tickValues ([21a6c28](https://github.com/jkrumm/basalt-ui/commit/21a6c287ad020e50dad7004135e1695bce58e2d6))
+
+
+### Features
+
+* a format module, chart states by flag, useBreakpoint, command handles ([dbf38f7](https://github.com/jkrumm/basalt-ui/commit/dbf38f79d01a2333181cf3f490f66ae8cd0dffbf))
+* transport message ids, onError and hydrated resume in the agent layer ([a30959e](https://github.com/jkrumm/basalt-ui/commit/a30959ef81eac0f555e0ad06e6fe68366cb358a8))
+
 # [1.28.0](https://github.com/jkrumm/basalt-ui/compare/v1.27.0...v1.28.0) (2026-09-02)
 
 

package/MIGRATING.md

@@ -180,8 +180,8 @@ What is new, one line each — nothing here renames or removes anything:
   `tier` is the package's word for "how loud is this" (`WidgetHeader`, `CtlSlot`), and `'section'`
   meant two different things across the two spellings. `variant` is `@deprecated` and still
   honoured; resolution is `tier ?? variant ?? 'page'`, so nothing moves until you change the prop.
-  `QueryStateTier` is the new type name; `QueryStateVariant` stays exported as an alias. No removal
-  is scheduled — this is a preferred spelling, not a sunset.
+  `QueryStateTier` is the new type name; `QueryStateVariant` stayed exported as an alias through
+  1.28.x and is **removed in 1.29.0** together with the `variant` prop (see § Consolidation).
 - **`WidgetHeader` and `QueryState` gained slot classes** — `classNames={{ root, title, metric,
 icon }}` on the first, `classNames={{ root }}` on the second (the branch that is live). Additive.
   `Section` now OMITS `classNames` from the `WidgetHeaderProps` it re-publishes, so its slot union
@@ -221,8 +221,8 @@ icon }}` on the first, `classNames={{ root }}` on the second (the branch that is
   not activate.
 - **`BasaltDataTable` row selection** — `enableRowSelection` prepends a checkbox column (header =
   select-all on the page) and arms TanStack's row-selection feature; `rowSelection` /
-  `onRowSelectionChange` are the controlled pair over TanStack's own `RowSelectionState` (now
-  re-exported from `basalt-ui/data` and `basalt-ui/data/table`), and `getRowId` makes a selection
+  `onRowSelectionChange` are the controlled pair over TanStack's own `RowSelectionState` (re-exported
+  from `basalt-ui/data/table` in 1.28.x; from 1.29.0 import it from `@tanstack/react-table`), and `getRowId` makes a selection
   survive a re-sort or a refetch (the default id is the row INDEX). `bulkActions` renders a bar
   above the table while ≥1 row is selected — the count, then the actions, through the SAME
   `BarAction[]` vocabulary `PageBar` uses, so the ≤3-inline fold and the mobile kebab are basalt's
@@ -444,7 +444,7 @@ The `field.*` store builder (`basalt-ui/state`, `basalt-ui/router-tanstack`) is
 ### Shell — region seams, and what moved with them
 
 **Every `AppShell` region now ends in a real, themed 1px `--vx-divider` line on its Main-facing
-edge, with no opt-out** (`docs/DESIGN-SPEC.md` §5 "Region seams", §8 inversion #12): sidebar|main
+edge, with no opt-out** (`docs/MANTINE-THEMING.md` § Chrome integration): sidebar|main
 (full height, under `layout="alt"` it owns the top-left corner), header|main (main column only),
 main|aside (full height, absent when the aside is unclaimed), main|mobile-nav (below `sm`). Mantine
 draws all four itself through `[data-with-border]`; the colour is one theme var,
@@ -879,6 +879,138 @@ Three rendering changes ride along, all visible without any code change:
   `12ch`, capped at `100%`). The field still resolves to 220px wherever 220 fits and still never
   grows with the table; below that the search and the pills wrap onto their own lines.
 
+### Consolidation (targeting 1.29.0)
+
+**Dropped subpaths — three, all folded into `.`/`./provider`, none deleted outright.**
+
+<!-- C1 symbol list -->
+
+- `./query` — dropped. `createBasaltQueryClient`, `unwrap`, `BasaltQueryDevtools`,
+  `toErrorMessage`, `errorStatus` now on `.` (root barrel) — import from `basalt-ui` instead of
+  `basalt-ui/query`. The nine raw TanStack re-exports it carried (`QueryClientProvider`,
+  `QueryErrorResetBoundary`, `useQueryErrorResetBoundary`, `useQuery`, `useSuspenseQuery`,
+  `useMutation`, `useQueryClient`, `useInfiniteQuery`, `queryOptions`) are gone from basalt entirely —
+  import them from `@tanstack/react-query`, which the root entry already requires.
+- `./data/table` — **narrowed, not dropped**: `BasaltDataTable`, its types and `createColumnHelper`
+  stay; the TanStack pass-throughs (`useReactTable`, `flexRender`, `getCoreRowModel`,
+  `getSortedRowModel`, `getFilteredRowModel`, `getPaginationRowModel`, `ColumnDef`, `SortingState`,
+  `ColumnHelper`, `PaginationState`, `ColumnPinningState`, `RowSelectionState`, `ColumnFiltersState`)
+  are imported from `@tanstack/react-table` directly.
+- `./connectivity` — dropped. `ConnectivityProvider` (auto-mounted by `BasaltProvider`, no
+  consumer-side import needed), `useConnectivity`, `ConnectivityIndicator` now on `.`.
+- `./data` (bare) — dropped. It never carried its own exports beyond re-exporting `./data/table`
+  and `./data/virtual` — import the narrow subpath you need directly; nothing renamed.
+- `./controls-dates` — **unaffected**, stays a separate subpath (inlining it into `./controls`
+  would pull `@mantine/dates` into a subpath that must resolve without it).
+
+**Deleted `@deprecated` shims** (every one slated for 1.29.0 removal in an earlier minor's
+deprecation row — see that minor's own `MIGRATING.md` section for the original `@deprecated`
+annotation and rationale):
+
+- `state.ts`'s legacy connectivity export — use `./provider`'s `useConnectivity` instead.
+- `BasaltProvider`'s flat `sseUrl` / `healthUrl` / `healthIntervalMs` props — use
+  `connectivity={{ sseUrl, healthUrl, healthIntervalMs }}`.
+- `QueryStateVariant` and the `variant` prop on `QueryState`/`LoadingState`/`ErrorState`/`EmptyState`
+  — use `QueryStateTier` and `tier` (identical values).
+- `createSearchParamStore` / `createMultiSearchParamStore` (`basalt-ui/router-tanstack`) and the
+  legacy branches they kept alive in the field vocabulary — use `createSearchStore` with
+  `field.enum` / `field.multi`.
+- `field` on `basalt-ui/forms` — use `inputProps(form, path)` + `fieldKey(form, path)`.
+- `BasaltNotifications` / `BasaltNotificationsProps` (`basalt-ui/notifications`) — mount
+  `<BasaltOverlays notifications />` from `basalt-ui/commands` instead. **Doctrine exception,
+  recorded**: this one never carried a `deprecated-export` row; it was superseded in 1.2x and its own
+  JSDoc warned against mounting it next to `BasaltOverlays`, so it leaves in the same minor as the
+  other shims. The `duplicate-notifications-mount` lint rule that only existed to catch the
+  double-mount is retired with it.
+- `ConnectivityIndicatorProps` stays on the root barrel (it is `BasaltProps`).
+
+**CLI** (`basalt-ui`): `info` and `check-coverage` are gone — `check-coverage` is a repo-internal
+script (`bun scripts/check-coverage.ts`), not a consumer command; `info` graded a consumer's
+`vite.config.ts` by parsing it and nobody read the output. `doctor` checks THIS package only: the
+workspace-wide `ai` major-parity walk (with `!`-exclusions and `aiMajorSkewReason`) and the
+`basaltAppPlugin({ icons })` file check are dropped. One resolver remains for every command —
+`BASALT_CWD`, then cwd, plus a declared `basalt.roots`; nothing is inferred from siblings or parents.
+
+- `ZonedLine`/`Bars`' `ZoneSpec` aliases — use the canonical `AxisConfig`-scoped zone type each
+  kind now exports directly.
+- `inputProps`'s `key` return field (already shape-changed in an earlier Unreleased entry above) —
+  fully removed this minor; use `fieldKey(form, name)` alongside `inputProps(form, name)`.
+
+**On notice for 1.30.0** — a public export with exactly one consumer (the playground) as of this
+audit. Adopt-or-delete: gains a real consumer by 1.30.0 or is removed. Not a promise either way;
+record your adoption in `docs/ARGO-MIGRATION-LEARNINGS.md` if you pick one up.
+
+- **Threads/agent-chat composite tier**: `ThreadWorkspace`, `ThreadFeed`, `ThreadFeedRow`,
+  `ThreadDetailPanel`, `ThreadOutcomeCard`, `ThreadsStoreAdapter`, `createThreadsStore`,
+  `createAdapterThreadsStore`, `threadsStoreAdapterContract`, `threadPartRenderers`,
+  `definePartRenderers`.
+- **Chart kind**: `Heatmap` only — `DualPanel` has an argo consumer and `MirroredBars`/`BandStrip`
+  are consumed by linewatch, so those three are NOT on notice.
+- **Nav/shell**: `PageAside`, `PanelRow`, `SettingsRow` (playground-only as of this audit).
+- **Controls**: `SliderControl`, `SearchFilter`, `ToggleFilter`, `CompareFilter`, `OverflowMenu`,
+  `ControlGroup`.
+
+**`common/**`— the public common primitives, as a unit.**`src/common/\*\*`(shipped from the
+maturation round) is now the one place base prop/error/ref vocabulary lives:`BasaltProps`,
+`SlotStylesProps`, `cx`, `mergeRefs`/`assignRef`, the prefixed `errors.ts` table
+(`toErrorMessage`/`errorStatus`), `useValidateProps`, `assertRequiredProps`. Every basalt component
+extends `BasaltProps`for its own prop type rather than redeclaring`className`/`style`; a consumer
+composing over a basalt component should do the same.
+
+### Additions (targeting 1.29.0)
+
+C5 consolidation — every item below names the argo lines it lets a consumer delete
+(`.claude/maturation/consolidation-plan.md` §C5, `audit-f-argo-consumer.md`). All additive; nothing
+in this block removes or renames an existing export.
+
+- **`basalt-ui/format`** — new subpath, Mantine-free and React-free: `money`, `percent`, `integer`,
+  `compact`, `deltaPct`, `duration` (seconds → `"1h 02m"`; `{ unit: 'minutes' }` for a
+  minutes-based input), `durationClock` (`"1:02:03"`), `clock`, `relativeTime`, `weekday`, `km`,
+  `kcal` — plus the original chart-formatter names (`fmtCompact`/`fmtPercent`/`fmtCurrency`/
+  `fmtInt`/`fmtAxisDate`/`fmtTooltipDate`/`NON_FINITE`/`formatters`), now re-exported from here;
+  `./charts`' `utils/format.ts` is an internal re-export shim, not a second implementation.
+- **`ChartState.empty`** widens to `boolean | string` — a string is both truthy and the label
+  `ChartEmpty` paints. `ChartCard` gains `state?: ChartState`, `placeholderHeight?: number`
+  (default 240) and `stateAction?: ReactNode`, and `children` is now optional so a title-less
+  pending card can be a route's own `<Suspense fallback>`. Resolution order is the same
+  `resolveChartState` precedence every kind already has — pending → error → empty — and
+  `state={{}}`/omitting `state` renders `children` unchanged. `ChartCenter`'s `width` widens to
+  `number | string` (`'100%'` for a non-measured block body).
+- **`DualPanel`'s `fillBetween` gains `aboveFill?: string`** — the above-side fill color; omitted,
+  both sides keep sharing `fill` (unchanged behaviour). **`AxisBottomNumeric`** exported from
+  `./charts` — the numeric twin of `AxisLeftNumeric`, for a bespoke continuous-x plot.
+- **`useBreakpoint(name, edge?, options?)`** on the root barrel — SSR/hydration-safe media query
+  over `theme.breakpoints`, built on `useSyncExternalStore` (not `@mantine/hooks`' `useMediaQuery`,
+  which mismatches during hydration). `edge` is `'min'` (default, "at least this wide") or `'max'`.
+  `page-aside.tsx` now composes this hook's own internals instead of a private duplicate.
+- **`--vx-space-touch-target` / `VX.spaceTouchTarget`** — the WCAG touch-target floor (44px),
+  density-exempt. The one `SPACE_FIXED` member that IS emitted as a CSS var (every other one stays
+  JS-only) — a consumer's own `@media (pointer: coarse)` CSS-module rule reads it directly.
+- **`SettingsMenuItem.active?: boolean`** — renders a trailing check glyph and `aria-current` in
+  every projection (the sidebar's flat rows and gear menu, the mobile More sheet).
+- **`basalt-ui/commands` gains imperative shell handles**: `setColorScheme(scheme)` and
+  `toggleSidebar()`, wired automatically — `BasaltProvider` registers the Mantine color-scheme
+  setter, `BasaltShell` registers the collapse toggle, so a command's `run` calls either with zero
+  `__root.tsx` bridge wiring (unlike the hand-rolled `color-scheme-bridge.ts`/`sidebar-bridge.ts`
+  shape this seeds from). `Slot<K, Constraint>` (`register.ts`) changed its internal resolution
+  from a whole-interface mapped-type match to an indexed-access form — same public behaviour,
+  fixes the commands↔overlays same-file type cycle a command calling `overlays.open(...)` used to
+  hit while `defineCommands`'s own type was still being inferred.
+- **`BasaltDevDock`** on the root barrel — a fixed, dev-only bottom drawer hosting TanStack Router
+  devtools, TanStack Query devtools and the theme lab, each peer lazy-loaded. New optional peer:
+  `@tanstack/react-router-devtools`.
+- **`BasaltErrorBoundaryProps`** is now exported; `onError` is optional (defaults to the same
+  console-warn-in-dev fallback `BasaltProvider`'s own top-level `onError` uses); an omitted
+  `fallback` now renders a minimal built-in default (a `PageTitle` + reload button) instead of
+  `null` — pass `fallback={null}` explicitly for the old swallow-it behaviour. **`PageTitle`** is a
+  new shell-less page-title primitive on the root barrel (a plain `<h1>`, not Mantine's `<Title>`,
+  so it needs no `in-body-page-title` waiver) — the remedy for the `in-body-page-title` waiver a
+  shell-less error/auth page used to need.
+- **`unwrap` gains a second overload** — the original took only a `Promise` of the `{ data, error }`
+  envelope; it now also accepts the ALREADY-RESOLVED envelope directly (`unwrap(await api.x.get())`,
+  or as a bare `.then(unwrap)` callback), inferring which overload from whether the argument IS a
+  `Promise`. The absence guard also now throws on `undefined` data, not just `null`.
+
 ## 1.26.0 — the control tier, the page bar and the store
 
 **One export removed and two deprecated — see § Stores below; two shell PROPS removed — see
@@ -921,6 +1053,18 @@ Consumers who never overrode `basalt.severity` for any of the eight kinds/rules
 waived them see these findings for the first time as `error`; measure against the shipped preset
 before upgrading if that's a concern (`basalt-ui check-theme --audit-allows`, `oxlint .`).
 
+- **`AgentTransport.stream`'s third param** (`basalt-ui/agent`) — `ctx?: { messageId: string }`;
+  `aiSdkTransport` and `useAgentThreadRuns.start()`/`retry()` now share ONE id per turn instead of two.
+- **`useAgentThreadRuns({ onError })`** (`basalt-ui/agent`) — a genuine (non-abort) stream failure
+  per thread, for a toast without wrapping the transport.
+- **`useAgentThreadRuns` re-sweeps when `store.hydrated` flips true** (`basalt-ui/agent`) —
+  resume-after-reload now works for an async `createAdapterThreadsStore`; no API change.
+- **`ThreadFeedRow` gains `title`/`summary`/`headerLeft`/`headerRight`/`messages`/`classNames`**
+  (`basalt-ui/agent-chat`) — header and transcript overrides plus slot classes for a server-titled row.
+- **`ThreadFeedRow.height` no longer requires `virtualize`** (`basalt-ui/agent-chat`) — a bounded,
+  auto-scrolling body via `BasaltStickToBottom`.
+- **`ThreadFeed.anchor`** (`basalt-ui/agent-chat`) — `'end'` for a bottom-anchored chat feed.
+
 ### Composers — WidgetHeader-backed renames (docs/CONTROLS-SPEC.md §2.2)
 
 `StatCard`, `ChartCard`, `Section` (new), `SettingsSection`/`DangerZone` and `BasaltDataTable` now
@@ -1259,7 +1403,7 @@ homes rather than shipped repo-wide. `basalt/shadow-basalt-export` gains a renam
 → `StatCard`), so a fork that RENAMED the export is visible too. It stays a permanent advisory
 `warn`.
 
-**`profile: 'tokens-only'` now disables 19 kinds, not 17** — both new kinds are Mantine-coupled.
+**`profile: 'tokens-only'` now disables 18 kinds** — Mantine-coupled kinds, count as of this write (drifts release to release; `TOKENS_ONLY_DISABLED_KINDS.size` in `src/guard/index.ts` is ground truth, this table isn't).
 
 **`SURFACES` gains `pluginRules`** (`src/surfaces.ts`, internal — not a published subpath): every
 doctrine surface names the oxlint rules that enforce it, every registered rule maps to exactly one
@@ -1944,7 +2088,7 @@ with the whole lint half off).
 
 | Surface                                                          | Note                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt.profile: 'tokens-only'` / `--tokens-only`                | disables the 19 kinds whose remedy is a Mantine component, prop or the React theme factory. `check-theme` requires it DECLARED; `doctor` infers it, because its profile only changes advice, never enforcement                                                                                                                                                                                                                               |
+| `basalt.profile: 'tokens-only'` / `--tokens-only`                | disables the 18 kinds whose remedy is a Mantine component, prop or the React theme factory. `check-theme` requires it DECLARED; `doctor` infers it, because its profile only changes advice, never enforcement                                                                                                                                                                                                                               |
 | `basalt.include: [...]`                                          | scan a named file outside `roots` — and the only route to a `.json`, which is never blanket-scanned                                                                                                                                                                                                                                                                                                                                          |
 | `basalt.roots` + a `lint:basalt` script                          | written by `init` from the real layout; `init` on an existing app is a lint-debt event, not a no-op                                                                                                                                                                                                                                                                                                                                          |
 | `tokens:css --check`, `--selector-class <c>` (+ `--light-class`) | drift gate; the Tailwind `<html class="dark">` convention. There is no `scheme: { class }` API — the class form is CLI-only                                                                                                                                                                                                                                                                                                                  |

package/README.md

@@ -59,7 +59,7 @@ bunx basalt-ui init
 That's the whole install — there is no plugin, no marketplace, and no second version to track.
 `init` writes into the consumer repo:
 
-- `.claude/rules/basalt-*.md` — thirteen Claude Code rules (`basalt-tokens`, `basalt-charts`, `basalt-mantine`, `basalt-router`, `basalt-query`, `basalt-state`, `basalt-forms`, `basalt-notifications`, `basalt-commands`, `basalt-data`, `basalt-agent`, `basalt-content`, `basalt-app`)
+- `.claude/rules/basalt-*.md` — six Claude Code rules (`basalt-tokens`, `basalt-mantine`, `basalt-charts`, `basalt-state`, `basalt-controls`, `basalt-batteries`), each with a generated coverage header naming what enforces it
 - `.claude/skills/basalt-{app,design,charts}/SKILL.md` — the three skills (`/basalt-app`, `/basalt-design`, `/basalt-charts`), same managed path as the rules
 - A managed `<!-- basalt:begin/end -->` block in `CLAUDE.md` — stack facts, the DESIGN.md pointer, and the frontend-design restraint override
 - A thin `DESIGN.md` seed — your app's deltas (series dictionary, identity, deviations)
@@ -172,8 +172,8 @@ const theme = createBasaltTheme(
 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 and replaces a
-standalone `<BasaltNotifications />`. `paletteOptions={{ groups: paletteGroups }}` emits your
+`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.
@@ -245,7 +245,7 @@ scanned files, and `doctor`'s `guard-scan` check agrees with it. Each root's **p
 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 19 kinds whose remedy is a Mantine component or prop, and must be
+"tokens-only"` turns off the 18 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
@@ -610,9 +610,10 @@ bun add @mantine/notifications
 ```
 
 ```tsx
-import { BasaltNotifications, notifySuccess, notifyError } from 'basalt-ui/notifications'
+import { notifySuccess, notifyError } from 'basalt-ui/notifications'
+import { BasaltOverlays } from 'basalt-ui/commands'
 
-// in main.tsx: <BasaltProvider><BasaltNotifications /><App /></BasaltProvider>
+// in main.tsx: <BasaltProvider><BasaltOverlays notifications><App /></BasaltOverlays></BasaltProvider>
 notifySuccess('Saved')
 notifyError('Upload failed', { title: 'Error' })
 ```
@@ -825,66 +826,11 @@ Current slots: `series` (read by `./charts` + `./tokens`), `commands` (read by `
 
 ## CLI
 
-```bash
-bunx basalt-ui init              # scaffold doctrine into a consumer repo — the one command with no install to resolve
-basalt-ui --version              # one bare line, exit 0 (also -v / version) — which CLI is actually running
-basalt-ui sync                   # three-way diff against .basalt/manifest.json after a basalt-ui upgrade
-basalt-ui sync --check           # CI drift gate — non-zero exit on any managed-file drift
-basalt-ui check-theme            # palette guard — fails on colors that bypass the central --vx-* system
-basalt-ui doctor                 # integration health: basalt-resolves, guard-scan, oxlint-preset, lefthook-preset, manifest presence, node_modules-vs-manifest version, spacing-scale drift, and a cross-package `ai` major-version parity check (HARD failure — walks every workspace manifest, exemptable via `basalt.aiMajorSkewReason` — see above) + warn on an icon file basaltAppPlugin references and public/ does not have
-basalt-ui doctor --tokens-only   # force the Mantine-free profile (auto-detected otherwise; --framework forces the full set)
-bunx basalt-ui tokens:css --out src/tokens.css     # emit the --vx-* stylesheet as a file you own — `bunx` ONLY if basalt is not installed here
-bunx basalt-ui fonts:css --out src/fonts.css       # emit the shipped --basalt-font-* stacks — same exception
-basalt-ui info --json            # surface map as stable JSON (InfoOutput shape); bare `info` is the human-readable form
-basalt-ui help                   # full usage; every subcommand also takes --help / -h
-```
-
-**Nothing fails open.** `--version` resolves before dispatch, so it can never run a command to
-answer which CLI ran. Every subcommand validates its flags and exits 1 naming the first one it does
-not accept — `doctor --json` used to run doctor and exit **0**, and `check-theme --audit-allow`
-scanned and reported success. An unknown command says so above the usage block.
-
-`doctor` reports **`SKIPPED`** as a third outcome beside pass/warn/fail and exits non-zero on it —
-"All checks passed" is only printable when every check actually ran. **`check-theme`, `doctor` and
-`sync` all resolve their project the same way**: `BASALT_CWD` wins, then the cwd itself, then the
-workspace packages the root declares, then a two-level layout scan. Two candidates is reported as
-ambiguous, never guessed. The scan is what a repo declaring **no `workspaces` field** needs — with
-the install one level down and nothing declaring it, every command answered about the root and
-found nothing there: `check-theme` printed "no off-palette colors" having scanned zero files, and
-`doctor` inferred `tokens-only` for a full Mantine consumer. `tokens:css` and `fonts:css` both take
-`--check` as a CI drift gate, comparing everything but the header's provenance line — so a
-basalt-ui version bump alone never forces a no-op commit in a tokens-only consumer.
-
-**Run the local bin, not `bunx`.** `bunx` does not re-resolve a package it has already cached, so a
-`bunx basalt-ui …` run can execute a version you upgraded away from — which is how one consumer
-filed a P0 against a 1.20.0 cache while pinned to 1.22.0. `init` and `sync` now render every seeded
-script, CI step, hook and piece of doctor advice with the resolved `./node_modules/.bin/basalt-ui`
-(`BASALT_BIN` overrides it, and `configs/lefthook.yml` keeps `bunx --no-install` as a deliberately
-loud fallback). `basalt-ui --version` is the one-second check.
-
-**Three commands are the sanctioned exception, and only when basalt is not installed in the repo:**
-`init` (which predates the install by definition) and `tokens:css` / `fonts:css` (the framework-free
-route, where there is nothing to install). In a repo that _does_ carry basalt — which includes every
-tokens-only consumer that keeps it as a devDependency — run those through the local bin too.
-
-`sync` strategy per file: unchanged since last write → overwrite; locally edited → skip (show diff);
-missing → recreate. `--force` overwrites local edits. The summary counts `created` and `recreated`
-apart: `recreated` means the ledger placed that file once and it went missing. On a
-`"basalt": { "profile": "tokens-only" }` consumer there is no scaffold to reconcile, so `sync`
-prints `n/a` and exits 0 — `sync --check` is wirable into a tokens-only repo's CI without a
-special case. `sync` also heals a `DESIGN.md` opener that still names a version: the file is a
-**seed**, written once and never reconciled, so any number stamped into it was stale by the next
-release.
-
-**`sync` refreshes an existing install; it does not create one.** It resolves its project exactly as
-`check-theme` and `doctor` do, and since 1.22.0 **exits 1** when the resolved project has no
-`.basalt/manifest.json`, naming the install it found above instead of scaffolding a second one
-beside it. Run it at the package that holds the manifest, or point `BASALT_CWD` at that package.
-Creating an install is `basalt-ui init`'s decision — and `doctor` now says the same sentence from
-the same directory, where it used to prescribe `init` and so recommend the very scaffold that
-refusal exists to prevent.
-
----
+`basalt-ui help` prints full usage (every subcommand also takes `--help`/`-h`); `AGENTS.md` at the
+install directory is the machine-readable companion. Run the **local bin, not `bunx`** —
+`./node_modules/.bin/basalt-ui` or a `package.json` script; `bunx` can silently run a cached version
+you've upgraded away from. The one sanctioned `bunx` invocation is `init`, because nothing is
+installed yet.
 
 ## Toolchain
 
@@ -901,6 +847,17 @@ The `./configs/*` export gives consumer apps raw presets to `extends` or copy vi
 { "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }
 ```
 
+`tsconfig.json` `extends` resolves the SAME way, through package exports (`bundler`
+`moduleResolution`, CI-verified by `scripts/pack-test.sh`) — three raw presets, `base` (the shared
+strict flags), `react-app` (`base` + DOM/JSX libs) and `node` (`base` + Node types):
+
+```json
+{ "extends": "basalt-ui/configs/tsconfig.react-app.json" }
+```
+
+`.oxfmtrc.json` has no `extends` of its own — copy `configs/oxfmt.json` verbatim (`basalt-ui init`
+does this for you).
+
 ---
 
 ## `basalt-ui sync` in CI