basalt-ui 1.40.3 → 2.0.0

package/src/{agent-chat → agent/chat}/composer.tsx

@@ -25,7 +25,7 @@
  * <Composer
  *   ref={composerRef}
  *   draftKey={`thread:${thread.id}`}
- *   streaming={runStatus === 'streaming'}
+ *   streaming={run?.status === 'submitted' || run?.status === 'streaming'}
  *   onStop={() => runs.stop(thread.id)}
  *   leftSection={
  *     <VoiceRecordButton
@@ -38,11 +38,11 @@
  */
 import { ActionIcon, Box, Group, Kbd, Stack, Text, Textarea } from '@mantine/core'
 import type { ClipboardEvent, ComponentProps, JSX, KeyboardEvent, ReactNode, Ref } from 'react'
-import { useImperativeHandle, useLayoutEffect, useRef, useSyncExternalStore } from 'react'
-import { cx } from '../common/props'
-import type { BasaltProps, SlotStylesProps } from '../common/props'
-import { readPersistedValue } from '../state'
-import { VX } from '../tokens'
+import { useImperativeHandle, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+import { cx } from '../../common/props'
+import type { BasaltProps, SlotStylesProps } from '../../common/props'
+import { readPersistedValue } from '../../state/persisted'
+import { VX } from '../../tokens'
 import { useKeyboardInsetRef } from './use-keyboard-inset'
 
 /** A minimal, dependency-free send-arrow glyph (icons are passed in as ReactNode elsewhere; this
@@ -275,7 +275,7 @@ export type ComposerSlot = 'root' | 'input' | 'actions'
 export type ComposerProps = BasaltProps &
   SlotStylesProps<ComposerSlot> & {
     /** Imperative write/focus handle — see `ComposerHandle`. */
-    readonly ref?: Ref<ComposerHandle>
+    readonly ref?: Ref<ComposerHandle> | undefined
     /**
      * Called with the trimmed text plus the pending attachments. May return `void` (fire-and-forget,
      * validated only synchronously) or a `Promise<void>` (its outcome is awaited, its timing is not).
@@ -298,41 +298,41 @@ export type ComposerProps = BasaltProps &
      * A resolved promise clears and stays cleared, same as a `void` return.
      */
     readonly onSubmit: (payload: ComposerSubmit) => void | Promise<void>
-    readonly placeholder?: string
+    readonly placeholder?: string | undefined
     /** Autofocuses the textarea on mount. */
-    readonly autoFocus?: boolean
+    readonly autoFocus?: boolean | undefined
     /** Autosize ceiling for the textarea. Default 6. */
-    readonly maxRows?: number
+    readonly maxRows?: number | undefined
     /** Hard-disable, independent of streaming (e.g. offline). */
-    readonly disabled?: boolean
+    readonly disabled?: boolean | undefined
     /** A run is in flight on this thread. */
-    readonly streaming?: boolean
+    readonly streaming?: boolean | undefined
     /** Default false — preserves the historical `disabled={streaming}` behaviour. */
-    readonly allowSubmitWhileStreaming?: boolean
+    readonly allowSubmitWhileStreaming?: boolean | undefined
     /** When given, the send action becomes a Stop action while `streaming`. */
-    readonly onStop?: () => void
+    readonly onStop?: (() => void) | undefined
     /**
      * Opaque slot rendered before the textarea (a voice recorder, a mode switch, …). Slot content
      * that needs to WRITE into the composer — append a transcript, insert a suggestion — does so
      * through the `ref` handle (`ComposerHandle`), not a callback prop here; see the file's
      * `@example`.
      */
-    readonly leftSection?: ReactNode
+    readonly leftSection?: ReactNode | undefined
     /** Opaque slot rendered between the textarea and the send action (an attach button, …). */
-    readonly rightSection?: ReactNode
+    readonly rightSection?: ReactNode | undefined
     /**
      * Pending attachments, owned by the caller. Composer only forwards them on submit and asks for a
      * reset afterwards — rendering previews is the caller's job, via `leftSection`/`rightSection`.
      */
-    readonly attachments?: readonly ComposerAttachment[]
+    readonly attachments?: readonly ComposerAttachment[] | undefined
     /**
      * Called with `[]` optimistically the instant a submit goes out WITH pending attachments — a
      * submit that had none to begin with skips the call rather than reporting a no-op change — and,
      * subject to the restoration guards documented on `onSubmit`, with the original attachments
      * again if that submit later rejects.
      */
-    readonly onAttachmentsChange?: (next: readonly ComposerAttachment[]) => void
-    readonly onPaste?: (event: ClipboardEvent<HTMLTextAreaElement>) => void
+    readonly onAttachmentsChange?: ((next: readonly ComposerAttachment[]) => void) | undefined
+    readonly onPaste?: ((event: ClipboardEvent<HTMLTextAreaElement>) => void) | undefined
     /**
      * Persists the unsent draft under `basalt:composer-draft:<key>`; switching keys swaps drafts, and
      * the entry is removed (not blanked) on a successful submit.
@@ -341,9 +341,9 @@ export type ComposerProps = BasaltProps &
      * that fails, synchronously or later over the network, restores this persisted draft instead of
      * leaving it erased (subject to the restoration guards documented on `onSubmit`).
      */
-    readonly draftKey?: string
+    readonly draftKey?: string | undefined
     /** Replaces the whole Enter/Shift+Enter hint row. Pass `null` to drop it entirely. */
-    readonly hint?: ReactNode
+    readonly hint?: ReactNode | undefined
   }
 
 /** The default footer: the Enter / Shift+Enter keyboard contract, in the mono micro-label voice. */
@@ -395,11 +395,9 @@ export function Composer({
   classNames,
 }: ComposerProps): JSX.Element {
   // Per-instance fallback for the un-keyed case, so two keyless Composers never share a draft.
-  // A lazily-initialised ref rather than `useState` — this is a create-once value React never
-  // needs to re-render on; the store's own subscription is what drives updates.
-  const memoryStore = useRef<DraftStore | null>(null)
-  memoryStore.current ??= createDraftStore(null)
-  const store = draftKey === undefined ? memoryStore.current : persistedDraftStore(draftKey)
+  // Create-once state React never re-renders on; the store's own subscription drives updates.
+  const memoryStore = useMemo<DraftStore>(() => createDraftStore(null), [])
+  const store = draftKey === undefined ? memoryStore : persistedDraftStore(draftKey)
   const value = useSyncExternalStore(
     isServer ? noopSubscribe : store.subscribe,
     isServer ? emptyDraft : store.get,
@@ -418,14 +416,15 @@ export function Composer({
   // An attachment with no caption is a legitimate send; text-only callers behave exactly as before.
   const hasPayload = trimmed.length > 0 || pending.length > 0
 
-  // "Latest ref" mirrors of two controlled inputs, kept live every render (plain overwrites, not
-  // derived — safe to do in the render body) so a submit's rejection handler — which fires long
+  // "Latest ref" mirrors of two controlled inputs, refreshed after every commit so a submit's rejection handler — which fires long
   // after the render that started it — can read what is CURRENTLY true rather than what was true
   // when it was created. Both feed the restoration guards in `submit()` below.
   const attachmentsRef = useRef(pending)
-  attachmentsRef.current = pending
   const draftKeyRef = useRef(draftKey)
-  draftKeyRef.current = draftKey
+  useLayoutEffect(() => {
+    attachmentsRef.current = pending
+    draftKeyRef.current = draftKey
+  })
 
   // ── Imperative handle (ComposerHandle) ────────────────────────────────────────
   //

package/src/{agent-chat → agent/chat}/message-affordances.ts

@@ -10,14 +10,15 @@
  * stays internal — resolving unset fields is the components' job, not the consumer's.
  */
 import type { ReactNode } from 'react'
-import type { ChatMessage, TranscriptPart } from '../agent'
+import type { ChatMessage } from '../history'
+import type { TranscriptPart } from '../foreign'
 
 export type MessageAffordances = {
   /**
    * How the per-message timestamp renders.
    * @default 'relative'
    */
-  readonly timestamp?: 'relative' | 'absolute' | 'none'
+  readonly timestamp?: 'relative' | 'absolute' | 'none' | undefined
   /**
    * Whether a copy action is offered on the hover row. Copies the message's COALESCED text (the
    * same merged/de-duplicated text `coalesceParts` produces for display), not the raw `parts`
@@ -26,7 +27,7 @@ export type MessageAffordances = {
    * assembled.
    * @default true
    */
-  readonly copy?: boolean
+  readonly copy?: boolean | undefined
   /**
    * Regenerate action, shown on the LAST ASSISTANT message only (never on earlier turns, never on
    * user messages). Receives that message's `id`. `useAgentThreadRuns`'s `retry` is
@@ -34,7 +35,7 @@ export type MessageAffordances = {
    * whole thread — the consumer bridges this messageId-keyed callback to that thread-keyed retry;
    * the framework only ever hands back the messageId, it does not know about threads.
    */
-  readonly onRegenerate?: (messageId: string) => void
+  readonly onRegenerate?: ((messageId: string) => void) | undefined
   /**
    * Extra actions appended to the hover row, after the built-in copy/regenerate actions.
    *
@@ -48,7 +49,9 @@ export type MessageAffordances = {
    * a long thread it is worth avoiding: wrap `actions` in the consumer's own `useCallback`, keyed
    * on whatever state it actually reads.
    */
-  readonly actions?: (ctx: { readonly message: ChatMessage<TranscriptPart> }) => ReactNode
+  readonly actions?:
+    | ((ctx: { readonly message: ChatMessage<TranscriptPart> }) => ReactNode)
+    | undefined
 }
 
 /**

package/src/{agent-chat → agent/chat}/thread-feed-row.tsx

@@ -35,20 +35,15 @@
 import { Box, Group, Stack, Text, UnstyledButton } from '@mantine/core'
 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, SlotStylesProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import { VX } from '../tokens'
+import { isLiveStatus } from '../thread'
+import type { AgentThread, StreamStatus } from '../thread'
+import type { ChatMessage } from '../history'
+import type { ForeignPart, PartRenderer, PartRenderers, TranscriptPart } from '../foreign'
+import { BasaltStickToBottom } from '../stick-to-bottom'
+import { cx } 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'
 import { Composer } from './composer'
 import type { MessageAffordances } from './message-affordances'
@@ -115,48 +110,48 @@ type ThreadFeedRowBase = {
    * and never guessed client-side), pass it directly instead of forcing an outcome shape onto data
    * that never had one.
    */
-  readonly title?: string
+  readonly title?: string | undefined
   /** Header summary override, same fallback rule as `title` (`thread.outcome?.summary ?? ''`). */
-  readonly summary?: string
+  readonly summary?: string | undefined
   /** 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
+  readonly headerLeft?: ReactNode | undefined
   /** 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
+  readonly headerRight?: ReactNode | undefined
   /**
    * 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>[]
+  readonly messages?: readonly ChatMessage<TranscriptPart>[] | undefined
   /** The live (in-flight) assistant turn's parts, when a run is streaming for this thread. */
-  readonly liveParts?: readonly TranscriptPart[]
+  readonly liveParts?: readonly TranscriptPart[] | undefined
   /** The live run's status — drives the in-progress indicator on the live block. */
-  readonly liveStatus?: StreamStatus
+  readonly liveStatus?: StreamStatus | undefined
   /** Consumer renderers keyed by part.type, forwarded to `ThreadTranscript`. */
-  readonly renderers?: PartRenderers
+  readonly renderers?: PartRenderers | undefined
   /** Forwarded to `ThreadTranscript` — see its own prop doc. */
-  readonly fallbackRenderer?: PartRenderer<ForeignPart>
+  readonly fallbackRenderer?: PartRenderer<ForeignPart> | undefined
   /**
    * Per-message hover-row contract (timestamp/copy/regenerate/actions), forwarded verbatim to the
    * row's `ThreadTranscript`. Shared with it via `message-affordances.ts` so the two cannot drift
    * on what an unset field means.
    */
-  readonly affordances?: MessageAffordances
+  readonly affordances?: MessageAffordances | undefined
   /** Forwarded to `ThreadTranscript` — suppresses role label + chrome on same-speaker runs.
    * @default true */
-  readonly groupConsecutive?: boolean
+  readonly groupConsecutive?: boolean | undefined
   /** Called with the composer's submit payload. */
   readonly onSend: (payload: ComposerSubmit) => void
-  /** Shown as the composer's Stop action while `liveStatus === 'streaming'`. */
-  readonly onStop?: () => void
+  /** Shown as the composer's Stop action while `liveStatus` is `'submitted'` or `'streaming'`. */
+  readonly onStop?: (() => void) | undefined
   /** Forwarded to the row's `Composer`, minus the three props this component always wires itself
    * (`onSubmit`, `onStop`, and `streaming` — the last derived from `liveStatus` so a consumer can't
    * pass one that disagrees with the row's own live status). */
-  readonly composerProps?: Omit<ComposerProps, 'onSubmit' | 'onStop' | 'streaming'>
+  readonly composerProps?: Omit<ComposerProps, 'onSubmit' | 'onStop' | 'streaming'> | undefined
 }
 
 /**
@@ -254,17 +249,17 @@ export function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element {
   // textarea when it is TOLD a run is streaming (`composer.tsx`'s `showStop`/`inputDisabled`) — it
   // has no way to infer that from `onStop` alone. Forwarding `onStop` without this was the defect:
   // Stop never rendered and a second turn could still be typed into a live thread.
-  const streaming = liveStatus === 'streaming'
+  const streaming = isLiveStatus(liveStatus)
 
   const transcript = (
     <ThreadTranscript
       messages={transcriptMessages}
-      {...(liveParts !== undefined ? { liveParts } : {})}
-      {...(liveStatus !== undefined ? { liveStatus } : {})}
-      {...(renderers !== undefined ? { renderers } : {})}
-      {...(fallbackRenderer !== undefined ? { fallbackRenderer } : {})}
-      {...(affordances !== undefined ? { affordances } : {})}
-      {...(groupConsecutive !== undefined ? { groupConsecutive } : {})}
+      liveParts={liveParts}
+      liveStatus={liveStatus}
+      renderers={renderers}
+      fallbackRenderer={fallbackRenderer}
+      affordances={affordances}
+      groupConsecutive={groupConsecutive}
       {...virtualizeProps}
     />
   )

package/src/{agent-chat → agent/chat}/thread-feed.tsx

@@ -19,15 +19,15 @@
  */
 import { Box, ScrollArea, Stack } from '@mantine/core'
 import { useReducedMotion } from '@mantine/hooks'
-import { AnimatePresence, motion } from 'motion/react'
+import { AnimatePresence, MotionConfig, motion } from 'motion/react'
 import type { JSX, ReactNode } from 'react'
-import { useEffect, useState } from 'react'
-import type { AgentThread } from '../agent'
-import { BasaltStickToBottom } from '../agent'
-import { cx } from '../common/props'
-import type { BasaltProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import { MOTION_SPRING } from '../common/motion'
+import { useState } from 'react'
+import type { AgentThread } from '../thread'
+import { BasaltStickToBottom } from '../stick-to-bottom'
+import { cx } from '../../common/props'
+import type { BasaltProps } from '../../common/props'
+import { assertRequiredProps } from '../../common/validate'
+import { MOTION_SPRING } from '../../common/motion'
 import type { ComposerSubmit } from './composer'
 import { ThreadFeedRow } from './thread-feed-row'
 import { ThreadOutcomeCard } from './thread-outcome-card'
@@ -54,22 +54,22 @@ export type ThreadFeedProps = BasaltProps & {
    * directly (the previous shape) meant a plain `onSelect={setActiveId}` consumer could never
    * collapse a row, since re-selecting the same id is a no-op state update. Collapsing here is
    * local, UI-only state, reset whenever `activeId` changes to point at a DIFFERENT thread. Since
-   * this reset is a `useEffect` keyed on `activeId`, re-driving it to the SAME id from outside
-   * this component is a no-op React dep comparison, so it does not clear the override.
+   * this reset compares `activeId` against the last one seen, re-driving it to the SAME id from outside
+   * this component is a no-op comparison, so it does not clear the override.
    */
-  readonly variant?: 'outcome' | 'inline'
+  readonly variant?: 'outcome' | 'inline' | undefined
   /**
    * Wires the built-in `'inline'` row's composer to a real send channel — called with the thread
    * and the composer's submit payload. Omit it and the row's composer renders disabled (visibly
    * inert) instead of a live control that silently discards whatever is typed into it; a consumer
    * that needs the composer live must supply this (or `renderRow`, for full control over the row).
    */
-  readonly onSend?: (thread: AgentThread, payload: ComposerSubmit) => void
+  readonly onSend?: ((thread: AgentThread, payload: ComposerSubmit) => void) | undefined
   /** Overrides row rendering entirely, for BOTH variants — when supplied, this is called for every
    * thread instead of either built-in row. Gives full control over live-run wiring
    * (`onStop`/`liveParts`/`liveStatus`) the built-in `'inline'` row doesn't expose; see `variant`
    * and `onSend`. */
-  readonly renderRow?: (thread: AgentThread) => ReactNode
+  readonly renderRow?: ((thread: AgentThread) => ReactNode) | undefined
   /**
    * Scroll anchor. `'start'` (default) is today's top-anchored `ScrollArea` feed, unchanged.
    * `'end'` anchors the feed's growth to the BOTTOM instead — a `BasaltStickToBottom` scroll node
@@ -79,7 +79,7 @@ export type ThreadFeedProps = BasaltProps & {
    * (argo's hermes-chat S15 — oldest→newest top→bottom, pinned last, `renderRow`-driven) needs
    * instead of hand-rolling its own scroll shell around `renderRow`.
    */
-  readonly anchor?: 'start' | 'end'
+  readonly anchor?: 'start' | 'end' | undefined
 }
 
 function defaultRow(
@@ -138,14 +138,16 @@ export function ThreadFeed({
   // meaningful for the id it names; a stale value left over for a since-deselected thread is inert
   // (the per-row `expanded` check below always requires `thread.id === activeId` too).
   const [collapsedId, setCollapsedId] = useState<string | null>(null)
-  // Any externally-driven move of `activeId` to a DIFFERENT thread clears a stale override. React
-  // bails on a same-value dep, so re-driving `activeId` to the id it already holds (e.g. the SAME
-  // thread re-selected after being manually collapsed) does NOT re-run this effect. A collapse
-  // triggered by this component's own header click does NOT touch `activeId` at all (see
-  // `handleInlineToggle`), so it does not re-trigger this effect either.
-  useEffect(() => {
+  // Any externally-driven move of `activeId` to a DIFFERENT thread clears a stale override, by
+  // comparing against the last `activeId` seen during render. Re-driving `activeId` to the id it
+  // already holds (e.g. the SAME thread re-selected after being manually collapsed) is no change, so
+  // it does not clear the override. A collapse triggered by this component's own header click does
+  // NOT touch `activeId` at all (see `handleInlineToggle`), so it does not clear it either.
+  const [seenActiveId, setSeenActiveId] = useState(activeId)
+  if (seenActiveId !== activeId) {
+    setSeenActiveId(activeId)
     setCollapsedId(null)
-  }, [activeId])
+  }
 
   function handleInlineToggle(id: string): void {
     const isOpen = id === activeId && id !== collapsedId
@@ -178,20 +180,23 @@ export function ThreadFeed({
     </Stack>
   ) : (
     <Stack gap="sm" p="sm" {...stackAnchorProps}>
-      <AnimatePresence mode="popLayout" initial={false}>
-        {threads.map((thread) => (
-          <motion.div
-            key={thread.id}
-            layout
-            initial={{ opacity: 0, y: -8 }}
-            animate={{ opacity: 1, y: 0 }}
-            exit={{ opacity: 0, scale: 0.97 }}
-            transition={MOTION_SPRING}
-          >
-            {rowFor(thread)}
-          </motion.div>
-        ))}
-      </AnimatePresence>
+      {/* V2-SPEC § 5: the OS setting also reaches `motion`'s own transforms. */}
+      <MotionConfig reducedMotion="user">
+        <AnimatePresence mode="popLayout" initial={false}>
+          {threads.map((thread) => (
+            <motion.div
+              key={thread.id}
+              layout
+              initial={{ opacity: 0, y: -8 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, scale: 0.97 }}
+              transition={MOTION_SPRING}
+            >
+              {rowFor(thread)}
+            </motion.div>
+          ))}
+        </AnimatePresence>
+      </MotionConfig>
     </Stack>
   )
 

package/src/{agent-chat → agent/chat}/thread-message.tsx

@@ -14,8 +14,8 @@
  *
  * <ThreadTranscript
  *   messages={thread.messages}
- *   liveParts={liveParts}
- *   liveStatus={runStatus}
+ *   liveParts={run?.parts}
+ *   liveStatus={run?.status}
  * />
  */
 import {
@@ -34,26 +34,26 @@ import { Fragment, lazy, memo, Suspense, useLayoutEffect, useMemo, useRef } from
 import type { JSX } from 'react'
 import type {
   AgentPart,
-  AgentPartRenderers,
-  ChatMessage,
   ErrorPart,
-  ForeignPart,
-  PartRenderer,
-  PartRenderers,
   ReasoningPart,
   SourcePart,
-  StreamStatus,
   TextPart,
   ToolCallPart,
-  TranscriptPart,
-} from '../agent'
-import { coalesceParts, narrowAgentPart, PartList } from '../agent'
-import { cx } from '../common/props'
-import type { BasaltProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import { Markdown } from '../content/markdown'
-import { CopyAction } from '../content/copy-action'
-import { VX } from '../tokens'
+} from '../parts'
+import type { AgentPartRenderers } from '../part-list'
+import type { ChatMessage } from '../history'
+import type { ForeignPart, PartRenderer, PartRenderers, TranscriptPart } from '../foreign'
+import { isLiveStatus } from '../thread'
+import type { StreamStatus } from '../thread'
+import { coalesceParts } from '../coalesce'
+import { narrowAgentPart } from '../foreign'
+import { PartList } from '../part-list'
+import { cx } from '../../common/props'
+import type { BasaltProps } from '../../common/props'
+import { assertRequiredProps } from '../../common/validate'
+import { Markdown } from '../../content/markdown'
+import { CopyAction } from '../../content/copy-action'
+import { VX } from '../../tokens'
 import { DEFAULT_AFFORDANCES } from './message-affordances'
 import type { MessageAffordances } from './message-affordances'
 import { formatRelativeTime } from './relative-time'
@@ -394,23 +394,23 @@ const FINISH_INDICATOR: Partial<
 
 type MessageBlockProps = {
   readonly message: ChatMessage<TranscriptPart>
-  readonly streaming?: boolean
+  readonly streaming?: boolean | undefined
   readonly renderers: PartRenderers
   readonly fallbackRenderer: PartRenderer<ForeignPart>
   /** Suppresses the role label and surface chrome — this message continues the same speaker's
    * immediately-preceding turn within the grouping window (the Slack rhythm, AGENT-CHAT-SPEC.md
    * §_). Computed by `ThreadTranscript` (a property of the SEQUENCE, not of one message in
    * isolation) and passed down. @default false */
-  readonly grouped?: boolean
+  readonly grouped?: boolean | undefined
   /** Per-message hover-row affordances. `undefined` renders NO affordance row at all — this is how
    * `ThreadTranscript` opts the live/streaming message out (an epoch-0 `createdAt` and a
    * half-streamed coalesced text would otherwise render a nonsensical "56 years ago" timestamp and
    * a copy button that copies a fragment). Every settled message gets a resolved (defaults-merged)
    * object instead. */
-  readonly affordances?: MessageAffordances
+  readonly affordances?: MessageAffordances | undefined
   /** True only for the single most-recent SETTLED assistant message — the sole message
    * `affordances.onRegenerate` renders a control for. @default false */
-  readonly isLastAssistant?: boolean
+  readonly isLastAssistant?: boolean | undefined
 }
 
 /**
@@ -987,22 +987,22 @@ type ThreadTranscriptBase = BasaltProps & {
   /** Settled messages for the thread, oldest first. */
   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[]
+  readonly liveParts?: readonly TranscriptPart[] | undefined
   /** The live run's status — drives the in-progress indicator on the live block. */
-  readonly liveStatus?: StreamStatus
+  readonly liveStatus?: StreamStatus | undefined
   /** Consumer renderers keyed by part.type. Consulted BEFORE the built-in union. */
-  readonly renderers?: PartRenderers
+  readonly renderers?: PartRenderers | undefined
   /** Called for a part whose type is neither an AgentPart variant nor a registered key. Defaults
    * to a visible `UnknownPartChip` outside production, `null` in production — never throws. */
-  readonly fallbackRenderer?: PartRenderer<ForeignPart>
+  readonly fallbackRenderer?: PartRenderer<ForeignPart> | undefined
   /** Per-message hover-row affordances (timestamp/copy/regenerate/custom actions). Unset fields
    * fall back to `DEFAULT_AFFORDANCES`. Never shown on the live/streaming message — see
    * `MessageBlockProps.affordances`. */
-  readonly affordances?: MessageAffordances
+  readonly affordances?: MessageAffordances | undefined
   /** Suppresses the role label and surface chrome on a message whose predecessor shares its role
    * and landed within 5 minutes — the Slack rhythm.
    * @default true */
-  readonly groupConsecutive?: boolean
+  readonly groupConsecutive?: boolean | undefined
 }
 
 export type ThreadTranscriptProps = ThreadTranscriptBase & VirtualizeProps
@@ -1020,6 +1020,9 @@ export type ThreadTranscriptProps = ThreadTranscriptBase & VirtualizeProps
  * bail-out. Only a genuine defined-to-undefined (or back) transition changes the returned wrapper's
  * presence.
  *
+ * The ref is refreshed in a layout effect, so the guarantee covers invocations AFTER commit (a click,
+ * a timer) — never one made during render.
+ *
  * ONLY EVER APPLY THIS TO AN EVENT HANDLER — never to a render prop. The trick works precisely
  * because the wrapper is invoked AFTER render (from a click), so freezing its identity costs
  * nothing: React re-reads the ref at call time. A render prop (`MessageAffordances.actions`, which
@@ -1035,7 +1038,9 @@ function useStableCallback<Args extends unknown[], R>(
   callback: ((...args: Args) => R) | undefined,
 ): ((...args: Args) => R) | undefined {
   const callbackRef = useRef(callback)
-  callbackRef.current = callback
+  useLayoutEffect(() => {
+    callbackRef.current = callback
+  })
   // Deliberately empty deps: this is what keeps `stable`'s identity constant across renders. It
   // reads `callbackRef.current` at CALL time (not at creation time), so it always invokes whatever
   // the consumer most recently passed — never a closure captured at first mount.
@@ -1064,7 +1069,7 @@ function useStableCallback<Args extends unknown[], R>(
  *
  * @example
  * import { ThreadTranscript } from 'basalt-ui'
- * <ThreadTranscript messages={thread.messages} liveParts={liveParts} liveStatus={runStatus} />
+ * <ThreadTranscript messages={thread.messages} liveParts={run?.parts} liveStatus={run?.status} />
  *
  * @example
  * // Windowed, for a long thread:
@@ -1123,11 +1128,8 @@ export function ThreadTranscript(props: ThreadTranscriptProps): JSX.Element {
     () => ({
       timestamp: affordancesProp?.timestamp ?? DEFAULT_AFFORDANCES.timestamp,
       copy: affordancesProp?.copy ?? DEFAULT_AFFORDANCES.copy,
-      // `exactOptionalPropertyTypes` forbids assigning a possibly-`undefined` value to an optional
-      // property directly — spread each field in only when it is actually present, rather than
-      // widening `MessageAffordances` itself to accept an explicit `undefined`.
-      ...(stableOnRegenerate !== undefined && { onRegenerate: stableOnRegenerate }),
-      ...(actions !== undefined && { actions }),
+      onRegenerate: stableOnRegenerate,
+      actions,
     }),
     [affordancesProp?.timestamp, affordancesProp?.copy, stableOnRegenerate, actions],
   )
@@ -1176,7 +1178,7 @@ export function ThreadTranscript(props: ThreadTranscriptProps): JSX.Element {
         <div aria-live="polite" aria-atomic="false" aria-relevant="additions">
           <MessageBlock
             message={liveMessage}
-            streaming={liveStatus === 'streaming'}
+            streaming={isLiveStatus(liveStatus)}
             renderers={renderers}
             fallbackRenderer={fallbackRenderer}
           />

package/src/{agent-chat → agent/chat}/thread-outcome-card.tsx

@@ -21,11 +21,11 @@
 import { Badge, Group, Skeleton, Stack, Text, UnstyledButton } from '@mantine/core'
 import { useHover } from '@mantine/hooks'
 import type { JSX } from 'react'
-import type { AgentThread, ThreadStatus } from '../agent'
-import { assertRequiredProps } from '../common/validate'
-import { cx } from '../common/props'
-import type { BasaltProps } from '../common/props'
-import { alpha, VX } from '../tokens'
+import type { AgentThread, ThreadStatus } from '../thread'
+import { assertRequiredProps } from '../../common/validate'
+import { cx } from '../../common/props'
+import type { BasaltProps } from '../../common/props'
+import { alpha, VX } from '../../tokens'
 import { formatRelativeTime } from './relative-time'
 
 // ── Status badge — shown ONLY for states that need a glance (attention/error). ────