basalt-ui 1.40.3 → 2.0.0

package/src/provider/index.tsx

@@ -1,168 +1,99 @@
 /**
- * BasaltProvider — wraps `MantineProvider` with the Basalt theme, injects the `--vx-*` palette
- * stylesheet, and bridges Mantine's color scheme into the Vx chart theme context so chrome and
- * charts share one scheme-reactive identity.
+ * BasaltProvider — the one provider tree (V2-SPEC § 2): `MantineProvider` with the Basalt theme and
+ * resolver, the `--vx-*` palette `<style>`, and then
+ * `QueryClientProvider > ModalsProvider > RouterProvider` with `Notifications` and `Spotlight` as
+ * siblings. The consumer writes the route tree, the nav and the registries.
  *
- * Grounded in argo: argo split this into `main.tsx` (the `MantineProvider` + `cssVariablesResolver`
- * wiring) and `charts-bridge.tsx` (the `VxBridge`: read the Mantine color scheme, provide the Vx
- * context, inject the palette `<style>`). Basalt folds the GENERIC half of both into one provider.
- * The DOMAIN half of argo's `main.tsx` — router, query client, app routes, auth gate, the concrete
- * series/sections — stays in the consumer and does NOT extract.
+ * It also owns the root error boundary, the `window` error listeners and the telemetry seam
+ * (V2-SPEC § 7), the command hotkeys and Spotlight actions, and — in dev only — the dev dock.
  *
- * The palette injection is pure CSS: the `<style>` emitted by `buildPaletteCss` keys off Mantine's
- * `[data-mantine-color-scheme]` attribute, so dark/light resolution needs no React re-render. The
- * Vx context still carries the resolved `colorScheme` for any non-color branching a chart may need.
- *
- * Mantine usage is allowed in this `./` root layer (unlike `src/charts/**` and `src/tokens/**`).
+ * The palette injection is pure CSS keyed off Mantine's `[data-mantine-color-scheme]` attribute, so
+ * dark/light resolution needs no React re-render.
  */
-import {
-  MantineProvider,
-  useComputedColorScheme,
-  useMantineColorScheme,
-  useMantineTheme,
-} from '@mantine/core'
+import { MantineProvider, useMantineColorScheme, useMantineTheme } from '@mantine/core'
 import type { MantineProviderProps } from '@mantine/core'
-import { Component, useEffect, useMemo } from 'react'
+import { ModalsProvider } from '@mantine/modals'
+import { Notifications } from '@mantine/notifications'
+import { Spotlight } from '@mantine/spotlight'
+import type { SpotlightActionData } from '@mantine/spotlight'
+import { QueryClientProvider } from '@tanstack/react-query'
+import type { QueryClient } from '@tanstack/react-query'
+import { RouterProvider } from '@tanstack/react-router'
+import type { AnyRouter } from '@tanstack/react-router'
+import { Component, Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { ErrorInfo, ReactNode } from 'react'
-import { VxThemeProvider } from '../charts/theme'
 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 { buildDensityCss, buildFontsCss, buildPaletteCss, buildRadiusCss } from '../tokens/core'
+import type { BuildPaletteOpts } from '../tokens/core'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
 import { useMediaQuery } from '../common/use-media-query'
+import { registerModalsProvider } from '../commands/define-overlays'
 import { registerColorSchemeSetter } from '../commands/shell-bridge'
 import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import { PageTitle } from '../shell/page-title'
 import { SizeClassHintContext } from '../shell/use-size-class'
 import type { SizeClass } from '../shell/use-size-class'
-
-/**
- * Where an error surfaced — drives consumer routing (a render error vs a global rejection differ).
- *
- * @example
- * <BasaltProvider
- *   onError={(e, ctx) => {
- *     if (ctx.kind === 'render') Sentry.captureException(e, { extra: { info: ctx.info } })
- *     if (ctx.kind === 'unhandledrejection') Sentry.captureException(e)
- *   }}
- * >
- */
-export type BasaltErrorContext =
-  | { kind: 'render'; info: ErrorInfo }
-  | { kind: 'window'; event: ErrorEvent }
-  | { kind: 'unhandledrejection'; reason: unknown }
+import { TelemetryContext, bindRouterTelemetry, createEmitter, errorName, now } from '../telemetry'
+import type { Telemetry } from '../telemetry'
+import type { BasaltDevDockTool } from '../dev-dock'
+import type { BasaltRouter, BasaltRouterContext } from './create-router'
+import { useRegistryHotkeys } from './hotkeys'
+import { buildSpotlightActions } from './spotlight-actions'
 
 export type BasaltProviderProps = {
-  children: ReactNode
-  /** Theme override merged onto the Basalt base. Omit to use the base theme as-is. */
+  /** From `createBasaltRouter`; the provider mounts it and reads its `queryClient`. */
+  router: BasaltRouter
+  /** Theme override merged onto the Basalt base. Defaults to `createBasaltTheme()`. */
   theme?: MantineProviderProps['theme']
+  /**
+   * Typed events (V2-SPEC § 7) — navigations, route/query/mutation/render/window errors. Called
+   * synchronously and wrapped in `try/catch`, so a throwing sink never breaks a render. Events carry
+   * ids, hashes, counts and durations only; no sink, no events.
+   */
+  telemetry?: Telemetry
+  /** The root error boundary's UI. Unset → a minimal page with a reload button; `null` renders nothing. */
+  fallback?: ReactNode | ((error: unknown) => ReactNode)
   /**
    * Inject the `--vx-*` palette stylesheet once via an inline `<style>`. Default `true`. Set
-   * `false` to skip it (SSR / head injection — emit `buildPaletteCss(paletteOptions)` yourself, all
-   * three builders importable from `basalt-ui/tokens`).
-   * A `{ fonts }` config passed to `createBasaltTheme` rides this SAME injection (its
-   * `--basalt-font-*` declarations are appended to the same `<style>`), so `injectPalette={false}`
-   * opts fonts out too — emit `buildFontsCss(theme.other.basaltFonts)` yourself alongside the
-   * palette CSS in that case.
-   * A `{ radius }` config rides the SAME injection too (its `--vx-radius-*` override declarations
-   * are appended alongside), so `injectPalette={false}` opts radius out just the same — an SSR
-   * consumer disabling injection must also emit `buildRadiusCss(theme.other.basaltRadius)`
-   * themselves, or `var(--vx-radius-*)` consumers render at their defaults instead of the retuned
-   * level.
-   * A `{ density }` config rides the SAME injection too (its `--vx-space-*` override declarations
-   * are appended alongside), so `injectPalette={false}` opts density out just the same — an SSR
-   * consumer disabling injection must also emit `buildDensityCss(theme.other.basaltDensity)`
-   * themselves, or `var(--vx-space-*)` consumers render at their defaults instead of the retuned
-   * level.
+   * `false` to skip it (SSR / head injection — emit `buildPaletteCss(paletteOptions)` yourself).
+   * Fonts, radius and density configs ride the same injection, so `false` opts them out too.
    */
   injectPalette?: boolean
   /**
    * Passed through to `buildPaletteCss` so a consumer can append its own series/groups/derived
-   * declarations on top of the framework primitives. Additive extension to the S0 stub shape.
+   * declarations on top of the framework primitives.
    */
   paletteOptions?: BuildPaletteOpts
   /** Default color scheme. Defaults to dark. */
   defaultColorScheme?: MantineProviderProps['defaultColorScheme']
   /**
-   * Report errors caught by the in-provider boundary AND global window/unhandledrejection listeners.
-   * Unset → console.error in dev (process.env.NODE_ENV !== 'production'), no-op in prod.
-   * NEVER a no-op prop — the BasaltErrorBoundary + listeners that feed it ship in this same freeze.
-   *
-   * @example
-   * <BasaltProvider onError={(e, ctx) => Sentry.captureException(e, { tags: { kind: ctx.kind } })}>
-   */
-  onError?: (error: unknown, ctx: BasaltErrorContext) => void
-  /**
-   * CSP nonce for the raw palette `<style>` at provider/index.tsx (the one element `...rest`
-   * cannot reach — it is basalt's own JSX, not a Mantine prop). For Mantine's own injected styles,
-   * also pass `getStyleNonce={() => nonce}` via `...rest` — Mantine v9 has no top-level `nonce`
-   * prop; its nonce mechanism is `getStyleNonce: () => string`, which flows through `...rest`.
+   * CSP nonce for the raw palette `<style>` (the one element `...rest` cannot reach). For Mantine's
+   * own injected styles also pass `getStyleNonce={() => nonce}` via `...rest`.
    */
   nonce?: string
-  /**
-   * 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'>
   /**
    * The size class `useSizeClass()` reports on the server and during hydration, before `matchMedia`
-   * can answer. Default `'compact'` (mobile-first). SSR only: a client-rendered (`createRoot`) app
-   * reads `matchMedia` on its first render and never sees this value. An SSR app that knows the
-   * device class (UA hint, cookie) passes it so the first frame already matches. An SSR desktop app
-   * SHOULD pass it: without it the first paint is `'compact'`, and `PageAside`/`ThreadWorkspace`
-   * remount after hydration when the real class lands.
+   * can answer. Default `'compact'`. SSR only; an SSR desktop app SHOULD pass it.
    */
   sizeClassHint?: SizeClass
 } & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>
 
-// ── Default error handler ─────────────────────────────────────────────────────────────────────────
-
-function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
-  if (process.env.NODE_ENV !== 'production') {
-    // eslint-disable-next-line no-console -- intentional dev-only diagnostic when no onError is supplied
-    console.error('[BasaltProvider] unhandled error', ctx.kind, error)
-  }
-  // prod: no-op
-}
+// ── Root error boundary ───────────────────────────────────────────────────────────────────────────
 
-// ── Error boundary ────────────────────────────────────────────────────────────────────────────────
-
-/**
- * `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 = {
+type RootBoundaryProps = {
   children: ReactNode
-  /**
-   * 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)
+  emit: Telemetry
+  fallback: BasaltProviderProps['fallback']
 }
 
 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.
+ * The boundary's own default fallback — a `PageTitle` plus a plain reload affordance. Deliberately
+ * minimal: a consumer wanting session ids or a "try to recover" reset passes its own `fallback`.
  */
 function DefaultErrorFallback(): ReactNode {
   return (
@@ -182,18 +113,9 @@ function DefaultErrorFallback(): ReactNode {
   )
 }
 
-/**
- * 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.
- * Also exported so consumers can mount nested boundaries with the same `onError` contract.
- *
- * @example
- * <BasaltErrorBoundary onError={(e, ctx) => Sentry.captureException(e)} fallback={<p>Something went wrong.</p>}>
- *   <MyFeature />
- * </BasaltErrorBoundary>
- */
-export class BasaltErrorBoundary extends Component<BasaltErrorBoundaryProps, BoundaryState> {
-  constructor(props: BasaltErrorBoundaryProps) {
+/** Catches render-phase errors inside `MantineProvider`, so a fallback still has theme context. */
+export class RootBoundary extends Component<RootBoundaryProps, BoundaryState> {
+  constructor(props: RootBoundaryProps) {
     super(props)
     this.state = { hasError: false, error: undefined }
   }
@@ -202,43 +124,43 @@ export class BasaltErrorBoundary extends Component<BasaltErrorBoundaryProps, Bou
     return { hasError: true, error }
   }
 
-  override componentDidCatch(error: unknown, info: ErrorInfo): void {
-    const onError = this.props.onError ?? defaultOnError
-    onError(error, { kind: 'render', info })
+  override componentDidCatch(error: unknown, _info: ErrorInfo): void {
+    if (process.env.NODE_ENV !== 'production') console.error('[basalt] render error', error)
+    this.props.emit({
+      type: 'render.error',
+      failed: true,
+      start: now(),
+      attributes: {
+        'exception.type': errorName(error),
+        'basalt.error.kind': 'render',
+        'basalt.error.boundary': 'root',
+      },
+    })
   }
 
   override render(): ReactNode {
-    if (this.state.hasError) {
-      const { fallback } = this.props
-      if (fallback === undefined) return <DefaultErrorFallback />
-      if (fallback === null) return null
-      return typeof fallback === 'function' ? fallback(this.state.error) : fallback
-    }
-    return this.props.children
+    if (!this.state.hasError) return this.props.children
+    const { fallback } = this.props
+    if (fallback === undefined) return <DefaultErrorFallback />
+    if (fallback === null) return null
+    return typeof fallback === 'function' ? fallback(this.state.error) : fallback
   }
 }
 
 /**
  * Compose the four independently-built override CSS blocks into ONE injected `<style>` body, in
- * cascade-winning order. Every builder (`buildPaletteCss`/`buildFontsCss`/`buildRadiusCss`/
- * `buildDensityCss`) emits its declarations under a bare `:root { ... }` block — EQUAL selector
- * specificity across all four — so nothing but DOCUMENT ORDER decides which value a browser paints
- * when two blocks declare the same custom property. `density` must come LAST (its `--vx-space-*`
- * overrides must out-cascade the base palette's own defaults), `radius` after `fonts`, `fonts` after
- * `base` — reorder this array and the density/radius/fonts knobs silently stop working, with every
- * OTHER existing test still green (each builder is tested for its OWN output in isolation, not for
- * where it lands in the concatenated string). Exported as a pure function (not inlined in
- * `BasaltBridge`'s `useMemo`) purely so `provider/index.test.ts` can assert the ORDER holds without
- * rendering a React tree.
+ * cascade-winning order. Every builder emits its declarations under a bare `:root { ... }` block —
+ * EQUAL selector specificity — so nothing but DOCUMENT ORDER decides which value a browser paints.
+ * `density` must come LAST, `radius` after `fonts`, `fonts` after `base`; reorder this array and the
+ * knobs silently stop working. Exported as a pure function so a test can assert the ORDER.
  */
 export function composeInjectedCss(
   base: string,
   fontsCss: string,
   radiusCss: string,
   densityCss: string,
-  inputsCss = '',
 ): string {
-  return [base, fontsCss, radiusCss, densityCss, inputsCss].filter(Boolean).join('\n')
+  return [base, fontsCss, radiusCss, densityCss].filter(Boolean).join('\n')
 }
 
 // ── Host attribute ────────────────────────────────────────────────────────────────────────────────
@@ -284,30 +206,22 @@ export function useHostAttribute(): void {
 // ── Inner bridge ──────────────────────────────────────────────────────────────────────────────────
 
 /**
- * Inner bridge — must render INSIDE `MantineProvider` to read the active color scheme. Provides
- * the Vx chart theme context and injects the palette `<style>`. Mirrors argo's `VxBridge`.
- * Also registers global window error listeners for the `onError` contract.
+ * Inner bridge — must render INSIDE `MantineProvider` (it reads the theme and registers the
+ * color-scheme handle). Injects the palette `<style>`; charts paint through those CSS variables.
  */
 function BasaltBridge({
   children,
   injectPalette,
   paletteOptions,
   nonce,
-  onError,
 }: {
   children: ReactNode
   injectPalette: boolean
   paletteOptions: BuildPaletteOpts | undefined
   nonce: string | undefined
-  onError: (error: unknown, ctx: BasaltErrorContext) => void
 }) {
-  // Resolve via Mantine's computed scheme so 'auto' follows the OS prefers-color-scheme
-  // (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).
+  // `MantineProvider`) so a consumer's `commands.tsx` calls it with ZERO `__root.tsx` wiring.
   const { setColorScheme: setMantineColorScheme } = useMantineColorScheme()
   useEffect(() => {
     registerColorSchemeSetter(setMantineColorScheme)
@@ -315,18 +229,14 @@ function BasaltBridge({
   }, [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
+  // paths stash the resolved values on `theme.other.basalt*` — read them here (INSIDE
   // MantineProvider, so `useMantineTheme` sees the fully-merged runtime theme) to decide whether the
-  // pre-baked static palette CSS still applies or a re-derived one is needed, and whether any
-  // `--basalt-font-*` / `--vx-radius-*` / `--vx-space-*` override declarations must ride along.
-  // Default/absent config -> zero extra derivation work.
+  // pre-baked static palette CSS still applies or a re-derived one is needed.
   const theme = useMantineTheme()
   const deriveConfig = theme.other?.basaltDerive
   const fontsConfig = theme.other?.basaltFonts
   const radiusConfig = theme.other?.basaltRadius
   const densityConfig = theme.other?.basaltDensity
-  const desktopInputs = theme.other?.['basaltInputs'] === 'desktop'
   const paletteCss = useMemo(() => {
     if (!injectPalette) return ''
     const base =
@@ -335,48 +245,19 @@ function BasaltBridge({
         : // Memoized by `buildPaletteData` (keyed on the config value), so retuning is never a
           // per-render re-derivation once a given config has been built once.
           buildPaletteCss(paletteOptions, buildPaletteData(deriveConfig))
-    const fontsCss = buildFontsCss(fontsConfig)
-    const radiusCss = buildRadiusCss(radiusConfig)
-    const densityCss = buildDensityCss(densityConfig)
-    // `createBasaltTheme({ inputs: 'desktop' })` — lifts the iOS 16px input-font floor (`styles.css`).
-    const inputsCss = desktopInputs ? ':root {\n--basalt-input-fz-floor: 0px;\n}' : ''
-    return composeInjectedCss(base, fontsCss, radiusCss, densityCss, inputsCss)
-  }, [
-    injectPalette,
-    deriveConfig,
-    fontsConfig,
-    radiusConfig,
-    densityConfig,
-    desktopInputs,
-    paletteOptions,
-  ])
-
-  useEffect(() => {
-    // SSR guard — window is not available in server contexts
-    if (typeof window === 'undefined') return
-
-    const handleError = (e: ErrorEvent): void => {
-      onError(e.error ?? e, { kind: 'window', event: e })
-    }
-
-    const handleUnhandledRejection = (e: PromiseRejectionEvent): void => {
-      onError(e.reason, { kind: 'unhandledrejection', reason: e.reason })
-    }
-
-    window.addEventListener('error', handleError)
-    window.addEventListener('unhandledrejection', handleUnhandledRejection)
-
-    return () => {
-      window.removeEventListener('error', handleError)
-      window.removeEventListener('unhandledrejection', handleUnhandledRejection)
-    }
-  }, [onError])
+    return composeInjectedCss(
+      base,
+      buildFontsCss(fontsConfig),
+      buildRadiusCss(radiusConfig),
+      buildDensityCss(densityConfig),
+    )
+  }, [injectPalette, deriveConfig, fontsConfig, radiusConfig, densityConfig, paletteOptions])
 
   return (
-    <VxThemeProvider colorScheme={resolved}>
+    <>
       {injectPalette ? <style nonce={nonce}>{paletteCss}</style> : null}
       {children}
-    </VxThemeProvider>
+    </>
   )
 }
 
@@ -386,7 +267,7 @@ function BasaltBridge({
  * 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
+ * `MantineProvider`, the palette `<style>`, the router and the overlays — 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).
  */
@@ -397,31 +278,164 @@ function useDuplicateProviderGuard(): void {
     if (providerMounts.mount() > 1 && process.env.NODE_ENV !== 'production') {
       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.',
+          'BasaltProviders double-mount MantineProvider, the palette <style>, the router and the ' +
+          'overlays. Mount exactly one, at the app root.',
       )
     }
     return () => void providerMounts.unmount()
   }, [])
 }
 
+// ── Telemetry sources ─────────────────────────────────────────────────────────────────────────────
+
+/** `window` `error` / `unhandledrejection` → `window.error`. */
+function useWindowErrors(emit: Telemetry): void {
+  useEffect(() => {
+    const report = (source: 'error' | 'unhandledrejection', error: unknown): void => {
+      if (process.env.NODE_ENV !== 'production') console.error(`[basalt] ${source}`, error)
+      emit({
+        type: 'window.error',
+        failed: true,
+        start: now(),
+        attributes: {
+          'exception.type': errorName(error),
+          'basalt.error.kind': source === 'error' ? 'window' : 'unhandledrejection',
+          'basalt.error.source': source,
+        },
+      })
+    }
+    const onError = (e: ErrorEvent): void => report('error', e.error ?? e)
+    const onRejection = (e: PromiseRejectionEvent): void => report('unhandledrejection', e.reason)
+    window.addEventListener('error', onError)
+    window.addEventListener('unhandledrejection', onRejection)
+    return () => {
+      window.removeEventListener('error', onError)
+      window.removeEventListener('unhandledrejection', onRejection)
+    }
+  }, [emit])
+}
+
+/** Router navigations and the QueryClient's caches → `route.*`, `query.error`, `mutation.error`. */
+function useDataTelemetry(router: AnyRouter, client: QueryClient, emit: Telemetry): void {
+  useEffect(() => {
+    const unbind = bindRouterTelemetry(router, emit)
+
+    // Keyed by the target href: a newer navigation overwrites, and a resolve for any other target
+    // (a superseded or redirected navigation) is dropped rather than paired with the wrong start.
+    let pending: { href: string; start: number; from: string } | undefined
+    const offBefore = router.subscribe('onBeforeNavigate', (ev) => {
+      pending = { href: ev.toLocation.href, start: now(), from: ev.fromLocation?.pathname ?? '' }
+    })
+    const offResolved = router.subscribe('onResolved', (ev) => {
+      if (pending?.href !== ev.toLocation.href) return
+      const { start, from } = pending
+      pending = undefined
+      emit({
+        type: 'route.navigate',
+        failed: false,
+        start,
+        duration: now() - start,
+        attributes: {
+          'basalt.route.id': router.state.matches.at(-1)?.routeId ?? 'unknown',
+          'basalt.route.from': from,
+          'url.path': ev.toLocation.pathname,
+        },
+      })
+    })
+
+    const offQuery = client.getQueryCache().subscribe((ev) => {
+      if (ev.type !== 'updated' || ev.action.type !== 'error') return
+      emit({
+        type: 'query.error',
+        failed: true,
+        start: now(),
+        attributes: {
+          'basalt.query.hash': ev.query.queryHash,
+          'basalt.query.failure_count': ev.query.state.fetchFailureCount,
+          'exception.type': errorName(ev.action.error),
+          'basalt.error.kind': 'query',
+        },
+      })
+    })
+    const offMutation = client.getMutationCache().subscribe((ev) => {
+      if (ev.type !== 'updated' || ev.action.type !== 'error') return
+      emit({
+        type: 'mutation.error',
+        failed: true,
+        start: now(),
+        attributes: {
+          'basalt.mutation.key': JSON.stringify(ev.mutation.options.mutationKey ?? null),
+          'exception.type': errorName(ev.action.error),
+          'basalt.error.kind': 'mutation',
+        },
+      })
+    })
+
+    return () => {
+      unbind()
+      offBefore()
+      offResolved()
+      offQuery()
+      offMutation()
+    }
+  }, [router, client, emit])
+}
+
+// ── Dev dock (dev-only, behind a literal NODE_ENV read at the lazy site) ──────────────────────────
+
+const LazyDevDock = lazy(() => import('../dev-dock').then((m) => ({ default: m.BasaltDevDock })))
+
+function readQueryClient(router: AnyRouter): QueryClient {
+  const client = (router.options.context as Partial<BasaltRouterContext> | undefined)?.queryClient
+  if (client === undefined) {
+    throw new Error(
+      '[basalt] BasaltProvider: the router has no context.queryClient — create it with ' +
+        'createBasaltRouter({ routeTree }).',
+    )
+  }
+  return client
+}
+
 // ── Public provider ───────────────────────────────────────────────────────────────────────────────
 
 export function BasaltProvider({
-  children,
+  router,
   theme,
+  telemetry,
+  fallback,
   injectPalette = true,
   paletteOptions,
   defaultColorScheme = 'dark',
-  onError,
   nonce,
-  connectivity,
   sizeClassHint = 'compact',
   ...rest
 }: BasaltProviderProps) {
   useDuplicateProviderGuard()
   useHostAttribute()
-  const errorHandler = onError ?? defaultOnError
+
+  // The sink is read through a ref, so an inline `telemetry` function does not re-subscribe.
+  const sinkRef = useRef(telemetry)
+  useEffect(() => {
+    sinkRef.current = telemetry
+  })
+  const emit = useMemo(() => createEmitter((event) => sinkRef.current?.(event)), [])
+  useWindowErrors(emit)
+  useRegistryHotkeys()
+  // `overlays.confirm` is an imperative call; this tells it a `ModalsProvider` is live.
+  useEffect(() => registerModalsProvider(), [])
+
+  const client = readQueryClient(router)
+  useDataTelemetry(router, client, emit)
+
+  const [devTool, setDevTool] = useState<BasaltDevDockTool | null>(null)
+  // Rebuilt on mount and again at every open, so a command's `when()` is read when the palette
+  // appears, not frozen at mount — and `detectMac` (inside the builder) never runs during render.
+  const [actions, setActions] = useState<SpotlightActionData[]>([])
+  const refreshActions = useCallback(
+    () => setActions(buildSpotlightActions(router, setDevTool)),
+    [router],
+  )
+  useEffect(refreshActions, [refreshActions])
 
   // `createBasaltTheme(theme)` — plus, when the theme lab's "Apply" switch is on, the delta of its
   // persisted config, so the dev tool moves the numeric `defaultProps` and `theme.spacing` a `<style>`
@@ -429,31 +443,47 @@ 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.
+    // exists to install.
     <MantineProvider
       {...rest}
       theme={resolvedTheme}
       cssVariablesResolver={cssVariablesResolver}
       defaultColorScheme={defaultColorScheme}
     >
-      <BasaltErrorBoundary onError={errorHandler}>
-        <BasaltBridge
-          injectPalette={injectPalette}
-          paletteOptions={paletteOptions}
-          nonce={nonce}
-          onError={errorHandler}
-        >
-          <SizeClassHintContext.Provider value={sizeClassHint}>
-            <ConnectivityProvider {...resolvedConnectivity}>{children}</ConnectivityProvider>
-          </SizeClassHintContext.Provider>
+      <RootBoundary emit={emit} fallback={fallback}>
+        <BasaltBridge injectPalette={injectPalette} paletteOptions={paletteOptions} nonce={nonce}>
+          <TelemetryContext.Provider value={emit}>
+            <SizeClassHintContext.Provider value={sizeClassHint}>
+              <QueryClientProvider client={client}>
+                {/* ModalsProvider WRAPS the router, so `useModals()` / `openContextModal` have real context. */}
+                <ModalsProvider>
+                  <RouterProvider router={router} />
+                  {/* The literal read sits at the branch, so a production build drops the import. */}
+                  {process.env.NODE_ENV !== 'production' && (
+                    <Suspense fallback={null}>
+                      <LazyDevDock
+                        tool={devTool}
+                        onClose={() => setDevTool(null)}
+                        router={router}
+                      />
+                    </Suspense>
+                  )}
+                </ModalsProvider>
+              </QueryClientProvider>
+              <Notifications position="bottom-right" autoClose={4000} limit={5} />
+              <Spotlight
+                actions={actions}
+                onSpotlightOpen={refreshActions}
+                shortcut="mod + K"
+                maxHeight={420}
+              />
+            </SizeClassHintContext.Provider>
+          </TelemetryContext.Provider>
         </BasaltBridge>
-      </BasaltErrorBoundary>
+      </RootBoundary>
     </MantineProvider>
   )
 }