basalt-ui 1.27.0 → 1.29.0

package/src/notifications/center.tsx

@@ -25,6 +25,8 @@ import {
   Stack,
   Text,
 } from '@mantine/core'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import { VX } from '../tokens'
 import { resolveAction } from './define-notifications'
 import { useNotificationHistory } from './store'
@@ -64,6 +66,11 @@ const INTENT_STATUS: Record<NotificationIntent, string> = {
 
 type CenterView = 'inbox' | 'all'
 
+/** The popover width `NotificationBell` fixes at the `Popover` level (see `NotificationCenter`'s
+ *  own doc for why WIDTH lives there and not on this component). Shared so the two call sites and
+ *  this doc's example never drift apart. */
+export const NOTIFICATION_POPOVER_WIDTH = 320
+
 // ── NotificationItem ──────────────────────────────────────────────────────────
 
 function NotificationItem({
@@ -150,7 +157,7 @@ function NotificationItem({
 
 // ── NotificationCenter ────────────────────────────────────────────────────────
 
-export type NotificationCenterProps = {
+export type NotificationCenterProps = BasaltProps & {
   /** Maximum height of the scrollable list. Default: 320px. */
   maxHeight?: number | string
 }
@@ -160,16 +167,22 @@ export type NotificationCenterProps = {
  * registry-resolved action buttons. Designed to be mounted inside a Popover or Drawer (e.g.
  * NotificationBell).
  *
+ * Sizes to its host's full width (`width: 100%`) rather than a fixed px — a popover default that
+ * overflowed any inline mount. `NotificationBell` fixes the WIDTH at the Popover level instead
+ * (`<Popover width={NOTIFICATION_POPOVER_WIDTH}>`), which is the correct home for a
+ * popover-specific dimension; a consumer mounting this directly controls the same thing through
+ * its own container.
+ *
  * @example
- * import { NotificationCenter } from 'basalt-ui/notifications'
+ * import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from 'basalt-ui/notifications'
  *
- * <Popover>
+ * <Popover width={NOTIFICATION_POPOVER_WIDTH}>
  *   <Popover.Dropdown>
  *     <NotificationCenter />
  *   </Popover.Dropdown>
  * </Popover>
  */
-export function NotificationCenter({ maxHeight = 320 }: NotificationCenterProps) {
+export function NotificationCenter({ maxHeight = 320, className, style }: NotificationCenterProps) {
   const { items, inbox, unreadCount, markRead, markAllRead, dismiss, dismissAll, remove, clear } =
     useNotificationHistory()
   const [view, setView] = useState<CenterView>('inbox')
@@ -178,7 +191,7 @@ export function NotificationCenter({ maxHeight = 320 }: NotificationCenterProps)
   const emptyLabel = view === 'inbox' ? "You're all caught up" : 'No notifications yet'
 
   return (
-    <Stack gap="xs" style={{ width: 320 }}>
+    <Stack className={cx(className)} gap="xs" style={{ width: '100%', ...style }}>
       {/* Header: title + a single mark-all-read affordance (only when there's something unread) */}
       <Group justify="space-between" align="center" wrap="nowrap">
         <Text size="sm" fw={600}>

package/src/notifications/define-notifications.ts

@@ -5,6 +5,11 @@
  * Consumer augments BasaltRegister.notifications with the spec map type, then uses the typed
  * `emit` helper which resolves the registered kind at compile-time. An unknown kind is a tsc error.
  *
+ * A kind's payload type is INFERRED, the same way `defineOverlays` infers an overlay's props from
+ * `render` — annotate `toMessage` (or `action.run`) with the payload shape and `emit` picks it up:
+ * `emit('saved', { id })` then requires that shape and a wrong one is a tsc error. A kind that never
+ * annotates either function keeps today's `payload?: unknown` — additive, no existing call breaks.
+ *
  * @example
  * // notifications.ts (app-side)
  * import { defineNotifications } from 'basalt-ui/notifications'
@@ -18,8 +23,9 @@
  *
  * // usage.ts
  * import { emit } from 'basalt-ui/notifications'
- * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed
- * emit('nonexistent', {})                         // ✗ tsc error
+ * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed, and the payload shape is checked
+ * emit('upload:success', 'nope')                  // ✗ tsc error — wrong payload shape
+ * emit('nonexistent', {})                         // ✗ tsc error — unregistered kind
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
@@ -36,23 +42,33 @@ export type { NotificationIntent }
  * registry (code, app-scoped) — only a serializable `{ kind, payload }` ref is persisted — so an
  * actionable notification keeps working after a reload. The handler can do anything (navigate, open
  * a modal, retry a request); it receives the same payload that was passed to `emit`.
+ *
+ * The payload type P is the consumer's own payload — same generic shape as `Overlay<P>` in
+ * ./define-overlays, inferred from `run`'s parameter, not a separate declared field.
  */
-export type NotificationAction = {
+export type NotificationAction<P = unknown> = {
   label: string
-  run: (payload: unknown) => void
+  run: (payload: P) => void
 }
 
 // ── NotificationSpecMap ───────────────────────────────────────────────────────
 
-/** A single notification kind spec — intent + optional payload→message renderer + optional action. */
-export type NotificationSpec = {
+/**
+ * A single notification kind spec — intent + optional payload→message renderer + optional action.
+ *
+ * The payload type P is INFERRED from `toMessage`/`action.run`'s parameter, the same mechanism
+ * `defineOverlays`' `Overlay<P>` uses for `render`. Default `unknown` — a kind that annotates
+ * neither function keeps taking any payload, unchanged.
+ */
+export type NotificationSpec<P = unknown> = {
   intent?: NotificationIntent
-  toMessage?: (payload: unknown) => ReactNode
-  action?: NotificationAction
+  toMessage?: (payload: P) => ReactNode
+  action?: NotificationAction<P>
 }
 
 /** The map of kind → spec that a consumer registers. */
-export type NotificationSpecMap = Record<string, NotificationSpec>
+// oxlint-disable-next-line typescript/no-explicit-any -- load-bearing contravariant spec map, mirrors OverlayMap
+export type NotificationSpecMap = Record<string, NotificationSpec<any>>
 
 // ── Slot extraction (mirror of SeriesKey pattern in register.ts) ──────────────
 
@@ -66,11 +82,33 @@ type Notifications = Slot<'notifications', NotificationSpecMap>
  */
 export type NotificationKind = Extract<keyof Notifications, string>
 
+/**
+ * Extract the inferred payload type for a registered notification kind — mirrors `OverlayProps` in
+ * ./define-overlays (same `infer` over the generic spec type, not a separate declared field).
+ *
+ * Resolves to `unknown` for a kind whose spec never annotates `toMessage`/`action.run` with a
+ * payload shape — that is the additive fallback, not a failure to infer.
+ */
+type NotificationPayload<K extends NotificationKind> = Notifications extends {
+  [_K in K]: NotificationSpec<infer V>
+}
+  ? V
+  : unknown
+
 // ── defineNotification (singular) ────────────────────────────────────────────
 
 /**
- * Type a single notification spec without registering it.
- * Identity passthrough — preserves the exact literal shape for local type-checking.
+ * Type a single notification spec without registering it. Identity passthrough — the payload type
+ * `P` is INFERRED from `toMessage`/`action.run`'s parameter, exactly as it is inside
+ * `defineNotifications`, so a spec typed here and a spec written inline behave identically.
+ *
+ * **It is `NotificationSpec<P>`, NOT `<const T extends NotificationSpec>(spec: T): T`** — the
+ * const-generic shape every other `defineX` factory takes. Under `strictFunctionTypes` that
+ * constraint rejects the example below outright: `T` must extend `NotificationSpec<unknown>`, and a
+ * `toMessage: (p: { name: string }) => …` is not assignable to `(payload: unknown) => …`
+ * (parameters are contravariant). The factory's own documented usage did not compile. Inferring `P`
+ * instead is what makes an annotated payload the point of this file rather than a type error.
+ * `.type-guard.test.ts` pins both halves.
  *
  * **WARNING:** this does NOT register the spec in the runtime registry and does NOT
  * augment BasaltRegister. Use `defineNotifications` (plural) to register a full spec
@@ -85,7 +123,7 @@ export type NotificationKind = Extract<keyof Notifications, string>
  * // Merge into the full registry before passing to defineNotifications:
  * const NOTIFICATIONS = defineNotifications({ 'upload:success': uploadSuccess })
  */
-export function defineNotification<const T extends NotificationSpec>(spec: T): T {
+export function defineNotification<P = unknown>(spec: NotificationSpec<P>): NotificationSpec<P> {
   return spec
 }
 
@@ -116,6 +154,16 @@ export function defineNotifications<const T extends NotificationSpecMap>(spec: T
 
 // ── emit ──────────────────────────────────────────────────────────────────────
 
+/**
+ * The rest-args tuple for `emit`'s payload + opts. A kind whose spec declared a payload shape
+ * (`NotificationPayload<K>` is narrower than `unknown`) requires that shape as a real argument; a
+ * kind that never declared one keeps `payload?: unknown` — the pre-existing, backward-compatible
+ * shape.
+ */
+type EmitArgs<K extends NotificationKind> = [unknown] extends [NotificationPayload<K>]
+  ? [payload?: unknown, opts?: Omit<NotifyOptions, 'intent' | 'message'>]
+  : [payload: NotificationPayload<K>, opts?: Omit<NotifyOptions, 'intent' | 'message'>]
+
 /**
  * Emit a registered notification kind. The kind must be a key of the consumer's registered
  * `BasaltRegister.notifications` map — any other string is a tsc error.
@@ -123,17 +171,15 @@ export function defineNotifications<const T extends NotificationSpecMap>(spec: T
  * Resolves the spec's intent + toMessage, then calls notify(). Extra opts override spec defaults.
  *
  * Un-augmented (Notifications = {}): NotificationKind = never → `emit` is effectively uncallable.
- * Augmented: only the registered keys are accepted.
+ * Augmented: only the registered keys are accepted, and a kind whose spec annotated
+ * `toMessage`/`action.run` with a payload shape requires that shape — see {@link NotificationPayload}.
  *
  * @example
  * emit('upload:success', { name: 'photo.jpg' })
  * emit('upload:error', null, { title: 'Storage full' })
  */
-export function emit(
-  kind: NotificationKind,
-  payload?: unknown,
-  opts?: Omit<NotifyOptions, 'intent' | 'message'>,
-): string {
+export function emit<K extends NotificationKind>(kind: K, ...args: EmitArgs<K>): string {
+  const [payload, opts] = args
   // The kind's compile-time validity comes from the BasaltRegister slot; the runtime spec
   // (intent/toMessage/action) comes from the registry stashed by defineNotifications.
   const spec: NotificationSpec | undefined = activeRegistry[kind]

package/src/notifications/index.ts

@@ -2,7 +2,9 @@
  * ./notifications — Mantine notification adapter battery.
  *
  * Provides notify helpers, a typed registry, a persisted history store, and a bell/center
- * overlay component on top of @mantine/notifications.
+ * component on top of @mantine/notifications. The overlay mount is `<BasaltOverlays notifications
+ * />` (`basalt-ui/commands`) — this subpath no longer ships one of its own (C1 consolidation:
+ * `BasaltNotifications` was superseded and is removed).
  *
  * Optional peer: @mantine/notifications ^9.3.0.
  *
@@ -10,8 +12,8 @@
  *
  * @example
  * // main.tsx — mount the overlay:
- * import { BasaltNotifications } from 'basalt-ui/notifications'
- * <BasaltProvider><BasaltNotifications /><App /></BasaltProvider>
+ * import { BasaltOverlays } from 'basalt-ui/commands'
+ * <BasaltProvider><BasaltOverlays><App /></BasaltOverlays></BasaltProvider>
  *
  * // Usage:
  * import { notifySuccess, notifyError, notifyPromise, NotificationBell } from 'basalt-ui/notifications'
@@ -19,6 +21,10 @@
  * notifyError('Failed', { title: 'Upload error' })
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
+ * // Optimistic mutation with an undo window (the toast's autoClose IS the window):
+ * import { notifyUndo } from 'basalt-ui/notifications'
+ * notifyUndo({ message: 'Item deleted', onUndo: () => restore(), onExpire: () => api.delete(id) })
+ *
  * // Shell bell (globalActions slot):
  * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
@@ -31,8 +37,15 @@ export {
   notifyWarning,
   notifyInfo,
   notifyPromise,
+  notifyUndo,
+  notifyUndoable,
+} from './notify'
+export type {
+  NotifyOptions,
+  NotifyPromiseMessages,
+  NotifyUndoOptions,
+  NotifyUndoHandle,
 } from './notify'
-export type { NotifyOptions, NotifyPromiseMessages } from './notify'
 
 // ── defineNotification + defineNotifications + typed emit ─────────────────────
 export {
@@ -73,7 +86,3 @@ export type { NotificationBellProps } from './bell'
 // ── NotificationCenter ────────────────────────────────────────────────────────
 export { NotificationCenter } from './center'
 export type { NotificationCenterProps } from './center'
-
-// ── BasaltNotifications overlay ───────────────────────────────────────────────
-export { BasaltNotifications } from './overlay'
-export type { BasaltNotificationsProps } from './overlay'

package/src/notifications/mount-guard.ts

@@ -0,0 +1,39 @@
+/**
+ * Duplicate-Notifications-mount guard (F15) — a shared module-level counter, not a per-caller ref,
+ * because the whole point is detecting a SECOND, unrelated caller mounting `<BasaltOverlays
+ * notifications />` (`commands/overlays-mount.tsx`) at once — nested/duplicate mounts double-render
+ * Mantine's `<Notifications />` and neither instance can see the other.
+ *
+ * Lives here (`./notifications`), not `./commands`, so `commands` is the one importing a shared util
+ * rather than the reverse — `./notifications` never depends on `./commands`. Zero `@mantine/*`
+ * import, so pulling it into `commands` does not eagerly load `@mantine/notifications`.
+ *
+ * Not exported from the `./notifications` public barrel (`index.ts`) — internal wiring only, same
+ * as `provider/lab-theme.ts`.
+ */
+import { useEffect } from 'react'
+import { isDev } from '../common/is-dev'
+
+let mountedNotificationsCount = 0
+
+/**
+ * Call from any component that renders a `<Notifications />` overlay. Warns in dev when a second
+ * caller is mounted at the same time. Not a false positive under React 18 StrictMode's double-invoke
+ * (that mounts/unmounts the SAME instance in sequence, so the count returns to 0 before a genuine
+ * second instance could exist).
+ */
+export function useNotificationsMountGuard(): void {
+  useEffect(() => {
+    mountedNotificationsCount++
+    if (mountedNotificationsCount > 1 && isDev()) {
+      console.warn(
+        '[basalt] more than one Notifications overlay is mounted at once — mount exactly ONE ' +
+          "<BasaltOverlays notifications /> (they all render Mantine's <Notifications />, so " +
+          'toasts would double-fire).',
+      )
+    }
+    return () => {
+      mountedNotificationsCount--
+    }
+  }, [])
+}

package/src/notifications/notify.tsx

@@ -7,7 +7,8 @@
  *   2. dedupKey window — module-level Map prevents duplicate keys within 1500ms
  *
  * For loading→success/error transitions use notifyPromise — it calls notifications.update
- * (never show()) so the loading state is replaced correctly.
+ * (never show()) so the loading state is replaced correctly. For an optimistic mutation with a
+ * grace period use notifyUndo — one number is both the Undo affordance and the commit delay.
  *
  * @example
  * notify({ intent: 'success', message: 'Saved' })
@@ -15,6 +16,7 @@
  * notifyPromise(apiCall(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  */
 import type { ReactNode } from 'react'
+import { Button, Group, Text } from '@mantine/core'
 import { notifications } from '@mantine/notifications'
 import { add } from './store'
 import type { NotificationIntent, NotificationActionRef } from './store'
@@ -85,6 +87,12 @@ export type NotifyOptions = {
    * only when calling `notify()` for an action registered in the notifications registry.
    */
   action?: NotificationActionRef
+  /**
+   * What the persisted history records instead of `String(message)`. Only needed when `message` is
+   * a composed ReactNode the store cannot stringify — `String(<Group/>)` is `[object Object]`.
+   * `notifyUndo` passes its plain text here because its toast body carries the Undo button.
+   */
+  historyMessage?: string
 }
 
 // ── notify ────────────────────────────────────────────────────────────────────
@@ -98,7 +106,17 @@ export type NotifyOptions = {
  * const id = notify({ intent: 'error', message: <b>Failed</b>, autoClose: false })
  */
 export function notify(opts: NotifyOptions): string {
-  const { intent = 'info', message, title, icon, autoClose, id, dedupKey, action } = opts
+  const {
+    intent = 'info',
+    message,
+    title,
+    icon,
+    autoClose,
+    id,
+    dedupKey,
+    action,
+    historyMessage,
+  } = opts
 
   // Two-layer dedup: dedupKey window guard
   if (dedupKey !== undefined && isDuplicateKey(dedupKey)) return id ?? nextId()
@@ -123,7 +141,7 @@ export function notify(opts: NotifyOptions): string {
     id: resolvedId,
     intent,
     ...(title !== undefined && { title: String(title) }),
-    message: String(message),
+    message: historyMessage ?? String(message),
     createdAt: Date.now(),
     ...(action !== undefined && { action }),
   })
@@ -186,6 +204,107 @@ export function notifyInfo(
   return notify({ ...opts, intent: 'info', message })
 }
 
+// ── notifyUndo ────────────────────────────────────────────────────────────────
+
+/** Default undo window (ms) — the toast's autoClose and the grace period are the same number. */
+const UNDO_WINDOW_MS = 6000
+
+export type NotifyUndoOptions = {
+  /** The toast text, left of the Undo button. Also what the history records. */
+  message: ReactNode
+  /** Revert the optimistic change. Runs once, on click; `onExpire` then never runs. */
+  onUndo: () => void
+  /** How long the Undo button stays offered, in ms. Also the toast's autoClose. Default: 6000. */
+  window?: number
+  /**
+   * The window elapsed with no undo — the place to COMMIT the optimistic mutation. Runs at most
+   * once, and never after `onUndo`.
+   */
+  onExpire?: () => void
+}
+
+export type NotifyUndoHandle = {
+  /** The toast id — the same id in Mantine and in the notification history. */
+  id: string
+  /**
+   * Close the toast early and settle the window NOW: `onExpire` runs (unless undo already did), so
+   * a dismissed toast can never strand an uncommitted mutation. Idempotent.
+   */
+  dismiss: () => void
+}
+
+/**
+ * Show a toast offering an Undo for `window` ms, then commit.
+ *
+ * The affordance and the grace period are ONE number: `autoClose === window`, so the button is on
+ * screen for exactly as long as undoing still does something. Exactly one of `onUndo` / `onExpire`
+ * runs, exactly once — clicking Undo cancels the timer, and letting it elapse (or calling
+ * `dismiss()`) commits.
+ *
+ * Built on `notify`, so the toast is recorded to the notification history like any other.
+ *
+ * @example
+ * // Optimistic delete: the row is already gone from the UI; commit when the window closes.
+ * setRows((rows) => rows.filter((r) => r.id !== id))
+ * notifyUndo({
+ *   message: 'Item deleted',
+ *   onUndo: () => setRows(before),
+ *   onExpire: () => api.delete(id),
+ * })
+ */
+export function notifyUndo(opts: NotifyUndoOptions): NotifyUndoHandle {
+  const { message, onUndo, window: undoWindow = UNDO_WINDOW_MS, onExpire } = opts
+  const id = nextId()
+
+  let settled = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const settle = (undone: boolean): void => {
+    if (settled) return
+    settled = true
+    if (timer !== undefined) clearTimeout(timer)
+    notifications.hide(id)
+    if (undone) onUndo()
+    else onExpire?.()
+  }
+
+  timer = setTimeout(() => settle(false), undoWindow)
+
+  notify({
+    intent: 'info',
+    id,
+    autoClose: undoWindow,
+    historyMessage: String(message),
+    message: (
+      <Group justify="space-between" wrap="nowrap" gap="sm">
+        <Text span size="sm">
+          {message}
+        </Text>
+        <Button variant="subtle" size="compact-xs" onClick={() => settle(true)}>
+          Undo
+        </Button>
+      </Group>
+    ),
+  })
+
+  return { id, dismiss: () => settle(false) }
+}
+
+/**
+ * `notifyUndo` for the common optimistic shape: the UI already changed, `undo` puts it back, and
+ * `mutate` is what actually commits when the window closes.
+ *
+ * @example
+ * notifyUndoable(() => api.delete(id), () => setRows(before), { message: 'Item deleted' })
+ */
+export function notifyUndoable(
+  mutate: () => void,
+  undo: () => void,
+  opts: Omit<NotifyUndoOptions, 'onUndo' | 'onExpire'>,
+): NotifyUndoHandle {
+  return notifyUndo({ ...opts, onUndo: undo, onExpire: mutate })
+}
+
 // ── notifyPromise ─────────────────────────────────────────────────────────────
 
 export type NotifyPromiseMessages = {

package/src/notifications/store.ts

@@ -21,6 +21,13 @@ import { useSyncExternalStore } from 'react'
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
+/**
+ * Mantine's own notification vocabulary — kept as its own type rather than aliased to
+ * `common/props.ts`'s `Tone` (`'good' | 'warn' | 'bad'`) because `@mantine/notifications` and
+ * `INTENT_COLOR`/`INTENT_ROLE` key off exactly these four strings. Roughly:
+ * `success` ~ `Tone.good`, `error`/`warning` ~ `Tone.bad`/`Tone.warn`, `info` has no `Tone`
+ * equivalent (`ToneWithNeutral`'s `'neutral'` is the nearest fit).
+ */
 export type NotificationIntent = 'success' | 'error' | 'warning' | 'info'
 
 /**

package/src/{connectivity → provider}/connectivity-indicator.tsx

@@ -16,9 +16,12 @@
 import { ActionIcon, Badge, Divider, Group, Popover, Stack, Text } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
 import { useRef } from 'react'
+import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { useConnectivity } from './use-connectivity'
-import type { ConnectivityStatus } from './types'
+import type { ConnectivityStatus } from './connectivity-types'
+
+export type ConnectivityIndicatorProps = BasaltProps
 
 const HOVER_OPEN_DELAY = 150
 const HOVER_CLOSE_DELAY = 200
@@ -180,7 +183,7 @@ const ICON_COLOR: Record<ConnectivityStatus, string> = {
  *   {...rest}
  * />
  */
-export function ConnectivityIndicator() {
+export function ConnectivityIndicator({ className, style }: ConnectivityIndicatorProps = {}) {
   const [opened, { open, toggle, close }] = useDisclosure(false)
   const { status, details } = useConnectivity()
   const statusCfg = STATUS_CONFIG[status]
@@ -215,6 +218,8 @@ export function ConnectivityIndicator() {
           aria-label={statusCfg.label}
           aria-expanded={opened}
           aria-haspopup="dialog"
+          {...(className !== undefined && { className })}
+          {...(style !== undefined && { style })}
         >
           <WifiIcon />
         </ActionIcon>

package/src/{connectivity → provider}/connectivity-provider.tsx

@@ -8,7 +8,7 @@
 import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import { onlineManager } from '@tanstack/react-query'
-import type { ConnectivitySnapshot, ConnectivityProviderProps } from './types'
+import type { ConnectivitySnapshot, ConnectivityProviderProps } from './connectivity-types'
 
 // ── SSR-safe default ────────────────────────────────────────────────────────────────────────────────
 
@@ -16,7 +16,10 @@ const SSR_SNAPSHOT: ConnectivitySnapshot = {
   status: 'online',
   details: {
     browserOnline: true,
-    queryOnline: null,
+    // Optimistic `true`, matching `browserOnline` — `onlineManager` is a module singleton so it is
+    // always readable, this is the same pre-hydration default as every other signal, never the
+    // "not mounted" case (see `ConnectivitySnapshot['details']['queryOnline']`'s JSDoc).
+    queryOnline: true,
     sseOpen: null,
     healthPassing: null,
   },

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

@@ -13,7 +13,10 @@ export type ConnectivitySnapshot = {
   /** Per-signal breakdown for debugging / detailed indicators */
   details: {
     browserOnline: boolean // navigator.onLine
-    queryOnline: boolean | null // React Query onlineManager — null when QueryClient not mounted
+    // React Query onlineManager — a module-level singleton, so it is always readable regardless of
+    // whether a QueryClient is mounted; never null on the client (the pre-hydration SSR snapshot
+    // reports an optimistic `true`, matching `browserOnline`, rather than an "unknown" null).
+    queryOnline: boolean
     sseOpen: boolean | null // EventSource readyState === OPEN — null when no sseUrl configured
     healthPassing: boolean | null // /health ping succeeded — null when no healthUrl configured
   }
@@ -21,7 +24,7 @@ export type ConnectivitySnapshot = {
 
 export type ConnectivityOverride = {
   browserOnline?: boolean
-  queryOnline?: boolean | null
+  queryOnline?: boolean
   sseOpen?: boolean | null
   healthPassing?: boolean | null
 }

package/src/provider/error-fallback.module.css

@@ -0,0 +1,21 @@
+/* The boundary renders ABOVE MantineProvider, so its fallback is plain HTML styled here — no
+   Mantine primitive, no inline style object (hidden-inline-style). Tokens only. */
+.root {
+  max-width: 32rem;
+  margin: 0 auto;
+  padding: var(--vx-space-stack-xl);
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md);
+}
+
+.reload {
+  align-self: flex-start;
+  font: inherit;
+  cursor: pointer;
+  padding: var(--vx-space-stack-xs) var(--vx-space-stack-md);
+  border: 1px solid var(--vx-divider);
+  border-radius: var(--vx-radius-ctrl);
+  background: transparent;
+  color: inherit;
+}

package/src/provider/error-fallback.module.css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly reload: string
+}
+export default classes