basalt-ui 1.27.0 → 1.29.0

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,6 +38,7 @@
  * <PartList parts={coalesceParts(parts)} />
  */
 import type { AgentPart, ReasoningPart, TextPart, ToolCallPart } from './parts'
+import { isDev } from '../common/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 
@@ -169,7 +170,7 @@ function mergeToolPart(existing: ToolCallPart, next: ToolCallPart): ToolCallPart
       // and make every field read below a compile error, so the assertion is what makes the
       // runtime value usable. It asserts nothing tsc has not already proved on the line above.
       const fallback = unhandled as ToolCallPart
-      if (process.env['NODE_ENV'] !== 'production') {
+      if (isDev()) {
         console.warn(
           `[basalt] coalesceParts: unrecognized tool state ${JSON.stringify(fallback.state)} — kept, merged best-effort`,
         )

package/src/agent/merge.ts

@@ -29,6 +29,7 @@
  * // parts === [{ id: 'p1', type: 'text', text: 'Hello' }]
  */
 import type { ReasoningPart, TextPart } from './parts'
+import { isDev } from '../common/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 
@@ -78,7 +79,7 @@ function clampOffset(offset: number, length: number): number {
   // A non-finite offset would make every slice() return '' and blank the part outright — it is
   // out of range like any other, and appending is the safe reading of "position unknown".
   const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length
-  if (clamped !== offset && process.env['NODE_ENV'] !== 'production') {
+  if (clamped !== offset && isDev()) {
     console.warn(
       `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] — clamped to ${clamped}`,
     )

package/src/agent/part-list.tsx

@@ -27,6 +27,7 @@
  */
 import { Fragment, useMemo } from 'react'
 import type { JSX } from 'react'
+import { assertRequiredProps } from '../common/validate'
 import { assertNever } from '../register'
 import { alpha, VX } from '../tokens'
 import type {
@@ -285,6 +286,7 @@ export function PartList<TPart extends AgentPart = AgentPart>({
   components,
   settled = true,
 }: PartListProps<TPart>): JSX.Element {
+  assertRequiredProps('PartList', { parts }, ['parts'])
   // Memoised to avoid rebuilding the renderer map on every streaming re-render (hot path).
   // Cast required because DEFAULT_RENDERERS is typed for the base AgentPart, not the generic TPart.
   const renderers = useMemo(

package/src/agent/stick-to-bottom.tsx

@@ -26,14 +26,13 @@
  */
 import { lazy, Suspense } from 'react'
 import type { CSSProperties, JSX, ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
 import { VX } from '../tokens'
 
 // ── Lazy-loaded StickToBottom ─────────────────────────────────────────────────
 
-type WrapperProps = {
+type WrapperProps = BasaltProps & {
   children: ReactNode
-  className?: string
-  style?: CSSProperties
 }
 
 /** Plain scrollable container rendered when use-stick-to-bottom peer is absent. */
@@ -110,15 +109,12 @@ const LazyStickToBottom = lazy(() =>
     })
     .catch(() => ({ default: PlainContainerFallback })),
 )
+Object.assign(LazyStickToBottom, { displayName: 'LazyStickToBottom' })
 
 // ── BasaltStickToBottom ───────────────────────────────────────────────────────
 
-export type BasaltStickToBottomProps = {
+export type BasaltStickToBottomProps = BasaltProps & {
   readonly children: ReactNode
-  /** Applied to the scroll content container. */
-  readonly className?: string
-  /** Applied to the outer StickToBottom element. */
-  readonly style?: CSSProperties
 }
 
 /**
@@ -143,9 +139,11 @@ export function BasaltStickToBottom({
   if (className !== undefined) fallbackProps.className = className
   if (style !== undefined) fallbackProps.style = style
 
-  const lazyProps: WrapperProps = { children }
-  if (className !== undefined) lazyProps.className = className
-  if (style !== undefined) lazyProps.style = style
+  const lazyProps: WrapperProps = {
+    children,
+    ...(className !== undefined && { className }),
+    ...(style !== undefined && { style }),
+  }
 
   return (
     <Suspense fallback={<div {...fallbackProps}>{children}</div>}>

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/composer.tsx

@@ -39,6 +39,8 @@
 import { ActionIcon, 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'
 
@@ -257,78 +259,83 @@ function liveSelection(el: HTMLTextAreaElement): { start: number; end: number }
   return { start: selectionStart, end: selectionEnd }
 }
 
-export type ComposerProps = {
-  /** Imperative write/focus handle — see `ComposerHandle`. */
-  readonly ref?: Ref<ComposerHandle>
-  /**
-   * 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).
-   *
-   * The draft and attachments clear OPTIMISTICALLY, immediately, before this settles — a chat
-   * composer has to feel instant, so Composer never sits on the typed text for a round trip.
-   * Rejecting restores them instead:
-   *   - THROW synchronously to refuse a send outright (bad input, offline, …) — the clear never
-   *     runs, exactly as before this prop went async.
-   *   - Return a promise that REJECTS to report a failure discovered later (a network error) — the
-   *     text and attachments are put back, UNLESS something has since made that unsafe:
-   *       - the user already typed something new into the (now-empty) box — their new text wins;
-   *         the failed one is not restored (surface a retry via the failed message instead);
-   *       - a LATER submit has already gone through this same draft — that one's own optimistic
-   *         clear (whether it went on to succeed or fail) wins over restoring this older one;
-   *       - the attachments are no longer empty (the caller already put something else there), or
-   *         `draftKey` has since changed (this Composer now points at a different thread/consumer
-   *         destination) — either way the attachments are left as they are rather than risking a
-   *         leak into whatever is current now.
-   * A resolved promise clears and stays cleared, same as a `void` return.
-   */
-  readonly onSubmit: (payload: ComposerSubmit) => void | Promise<void>
-  readonly placeholder?: string
-  /** Autofocuses the textarea on mount. */
-  readonly autoFocus?: boolean
-  /** Autosize ceiling for the textarea. Default 6. */
-  readonly maxRows?: number
-  /** Hard-disable, independent of streaming (e.g. offline). */
-  readonly disabled?: boolean
-  /** A run is in flight on this thread. */
-  readonly streaming?: boolean
-  /** Default false — preserves the historical `disabled={streaming}` behaviour. */
-  readonly allowSubmitWhileStreaming?: boolean
-  /** When given, the send action becomes a Stop action while `streaming`. */
-  readonly onStop?: () => void
-  /**
-   * 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
-  /** Opaque slot rendered between the textarea and the send action (an attach button, …). */
-  readonly rightSection?: ReactNode
-  /**
-   * 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[]
-  /**
-   * 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
-  /**
-   * Persists the unsent draft under `basalt:composer-draft:<key>`; switching keys swaps drafts, and
-   * the entry is removed (not blanked) on a successful submit.
-   *
-   * "Successful" means `onSubmit` returned (or resolved) without throwing or rejecting — a send
-   * 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
-  /** Replaces the whole Enter/Shift+Enter hint row. Pass `null` to drop it entirely. */
-  readonly hint?: ReactNode
-}
+/** The three boxes `Composer` paints: `root` is the outer stack, `input` is the `Textarea`,
+ * `actions` is the Stop/Send action-button group. */
+export type ComposerSlot = 'root' | 'input' | 'actions'
+
+export type ComposerProps = BasaltProps &
+  SlotStylesProps<ComposerSlot> & {
+    /** Imperative write/focus handle — see `ComposerHandle`. */
+    readonly ref?: Ref<ComposerHandle>
+    /**
+     * 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).
+     *
+     * The draft and attachments clear OPTIMISTICALLY, immediately, before this settles — a chat
+     * composer has to feel instant, so Composer never sits on the typed text for a round trip.
+     * Rejecting restores them instead:
+     *   - THROW synchronously to refuse a send outright (bad input, offline, …) — the clear never
+     *     runs, exactly as before this prop went async.
+     *   - Return a promise that REJECTS to report a failure discovered later (a network error) — the
+     *     text and attachments are put back, UNLESS something has since made that unsafe:
+     *       - the user already typed something new into the (now-empty) box — their new text wins;
+     *         the failed one is not restored (surface a retry via the failed message instead);
+     *       - a LATER submit has already gone through this same draft — that one's own optimistic
+     *         clear (whether it went on to succeed or fail) wins over restoring this older one;
+     *       - the attachments are no longer empty (the caller already put something else there), or
+     *         `draftKey` has since changed (this Composer now points at a different thread/consumer
+     *         destination) — either way the attachments are left as they are rather than risking a
+     *         leak into whatever is current now.
+     * A resolved promise clears and stays cleared, same as a `void` return.
+     */
+    readonly onSubmit: (payload: ComposerSubmit) => void | Promise<void>
+    readonly placeholder?: string
+    /** Autofocuses the textarea on mount. */
+    readonly autoFocus?: boolean
+    /** Autosize ceiling for the textarea. Default 6. */
+    readonly maxRows?: number
+    /** Hard-disable, independent of streaming (e.g. offline). */
+    readonly disabled?: boolean
+    /** A run is in flight on this thread. */
+    readonly streaming?: boolean
+    /** Default false — preserves the historical `disabled={streaming}` behaviour. */
+    readonly allowSubmitWhileStreaming?: boolean
+    /** When given, the send action becomes a Stop action while `streaming`. */
+    readonly onStop?: () => void
+    /**
+     * 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
+    /** Opaque slot rendered between the textarea and the send action (an attach button, …). */
+    readonly rightSection?: ReactNode
+    /**
+     * 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[]
+    /**
+     * 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
+    /**
+     * Persists the unsent draft under `basalt:composer-draft:<key>`; switching keys swaps drafts, and
+     * the entry is removed (not blanked) on a successful submit.
+     *
+     * "Successful" means `onSubmit` returned (or resolved) without throwing or rejecting — a send
+     * 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
+    /** Replaces the whole Enter/Shift+Enter hint row. Pass `null` to drop it entirely. */
+    readonly hint?: ReactNode
+  }
 
 /** The default footer: the Enter / Shift+Enter keyboard contract, in the mono micro-label voice. */
 function DefaultHint(): JSX.Element {
@@ -374,6 +381,9 @@ export function Composer({
   onPaste,
   draftKey,
   hint,
+  className,
+  style,
+  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
@@ -557,43 +567,54 @@ export function Composer({
   if (placeholder !== undefined) textareaProps.placeholder = placeholder
   if (autoFocus !== undefined) textareaProps.autoFocus = autoFocus
   if (onPaste !== undefined) textareaProps.onPaste = onPaste
+  if (classNames?.input !== undefined) textareaProps.className = cx(classNames.input)
+
+  const showActions = showStop || showSend
 
   return (
-    <Stack gap={6}>
+    <Stack
+      gap={6}
+      className={cx(classNames?.root, className)}
+      {...(style !== undefined && { style })}
+    >
       <Group gap="xs" align="flex-end" wrap="nowrap">
         {leftSection}
         <Textarea {...textareaProps} ref={textareaRef} />
         {rightSection}
-        {showStop ? (
-          <ActionIcon
-            size={42}
-            radius="md"
-            variant="filled"
-            color="red"
-            onClick={onStop}
-            aria-label="Stop generating"
-          >
-            <StopGlyph />
-          </ActionIcon>
-        ) : null}
-        {showSend ? (
-          <ActionIcon
-            size={42}
-            radius="md"
-            variant="filled"
-            onClick={submit}
-            disabled={inputDisabled || !hasPayload}
-            aria-label="Send message"
-            // Send action (docs/DESIGN-SPEC.md §5): the one accent-filled control. It needs no color
-            // override — `filled` resolves through the theme to `--vx-accent-fill` / `--vx-on-accent`.
-            // (It used to hand-wire those two vars inline, which is why this was the ONLY filled
-            // control that stayed legible while the rest of the chrome went through Mantine's
-            // scheme-blind autoContrast. The theme owns it now, and hover works again — an inline
-            // style can't express a `:hover` state.)
-          >
-            <SendGlyph />
-          </ActionIcon>
-        ) : null}
+        {showActions && (
+          <Group gap="xs" wrap="nowrap" className={cx(classNames?.actions)}>
+            {showStop ? (
+              <ActionIcon
+                size={42}
+                radius="md"
+                variant="filled"
+                color="red"
+                onClick={onStop}
+                aria-label="Stop generating"
+              >
+                <StopGlyph />
+              </ActionIcon>
+            ) : null}
+            {showSend ? (
+              <ActionIcon
+                size={42}
+                radius="md"
+                variant="filled"
+                onClick={submit}
+                disabled={inputDisabled || !hasPayload}
+                aria-label="Send message"
+                // Send action (docs/DESIGN-SPEC.md §5): the one accent-filled control. It needs no
+                // color override — `filled` resolves through the theme to `--vx-accent-fill` /
+                // `--vx-on-accent`. (It used to hand-wire those two vars inline, which is why this
+                // was the ONLY filled control that stayed legible while the rest of the chrome went
+                // through Mantine's scheme-blind autoContrast. The theme owns it now, and hover
+                // works again — an inline style can't express a `:hover` state.)
+              >
+                <SendGlyph />
+              </ActionIcon>
+            ) : null}
+          </Group>
+        )}
       </Group>
       {hint === undefined ? <DefaultHint /> : hint}
     </Stack>

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'