basalt-ui 1.41.0 → 2.0.1

package/src/{agent-chat → agent/chat}/tool-chip.tsx

@@ -8,7 +8,7 @@
  * validated, the error text, the denial reason, or the approve/deny affordances.
  *
  * @example
- * import { ToolChip } from 'basalt-ui/agent-chat'
+ * import { ToolChip } from 'basalt-ui/agent'
  *
  * <ToolChip
  *   part={part}
@@ -19,12 +19,12 @@
 import { Box, Button, Collapse, Group, Stack, Text, UnstyledButton } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
 import type { JSX } from 'react'
-import { isToolCallSettled } from '../agent'
-import type { ToolCallPart } from '../agent'
-import { cx } from '../common/props'
-import type { BasaltProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import { alpha, VX } from '../tokens'
+import { isToolCallSettled } from '../parts'
+import type { ToolCallPart } from '../parts'
+import { cx } from '../../common/props'
+import type { BasaltProps } from '../../common/props'
+import { assertRequiredProps } from '../../common/validate'
+import { alpha, VX } from '../../tokens'
 
 // Mirrors thread-message.tsx's micro-label/rail/code-block idiom (docs/DESIGN-SPEC.md §3/§5) —
 // duplicated locally rather than imported, matching the existing part-list.tsx/thread-message.tsx
@@ -81,8 +81,8 @@ function stateMeta(part: ToolCallPart): { readonly label: string; readonly dotTo
       // `part` is `never` here ONLY at compile time — this switch is genuinely exhaustive today,
       // so adding an eighth ToolCallPart state without a case above makes this assignment a tsc
       // error, the same gate `assertNever` provides. But `part` at RUNTIME can be a value this
-      // build never declared: `createThreadsStore` persists to localStorage with no shape
-      // validation, and `edenTransport` trusts the wire with zero validation, so a 1.10.0-shaped
+      // build never declared: a consumer-owned thread store may persist to localStorage with no
+      // shape validation, and a transport may carry wire data with zero validation, so a 1.10.0-shaped
       // flat tool part (`state` undefined) or a future/foreign `state` string both reach here.
       // That must never THROW during render — mirrors ThreadTranscript's fallbackRenderer
       // doctrine (unknown data renders inert, it doesn't blank the transcript) — so, unlike a
@@ -101,10 +101,10 @@ function formatDuration(ms: number): string {
 
 export type ToolChipProps = BasaltProps & {
   readonly part: ToolCallPart
-  readonly defaultExpanded?: boolean
+  readonly defaultExpanded?: boolean | undefined
   /** Rendered only in 'approval-requested'. Omit both to render a read-only chip. */
-  readonly onApprove?: (approvalId: string) => void
-  readonly onDeny?: (approvalId: string, reason?: string) => void
+  readonly onApprove?: ((approvalId: string) => void) | undefined
+  readonly onDeny?: ((approvalId: string, reason?: string) => void) | undefined
 }
 
 /**

package/src/{agent-chat → agent/chat}/use-keyboard-inset.ts

@@ -27,7 +27,7 @@
  * outside React state.
  */
 import { useCallback, useState } from 'react'
-import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
+import { useIsomorphicLayoutEffect } from '../../common/isomorphic-layout-effect'
 
 const KEYBOARD_INSET_VAR = '--vx-keyboard-inset'
 

package/src/{agent-chat → agent/chat}/virtualize.ts

@@ -88,13 +88,13 @@
 /** Tuning knobs passed through to `@tanstack/react-virtual`'s `useVirtualizer`. */
 export type VirtualizeOptions = {
   /** Extra rows rendered beyond the visible viewport, each side. Library default: 1. */
-  readonly overscan?: number
+  readonly overscan?: number | undefined
   /** Estimated row height in px, used before a row has been measured. */
-  readonly estimateSize?: number
+  readonly estimateSize?: number | undefined
   /** Where the transcript sits on first mount. Default 'end' — a chat transcript opens at the
       newest message. 'start' opens at the oldest. See this module's fourth composition rule
       above for the mechanism and why a consumer restoring its own scroll position wants 'start'. */
-  readonly initialScroll?: 'end' | 'start'
+  readonly initialScroll?: 'end' | 'start' | undefined
 }
 
 /**
@@ -103,7 +103,7 @@ export type VirtualizeOptions = {
  * scroll container, so there is no valid virtualized layout without one.
  */
 export type VirtualizeProps =
-  | { readonly virtualize?: false; readonly height?: never }
+  | { readonly virtualize?: false | undefined; readonly height?: undefined }
   | { readonly virtualize: true | VirtualizeOptions; readonly height: number | string }
 
 /** The enabled branch of {@link VirtualizeProps}, with `height` no longer optional. */
@@ -126,7 +126,7 @@ export type ResolvedVirtualize = {
  * transcript body with inner scroll, no `@tanstack/react-virtual` peer installed).
  */
 export type RowHeightProps =
-  | { readonly virtualize?: false; readonly height?: number | string }
+  | { readonly virtualize?: false | undefined; readonly height?: number | string | undefined }
   | { readonly virtualize: true | VirtualizeOptions; readonly height: number | string }
 
 /** The resolved shape of {@link RowHeightProps} — exactly one of the three row body layouts. */

package/src/agent/error.ts

@@ -0,0 +1,43 @@
+/**
+ * AgentError — the closed, serializable shape of a failed turn (V2-SPEC § 6).
+ *
+ * `useAgentThreadRuns({ onError })` keeps the raw thrown value; `ThreadRunState.error` and the
+ * `chat.turn` telemetry carry this union instead, so a consumer switches on `kind` rather than
+ * parsing an error body. Classification is duck-typed on purpose: this module must never resolve
+ * the optional `ai` peer at runtime.
+ */
+
+/**
+ * - `http`: the chat endpoint answered with a non-2xx `status` (AI SDK's `APICallError`).
+ * - `stream`: the UI-message stream was malformed (AI SDK's `UIMessageStreamError`).
+ * - `server`: an `error` chunk arrived mid-stream, or any other failure; `message` is the server's
+ *   `errorText` or the thrown error's message.
+ * - `aborted`: the request was aborted by something other than `stop()`.
+ */
+export type AgentError =
+  | { readonly kind: 'http'; readonly status: number }
+  | { readonly kind: 'stream'; readonly chunkType: string; readonly chunkId: string }
+  | { readonly kind: 'server'; readonly message: string }
+  | { readonly kind: 'aborted' }
+
+function stringField(value: unknown, key: string): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const field = (value as Record<string, unknown>)[key]
+  return typeof field === 'string' ? field : undefined
+}
+
+/** Maps whatever a transport threw onto the closed `AgentError` union. */
+export function toAgentError(error: unknown): AgentError {
+  // By name, not `instanceof Error`: a `fetch` abort is a DOMException, which is not an Error.
+  if (stringField(error, 'name') === 'AbortError') return { kind: 'aborted' }
+  const status =
+    typeof error === 'object' && error !== null
+      ? (error as Record<string, unknown>)['statusCode']
+      : undefined
+  if (typeof status === 'number') return { kind: 'http', status }
+  const chunkType = stringField(error, 'chunkType')
+  const chunkId = stringField(error, 'chunkId')
+  if (chunkType !== undefined && chunkId !== undefined)
+    return { kind: 'stream', chunkType, chunkId }
+  return { kind: 'server', message: stringField(error, 'message') ?? String(error) }
+}

package/src/agent/history.ts

@@ -1,27 +1,4 @@
-/**
- * createChatHistoryStore — persisted, ring-buffered chat history on createPersistedState.
- *
- * Returns a stable hook factory (call once per module per stable key) that provides the full
- * message history, an append function, and a clear function. Messages are trimmed to `max`
- * (default 100) via a ring-buffer strategy — oldest entries are dropped first.
- *
- * SSR-safe: the underlying createPersistedState handles the server snapshot (returns initial).
- * Cross-tab: the 'storage' event propagates changes to other tabs automatically.
- *
- * @example
- * import { createChatHistoryStore } from 'basalt-ui/agent'
- *
- * // Call once at module scope with a stable key:
- * const useChatHistory = createChatHistoryStore({ key: 'main-chat', version: 1 })
- *
- * // In a component:
- * function Chat() {
- *   const { messages, append, clear } = useChatHistory()
- *   // ...
- * }
- */
-import { useCallback, useRef } from 'react'
-import { createPersistedState } from '../state'
+/** ChatMessage — the typed message shape every thread carries. */
 import type { AgentPart } from './parts'
 
 // ── ChatMessage ───────────────────────────────────────────────────────────────
@@ -44,87 +21,5 @@ export type ChatMessage<TPart = AgentPart> = {
   readonly parts: TPart[]
   readonly createdAt: number
   /** How the turn ended. Absent on user messages and on pre-1.11 persisted assistant messages. */
-  readonly finish?: 'complete' | 'stopped' | 'error'
-}
-
-// ── createChatHistoryStore options ────────────────────────────────────────────
-
-export type ChatHistoryStoreOptions = {
-  /** localStorage key (namespaced as `basalt:<key>`). Stable — changes key lose history. */
-  readonly key: string
-  /** Envelope version. Increment when the ChatMessage shape changes to clear old data. */
-  readonly version: number
-  /**
-   * Maximum number of messages to retain. Oldest messages are dropped when exceeded.
-   * @default 100
-   */
-  readonly max?: number
-}
-
-// ── Return type of the factory hook ──────────────────────────────────────────
-
-export type ChatHistoryStore<TPart = AgentPart> = {
-  /** All retained messages, oldest first. */
-  readonly messages: ChatMessage<TPart>[]
-  /** Append a message. Trims to `max` if needed (ring-buffer: drops oldest). */
-  readonly append: (message: ChatMessage<TPart>) => void
-  /** Clear all messages. */
-  readonly clear: () => void
-}
-
-// ── createChatHistoryStore ────────────────────────────────────────────────────
-
-/**
- * Creates a stable persisted chat history hook for the given key + version.
- *
- * Call this ONCE per module (not inside a component). The returned hook can be called in any
- * component that needs access to the same history. All instances sharing the same key stay
- * in sync across tabs via the 'storage' event.
- *
- * @example
- * // src/chat/history.ts — ONE stable creation per key:
- * export const useChatHistory = createChatHistoryStore({ key: 'main-chat', version: 1 })
- *
- * // In a component:
- * const { messages, append, clear } = useChatHistory()
- * append({ id: crypto.randomUUID(), role: 'user', parts: [...], createdAt: Date.now() })
- */
-export function createChatHistoryStore<TPart = AgentPart>(
-  opts: ChatHistoryStoreOptions,
-): () => ChatHistoryStore<TPart> {
-  const max = opts.max ?? 100
-
-  const usePersistedMessages = createPersistedState<ChatMessage<TPart>[]>({
-    key: opts.key,
-    version: opts.version,
-    initial: [],
-  })
-
-  return function useChatHistoryStore(): ChatHistoryStore<TPart> {
-    const [messages, setMessages] = usePersistedMessages()
-
-    // Ref mirrors the latest committed value so that two synchronous append() calls in one
-    // render cycle accumulate correctly. createPersistedState's setter is a whole-value setter
-    // (not a functional updater), so the second call would otherwise overwrite the first.
-    const ref = useRef(messages)
-    ref.current = messages
-
-    const append = useCallback(
-      (message: ChatMessage<TPart>): void => {
-        const next = [...ref.current, message]
-        // Ring-buffer: trim to max, dropping oldest entries first.
-        const trimmed = next.length > max ? next.slice(next.length - max) : next
-        ref.current = trimmed // sync so a second append in the same tick sees the update
-        setMessages(trimmed)
-      },
-      [setMessages],
-    )
-
-    const clear = useCallback((): void => {
-      ref.current = []
-      setMessages([])
-    }, [setMessages])
-
-    return { messages, append, clear }
-  }
+  readonly finish?: 'complete' | 'stopped' | 'error' | undefined
 }

package/src/agent/id.ts

@@ -1,9 +1,8 @@
 /**
  * Id-minting helpers shared across the agent layer: `mintThreadId` (a low-stakes client-side id —
- * threads, run/chat namespaces — used by `./thread`'s `createThreadsStore`, `./adapter`'s
- * `createAdapterThreadsStore`/`threadsStoreAdapterContract`, `./use-agent-stream`'s per-send run
- * id, and `aiSdkTransport`'s fixed chat id), `mintMessageId` (the higher-stakes id `appendMessage`
- * treats as its only idempotency key), and `withPartIds` (stamps sequence ids onto streamed
+ * threads, run/chat namespaces — used by `useAgentThreadRuns`'s per-send run id and
+ * `aiSdkTransport`'s fixed chat id; the thread store itself is consumer-owned), `mintMessageId`
+ * (the higher-stakes id `appendMessage` treats as its only idempotency key), and `withPartIds` (stamps sequence ids onto streamed
  * parts). Grouped here because they're the id-minting leaves every store/hook/transport in this
  * layer sits above — not because they share a mechanism (`mintMessageId` deliberately diverges
  * from `mintThreadId` on rung 3; see its own doc).
@@ -145,7 +144,7 @@ export function mintMessageId(): string {
  *   // part.id is always defined here
  * }
  */
-export async function* withPartIds<TPart extends { id?: string }>(
+export async function* withPartIds<TPart extends { id?: string | undefined }>(
   runId: string,
   source: AsyncGenerator<TPart>,
 ): AsyncGenerator<TPart & { id: string }> {

package/src/agent/index.ts

@@ -1,123 +1,34 @@
 /**
- * basalt-ui/agent — headless, Mantine-free streaming-chat layer over an injected transport seam.
- *
- * `aiSdkTransport` (backed by the `ai` npm package) is the RECOMMENDED DEFAULT transport for LLM
- * chat use cases; `edenTransport` remains the zero-extra-dependency alternative. Optional peers
- * (ai, use-stick-to-bottom) are all lazily loaded — importing this module does NOT eagerly resolve
- * either of them. This module ships no markdown renderer — `agent/** -> content` is lint-blocked
- * by design, so `PartList` takes a consumer-supplied `components.text`; basalt's own is
- * `basalt-ui/content`'s `Markdown`.
- *
- * Install optional peers:
- *   bun add ai                                   # aiSdkTransport
- *   bun add use-stick-to-bottom                  # BasaltStickToBottom
+ * basalt-ui/agent — the AI chat surface: a Mantine-free streaming runtime (`src/agent/**` outside
+ * `chat/`) plus the chat UI (`src/agent/chat/**`). `aiSdkTransport` (the `ai` npm package) is the
+ * one transport; `useAgentThreadRuns` is the one runner. Optional peers (`ai`,
+ * `use-stick-to-bottom`) load lazily — importing this module does not resolve either.
  *
  * @example
- * import { useAgentStream, edenTransport, PartList, BasaltStickToBottom } from 'basalt-ui/agent'
- *
- * const transport = edenTransport((input, signal) =>
- *   api.chat.post({ body: { message: input }, fetch: { signal } }),
- * )
- *
- * function Chat() {
- *   const { parts, status, send, stop } = useAgentStream({ transport })
- *   return (
- *     <BasaltStickToBottom style={{ height: '400px', overflow: 'auto' }}>
- *       <PartList parts={parts} />
- *       <button onClick={() => send('Hello')}>Send</button>
- *       {status === 'streaming' && <button onClick={stop}>Stop</button>}
- *     </BasaltStickToBottom>
- *   )
- * }
+ * import { aiSdkTransport, useAgentThreadRuns, ThreadFeed, Composer } from 'basalt-ui/agent'
  */
 
-// ── AgentPart discriminated union ─────────────────────────────────────────────
-export type {
-  AgentPart,
-  AgentPartDraft,
-  Drafted,
-  StartPart,
-  TextPart,
-  ReasoningPart,
-  ToolCallPart,
-  ToolCallState,
-  SourcePart,
-  ErrorPart,
-} from './parts'
-export { parseAgentPart, isStartPart, isToolCallSettled, TERMINAL_TOOL_STATES } from './parts'
-
-// ── mergePart (identity-addressed accumulator) ───────────────────────────────
-export { mergePart } from './merge'
+// ── Parts ─────────────────────────────────────────────────────────────────────
+export type { AgentPart, ToolCallPart } from './parts'
+export { parseAgentPart } from './parts'
+export type { ForeignPart, TranscriptPart, PartRenderers, PartRenderer } from './foreign'
 
-// ── withPartIds (drafts → identified parts) ──────────────────────────────────
-export { withPartIds } from './id'
-
-// ── coalesceParts (adjacent + by-id merge for display) ───────────────────────
-export { coalesceParts } from './coalesce'
-
-// ── foreign parts (the open half of the part-renderer registry) ──────────────
-export { definePartRenderers, narrowAgentPart } from './foreign'
-export type {
-  ForeignPart,
-  TranscriptPart,
-  ConsumerPart,
-  PartRenderers,
-  PartRenderContext,
-  PartRenderer,
-} from './foreign'
-
-// ── AgentTransport + edenTransport ───────────────────────────────────────────
-export type { AgentTransport, ResumableAgentTransport } from './transport'
-export { edenTransport, isResumable } from './transport'
-
-// ── aiSdkTransport (recommended default, optional peer: ai) ──────────────────
+// ── Transport and runner ──────────────────────────────────────────────────────
 export { aiSdkTransport } from './ai-sdk-transport'
-export type { AiSdkTransport, AiSdkTransportOptions } from './ai-sdk-transport'
-
-// ── useAgentStream ────────────────────────────────────────────────────────────
-export { useAgentStream } from './use-agent-stream'
-export type { StreamStatus, UseAgentStreamReturn } from './use-agent-stream'
-
-// ── useAgentThreadRuns ────────────────────────────────────────────────────────
 export { useAgentThreadRuns } from './use-agent-thread-runs'
-export type {
-  ThreadRunState,
-  UseAgentThreadRunsArgs,
-  UseAgentThreadRunsReturn,
-} from './use-agent-thread-runs'
-
-// ── PartList + renderer types ─────────────────────────────────────────────────
-export { PartList } from './part-list'
-export type {
-  PartListProps,
-  AgentPartRenderers,
-  TextPartRenderer,
-  ReasoningPartRenderer,
-  ToolCallPartRenderer,
-  SourcePartRenderer,
-  ErrorPartRenderer,
-} from './part-list'
+export type { ThreadRunState } from './use-agent-thread-runs'
+export type { AgentError } from './error'
 
-// ── BasaltStickToBottom (lazy, optional peer: use-stick-to-bottom) ────────────
-export { BasaltStickToBottom } from './stick-to-bottom'
-export type { BasaltStickToBottomProps } from './stick-to-bottom'
-
-// ── createChatHistoryStore + ChatMessage ──────────────────────────────────────
-export { createChatHistoryStore } from './history'
-export type { ChatMessage, ChatHistoryStore, ChatHistoryStoreOptions } from './history'
-
-// ── createThreadsStore + AgentThread ──────────────────────────────────────────
-export { createThreadsStore } from './thread'
-export type { AgentThread, ThreadStatus, ThreadsStore, ThreadsStoreOptions } from './thread'
-
-// ── AgentOutcome + heuristicOutcome ────────────────────────────────────────────
-export { heuristicOutcome } from './outcome'
+// ── Thread contracts (the store is consumer-owned) ────────────────────────────
+export type { ChatMessage } from './history'
+export type { AgentThread, ThreadStatus, ThreadsStore } from './thread'
 export type { AgentOutcome, OutcomeResolver } from './outcome'
+export type { AgentTransport, ResumableAgentTransport } from './transport'
 
-// ── createAdapterThreadsStore + threadsStoreAdapterContract ──────────────────
-export { createAdapterThreadsStore, threadsStoreAdapterContract } from './adapter'
-export type {
-  AdapterThreadsStoreOptions,
-  ThreadsStoreAdapter,
-  ThreadsStoreAdapterContractCase,
-} from './adapter'
+// ── Chat UI ───────────────────────────────────────────────────────────────────
+export { ThreadFeed } from './chat/thread-feed'
+export { ThreadFeedRow } from './chat/thread-feed-row'
+export type { MessageAffordances } from './chat/message-affordances'
+export { Composer } from './chat/composer'
+export type { ComposerHandle, ComposerSubmit } from './chat/composer'
+export { ToolChip } from './chat/tool-chip'

package/src/agent/outcome.ts

@@ -5,7 +5,7 @@
  * multi-thread feed — only a short, past-tense summary of what happened. AgentOutcome is
  * that DIFFERENT, smaller shape: a title, a one-line summary, and a status. Producing one
  * is the job of an OutcomeResolver (typically an LLM-backed summarizer wired by the
- * consumer); heuristicOutcome below is a text-only fallback for demos and early wiring.
+ * consumer).
  *
  * @example
  * import type { AgentOutcome } from 'basalt-ui/agent'
@@ -32,12 +32,12 @@ import type { AgentThread } from './thread'
  * turn has settled, so those never apply here.
  *
  * Note there are THREE overlapping status-shaped unions in this module family, one per layer:
- * `StreamStatus` (single-turn stream lifecycle, `./use-agent-stream`), `ThreadStatus` (persisted
+ * the internal `StreamStatus` (single-turn stream lifecycle, `./thread`), `ThreadStatus` (persisted
  * thread lifecycle, `./thread`), and this `AgentOutcome['status']` (feed-facing terminal
  * projection). They are related but not identical — `StreamStatus`'s `'idle'` (no turn in
  * flight) corresponds to `ThreadStatus`'s `'pending'` (thread created, no turn started yet); the
  * literal rename from `'idle'` to `'pending'` is intentionally deferred since it would ripple
- * into `use-agent-stream.ts` and its call sites.
+ * into `useAgentThreadRuns` and its call sites.
  *
  * @example
  * const outcome: AgentOutcome = { title: 'New chat', summary: '', status: 'done' }
@@ -65,56 +65,3 @@ export type AgentOutcome = {
 export type OutcomeResolver<TPart = AgentPart> = (
   thread: AgentThread<TPart>,
 ) => AgentOutcome | Promise<AgentOutcome>
-
-// ── heuristicOutcome ──────────────────────────────────────────────────────────
-
-const TITLE_MAX = 48
-const SUMMARY_MAX = 88
-
-/** Trim `text` to at most `max` characters, appending an ellipsis when cut. */
-function truncate(text: string, max: number): string {
-  if (text.length <= max) return text
-  return `${text.slice(0, max - 1).trimEnd()}…`
-}
-
-/** The leading sentence/clause of `text` (up to the first `.`, `!`, or `?`), trimmed. */
-function firstClause(text: string): string {
-  const match = text.match(/^[^.!?]+[.!?]?/)
-  return (match?.[0] ?? text).trim()
-}
-
-/**
- * DEMO-ONLY provisional heuristic — never the production path. Coalesces the last assistant
- * message's text parts into one string and derives a title/summary/status from it with no
- * model call. Real apps should wire an OutcomeResolver backed by an LLM summarizer; this
- * exists purely so a feed has something to render before that wiring lands.
- *
- * @example
- * const outcome = heuristicOutcome(thread)
- * // { title: 'Fixed the flaky test', summary: 'Fixed the flaky test by awaiting…', status: 'done' }
- */
-export function heuristicOutcome(thread: AgentThread): AgentOutcome {
-  const lastAssistant = thread.messages.toReversed().find((message) => message.role === 'assistant')
-  if (lastAssistant === undefined) {
-    return { title: 'New chat', summary: '', status: 'done' }
-  }
-
-  const text = lastAssistant.parts
-    .filter((part): part is Extract<AgentPart, { type: 'text' }> => part.type === 'text')
-    .map((part) => part.text)
-    .join('')
-    .trim()
-
-  if (text.length === 0) {
-    return { title: 'New chat', summary: '', status: 'done' }
-  }
-
-  const lastPart = lastAssistant.parts[lastAssistant.parts.length - 1]
-  const status: AgentOutcome['status'] = lastPart?.type === 'error' ? 'error' : 'done'
-
-  return {
-    title: truncate(firstClause(text), TITLE_MAX),
-    summary: truncate(text, SUMMARY_MAX),
-    status,
-  }
-}

package/src/agent/part-list.tsx

@@ -241,21 +241,21 @@ const DEFAULT_RENDERERS: AgentPartRenderers = {
 // ── PartList ──────────────────────────────────────────────────────────────────
 
 export type PartListProps<TPart extends AgentPart = AgentPart> = {
-  /** The parts accumulator from useAgentStream. */
+  /** The parts accumulator from useAgentThreadRuns. */
   readonly parts: TPart[]
   /**
    * Override individual part renderers. Omitted keys fall back to the headless defaults.
    * Pass `{ text: ({ part, settled }) => <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown> }`
    * to enable rich markdown rendering.
    */
-  readonly components?: Partial<AgentPartRenderers<TPart>>
+  readonly components?: Partial<AgentPartRenderers<TPart>> | undefined
   /**
    * `false` while the message these parts belong to is still streaming — forwarded to every
    * renderer so a text renderer can drop out of streaming mode (and a fenced mermaid/diagram can
    * upgrade) once the turn finishes. Defaults to `true`: a caller that knows nothing about a run
    * is rendering a finished list, and un-settled must be opted into by the thing that does know.
    */
-  readonly settled?: boolean
+  readonly settled?: boolean | undefined
 }
 
 /**