basalt-ui 1.27.0 → 1.29.0

package/src/provider/index.tsx

@@ -15,18 +15,28 @@
  *
  * Mantine usage is allowed in this `./` root layer (unlike `src/charts/**` and `src/tokens/**`).
  */
-import { MantineProvider, useComputedColorScheme, useMantineTheme } from '@mantine/core'
+import {
+  MantineProvider,
+  useComputedColorScheme,
+  useMantineColorScheme,
+  useMantineTheme,
+} from '@mantine/core'
 import type { MantineProviderProps } from '@mantine/core'
 import { Component, useEffect, useMemo } from 'react'
 import type { ErrorInfo, ReactNode } from 'react'
 import { VxThemeProvider } from '../charts/theme'
-import { ConnectivityProvider } from '../connectivity'
+import fallbackClasses from './error-fallback.module.css'
+import { ConnectivityProvider } from './connectivity-provider'
+import type { ConnectivityProviderProps } from './connectivity-types'
 import { cssVariablesResolver } from '../theme'
 import { useLabTheme } from './lab-theme'
 import { buildDensityCss, buildFontsCss, buildPaletteCss, buildRadiusCss } from '../tokens'
 import type { BuildPaletteOpts } from '../tokens'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
+import { isDev } from '../common/is-dev'
+import { registerColorSchemeSetter } from '../commands/shell-bridge'
+import { PageTitle } from '../shell/page-title'
 
 /**
  * Where an error surfaced — drives consumer routing (a render error vs a global rejection differ).
@@ -91,18 +101,19 @@ export type BasaltProviderProps = {
    * prop; its nonce mechanism is `getStyleNonce: () => string`, which flows through `...rest`.
    */
   nonce?: string
-  /** Optional SSE endpoint for connectivity monitoring. When set, an EventSource is opened. */
-  sseUrl?: string
-  /** Optional health-check endpoint for connectivity monitoring. When set, periodic GET pings run. */
-  healthUrl?: string
-  /** Interval in ms for health pings. Default: 30_000 (30s). */
-  healthIntervalMs?: number
-} & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme'>
+  /**
+   * Options threaded through to the auto-mounted `ConnectivityProvider` (everything except
+   * `children`) — `sseUrl`, `healthUrl`, `healthIntervalMs`, and `override` (previously
+   * unreachable through `BasaltProvider`: the only way to reach it was a second, shadowing
+   * `ConnectivityProvider`).
+   */
+  connectivity?: Omit<ConnectivityProviderProps, 'children'>
+} & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>
 
 // ── Default error handler ─────────────────────────────────────────────────────────────────────────
 
 function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
-  if (process.env['NODE_ENV'] !== 'production') {
+  if (isDev()) {
     // eslint-disable-next-line no-console -- intentional dev-only diagnostic when no onError is supplied
     console.error('[BasaltProvider] unhandled error', ctx.kind, error)
   }
@@ -111,15 +122,54 @@ function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
 
 // ── Error boundary ────────────────────────────────────────────────────────────────────────────────
 
-type BoundaryProps = {
+/**
+ * `BasaltErrorBoundary`'s props — exported (C5 consolidation) so a consumer mounting a nested
+ * boundary can name the type, e.g. for a wrapper component's own prop forwarding.
+ */
+export type BasaltErrorBoundaryProps = {
   children: ReactNode
-  onError: (error: unknown, ctx: BasaltErrorContext) => void
-  /** Optional UI to render when a render error is caught. If a function, called with the error. Defaults to null. */
+  /**
+   * Report the caught render error. Unset → `defaultOnError` (console.error in dev, no-op in
+   * prod — the same fallback `BasaltProvider`'s own top-level `onError` uses), so a NESTED
+   * boundary mounted with no `onError` still surfaces something in dev instead of silently
+   * swallowing it.
+   */
+  onError?: (error: unknown, ctx: BasaltErrorContext) => void
+  /**
+   * UI to render when a render error is caught. If a function, called with the error. Unset →
+   * {@link DefaultErrorFallback} — a minimal `PageTitle` + reload button, never a silent `null`;
+   * pass `fallback={null}` explicitly for the old swallow-it behaviour.
+   */
   fallback?: ReactNode | ((error: unknown) => ReactNode)
 }
 
 type BoundaryState = { hasError: boolean; error: unknown }
 
+/**
+ * The boundary's own default fallback — a `PageTitle` (C5's shell-less page-title primitive, so
+ * this needs no `in-body-page-title` waiver) plus a plain reload affordance. Deliberately minimal:
+ * a consumer wanting session ids, a stack trace or a "try to recover" reset (argo's own
+ * `lib/error-boundary.tsx`) still passes its own `fallback` render function — this default exists
+ * so an app that mounts `BasaltErrorBoundary` and does nothing else shows a page, not a blank one.
+ */
+function DefaultErrorFallback(): ReactNode {
+  return (
+    <div className={fallbackClasses.root}>
+      <PageTitle
+        title="Something went wrong"
+        subtitle="The page hit an unexpected error and was unloaded to keep the app stable."
+      />
+      <button
+        type="button"
+        className={fallbackClasses.reload}
+        onClick={() => window.location.reload()}
+      >
+        Reload page
+      </button>
+    </div>
+  )
+}
+
 /**
  * Error boundary that catches render-phase errors inside `BasaltProvider`. Wraps `BasaltBridge` +
  * children INSIDE `MantineProvider` so a thrown render error still has theme context for a fallback.
@@ -130,8 +180,8 @@ type BoundaryState = { hasError: boolean; error: unknown }
  *   <MyFeature />
  * </BasaltErrorBoundary>
  */
-export class BasaltErrorBoundary extends Component<BoundaryProps, BoundaryState> {
-  constructor(props: BoundaryProps) {
+export class BasaltErrorBoundary extends Component<BasaltErrorBoundaryProps, BoundaryState> {
+  constructor(props: BasaltErrorBoundaryProps) {
     super(props)
     this.state = { hasError: false, error: undefined }
   }
@@ -141,13 +191,15 @@ export class BasaltErrorBoundary extends Component<BoundaryProps, BoundaryState>
   }
 
   override componentDidCatch(error: unknown, info: ErrorInfo): void {
-    this.props.onError(error, { kind: 'render', info })
+    const onError = this.props.onError ?? defaultOnError
+    onError(error, { kind: 'render', info })
   }
 
   override render(): ReactNode {
     if (this.state.hasError) {
       const { fallback } = this.props
-      if (fallback === undefined) return null
+      if (fallback === undefined) return <DefaultErrorFallback />
+      if (fallback === null) return null
       return typeof fallback === 'function' ? fallback(this.state.error) : fallback
     }
     return this.props.children
@@ -200,6 +252,15 @@ function BasaltBridge({
   // (fallback 'dark' before hydration, matching the provider's defaultColorScheme).
   const resolved = useComputedColorScheme('dark')
 
+  // `commands/shell-bridge.ts`'s `setColorScheme` handle — registered here (already inside
+  // `MantineProvider`) so a consumer's `commands.tsx` calls it with ZERO `__root.tsx` wiring,
+  // unlike argo's hand-rolled `color-scheme-bridge.ts` this seeds from (see that file's own doc).
+  const { setColorScheme: setMantineColorScheme } = useMantineColorScheme()
+  useEffect(() => {
+    registerColorSchemeSetter(setMantineColorScheme)
+    return () => registerColorSchemeSetter(null)
+  }, [setMantineColorScheme])
+
   // `createBasaltTheme`'s non-default `{ derive }` / `{ fonts }` / `{ radius }` / `{ density }`
   // paths stash the resolved values on `theme.other.basaltDerive` / `theme.other.basaltFonts` /
   // `theme.other.basaltRadius` / `theme.other.basaltDensity` — read them here (INSIDE
@@ -255,6 +316,34 @@ function BasaltBridge({
   )
 }
 
+// ── Duplicate-mount guard (F14) ───────────────────────────────────────────────────────────────────
+
+/**
+ * Module-level (deliberately NOT a per-instance ref, unlike `fence-block.tsx`'s warn-once gate) —
+ * the whole point is detecting a SECOND, unrelated `BasaltProvider` mounted anywhere else in the
+ * tree, which a per-instance gate could never see. Nested/duplicate providers double-mount
+ * `MantineProvider`, the palette `<style>` and `ConnectivityProvider`'s signal listeners — real
+ * misuse, not a false positive from React 18 StrictMode's double-invoke (that mounts/unmounts the
+ * SAME instance in sequence, so the count returns to 0 before a second instance could ever exist).
+ */
+let mountedProviderCount = 0
+
+function useDuplicateProviderGuard(): void {
+  useEffect(() => {
+    mountedProviderCount++
+    if (mountedProviderCount > 1 && isDev()) {
+      console.warn(
+        '[basalt] BasaltProvider: more than one instance is mounted at once — nested/duplicate ' +
+          'BasaltProviders double-mount MantineProvider, the palette <style> and ' +
+          'ConnectivityProvider. Mount exactly one, at the app root.',
+      )
+    }
+    return () => {
+      mountedProviderCount--
+    }
+  }, [])
+}
+
 // ── Public provider ───────────────────────────────────────────────────────────────────────────────
 
 export function BasaltProvider({
@@ -265,11 +354,10 @@ export function BasaltProvider({
   defaultColorScheme = 'dark',
   onError,
   nonce,
-  sseUrl,
-  healthUrl,
-  healthIntervalMs,
+  connectivity,
   ...rest
 }: BasaltProviderProps) {
+  useDuplicateProviderGuard()
   const errorHandler = onError ?? defaultOnError
 
   // `createBasaltTheme(theme)` — plus, when the theme lab's "Apply" switch is on, the delta of its
@@ -278,12 +366,18 @@ export function BasaltProvider({
   // Basalt base and nothing else. See `./lab-theme.ts`.
   const resolvedTheme = useLabTheme(theme)
 
+  const resolvedConnectivity = connectivity ?? {}
+
   return (
+    // `...rest` spreads FIRST so a consumer's `MantineProviderProps` can never shadow the three
+    // values that follow it — `cssVariablesResolver` in particular is the resolver the package
+    // exists to install (F24); `theme`/`defaultColorScheme` are excluded from `rest`'s type too,
+    // this is belt-and-braces against a widened rest at the call site.
     <MantineProvider
+      {...rest}
       theme={resolvedTheme}
       cssVariablesResolver={cssVariablesResolver}
       defaultColorScheme={defaultColorScheme}
-      {...rest}
     >
       <BasaltErrorBoundary onError={errorHandler}>
         <BasaltBridge
@@ -292,13 +386,7 @@ export function BasaltProvider({
           nonce={nonce}
           onError={errorHandler}
         >
-          <ConnectivityProvider
-            {...(sseUrl !== undefined ? { sseUrl } : {})}
-            {...(healthUrl !== undefined ? { healthUrl } : {})}
-            {...(healthIntervalMs !== undefined ? { healthIntervalMs } : {})}
-          >
-            {children}
-          </ConnectivityProvider>
+          <ConnectivityProvider {...resolvedConnectivity}>{children}</ConnectivityProvider>
         </BasaltBridge>
       </BasaltErrorBoundary>
     </MantineProvider>

package/src/provider/lab-theme.ts

@@ -44,6 +44,7 @@ import { useMemo } from 'react'
 import { useDeriveControlsState, toDeriveOverride } from '../theme-lab/derive-state'
 import type { DeriveOverride } from '../theme-lab/derive-state'
 import { baseTheme, createBasaltTheme } from '../theme'
+import { isDev } from '../common/is-dev'
 
 type Plain = Record<string, unknown>
 
@@ -135,7 +136,7 @@ export function applyLabOverride(
  * through a dev server (`bun run dev`), so that is the right side of the trade — but if you ever
  * preview the playground via `vite build && vite preview`, the sliders will be inert there.
  */
-const LAB_ENABLED = process.env['NODE_ENV'] !== 'production'
+const LAB_ENABLED = isDev()
 
 /**
  * Dev build: subscribed to the lab store.

package/src/{connectivity → provider}/use-connectivity.ts

@@ -1,8 +1,9 @@
 /**
  * useConnectivity — reads the aggregated connectivity status from ConnectivityContext.
  *
- * Throws if used outside a ConnectivityProvider. For the provider-less simple boolean,
- * use the deprecated `useOnlineStatus` from `basalt-ui/state`.
+ * Throws if used outside a ConnectivityProvider. `BasaltProvider` auto-mounts
+ * `ConnectivityProvider`, so this hook works with zero setup in the common case. It replaced the
+ * former online-status hook that lived on `basalt-ui/state` (see MIGRATING.md).
  *
  * @example
  * const { status, details } = useConnectivity()
@@ -10,7 +11,7 @@
  */
 import { useContext } from 'react'
 import { ConnectivityContext } from './connectivity-provider'
-import type { ConnectivitySnapshot } from './types'
+import type { ConnectivitySnapshot } from './connectivity-types'
 
 export function useConnectivity(): ConnectivitySnapshot {
   const snapshot = useContext(ConnectivityContext)

package/src/query-client.ts

@@ -0,0 +1,100 @@
+/**
+ * `createBasaltQueryClient` + `unwrap` — the two TanStack Query primitives basalt ships. Folded
+ * onto the root barrel (C1 consolidation, dropping the `./query` subpath): the root already
+ * requires `@tanstack/react-query` as a peer, so a dedicated Mantine-free subpath bought nothing —
+ * and it re-exported 10 raw TanStack symbols no consumer imported through it.
+ * Optional peer: @tanstack/react-query.
+ */
+import { QueryClient } from '@tanstack/react-query'
+import type { QueryClientConfig } from '@tanstack/react-query'
+
+// ── createBasaltQueryClient ───────────────────────────────────────────────────────────────────────
+
+const BASALT_QUERY_DEFAULTS = {
+  staleTime: 30_000,
+  gcTime: 5 * 60 * 1000,
+  retry: 2,
+  refetchOnWindowFocus: false,
+} as const
+
+/**
+ * Wraps QueryClient with basalt dashboard defaults. All options are mergeable — consumer
+ * overrides win per-query, framework defaults are the fallback.
+ *
+ * @example
+ * import { createBasaltQueryClient } from 'basalt-ui'
+ * import { QueryClientProvider } from '@tanstack/react-query'
+ * import { useState } from 'react'
+ *
+ * function Root({ children }: { children: React.ReactNode }) {
+ *   const [client] = useState(() => createBasaltQueryClient())
+ *   return <QueryClientProvider client={client}>{children}</QueryClientProvider>
+ * }
+ */
+export function createBasaltQueryClient(config?: QueryClientConfig): QueryClient {
+  return new QueryClient({
+    ...config,
+    defaultOptions: {
+      ...config?.defaultOptions,
+      queries: { ...BASALT_QUERY_DEFAULTS, ...config?.defaultOptions?.queries },
+    },
+  })
+}
+
+// ── unwrap ────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Transport-agnostic unwrap for any `{ data, error }` envelope (Eden Treaty, raw fetch wrappers,
+ * etc.). TData is inferred from the data field. Throws on the error branch so failures surface
+ * to the nearest error boundary or TanStack Query's error state.
+ *
+ * Absence guard: if `error` is falsy but `data` is `null` OR `undefined`, unwrap throws with a
+ * descriptive message. This catches 204 No Content responses and silent transport failures that
+ * return `{ data: null, error: null }` — both signal an unexpected absence of data and should not
+ * silently resolve. `undefined` joined `null` here (C5 consolidation) so a hand-rolled fetch
+ * wrapper that leaves `data` unset on a miss — rather than explicitly `null` — is caught the same
+ * way; the two envelope shapes argo's own pre-basalt `unwrap` and basalt's ONLY differed on.
+ *
+ * **Two overloads, one name** — a Promise of the envelope (basalt's original shape,
+ * `queryFn: () => unwrap(api.x.get())`), or the ALREADY-RESOLVED envelope itself
+ * (`unwrap(await api.x.get())`, or passed directly as a `.then(unwrap)` callback — both argo's
+ * 97 call sites' shapes). Never a generic argument to disambiguate: TS infers the right overload
+ * from whether the argument IS a `Promise`.
+ *
+ * @example
+ * import { unwrap } from 'basalt-ui'
+ *
+ * // Promise-of-envelope — queryFn:
+ * queryFn: () => unwrap(api.users.get({ query: params }))
+ * // mutation:
+ * mutationFn: (body) => unwrap(api.resource.post({ body }))
+ *
+ * // resolved-envelope — either shape:
+ * const rows = unwrap(await api.users.get())
+ * const rows2 = await api.users.get().then(unwrap)
+ */
+export function unwrap<TData>(
+  response: Promise<{ data: TData | null | undefined; error: unknown }>,
+): Promise<TData>
+export function unwrap<TData>(response: { data: TData | null | undefined; error: unknown }): TData
+export function unwrap<TData>(
+  response:
+    | Promise<{ data: TData | null | undefined; error: unknown }>
+    | { data: TData | null | undefined; error: unknown },
+): TData | Promise<TData> {
+  if (response instanceof Promise) return response.then((envelope) => unwrapEnvelope(envelope))
+  return unwrapEnvelope(response)
+}
+
+function unwrapEnvelope<TData>(envelope: {
+  data: TData | null | undefined
+  error: unknown
+}): TData {
+  const { data, error } = envelope
+  if (error) throw error
+  if (data === null || data === undefined)
+    throw new Error(
+      'unwrap: null/undefined data with no error — check for a 204 response or a transport failure',
+    )
+  return data
+}

package/src/{query/devtools.tsx → query-devtools.tsx}

@@ -1,7 +1,8 @@
 /**
- * ./query/devtools — prod-safe lazy wrapper for @tanstack/react-query-devtools.
- * The devtools package is an OPTIONAL peer — never imported at module evaluation time.
- * The dynamic import() resolves only when rendered in non-production.
+ * `BasaltQueryDevtools` — prod-safe lazy wrapper for @tanstack/react-query-devtools. Folded onto
+ * the root barrel alongside `query-client.ts` (C1 consolidation, dropping the `./query` subpath).
+ * The devtools package is an OPTIONAL peer — never imported at module evaluation time. The dynamic
+ * import() resolves only when rendered in non-production.
  */
 import { lazy, Suspense } from 'react'
 import type { ComponentProps } from 'react'
@@ -10,6 +11,7 @@ import type { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 const LazyDevtools = lazy(() =>
   import('@tanstack/react-query-devtools').then((m) => ({ default: m.ReactQueryDevtools })),
 )
+Object.assign(LazyDevtools, { displayName: 'LazyDevtools' })
 
 /**
  * Lazy, production-excluded wrapper for ReactQueryDevtools. Safe to import unconditionally —
@@ -17,7 +19,7 @@ const LazyDevtools = lazy(() =>
  * import fires. In production this returns null immediately.
  *
  * @example
- * import { BasaltQueryDevtools } from 'basalt-ui/query'
+ * import { BasaltQueryDevtools } from 'basalt-ui'
  *
  * function Root() {
  *   return (

package/src/register.ts

@@ -37,11 +37,27 @@ export interface BasaltRegister {}
  * slot instantiates against. At 1.0 the `series`, `commands`, `overlays`, and `notifications`
  * slots ship and have concrete instantiations (define-commands.ts, define-overlays.ts,
  * define-notifications.ts); `router`, `query`, and `state` remain advisory.
+ *
+ * **Indexed-access form, not a mapped-type structural match (C5 consolidation)** — this used to
+ * read `BasaltRegister extends { [P in K]: infer S extends Constraint } ? S : {}`, which forces
+ * TS to structurally match the WHOLE `BasaltRegister` interface (every augmented slot's VALUE
+ * type, not just `K`'s) before it can answer "does slot `K` exist". That is the commands↔overlays
+ * cycle argo's `lib/overlays.tsx` documents: `defineCommands`'s inferred type has to type-check a
+ * command `run` body calling `overlays.open(…)`, which resolves `Slot<'overlays', …>` — and the
+ * OLD form's whole-interface match ALSO had to resolve `BasaltRegister['commands']`
+ * (`typeof COMMANDS`, the very type still being computed) to complete the match, because a
+ * mapped-type pattern binds every property simultaneously. `K extends keyof BasaltRegister` only
+ * needs the augmented KEY NAMES (available from declaration merging with no value-type checking
+ * at all), and `BasaltRegister[K]` then touches ONLY that one slot's value — so resolving
+ * `overlays` never has to resolve `commands` first, and a consumer can define both registries,
+ * with one calling the other's imperative controller, in a SINGLE file. Behaviourally identical to
+ * the old form for every existing augmentation (fixture J.1/J.2 pin both the `{}` fallback and the
+ * `Extract<keyof, string>` guard below); ONLY the internal resolution path changed.
  */
-export type Slot<K extends string, Constraint> = BasaltRegister extends {
-  [P in K]: infer S extends Constraint
-}
-  ? S
+export type Slot<K extends string, Constraint> = K extends keyof BasaltRegister
+  ? BasaltRegister[K] extends Constraint
+    ? BasaltRegister[K]
+    : {}
   : {}
 
 /** The consumer's registered series map, or `{}` when un-augmented. */

package/src/router-tanstack/index.ts

@@ -4,12 +4,11 @@
  * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
  * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
  * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs, plus
- * `createSearchStore` + the `field.*` vocabulary (and the two deprecated enum-only wrappers it
- * replaced) — no Mantine, no JSX.
+ * `createSearchStore` + the `field.*` vocabulary — no Mantine, no JSX.
  */
 
 export { createSearchStore, type CreateSearchStoreOptions, type SearchStore } from './search-store'
-export { field } from './field'
+export { field } from '../state'
 export type {
   AnyField,
   BooleanField,
@@ -32,17 +31,7 @@ export type {
   SearchValues,
   StoredValues,
   StringField,
-} from './field'
-export {
-  createSearchParamStore,
-  type SearchParamStore,
-  type SearchParamStoreOptions,
-} from './search-param-store'
-export {
-  createMultiSearchParamStore,
-  type MultiSearchParamStore,
-  type MultiSearchParamStoreOptions,
-} from './multi-search-param-store'
+} from '../state'
 export { defineNav, navGroup, navTarget, flattenNav } from './nav'
 export type {
   NavItemMeta,
@@ -59,7 +48,7 @@ export type {
 } from './nav'
 export { useNav } from './use-nav'
 export type { UseNavOptions, NavBinding } from './use-nav'
-export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../nav/types'
+export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../shell/nav-types'
 import type { ReactNode } from 'react'
 import { useLocation, useMatches } from '@tanstack/react-router'
 

package/src/router-tanstack/nav.ts

@@ -12,7 +12,7 @@
  * No JSX and no Mantine in this module — `./router-tanstack` is a headless barrel by contract.
  */
 import type { ReactNode } from 'react'
-import type { NavMobilePlacement, NavSectionMobile } from '../nav/types'
+import type { NavMobilePlacement, NavSectionMobile } from '../shell/nav-types'
 
 // ── authoring shapes ─────────────────────────────────────────────────────────────────────────────
 

package/src/router-tanstack/search-store.ts

@@ -30,16 +30,9 @@
  * Headless — no Mantine, no JSX. Same tier as `useBasaltNav` and `useRouterBreadcrumbs`.
  */
 import { useNavigate, useSearch } from '@tanstack/react-router'
-import { createStoreCore } from '../state'
-import type {
-  AnyField,
-  FieldHandle,
-  FieldSetOptions,
-  FieldWrite,
-  SearchValues,
-  StoreEntry,
-  StoredValues,
-} from '../state'
+import { createStoreCore } from '../state/fields'
+import type { FieldWrite, StoreEntry } from '../state/fields'
+import type { AnyField, FieldHandle, FieldSetOptions, SearchValues, StoredValues } from '../state'
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -219,12 +212,11 @@ function isMemoryLane(entry: StoreEntry): boolean {
 }
 
 /**
- * The store, plus the one knob the deprecated wrappers need: `legacyValueField` keeps the
- * enum-only stores' single-value storage layout so an already-persisted selection still resolves.
- * Not exported from the barrel — `createSearchStore` is the public door.
+ * The store's implementation. Not exported from the barrel — `createSearchStore` is the public
+ * door.
  */
 export function buildSearchStore<const S extends Record<string, AnyField>>(
-  o: CreateSearchStoreOptions<S> & { legacyValueField?: string },
+  o: CreateSearchStoreOptions<S>,
 ): InternalSearchStore<S> {
   assertNoLazyUrlFallback(o.key, o.fields)
   const core = createStoreCore(o)

package/src/router-tanstack/use-nav.ts

@@ -12,7 +12,7 @@
 import { createElement, useMemo } from 'react'
 import type { ElementType, ReactNode } from 'react'
 import { Link, useMatchRoute, useRouterState } from '@tanstack/react-router'
-import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../nav/types'
+import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../shell/nav-types'
 import { flattenNav } from './nav'
 import type { AnyNavGroup, AnyNavItem, NavConfig, NavItemId, NavTabId } from './nav'
 
@@ -113,26 +113,31 @@ export function useNav<
       // chain: the widened `AnyNavLink['search']` is `unknown`, which `LinkComponentProps` rejects.
       // The consumer gets zero casts, which is the point.
       //
-      // `activeOptions: { exact: true }` is what makes `resolveState` above the ONLY authority on
-      // active, and it is not a preference — a `Link` computes its own `isActive` (default
-      // `activeOptions.exact: false`, i.e. prefix) and spreads `{ 'data-status': 'active',
-      // 'aria-current': 'page' }` LAST, after `activeProps` and after every caller prop
-      // (`@tanstack/react-router/dist/esm/link.js` — `...isActive && STATIC_ACTIVE_PROPS` is the
-      // final entry of the returned object). So `aria-current` cannot be overridden from outside;
-      // the only lever is `isActive` itself. Left at its default, the router re-derived the exact
-      // fuzzy match this resolver exists to replace, and at `/dashboard/sessions` BOTH the parent
-      // and the child anchor carried `aria-current="page"` even with basalt's own model marking one
-      // of them an ancestor — verified in Chrome, and the reason the first attempt at this fix
-      // measured as no fix at all.
+      // `activeOptions: { exact: true, includeSearch: true }` is what makes `resolveState` above
+      // the ONLY authority on active, and it is not a preference — a `Link` computes its own
+      // `isActive` (default `activeOptions.exact: false`, i.e. prefix) and spreads
+      // `{ 'data-status': 'active', 'aria-current': 'page' }` LAST, after `activeProps` and after
+      // every caller prop (`@tanstack/react-router/dist/esm/link.js` — `...isActive &&
+      // STATIC_ACTIVE_PROPS` is the final entry of the returned object). So `aria-current` cannot
+      // be overridden from outside; the only lever is `isActive` itself. Left at its default, the
+      // router re-derived the exact fuzzy match this resolver exists to replace, and at
+      // `/dashboard/sessions` BOTH the parent and the child anchor carried `aria-current="page"`
+      // even with basalt's own model marking one of them an ancestor — verified in Chrome, and the
+      // reason the first attempt at this fix measured as no fix at all. `includeSearch` already
+      // defaults to `true` upstream; naming it here is belt-and-braces so a future default change
+      // cannot silently reopen the gap.
       //
       // Exact here does NOT narrow basalt's own law. `resolveState` still matches fuzzily and still
       // lights an item whose exact route is never visited; that item is simply named by the
       // `aria-current` `app-sidebar.tsx` stamps itself, which survives because the router's spread
-      // is conditional on ITS `isActive` being true.
+      // is conditional on ITS `isActive` being true. The CSS side no longer treats `aria-current`
+      // as a style hook either (`theme/nav-link.module.css`, `shell/app-sidebar.module.css`), so
+      // `use-nav`'s single `data-active` winner is the one visual authority even if the router's
+      // own `isActive` ever disagreed.
       const Anchor: NavAnchor = (props) =>
         createElement(Link as ElementType, {
           ...item.link,
-          activeOptions: { exact: true },
+          activeOptions: { exact: true, includeSearch: true },
           ...props,
         })
 

package/src/shell/account-types.ts

@@ -6,8 +6,11 @@
  */
 import type { ReactNode } from 'react'
 
-/** Badge tone for a role/plan chip. No dedicated tone union exists elsewhere in the shell/tokens
- * layers, so this is defined locally. */
+/**
+ * Badge tone for a role/plan chip. A different member set from `common`'s `Tone` (`common/props.ts`,
+ * audit A13) — `'neutral' | 'brand'` have no `Tone` equivalent — so this stays its own type rather
+ * than an alias; see `Tone` for the base three-tone vocabulary the rest of the framework shares.
+ */
 export type AccountBadgeTone = 'neutral' | 'brand' | 'success' | 'warn'
 
 /** The signed-in user's identity. `image` is nullable and currently unused by `SidebarAccount`