basalt-ui 1.12.0 → 1.14.0

package/src/agent-chat/thread-outcome-card.tsx

@@ -23,6 +23,7 @@ import { useHover } from '@mantine/hooks'
 import type { JSX } from 'react'
 import type { AgentThread, ThreadStatus } from '../agent'
 import { alpha, VX } from '../tokens'
+import { formatRelativeTime } from './relative-time'
 
 // ── Status badge — shown ONLY for states that need a glance (attention/error). ────
 // done/pending/streaming stay badge-free: a settled feed shouldn't be a wall of green chips —
@@ -35,31 +36,6 @@ const STATUS_BADGE: Partial<
   error: { label: 'Failed', statusToken: VX.status.bad },
 }
 
-// ── Dependency-free relative-time helper (no date-fns) ────────────────────────
-
-const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
-
-const RELATIVE_TIME_UNITS: readonly {
-  readonly unit: Intl.RelativeTimeFormatUnit
-  readonly ms: number
-}[] = [
-  { unit: 'year', ms: 31_536_000_000 },
-  { unit: 'month', ms: 2_628_000_000 },
-  { unit: 'week', ms: 604_800_000 },
-  { unit: 'day', ms: 86_400_000 },
-  { unit: 'hour', ms: 3_600_000 },
-  { unit: 'minute', ms: 60_000 },
-]
-
-/** Formats an epoch-ms timestamp as a short relative string ("3 hours ago", "just now"). */
-function formatRelativeTime(timestamp: number): string {
-  const diffMs = timestamp - Date.now()
-  const absMs = Math.abs(diffMs)
-  if (absMs < 60_000) return 'just now'
-  const unit = RELATIVE_TIME_UNITS.find(({ ms }) => absMs >= ms) ?? RELATIVE_TIME_UNITS.at(-1)!
-  return RELATIVE_TIME_FORMAT.format(Math.round(diffMs / unit.ms), unit.unit)
-}
-
 // ── Row bodies ─────────────────────────────────────────────────────────────────
 
 /** Preview skeleton shown while a thread has no resolved outcome yet (never raw prompt/live text). */

package/src/agent-chat/thread-workspace.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * ThreadWorkspace — hydration gating (D1).
+ *
+ * A store built with `createAdapterThreadsStore` starts `!hydrated` until its first `listThreads`
+ * succeeds. Before this fix, `ThreadWorkspace` read only `threads.length` to decide between the
+ * feed and the empty state, so a server-backed store with real threads (a database, a real API)
+ * would render "no threads yet" for the whole initial round trip, then swap to the populated feed
+ * once it landed — a defect invisible in the playground's demo only because that demo's in-memory
+ * adapter seeds an empty Map, so there is nothing to flash to.
+ *
+ * These tests drive `ThreadWorkspace` directly against a hand-built `ThreadsStore` (not a real
+ * `createAdapterThreadsStore` instance) so each case can assert one exact `{ hydrated, threads }`
+ * combination without racing a real async adapter.
+ */
+import { MantineProvider } from '@mantine/core'
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, test } from 'bun:test'
+import type { ReactElement } from 'react'
+import type { AgentThread, AgentTransport, OutcomeResolver, ThreadsStore } from '../agent'
+import { createThreadsStore } from '../agent'
+import { ThreadWorkspace } from './thread-workspace'
+
+afterEach(cleanup)
+
+// `useMediaQuery` reads `window.matchMedia` inside a mount effect RTL flushes synchronously —
+// force the wide-viewport branch so every case renders the feed pane (same idiom as
+// thread-feed.test.tsx's `withReducedMotion`).
+function withWideViewport<T>(fn: () => T): T {
+  const original = window.matchMedia
+  window.matchMedia = (query: string): MediaQueryList =>
+    ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }) as MediaQueryList
+  try {
+    return fn()
+  } finally {
+    window.matchMedia = original
+  }
+}
+
+function noop(): void {}
+
+/** A transport that never resolves — no case here calls `start()`, so `stream` is never invoked. */
+const stubTransport: AgentTransport<never, string> = {
+  stream: (): AsyncGenerator<never> => {
+    throw new Error('stubTransport.stream must not be called by these tests')
+  },
+}
+
+const stubResolveOutcome: OutcomeResolver = async (thread) => ({
+  title: thread.id,
+  summary: '',
+  status: 'done',
+})
+
+function buildThread(id: string): AgentThread {
+  return {
+    id,
+    messages: [],
+    outcome: { title: id, summary: '', status: 'done' },
+    status: 'done',
+    read: true,
+    createdAt: 0,
+    updatedAt: 0,
+  }
+}
+
+/** A minimal fixed `ThreadsStore` — every mutator is a no-op since no case here calls one. */
+function makeStore(overrides: Partial<ThreadsStore>): ThreadsStore {
+  return {
+    threads: [],
+    activeId: null,
+    hydrated: true,
+    error: undefined,
+    select: noop,
+    create: () => 'unused',
+    appendMessage: noop,
+    setOutcome: noop,
+    setStatus: noop,
+    setResumeToken: noop,
+    markRead: noop,
+    remove: noop,
+    clear: noop,
+    ...overrides,
+  }
+}
+
+function renderWorkspace(store: ThreadsStore): ReactElement {
+  return (
+    <MantineProvider>
+      <ThreadWorkspace
+        useThreads={() => store}
+        transport={stubTransport}
+        resolveOutcome={stubResolveOutcome}
+      />
+    </MantineProvider>
+  )
+}
+
+describe('ThreadWorkspace hydration gating', () => {
+  test('hydrating + empty: renders the hydrating hold, never the empty-state copy', () => {
+    withWideViewport(() => {
+      render(renderWorkspace(makeStore({ hydrated: false, threads: [] })))
+    })
+
+    expect(screen.getByTestId('thread-workspace-hydrating')).toBeDefined()
+    expect(screen.queryByText('No threads yet')).toBeNull()
+  })
+
+  test('hydrating + already-populated: renders the feed content, not the hydrating hold', () => {
+    withWideViewport(() => {
+      render(renderWorkspace(makeStore({ hydrated: false, threads: [buildThread('cached-1')] })))
+    })
+
+    expect(screen.getByText('cached-1')).toBeDefined()
+    expect(screen.queryByTestId('thread-workspace-hydrating')).toBeNull()
+  })
+
+  test('failed load: renders the error state, never the hydrating hold', () => {
+    withWideViewport(() => {
+      render(
+        renderWorkspace(
+          makeStore({ hydrated: false, error: new Error('listThreads failed'), threads: [] }),
+        ),
+      )
+    })
+
+    expect(screen.getByTestId('thread-workspace-error')).toBeDefined()
+    expect(screen.queryByTestId('thread-workspace-hydrating')).toBeNull()
+  })
+
+  test('hydrated + empty: renders the empty state (no threads really is the truth)', () => {
+    withWideViewport(() => {
+      render(renderWorkspace(makeStore({ hydrated: true, threads: [] })))
+    })
+
+    expect(screen.getByText('No threads yet')).toBeDefined()
+    expect(screen.queryByTestId('thread-workspace-hydrating')).toBeNull()
+  })
+
+  test('real synchronous createThreadsStore: never shows the hydrating hold, even on first render', () => {
+    // The real localStorage-backed store (hydrated pinned `true` — see thread.test.ts), not the
+    // hand-built stub above, so this proves the gate reads a genuine ThreadsStore correctly and
+    // does not regress the synchronous path with a permanent skeleton.
+    const useThreads = createThreadsStore({ key: 'thread-workspace-sync-empty', version: 1 })
+
+    withWideViewport(() => {
+      render(
+        <MantineProvider>
+          <ThreadWorkspace
+            useThreads={useThreads}
+            transport={stubTransport}
+            resolveOutcome={stubResolveOutcome}
+          />
+        </MantineProvider>,
+      )
+    })
+
+    expect(screen.getByText('No threads yet')).toBeDefined()
+    expect(screen.queryByTestId('thread-workspace-hydrating')).toBeNull()
+  })
+})

package/src/agent-chat/thread-workspace.tsx

@@ -32,11 +32,12 @@
  *   )
  * }
  */
-import { Box, Divider, Flex, Stack, Text } from '@mantine/core'
+import { Box, Divider, Flex, Skeleton, Stack, Text } from '@mantine/core'
 import { useMediaQuery } from '@mantine/hooks'
 import type { JSX, ReactNode } from 'react'
 import type { AgentPart, AgentTransport, OutcomeResolver, ThreadsStore } from '../agent'
 import { useAgentThreadRuns } from '../agent'
+import { VX } from '../tokens'
 import { Composer } from './composer'
 import { ThreadDetailPanel } from './thread-detail-panel'
 import { ThreadFeed } from './thread-feed'
@@ -56,11 +57,23 @@ export type ThreadWorkspaceProps = {
   readonly resolveOutcome: OutcomeResolver<AgentPart>
   /** Placeholder for the new-thread composer pinned under the feed. */
   readonly newThreadPlaceholder?: string
-  /** Rendered in place of the feed while there are no threads yet. */
+  /**
+   * Rendered in place of the feed once the store is hydrated and there really are no threads.
+   * Shown ONLY when `store.hydrated` is true — while an async store's initial load is still in
+   * flight, `ThreadWorkspace` holds a neutral loading state instead (see `FeedHydratingState`),
+   * so a server-backed workspace never asserts "no threads yet" before it actually knows that.
+   */
   readonly emptyState?: ReactNode
+  /**
+   * Rendered in place of the feed when the store's initial load has failed — `!store.hydrated &&
+   * store.error !== undefined` (see `ThreadsStore.hydrated`'s doc for the discriminant). Shown
+   * instead of `FeedHydratingState`, so a rejected `listThreads` surfaces a legible failure rather
+   * than an endless skeleton.
+   */
+  readonly errorState?: ReactNode
 }
 
-/** Default hint shown in the feed pane before any thread exists (overridable via `emptyState`). */
+/** Default hint shown in the feed pane once hydrated with no threads (overridable via `emptyState`). */
 function FeedEmptyState(): JSX.Element {
   return (
     <Stack align="center" justify="center" gap={4} h="100%" p="xl">
@@ -74,6 +87,50 @@ function FeedEmptyState(): JSX.Element {
   )
 }
 
+/**
+ * Neutral hold shown in the feed pane while an async store's initial `listThreads` is still in
+ * flight, has no threads to show yet, AND has not failed (`!store.hydrated && threads.length ===
+ * 0 && store.error === undefined`). Never shown for the synchronous `createThreadsStore`, whose
+ * `hydrated` is always `true` — see `ThreadsStore.hydrated`'s doc. A store that already holds
+ * cached threads while revalidating (`!hydrated` with a non-empty `threads`) skips this entirely
+ * and renders the feed normally. A failed load renders `FeedErrorState` instead of this.
+ */
+function FeedHydratingState(): JSX.Element {
+  return (
+    <Stack gap="sm" p="sm" data-testid="thread-workspace-hydrating">
+      <Skeleton height={54} radius="sm" />
+      <Skeleton height={54} radius="sm" />
+      <Skeleton height={54} radius="sm" />
+    </Stack>
+  )
+}
+
+/**
+ * Default failure hold shown in the feed pane when an async store's initial `listThreads` has
+ * rejected (`!store.hydrated && store.error !== undefined`), overridable via `errorState`. Never
+ * shown for the synchronous `createThreadsStore`, whose `error` is always `undefined` — see
+ * `ThreadsStore.error`'s doc.
+ */
+function FeedErrorState(): JSX.Element {
+  return (
+    <Stack
+      align="center"
+      justify="center"
+      gap={4}
+      h="100%"
+      p="xl"
+      data-testid="thread-workspace-error"
+    >
+      <Text fw={600} size="sm" style={{ color: VX.status.bad }}>
+        Couldn&apos;t load threads
+      </Text>
+      <Text size="xs" c="dimmed" ta="center">
+        Something went wrong loading your threads. Try refreshing the page.
+      </Text>
+    </Stack>
+  )
+}
+
 /**
  * A two-pane master-detail thread workspace: a scrollable feed of threads with an anchored
  * new-thread composer, and a detail panel for the open thread's live transcript. Collapses to a
@@ -88,6 +145,7 @@ export function ThreadWorkspace({
   resolveOutcome,
   newThreadPlaceholder,
   emptyState,
+  errorState,
 }: ThreadWorkspaceProps): JSX.Element {
   const store = useThreads()
   const runs = useAgentThreadRuns({ transport, store, resolveOutcome })
@@ -130,8 +188,14 @@ export function ThreadWorkspace({
   const feed = (
     <Flex direction="column" h="100%" style={{ overflow: 'hidden' }}>
       <Box style={{ flex: 1, minHeight: 0 }}>
-        {store.threads.length === 0 ? (
-          (emptyState ?? <FeedEmptyState />)
+        {threads.length === 0 ? (
+          store.hydrated ? (
+            (emptyState ?? <FeedEmptyState />)
+          ) : store.error !== undefined ? (
+            (errorState ?? <FeedErrorState />)
+          ) : (
+            <FeedHydratingState />
+          )
         ) : (
           <ThreadFeed threads={threads} activeId={store.activeId} onSelect={handleSelect} />
         )}

package/src/agent-chat/virtualize.ts

@@ -0,0 +1,132 @@
+/**
+ * Virtualization contract shared by the transcript/feed components that can opt into
+ * `@tanstack/react-virtual` for long lists.
+ *
+ * The `VirtualizeProps` union IS the guard: a virtualizer needs a measured scroll container, so
+ * turning `virtualize` on REQUIRES a `height` and turning it off (or omitting it) FORBIDS one. See
+ * `virtualize.type-guard.test.ts` beside this file for a compile-time proof that the union actually
+ * rejects the invalid combinations.
+ *
+ * The one piece of runtime here is {@link resolveVirtualize} — the single narrowing point every
+ * component that accepts `VirtualizeProps` goes through, so no call site has to re-derive (or
+ * assert its way past) the union's `virtualize`-implies-`height` link.
+ *
+ * The other half of the contract, not encoded in the types (it's a runtime/composition rule, not
+ * a shape): a virtualized transcript OWNS ITS OWN SCROLL NODE (the element `getScrollElement`
+ * measures) and must NOT be nested inside `BasaltStickToBottom` — unlike the non-virtual path,
+ * which `ThreadDetailPanel` nests inside `BasaltStickToBottom` today (its transcript body).
+ * Stacking a virtualizer's own scroll container inside `BasaltStickToBottom`'s would give the
+ * transcript two competing owners of "which element scrolls" and break both the virtualizer's
+ * `scrollToEnd` and stick-to-bottom's anchor tracking.
+ *
+ * A third composition rule, same category (runtime, not a shape): a virtualized transcript
+ * tolerates being hidden via `display: none` on an ANCESTOR (e.g. sitting inside a collapsible
+ * `ThreadFeedRow`) — collapsing does not corrupt its measurement cache, and re-expanding restores
+ * the same scroll position (same top-visible row) it had before the collapse. This is NOT free of
+ * virtual-core: hiding an ancestor makes every mounted row's ResizeObserver box report `0` (a
+ * `display: none` ancestor un-lays-out its descendants), and virtual-core 3.17.1's default
+ * `measureElement`/`resizeItem` write that `0` into `itemSizeCache` with no floor — unguarded, a
+ * few collapse/expand cycles permanently shrink `getTotalSize()` and silently scroll the visible
+ * window to a DIFFERENT part of the transcript (`scrollTop` stays put; the content under it moves).
+ * `thread-message.tsx` closes this with a `measureElement` override (`resolveGuardedMeasurement`)
+ * that treats a `0` reading as unreliable and keeps the last-known size instead of committing it —
+ * see that function's doc for the full mechanism, including why `useVirtualizer`'s `enabled` option
+ * is NOT the fix (it wipes the measurement cache outright, worse than the bug). A consumer combining a
+ * virtualized transcript with its own hide-via-CSS container gets this for free; a consumer who
+ * unmounts/remounts the transcript instead of hiding it is unaffected either way (a fresh
+ * `useVirtualizer` call has no stale cache to poison).
+ *
+ * A fourth composition rule: a virtualized transcript SCROLLS ITSELF on mount. `initialScroll`
+ * defaults to `'end'` — `anchorTo: 'end'` and `followOnAppend` (both wired in `thread-message.tsx`)
+ * only keep an ALREADY-at-the-end transcript pinned as content changes; neither performs the initial
+ * jump, so left alone a freshly mounted virtualized transcript renders at message #0, not the
+ * newest. The fix fires exactly once, on first mount, via `scrollToEnd()` — never again, so a user
+ * who has scrolled up is never yanked back down by a later append (that is precisely the failure
+ * `followOnAppend` exists to avoid, and re-introducing it here would be worse than the defect this
+ * closes). A consumer wiring its OWN scroll-restoration (e.g. `initialOffset` /
+ * `initialMeasurementsCache`, restoring a prior session's position) wants `initialScroll: 'start'` —
+ * otherwise this default jump fires first and the restoration has to fight it. `initialScroll` is
+ * ignored (no scroll, no throw) for an empty transcript, and is deferred rather than treated as done
+ * if the transcript's own scroll container measures 0px on mount (e.g. mounted behind a hidden
+ * ancestor) — it then lands on the first commit where the container is genuinely measurable, which
+ * is what makes "opens at the newest message" hold for a transcript whose lazy virtualizer settled
+ * while its `ThreadFeedRow` was collapsed. See `thread-message.tsx`'s `applyInitialScroll` for the
+ * guard, and `VirtualizedRowsInner` for why its effect is deliberately dependency-free.
+ *
+ * Firing `scrollToEnd()` once is not sufficient on its own to land there, because virtual-core
+ * 3.17.1's own `_willUpdate` writes to the SAME scroll container on the very next commit it runs
+ * on, from state that lags behind the DOM: `_scrollToOffset` only ever records the write's
+ * intent (`_intendedScrollOffset`) — `this.scrollOffset` itself updates ASYNCHRONOUSLY, from the
+ * native `scroll` event, not from the call that requested it. So a commit that runs `_willUpdate`
+ * before this effect had a chance to fire (element-attach) or that re-derives an anchor from
+ * `getScrollOffset()` while `this.scrollOffset` is still the pre-jump value (the anchor branch,
+ * gated on `pendingScrollAnchor`) writes that stale offset — 0, on first mount — straight back to
+ * `scrollTop`, clobbering this effect's jump within roughly one extra commit of it landing.
+ * `applyInitialScroll` survives this the same way the hidden-ancestor case above already
+ * (accidentally) does: by not treating one successful call as permanent. It fires, then — on a
+ * LATER call, i.e. a later commit, exactly the cadence this dependency-free effect already runs on
+ * — reads the container's REAL `scrollTop`/`scrollHeight`/`clientHeight` (never virtual-core's own
+ * `scrollOffset`, which is exactly the stale value that caused the clobber) to check whether the
+ * jump survived; if it didn't, it re-fires, bounded by `MAX_INITIAL_SCROLL_ATTEMPTS` so a DOM that
+ * pathologically never reports settled can never be fought forever. `resolveInitialScrollAction`
+ * itself is untouched by any of this — it is still the one-shot "should I even attempt this"
+ * decision; `applyInitialScroll` layers the across-commits verification on top.
+ *
+ * `initialOffset` (`number | (() => number)`, `virtual-core`'s own construction-time seed for
+ * `scrollOffset`) was investigated as a way to avoid the clobber altogether and rejected: it takes
+ * a concrete pixel number, not an `'end'` sentinel, and the only number available at the point
+ * it would need to resolve — before any row has ever been measured — is an ESTIMATE
+ * (`estimateSize` × count), not the real total. It would relocate the transcript's initial paint
+ * from message #0 to an approximately-right position, but the moment real measurements replace
+ * those estimates the total size (and therefore the true end offset) changes, which still needs a
+ * corrective `scrollToEnd()` once rows have actually measured — the exact write this whole
+ * mechanism exists to protect. It also can't reference the `virtualizer` instance it would be
+ * computing an offset for without a separate ref indirection, since it is itself one of the options
+ * passed to construct that instance. Not a fix for this defect, just a smaller wrong first paint.
+ */
+
+/** Tuning knobs passed through to `@tanstack/react-virtual`'s `useVirtualizer`. */
+export type VirtualizeOptions = {
+  /** Extra rows rendered beyond the visible viewport, each side. Library default: 1. */
+  readonly overscan?: number
+  /** Estimated row height in px, used before a row has been measured. */
+  readonly estimateSize?: number
+  /** Where the transcript sits on first mount. Default 'end' — a chat transcript opens at the
+      newest message. 'start' opens at the oldest. See this module's fourth composition rule
+      above for the mechanism and why a consumer restoring its own scroll position wants 'start'. */
+  readonly initialScroll?: 'end' | 'start'
+}
+
+/**
+ * `virtualize: false` (or omitted) → no `height` prop (content-sized, non-scrolling-owner layout).
+ * `virtualize: true | VirtualizeOptions` → `height` is REQUIRED — the virtualizer measures a fixed
+ * scroll container, so there is no valid virtualized layout without one.
+ */
+export type VirtualizeProps =
+  | { readonly virtualize?: false; readonly height?: never }
+  | { readonly virtualize: true | VirtualizeOptions; readonly height: number | string }
+
+/** The enabled branch of {@link VirtualizeProps}, with `height` no longer optional. */
+export type ResolvedVirtualize = {
+  readonly options: VirtualizeOptions
+  readonly height: number | string
+}
+
+/**
+ * Narrows a `VirtualizeProps` pair once, centrally: `null` when virtualization is off, otherwise
+ * the options object (normalizing the bare `virtualize: true` shorthand to `{}`) alongside the
+ * `height` the union guarantees is present. Every component accepting `VirtualizeProps` resolves
+ * through here rather than destructuring the two fields apart — destructuring severs the link TS
+ * needs, which is what forces a non-null assertion on `height` at each call site.
+ */
+export function resolveVirtualize(props: VirtualizeProps): ResolvedVirtualize | null {
+  const { virtualize } = props
+  if (virtualize === undefined || virtualize === false) return null
+  // The union already REQUIRES `height` on this branch and rejects it on the other — that guarantee
+  // is enforced where it matters, at every call site (see virtualize.type-guard.test.ts). What TS
+  // won't do is propagate the narrowing FROM `virtualize` TO `height`: `virtualize`'s enabled branch
+  // is `true | VirtualizeOptions`, and the object constituent disqualifies it as a discriminant
+  // property. So the pairing is re-stated once, here, instead of a `height!` at each consumer.
+  const height = props.height as number | string
+  return { options: virtualize === true ? {} : virtualize, height }
+}

package/src/agent-chat/virtualize.type-guard.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Compile-time proof that `VirtualizeProps` actually rejects the invalid `virtualize`/`height`
+ * combinations (not just documentation).
+ *
+ * This mirrors the `apps/playground/src/*.type-guard.ts` convention (one `@ts-expect-error` per bad
+ * line, proven by CI's `tsc --noEmit`) but lives HERE, beside the type, rather than in the
+ * playground app. `VirtualizeProps` IS public now (re-exported type-only from the agent-chat barrel
+ * and the root), so a playground fixture would also work — this stays put because a source-relative
+ * import proves the union at its definition, before the build, and needs no rebuild to stay honest.
+ * A co-located `.type-guard.ts` file under `src/` would get picked up by tsup's
+ * `src/**\/*.{ts,tsx}` build glob and ship an unused fixture in the published package; naming it
+ * `*.test.ts` excludes it from that glob (tsup.config.ts excludes `src/**\/*.test.{ts,tsx}`) while
+ * this package's own `tsc --noEmit` (and `bun test`, which type-checks test files per the repo
+ * convention) still verifies it.
+ */
+import { describe, expect, test } from 'bun:test'
+import type { VirtualizeProps } from './virtualize'
+
+function accept(props: VirtualizeProps): VirtualizeProps {
+  return props
+}
+
+// ── Valid combinations — must type-check with no error ────────────────────────
+
+accept({})
+accept({ virtualize: false })
+accept({ virtualize: true, height: 400 })
+accept({ virtualize: true, height: '100%' })
+accept({ virtualize: { overscan: 3 }, height: 400 })
+accept({ virtualize: { estimateSize: 72 }, height: '50vh' })
+
+// ── Invalid combinations — each MUST be a tsc error, one directive per bad line ─
+
+// @ts-expect-error `height` is forbidden when `virtualize` is false
+accept({ virtualize: false, height: 400 })
+// @ts-expect-error `height` is required when `virtualize: true`
+accept({ virtualize: true })
+// @ts-expect-error `height` is required when `virtualize` is a VirtualizeOptions object
+accept({ virtualize: { overscan: 2 } })
+// @ts-expect-error `height` is forbidden when `virtualize` is omitted (defaults to the `false` branch)
+accept({ height: 400 })
+
+describe('VirtualizeProps (type-guard)', () => {
+  test('is a compile-time-only fixture — see the @ts-expect-error directives above', () => {
+    // No runtime behavior to assert: the proof is that this file type-checks at all. A single
+    // trivial assertion keeps this a normal bun:test file rather than an empty-suite oddity.
+    expect(true).toBe(true)
+  })
+})

package/src/data/index.ts

@@ -7,7 +7,11 @@
  *
  * Optional peers:
  *  - @tanstack/react-table  >=8 <9  (BasaltDataTable)
- *  - @tanstack/react-virtual >=3 <4  (BasaltVirtualList)
+ *  - @tanstack/react-virtual >=3.13.26 <4  (BasaltVirtualList)
+ *
+ * BasaltVirtualList itself works on any 3.x; the declared floor is set by ./agent-chat's
+ * ThreadTranscript virtualize mode (it calls scrollToEnd/anchorTo, added in virtual-core 3.16.0,
+ * first pinned by react-virtual 3.13.26). npm has one peer range per package, so do not lower it.
  *
  * Install with:
  *   bun add @tanstack/react-table @tanstack/react-virtual

package/src/data/virtual-list.tsx

@@ -1,7 +1,8 @@
 /**
  * ./data — BasaltVirtualList: a windowed virtual list over @tanstack/react-virtual,
  * rendered with a Mantine Box scroll container.
- * Optional peer: @tanstack/react-virtual >=3 <4.
+ * 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.
  *
  * @example
  * import { BasaltVirtualList } from 'basalt-ui/data'

package/src/data/virtual.ts

@@ -2,7 +2,8 @@
  * ./data/virtual — BasaltVirtualList: a windowed virtual list over @tanstack/react-virtual,
  * rendered with a Mantine Box scroll container.
  *
- * Optional peer: @tanstack/react-virtual >=3 <4.
+ * 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.
  *
  * 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.

package/src/index.ts

@@ -113,6 +113,7 @@ export type { GuardKind } from './guard/types'
 export {
   ThreadWorkspace,
   ThreadFeed,
+  ThreadFeedRow,
   ThreadOutcomeCard,
   ThreadDetailPanel,
   Composer,
@@ -123,6 +124,7 @@ export {
 export type {
   ThreadWorkspaceProps,
   ThreadFeedProps,
+  ThreadFeedRowProps,
   ThreadOutcomeCardProps,
   ThreadDetailPanelProps,
   ComposerProps,
@@ -130,6 +132,9 @@ export type {
   ComposerAttachment,
   ComposerHandle,
   ThreadTranscriptProps,
+  MessageAffordances,
+  VirtualizeOptions,
+  VirtualizeProps,
   ToolChipProps,
 } from './agent-chat'
 export {

package/src/shell/app-sidebar.module.css

@@ -419,4 +419,15 @@
   .root[data-collapsed] .childList {
     display: none;
   }
+
+  /* `navExtra` has no sensible icon-rail representation (arbitrary consumer content, not a nav
+   * row) — hide it in the rail, same treatment as `.childList`. It stays mounted (never a JS
+   * conditional on `collapsed`): `collapsed` is one value shared by the desktop rail AND the
+   * mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` only ever un-collapses
+   * the mobile side), and the rail-vs-drawer split lives ENTIRELY in this media query, never in JS —
+   * a JS gate on `collapsed` would also drop `navExtra` from the mobile drawer, which opens at full
+   * width regardless of the persisted rail state. */
+  .root[data-collapsed] .navExtra {
+    display: none;
+  }
 }

package/src/shell/app-sidebar.module.css.d.ts

@@ -29,6 +29,7 @@ declare const classes: {
   readonly sectionHeader: string
   readonly subnavDropdown: string
   readonly childList: string
+  readonly navExtra: string
   readonly ghostIcon: string
 }
 export default classes