basalt-ui 1.27.0 → 1.29.0

package/src/commands/overlays-mount.tsx

@@ -2,9 +2,16 @@
  * overlays-mount — composable overlay mount for basalt-ui apps.
  *
  * `BasaltOverlays` bundles ModalsProvider, Spotlight, and Notifications into a single mount point.
- * Put it inside BasaltProvider, before the router. It replaces the standalone `<BasaltNotifications />`
- * from `basalt-ui/notifications` — do NOT mount both `<BasaltOverlays notifications />` and
- * `<BasaltNotifications />` in the same tree (double-mount of `<Notifications />`).
+ * Put it inside BasaltProvider, before the router. It is the ONLY notifications mount — the
+ * standalone `basalt-ui/notifications` overlay it superseded is gone (C1 consolidation); mounting
+ * a second, hand-rolled `<Notifications />` alongside `<BasaltOverlays notifications />` still
+ * double-mounts the overlay and is still wrong for the same reason.
+ *
+ * Every layer — ModalsProvider included — mounts as a SIBLING of `children`, never as a wrapper:
+ * see the comment in the component body (R1). `@mantine/modals`' imperative API (`modals.open*`,
+ * and so basalt's own `overlays.open`) is a window CustomEvent bus that ModalsProvider subscribes
+ * to, so nothing needs to be inside it; the one thing a sibling cannot serve is Mantine's
+ * `useModals()` context hook.
  *
  * Each overlay system is opt-in via props (all default to true). Use flags to disable layers the
  * app does not need — e.g. a charts-only app that has no commands can set `spotlight={false}`.
@@ -26,8 +33,8 @@
  * code. The re-exported `openSpotlight` / `closeSpotlight` helpers delegate to this store.
  *
  * @example
- * // main.tsx — replace <BasaltNotifications /> with <BasaltOverlays>. Use the layered bundle —
- * // the unlayered one outranks basalt's `@layer basalt` styles regardless of specificity:
+ * // main.tsx — mount <BasaltOverlays>. Use the layered bundle — the unlayered one outranks
+ * // basalt's `@layer basalt` styles regardless of specificity:
  * import { BasaltOverlays } from 'basalt-ui/commands'
  * import '@mantine/spotlight/styles.layer.css'
  *
@@ -55,8 +62,10 @@ import type { NotificationsProps } from '@mantine/notifications'
 import type { SpotlightActionData } from '@mantine/spotlight'
 import { runCommand } from './define-commands'
 import type { CommandId } from './define-commands'
+import { useModalsLayer } from './define-overlays'
 import { toSpotlightActions } from './projectors'
 import { useCommandHotkeys } from './useCommandHotkeys'
+import { useNotificationsMountGuard } from '../notifications/mount-guard'
 
 // ── Lazy @mantine/spotlight resolution (module-wide singleton) ────────────────
 
@@ -149,8 +158,9 @@ export type BasaltOverlaysProps = {
   children: ReactNode
 }
 
-// ── Lazy ModalsProvider (falls back to a passthrough fragment) ────────────────
+// ── Lazy ModalsProvider (falls back to rendering nothing) ─────────────────────
 
+/** Missing-peer fallback. Mounted childless (see BasaltOverlays), so it renders nothing. */
 function PassthroughFragment({ children }: ModalsProviderProps) {
   return <>{children}</>
 }
@@ -160,6 +170,7 @@ const LazyModalsProvider = lazy(() =>
     .then((m) => ({ default: m.ModalsProvider }))
     .catch(() => ({ default: PassthroughFragment })),
 )
+Object.assign(LazyModalsProvider, { displayName: 'LazyModalsProvider' })
 
 // ── Lazy SpotlightMount (falls back to rendering nothing) ─────────────────────
 
@@ -215,6 +226,7 @@ const LazySpotlightMount = lazy<
     })
     .catch(() => ({ default: NullFallback })),
 )
+Object.assign(LazySpotlightMount, { displayName: 'LazySpotlightMount' })
 
 // ── Lazy Notifications (falls back to rendering nothing) ──────────────────────
 
@@ -227,6 +239,29 @@ const LazyNotifications = lazy<ComponentType<NotificationsProps>>(() =>
     .then((m) => ({ default: m.Notifications as ComponentType<NotificationsProps> }))
     .catch(() => ({ default: NotificationsFallback })),
 )
+Object.assign(LazyNotifications, { displayName: 'LazyNotifications' })
+
+// ── NotificationsLayer (runs the shared duplicate-mount guard, F15) ───────────
+
+/** Wraps `LazyNotifications` so `useNotificationsMountGuard` only fires while this layer is
+ * actually enabled — the shared counter guards against any second `<Notifications />` mount. */
+function NotificationsLayer({
+  notificationsProps,
+}: {
+  notificationsProps: Omit<NotificationsProps, 'children'> | undefined
+}) {
+  useNotificationsMountGuard()
+  return (
+    <Suspense fallback={null}>
+      <LazyNotifications
+        position="bottom-right"
+        autoClose={4000}
+        limit={5}
+        {...notificationsProps}
+      />
+    </Suspense>
+  )
+}
 
 // ── HotkeysMount (inner component — ensures hook is inside component tree) ────
 
@@ -239,13 +274,11 @@ function HotkeysMount() {
 // ── BasaltOverlays ────────────────────────────────────────────────────────────
 
 /**
- * Composable overlay mount — wraps children in ModalsProvider and renders Spotlight +
- * Notifications siblings. All three layers are enabled by default; pass `false` to disable.
- * A disabled layer's optional peer is never imported.
+ * Composable overlay mount — renders ModalsProvider, Spotlight and Notifications as siblings of
+ * `children`. All three layers are enabled by default; pass `false` to disable. A disabled layer's
+ * optional peer is never imported.
  *
- * Mount exactly ONE BasaltOverlays per app. Do NOT combine with a standalone
- * `<BasaltNotifications />` from `basalt-ui/notifications` — that would double-mount
- * `<Notifications />`.
+ * Mount exactly ONE BasaltOverlays per app — a second instance double-mounts `<Notifications />`.
  *
  * @example
  * <BasaltProvider>
@@ -264,7 +297,20 @@ export function BasaltOverlays({
   projectCommands = true,
   children,
 }: BasaltOverlaysProps) {
-  const content = (
+  // Register the modals layer this mount serves, so `overlays.confirm` can reject with a named
+  // error instead of returning a promise nothing will ever settle (nothing subscribes to the modals
+  // event bus when no provider is up). With `modals={false}` nothing is registered here — a
+  // consumer mounting `<ModalsProvider>` themselves calls `registerModalsProvider()` instead.
+  useModalsLayer(enableModals)
+
+  // `children` sits OUTSIDE every Suspense boundary, and that is load-bearing (R1): React.lazy
+  // suspends on its first render even when the module is already warm, so a boundary wrapping the
+  // app defers the app's FIRST COMMIT past a microtask tick. TanStack Router's async loadMatches
+  // then resolves into that window and setStates onto the not-yet-mounted Transitioner fiber —
+  // "Can't perform a React state update on a component that hasn't mounted yet". The old shape
+  // also rendered `children` twice (once as the fallback, once resolved), running every effect in
+  // the app in both trees. Never put `children` under a lazy boundary here.
+  return (
     <>
       {enableSpotlight && (
         <Suspense fallback={null}>
@@ -274,28 +320,14 @@ export function BasaltOverlays({
           />
         </Suspense>
       )}
-      {enableNotifications && (
+      {enableNotifications && <NotificationsLayer notificationsProps={notificationsProps} />}
+      {enableHotkeys && <HotkeysMount />}
+      {enableModals && (
         <Suspense fallback={null}>
-          <LazyNotifications
-            position="bottom-right"
-            autoClose={4000}
-            limit={5}
-            {...notificationsProps}
-          />
+          <LazyModalsProvider />
         </Suspense>
       )}
-      {enableHotkeys && <HotkeysMount />}
       {children}
     </>
   )
-
-  if (enableModals) {
-    return (
-      <Suspense fallback={<>{content}</>}>
-        <LazyModalsProvider>{content}</LazyModalsProvider>
-      </Suspense>
-    )
-  }
-
-  return <>{content}</>
 }

package/src/commands/shell-bridge.ts

@@ -0,0 +1,86 @@
+/**
+ * `setColorScheme`/`toggleSidebar` — imperative shell handles, wired automatically.
+ *
+ * Command bodies run OUTSIDE the React tree (a Spotlight action, a hotkey), so a `run: () =>
+ * ...`  has no hook access to `useMantineColorScheme()` or `BasaltShell`'s collapse state. Every
+ * consumer of `defineCommands` therefore hand-rolled the SAME "register a live setter ref, read
+ * it later" bridge per action — argo's own `lib/color-scheme-bridge.ts` / `lib/sidebar-bridge.ts`
+ * are the seed for this file, right down to the reason each is its OWN leaf module: `commands.tsx`
+ * imports the router, which imports the generated route tree, which imports every route file
+ * including the one that owns the shell — so a command file importing anything back out of the
+ * shell closes a real circular module dependency (surfaces as TS's "implicitly has type any…
+ * referenced in its own initializer"). A leaf with ZERO local imports is what both sides can
+ * depend on without re-closing that cycle (`register.ts`'s `Slot` doc has the type-level half of
+ * the same story for `commands`↔`overlays`).
+ *
+ * basalt registers BOTH setters itself — `BasaltProvider` calls {@link registerColorSchemeSetter}
+ * from inside `MantineProvider` (`provider/index.tsx`'s `BasaltBridge`), `BasaltShell` calls
+ * {@link registerSidebarToggle} (`shell/index.tsx`'s `ShellFrame`) — so a consumer's own
+ * `commands.tsx` needs no `__root.tsx` wiring at all, unlike argo's hand-rolled version: mount
+ * `BasaltProvider`/`BasaltShell` once, and `setColorScheme`/`toggleSidebar` just work.
+ *
+ * Last-registered wins, same "last call wins" rule `defineCommands`/`defineOverlays`'s own runtime
+ * stash documents — two overlapping mounts (a route swap) are normal, not a race to guard against.
+ *
+ * @example
+ * // commands.ts
+ * import { defineCommands, setColorScheme, toggleSidebar } from 'basalt-ui/commands'
+ * export const COMMANDS = defineCommands({
+ *   'theme:dark': { label: 'Dark theme', run: () => setColorScheme('dark') },
+ *   'ui:toggle-sidebar': { label: 'Toggle sidebar', shortcut: 'Mod+B', run: () => toggleSidebar() },
+ * })
+ */
+
+export type ColorScheme = 'light' | 'dark' | 'auto'
+export type ColorSchemeSetter = (scheme: ColorScheme) => void
+export type SidebarToggle = () => void
+
+let colorSchemeSetterRef: ColorSchemeSetter | null = null
+let sidebarToggleRef: SidebarToggle | null = null
+
+/** @internal called by `BasaltProvider`. Not part of the public API surface. */
+export function registerColorSchemeSetter(setter: ColorSchemeSetter | null): void {
+  colorSchemeSetterRef = setter
+}
+
+/** @internal called by `BasaltShell`. Not part of the public API surface. */
+export function registerSidebarToggle(toggle: SidebarToggle | null): void {
+  sidebarToggleRef = toggle
+}
+
+/**
+ * Set the color scheme from outside the React tree. A no-op (with a dev-only console warning)
+ * when no `BasaltProvider` is mounted yet — the same "not wired" shape `runCommand`/
+ * `overlays.open` already use for an unregistered id.
+ *
+ * @example
+ * setColorScheme('dark')
+ */
+export function setColorScheme(scheme: ColorScheme): void {
+  if (colorSchemeSetterRef === null) {
+    if (process.env['NODE_ENV'] !== 'production') {
+      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      console.warn('[basalt] setColorScheme: no BasaltProvider is mounted yet')
+    }
+    return
+  }
+  colorSchemeSetterRef(scheme)
+}
+
+/**
+ * Toggle `BasaltShell`'s desktop sidebar collapse from outside the React tree. A no-op (with a
+ * dev-only console warning) when no `BasaltShell` is mounted yet.
+ *
+ * @example
+ * toggleSidebar()
+ */
+export function toggleSidebar(): void {
+  if (sidebarToggleRef === null) {
+    if (process.env['NODE_ENV'] !== 'production') {
+      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      console.warn('[basalt] toggleSidebar: no BasaltShell is mounted yet')
+    }
+    return
+  }
+  sidebarToggleRef()
+}

package/src/common/errors.ts

@@ -0,0 +1,143 @@
+/**
+ * The message table (Blueprint audit §3). Every basalt diagnostic — thrown or logged — is built
+ * here, so the prefix, the `Component: …` shape and the em-dash-then-remedy rhythm are one decision
+ * instead of 60. It is the generalisation of `assertQueryStateLike`, which was the ONLY component
+ * in the library naming itself in its own failure (isomorphic finding F-ERR-1: the other 54 fail as
+ * raw `TypeError`s that `BasaltErrorBoundary` swallows into a blank subtree).
+ *
+ * Every builder returns a string; nothing here throws or logs. The caller decides which it is —
+ * `assertRequiredProps` throws, `useValidateProps` logs, the mount guards log.
+ */
+
+/** The one namespace every basalt message opens with. */
+export const BASALT_PREFIX = '[basalt]'
+
+function message(component: string, body: string): string {
+  return `${BASALT_PREFIX} ${component}: ${body}`
+}
+
+/**
+ * A prop the component reads into and cannot render without. This is the F-ERR-1 message: the
+ * component names itself and the prop, instead of the read landing as
+ * `undefined is not an object (evaluating 'field.use')`.
+ */
+export function requiredProp(component: string, prop: string, hint?: string): string {
+  return message(component, `prop "${prop}" is required${hint === undefined ? '.' : ` — ${hint}`}`)
+}
+
+/** A prop with a closed value set that got something outside it. */
+export function oneOf(
+  component: string,
+  prop: string,
+  allowed: readonly string[],
+  got: unknown,
+): string {
+  return message(
+    component,
+    `prop "${prop}" must be one of ${allowed.map((value) => `'${value}'`).join(' | ')} — ` +
+      `got ${JSON.stringify(got)}.`,
+  )
+}
+
+/**
+ * A prop still shipped and still working, with a named successor and the version it goes away in.
+ * Majors are banned here, so the deprecation notice IS the migration channel.
+ */
+export function deprecatedProp(
+  component: string,
+  oldProp: string,
+  newProp: string,
+  removeIn: string,
+): string {
+  return message(
+    component,
+    `prop "${oldProp}" is deprecated — use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`,
+  )
+}
+
+/**
+ * An imperative call needs a layer that is not there — the optional peer is not installed, or the
+ * mount that subscribes to its event bus is disabled. Both halves are named because the remedy
+ * differs: install it, or stop turning it off.
+ */
+export function missingLayer(component: string, layer: string, remedy: string): string {
+  return message(component, `needs ${layer}, which is not available — ${remedy}.`)
+}
+
+/** A single-mount component found a second instance alive (`BasaltProvider`, `Notifications`). */
+export function duplicateMount(component: string): string {
+  return message(
+    component,
+    'more than one instance is mounted at once — mount exactly one, at the app root.',
+  )
+}
+
+// ── Transport-agnostic error decoding ────────────────────────────────────────────────────────────
+//
+// Deliberately in this module, with NO `@tanstack/react-query` import — `dashboard/query-state.tsx`
+// renders server messages and must not drag the query peer into the root barrel's graph to do it.
+
+/**
+ * The HTTP status behind a thrown envelope (Eden Treaty's `{ status, value }`, a `Response`-shaped
+ * throw), when there is one. Use it to BRANCH — 404 → "not found" copy — rather than to build a
+ * message; `toErrorMessage` already folds the status into its text when the body says nothing.
+ *
+ * @example
+ * if (errorStatus(err) === 404) return <EmptyState title="Gone" />
+ */
+export function errorStatus(err: unknown): number | undefined {
+  if (err === null || typeof err !== 'object') return undefined
+  const status = (err as { status?: unknown }).status
+  return typeof status === 'number' ? status : undefined
+}
+
+/** Strings that technically decoded but tell a reader nothing. `JSON.stringify` produces most. */
+const UNUSABLE_MESSAGES = new Set(['', '{}', '[]', 'null', 'undefined', '[object Object]'])
+
+function decodeError(err: unknown): string {
+  if (err instanceof Error) return err.message
+  if (typeof err === 'string') return err
+  if (typeof err === 'object' && err !== null) {
+    const obj = err as Record<string, unknown>
+    if (typeof obj['message'] === 'string') return obj['message']
+    // Eden-style { value: ... } or { status, value } envelopes — unwrap one level.
+    if ('value' in obj) return decodeError(obj['value'])
+  }
+  try {
+    return JSON.stringify(err) ?? ''
+  } catch {
+    return String(err)
+  }
+}
+
+/**
+ * Extract a human-readable message from an unknown thrown value (e.g. the raw Eden envelope
+ * thrown by `unwrap`). Removes the 8-line three-branch boilerplate consumers duplicate.
+ *
+ * Resolution order:
+ *   1. `Error` instance       → err.message
+ *   2. `{ message: string }`  → message (Eden / Elysia error shape)
+ *   3. `{ value: ... }`       → recursively (Eden nested value envelope)
+ *   4. plain string           → itself
+ *   5. anything else          → `JSON.stringify`
+ *
+ * **If that yields nothing a human can read** (`''`, `'{}'`, `'[]'`, `'null'`, `'undefined'`,
+ * `'[object Object]'` — the shapes `JSON.stringify` produces for an opaque envelope) the `fallback`
+ * is returned instead, with `(HTTP <status>)` appended when the envelope carries one. Without that
+ * guard the caller renders a literal `{}` at the user, or — for `toErrorMessage(undefined)` —
+ * the actual value `undefined`, since `JSON.stringify(undefined)` is not a string at all.
+ *
+ * @example
+ * try {
+ *   await unwrap(api.resource.post({ body }))
+ * } catch (e) {
+ *   toast(toErrorMessage(e, 'Could not create share'))   // → "slug already in use"
+ *                                                        // → "Could not create share (HTTP 502)"
+ * }
+ */
+export function toErrorMessage(err: unknown, fallback = 'The request failed.'): string {
+  const decoded = decodeError(err).trim()
+  if (!UNUSABLE_MESSAGES.has(decoded)) return decoded
+  const status = errorStatus(err)
+  return status === undefined ? fallback : `${fallback} (HTTP ${status})`
+}

package/src/common/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `common` — the prop, ref, message and validation primitives every basalt component shares.
+ *
+ * Not a published subpath: the pieces are re-exported from the root barrel (`.`) so a consumer has
+ * one import, and `src/surfaces.ts` stays the SSOT for real subpaths. The module is Mantine-free by
+ * rule (`.oxlintrc.json`) and by test (`boundary.test.ts`), so the Mantine-free half of the library
+ * may reach it too.
+ */
+export { type BasaltProps, type SlotClassNames, type SlotStylesProps } from './props'
+export { type Tone, type ToneWithNeutral, type Tier, cx } from './props'
+export { assignRef, mergeRefs } from './refs'
+export {
+  BASALT_PREFIX,
+  requiredProp,
+  oneOf,
+  deprecatedProp,
+  duplicateMount,
+  missingLayer,
+} from './errors'
+export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
+export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'
+export { isDev } from './is-dev'
+export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion'

package/src/common/is-dev.ts

@@ -0,0 +1,4 @@
+/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
+export function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}

package/src/common/props.ts

@@ -0,0 +1,71 @@
+/**
+ * The prop vocabulary every basalt component shares (Blueprint audit §1, isomorphic finding C8).
+ *
+ * The finding this file answers: 98 of 123 exported components drop `className`, so a consumer who
+ * needs one margin has to fork the component. Fixing that per component is 79 edits; fixing it once
+ * here is one — every component's props type extends `BasaltProps`, and the root element takes
+ * `cx(classes.root, className)` plus `style`.
+ *
+ * **`className` + per-slot `classNames`, and nothing else.** No `styles` object, no `vars`: basalt
+ * does not spread `...rest` onto the DOM (which is why the harness saw zero unknown-attribute
+ * warnings), and a `styles`/`vars` surface would re-open the styling seam Mantine already owns for
+ * the primitives underneath. A composite that needs more than its root styled declares its SLOT
+ * NAMES in its own props type — `SlotStylesProps<'root' | 'header' | 'body'>` — so the slot set is
+ * a documented, compiler-checked union rather than an open record.
+ *
+ * This module is **Mantine-free and React-type-only** so `./charts` and `./tokens` may reach it
+ * without breaching the layer boundary (`common/boundary.test.ts` pins that, and `.oxlintrc.json`
+ * bans `@mantine/*` here the same way it does for `state`/`query`/`guard`).
+ */
+import type { CSSProperties } from 'react'
+
+/**
+ * The base every basalt component accepts. `| undefined` is explicit on both members because
+ * `exactOptionalPropertyTypes` is on: a component destructuring `className` and forwarding it to a
+ * child would otherwise fail to type-check at every call site.
+ */
+export interface BasaltProps {
+  /** Appended to the root element's own class — never replaces it. */
+  readonly className?: string | undefined
+  /** Merged onto the root element's own inline style, if it has one. */
+  readonly style?: CSSProperties | undefined
+}
+
+/** One class per named slot. The slot union is the component's documented contract. */
+export type SlotClassNames<S extends string> = Partial<Record<S, string>>
+
+/**
+ * The composite half of the contract: a container that paints more than one box publishes its slot
+ * names here. The set is small on purpose — `Section`, `StatCard`, `ChartCard`, `PageBar`,
+ * `PageAside`, `WidgetHeader`, `EmptyState`, `QueryState`, `BasaltDataTable`. A leaf takes
+ * `BasaltProps` alone.
+ */
+export interface SlotStylesProps<S extends string> {
+  readonly classNames?: SlotClassNames<S> | undefined
+}
+
+/**
+ * The ONE status vocabulary (audit A13). Five forks exist today — `StatCardTone` and
+ * `SidebarBlockTone` are byte-identical to this, `CalloutKind` / `AccountBadgeTone` /
+ * `NotificationIntent` each differ — and they stay put for now: an adopter aliases its fork to this
+ * type, it does not get renamed out from under a consumer.
+ */
+export type Tone = 'good' | 'warn' | 'bad'
+
+/** `Tone` plus the un-toned state — a badge or a block with nothing to say yet. */
+export type ToneWithNeutral = Tone | 'neutral'
+
+/**
+ * The heading tier (`docs/CONTROLS-SPEC.md` §2.2). Re-exported from its owner rather than declared
+ * twice — `WidgetHeaderTier` stays the name on the public barrel; `Tier` is what `common`-aware
+ * code spells. Type-only, so this file emits no runtime edge into the Mantine-coupled half.
+ */
+export type { WidgetHeaderTier as Tier } from '../dashboard/widget-header'
+
+/**
+ * The class joiner. Replaces the `[a, b].filter(Boolean).join(' ')` spelled out in seven files
+ * today; falsy parts drop, so `cx(classes.root, open && classes.open, className)` is the idiom.
+ */
+export function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter((part): part is string => typeof part === 'string' && part !== '').join(' ')
+}

package/src/common/query-state-like.ts

@@ -0,0 +1,64 @@
+/**
+ * The query envelope every basalt container reads, and the ONE runtime assertion that stands in for
+ * the compiler over it.
+ *
+ * It lives in `common/` because two independent readers grew their own copy and the copies
+ * DISAGREED: `QueryState` (`dashboard/query-state.tsx`) checked the `data` key and that `refetch` is
+ * a function; `dataQueryBranch` (`data/query-branch.ts`) checked neither, so the table accepted a
+ * result whose Retry button did nothing. A validator that exists twice is a validator with two
+ * strictnesses, which is exactly the class of defect the assertion exists to catch.
+ *
+ * Mantine-free by construction (`common/boundary.test.ts`): types, a set and a throw.
+ */
+
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read.
+ *
+ * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
+ * hand-rolled result must be passable without a cast, and the components stay independent of which
+ * `@tanstack/react-query` major a consumer pins. This is NOT a claim that the root barrel is free of
+ * that package — `./connectivity` imports `onlineManager` as a value and is re-exported from
+ * `src/index.ts`. The cost of the subset is that the compiler stops policing the shape — which is
+ * why {@link assertQueryStateLike} checks it at runtime.
+ */
+export type QueryStateLike<TData> = {
+  data: TData | undefined
+  isError: boolean
+  error: unknown
+  fetchStatus: 'fetching' | 'paused' | 'idle'
+  refetch: () => unknown
+}
+
+/** The three `fetchStatus` values a `UseQueryResult` can carry. */
+export const FETCH_STATUSES: ReadonlySet<string> = new Set(['fetching', 'paused', 'idle'])
+
+/**
+ * `QueryStateLike` is a structural subset, so TypeScript cannot protect a hand-composed result the
+ * way it protects a real `UseQueryResult` — and every field it drops fails SILENTLY in the exact
+ * direction these components exist to prevent. A missing `isError` renders "no data" over a 500. A
+ * misspelled `fetchStatus` never leaves the spinner. A missing `refetch` renders a Retry button that
+ * does nothing. Each of those is a false claim about the data, so it throws.
+ *
+ * `component` opens the message so the throw names the container that got the bad envelope —
+ * `QueryState`, `BasaltDataTable`, `BasaltVirtualList` all read the same shape.
+ */
+export function assertQueryStateLike(
+  component: string,
+  query: unknown,
+): asserts query is QueryStateLike<unknown> {
+  const bad = (detail: string): never => {
+    throw new Error(
+      `${component}: \`query\` ${detail}. It must carry { data, isError, error, fetchStatus, refetch } — ` +
+        'a TanStack UseQueryResult does; a hand-composed one must spell every field, because a ' +
+        'missing branch flag renders a false claim about the data instead of an error.',
+    )
+  }
+  if (query === null || typeof query !== 'object')
+    bad(`is ${query === null ? 'null' : typeof query}`)
+  const q = query as Record<string, unknown>
+  if (!('data' in q)) bad('has no `data` key')
+  if (typeof q['isError'] !== 'boolean') bad('has no boolean `isError`')
+  if (typeof q['fetchStatus'] !== 'string' || !FETCH_STATUSES.has(q['fetchStatus']))
+    bad(`has fetchStatus=${JSON.stringify(q['fetchStatus'])}, not 'fetching' | 'paused' | 'idle'`)
+  if (typeof q['refetch'] !== 'function') bad('has no `refetch()`')
+}

package/src/common/refs.ts

@@ -0,0 +1,58 @@
+/**
+ * Ref plumbing for composites (Blueprint audit §2). React 19 made `ref` an ordinary prop, which
+ * removed `forwardRef` — it did NOT remove the need to merge: a component that both forwards its
+ * caller's ref and keeps its own (a measurement, a focus target) still has two refs and one node.
+ *
+ * The React 19 wrinkle these two functions exist to get right: a callback ref MAY return a cleanup
+ * function, and when it does React never calls it again with `null`. So merging cannot just fan out
+ * — it has to fan out the cleanups too, and null out the refs that returned none.
+ */
+import type { Ref, RefCallback } from 'react'
+
+/**
+ * Writes `value` into one ref of either shape.
+ *
+ * @returns the callback ref's own cleanup when it returned one, else `undefined`.
+ */
+export function assignRef<T>(ref: Ref<T> | undefined, value: T | null): (() => void) | undefined {
+  if (ref === undefined || ref === null) return undefined
+  if (typeof ref === 'function') {
+    const cleanup = ref(value)
+    return typeof cleanup === 'function' ? cleanup : undefined
+  }
+  // `@types/react` 19 types `RefObject.current` as MUTABLE — the readonly `current` that forced a
+  // cast here was the React 18 `RefObject`, and `Ref<T>` now narrows to `RefObject<T | null>`.
+  ref.current = value
+  return undefined
+}
+
+/**
+ * Fans one node out to several refs.
+ *
+ * Returns a NEW function on every call, so a component that passes it straight to JSX re-attaches
+ * on every render — wrap it in `useCallback`/`useMemo` over the refs it merges when the node is
+ * expensive to re-attach.
+ *
+ * @example
+ * const merged = useMemo(() => mergeRefs(ref, localRef), [ref])
+ * return <div ref={merged} />
+ */
+export function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
+  return (value: T | null) => {
+    const cleanups = refs.map((ref) => assignRef(ref, value))
+    // No child returned a cleanup → stay on React's legacy path and let it call us with `null`.
+    if (cleanups.every((cleanup) => cleanup === undefined)) return undefined
+    // At least one did → React will call THIS instead of re-invoking with `null`, so the refs that
+    // returned no cleanup have to be cleared here or they keep pointing at a detached node.
+    return () => {
+      refs.forEach((ref, index) => {
+        const cleanup = cleanups[index]
+        if (cleanup !== undefined) {
+          cleanup()
+          return
+        }
+        assignRef(ref, null)
+      })
+    }
+  }
+}

package/src/common/scroll-parent.ts

@@ -0,0 +1,42 @@
+/**
+ * `scrollParentOf` — which box actually scrolls `el`.
+ *
+ * Since `BasaltShell` made `AppShell.Main` the scrollport (`shell/app-main.module.css`), the
+ * document no longer scrolls inside a shell: `window.scrollY` is pinned at 0 and a `scroll`
+ * listener on `window` never fires. Everything in the package that reacted to page scroll had to
+ * stop asking the window and start asking whichever ancestor is really scrolling — and it has to
+ * keep working in a SHELL-LESS app, where the answer genuinely is the window.
+ *
+ * `null` IS the answer for "the document scrolls this", not a failure — callers listen on `window`
+ * and read `window.scrollY` in that case.
+ */
+
+/** The attribute `BasaltShell` puts on `AppShell.Main`. Also the public handle for a consumer. */
+export const SCROLLPORT_ATTRIBUTE = 'data-basalt-scrollport'
+
+function isScrollport(element: HTMLElement): boolean {
+  // The declared handle wins outright: Main is a scrollport by construction even on the frame where
+  // its content is short enough that `scrollHeight === clientHeight`.
+  if (element.hasAttribute(SCROLLPORT_ATTRIBUTE)) return true
+  const overflowY = getComputedStyle(element).overflowY
+  if (overflowY !== 'auto' && overflowY !== 'scroll') return false
+  return element.scrollHeight > element.clientHeight
+}
+
+/**
+ * The nearest scrolling ANCESTOR of `el`, or `null` when the document is the scroller.
+ *
+ * `el` itself is never considered — the question is which box scrolls it, not whether it scrolls
+ * its own children. `<body>` and `<html>` are never returned either: an app that scrolls at the
+ * document level is exactly the `null` case.
+ */
+export function scrollParentOf(el: Element | null): HTMLElement | null {
+  if (el === null || typeof window === 'undefined') return null
+  const root = el.ownerDocument.documentElement
+  let node = el.parentElement
+  while (node !== null && node !== root && node !== el.ownerDocument.body) {
+    if (isScrollport(node)) return node
+    node = node.parentElement
+  }
+  return null
+}