basalt-ui 1.28.0 → 1.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",
@@ -77,6 +77,11 @@
       "import": "./dist/guard/index.js",
       "default": "./dist/guard/index.js"
     },
+    "./format": {
+      "types": "./dist/format/index.d.ts",
+      "import": "./dist/format/index.js",
+      "default": "./dist/format/index.js"
+    },
     "./forms": {
       "types": "./dist/forms/index.d.ts",
       "import": "./dist/forms/index.js",
@@ -92,21 +97,11 @@
       "import": "./dist/notifications/index.js",
       "default": "./dist/notifications/index.js"
     },
-    "./query": {
-      "types": "./dist/query/index.d.ts",
-      "import": "./dist/query/index.js",
-      "default": "./dist/query/index.js"
-    },
     "./router-tanstack": {
       "types": "./dist/router-tanstack/index.d.ts",
       "import": "./dist/router-tanstack/index.js",
       "default": "./dist/router-tanstack/index.js"
     },
-    "./data": {
-      "types": "./dist/data/index.d.ts",
-      "import": "./dist/data/index.js",
-      "default": "./dist/data/index.js"
-    },
     "./data/table": {
       "types": "./dist/data/table.d.ts",
       "import": "./dist/data/table.js",
@@ -147,11 +142,6 @@
       "import": "./dist/state.js",
       "default": "./dist/state.js"
     },
-    "./connectivity": {
-      "types": "./dist/connectivity/index.d.ts",
-      "import": "./dist/connectivity/index.js",
-      "default": "./dist/connectivity/index.js"
-    },
     "./styles.css": "./dist/styles.css",
     "./tokens.css": "./dist/tokens.css",
     "./configs/*": "./configs/*",
@@ -165,6 +155,7 @@
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly --declarationMap && bun scripts/copy-assets.mjs && bun scripts/gen-tokens-css.mjs && bun scripts/fix-esm-extensions.mjs",
     "typecheck": "tsc --noEmit",
+    "check-budgets": "bun scripts/check-budgets.ts",
     "test": "cd ../.. && bun test packages/basalt-ui",
     "pack-test": "bash scripts/pack-test.sh",
     "prepack": "bun run build",
@@ -179,6 +170,7 @@
     "@shikijs/langs": "^4.3.1",
     "@shikijs/themes": "^4.3.1",
     "@tanstack/react-hotkeys": "0.10.0",
+    "@tanstack/react-router-devtools": "^1.166.13",
     "@types/bun": "^1.3.14",
     "@types/hast": "^3.0.4",
     "@types/react": "^19.2.17",
@@ -224,6 +216,7 @@
     "@tanstack/react-query": "^5.101.0",
     "@tanstack/react-query-devtools": "^5.101.0",
     "@tanstack/react-router": "^1.170.0",
+    "@tanstack/react-router-devtools": "^1.166.13",
     "@tanstack/react-table": ">=8 <9",
     "@tanstack/react-virtual": ">=3.13.26 <4",
     "@visx/axis": "4.0.0",
@@ -298,6 +291,9 @@
     "@tanstack/react-router": {
       "optional": true
     },
+    "@tanstack/react-router-devtools": {
+      "optional": true
+    },
     "@tanstack/react-table": {
       "optional": true
     },

package/src/agent/ai-sdk-transport.ts

@@ -395,7 +395,11 @@ export function aiSdkTransport<TPart = AgentPart>(
       // diffPart), so a replayed run rewrites in place instead of duplicating — the literal
       // condition this assertion stands for.
       idempotentReplay: true,
-      async *stream(input: string, signal?: AbortSignal): AsyncGenerator<TPart> {
+      async *stream(
+        input: string,
+        signal?: AbortSignal,
+        ctx?: { readonly messageId: string },
+      ): AsyncGenerator<TPart> {
         // Synthesized locally, first — we already know the chat id client-side, so there is no
         // need to wait on the server to hand us a run id (unlike a river-style protocol).
         yield { id: `${chatId}#start`, type: 'start', runId: chatId, resumeToken: chatId } as TPart
@@ -403,9 +407,12 @@ export function aiSdkTransport<TPart = AgentPart>(
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk()
         const userMessage: UIMessage = {
           // This id is what AI SDK's own backend persistence/dedup keys turns hang off — the same
-          // idempotency-key cost as basalt's own ChatMessage.id (see mintMessageId's doc), so
-          // mintMessageId, not mintThreadId, is the right helper here.
-          id: mintMessageId(),
+          // idempotency-key cost as basalt's own ChatMessage.id (see mintMessageId's doc). Prefer
+          // the caller's OWN idempotency key (ctx.messageId — the id useAgentThreadRuns.start()
+          // already minted for this turn's ChatMessage) so the two never diverge for one turn; only
+          // a caller that omits ctx (useAgentStream, a hand-rolled stream() call) falls back to
+          // minting a fresh one here.
+          id: ctx?.messageId ?? mintMessageId(),
           role: 'user',
           parts: [{ type: 'text', text: input }],
         }

package/src/agent/coalesce.ts

@@ -38,7 +38,7 @@
  * <PartList parts={coalesceParts(parts)} />
  */
 import type { AgentPart, ReasoningPart, TextPart, ToolCallPart } from './parts'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 

package/src/agent/merge.ts

@@ -29,7 +29,7 @@
  * // parts === [{ id: 'p1', type: 'text', text: 'Hello' }]
  */
 import type { ReasoningPart, TextPart } from './parts'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 

package/src/agent/transport.ts

@@ -34,7 +34,7 @@ import type { AgentPart, AgentPartDraft } from './parts'
 // ── AgentTransport ────────────────────────────────────────────────────────────
 
 /**
- * The injected transport seam. `stream(input, signal)` returns an async generator of parts.
+ * The injected transport seam. `stream(input, signal, ctx)` returns an async generator of parts.
  * Implement this interface for any backend — Eden, fetch-based SSE, AI SDK, or a mock.
  *
  * The default `TPart` is `AgentPartDraft` (not `AgentPart`): transports yield DRAFTS — `id`
@@ -42,6 +42,15 @@ import type { AgentPart, AgentPartDraft } from './parts'
  * part before it is ever accumulated. Pass an explicit `AgentPart` generic when a transport mints
  * its own ids directly (as `aiSdkTransport` does).
  *
+ * `ctx.messageId`, when present, is the id `useAgentThreadRuns.start()` already minted for this
+ * turn's user `ChatMessage` — the SAME idempotency key `appendMessage`/the backend's dedup keys off
+ * of (see `mintMessageId`'s doc). A transport that mints its OWN wire-level message id independent
+ * of that (as `aiSdkTransport` used to) forces the consumer to reconcile two ids for one turn; a
+ * transport MAY use `ctx.messageId` as its outbound message id instead of minting a fresh one. The
+ * param is optional and appended last so an existing two-arg transport keeps compiling unchanged —
+ * only `useAgentThreadRuns.start()`/`retry()` pass it; a bare `stream(input, signal)` call (e.g.
+ * `useAgentStream`, a hand-rolled caller) omits it and a transport falls back to minting its own.
+ *
  * @example
  * // Minimal mock transport for tests / playground:
  * const mockTransport: AgentTransport = {
@@ -51,7 +60,11 @@ import type { AgentPart, AgentPartDraft } from './parts'
  * }
  */
 export type AgentTransport<TPart = AgentPartDraft, TInput = string> = {
-  stream: (input: TInput, signal?: AbortSignal) => AsyncGenerator<TPart>
+  stream: (
+    input: TInput,
+    signal?: AbortSignal,
+    ctx?: { readonly messageId: string },
+  ) => AsyncGenerator<TPart>
   /** Optional: resume a previously-started run from its resumeToken (see StartPart). Transports that don't support resumption simply omit this. */
   resume?: (resumeToken: string, signal?: AbortSignal) => AsyncGenerator<TPart>
 }

package/src/agent/use-agent-thread-runs.ts

@@ -96,6 +96,14 @@ export type UseAgentThreadRunsArgs<TPart = AgentPart> = {
    * Required when TPart is not the default AgentPart union.
    */
   readonly toUserParts?: (input: string) => TPart[]
+  /**
+   * Called when a turn's stream throws — never for an `AbortError` (an intentional stop()/
+   * supersede, not a failure worth surfacing). Fires from the SAME catch branch that sets
+   * `onFailureStatus` on the thread, so a caller wanting a toast/notification for a genuine
+   * transport error (a 409/503/401, argo's hermes-chat S19) no longer has to wrap every transport
+   * call in its own generator to intercept the throw — see `consumeAndFinalize`'s catch block.
+   */
+  readonly onError?: (info: { readonly threadId: string; readonly error: unknown }) => void
 }
 
 // ── useAgentThreadRuns return type ────────────────────────────────────────────
@@ -207,6 +215,7 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
   resolveOutcome: OutcomeResolver<TPart>
   setRuns: Dispatch<SetStateAction<Map<string, ThreadRunState<TPart>>>>
   onFailureStatus: ThreadStatus
+  onError?: (info: { readonly threadId: string; readonly error: unknown }) => void
 }): Promise<void> {
   const {
     threadId,
@@ -219,6 +228,7 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
     resolveOutcome,
     setRuns,
     onFailureStatus,
+    onError,
   } = args
   let parts: TPart[] = []
   try {
@@ -314,6 +324,7 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
       next.delete(threadId)
       return next
     })
+    onError?.({ threadId, error: err })
   }
 }
 
@@ -435,6 +446,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   store,
   resolveOutcome,
   toUserParts,
+  onError,
 }: UseAgentThreadRunsArgs<TPart>): UseAgentThreadRunsReturn<TPart> {
   const [runs, setRuns] = useState<Map<string, ThreadRunState<TPart>>>(new Map())
   // Mirrors the latest `runs` state every render so stop() (a plain callback, not a render) can
@@ -442,6 +454,10 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   // updater — same mirroring pattern as storeRef/transportRef below.
   const runsRef = useRef(runs)
   runsRef.current = runs
+  // Mirrors the latest onError every render (same pattern as storeRef/transportRef) so a stale
+  // closure from an earlier render never fires instead of the consumer's current callback.
+  const onErrorRef = useRef(onError)
+  onErrorRef.current = onError
 
   // Refs: mutable per-render state that must not trigger re-renders.
   const controllersRef = useRef<Map<string, AbortController>>(new Map())
@@ -520,9 +536,12 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   // seeing a phantom in-flight turn no controller is driving anymore, and `stop()` on it was a
   // permanent no-op (nothing left in `controllersRef` to abort) — see `stop()`'s own doc. Scoped to
   // exactly the threadIds this pass is aborting (not a blind `runs.clear()`): the mount-reconcile
-  // effect below runs AFTER this cleanup completes, in the same synchronous commit (both are
-  // `[]`-dep effects on this same fiber, so StrictMode/`<Activity>` destroy-then-recreate both
-  // together, in declaration order) — a resumable thread's reconcile pass registers a FRESH
+  // effect below runs AFTER this cleanup completes, in the same synchronous commit — StrictMode's
+  // dev-only double-invoke and `<Activity>` hide/show both destroy-then-recreate EVERY mount effect
+  // on this fiber together, in declaration order, regardless of each effect's own dep array (this
+  // one stays `[]`; the reconcile effect below is `[store.hydrated]` as of R3 — the double-invoke
+  // guarantee is about the mount/unmount CYCLE, not per-effect dep memoization) — a resumable
+  // thread's reconcile pass registers a FRESH
   // controller and a fresh `runs` entry there, and this teardown must never clobber that. It
   // can't: by the time this cleanup runs, nothing has created a NEW entry for these threadIds yet
   // (that only happens in the reconcile effect, still to come), so scoping to the ids this pass is
@@ -547,17 +566,37 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
     [],
   )
 
-  // Reconcile orphaned in-flight threads on mount: a persisted thread can be stuck 'pending' or
-  // 'streaming' after a reload/remount, since controllersRef and `runs` both start empty — nothing
-  // would otherwise resolve that skeleton. If the transport supports resumption and the thread has
-  // a resumeToken (from a StartPart emitted before the disconnect) plus a user message to resume
-  // from, attempt to reconnect the run instead. Any other case — no resume(), no resumeToken, no
-  // user message, or the resume itself failing — falls back to 'interrupted' so the UI renders a
-  // resend prompt instead of an unresolving skeleton (today's behavior, unchanged as the fallback
-  // path). Mount-only by design (empty deps): this is a one-time sweep of whatever was persisted
-  // when this manager first attaches, not a recurring check — a thread only needs reconciling once
-  // per stale mount.
+  // Reconcile orphaned in-flight threads once the store is HYDRATED: a persisted thread can be
+  // stuck 'pending' or 'streaming' after a reload/remount, since controllersRef and `runs` both
+  // start empty — nothing would otherwise resolve that skeleton. If the transport supports
+  // resumption and the thread has a resumeToken (from a StartPart emitted before the disconnect)
+  // plus a user message to resume from, attempt to reconnect the run instead. Any other case — no
+  // resume(), no resumeToken, no user message, or the resume itself failing — falls back to
+  // 'interrupted' so the UI renders a resend prompt instead of an unresolving skeleton (today's
+  // behavior, unchanged as the fallback path).
+  //
+  // R3: keyed on `store.hydrated` rather than a bare `[]`-dep effect. `ThreadsStore.hydrated` is
+  // always `true` for the localStorage store (createPersistedState resolves synchronously), so this
+  // still fires on the very first commit for every consumer that predates this change — no behavior
+  // change there. It only matters for an ASYNC store (`createAdapterThreadsStore`): with `[]`, this
+  // ran on mount while `store.threads` was still the adapter's empty pre-load snapshot, so every
+  // orphaned thread from a previous session was invisible to the sweep — reconcile-after-reload was
+  // silently dead for exactly the store shape (server-backed, paginated) that most needs it. Firing
+  // again when `hydrated` flips true re-sweeps against the now-real `storeRef.current.threads`.
+  //
+  // Deliberately NO separate "has this already run" ref here — the sweep is naturally idempotent:
+  // a thread only qualifies as orphaned while its status is 'pending'/'streaming' AND it has no
+  // live controller, and this effect's own first pass either moves the status off that pair
+  // ('interrupted', or eventually 'done'/'error' once the resumed/started run settles) or registers
+  // a controller for it synchronously (before the first `await`) — so a second invocation with the
+  // SAME `store.hydrated` value (including React 19 StrictMode's dev-only double-invoke of every
+  // mount effect, and an `<Activity>` hide/show — see use-agent-thread-runs.wedge.test.tsx) finds
+  // nothing left to reconcile except whatever its own sibling invocation genuinely orphaned by
+  // aborting an in-flight controller, which is exactly the case that file's (b)/(c) tests require
+  // resume() to fire again for. An explicit "ran once" ref would suppress that second, legitimate
+  // sweep and reintroduce the F3 wedge for `store.hydrated`-keyed remounts.
   useEffect(() => {
+    if (!store.hydrated) return
     for (const thread of storeRef.current.threads) {
       const orphaned =
         (thread.status === 'pending' || thread.status === 'streaming') &&
@@ -606,10 +645,14 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
         resolveOutcome,
         setRuns,
         onFailureStatus: 'interrupted',
+        onError: (info) => onErrorRef.current?.(info),
       })
     }
+    // Only `store.hydrated` — every other read in this body goes through a ref (storeRef,
+    // resolveTransport→transportRef/transportsRef, resolveOutcome closed over from the hook's own
+    // args) precisely so this effect's re-run trigger is `hydrated` alone. See the doc above.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
+  }, [store.hydrated])
 
   const start = useCallback(
     (threadId: string, input: string): void => {
@@ -643,7 +686,13 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
         threadId,
         controller,
         // Namespaced by threadId — same choice, same caveat, as the mount-time resume call above.
-        generator: withPartIds(threadId, resolvedTransport.stream(input, controller.signal)),
+        // ctx.messageId is this turn's OWN idempotency key (userMessage.id, just minted above) —
+        // a transport that accepts it (aiSdkTransport) mints its wire-level message with the SAME
+        // id instead of a second, unrelated one (R1 — see AgentTransport.stream's doc).
+        generator: withPartIds(
+          threadId,
+          resolvedTransport.stream(input, controller.signal, { messageId: userMessage.id }),
+        ),
         userMessage,
         controllersRef,
         appendedRef,
@@ -651,6 +700,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
         resolveOutcome,
         setRuns,
         onFailureStatus: 'error',
+        onError: (info) => onErrorRef.current?.(info),
       })
     },
     [resolveOutcome],

package/src/agent-chat/index.ts

@@ -25,11 +25,13 @@ export type { ThreadFeedRowProps } from './thread-feed-row'
 
 // ── Shared transcript/row contracts ───────────────────────────────────────────
 // Type-only. Both are named in the PUBLIC props of components exported above
-// (`ThreadTranscriptProps.affordances`, `ThreadFeedRowProps`'s virtualize union), so a consumer
-// that wants to hold one in a typed variable needs to be able to name it. No runtime export here —
-// the resolution/defaults live inside the components.
+// (`ThreadTranscriptProps.affordances`, `ThreadFeedRowProps`'s height union), so a consumer that
+// wants to hold one in a typed variable needs to be able to name it. No runtime export here — the
+// resolution/defaults live inside the components. `RowHeightProps` (B3) is `ThreadFeedRow`'s OWN
+// height contract — a superset of `VirtualizeProps` that also allows `height` without
+// `virtualize` — kept alongside it for the same reason.
 export type { MessageAffordances } from './message-affordances'
-export type { VirtualizeOptions, VirtualizeProps } from './virtualize'
+export type { RowHeightProps, VirtualizeOptions, VirtualizeProps } from './virtualize'
 
 // ── ThreadOutcomeCard ─────────────────────────────────────────────────────────
 export { ThreadOutcomeCard } from './thread-outcome-card'

package/src/agent-chat/relative-time.ts

@@ -7,7 +7,7 @@
  *
  * Internal to `agent-chat/` — not part of the public barrel.
  */
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
 

package/src/agent-chat/thread-detail-panel.tsx

@@ -28,7 +28,7 @@ import type { AgentPart, AgentThread, StreamStatus } from '../agent'
 import { BasaltStickToBottom } from '../agent'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
-import { MOTION_SPRING } from '../motion'
+import { MOTION_SPRING } from '../common/motion'
 import { Composer } from './composer'
 import { ThreadTranscript } from './thread-message'
 import { VX } from '../tokens'

package/src/agent-chat/thread-feed-row.tsx

@@ -33,18 +33,20 @@
  * />
  */
 import { Box, Group, Stack, Text, UnstyledButton } from '@mantine/core'
-import type { JSX } from 'react'
+import type { JSX, ReactNode } from 'react'
 import { useState } from 'react'
 import type {
   AgentThread,
+  ChatMessage,
   ForeignPart,
   PartRenderer,
   PartRenderers,
   StreamStatus,
   TranscriptPart,
 } from '../agent'
+import { BasaltStickToBottom } from '../agent'
 import { cx } from '../common/props'
-import type { BasaltProps } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
 import { VX } from '../tokens'
 import type { ComposerProps, ComposerSubmit } from './composer'
@@ -52,8 +54,8 @@ import { Composer } from './composer'
 import type { MessageAffordances } from './message-affordances'
 import { formatRelativeTime } from './relative-time'
 import { ThreadTranscript } from './thread-message'
-import { resolveVirtualize } from './virtualize'
-import type { VirtualizeProps } from './virtualize'
+import { resolveRowHeight } from './virtualize'
+import type { RowHeightProps, VirtualizeProps } from './virtualize'
 
 /** A minimal, dependency-free chevron — rotates 90deg when expanded (same inline-svg idiom as
  * `composer.tsx`'s `SendGlyph`/`StopGlyph`: no icon-library dependency for a one-off glyph). */
@@ -106,6 +108,30 @@ type ThreadFeedRowBase = {
   readonly expanded: boolean
   /** Called with the thread's id when the header is clicked/activated. */
   readonly onToggle: (id: string) => void
+  /**
+   * Header title override. Falls back to `thread.outcome?.title ?? 'Untitled thread'` (today's
+   * behavior, unchanged) when omitted. For a server-titled thread whose title is never distilled
+   * into a basalt `AgentOutcome` (argo's hermes-chat S4 — title/summary/type/pin are server-owned
+   * and never guessed client-side), pass it directly instead of forcing an outcome shape onto data
+   * that never had one.
+   */
+  readonly title?: string
+  /** Header summary override, same fallback rule as `title` (`thread.outcome?.summary ?? ''`). */
+  readonly summary?: string
+  /** Rendered at the START of the header row, before the title/summary stack — a pin icon, a type
+   * badge (argo's hermes-chat S5). Absent by default; renders nothing extra when omitted. */
+  readonly headerLeft?: ReactNode
+  /** Rendered at the END of the header row, before the timestamp and chevron — a collapsed-only
+   * streaming indicator (argo's hermes-chat S5). Absent by default; renders nothing extra when
+   * omitted. */
+  readonly headerRight?: ReactNode
+  /**
+   * Overrides the transcript source: when provided, the row renders THESE messages instead of
+   * reading `thread.messages` directly (argo's hermes-chat S6 — the confirmed transcript is an
+   * optimistic-overlay MERGE over the store's messages, not the store's messages verbatim).
+   * Defaults to `thread.messages`.
+   */
+  readonly messages?: readonly ChatMessage<TranscriptPart>[]
   /** The live (in-flight) assistant turn's parts, when a run is streaming for this thread. */
   readonly liveParts?: readonly TranscriptPart[]
   /** The live run's status — drives the in-progress indicator on the live block. */
@@ -137,16 +163,29 @@ type ThreadFeedRowBase = {
  * `virtualize`/`height` are forwarded straight to the row's `ThreadTranscript`, carrying the same
  * union guard: an inline row holding a very long thread can window it, and doing so REQUIRES a
  * `height` (the transcript then owns a fixed-height scroll node inside the expanded body, instead
- * of the body growing to the thread's full length). Omit both and the row's transcript is
- * content-sized, as before.
+ * of the body growing to the thread's full length). `height` alone (no `virtualize`) is B3's
+ * bounded-but-not-virtualized mode — see `RowHeightProps`'s own doc. Omit both and the row's
+ * transcript is content-sized, as before.
  */
-export type ThreadFeedRowProps = ThreadFeedRowBase & VirtualizeProps & BasaltProps
+export type ThreadFeedRowProps = ThreadFeedRowBase &
+  RowHeightProps &
+  SlotStylesProps<'root' | 'header' | 'body'> &
+  BasaltProps
+
+/** The row header's title: the `title` prop override, else the resolved outcome title, else a
+ * plain placeholder — this row never falls back to scanning the first user message the way
+ * `ThreadOutcomeCard`'s `promptOf` does, since an inline row's own expanded transcript already
+ * shows that prompt a scroll away. */
+function rowTitle(thread: AgentThread<TranscriptPart>, titleOverride: string | undefined): string {
+  return titleOverride ?? thread.outcome?.title ?? 'Untitled thread'
+}
 
-/** The row header's title: the resolved outcome title, else a plain placeholder — this row never
- * falls back to scanning the first user message the way `ThreadOutcomeCard`'s `promptOf` does,
- * since an inline row's own expanded transcript already shows that prompt a scroll away. */
-function rowTitle(thread: AgentThread<TranscriptPart>): string {
-  return thread.outcome?.title ?? 'Untitled thread'
+/** The row header's summary: the `summary` prop override, else the resolved outcome summary. */
+function rowSummary(
+  thread: AgentThread<TranscriptPart>,
+  summaryOverride: string | undefined,
+): string {
+  return summaryOverride ?? thread.outcome?.summary ?? ''
 }
 
 /**
@@ -162,6 +201,11 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
     thread,
     expanded,
     onToggle,
+    title,
+    summary: summaryOverride,
+    headerLeft,
+    headerRight,
+    messages,
     liveParts,
     liveStatus,
     renderers,
@@ -171,16 +215,21 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
     onSend,
     onStop,
     composerProps,
+    classNames,
     className,
     style,
   } = props
   assertRequiredProps('ThreadFeedRow', { thread }, ['thread'])
 
   // Resolved through the shared narrowing point rather than by destructuring `virtualize`/`height`
-  // apart — see `resolveVirtualize`'s doc for why the two must be read together.
-  const virtualized = resolveVirtualize(props)
+  // apart — see `resolveRowHeight`'s doc for why the two must be read together, and why it is a
+  // three-way (virtualized / bounded / content-sized) resolve rather than `resolveVirtualize`'s
+  // binary one (B3 adds the 'bounded' branch).
+  const rowHeight = resolveRowHeight(props)
   const virtualizeProps: VirtualizeProps =
-    virtualized === null ? {} : { virtualize: virtualized.options, height: virtualized.height }
+    rowHeight.kind === 'virtualized'
+      ? { virtualize: rowHeight.virtualize.options, height: rowHeight.virtualize.height }
+      : {}
 
   // Lazy-mount + keep-mounted: flips true on the row's first expand and never resets. Everything
   // below this line renders — once — the first time `expanded` becomes true, and stays in the tree
@@ -197,7 +246,9 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
     setHasOpened(true)
   }
 
-  const summary = thread.outcome?.summary ?? ''
+  const resolvedTitle = rowTitle(thread, title)
+  const resolvedSummary = rowSummary(thread, summaryOverride)
+  const transcriptMessages = messages ?? thread.messages
 
   // The composer half of `liveStatus`: `Composer` only shows its Stop action and gates the
   // textarea when it is TOLD a run is streaming (`composer.tsx`'s `showStop`/`inputDisabled`) — it
@@ -205,18 +256,37 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
   // Stop never rendered and a second turn could still be typed into a live thread.
   const streaming = liveStatus === 'streaming'
 
+  const transcript = (
+    <ThreadTranscript
+      messages={transcriptMessages}
+      {...(liveParts !== undefined ? { liveParts } : {})}
+      {...(liveStatus !== undefined ? { liveStatus } : {})}
+      {...(renderers !== undefined ? { renderers } : {})}
+      {...(fallbackRenderer !== undefined ? { fallbackRenderer } : {})}
+      {...(affordances !== undefined ? { affordances } : {})}
+      {...(groupConsecutive !== undefined ? { groupConsecutive } : {})}
+      {...virtualizeProps}
+    />
+  )
+
   return (
-    <Box className={cx(className)} style={style ? { ...CARD_STYLE, ...style } : CARD_STYLE}>
+    <Box
+      className={cx(classNames?.root, className)}
+      style={style ? { ...CARD_STYLE, ...style } : CARD_STYLE}
+      data-expanded={expanded}
+    >
       <UnstyledButton
         onClick={() => onToggle(thread.id)}
         w="100%"
         aria-expanded={expanded}
+        {...(classNames?.header !== undefined && { className: classNames.header })}
         style={{
           display: 'block',
           padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)',
         }}
       >
         <Group justify="space-between" gap="xs" wrap="nowrap" align="center">
+          {headerLeft}
           <Stack gap={2} style={{ flex: 1, minWidth: 0 }}>
             <Text
               fw={550}
@@ -227,14 +297,15 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
                 fontStretch: '88%',
               }}
             >
-              {rowTitle(thread)}
+              {resolvedTitle}
             </Text>
-            {summary.length > 0 && (
+            {resolvedSummary.length > 0 && (
               <Text size="xs" c="dimmed" lineClamp={1}>
-                {summary}
+                {resolvedSummary}
               </Text>
             )}
           </Stack>
+          {headerRight}
           <Text
             style={{
               fontFamily: 'var(--basalt-font-mono)',
@@ -251,6 +322,7 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
       {hasOpened && (
         <Box
           data-testid="thread-feed-row-body"
+          {...(classNames?.body !== undefined && { className: classNames.body })}
           style={{
             display: expanded ? 'block' : 'none',
             padding: 'var(--mantine-spacing-sm)',
@@ -258,16 +330,19 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
           }}
         >
           <Stack gap="sm">
-            <ThreadTranscript
-              messages={thread.messages}
-              {...(liveParts !== undefined ? { liveParts } : {})}
-              {...(liveStatus !== undefined ? { liveStatus } : {})}
-              {...(renderers !== undefined ? { renderers } : {})}
-              {...(fallbackRenderer !== undefined ? { fallbackRenderer } : {})}
-              {...(affordances !== undefined ? { affordances } : {})}
-              {...(groupConsecutive !== undefined ? { groupConsecutive } : {})}
-              {...virtualizeProps}
-            />
+            {rowHeight.kind === 'bounded' ? (
+              <BasaltStickToBottom
+                style={{
+                  height: rowHeight.height,
+                  // theme-allow raw-scroll-container — BasaltStickToBottom owns this scroll node (see stick-to-bottom.tsx).
+                  overflowY: 'auto',
+                }}
+              >
+                {transcript}
+              </BasaltStickToBottom>
+            ) : (
+              transcript
+            )}
             <Composer
               onSubmit={onSend}
               streaming={streaming}