basalt-ui 1.27.0 → 1.29.0

package/src/data/query-branch.ts

@@ -0,0 +1,53 @@
+/**
+ * The uniform query contract `./data`'s two containers resolve (law C3, components audit #3).
+ *
+ * `BasaltDataTable` took `isLoading` + `emptyState` and had NO error branch at all;
+ * `BasaltVirtualList` took `isLoading` alone. Both therefore steered a caller into the same wrong
+ * render `QueryState` exists to delete — *No data to display.* printed over a 500 — and neither
+ * could be handed a `UseQueryResult` at all.
+ *
+ * This is not a second `QueryState`. `QueryState` REPLACES its children with a branch; a table has
+ * to keep its `<thead>`, its toolbar and its header drawn and swap only the `<tbody>`, so what it
+ * needs from the contract is the BRANCH, not the rendering. Hence one function, and the same
+ * precedence `QueryState` documents, read from one place so the two cannot drift.
+ */
+import { assertQueryStateLike } from '../common/query-state-like'
+import type { QueryStateLike } from '../common/query-state-like'
+
+/**
+ * Which body a data container paints.
+ *
+ * `'ready'` covers three of `QueryState`'s four cases — data, an EMPTY resolved result, and an
+ * error that arrived over cached data. The container itself decides between rows and its own empty
+ * state, because it already knows whether it has any (`table.getRowCount()`, `items.length`) and a
+ * query envelope does not.
+ *
+ * A refetch that fails while rows are already on screen therefore keeps the rows, with no banner —
+ * that is `QueryState`'s "a background refetch failing must not blank a page that already works",
+ * minus the banner it draws. Compose `QueryState` AROUND the container when the banner is wanted.
+ */
+export type DataQueryBranch = 'pending' | 'error' | 'ready'
+
+/**
+ * Resolves a `QueryStateLike` to the branch its container should paint, asserting first — through
+ * the SAME `assertQueryStateLike` `QueryState` runs (`common/query-state-like.ts`), so the table and
+ * the wrapper cannot disagree about what a valid envelope is. This function once carried its own
+ * narrower copy that skipped the `data` key and the `refetch()` check, which let a result whose
+ * Retry button did nothing through the very branch that renders one.
+ *
+ * `isError` WITH data is `'ready'`, not `'error'`: the stale rows stay on screen. That is deliberate
+ * and it differs from `QueryState`, which paints the same case as children PLUS a "showing cached
+ * data" banner — a container swaps only its body, so it has nowhere to draw one. Compose
+ * `QueryState` AROUND the container when the banner is wanted. Pinned in `data-table.test.tsx`.
+ */
+export function dataQueryBranch(
+  component: string,
+  query: QueryStateLike<unknown>,
+): DataQueryBranch {
+  assertQueryStateLike(component, query)
+  if (query.isError && query.data === undefined) return 'error'
+  // `idle` with no data is an `enabled: false` query, not a pending one — it resolves to the
+  // container's own empty state, exactly as `QueryState` resolves it to `empty`.
+  if (query.data === undefined && query.fetchStatus !== 'idle') return 'pending'
+  return 'ready'
+}

package/src/data/table.ts

@@ -23,31 +23,17 @@
 export { BasaltDataTable } from './data-table'
 export type {
   BasaltDataTableProps,
+  BasaltDataTableSlot,
   DataTableAlign,
+  DataTableColumnId,
+  DataTableColumnPinning,
   DataTableFacet,
   DataTableFacetOption,
 } from './data-table'
 
-// ── @tanstack/react-table convenience re-exports ──────────────────────────────
-// These are the handful of table primitives a consumer needs at the call site;
-// importing them from basalt-ui/data/table avoids a separate @tanstack/react-table import.
-// useReactTable + flexRender + the row-model builders (getCoreRowModel/getSortedRowModel/
-// getFilteredRowModel/getPaginationRowModel) are the raw escape hatch: a bespoke, fully custom
-// table can be built from this subpath alone, with no direct @tanstack/react-table import in
-// consumer code.
-export {
-  createColumnHelper,
-  useReactTable,
-  flexRender,
-  getCoreRowModel,
-  getSortedRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  type ColumnDef,
-  type SortingState,
-  type ColumnHelper,
-  type PaginationState,
-  type ColumnPinningState,
-  // The type `onColumnFiltersChange` hands back — needed at the call site for server-side faceting.
-  type ColumnFiltersState,
-} from '@tanstack/react-table'
+// ── @tanstack/react-table convenience re-export ───────────────────────────────
+// `createColumnHelper` is the one raw TanStack symbol every `BasaltDataTable` call site needs to
+// build its `columns` array (C1 consolidation: every OTHER pass-through — `useReactTable`,
+// `flexRender`, the row-model builders, and the type re-exports — was unused by any consumer;
+// import TanStack directly for those).
+export { createColumnHelper } from '@tanstack/react-table'

package/src/data/virtual-list.tsx

@@ -5,7 +5,7 @@
  * set by ./agent-chat's virtualize mode (see ./data/index.ts), so do not lower it.
  *
  * @example
- * import { BasaltVirtualList } from 'basalt-ui/data'
+ * import { BasaltVirtualList } from 'basalt-ui/data/virtual'
  *
  * const items = Array.from({ length: 10_000 }, (_, i) => ({ id: i, label: `Row ${i}` }))
  * <BasaltVirtualList
@@ -17,11 +17,23 @@
  */
 import { Box, Skeleton } from '@mantine/core'
 import { useVirtualizer } from '@tanstack/react-virtual'
-import { useRef } from 'react'
-import type { ReactNode } from 'react'
+import type { ScrollToOptions, Virtualizer } from '@tanstack/react-virtual'
+import { useImperativeHandle, useRef } from 'react'
+import type { ReactNode, Ref } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import { BASALT_PREFIX } from '../common/errors'
+import { assertRequiredProps, useValidateProps } from '../common/validate'
+import { ErrorState } from '../dashboard/query-state'
+import type { QueryStateLike } from '../dashboard/query-state'
+import { dataQueryBranch } from './query-branch'
 
 // ── Props ─────────────────────────────────────────────────────────────────────
 
+/** The two boxes `BasaltVirtualList` paints: `root` is the scroll container, `row` is each
+ * absolutely-positioned virtual item. */
+export type BasaltVirtualListSlot = 'root' | 'row'
+
 /**
  * Props for {@link BasaltVirtualList}.
  *
@@ -35,42 +47,97 @@ import type { ReactNode } from 'react'
  *   getItemKey: (item) => item.id,
  * }
  */
-export type BasaltVirtualListProps<T> = {
-  /** All items in the list (unsliced — virtualization is handled internally). */
-  items: T[]
-  /** Height of the scroll container. Accepts a CSS value ('400px', '60vh') or a number in px. */
-  height: number | string
-  /**
-   * Estimated row height in px (used for virtual layout before measure).
-   * @default 40
-   */
-  estimateSize?: number
-  /**
-   * Number of items rendered beyond the visible viewport (above + below) to reduce flicker.
-   * @default 5
-   */
-  overscan?: number
-  /**
-   * Render function for a single item. Receives the item and its list index.
-   * The returned node is placed inside an absolutely-positioned row container.
-   */
-  renderItem: (item: T, index: number) => ReactNode
-  /**
-   * Stable key for each item. Falls back to the numeric list index when omitted.
-   * Providing a stable key prevents react reconciliation churn on scroll.
-   */
-  getItemKey?: (item: T, index: number) => string | number
-  /**
-   * When true, renders skeleton placeholder rows at the given height instead of the virtual item
-   * list. The scroll container is still rendered at the specified `height`. Use while async data
-   * is loading.
-   */
-  isLoading?: boolean
+export type BasaltVirtualListProps<T> = BasaltProps &
+  SlotStylesProps<BasaltVirtualListSlot> & {
+    /** All items in the list (unsliced — virtualization is handled internally). */
+    items: T[]
+    /** Height of the scroll container. Accepts a CSS value ('400px', '60vh') or a number in px. */
+    height: number | string
+    /**
+     * Estimated row height in px (used for virtual layout before measure).
+     * @default 40
+     */
+    estimateSize?: number
+    /**
+     * Number of items rendered beyond the visible viewport (above + below) to reduce flicker.
+     * @default 5
+     */
+    overscan?: number
+    /**
+     * Render function for a single item. Receives the item and its list index.
+     * The returned node is placed inside an absolutely-positioned row container.
+     */
+    renderItem: (item: T, index: number) => ReactNode
+    /**
+     * Stable key for each item, handed straight to the virtualizer's own `getItemKey` — required,
+     * not merely recommended: the previous index fallback hid stale rows across a mutation (an
+     * insert/delete shifting every index below it keeps rendering the OLD item at each shifted
+     * index until React's own reconciliation happens to catch up), silently, in the one component
+     * whose job is a long mutable list.
+     */
+    getItemKey: (item: T, index: number) => string | number
+    /**
+     * When true, renders skeleton placeholder rows at the given height instead of the virtual item
+     * list. The scroll container is still rendered at the specified `height`. Use while async data
+     * is loading.
+     *
+     * Superseded by `query`, which resolves this branch AND the two this prop cannot express — pass
+     * both and `query` wins, with a dev warning.
+     */
+    isLoading?: boolean
+    /**
+     * The result behind `items`, resolved into a body: pending → the skeleton rows, error with no
+     * data → an `ErrorState` inside the scroll box (the query's own `refetch` behind Retry),
+     * anything else → the rows, or `emptyState` when `items` is empty.
+     *
+     * Law C3's uniform container contract (`docs/CONTROLS-SPEC.md` §1). The list took `isLoading`
+     * and nothing else (components audit #3), so a failed fetch and a genuinely empty list rendered
+     * the same blank box — the exact false claim `QueryState` exists to delete.
+     *
+     * The container keeps its declared `height` through every branch, so the page does not jump as
+     * the state resolves.
+     */
+    query?: QueryStateLike<unknown>
+    /**
+     * Rendered inside the scroll container when `items` is empty and nothing is pending. Omit to
+     * keep today's rendering — an empty box. Works with or without `query`.
+     */
+    emptyState?: ReactNode
+    /**
+     * Number of skeleton rows to render when `isLoading` is true.
+     * @default 5
+     */
+    skeletonRows?: number
+    /** Imperative scroll handle — see {@link BasaltVirtualListHandle}. */
+    ref?: Ref<BasaltVirtualListHandle>
+  }
+
+/**
+ * Imperative escape hatch for {@link BasaltVirtualList} — the virtualizer's own `scrollToIndex` /
+ * `scrollToOffset` / `scrollToEnd` were otherwise unreachable, since the component owns the
+ * `useVirtualizer()` instance internally. `getVirtualizer()` is the full escape hatch for anything
+ * not covered by the three convenience methods (mirrors `./data/table`'s `useReactTable` export as
+ * the table's own escape hatch).
+ *
+ * @example
+ * const listRef = useRef<BasaltVirtualListHandle>(null)
+ * <BasaltVirtualList ref={listRef} items={items} height={400} renderItem={renderRow} getItemKey={(i) => i.id} />
+ * listRef.current?.scrollToIndex(42, { align: 'center' })
+ */
+export type BasaltVirtualListHandle = {
+  /** Scrolls so the item at `index` is in view. */
+  scrollToIndex: (index: number, opts?: ScrollToOptions) => void
+  /** Scrolls the container to a raw pixel `offset`. */
+  scrollToOffset: (offset: number, opts?: ScrollToOptions) => void
+  /** Scrolls to the end of the list. */
+  scrollToEnd: (opts?: Pick<ScrollToOptions, 'behavior'>) => void
   /**
-   * Number of skeleton rows to render when `isLoading` is true.
-   * @default 5
+   * The underlying `@tanstack/react-virtual` instance — the full escape hatch. Returns the RAW
+   * `@tanstack/react-virtual` `Virtualizer`, so a future major of that library reaching this shape
+   * ships here as a plain `feat:` under the no-majors doctrine (`../../CLAUDE.md` "Commit type
+   * discipline"), not a silent break.
    */
-  skeletonRows?: number
+  getVirtualizer: () => Virtualizer<HTMLDivElement, Element>
 }
 
 // ── Component ─────────────────────────────────────────────────────────────────
@@ -96,16 +163,41 @@ export type BasaltVirtualListProps<T> = {
  *   getItemKey={(item) => item.id}
  * />
  */
-export function BasaltVirtualList<T>({
-  items,
-  height,
-  estimateSize = 40,
-  overscan = 5,
-  renderItem,
-  getItemKey,
-  isLoading = false,
-  skeletonRows = 5,
-}: BasaltVirtualListProps<T>) {
+export function BasaltVirtualList<T>(props: BasaltVirtualListProps<T>) {
+  // F-ERR-1: without this, a list missing `items`/`renderItem`/`getItemKey` fails deep inside
+  // `useVirtualizer` as a raw `TypeError` caught by `BasaltErrorBoundary` — a blank subtree with no
+  // message naming any of the three.
+  assertRequiredProps('BasaltVirtualList', props, ['items', 'renderItem', 'getItemKey'])
+  const {
+    items,
+    height,
+    estimateSize = 40,
+    overscan = 5,
+    renderItem,
+    getItemKey,
+    isLoading = false,
+    query,
+    emptyState,
+    skeletonRows = 5,
+    ref,
+    className,
+    style,
+    classNames,
+  } = props
+
+  // `query` resolves the pending branch `isLoading` used to own, plus the error and empty ones the
+  // boolean cannot express — so it wins outright, and says so rather than letting the flag look
+  // broken.
+  useValidateProps(
+    'BasaltVirtualList',
+    () =>
+      query === undefined || props.isLoading === undefined
+        ? null
+        : `${BASALT_PREFIX} BasaltVirtualList: props "query" and "isLoading" are both set — ` +
+          '"query" wins and "isLoading" is ignored. Drop "isLoading".',
+    [query === undefined, props.isLoading === undefined],
+  )
+
   const parentRef = useRef<HTMLDivElement>(null)
 
   const rowVirtualizer = useVirtualizer({
@@ -116,18 +208,55 @@ export function BasaltVirtualList<T>({
     // Silences a React 19 deprecation warning: TanStack Virtual calls flushSync on scroll;
     // setting this to false opts out of that path entirely.
     useFlushSync: false,
-    ...(getItemKey !== undefined && {
-      getItemKey: (index: number) => {
-        const item = items[index]
-        return item !== undefined ? getItemKey(item, index) : index
-      },
-    }),
+    getItemKey: (index: number) => {
+      const item = items[index]
+      return item !== undefined ? getItemKey(item, index) : index
+    },
   })
 
-  if (isLoading) {
+  useImperativeHandle(
+    ref,
+    () => ({
+      scrollToIndex: (index, opts) => rowVirtualizer.scrollToIndex(index, opts),
+      scrollToOffset: (offset, opts) => rowVirtualizer.scrollToOffset(offset, opts),
+      scrollToEnd: (opts) => rowVirtualizer.scrollToEnd(opts),
+      getVirtualizer: () => rowVirtualizer,
+    }),
+    [rowVirtualizer],
+  )
+
+  const branch = query === undefined ? undefined : dataQueryBranch('BasaltVirtualList', query)
+  const showSkeleton = branch === undefined ? isLoading : branch === 'pending'
+  // Every non-virtual branch paints into the SAME box at the SAME declared height, so the page does
+  // not reflow as one state resolves into the next.
+  const boxProps = {
+    className: cx(classNames?.root, className),
+    style: {
+      height,
+      // theme-allow raw-scroll-container — matches the virtualizer's own scroll box below, so a
+      // placeholder branch doesn't reflow.
+      overflow: 'auto' as const,
+      ...style,
+    },
+  }
+
+  if (branch === 'error' && query !== undefined) {
+    return (
+      <Box {...boxProps}>
+        <ErrorState
+          error={query.error}
+          title="Could not load"
+          tier="section"
+          retrying={query.fetchStatus === 'fetching'}
+          onRetry={() => void query.refetch()}
+        />
+      </Box>
+    )
+  }
+
+  if (showSkeleton) {
     return (
-      // theme-allow raw-scroll-container — matches the virtualizer's own scroll box below, so the skeleton doesn't reflow.
-      <Box style={{ height, overflow: 'auto' }}>
+      <Box {...boxProps}>
         {Array.from({ length: skeletonRows }, (_, i) => (
           <Box
             key={`skeleton-${i}`}
@@ -150,13 +279,17 @@ export function BasaltVirtualList<T>({
     )
   }
 
+  if (items.length === 0 && emptyState !== undefined) return <Box {...boxProps}>{emptyState}</Box>
+
   return (
     <Box
       ref={parentRef}
+      className={cx(classNames?.root, className)}
       style={{
         height,
         // theme-allow raw-scroll-container — TanStack Virtual measures this element as the scroll container.
         overflow: 'auto',
+        ...style,
       }}
     >
       {/* Inner sizer — defines total scroll height for the virtualizer */}
@@ -172,6 +305,7 @@ export function BasaltVirtualList<T>({
           return (
             <Box
               key={virtualItem.key}
+              className={cx(classNames?.row)}
               style={{
                 position: 'absolute',
                 top: 0,

package/src/data/virtual.ts

@@ -3,10 +3,10 @@
  * rendered with a Mantine Box scroll container.
  *
  * Optional peer: @tanstack/react-virtual >=3.13.26 <4. This list works on any 3.x — the floor is
- * set by ./agent-chat's virtualize mode (see ./data/index.ts), so do not lower it.
+ * set by ./agent-chat's virtualize mode, so do not lower it.
  *
- * Use this fine subpath instead of the `./data` barrel when your app only needs the virtual list
- * — it does NOT value-import @tanstack/react-table, so the data-table peer is never required.
+ * This subpath does NOT value-import @tanstack/react-table, so the data-table peer is never
+ * required — use `./data/table` when your app only needs the table.
  *
  * Install with:
  *   bun add @tanstack/react-virtual
@@ -19,4 +19,8 @@
 
 // ── BasaltVirtualList ─────────────────────────────────────────────────────────
 export { BasaltVirtualList } from './virtual-list'
-export type { BasaltVirtualListProps } from './virtual-list'
+export type {
+  BasaltVirtualListHandle,
+  BasaltVirtualListProps,
+  BasaltVirtualListSlot,
+} from './virtual-list'

package/src/dev-dock.tsx

@@ -0,0 +1,159 @@
+/**
+ * `BasaltDevDock` — a fixed, dev-only bottom drawer hosting the in-app tooling: TanStack Router
+ * devtools, TanStack Query devtools (the embeddable `ReactQueryDevtoolsPanel` — NOT
+ * `BasaltQueryDevtools`, which wraps the floating-button `ReactQueryDevtools` and would duplicate
+ * this dock's own chrome), and the theme lab (`basalt-ui/theme-lab`'s `ThemeLabControls`). Ported
+ * from argo's `components/dev-dock.tsx` (91 lines) — same three-tool shape, same "only renders the
+ * ACTIVE panel" contract: the launcher (which tool is open) lives wherever the consumer puts it —
+ * a `SettingsMenuItem` per tool with `active` set to the currently-open one (C5's
+ * `SettingsMenuItem.active`) is the seeded pattern — this component owns only the render.
+ *
+ * Every dependency is an OPTIONAL peer, loaded lazily so importing (or even rendering, with
+ * `tool={null}`) this module never requires `@tanstack/react-router-devtools`,
+ * `@tanstack/react-query-devtools` or `@tanstack/react-router` unless a consumer actually opens
+ * that tool — same discipline as `BasaltQueryDevtools` (`query-devtools.tsx`) and
+ * `ThemeLabControls`'s own `React.lazy` wrapper here. In production this returns `null`
+ * immediately, before any dynamic import fires.
+ *
+ * @example
+ * import { BasaltDevDock, type BasaltDevDockTool } from 'basalt-ui'
+ * import { useState } from 'react'
+ * import { useRouter } from '@tanstack/react-router'
+ *
+ * function DevTools() {
+ *   const [tool, setTool] = useState<BasaltDevDockTool | null>(null)
+ *   const router = useRouter()
+ *   return <BasaltDevDock tool={tool} onClose={() => setTool(null)} router={router} />
+ * }
+ * // wire the launchers as settings-menu entries with `active: tool === 'router'` etc.
+ */
+import { lazy, Suspense } from 'react'
+import type { ReactNode } from 'react'
+import { Box, CloseButton, Flex, Group, Text } from '@mantine/core'
+import type { BasaltProps } from './common/props'
+import type { ThemeLabControlsProps } from './theme-lab'
+
+/** Which panel is open. `null` renders nothing (the dock is unmounted, not hidden). */
+export type BasaltDevDockTool = 'router' | 'query' | 'theme'
+
+const TOOL_TITLE: Record<BasaltDevDockTool, string> = {
+  router: 'Router Devtools',
+  query: 'Query Devtools',
+  theme: 'Theme Lab',
+}
+
+// Minimal structural shape of a TanStack `Router` instance — avoids a hard, eager type
+// dependency on `@tanstack/react-router` for a consumer who never renders the `'router'` tool.
+// `TanStackRouterDevtoolsPanel` itself takes the real (much wider) `AnyRouter` type; this
+// structural subset is only what THIS component threads through as a prop.
+type DevDockRouter = { __routerHasBeenSetup?: unknown } | Record<string, unknown>
+
+const LazyRouterDevtoolsPanel = lazy(() =>
+  import('@tanstack/react-router-devtools').then((m) => ({
+    default: m.TanStackRouterDevtoolsPanel,
+  })),
+)
+Object.assign(LazyRouterDevtoolsPanel, { displayName: 'LazyRouterDevtoolsPanel' })
+
+// The embeddable PANEL, not `ReactQueryDevtools` (`BasaltQueryDevtools`'s own wrapped export) —
+// that one renders its own floating trigger button + auto-popup shell, which would duplicate the
+// dock's own chrome. `query-devtools.tsx`'s `BasaltQueryDevtools` stays the answer for a consumer
+// who wants the traditional floating-button devtools instead of a dock tab.
+const LazyQueryDevtoolsPanel = lazy(() =>
+  import('@tanstack/react-query-devtools').then((m) => ({ default: m.ReactQueryDevtoolsPanel })),
+)
+Object.assign(LazyQueryDevtoolsPanel, { displayName: 'LazyQueryDevtoolsPanel' })
+
+const LazyThemeLabControls = lazy(() =>
+  import('./theme-lab').then((m) => ({ default: m.ThemeLabControls })),
+)
+Object.assign(LazyThemeLabControls, { displayName: 'LazyThemeLabControls' })
+
+export type BasaltDevDockProps = BasaltProps & {
+  /** Which panel to show. `null` renders nothing. */
+  tool: BasaltDevDockTool | null
+  /** Called when the dock's own close button fires, or a hosted panel asks to close itself
+   * (the router devtools' own `setIsOpen`, the query devtools' own `onClose`). */
+  onClose: () => void
+  /** The active TanStack `Router` instance — required only to render the `'router'` tool; a
+   * consumer that never opens it may omit this entirely. */
+  router?: DevDockRouter
+  /** Forwarded to the hosted `ThemeLabControls` (icons, the copy callback — see its own props). */
+  themeLab?: ThemeLabControlsProps
+}
+
+/**
+ * Lazy, production-excluded dock. Safe to mount unconditionally with `tool={null}` — the dynamic
+ * imports for whichever peer a tool needs only fire once that tool is actually selected, and
+ * never at all in production.
+ */
+export function BasaltDevDock({
+  tool,
+  onClose,
+  router,
+  themeLab,
+  className,
+  style,
+}: BasaltDevDockProps): ReactNode {
+  if (process.env['NODE_ENV'] === 'production') return null
+  if (tool === null) return null
+
+  return (
+    <Flex
+      direction="column"
+      {...(className !== undefined && { className })}
+      style={{
+        position: 'fixed',
+        left: 0,
+        right: 0,
+        bottom: 0,
+        height: '42vh',
+        zIndex: 400,
+        background: 'var(--mantine-color-body)',
+        borderTop: '1px solid var(--mantine-color-default-border)',
+        // Floating tier: a fixed dock sits above the page like a menu/drawer, so it takes
+        // basalt's overlay depth token rather than Mantine's raw shadow ramp.
+        boxShadow: 'var(--vx-shadow-overlay)',
+        ...style,
+      }}
+    >
+      <Group
+        justify="space-between"
+        px="sm"
+        py={6}
+        style={{ borderBottom: '1px solid var(--mantine-color-default-border)' }}
+      >
+        <Text size="xs" fw={600} tt="uppercase" c="dimmed">
+          {TOOL_TITLE[tool]}
+        </Text>
+        <CloseButton size="sm" onClick={onClose} aria-label="Close devtools" />
+      </Group>
+      {/* theme-allow raw-scroll-container — hosts third-party devtools panels sized to
+          height: 100%; they need a real overflow ancestor, not ScrollArea's custom viewport. */}
+      <Box style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
+        <Suspense fallback={null}>
+          {tool === 'router' && router !== undefined && (
+            <LazyRouterDevtoolsPanel
+              // The devtools panel's own `router` prop takes the real `AnyRouter` type;
+              // `DevDockRouter` is deliberately a narrower structural stand-in so this module
+              // never eagerly imports the router's types.
+              // oxlint-disable-next-line typescript/no-explicit-any -- see above
+              router={router as any}
+              isOpen
+              setIsOpen={onClose}
+              style={{ height: '100%' }}
+            />
+          )}
+          {tool === 'query' && (
+            <LazyQueryDevtoolsPanel onClose={onClose} style={{ height: '100%' }} />
+          )}
+          {tool === 'theme' && (
+            <Box p="md">
+              <LazyThemeLabControls {...themeLab} />
+            </Box>
+          )}
+        </Suspense>
+      </Box>
+    </Flex>
+  )
+}