From cb16e269f096f33de237da8dca8636e7e1deab51 Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:56:11 +0900
Subject: [PATCH 01/12] feat(client): make the chat panel's regions replaceable

The built-in chat UI was one 1620-line component, so a host app that needed a
different layout had to replace the whole panel through CustomChat and rebuild
every region from scratch.

Each region is now a slot - Header, EmptyState, Message, PendingIndicator,
ToolApproval, Disclaimer and Composer - passed through `components` on the
provider. Every slot's built-in lives in `chatSlots/` as an exported `Default*`
component typed by its own slot props, so an override can wrap or re-invoke one
instead of rebuilding the region. The panel drops to 515 lines and only wires
props.

Typing each default against its own props is what forces those props to be
complete. Two gaps had to be closed to make it typecheck: `saveAsCommand` on the
message slot, and `submitMode`, `attachmentProcessing`, `disclaimerVisible` and
`slashCommands` on the composer. Both were read from panel scope, so replacing
`Message` had silently dropped "save as slash command".

A turn's raw messages and the run's ordered parts are exposed as well
(`sourceMessages`, `streamingParts`, `executingTool`): merging a turn into one
bubble drops its tool calls, tool results and per-step reasoning, and
`streamingText` / `streamingReasoning` flatten a multi-step answer into two
strings. Both strings stay, so the built-in bubble is unchanged.

Also stops a turn's pendingSources from leaking into the next turn when its
assistant messages carried only tool calls, and guards `streamingParts` with
`displayedChatId` like its sibling streaming fields.

The example app gains a slots showcase that lays a turn out as a timeline with
tool cards, per-step reasoning and citation cards.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  104 ++
 apps/example/src/App.tsx                      |    3 +
 .../example/src/pages/CustomSlotsDemoPage.tsx |  625 ++++++++
 apps/example/src/pages/CustomUIPage.tsx       |   34 +
 apps/example/src/pages/orbitTimeline.tsx      |  353 +++++
 .../src/providers/NavigationAIProvider.tsx    |    1 +
 .../client/src/components/UseAIChat.test.tsx  |   15 +
 packages/client/src/components/UseAIChat.tsx  |   22 +-
 .../client/src/components/UseAIChatPanel.tsx  | 1333 +++--------------
 .../src/components/UseAIChatSlots.test.tsx    |  225 +++
 .../components/chatSlots/DefaultComposer.tsx  |  269 ++++
 .../chatSlots/DefaultDisclaimer.tsx           |   22 +
 .../chatSlots/DefaultEmptyState.tsx           |   83 +
 .../components/chatSlots/DefaultHeader.tsx    |  425 ++++++
 .../components/chatSlots/DefaultMessage.tsx   |  241 +++
 .../chatSlots/DefaultPendingIndicator.tsx     |   67 +
 .../chatSlots/DefaultToolApproval.tsx         |   31 +
 .../components/chatSlots/FeedbackButton.tsx   |   88 ++
 .../client/src/components/chatSlots/Slot.tsx  |   30 +
 .../client/src/components/chatSlots/index.ts  |    9 +
 .../src/components/chatSlots/messageFiles.ts  |   24 +
 .../client/src/components/chatSlots/types.ts  |  186 +++
 .../useServerEvents.streamingParts.test.tsx   |   98 ++
 packages/client/src/hooks/useServerEvents.ts  |   57 +-
 packages/client/src/index.ts                  |   28 +
 .../client/src/providers/useAIProvider.tsx    |   15 +-
 .../src/utils/mergeAssistantMessages.test.ts  |   45 +
 .../src/utils/mergeAssistantMessages.ts       |   44 +-
 28 files changed, 3307 insertions(+), 1170 deletions(-)
 create mode 100644 apps/example/src/pages/CustomSlotsDemoPage.tsx
 create mode 100644 apps/example/src/pages/orbitTimeline.tsx
 create mode 100644 packages/client/src/components/UseAIChatSlots.test.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultComposer.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultDisclaimer.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultEmptyState.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultHeader.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultMessage.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultPendingIndicator.tsx
 create mode 100644 packages/client/src/components/chatSlots/DefaultToolApproval.tsx
 create mode 100644 packages/client/src/components/chatSlots/FeedbackButton.tsx
 create mode 100644 packages/client/src/components/chatSlots/Slot.tsx
 create mode 100644 packages/client/src/components/chatSlots/index.ts
 create mode 100644 packages/client/src/components/chatSlots/messageFiles.ts
 create mode 100644 packages/client/src/components/chatSlots/types.ts
 create mode 100644 packages/client/src/hooks/useServerEvents.streamingParts.test.tsx

diff --git a/README.md b/README.md
index 15ded121..b0c4b838 100644
--- a/README.md
+++ b/README.md
@@ -723,6 +723,110 @@ root.render(
 );
 ```
 
+For partial customization, override only the built-in chat regions you own.
+Every slot receives the built-in UI as `children`: render it to decorate the
+default behavior, or omit it to replace that region completely.
+
+```tsx
+import type {
+  ChatMessageSlotProps,
+  ChatComposerSlotProps,
+} from '@meetsmore-oss/use-ai-client';
+
+function Message({ message, children }: ChatMessageSlotProps) {
+  return <div className={`my-message my-message-${message.role}`}>{children}</div>;
+}
+
+function Composer({ input, onInputChange, onSend, canSend }: ChatComposerSlotProps) {
+  return (
+    <form onSubmit={(event) => { event.preventDefault(); onSend(); }}>
+      <textarea value={input} onChange={(event) => onInputChange(event.target.value)} />
+      <button disabled={!canSend}>Send</button>
+    </form>
+  );
+}
+
+<UseAIProvider
+  serverUrl="wss://your-server.com"
+  chatComponents={{ Message, Composer }}
+>
+  <App />
+</UseAIProvider>
+```
+
+Available slots are `Header`, `EmptyState`, `Message`, `PendingIndicator`,
+`Composer`, `ToolApproval`, and `Disclaimer`. Provider-level `chatComponents` apply to all
+chat instances. A specific `<UseAIChat components={...} />` takes precedence.
+
+Each region's built-in implementation is exported as `DefaultHeader`,
+`DefaultMessage` and so on, taking exactly the props its slot receives. Reuse
+one when only part of a region needs to change:
+
+```tsx
+import { DefaultMessage, type ChatMessageSlotProps } from '@meetsmore-oss/use-ai-client';
+
+function Message(props: ChatMessageSlotProps) {
+  return (
+    <>
+      <DefaultMessage {...props} />
+      {props.isLast && <Citations />}
+    </>
+  );
+}
+```
+
+The answer being streamed goes through `Message` too, as a provisional entry
+carrying the id it will be persisted under. `streaming` tells the two apart, and
+`streamingParts` holds the answer so far as the ordered pieces the model emitted:
+
+```tsx
+function Message({ message, streaming, streamingParts }: ChatMessageSlotProps) {
+  if (!streaming) return <PersistedTurn message={message} />;
+
+  return (
+    <div className="my-message is-streaming">
+      {streamingParts.map((part, index) => {
+        if (part.kind === 'reasoning') return <Thinking key={index} text={part.text} />;
+        if (part.kind === 'tool_call') return <ToolCard key={index} name={part.name} />;
+        return <Body key={index} text={part.text} />;
+      })}
+    </div>
+  );
+}
+```
+
+A run that thinks, calls a tool, thinks again and answers gives four parts in
+that order. `streamingText` and `streamingReasoning` are still there, each
+flattening the whole run into one string; the built-in bubble uses those.
+
+`PendingIndicator` covers the gap between the run starting and the first token
+arriving, plus send-time file processing. It receives `executingTool` and
+`fileProcessing`, and stops rendering once the answer starts arriving.
+
+### Rendering a turn as a timeline
+
+The built-in bubble shows one turn as a single block of text: the tool calls,
+their results and the per-step reasoning are merged away. `sourceMessages` hands
+those back, in the order the model produced them, so a `Message` slot can lay
+the turn out step by step instead:
+
+```tsx
+function Message({ sourceMessages }: ChatMessageSlotProps) {
+  return sourceMessages.flatMap((source) => {
+    if (source.role === 'tool') return [];          // consumed as a call's result
+    return [
+      ...(source.reasoningParts ?? []).map((part) => <Thinking text={part.text} />),
+      <Prose content={source.content} />,
+      ...(source.toolCalls ?? []).map((call) => <ToolCard call={call} />),
+    ];
+  });
+}
+```
+
+A `tool` message carries the result of the call with the matching `toolCallId`,
+so anything a tool returned (citations, a table, a chart) is available to render
+under the answer. `apps/example` has a working page: `/custom-slots-demo`.
+
 You can also disable them by passing `null`:
 
 ```tsx
diff --git a/apps/example/src/App.tsx b/apps/example/src/App.tsx
index 09873e90..e9ed5cda 100644
--- a/apps/example/src/App.tsx
+++ b/apps/example/src/App.tsx
@@ -17,6 +17,7 @@ import ClientToolsPage from './pages/ClientToolsPage';
 import ChatHistoryPage from './pages/ChatHistoryPage';
 import SlashCommandsPage from './pages/SlashCommandsPage';
 import CustomUIPage from './pages/CustomUIPage';
+import CustomSlotsDemoPage from './pages/CustomSlotsDemoPage';
 import ThemeI18nPage from './pages/ThemeI18nPage';
 import SuggestionsPage from './pages/SuggestionsPage';
 import DestructiveApprovalPage from './pages/DestructiveApprovalPage';
@@ -66,6 +67,7 @@ const NAV_CATEGORIES: NavCategory[] = [
   {
     label: 'UI Customization',
     items: [
+      { path: '/custom-slots-demo', label: 'Component Slots Demo' },
       { path: '/custom-ui', label: 'Custom UI' },
       { path: '/theme-i18n', label: 'Theme & i18n' },
       { path: '/submit-mode', label: 'Submit Mode (Enter key)' },
@@ -174,6 +176,7 @@ function AppContent() {
         <Route path="/programmatic-chat"><ProgrammaticChatPage /></Route>
         <Route path="/chat-history"><ChatHistoryPage /></Route>
         <Route path="/slash-commands"><SlashCommandsPage /></Route>
+        <Route path="/custom-slots-demo"><CustomSlotsDemoPage /></Route>
         <Route path="/custom-ui"><CustomUIPage /></Route>
         <Route path="/theme-i18n"><ThemeI18nPage /></Route>
         <Route path="/submit-mode"><SubmitModePage /></Route>
diff --git a/apps/example/src/pages/CustomSlotsDemoPage.tsx b/apps/example/src/pages/CustomSlotsDemoPage.tsx
new file mode 100644
index 00000000..a83b7f96
--- /dev/null
+++ b/apps/example/src/pages/CustomSlotsDemoPage.tsx
@@ -0,0 +1,625 @@
+import React from 'react';
+import { z } from 'zod';
+import {
+  UseAIChat,
+  useAI,
+  defineTool,
+  type ChatComposerSlotProps,
+  type ChatDisclaimerSlotProps,
+  type ChatEmptyStateSlotProps,
+  type ChatHeaderSlotProps,
+  type ChatMessageSlotProps,
+  type ChatPendingIndicatorSlotProps,
+  type ChatToolApprovalSlotProps,
+  type PersistedMessageContent,
+  type UseAIChatComponentOverrides,
+} from '@meetsmore-oss/use-ai-client';
+import {
+  OrbitCitations,
+  OrbitProse,
+  OrbitReasoning,
+  OrbitToolCard,
+  buildStreamingTimeline,
+  buildTimeline,
+  collectSources,
+} from './orbitTimeline';
+
+const FALLBACK_SUGGESTIONS = [
+  'Look up how component slots work and cite your sources',
+  'Work out the orbital period for a 7000 km radius, with the formula',
+  'Search the handbook for tool approval, then summarize it',
+];
+
+function contentToText(content: PersistedMessageContent): string {
+  if (typeof content === 'string') return content;
+
+  return content
+    .map((part) => {
+      if (part.type === 'text' || part.type === 'transformed_file') return part.text;
+      if (part.type === 'file') return `Attachment: ${part.file.name}`;
+      if (part.type === 'attachment_ref') return `Attachment: ${part.name}`;
+      return '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+function OrbitHeader({
+  connected,
+  messages,
+  availableAgents,
+  defaultAgent,
+  selectedAgent,
+  onAgentChange,
+  onNewChat,
+}: ChatHeaderSlotProps) {
+  const activeAgent = availableAgents.find((agent) => agent.id === (selectedAgent ?? defaultAgent));
+
+  return (
+    <header className="orbit-header" data-testid="orbit-header">
+      <div className="orbit-brand-mark" aria-hidden="true">
+        <span />
+      </div>
+      <div className="orbit-brand-copy">
+        <span className="orbit-eyebrow">WORKSPACE COPILOT</span>
+        <strong>Orbit</strong>
+      </div>
+      <div className="orbit-header-actions">
+        {availableAgents.length > 1 && onAgentChange ? (
+          <select
+            aria-label="Select Orbit agent"
+            className="orbit-agent-select"
+            value={selectedAgent ?? defaultAgent ?? ''}
+            onChange={(event) => onAgentChange(event.target.value === defaultAgent ? null : event.target.value)}
+          >
+            {availableAgents.map((agent) => (
+              <option key={agent.id} value={agent.id}>{agent.name}</option>
+            ))}
+          </select>
+        ) : (
+          <span className="orbit-agent-name">{activeAgent?.name ?? 'General'}</span>
+        )}
+        <span className={`orbit-status ${connected ? 'is-online' : ''}`}>
+          <span aria-hidden="true" />
+          {connected ? 'Live' : 'Offline'}
+        </span>
+        {onNewChat && (
+          <button
+            type="button"
+            className="orbit-icon-button"
+            onClick={() => void onNewChat()}
+            title="Start a new conversation"
+            aria-label="Start a new conversation"
+            disabled={messages.length === 0}
+          >
+            +
+          </button>
+        )}
+      </div>
+    </header>
+  );
+}
+
+function OrbitEmptyState({ suggestions, connected, loading, onSelectSuggestion }: ChatEmptyStateSlotProps) {
+  const prompts = suggestions.length > 0 ? suggestions : FALLBACK_SUGGESTIONS;
+
+  return (
+    <section className="orbit-empty" data-testid="orbit-empty-state">
+      <div className="orbit-orb" aria-hidden="true">
+        <div />
+      </div>
+      <p className="orbit-kicker">READY WHEN YOU ARE</p>
+      <h2>Make space for<br /><em>better work.</em></h2>
+      <p className="orbit-intro">
+        Ask Orbit to plan, summarize, calculate, or move through this example app with you.
+      </p>
+      <div className="orbit-prompts">
+        {prompts.slice(0, 3).map((prompt, index) => (
+          <button
+            key={prompt}
+            type="button"
+            onClick={() => onSelectSuggestion(prompt)}
+            disabled={!connected || loading}
+            data-testid="orbit-suggestion"
+          >
+            <span>0{index + 1}</span>
+            {prompt}
+            <b aria-hidden="true">↗</b>
+          </button>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function OrbitMessage({
+  message,
+  sourceMessages,
+  streaming,
+  streamingParts,
+}: ChatMessageSlotProps) {
+  const isUser = message.role === 'user';
+  const text = contentToText(message.content);
+
+  if (isUser) {
+    return (
+      <article className="orbit-message is-user" data-testid="orbit-message">
+        <div className="orbit-avatar" aria-hidden="true">Y</div>
+        <div className="orbit-message-body">
+          <div className="orbit-message-meta">
+            <strong>You</strong>
+            <span>{new Date(message.createdAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}</span>
+          </div>
+          <div className="orbit-message-bubble">{text}</div>
+        </div>
+      </article>
+    );
+  }
+
+  // A run in flight and a persisted turn reduce to the same entries, so the
+  // layout below does not change when the answer completes.
+  const entries = streaming ? buildStreamingTimeline(streamingParts) : buildTimeline(sourceMessages);
+  const sources = collectSources(entries);
+  const lastEntry = entries[entries.length - 1];
+
+  return (
+    <article
+      className="orbit-message"
+      data-testid={streaming ? 'orbit-streaming-message' : 'orbit-message'}
+    >
+      <div className={`orbit-avatar ${streaming ? 'orbit-avatar-pulse' : ''}`} aria-hidden="true">O</div>
+      <div className="orbit-message-body">
+        <div className="orbit-message-meta">
+          <strong>Orbit</strong>
+          {streaming ? (
+            <span className="orbit-writing">
+              <i /><i /><i />{' '}
+              {lastEntry?.kind === 'reasoning' ? 'Thinking through the details'
+                : lastEntry?.kind === 'tool' ? `Running ${lastEntry.name}`
+                : 'Writing a response'}
+            </span>
+          ) : (
+            <span>{new Date(message.createdAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}</span>
+          )}
+        </div>
+        {entries.length === 0 ? (
+          <OrbitProse text={text || 'Completed.'} />
+        ) : (
+          entries.map((entry) => {
+            if (entry.kind === 'reasoning') {
+              // Open the block still being written so the run reads as it happens.
+              return <OrbitReasoning key={entry.key} text={entry.text!} open={streaming && entry === lastEntry} />;
+            }
+            if (entry.kind === 'tool') return <OrbitToolCard key={entry.key} entry={entry} />;
+            return <OrbitProse key={entry.key} text={entry.text!} />;
+          })
+        )}
+        {sources.length > 0 && <OrbitCitations sources={sources} />}
+      </div>
+    </article>
+  );
+}
+
+function OrbitPendingIndicator({ executingTool, fileProcessing }: ChatPendingIndicatorSlotProps) {
+  const activity = executingTool?.displayText
+    ?? (fileProcessing ? 'Reading your attachment' : 'Getting started');
+
+  return (
+    <article className="orbit-message" data-testid="orbit-pending-indicator">
+      <div className="orbit-avatar orbit-avatar-pulse" aria-hidden="true">O</div>
+      <div className="orbit-message-body">
+        <div className="orbit-message-meta">
+          <strong>Orbit</strong>
+          <span className="orbit-writing"><i /><i /><i /> {activity}</span>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+function OrbitComposer({
+  input,
+  connected,
+  loading,
+  placeholder,
+  canSend,
+  canAbort,
+  attachments,
+  fileUploadEnabled,
+  fileError,
+  pendingApprovals,
+  onInputChange,
+  onSend,
+  onAbort,
+  onOpenFilePicker,
+  onRemoveAttachment,
+}: ChatComposerSlotProps) {
+  // ToolApproval is rendered independently by use-ai. Hide the composer while
+  // an approval is pending to match the built-in interaction pattern.
+  if (pendingApprovals.length > 0) return null;
+
+  return (
+    <footer className="orbit-composer-wrap" data-testid="orbit-composer">
+      {attachments.length > 0 && (
+        <div className="orbit-attachments">
+          {attachments.map((attachment) => (
+            <button key={attachment.id} type="button" onClick={() => onRemoveAttachment(attachment.id)}>
+              {attachment.file.name} <span>×</span>
+            </button>
+          ))}
+        </div>
+      )}
+      {fileError && <p className="orbit-file-error">{fileError}</p>}
+      <div className="orbit-composer">
+        <textarea
+          aria-label="Message Orbit"
+          value={input}
+          onChange={(event) => onInputChange(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter' && !event.shiftKey) {
+              event.preventDefault();
+              if (canSend) onSend();
+            }
+          }}
+          placeholder={placeholder}
+          rows={2}
+          disabled={!connected}
+        />
+        <div className="orbit-composer-actions">
+          <div>
+            {fileUploadEnabled && (
+              <button type="button" onClick={onOpenFilePicker} className="orbit-attach-button">
+                <span aria-hidden="true">＋</span> Add context
+              </button>
+            )}
+            <small>{connected ? 'Enter to send · Shift + Enter for a new line' : 'Waiting for the server…'}</small>
+          </div>
+          {canAbort ? (
+            <button type="button" className="orbit-send-button is-stop" onClick={onAbort} aria-label="Stop response">
+              ■
+            </button>
+          ) : (
+            <button
+              type="button"
+              className="orbit-send-button"
+              onClick={onSend}
+              disabled={!canSend || loading}
+              aria-label="Send message"
+            >
+              ↑
+            </button>
+          )}
+        </div>
+      </div>
+    </footer>
+  );
+}
+
+function OrbitToolApproval({ approvals, onApprove, onReject }: ChatToolApprovalSlotProps) {
+  const firstApproval = approvals[0];
+  if (!firstApproval) return null;
+
+  return (
+    <aside className="orbit-approval" data-testid="orbit-tool-approval">
+      <span className="orbit-approval-icon" aria-hidden="true">!</span>
+      <div>
+        <p>Permission requested</p>
+        <strong>{firstApproval.annotations?.title ?? firstApproval.toolCallName}</strong>
+        {approvals.length > 1 && <small> + {approvals.length - 1} more actions</small>}
+      </div>
+      <button type="button" onClick={() => onReject('Declined in Orbit custom UI')}>Decline</button>
+      <button type="button" className="is-approve" onClick={onApprove}>Allow once</button>
+    </aside>
+  );
+}
+
+function OrbitDisclaimer({ text }: ChatDisclaimerSlotProps) {
+  return (
+    <p className="orbit-disclaimer" data-testid="orbit-disclaimer">
+      <span aria-hidden="true">✦</span> {text}
+    </p>
+  );
+}
+
+const orbitComponents: UseAIChatComponentOverrides = {
+  Header: OrbitHeader,
+  EmptyState: OrbitEmptyState,
+  Message: OrbitMessage,
+  PendingIndicator: OrbitPendingIndicator,
+  Composer: OrbitComposer,
+  ToolApproval: OrbitToolApproval,
+  Disclaimer: OrbitDisclaimer,
+};
+
+/**
+ * Stand-in search index. The point of the demo is the rendering, so the
+ * "sources" are fixed rather than fetched.
+ */
+const HANDBOOK = [
+  {
+    title: 'Component slots',
+    url: 'https://example.com/handbook/component-slots',
+    snippet: 'Each region of the chat is a React component the host app supplies.',
+    body: 'Slots receive live chat state and callbacks. Omit children to replace a region outright.',
+  },
+  {
+    title: 'Tool approval',
+    url: 'https://example.com/handbook/tool-approval',
+    snippet: 'Tools marked destructive wait for an explicit confirmation.',
+    body: 'A tool annotated with destructiveHint pauses the run until the user approves it.',
+  },
+  {
+    title: 'Chat history',
+    url: 'https://example.com/handbook/chat-history',
+    snippet: 'Conversations persist through a ChatRepository.',
+    body: 'The default repository stores the twenty most recent chats in localStorage.',
+  },
+];
+
+const searchHandbook = defineTool(
+  'Search the Orbit handbook. Returns matching passages and the sources they came from.',
+  z.object({ query: z.string() }),
+  ({ query }) => {
+    const needle = query.toLowerCase();
+    const hits = HANDBOOK.filter(
+      (entry) => entry.title.toLowerCase().includes(needle) || entry.body.toLowerCase().includes(needle)
+    );
+    const matches = hits.length > 0 ? hits : HANDBOOK;
+
+    return {
+      passages: matches.map((entry) => entry.body),
+      // Read back by the Message slot to render the citation cards.
+      sources: matches.map(({ title, url, snippet }) => ({ title, url, snippet })),
+    };
+  }
+);
+
+const computeOrbitalPeriod = defineTool(
+  'Compute the orbital period for a circular orbit of the given radius around Earth.',
+  z.object({ radiusKm: z.number() }),
+  ({ radiusKm }) => {
+    const mu = 398600.4418; // km^3/s^2
+    const seconds = 2 * Math.PI * Math.sqrt(radiusKm ** 3 / mu);
+
+    return {
+      radiusKm,
+      periodMinutes: Number((seconds / 60).toFixed(2)),
+      formula: 'T = 2\\pi\\sqrt{\\frac{r^{3}}{\\mu}}',
+      sources: [
+        {
+          title: 'Orbital mechanics primer',
+          url: 'https://example.com/handbook/orbital-mechanics',
+          snippet: 'Vis-viva and the circular orbit period.',
+        },
+      ],
+    };
+  }
+);
+
+const SLOT_NAMES = ['Header', 'Empty state', 'Messages', 'Pending indicator', 'Composer', 'Tool approval', 'Disclaimer'];
+
+const RENDERING_NOTES = [
+  'Tool calls as cards, in the turn',
+  'LaTeX in assistant prose',
+  'Sources pinned under the answer',
+  'Reasoning inline, step by step',
+];
+
+export default function CustomSlotsDemoPage() {
+  useAI({
+    tools: { searchHandbook, computeOrbitalPeriod },
+    prompt: [
+      'The user is viewing the Orbit component slots customization demo.',
+      'Use searchHandbook for questions about this library, and computeOrbitalPeriod for orbit questions.',
+      'Write mathematics as LaTeX between $ for inline and $$ for display; the UI renders it.',
+    ].join('\n'),
+    suggestions: FALLBACK_SUGGESTIONS,
+  });
+
+  return (
+    <div className="custom-slots-demo" data-testid="custom-slots-demo-page">
+      <style>{orbitStyles}</style>
+      <section className="orbit-page-intro">
+        <div>
+          <p className="orbit-page-kicker">COMPONENT SLOTS / LIVE EXAMPLE</p>
+          <h1>Same engine.<br /><em>A different character.</em></h1>
+        </div>
+        <div className="orbit-page-note">
+          <span>07</span>
+          <p>Every visible region below is supplied by the consuming app. Protocol, state, and streaming stay inside use-ai.</p>
+        </div>
+      </section>
+
+      <section className="orbit-demo-grid">
+        <div className="orbit-chat-shell">
+          <div className="orbit-chat-accent" />
+          <div className="orbit-chat" data-testid="orbit-chat">
+            <UseAIChat components={orbitComponents} />
+          </div>
+        </div>
+
+        <aside className="orbit-specimen-card">
+          <p className="orbit-page-kicker">OVERRIDDEN REGIONS</p>
+          <h2>Slots, not a theme preset.</h2>
+          <p>
+            These are regular React components receiving live chat state and callbacks. Change markup, layout, or behavior without forking the chat client.
+          </p>
+          <ol>
+            {SLOT_NAMES.map((name, index) => (
+              <li key={name}><span>0{index + 1}</span>{name}</li>
+            ))}
+          </ol>
+          <p className="orbit-page-kicker">BUILT FROM sourceMessages</p>
+          <ul className="orbit-notes">
+            {RENDERING_NOTES.map((note) => (
+              <li key={note}>{note}</li>
+            ))}
+          </ul>
+          <div className="orbit-code-line">
+            <code>{'<UseAIChat components={orbitComponents} />'}</code>
+          </div>
+        </aside>
+      </section>
+    </div>
+  );
+}
+
+const orbitStyles = `
+  .custom-slots-demo {
+    --orbit-ink: #11182b;
+    --orbit-lime: #d7ff3f;
+    --orbit-coral: #ff6b57;
+    min-height: 100vh;
+    padding: 52px clamp(24px, 5vw, 72px) 72px;
+    box-sizing: border-box;
+    color: var(--orbit-ink);
+    background:
+      radial-gradient(circle at 90% 4%, rgba(255, 107, 87, .19), transparent 27%),
+      linear-gradient(115deg, rgba(17, 24, 43, .045) 1px, transparent 1px),
+      #f1f2e9;
+    background-size: auto, 34px 34px, auto;
+    font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  }
+  .orbit-page-intro { display: flex; justify-content: space-between; align-items: end; gap: 40px; max-width: 1180px; margin: 0 auto 42px; }
+  .orbit-page-kicker, .orbit-kicker, .orbit-eyebrow { margin: 0; font-size: 10px; line-height: 1.2; font-weight: 800; letter-spacing: .19em; }
+  .orbit-page-intro h1 { margin: 13px 0 0; font-size: clamp(38px, 5vw, 68px); line-height: .96; letter-spacing: -.055em; font-weight: 760; }
+  .orbit-page-intro h1 em, .orbit-empty h2 em { color: var(--orbit-coral); font-family: Georgia, serif; font-weight: 400; }
+  .orbit-page-note { display: flex; align-items: start; gap: 14px; width: min(360px, 100%); padding-bottom: 5px; }
+  .orbit-page-note > span { display: grid; place-items: center; flex: 0 0 44px; height: 44px; background: var(--orbit-lime); border: 1px solid var(--orbit-ink); border-radius: 50%; font-size: 13px; font-weight: 800; }
+  .orbit-page-note p { margin: 0; font-size: 13px; line-height: 1.55; color: #555b68; }
+  .orbit-demo-grid { display: grid; grid-template-columns: minmax(520px, 1fr) 310px; gap: 24px; max-width: 1180px; margin: 0 auto; align-items: stretch; }
+  .orbit-chat-shell { display: grid; position: relative; min-height: 680px; overflow: hidden; background: var(--orbit-ink); border-radius: 26px; box-shadow: 0 26px 70px rgba(17, 24, 43, .18); }
+  .orbit-chat-accent { position: absolute; top: -55px; right: -42px; width: 190px; height: 190px; border: 34px solid rgba(215, 255, 63, .11); border-radius: 50%; pointer-events: none; z-index: 1; }
+  .orbit-chat { min-height: 0; position: relative; z-index: 2; }
+  .orbit-chat > div { background: transparent !important; color: #f7f8f0; }
+  .orbit-header { min-height: 82px; padding: 18px 22px; box-sizing: border-box; display: flex; align-items: center; gap: 12px; border-bottom: 1px solid rgba(255,255,255,.09); }
+  .orbit-brand-mark { position: relative; display: grid; place-items: center; width: 41px; height: 41px; border: 1px solid rgba(255,255,255,.34); border-radius: 50%; }
+  .orbit-brand-mark::before { content: ''; position: absolute; inset: 7px -5px; border: 1px solid var(--orbit-lime); border-radius: 50%; transform: rotate(-28deg); }
+  .orbit-brand-mark span { width: 7px; height: 7px; background: var(--orbit-lime); border-radius: 50%; box-shadow: 0 0 14px var(--orbit-lime); }
+  .orbit-brand-copy { display: flex; flex-direction: column; gap: 2px; }
+  .orbit-brand-copy strong { font-family: Georgia, serif; font-size: 22px; font-weight: 400; }
+  .orbit-eyebrow { color: #8e96a8; font-size: 8px; }
+  .orbit-header-actions { margin-left: auto; display: flex; align-items: center; gap: 8px; }
+  .orbit-agent-name, .orbit-agent-select { color: #aab0bf; font: inherit; font-size: 11px; background: transparent; border: 0; }
+  .orbit-agent-select { max-width: 130px; color: #f7f8f0; outline: none; }
+  .orbit-status { display: flex; align-items: center; gap: 6px; padding: 7px 10px; border: 1px solid rgba(255,255,255,.12); border-radius: 999px; color: #aab0bf; font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
+  .orbit-status > span { width: 6px; height: 6px; border-radius: 50%; background: #687083; }
+  .orbit-status.is-online > span { background: var(--orbit-lime); box-shadow: 0 0 9px rgba(215,255,63,.75); }
+  .orbit-icon-button { width: 32px; height: 32px; border: 0; border-radius: 50%; background: var(--orbit-lime); color: var(--orbit-ink); cursor: pointer; font-size: 20px; line-height: 1; }
+  .orbit-icon-button:disabled { opacity: .25; cursor: default; }
+  .orbit-empty { display: flex; flex-direction: column; align-items: flex-start; max-width: 550px; width: 100%; margin: auto; padding: 32px 26px 18px; box-sizing: border-box; }
+  .orbit-orb { position: relative; width: 67px; height: 67px; margin-bottom: 24px; border-radius: 50%; border: 1px solid rgba(215,255,63,.72); display: grid; place-items: center; }
+  .orbit-orb::before { content: ''; position: absolute; width: 89px; height: 30px; border: 1px solid rgba(215,255,63,.35); border-radius: 50%; transform: rotate(-25deg); }
+  .orbit-orb div { width: 20px; height: 20px; border-radius: 50%; background: var(--orbit-lime); filter: blur(1px); box-shadow: 0 0 24px rgba(215,255,63,.75); }
+  .orbit-kicker { color: var(--orbit-lime); }
+  .orbit-empty h2 { margin: 10px 0 10px; color: #f7f8f0; font-size: clamp(32px, 4vw, 47px); line-height: .98; letter-spacing: -.045em; }
+  .orbit-intro { max-width: 420px; margin: 0; color: #9fa6b7; font-size: 13px; line-height: 1.55; }
+  .orbit-prompts { width: 100%; display: grid; gap: 7px; margin-top: 24px; }
+  .orbit-prompts button { display: grid; grid-template-columns: 27px 1fr auto; align-items: center; gap: 7px; width: 100%; padding: 11px 13px; color: #e9ebdf; background: rgba(255,255,255,.045); border: 1px solid rgba(255,255,255,.1); border-radius: 9px; text-align: left; cursor: pointer; font: inherit; font-size: 12px; transition: border-color .15s, background .15s, transform .15s; }
+  .orbit-prompts button:hover:not(:disabled) { background: rgba(215,255,63,.07); border-color: rgba(215,255,63,.55); transform: translateX(3px); }
+  .orbit-prompts button:disabled { opacity: .45; cursor: not-allowed; }
+  .orbit-prompts button span { color: #737b8d; font-size: 9px; font-weight: 800; }
+  .orbit-prompts button b { color: var(--orbit-lime); font-size: 15px; }
+  .orbit-message { display: flex; align-items: flex-start; gap: 10px; width: min(88%, 590px); }
+  .orbit-message.is-user { flex-direction: row-reverse; align-self: flex-end; }
+  .orbit-message.is-tool { opacity: .75; }
+  .orbit-avatar { display: grid; place-items: center; flex: 0 0 30px; height: 30px; border: 1px solid rgba(215,255,63,.5); border-radius: 50%; color: var(--orbit-lime); font: 12px Georgia, serif; }
+  .orbit-message.is-user .orbit-avatar { color: var(--orbit-ink); background: var(--orbit-coral); border-color: var(--orbit-coral); font-family: inherit; font-weight: 800; }
+  .orbit-message-body { flex: 1; min-width: 0; }
+  .orbit-message-meta { display: flex; align-items: center; gap: 8px; margin: 1px 0 5px; color: #747d91; font-size: 9px; text-transform: uppercase; letter-spacing: .08em; }
+  .orbit-message.is-user .orbit-message-meta { justify-content: flex-end; }
+  .orbit-message-meta strong { color: #c9ced8; font-size: 10px; }
+  .orbit-message-bubble { padding: 11px 13px; color: #e8eae3; background: rgba(255,255,255,.055); border: 1px solid rgba(255,255,255,.075); border-radius: 4px 14px 14px 14px; white-space: pre-wrap; font-size: 13px; line-height: 1.55; overflow-wrap: anywhere; }
+  .orbit-message.is-user .orbit-message-bubble { color: var(--orbit-ink); background: var(--orbit-lime); border-color: var(--orbit-lime); border-radius: 14px 4px 14px 14px; }
+  .orbit-message-body > * + * { margin-top: 7px; }
+  .orbit-reasoning { padding: 8px 11px; background: rgba(255,255,255,.03); border: 1px dashed rgba(255,255,255,.14); border-radius: 10px; }
+  .orbit-reasoning summary { color: #8e96a8; font-size: 9px; font-weight: 800; letter-spacing: .14em; text-transform: uppercase; cursor: pointer; }
+  .orbit-reasoning p { margin: 7px 0 0; color: #9fa6b7; font-size: 11px; line-height: 1.6; white-space: pre-wrap; }
+  .orbit-tool-card { padding: 10px 12px; background: rgba(215,255,63,.05); border: 1px solid rgba(215,255,63,.28); border-radius: 11px; }
+  .orbit-tool-card.is-pending { border-style: dashed; opacity: .8; }
+  .orbit-tool-head { display: flex; align-items: center; gap: 8px; }
+  .orbit-tool-glyph { display: grid; place-items: center; width: 20px; height: 20px; border-radius: 5px; color: var(--orbit-ink); background: var(--orbit-lime); font-size: 11px; }
+  .orbit-tool-head strong { color: #edf0e5; font-size: 12px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .orbit-tool-state { margin-left: auto; color: #8e96a8; font-size: 8px; font-weight: 800; letter-spacing: .14em; text-transform: uppercase; }
+  .orbit-tool-args { display: grid; gap: 3px; margin: 8px 0 0; }
+  .orbit-tool-args > div { display: flex; gap: 8px; font-size: 11px; }
+  .orbit-tool-args dt { flex: 0 0 auto; color: #8e96a8; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .orbit-tool-args dd { margin: 0; min-width: 0; color: #d9dce4; overflow-wrap: anywhere; }
+  .orbit-math { font-family: Georgia, 'Times New Roman', serif; font-style: italic; color: var(--orbit-lime); white-space: nowrap; }
+  .orbit-math.is-block { display: block; margin: 9px 0; padding: 9px 0; text-align: center; font-size: 16px; border-top: 1px solid rgba(255,255,255,.07); border-bottom: 1px solid rgba(255,255,255,.07); }
+  .orbit-math sup, .orbit-math sub { font-size: .68em; font-style: normal; }
+  .orbit-frac { display: inline-flex; flex-direction: column; vertical-align: middle; text-align: center; }
+  .orbit-frac > span:first-child { border-bottom: 1px solid currentColor; padding: 0 4px 1px; }
+  .orbit-frac > span:last-child { padding: 1px 4px 0; }
+  .orbit-sqrt { border-top: 1px solid currentColor; padding: 1px 3px 0; }
+  .orbit-sqrt::before { content: '√'; margin-left: -3px; }
+  .orbit-citations { padding-top: 4px; }
+  .orbit-citations .orbit-kicker { margin-bottom: 6px; color: #747d91; }
+  .orbit-citation-row { display: flex; gap: 7px; overflow-x: auto; padding-bottom: 3px; }
+  .orbit-citation { display: grid; gap: 3px; flex: 0 0 178px; padding: 9px 10px; color: inherit; background: rgba(255,255,255,.045); border: 1px solid rgba(255,255,255,.1); border-radius: 10px; text-decoration: none; transition: border-color .15s, transform .15s; }
+  .orbit-citation:hover { border-color: rgba(215,255,63,.5); transform: translateY(-2px); }
+  .orbit-citation > span { color: var(--orbit-ink); background: var(--orbit-lime); width: 15px; height: 15px; border-radius: 4px; display: grid; place-items: center; font-size: 8px; font-weight: 800; }
+  .orbit-citation strong { color: #e8eae3; font-size: 11px; line-height: 1.3; }
+  .orbit-citation small { color: #8e96a8; font-size: 10px; line-height: 1.4; }
+  .orbit-citation em { color: #747d91; font-size: 9px; font-style: normal; }
+  .orbit-notes { list-style: none; margin: 0 0 18px; padding: 0; display: grid; gap: 6px; }
+  .orbit-notes li { position: relative; padding-left: 15px; color: #626775; font-size: 11px; line-height: 1.5; }
+  .orbit-notes li::before { content: ''; position: absolute; left: 0; top: 6px; width: 6px; height: 6px; border-radius: 2px; background: var(--orbit-coral); }
+  .orbit-avatar-pulse { animation: orbit-pulse 1.6s ease-in-out infinite; }
+  .orbit-writing { display: flex; align-items: center; gap: 3px; text-transform: none; letter-spacing: 0; }
+  .orbit-writing i { width: 3px; height: 3px; background: var(--orbit-lime); border-radius: 50%; animation: orbit-dot 1s ease-in-out infinite; }
+  .orbit-writing i:nth-child(2) { animation-delay: .15s; } .orbit-writing i:nth-child(3) { animation-delay: .3s; margin-right: 3px; }
+  .orbit-composer-wrap { padding: 10px 16px 16px; }
+  .orbit-composer { padding: 10px 12px 9px; border: 1px solid rgba(255,255,255,.14); border-radius: 15px; background: rgba(255,255,255,.055); box-shadow: 0 10px 35px rgba(0,0,0,.18); }
+  .orbit-composer:focus-within { border-color: rgba(215,255,63,.6); }
+  .orbit-composer textarea { display: block; width: 100%; min-height: 39px; resize: none; box-sizing: border-box; padding: 2px; color: #f7f8f0; background: transparent; border: 0; outline: 0; font: 13px/1.45 inherit; }
+  .orbit-composer textarea::placeholder { color: #747d91; }
+  .orbit-composer-actions { display: flex; align-items: end; justify-content: space-between; gap: 12px; margin-top: 5px; }
+  .orbit-composer-actions > div { display: flex; align-items: center; gap: 9px; min-width: 0; }
+  .orbit-composer-actions small { color: #687083; font-size: 8px; }
+  .orbit-attach-button { padding: 4px 7px; color: #aab0bf; background: transparent; border: 1px solid rgba(255,255,255,.12); border-radius: 6px; cursor: pointer; font: 600 9px inherit; }
+  .orbit-send-button { width: 34px; height: 34px; flex: 0 0 34px; border: 0; border-radius: 50%; color: var(--orbit-ink); background: var(--orbit-lime); cursor: pointer; font-size: 18px; transition: transform .15s; }
+  .orbit-send-button:hover:not(:disabled) { transform: translateY(-2px); }
+  .orbit-send-button:disabled { opacity: .25; cursor: not-allowed; }
+  .orbit-send-button.is-stop { background: var(--orbit-coral); font-size: 11px; }
+  .orbit-attachments { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 7px; }
+  .orbit-attachments button { padding: 5px 8px; color: #e8eae3; background: rgba(255,255,255,.07); border: 1px solid rgba(255,255,255,.12); border-radius: 999px; font: 9px inherit; cursor: pointer; }
+  .orbit-file-error { margin: 0 0 6px; color: #ff9182; font-size: 10px; }
+  .orbit-disclaimer { margin: 0; padding: 0 18px 14px; color: #687083; font-size: 9px; line-height: 1.4; text-align: center; }
+  .orbit-disclaimer span { color: var(--orbit-lime); }
+  .orbit-approval { display: flex; align-items: center; gap: 10px; margin: 4px 16px; padding: 11px 12px; color: #f7f8f0; background: rgba(255,107,87,.09); border: 1px solid rgba(255,107,87,.45); border-radius: 11px; }
+  .orbit-approval-icon { display: grid; place-items: center; width: 27px; height: 27px; border-radius: 50%; color: var(--orbit-ink); background: var(--orbit-coral); font-weight: 900; }
+  .orbit-approval > div { flex: 1; min-width: 0; }
+  .orbit-approval p, .orbit-approval strong, .orbit-approval small { display: block; margin: 0; }
+  .orbit-approval p { color: #aab0bf; font-size: 9px; text-transform: uppercase; letter-spacing: .1em; }
+  .orbit-approval strong { margin-top: 2px; font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .orbit-approval small { color: #aab0bf; font-size: 9px; }
+  .orbit-approval button { padding: 7px 9px; color: #c4c9d3; background: transparent; border: 1px solid rgba(255,255,255,.13); border-radius: 7px; cursor: pointer; font: 600 9px inherit; }
+  .orbit-approval button.is-approve { color: var(--orbit-ink); background: var(--orbit-coral); border-color: var(--orbit-coral); }
+  .orbit-specimen-card { display: flex; flex-direction: column; min-height: 680px; box-sizing: border-box; padding: 28px 26px; background: #fffdf5; border: 1px solid rgba(17,24,43,.13); border-radius: 26px; }
+  .orbit-specimen-card h2 { margin: 16px 0 10px; font-family: Georgia, serif; font-size: 28px; line-height: 1.05; font-weight: 400; letter-spacing: -.025em; }
+  .orbit-specimen-card > p:not(.orbit-page-kicker) { margin: 0; color: #626775; font-size: 12px; line-height: 1.6; }
+  .orbit-specimen-card ol { list-style: none; margin: 27px 0; padding: 0; border-top: 1px solid #dadbd4; }
+  .orbit-specimen-card li { display: flex; gap: 13px; padding: 11px 0; border-bottom: 1px solid #dadbd4; font-size: 12px; font-weight: 700; }
+  .orbit-specimen-card li span { color: var(--orbit-coral); font-size: 9px; font-weight: 800; }
+  .orbit-code-line { margin-top: auto; padding: 13px; color: #edf0e5; background: var(--orbit-ink); border-radius: 10px; overflow: hidden; }
+  .orbit-code-line code { font-size: 9px; white-space: nowrap; }
+  @keyframes orbit-pulse { 50% { box-shadow: 0 0 0 6px rgba(215,255,63,.08); } }
+  @keyframes orbit-dot { 50% { opacity: .25; transform: translateY(-2px); } }
+  @media (max-width: 1050px) {
+    .orbit-demo-grid { grid-template-columns: 1fr; }
+    .orbit-specimen-card { min-height: auto; }
+    .orbit-specimen-card ol { display: grid; grid-template-columns: 1fr 1fr; gap: 0 18px; }
+    .orbit-code-line { margin-top: 8px; }
+  }
+  @media (max-width: 720px) {
+    .custom-slots-demo { padding: 32px 14px 48px; }
+    .orbit-page-intro { display: block; }
+    .orbit-page-note { margin-top: 24px; }
+    .orbit-demo-grid { display: block; }
+    .orbit-chat-shell { min-height: 650px; }
+    .orbit-specimen-card { margin-top: 18px; }
+    .orbit-composer-actions small { display: none; }
+    .orbit-agent-name, .orbit-agent-select { display: none; }
+  }
+`;
diff --git a/apps/example/src/pages/CustomUIPage.tsx b/apps/example/src/pages/CustomUIPage.tsx
index 730b3a1a..87cca7d1 100644
--- a/apps/example/src/pages/CustomUIPage.tsx
+++ b/apps/example/src/pages/CustomUIPage.tsx
@@ -61,6 +61,40 @@ function MyChat({ isOpen, onClose, messages, onSendMessage, loading }: ChatPanel
         </CollapsibleCode>
       </div>
 
+      <div style={docStyles.definitionCard}>
+        <h2 style={docStyles.subtitle}>Component Slots</h2>
+        <p style={docStyles.text}>
+          Override only the regions you need. Render <code style={docStyles.code}>children</code>{' '}
+          to decorate the built-in UI, or omit it to replace that region completely.
+        </p>
+        <CollapsibleCode>
+{`import type {
+  ChatMessageSlotProps,
+  ChatComposerSlotProps,
+} from '@meetsmore-oss/use-ai-client';
+
+function Message({ message, children }: ChatMessageSlotProps) {
+  return <div className={\`message message-\${message.role}\`}>{children}</div>;
+}
+
+function Composer({ input, onInputChange, onSend, canSend }: ChatComposerSlotProps) {
+  return (
+    <form onSubmit={(event) => { event.preventDefault(); onSend(); }}>
+      <textarea value={input} onChange={(event) => onInputChange(event.target.value)} />
+      <button disabled={!canSend}>Send</button>
+    </form>
+  );
+}
+
+<UseAIProvider chatComponents={{ Message, Composer }} serverUrl="...">
+  <App />
+</UseAIProvider>
+
+// Override one chat instance (takes precedence over the provider)
+<UseAIChat components={{ EmptyState: MyEmptyState }} />`}
+        </CollapsibleCode>
+      </div>
+
       <div style={docStyles.definitionCard}>
         <h2 style={docStyles.subtitle}>Disable Components</h2>
         <CollapsibleCode>
diff --git a/apps/example/src/pages/orbitTimeline.tsx b/apps/example/src/pages/orbitTimeline.tsx
new file mode 100644
index 00000000..e1c35da9
--- /dev/null
+++ b/apps/example/src/pages/orbitTimeline.tsx
@@ -0,0 +1,353 @@
+import React from 'react';
+import type { ChatStreamingPart, PersistedMessage } from '@meetsmore-oss/use-ai-client';
+
+/**
+ * Rendering pieces for the component-slots demo.
+ *
+ * The built-in `Message` slot renders one turn as a single bubble. These pieces
+ * take the same turn apart again using `sourceMessages` and lay it out as a
+ * timeline: reasoning, tool cards and prose appear in the order the model
+ * produced them, and the sources a tool returned are pinned under the answer.
+ */
+
+// ── LaTeX ───────────────────────────────────────────────────────────────────
+
+const SYMBOLS: Record<string, string> = {
+  alpha: 'α', beta: 'β', gamma: 'γ', delta: 'δ', theta: 'θ', lambda: 'λ',
+  mu: 'μ', pi: 'π', rho: 'ρ', sigma: 'σ', phi: 'φ', omega: 'ω',
+  Delta: 'Δ', Sigma: 'Σ', Omega: 'Ω',
+  times: '×', cdot: '·', pm: '±', leq: '≤', geq: '≥', neq: '≠',
+  approx: '≈', infty: '∞', rightarrow: '→', partial: '∂', int: '∫', sum: '∑',
+};
+
+/** Reads a `{...}` group starting at `i`, returning its body and the index after it. */
+function readGroup(tex: string, i: number): [string, number] {
+  if (tex[i] !== '{') return [tex[i] ?? '', i + 1];
+  let depth = 0;
+  for (let j = i; j < tex.length; j++) {
+    if (tex[j] === '{') depth++;
+    else if (tex[j] === '}' && --depth === 0) return [tex.slice(i + 1, j), j + 1];
+  }
+  return [tex.slice(i + 1), tex.length];
+}
+
+/**
+ * A deliberately small TeX subset: fractions, roots, super/subscripts and the
+ * symbols above. Enough to show that the slot owns the renderer; a real app
+ * would hand the same string to KaTeX or MathJax here.
+ */
+function renderMath(tex: string, keyPrefix: string): React.ReactNode[] {
+  const out: React.ReactNode[] = [];
+  let buffer = '';
+  let i = 0;
+
+  const flush = () => {
+    if (buffer) {
+      out.push(buffer);
+      buffer = '';
+    }
+  };
+
+  while (i < tex.length) {
+    const char = tex[i];
+
+    if (char === '\\') {
+      const command = /^[a-zA-Z]+/.exec(tex.slice(i + 1))?.[0];
+      if (!command) { buffer += tex[i + 1] ?? ''; i += 2; continue; }
+      i += 1 + command.length;
+
+      if (command === 'frac') {
+        const [numerator, afterNum] = readGroup(tex, i);
+        const [denominator, afterDen] = readGroup(tex, afterNum);
+        i = afterDen;
+        flush();
+        out.push(
+          <span className="orbit-frac" key={`${keyPrefix}-f${i}`}>
+            <span>{renderMath(numerator, `${keyPrefix}-fn${i}`)}</span>
+            <span>{renderMath(denominator, `${keyPrefix}-fd${i}`)}</span>
+          </span>
+        );
+        continue;
+      }
+
+      if (command === 'sqrt') {
+        const [body, after] = readGroup(tex, i);
+        i = after;
+        flush();
+        out.push(
+          <span className="orbit-sqrt" key={`${keyPrefix}-r${i}`}>
+            {renderMath(body, `${keyPrefix}-rb${i}`)}
+          </span>
+        );
+        continue;
+      }
+
+      buffer += SYMBOLS[command] ?? command;
+      continue;
+    }
+
+    if (char === '^' || char === '_') {
+      const [body, after] = readGroup(tex, i + 1);
+      i = after;
+      flush();
+      const Tag = char === '^' ? 'sup' : 'sub';
+      out.push(<Tag key={`${keyPrefix}-s${i}`}>{renderMath(body, `${keyPrefix}-sb${i}`)}</Tag>);
+      continue;
+    }
+
+    buffer += char;
+    i++;
+  }
+
+  flush();
+  return out;
+}
+
+/**
+ * Assistant prose with `$…$` inline and `$$…$$` display math pulled out.
+ *
+ * The answer is laid out one line per element instead of one node for the whole
+ * text. Rewriting a text node collapses any live range inside it: the DOM spec
+ * moves a range's offsets to the start of the replaced data, so a selection
+ * dies. Holding the whole answer in a single node would rewrite it on every
+ * token and drop the user's selection each time. Split this way, React leaves
+ * a line whose string did not change untouched, so everything already written
+ * stays selectable while the answer continues. Only the line currently being
+ * written churns.
+ *
+ * Split results are kept unfiltered for the same reason: dropping the empty
+ * strings would renumber the keys as the answer grows.
+ */
+export function OrbitProse({ text }: { text: string }) {
+  const segments = text.split(/(\$\$[^$]+\$\$|\$[^$\n]+\$)/g);
+
+  return (
+    <div className="orbit-message-bubble" data-testid="orbit-prose">
+      {segments.map((segment, index) => {
+        if (segment.startsWith('$$') && segment.endsWith('$$')) {
+          return (
+            <span className="orbit-math is-block" key={index} data-testid="orbit-math-block">
+              {renderMath(segment.slice(2, -2).trim(), `b${index}`)}
+            </span>
+          );
+        }
+        if (segment.startsWith('$') && segment.endsWith('$') && segment.length > 2) {
+          return (
+            <span className="orbit-math" key={index} data-testid="orbit-math-inline">
+              {renderMath(segment.slice(1, -1).trim(), `i${index}`)}
+            </span>
+          );
+        }
+        // The separators are kept as their own nodes; the bubble is pre-wrap,
+        // so the rendered text reads exactly as it did in one node.
+        return segment.split(/(\n)/).map((line, lineIndex) => (
+          <span key={`${index}-${lineIndex}`}>{line}</span>
+        ));
+      })}
+    </div>
+  );
+}
+
+// ── Timeline ────────────────────────────────────────────────────────────────
+
+export interface TimelineEntry {
+  kind: 'reasoning' | 'text' | 'tool';
+  key: string;
+  text?: string;
+  toolCallId?: string;
+  name?: string;
+  args?: unknown;
+  result?: unknown;
+}
+
+function parseJson(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function messageText(content: PersistedMessage['content']): string {
+  if (typeof content === 'string') return content;
+  return content.map((part) => ('text' in part ? part.text : '')).join('');
+}
+
+/**
+ * Flattens a turn into the order the model produced it. Reasoning is placed
+ * before the text of the step it belongs to, which is the only ordering the
+ * persisted shape records (reasoning lives in its own field, not inline).
+ *
+ * Entry keys are ordinals within the turn rather than message ids, so that
+ * `buildStreamingTimeline` can produce the same key for the same entry. Only
+ * the final step's id is known while a run is in flight; the earlier steps get
+ * theirs when the turn is persisted, so any id-derived key would change under
+ * React the moment the run finishes and remount the prose, dropping a
+ * selection the user was making inside it.
+ */
+export function buildTimeline(sourceMessages: PersistedMessage[]): TimelineEntry[] {
+  const results = new Map<string, unknown>();
+  for (const message of sourceMessages) {
+    if (message.role === 'tool' && message.toolCallId) {
+      results.set(message.toolCallId, parseJson(messageText(message.content)));
+    }
+  }
+
+  const entries: TimelineEntry[] = [];
+  const ordinals = { reasoning: 0, text: 0 };
+  for (const message of sourceMessages) {
+    if (message.role !== 'assistant') continue;
+
+    message.reasoningParts?.forEach((part) => {
+      if (part.text.trim()) {
+        entries.push({ kind: 'reasoning', key: `r${ordinals.reasoning++}`, text: part.text });
+      }
+    });
+
+    const text = messageText(message.content).trim();
+    if (text) {
+      entries.push({ kind: 'text', key: `t${ordinals.text++}`, text });
+    }
+
+    message.toolCalls?.forEach((call) => {
+      entries.push({
+        kind: 'tool',
+        key: call.id,
+        toolCallId: call.id,
+        name: call.function.name,
+        args: parseJson(call.function.arguments),
+        result: results.get(call.id),
+      });
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * The same flattening for a run still in flight. The parts already arrive in
+ * order, so this only reshapes them; results are not known yet, which is what
+ * leaves the tool cards in their pending state.
+ *
+ * Ordinals are counted exactly as `buildTimeline` counts them, which is what
+ * keeps an entry's key stable when the run finishes and the persisted turn
+ * takes over. Both walk the same turn in the same order and drop blank text the
+ * same way, so the nth text entry here is the nth text entry there.
+ */
+export function buildStreamingTimeline(parts: ChatStreamingPart[]): TimelineEntry[] {
+  const ordinals = { reasoning: 0, text: 0 };
+
+  return parts.flatMap((part) => {
+    if (part.kind === 'tool_call') {
+      return [{
+        kind: 'tool' as const,
+        key: part.toolCallId,
+        toolCallId: part.toolCallId,
+        name: part.name,
+        args: parseJson(part.args),
+      }];
+    }
+    if (!part.text.trim()) return [];
+
+    const key = part.kind === 'reasoning'
+      ? `r${ordinals.reasoning++}`
+      : `t${ordinals.text++}`;
+    return [{ kind: part.kind, key, text: part.text }];
+  });
+}
+
+export function OrbitReasoning({ text, open }: { text: string; open?: boolean }) {
+  return (
+    <details className="orbit-reasoning" data-testid="orbit-reasoning" open={open}>
+      <summary>Thinking</summary>
+      <p>{text}</p>
+    </details>
+  );
+}
+
+export function OrbitToolCard({ entry }: { entry: TimelineEntry }) {
+  // While a call streams its arguments are half-parsed JSON, so only show them
+  // once they parse into an object.
+  const args =
+    typeof entry.args === 'object' && entry.args !== null && !Array.isArray(entry.args)
+      ? (entry.args as Record<string, unknown>)
+      : undefined;
+  const pending = entry.result === undefined;
+
+  return (
+    <div className={`orbit-tool-card ${pending ? 'is-pending' : ''}`} data-testid="orbit-tool-card">
+      <div className="orbit-tool-head">
+        <span className="orbit-tool-glyph" aria-hidden="true">⌘</span>
+        <strong>{entry.name}</strong>
+        <span className="orbit-tool-state">{pending ? 'running' : 'done'}</span>
+      </div>
+      {args && Object.keys(args).length > 0 && (
+        <dl className="orbit-tool-args">
+          {Object.entries(args).map(([key, value]) => (
+            <div key={key}>
+              <dt>{key}</dt>
+              <dd>{typeof value === 'string' ? value : JSON.stringify(value)}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+    </div>
+  );
+}
+
+// ── Citations ───────────────────────────────────────────────────────────────
+
+export interface OrbitSource {
+  title: string;
+  url: string;
+  snippet?: string;
+}
+
+function isSource(value: unknown): value is OrbitSource {
+  return (
+    typeof value === 'object' && value !== null &&
+    typeof (value as OrbitSource).title === 'string' &&
+    typeof (value as OrbitSource).url === 'string'
+  );
+}
+
+/** Collects the `sources` a tool returned, de-duplicated by url. */
+export function collectSources(entries: TimelineEntry[]): OrbitSource[] {
+  const byUrl = new Map<string, OrbitSource>();
+
+  for (const entry of entries) {
+    const sources = (entry.result as { sources?: unknown })?.sources;
+    if (!Array.isArray(sources)) continue;
+    for (const source of sources) {
+      if (isSource(source) && !byUrl.has(source.url)) byUrl.set(source.url, source);
+    }
+  }
+
+  return [...byUrl.values()];
+}
+
+export function OrbitCitations({ sources }: { sources: OrbitSource[] }) {
+  return (
+    <div className="orbit-citations" data-testid="orbit-citations">
+      <p className="orbit-kicker">SOURCES</p>
+      <div className="orbit-citation-row">
+        {sources.map((source, index) => (
+          <a
+            key={source.url}
+            className="orbit-citation"
+            href={source.url}
+            target="_blank"
+            rel="noreferrer"
+            data-testid="orbit-citation"
+          >
+            <span>{index + 1}</span>
+            <strong>{source.title}</strong>
+            {source.snippet && <small>{source.snippet}</small>}
+            <em>{new URL(source.url).hostname}</em>
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/example/src/providers/NavigationAIProvider.tsx b/apps/example/src/providers/NavigationAIProvider.tsx
index 6ed8c37d..f5e664fd 100644
--- a/apps/example/src/providers/NavigationAIProvider.tsx
+++ b/apps/example/src/providers/NavigationAIProvider.tsx
@@ -15,6 +15,7 @@ const AVAILABLE_PAGES = [
   { path: '/programmatic-chat', label: 'Programmatic Chat', description: 'Sending messages programmatically via sendMessage()' },
   { path: '/chat-history', label: 'Chat History', description: 'localStorage persistence, ChatRepository, chat management' },
   { path: '/slash-commands', label: 'Slash Commands', description: 'Slash command autocomplete and custom command repository' },
+  { path: '/custom-slots-demo', label: 'Component Slots Demo', description: 'Fully custom chat UI built with Header, Message, Composer, and other component slots' },
   { path: '/custom-ui', label: 'Custom UI', description: 'CustomButton, CustomChat props and onOpenChange callback' },
   { path: '/theme-i18n', label: 'Theme & i18n', description: 'Theme colors, strings localization, error messages' },
   { path: '/suggestions', label: 'Suggestions', description: 'Empty chat suggestions aggregated from all components' },
diff --git a/packages/client/src/components/UseAIChat.test.tsx b/packages/client/src/components/UseAIChat.test.tsx
index 892ed735..d647cf31 100644
--- a/packages/client/src/components/UseAIChat.test.tsx
+++ b/packages/client/src/components/UseAIChat.test.tsx
@@ -58,6 +58,21 @@ function createContextValue(overrides: Partial<ChatUIContextValue> = {}): ChatUI
 }
 
 describe('UseAIChat', () => {
+  test('prefers instance component overrides over provider-level overrides', () => {
+    const ProviderHeader = () => <div data-testid="provider-header" />;
+    const InstanceHeader = () => <div data-testid="instance-header" />;
+    const ctx = createContextValue({ components: { Header: ProviderHeader } });
+
+    const { getByTestId, queryByTestId } = render(
+      <__UseAIChatContext.Provider value={ctx}>
+        <UseAIChat components={{ Header: InstanceHeader }} />
+      </__UseAIChatContext.Provider>
+    );
+
+    expect(getByTestId('instance-header')).toBeInTheDocument();
+    expect(queryByTestId('provider-header')).toBeNull();
+  });
+
   test('passes streaming reasoning through to UseAIChatPanel', () => {
     const ctx = createContextValue({
       loading: true,
diff --git a/packages/client/src/components/UseAIChat.tsx b/packages/client/src/components/UseAIChat.tsx
index 1a35bc87..c587cd42 100644
--- a/packages/client/src/components/UseAIChat.tsx
+++ b/packages/client/src/components/UseAIChat.tsx
@@ -7,6 +7,8 @@ import type { AgentInfo, FeedbackValue, ToolAnnotations, EnabledFeatures } from
 import type { FileUploadConfig, FileAttachment, FileProcessingState } from '../fileUpload/types';
 import type { SavedCommand } from '../commands/types';
 import type { Chat } from '../providers/chatRepository/types';
+import type { UseAIChatComponentOverrides } from './chatSlots';
+import type { ChatStreamingPart, ExecutingToolDisplay } from '../hooks/useServerEvents';
 
 /**
  * Internal context value for chat UI state.
@@ -36,6 +38,8 @@ export interface ChatUIContextValue {
    * streaming bubble and the persisted one be the same element.
    */
   streamingMessageId: string | null;
+  /** The in-flight answer split into ordered parts; empty between runs. */
+  streamingParts: ChatStreamingPart[];
   /** Aggregated suggestions from all useAI hooks */
   suggestions: string[];
   /** File upload configuration */
@@ -94,7 +98,7 @@ export interface ChatUIContextValue {
   /** Tool execution and approval state */
   tools: {
     /** Currently executing tool info for status display */
-    executing: { displayText: string } | null;
+    executing: ExecutingToolDisplay | null;
     /** Pending tool approval */
     pending: {
       /** All tools awaiting approval */
@@ -129,6 +133,8 @@ export interface ChatUIContextValue {
    * @default 'enter'
    */
   submitMode?: SubmitMode;
+  /** Provider-level component overrides for the built-in chat UI. */
+  components?: UseAIChatComponentOverrides;
 }
 
 /**
@@ -169,6 +175,11 @@ export interface UseAIChatProps {
    * - `'mod-enter'`: Enter inserts a newline. Cmd/Ctrl+Enter submits.
    */
   submitMode?: SubmitMode;
+  /**
+   * Replace individual regions of the built-in chat UI. Instance overrides
+   * take precedence over `UseAIProvider.chatComponents`.
+   */
+  components?: UseAIChatComponentOverrides;
 }
 
 /**
@@ -196,9 +207,14 @@ export interface UseAIChatProps {
  * </UseAIProvider>
  * ```
  */
-export function UseAIChat({ floating = false, submitMode }: UseAIChatProps) {
+export function UseAIChat({ floating = false, submitMode, components }: UseAIChatProps) {
   const ctx = useChatUIContext();
 
+  const mergedComponents = {
+    ...ctx.components,
+    ...components,
+  };
+
   const chatPanelProps = {
     submitMode: submitMode ?? ctx.submitMode,
     onSendMessage: ctx.sendMessage,
@@ -208,6 +224,7 @@ export function UseAIChat({ floating = false, submitMode }: UseAIChatProps) {
     streamingText: ctx.streamingText,
     streamingReasoning: ctx.streamingReasoning,
     streamingMessageId: ctx.streamingMessageId,
+    streamingParts: ctx.streamingParts,
     currentChatId: ctx.history.currentId,
     onNewChat: ctx.history.create,
     onLoadChat: ctx.history.load,
@@ -233,6 +250,7 @@ export function UseAIChat({ floating = false, submitMode }: UseAIChatProps) {
     onApproveToolCall: ctx.tools.pending.tools.length > 0 ? ctx.tools.pending.approveAll : undefined,
     onRejectToolCall: ctx.tools.pending.tools.length > 0 ? ctx.tools.pending.rejectAll : undefined,
     onAbort: ctx.abortRun,
+    components: mergedComponents,
   };
 
   if (floating) {
diff --git a/packages/client/src/components/UseAIChatPanel.tsx b/packages/client/src/components/UseAIChatPanel.tsx
index 8ffdf2f2..98871868 100644
--- a/packages/client/src/components/UseAIChatPanel.tsx
+++ b/packages/client/src/components/UseAIChatPanel.tsx
@@ -1,23 +1,30 @@
 import React, { useState, useRef, useEffect } from 'react';
-import type { Chat, PersistedMessage, PersistedMessageContent, PersistedContentPart, MessageDisplayMode } from '../providers/chatRepository/types';
-import { getTextFromContent, getDisplayTextFromContent } from '../utils/messageContent';
-import { mergeAssistantMessagesForDisplay } from '../utils/mergeAssistantMessages';
-import { shouldSubmitOnEnter, type SubmitMode } from '../utils/keyboard';
-import type { AgentInfo, FeedbackValue, ToolAnnotations, EnabledFeatures } from '../types';
+import type { Chat, PersistedMessage } from '../providers/chatRepository/types';
+import { getDisplayTextFromContent } from '../utils/messageContent';
+import { mergeAssistantMessagesForDisplay, type MergedMessage } from '../utils/mergeAssistantMessages';
+import type { SubmitMode } from '../utils/keyboard';
+import type { AgentInfo, FeedbackValue, EnabledFeatures } from '../types';
 import { DEFAULT_ENABLED_FEATURES } from '../types';
 import type { FileAttachment, FileUploadConfig, FileProcessingState } from '../fileUpload/types';
-import { MarkdownContent } from './MarkdownContent';
-import { FileChip, FilePlaceholder } from './FileChip';
 import type { SavedCommand } from '../commands/types';
 import { useSlashCommands } from '../hooks/useSlashCommands';
 import { useFileUpload } from '../hooks/useFileUpload';
-import { useDropdownState } from '../hooks/useDropdownState';
-import { useTheme, useStrings } from '../theme';
+import { useStrings, useTheme } from '../theme';
 import type { UseAIStrings, UseAITheme } from '../theme';
-import { ToolApprovalDialog } from './ToolApprovalDialog';
-import { Reasoning } from './Reasoning';
-
-import type { ReasoningPart } from '../types';
+import type { ChatStreamingPart, ExecutingToolDisplay } from '../hooks/useServerEvents';
+import {
+  Slot,
+  DefaultHeader,
+  DefaultEmptyState,
+  DefaultMessage,
+  DefaultPendingIndicator,
+  DefaultComposer,
+  DefaultToolApproval,
+  DefaultDisclaimer,
+  type ChatSaveAsCommand,
+  type ChatToolApproval,
+  type UseAIChatComponentOverrides,
+} from './chatSlots';
 
 // Re-export types for backwards compatibility
 export type UseAIChatPanelStrings = UseAIStrings;
@@ -28,122 +35,15 @@ export type UseAIChatPanelTheme = UseAITheme;
  */
 type Message = PersistedMessage;
 
-/**
- * Props for the FeedbackButton component.
- */
-interface FeedbackButtonProps {
-  /** The type of feedback this button represents */
-  type: 'upvote' | 'downvote';
-  /** Whether this feedback type is currently selected */
-  isSelected: boolean;
-  /** Callback when clicked */
-  onClick: () => void;
-  /** Color when selected */
-  selectedColor: string;
-  /** Color when not selected */
-  unselectedColor: string;
-}
-
-/**
- * Thumbs up/down feedback button with pop animation.
- */
-function FeedbackButton({ type, isSelected, onClick, selectedColor, unselectedColor }: FeedbackButtonProps) {
-  const buttonRef = useRef<HTMLButtonElement>(null);
-
-  const handleClick = () => {
-    // Pop animation only on select, not de-select
-    if (!isSelected && buttonRef.current) {
-      buttonRef.current.style.transform = 'scale(1.3)';
-      setTimeout(() => {
-        if (buttonRef.current) {
-          buttonRef.current.style.transform = 'scale(1)';
-        }
-      }, 150);
-    }
-    onClick();
-  };
-
-  const thumbsUpPath = "M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9a2 2 0 0 0-2-2.3zM7 22H4a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h3";
-  const thumbsDownPath = "M10 15v4a3 3 0 0 0 3 3l4-9V2H5.72a2 2 0 0 0-2 1.7l-1.38 9a2 2 0 0 0 2 2.3zm7-13h2.67A2.31 2.31 0 0 1 22 4v7a2.31 2.31 0 0 1-2.33 2H17";
-
-  return (
-    <button
-      ref={buttonRef}
-      data-testid={`feedback-${type}`}
-      onClick={handleClick}
-      title={type === 'upvote' ? 'Good response' : 'Poor response'}
-      style={{
-        background: 'transparent',
-        border: 'none',
-        padding: '4px',
-        cursor: 'pointer',
-        color: isSelected ? selectedColor : unselectedColor,
-        opacity: isSelected ? 1 : 0.5,
-        transition: 'all 0.15s',
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'center',
-        borderRadius: '4px',
-        transform: 'scale(1)',
-      }}
-      onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-        if (!isSelected) {
-          e.currentTarget.style.opacity = '0.8';
-          e.currentTarget.style.color = selectedColor;
-        }
-      }}
-      onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-        if (!isSelected) {
-          e.currentTarget.style.opacity = '0.5';
-          e.currentTarget.style.color = unselectedColor;
-        }
-      }}
-    >
-      <svg
-        width="14"
-        height="14"
-        viewBox="0 0 24 24"
-        fill={isSelected ? 'currentColor' : 'none'}
-        stroke="currentColor"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      >
-        <path d={type === 'upvote' ? thumbsUpPath : thumbsDownPath} />
-      </svg>
-    </button>
-  );
-}
-
-/**
- * Helper that checks whether `content` includes a file attachment. Covers both
- * the metadata-only `file` and the ref-based `attachment_ref`; both are rendered as
- * a name/size FilePlaceholder.
- */
-function hasFileContent(content: PersistedMessageContent): content is PersistedContentPart[] {
-  return (
-    Array.isArray(content) &&
-    content.some(part => part.type === 'file' || part.type === 'attachment_ref')
-  );
-}
-
-/** Extracts name + size from a file-bearing persisted part for the FilePlaceholder shown on reload. */
-function fileChipInfo(part: PersistedContentPart): { name: string; size: number } | null {
-  if (part.type === 'file') {
-    return { name: part.file.name, size: part.file.size };
-  }
-  if (part.type === 'attachment_ref') {
-    return { name: part.name, size: part.size };
-  }
-  return null;
-}
-
 /**
  * A message as shown in the panel. `streaming` marks the provisional entry
  * for the answer that is still arriving; it has no timestamp, feedback
  * buttons or persisted reasoning parts yet.
  */
-type DisplayMessage = PersistedMessage & { streaming?: boolean };
+type DisplayMessage = MergedMessage & { streaming?: boolean };
+
+/** Stable identity so an omitted `streamingParts` does not re-render the slot. */
+const EMPTY_STREAMING_PARTS: ChatStreamingPart[] = [];
 
 /** Key for the provisional streaming message when no persisted id is known. */
 const PROVISIONAL_MESSAGE_ID = 'streaming-answer';
@@ -169,6 +69,11 @@ export interface UseAIChatPanelProps {
   streamingText?: string;
   /** Currently streaming reasoning text from extended thinking */
   streamingReasoning?: string;
+  /**
+   * The in-flight answer split into ordered parts. Handed to the `Message`
+   * slot; the built-in bubble renders `streamingText`/`streamingReasoning`.
+   */
+  streamingParts?: ChatStreamingPart[];
   /**
    * Id the streaming answer will be persisted under. While set, the streaming
    * answer renders as a provisional message with this id, so when the persisted
@@ -207,18 +112,13 @@ export interface UseAIChatPanelProps {
   /** Optional close button to render in header (for floating mode) */
   closeButton?: React.ReactNode;
   /** Currently executing tool info for status display */
-  executingTool?: { displayText: string } | null;
+  executingTool?: ExecutingToolDisplay | null;
   /** Whether feedback buttons are enabled (requires Langfuse on server) */
   feedbackEnabled?: boolean;
   /** Callback when user submits feedback on a message */
   onFeedback?: (messageId: string, traceId: string, feedback: FeedbackValue) => void;
   /** Pending tool approvals awaiting user confirmation */
-  pendingApprovals?: Array<{
-    toolCallId: string;
-    toolCallName: string;
-    toolCallArgs: Record<string, unknown>;
-    annotations?: ToolAnnotations;
-  }>;
+  pendingApprovals?: ChatToolApproval[];
   /** Callback to approve all pending tool calls */
   onApproveToolCall?: () => void;
   /** Callback to reject all pending tool calls */
@@ -237,6 +137,8 @@ export interface UseAIChatPanelProps {
    * @default 'enter'
    */
   submitMode?: SubmitMode;
+  /** Replace individual regions while retaining the built-in behavior by default. */
+  components?: UseAIChatComponentOverrides;
 }
 
 /**
@@ -251,6 +153,7 @@ export function UseAIChatPanel({
   connected,
   streamingText = '',
   streamingReasoning = '',
+  streamingParts = EMPTY_STREAMING_PARTS,
   streamingMessageId = null,
   currentChatId,
   onNewChat,
@@ -278,6 +181,7 @@ export function UseAIChatPanel({
   onApproveToolCall,
   onRejectToolCall,
   submitMode = 'enter',
+  components,
 }: UseAIChatPanelProps) {
   const strings = useStrings();
   const theme = useTheme();
@@ -292,6 +196,7 @@ export function UseAIChatPanel({
   // This preserves per-step data structure (for LLM context) while showing
   // a unified bubble to the user.
   const displayMessages = mergeAssistantMessagesForDisplay(messages);
+  const showInputDisclaimer = !!features.inputDisclaimer && displayMessages.length > 0;
 
   // The streaming answer is shown as a provisional assistant message under the
   // id it will be persisted with. When the persisted message arrives it takes
@@ -307,6 +212,7 @@ export function UseAIChatPanel({
           role: 'assistant',
           content: streamingText,
           createdAt: PROVISIONAL_CREATED_AT,
+          sourceMessages: [],
           streaming: true,
         }
       : null;
@@ -315,15 +221,8 @@ export function UseAIChatPanel({
     : displayMessages;
 
   const [input, setInput] = useState('');
-  const chatHistoryDropdown = useDropdownState();
-  const agentDropdown = useDropdownState();
-  const [chatHistory, setChatHistory] = useState<Array<Omit<Chat, 'messages'>>>([]);
   const messagesEndRef = useRef<HTMLDivElement>(null);
   const [displayedSuggestions, setDisplayedSuggestions] = useState<string[]>([]);
-  const textareaRef = useRef<HTMLTextAreaElement>(null);
-
-  // Message hover state for save button
-  const [hoveredMessageId, setHoveredMessageId] = useState<string | null>(null);
 
   // File upload hook - includes processing state for transformation progress
   const {
@@ -359,21 +258,6 @@ export function UseAIChatPanel({
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
   }, [messages]);
 
-  const maxTextareaHeight = 160;
-
-  // Auto-resize textarea based on content
-  useEffect(() => {
-    const textarea = textareaRef.current;
-    if (!textarea) return;
-
-    // Reset to single row to measure actual content height
-    textarea.style.height = 'auto';
-
-    // Calculate new height based on scrollHeight (clamped to max)
-    const newHeight = Math.min(textarea.scrollHeight, maxTextareaHeight);
-    textarea.style.height = `${newHeight}px`;
-  }, [input]);
-
   // Randomly select up to 4 suggestions when messages become empty
   useEffect(() => {
     if (!suggestions || suggestions.length === 0) {
@@ -397,46 +281,40 @@ export function UseAIChatPanel({
     slashCommands.closeAutocomplete();
   };
 
-  // Handle input change with slash command detection
-  const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-    const value = e.target.value;
+  const handleInputValueChange = (value: string) => {
     setInput(value);
     slashCommands.handleInputChange(value);
   };
 
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    // Let slash commands hook handle keyboard navigation
-    if (slashCommands.handleKeyDown(e)) {
-      return;
-    }
-
-    if (shouldSubmitOnEnter(e, submitMode)) {
-      e.preventDefault();
-      handleSend();
-    }
-  };
-
-  const handleNewChat = async () => {
-    if (onNewChat) {
-      await onNewChat();
-    }
-  };
-
-  const handleDeleteChat = async () => {
-    if (onDeleteChat && currentChatId && confirm(strings.header.deleteConfirm)) {
-      await onDeleteChat(currentChatId);
-      if (onNewChat) {
-        await onNewChat();
-      }
-    }
+  /**
+   * The save-as-slash-command affordance for a user message, or undefined when
+   * the feature is off, the host takes no commands, or the message is not one
+   * the user wrote.
+   */
+  const saveAsCommandFor = (message: DisplayMessage): ChatSaveAsCommand | undefined => {
+    if (message.role !== 'user' || !slashCommandsEnabled || !onSaveCommand) return undefined;
+    const text = getDisplayTextFromContent(message.content);
+
+    return {
+      isEditing: slashCommands.isSavingCommand(message.id),
+      start: () => slashCommands.startSavingCommand(message.id, text),
+      save: (name: string) => onSaveCommand(name, text),
+      editor: slashCommands.renderInlineSaveUI({ messageId: message.id, messageText: text }),
+    };
   };
 
-  const handleLoadChat = async (chatId: string) => {
-    if (onLoadChat) {
-      await onLoadChat(chatId);
-      chatHistoryDropdown.close();
-    }
-  };
+  const composerPlaceholder = !connected
+    ? strings.input.connectingPlaceholder
+    : loading
+      ? `${executingTool?.displayText ?? strings.input.thinking}...`
+      : strings.input.placeholder;
+  const canSend = !!(
+    connected &&
+    !loading &&
+    pendingApprovals.length === 0 &&
+    (input.trim() || attachments.length > 0)
+  );
+  const canAbort = loading && !!onAbort;
 
   return (
     <div
@@ -459,374 +337,24 @@ export function UseAIChatPanel({
       {DropZoneOverlay}
 
       {/* Header */}
-      <div
-        style={{
-          padding: '12px 16px',
-          borderBottom: `1px solid ${theme.borderColor}`,
-          background: theme.backgroundColor,
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'space-between',
-          gap: '12px',
+      <Slot
+        component={components?.Header}
+        fallback={DefaultHeader}
+        props={{
+          connected,
+          messages: displayMessages,
+          currentChatId: currentChatId ?? null,
+          availableAgents: availableAgents ?? [],
+          defaultAgent: defaultAgent ?? null,
+          selectedAgent: selectedAgent ?? null,
+          closeButton,
+          onNewChat,
+          onDeleteChat,
+          onListChats,
+          onLoadChat,
+          onAgentChange,
         }}
-      >
-        {/* Left side: Chat dropdown */}
-        <div style={{ flex: 1, minWidth: 0, position: 'relative' }}>
-          {onListChats ? (
-            <button
-              data-testid="chat-history-dropdown-button"
-              onClick={async () => {
-                const chats = await onListChats();
-                setChatHistory(chats);
-                chatHistoryDropdown.toggle();
-              }}
-              style={{
-                background: 'transparent',
-                border: 'none',
-                padding: '6px 8px',
-                cursor: 'pointer',
-                display: 'flex',
-                alignItems: 'center',
-                gap: '8px',
-                fontSize: '14px',
-                fontWeight: '600',
-                color: theme.textColor,
-                borderRadius: '6px',
-                transition: 'background 0.2s',
-                width: '100%',
-                textAlign: 'left',
-                overflow: 'hidden',
-              }}
-              onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                e.currentTarget.style.background = theme.hoverBackground;
-              }}
-              onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                e.currentTarget.style.background = 'transparent';
-              }}
-            >
-              <span style={{
-                overflow: 'hidden',
-                textOverflow: 'ellipsis',
-                whiteSpace: 'nowrap',
-                flex: 1,
-                minWidth: 0,
-              }}>
-                {/* Get current chat title */}
-                {(() => {
-                  if (displayMessages.length > 0) {
-                    const firstUserMsg = displayMessages.find((m) => m.role === 'user');
-                    if (firstUserMsg) {
-                      const textContent = getDisplayTextFromContent(firstUserMsg.content);
-                      const maxLength = 30;
-                      return textContent.length > maxLength
-                        ? textContent.substring(0, maxLength) + '...'
-                        : textContent || strings.header.newChat;
-                    }
-                  }
-                  return strings.header.newChat;
-                })()}
-              </span>
-              <svg width="12" height="12" viewBox="0 0 12 12" fill="none" style={{ flexShrink: 0 }}>
-                <path d="M3 4.5L6 7.5L9 4.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
-              </svg>
-            </button>
-          ) : (
-            <div style={{ fontSize: '14px', fontWeight: '600', color: theme.textColor, padding: '6px 8px' }}>
-              {strings.header.aiAssistant}
-            </div>
-          )}
-        </div>
-
-        {/* Right side: Actions */}
-        <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}>
-          {/* Model selector */}
-          {availableAgents && availableAgents.length > 1 && onAgentChange && (
-            <div style={{ position: 'relative' }}>
-              <button
-                data-testid="agent-selector"
-                onClick={agentDropdown.toggle}
-                style={{
-                  background: 'transparent',
-                  border: 'none',
-                  padding: '6px 8px',
-                  cursor: 'pointer',
-                  display: 'flex',
-                  alignItems: 'center',
-                  gap: '4px',
-                  fontSize: '13px',
-                  fontWeight: '500',
-                  color: theme.secondaryTextColor,
-                  borderRadius: '6px',
-                  transition: 'all 0.2s',
-                }}
-                onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                  e.currentTarget.style.background = theme.hoverBackground;
-                  e.currentTarget.style.color = theme.textColor;
-                }}
-                onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                  e.currentTarget.style.background = 'transparent';
-                  e.currentTarget.style.color = theme.secondaryTextColor;
-                }}
-                title="Select AI model"
-              >
-                <span style={{
-                  overflow: 'hidden',
-                  textOverflow: 'ellipsis',
-                  whiteSpace: 'nowrap',
-                  maxWidth: '120px',
-                }}>
-                  {(() => {
-                    const agent = availableAgents.find((a: AgentInfo) => a.id === (selectedAgent ?? defaultAgent));
-                    return agent?.name || 'AI';
-                  })()}
-                </span>
-                <svg width="10" height="10" viewBox="0 0 12 12" fill="none" style={{ flexShrink: 0 }}>
-                  <path d="M3 4.5L6 7.5L9 4.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
-                </svg>
-              </button>
-
-              {/* Agent Selector Dropdown */}
-              {agentDropdown.isOpen && (
-                <div
-                  style={{
-                    position: 'absolute',
-                    top: '100%',
-                    left: '50%',
-                    transform: 'translateX(-50%)',
-                    marginTop: '4px',
-                    minWidth: '180px',
-                    maxWidth: '280px',
-                    background: theme.backgroundColor,
-                    borderRadius: '8px',
-                    boxShadow: '0 4px 16px rgba(0, 0, 0, 0.15)',
-                    zIndex: 1003,
-                    overflow: 'hidden',
-                    padding: '4px',
-                  }}
-                >
-                  {availableAgents.map((agent: AgentInfo) => {
-                    const isSelected = agent.id === (selectedAgent ?? defaultAgent);
-                    return (
-                      <div
-                        key={agent.id}
-                        data-testid="agent-option"
-                        onClick={() => {
-                          onAgentChange(agent.id === defaultAgent ? null : agent.id);
-                          agentDropdown.close();
-                        }}
-                        style={{
-                          padding: '8px 12px',
-                          background: isSelected ? theme.activeBackground : 'transparent',
-                          borderRadius: '6px',
-                          cursor: 'pointer',
-                          transition: 'background 0.15s',
-                          display: 'flex',
-                          alignItems: 'center',
-                          justifyContent: 'space-between',
-                          gap: '8px',
-                        }}
-                        onMouseEnter={(e: React.MouseEvent<HTMLDivElement>) => {
-                          if (!isSelected) {
-                            e.currentTarget.style.background = theme.hoverBackground;
-                          }
-                        }}
-                        onMouseLeave={(e: React.MouseEvent<HTMLDivElement>) => {
-                          if (!isSelected) {
-                            e.currentTarget.style.background = 'transparent';
-                          }
-                        }}
-                      >
-                        <div style={{ flex: 1, minWidth: 0 }}>
-                          <div style={{
-                            fontSize: '13px',
-                            fontWeight: isSelected ? '600' : '500',
-                            color: isSelected ? theme.primaryColor : theme.textColor,
-                          }}>
-                            {agent.name}
-                          </div>
-                          {agent.annotation && (
-                            <div style={{
-                              fontSize: '11px',
-                              color: theme.secondaryTextColor,
-                              marginTop: '2px',
-                              overflow: 'hidden',
-                              textOverflow: 'ellipsis',
-                              whiteSpace: 'nowrap',
-                            }}>
-                              {agent.annotation}
-                            </div>
-                          )}
-                        </div>
-                        {isSelected && (
-                          <svg width="14" height="14" viewBox="0 0 14 14" fill="none" style={{ flexShrink: 0 }}>
-                            <path d="M2 7L5.5 10.5L12 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"/>
-                          </svg>
-                        )}
-                      </div>
-                    );
-                  })}
-                </div>
-              )}
-            </div>
-          )}
-
-          {/* New Chat button */}
-          {onNewChat && (
-            <button
-              data-testid="new-chat-button"
-              onClick={handleNewChat}
-              style={{
-                background: 'transparent',
-                border: 'none',
-                borderRadius: '6px',
-                padding: '6px 8px',
-                color: theme.secondaryTextColor,
-                fontSize: '13px',
-                cursor: 'pointer',
-                transition: 'all 0.2s',
-                display: 'flex',
-                alignItems: 'center',
-                gap: '4px',
-              }}
-              onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                e.currentTarget.style.background = theme.hoverBackground;
-                e.currentTarget.style.color = theme.textColor;
-              }}
-              onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                e.currentTarget.style.background = 'transparent';
-                e.currentTarget.style.color = theme.secondaryTextColor;
-              }}
-              title={strings.header.newChat}
-            >
-              <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
-                <path d="M8 3.5V12.5M3.5 8H12.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"/>
-              </svg>
-            </button>
-          )}
-
-          {/* Delete button */}
-          {onDeleteChat && displayMessages.length > 0 && (
-            <button
-              data-testid="delete-chat-button"
-              onClick={handleDeleteChat}
-              style={{
-                background: 'transparent',
-                border: 'none',
-                borderRadius: '6px',
-                padding: '6px 8px',
-                color: theme.secondaryTextColor,
-                fontSize: '13px',
-                cursor: 'pointer',
-                transition: 'all 0.2s',
-              }}
-              onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                e.currentTarget.style.background = theme.hoverBackground;
-                e.currentTarget.style.color = theme.textColor;
-              }}
-              onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                e.currentTarget.style.background = 'transparent';
-                e.currentTarget.style.color = theme.secondaryTextColor;
-              }}
-              title={strings.header.deleteChat}
-            >
-              <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
-                <path d="M2 4H14M6.5 7V11M9.5 7V11M3 4L4 13C4 13.5304 4.21071 14.0391 4.58579 14.4142C4.96086 14.7893 5.46957 15 6 15H10C10.5304 15 11.0391 14.7893 11.4142 14.4142C11.7893 14.0391 12 13.5304 12 13L13 4M5.5 4V2.5C5.5 2.23478 5.60536 1.98043 5.79289 1.79289C5.98043 1.60536 6.23478 1.5 6.5 1.5H9.5C9.76522 1.5 10.0196 1.60536 10.2071 1.79289C10.3946 1.98043 10.5 2.23478 10.5 2.5V4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
-              </svg>
-            </button>
-          )}
-
-          {/* Optional close button (passed in for floating mode) */}
-          {closeButton}
-        </div>
-      </div>
-
-      {/* Chat History Dropdown */}
-      {chatHistoryDropdown.isOpen && onListChats && (
-        <div
-          style={{
-            position: 'absolute',
-            top: '60px',
-            left: '16px',
-            width: '320px',
-            maxHeight: '400px',
-            background: theme.backgroundColor,
-            borderRadius: '8px',
-            boxShadow: theme.panelShadow,
-            zIndex: 1003,
-            display: 'flex',
-            flexDirection: 'column',
-            overflow: 'hidden',
-          }}
-        >
-          {/* Chat List */}
-          <div
-            style={{
-              flex: 1,
-              overflowY: 'auto',
-              padding: '8px',
-            }}
-          >
-            {chatHistory.length === 0 ? (
-              <div
-                style={{
-                  textAlign: 'center',
-                  color: theme.secondaryTextColor,
-                  padding: '32px 16px',
-                  fontSize: '13px',
-                }}
-              >
-                <p style={{ margin: 0 }}>{strings.chatHistory.noChatHistory}</p>
-              </div>
-            ) : (
-              chatHistory.map((chat) => (
-                <div
-                  key={chat.id}
-                  data-testid="chat-history-item"
-                  onClick={() => handleLoadChat(chat.id)}
-                  style={{
-                    padding: '10px 12px',
-                    marginBottom: '4px',
-                    background: currentChatId === chat.id ? theme.activeBackground : 'transparent',
-                    borderRadius: '6px',
-                    cursor: 'pointer',
-                    transition: 'background 0.15s',
-                  }}
-                  onMouseEnter={(e: React.MouseEvent<HTMLDivElement>) => {
-                    if (currentChatId !== chat.id) {
-                      e.currentTarget.style.background = theme.hoverBackground;
-                    }
-                  }}
-                  onMouseLeave={(e: React.MouseEvent<HTMLDivElement>) => {
-                    if (currentChatId !== chat.id) {
-                      e.currentTarget.style.background = 'transparent';
-                    }
-                  }}
-                >
-                  <div style={{ fontSize: '13px', fontWeight: '500', color: theme.textColor, marginBottom: '4px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
-                    {chat.title || strings.header.newChat}
-                  </div>
-                  <div style={{ fontSize: '11px', color: theme.secondaryTextColor }}>
-                    {new Date(chat.updatedAt).toLocaleDateString([], { month: 'short', day: 'numeric' })}
-                    {currentChatId === chat.id && (
-                      <span style={{
-                        marginLeft: '8px',
-                        color: theme.primaryColor,
-                        fontWeight: '600',
-                      }}>
-                        • {strings.chatHistory.active}
-                      </span>
-                    )}
-                  </div>
-                </div>
-              ))
-            )}
-          </div>
-        </div>
-      )}
-
-      {/* Backdrops to close dropdowns */}
-      {chatHistoryDropdown.Backdrop}
-      {agentDropdown.Backdrop}
+      />
 
       {/* Messages */}
       <div
@@ -840,622 +368,119 @@ export function UseAIChatPanel({
         }}
       >
         {displayMessages.length === 0 && (
-          <div
-            style={{
-              display: 'flex',
-              flexDirection: 'column',
-              alignItems: 'center',
-              padding: '40px 20px',
-              gap: '20px',
+          <Slot
+            component={components?.EmptyState}
+            fallback={DefaultEmptyState}
+            props={{
+              suggestions: displayedSuggestions,
+              connected,
+              loading,
+              onSelectSuggestion: (suggestion) => {
+                if (connected && !loading) onSendMessage(suggestion);
+              },
             }}
-          >
-            <div style={{ textAlign: 'center', color: theme.secondaryTextColor, fontSize: '14px' }}>
-              <p style={{ margin: 0, fontSize: '32px', marginBottom: '12px' }}>💬</p>
-              <p style={{ margin: 0 }}>{strings.emptyChat.startConversation}</p>
-              <p style={{ margin: '8px 0 0', fontSize: '12px' }}>
-                {strings.emptyChat.askMeToHelp}
-              </p>
-            </div>
-
-            {/* Suggestions */}
-            {displayedSuggestions.length > 0 && (
-              <div
-                style={{
-                  display: 'grid',
-                  gridTemplateColumns: '1fr',
-                  gap: '8px',
-                  width: '100%',
-                  maxWidth: '320px',
-                }}
-              >
-                {displayedSuggestions.map((suggestion, index) => (
-                  <button
-                    key={index}
-                    data-testid="chat-suggestion-button"
-                    onClick={() => {
-                      if (connected && !loading) {
-                        onSendMessage(suggestion);
-                      }
-                    }}
-                    disabled={!connected || loading}
-                    style={{
-                      padding: '10px 14px',
-                      background: theme.backgroundColor,
-                      border: `1px solid ${theme.borderColor}`,
-                      borderRadius: '8px',
-                      fontSize: '13px',
-                      color: theme.textColor,
-                      cursor: connected && !loading ? 'pointer' : 'not-allowed',
-                      textAlign: 'left',
-                      transition: 'all 0.2s',
-                      lineHeight: '1.4',
-                      opacity: connected && !loading ? 1 : 0.5,
-                    }}
-                    onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                      if (connected && !loading) {
-                        e.currentTarget.style.background = theme.hoverBackground;
-                        e.currentTarget.style.transform = 'translateY(-1px)';
-                        e.currentTarget.style.boxShadow = '0 2px 8px rgba(0, 0, 0, 0.08)';
-                      }
-                    }}
-                    onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                      e.currentTarget.style.background = theme.backgroundColor;
-                      e.currentTarget.style.transform = 'translateY(0)';
-                      e.currentTarget.style.boxShadow = 'none';
-                    }}
-                  >
-                    {suggestion}
-                  </button>
-                ))}
-              </div>
-            )}
-          </div>
+          />
         )}
 
-        {renderedMessages.map((message) => {
-          // Info notices (e.g. the abort "generation stopped" bubble) are
-          // display-only system messages. Render a compact, centered pill —
-          // no reasoning dropdown, markdown, feedback, or hover affordances.
-          if (message.displayMode === 'info') {
-            return (
-              <div
-                key={message.id}
-                data-testid="chat-message-info"
-                className="chat-message chat-message-info"
-                style={{ display: 'flex', justifyContent: 'center', padding: '2px 0' }}
-              >
-                <div
-                  style={{
-                    maxWidth: '80%',
-                    padding: '6px 12px',
-                    borderRadius: '12px',
-                    background: theme.assistantMessageBackground,
-                    color: theme.secondaryTextColor,
-                    fontSize: '12px',
-                    lineHeight: '1.4',
-                    textAlign: 'center',
-                    wordWrap: 'break-word',
-                  }}
-                >
-                  {getDisplayTextFromContent(message.content)}
-                </div>
-              </div>
-            );
-          }
-
-          // The provisional bubble is deliberately kept out of
-          // `chat-message-assistant` and `chat-message-content`: the E2E suites
-          // wait on those test ids to mean "the answer is done", and a bubble
-          // that appears with the first token would satisfy that wait
-          // mid-stream. Only the attributes change when the answer is
-          // persisted, so the elements themselves, and any selection inside
-          // them, are untouched.
-          const messageTestId = message.streaming
-            ? 'chat-message-assistant-streaming'
-            : `chat-message-${message.role}`;
-          const contentTestId = message.streaming
-            ? 'chat-message-content-streaming'
-            : 'chat-message-content';
-
-          return (
-          <div
+        {renderedMessages.map((message, index) => (
+          <Slot
             key={message.id}
-            data-testid={messageTestId}
-            className={`chat-message chat-message-${message.role}`}
-            style={{
-              display: 'flex',
-              flexDirection: 'column',
-              alignItems: message.role === 'user' ? 'flex-end' : 'flex-start',
+            component={components?.Message}
+            fallback={DefaultMessage}
+            props={{
+              message,
+              index,
+              isLast: index === renderedMessages.length - 1,
+              sourceMessages: message.sourceMessages,
+              streaming: !!message.streaming,
+              streamingReasoning: message.streaming ? streamingReasoning : '',
+              streamingParts: message.streaming ? streamingParts : EMPTY_STREAMING_PARTS,
+              feedbackEnabled: !!feedbackEnabled,
+              onFeedback,
+              saveAsCommand: saveAsCommandFor(message),
             }}
-            onMouseEnter={() => message.role === 'user' && setHoveredMessageId(message.id)}
-            onMouseLeave={() => setHoveredMessageId(null)}
-          >
-            <div
-              style={{
-                position: 'relative',
-                maxWidth: '80%',
-              }}
-            >
-              {/* Save as command button - appears on hover for user messages */}
-              {message.role === 'user' && slashCommandsEnabled && hoveredMessageId === message.id && onSaveCommand && !slashCommands.isSavingCommand(message.id) && (
-                <button
-                  data-testid="save-command-button"
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    const messageText = getDisplayTextFromContent(message.content);
-                    slashCommands.startSavingCommand(message.id, messageText);
-                  }}
-                  title="Save as slash command"
-                  style={{
-                    position: 'absolute',
-                    top: '-8px',
-                    right: '-8px',
-                    width: '24px',
-                    height: '24px',
-                    borderRadius: '50%',
-                    border: 'none',
-                    background: theme.backgroundColor,
-                    boxShadow: '0 2px 6px rgba(0, 0, 0, 0.15)',
-                    cursor: 'pointer',
-                    display: 'flex',
-                    alignItems: 'center',
-                    justifyContent: 'center',
-                    color: theme.primaryColor,
-                    transition: 'all 0.15s',
-                    zIndex: 10,
-                  }}
-                  onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                    e.currentTarget.style.transform = 'scale(1.1)';
-                    e.currentTarget.style.boxShadow = '0 3px 8px rgba(0, 0, 0, 0.2)';
-                  }}
-                  onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                    e.currentTarget.style.transform = 'scale(1)';
-                    e.currentTarget.style.boxShadow = '0 2px 6px rgba(0, 0, 0, 0.15)';
-                  }}
-                >
-                  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                    <path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z" />
-                    <polyline points="17 21 17 13 7 13 7 21" />
-                    <polyline points="7 3 7 8 15 8" />
-                  </svg>
-                </button>
-              )}
-              <div
-                data-testid={contentTestId}
-                className={`chat-message-content${message.role === 'assistant' ? ' markdown-content' : ''}`}
-                style={{
-                  padding: '10px 14px',
-                  borderRadius: slashCommands.isSavingCommand(message.id)
-                    ? '12px 12px 0 0'
-                    : '12px',
-                  background: message.displayMode === 'error'
-                    ? theme.errorBackground
-                    : message.role === 'user'
-                    ? theme.primaryGradient
-                    : theme.assistantMessageBackground,
-                  color: message.displayMode === 'error'
-                    ? theme.errorTextColor
-                    : message.role === 'user' ? 'white' : theme.textColor,
-                  fontSize: '14px',
-                  lineHeight: '1.5',
-                  wordWrap: 'break-word',
-                }}
-              >
-              {/* Render file placeholders for user messages with files */}
-              {message.role === 'user' && hasFileContent(message.content) && (
-                <div style={{ display: 'flex', flexWrap: 'wrap', gap: '6px', marginBottom: '8px' }}>
-                  {message.content.flatMap((part: PersistedContentPart, idx: number) => {
-                    const info = fileChipInfo(part);
-                    return info
-                      ? [<FilePlaceholder key={idx} name={info.name} size={info.size} />]
-                      : [];
-                  })}
-                </div>
-              )}
-              {message.role === 'assistant' ? (
-                <>
-                  {message.streaming && streamingReasoning && (
-                    <Reasoning
-                      reasoningParts={[]}
-                      isStreaming={true}
-                      streamingText={streamingReasoning}
-                      theme={theme}
-                      strings={strings}
-                    />
-                  )}
-                  {!message.streaming && message.reasoningParts && message.reasoningParts.length > 0 && (
-                    <Reasoning
-                      reasoningParts={message.reasoningParts}
-                      theme={theme}
-                      strings={strings}
-                    />
-                  )}
-                  {message.streaming && !streamingText ? (
-                    <span className="dots" style={{ opacity: 0.6 }}>...</span>
-                  ) : (
-                    <MarkdownContent content={getTextFromContent(message.content)} />
-                  )}
-                </>
-              ) : (
-                // User/tool bubbles: display-only text so transformed_file
-                // (e.g. OCR body) isn't dumped into the chat bubble.
-                getDisplayTextFromContent(message.content)
-              )}
-              </div>
-              {/* Inline save command UI - glued to chat bubble */}
-              {slashCommands.renderInlineSaveUI({
-                messageId: message.id,
-                messageText: getDisplayTextFromContent(message.content),
-              })}
-            </div>
-            {/* Feedback buttons - only for assistant messages with traceId */}
-            {message.role === 'assistant' && !message.streaming && message.traceId && feedbackEnabled && onFeedback && (
-              <div
-                data-testid="feedback-buttons"
-                style={{
-                  display: 'flex',
-                  gap: '4px',
-                  marginTop: '4px',
-                  padding: '0 4px',
-                }}
-              >
-                <FeedbackButton
-                  type="upvote"
-                  isSelected={message.feedback === 'upvote'}
-                  onClick={() => {
-                    const newFeedback = message.feedback === 'upvote' ? null : 'upvote';
-                    onFeedback(message.id, message.traceId!, newFeedback);
-                  }}
-                  selectedColor={theme.primaryColor}
-                  unselectedColor={theme.secondaryTextColor}
-                />
-                <FeedbackButton
-                  type="downvote"
-                  isSelected={message.feedback === 'downvote'}
-                  onClick={() => {
-                    const newFeedback = message.feedback === 'downvote' ? null : 'downvote';
-                    onFeedback(message.id, message.traceId!, newFeedback);
-                  }}
-                  selectedColor={theme.errorTextColor}
-                  unselectedColor={theme.secondaryTextColor}
-                />
-              </div>
-            )}
-            {!message.streaming && (
-              <div
-                data-testid="message-timestamp"
-                style={{
-                  fontSize: '11px',
-                  color: theme.secondaryTextColor,
-                  marginTop: '4px',
-                  padding: '0 4px',
-                }}
-              >
-                {message.createdAt.toLocaleTimeString([], {
-                  hour: '2-digit',
-                  minute: '2-digit'
-                })}
-              </div>
-            )}
-          </div>
-          );
-        })}
+          />
+        ))}
 
         {loading && !provisionalMessage && (
-          <div
-            style={{
-              display: 'flex',
-              alignItems: 'flex-start',
+          <Slot
+            component={components?.PendingIndicator}
+            fallback={DefaultPendingIndicator}
+            props={{
+              executingTool: executingTool ?? null,
+              fileProcessing: fileProcessing ?? null,
             }}
-          >
-            <div
-              className="markdown-content"
-              style={{
-                padding: '10px 14px',
-                borderRadius: '12px',
-                background: theme.assistantMessageBackground,
-                fontSize: '14px',
-                lineHeight: '1.5',
-                color: theme.textColor,
-                maxWidth: '80%',
-              }}
-            >
-              {fileProcessing && fileProcessing.status === 'processing' ? (
-                <div>
-                  <span style={{ opacity: 0.6 }}>{strings.input.processingFile}</span>
-                  {fileProcessing.progress != null && (
-                    <>
-                      <span style={{ opacity: 0.6, marginLeft: '4px' }}>
-                        {Math.round(fileProcessing.progress)}%
-                      </span>
-                      <div style={{
-                        marginTop: '6px',
-                        height: '4px',
-                        borderRadius: '2px',
-                        background: theme.borderColor,
-                        overflow: 'hidden',
-                      }}>
-                        <div style={{
-                          height: '100%',
-                          width: `${fileProcessing.progress}%`,
-                          borderRadius: '2px',
-                          background: theme.primaryColor,
-                          transition: 'width 0.3s ease',
-                        }} />
-                      </div>
-                    </>
-                  )}
-                  {fileProcessing.progress == null && (
-                    <span className="dots" style={{ marginLeft: '4px' }}>...</span>
-                  )}
-                </div>
-              ) : (
-                <span className="dots" style={{ opacity: 0.6 }}>...</span>
-              )}
-            </div>
-          </div>
+          />
         )}
 
         <div ref={messagesEndRef} />
       </div>
 
       {/* Input */}
-      <div
-        style={{
-          padding: '16px',
-          borderTop: `1px solid ${theme.borderColor}`,
-        }}
-      >
-        {/* File error message */}
-        {fileError && (
-          <div
-            data-testid="file-error"
-            style={{
-              marginBottom: '8px',
-              padding: '8px 12px',
-              background: theme.errorBackground,
-              color: theme.errorTextColor,
-              borderRadius: '6px',
-              fontSize: '13px',
-            }}
-          >
-            {fileError}
-          </div>
-        )}
-
-        {/* File chips */}
-        {attachments.length > 0 && (
-          <div
-            data-testid="file-attachments"
-            style={{
-              display: 'flex',
-              flexWrap: 'wrap',
-              gap: '8px',
-              marginBottom: '8px',
-            }}
-          >
-            {attachments.map((attachment) => (
-              <FileChip
-                key={attachment.id}
-                attachment={attachment}
-                onRemove={() => removeAttachment(attachment.id)}
-                disabled={loading}
-                processingState={fileProcessingState.get(attachment.id)}
-              />
-            ))}
-          </div>
-        )}
-
-        {/* Hidden file input - always rendered */}
-        <input
-          ref={fileInputRef}
-          type="file"
-          multiple
-          data-testid="file-input"
-          style={{ display: 'none' }}
-          onChange={handleFileInputChange}
-          accept={acceptedTypes?.join(',')}
+      {/* Hidden file input remains mounted even when Composer is replaced. */}
+      <input
+        ref={fileInputRef}
+        type="file"
+        multiple
+        data-testid="file-input"
+        style={{ display: 'none' }}
+        onChange={handleFileInputChange}
+        accept={acceptedTypes?.join(',')}
+      />
+
+      {/* Tool approval is independent from Composer so replacing the input UI
+          cannot accidentally remove the controls required to resume a run. */}
+      {pendingApprovals.length > 0 && onApproveToolCall && onRejectToolCall && (
+        <Slot
+          component={components?.ToolApproval}
+          fallback={DefaultToolApproval}
+          props={{
+            approvals: pendingApprovals,
+            onApprove: onApproveToolCall,
+            onReject: onRejectToolCall,
+          }}
         />
+      )}
 
-        {/* Tool approval dialog - replaces input when pending */}
-        {pendingApprovals.length > 0 && onApproveToolCall && onRejectToolCall ? (
-          <ToolApprovalDialog
-            toolCallName={pendingApprovals[0].toolCallName}
-            toolCallArgs={pendingApprovals[0].toolCallArgs}
-            annotations={pendingApprovals[0].annotations}
-            toolCount={pendingApprovals.length}
-            pendingTools={pendingApprovals}
-            onApprove={onApproveToolCall}
-            onReject={onRejectToolCall}
-            theme={theme}
-            strings={strings}
-          />
-        ) : (
-          /* Input container - single border around everything */
-          <div
-            style={{
-              border: `1px solid ${theme.borderColor}`,
-              borderRadius: '12px',
-              background: theme.backgroundColor,
-              overflow: 'hidden',
-              position: 'relative',
-            }}
-          >
-            {/* Command Autocomplete */}
-            {slashCommands.AutocompleteComponent}
-
-            {/* Textarea area */}
-            <textarea
-              ref={textareaRef}
-              data-testid="chat-input"
-              className="chat-input"
-              value={input}
-              onChange={handleInputChange}
-              onKeyDown={handleKeyDown}
-              placeholder={
-                !connected
-                  ? strings.input.connectingPlaceholder
-                  : loading
-                    ? `${executingTool?.displayText ?? strings.input.thinking}...`
-                    : strings.input.placeholder
-              }
-              disabled={!connected || loading || pendingApprovals.length > 0}
-              rows={1}
-              style={{
-                width: '100%',
-                padding: '10px 14px 6px',
-                border: 'none',
-                fontSize: '14px',
-                lineHeight: '1.4',
-                resize: 'none',
-                maxHeight: `${maxTextareaHeight}px`,
-                fontFamily: 'inherit',
-                outline: 'none',
-                background: 'transparent',
-                overflowY: 'auto',
-                boxSizing: 'border-box',
-              }}
-            />
-
-            {/* Bottom toolbar - fixed */}
-            <div
-              style={{
-                display: 'flex',
-                alignItems: 'center',
-                justifyContent: 'space-between',
-                padding: '4px 8px',
-              }}
-            >
-              {/* Left side - file picker */}
-              <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-                {fileUploadEnabled && (
-                  <button
-                    data-testid="file-picker-button"
-                    onClick={openFilePicker}
-                    disabled={!connected || loading || pendingApprovals.length > 0}
-                    style={{
-                      padding: '4px',
-                      background: 'transparent',
-                      border: `1px solid ${theme.borderColor}`,
-                      borderRadius: '50%',
-                      cursor: connected && !loading && pendingApprovals.length === 0 ? 'pointer' : 'not-allowed',
-                      color: theme.secondaryTextColor,
-                      display: 'flex',
-                      alignItems: 'center',
-                      justifyContent: 'center',
-                      width: '28px',
-                      height: '28px',
-                      transition: 'all 0.15s',
-                      opacity: connected && !loading && pendingApprovals.length === 0 ? 1 : 0.5,
-                    }}
-                    onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
-                      if (connected && !loading && pendingApprovals.length === 0) {
-                        e.currentTarget.style.color = theme.primaryColor;
-                        e.currentTarget.style.borderColor = theme.primaryColor;
-                      }
-                    }}
-                    onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
-                      e.currentTarget.style.color = theme.secondaryTextColor;
-                      e.currentTarget.style.borderColor = theme.borderColor;
-                    }}
-                    title={strings.fileUpload.attachFiles}
-                  >
-                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
-                      <line x1="12" y1="5" x2="12" y2="19" />
-                      <line x1="5" y1="12" x2="19" y2="12" />
-                    </svg>
-                  </button>
-                )}
-              </div>
-
-              {/* Right side - send / stop button.
-                  While loading and a stop handler is wired up, swap in a stop
-                  button so the user can interrupt streaming. Disabled when a
-                  tool is currently executing — that branch can't be safely
-                  cancelled in Phase 1 because the tool's side effects have
-                  already run on the client. */}
-              {(() => {
-                const canAbort = loading && !!onAbort
-                const canSend = connected && !loading && pendingApprovals.length === 0 && (input.trim() || attachments.length > 0);
-                if (loading && onAbort) {
-                  return (
-                    <button
-                      data-testid="chat-stop-button"
-                      className="chat-stop-button"
-                      onClick={onAbort}
-                      disabled={!canAbort}
-                      title={canAbort ? 'Stop generating' : 'Cannot stop while a tool is running'}
-                      aria-label="Stop generating"
-                      style={{
-                        padding: '6px',
-                        background: canAbort ? theme.stopButtonBackground : theme.buttonDisabledBackground,
-                        color: theme.secondaryTextColor,
-                        border: 'none',
-                        borderRadius: '50%',
-                        cursor: canAbort ? 'pointer' : 'not-allowed',
-                        display: 'flex',
-                        alignItems: 'center',
-                        justifyContent: 'center',
-                        width: '32px',
-                        height: '32px',
-                        transition: 'all 0.2s',
-                      }}
-                    >
-                      <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" stroke="none">
-                        <rect x="6" y="6" width="12" height="12" rx="2" />
-                      </svg>
-                    </button>
-                  );
-                }
-                return (
-                  <button
-                    data-testid="chat-send-button"
-                    className="chat-send-button"
-                    onClick={handleSend}
-                    disabled={!canSend}
-                    style={{
-                      padding: '6px',
-                      background: canSend ? theme.primaryGradient : theme.buttonDisabledBackground,
-                      color: canSend ? 'white' : theme.secondaryTextColor,
-                      border: 'none',
-                      borderRadius: '50%',
-                      cursor: canSend ? 'pointer' : 'not-allowed',
-                      display: 'flex',
-                      alignItems: 'center',
-                      justifyContent: 'center',
-                      width: '32px',
-                      height: '32px',
-                      transition: 'all 0.2s',
-                    }}
-                  >
-                    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
-                      <line x1="12" y1="19" x2="12" y2="5" />
-                      <polyline points="5 12 12 5 19 12" />
-                    </svg>
-                  </button>
-                );
-              })()}
-            </div>
-          </div>
-        )}
-
-        {/* Accuracy disclaimer. Kept out of the empty chat so the first
-            impression stays clean; once the user has sent a message it stays
-            visible for the rest of the conversation. */}
-        {features.inputDisclaimer && displayMessages.length > 0 && (
-          <div
-            data-testid="chat-input-disclaimer"
-            style={{
-              marginTop: '8px',
-              fontSize: '12px',
-              lineHeight: 1.3,
-              color: theme.disclaimerTextColor,
-            }}
-          >
-            {strings.input.disclaimer}
-          </div>
-        )}
-      </div>
+      <Slot
+        component={components?.Composer}
+        fallback={DefaultComposer}
+        props={{
+          input,
+          connected,
+          loading,
+          placeholder: composerPlaceholder,
+          canSend,
+          canAbort,
+          attachments,
+          fileUploadEnabled,
+          fileError,
+          pendingApprovals,
+          onInputChange: handleInputValueChange,
+          onSend: handleSend,
+          onAbort,
+          onOpenFilePicker: openFilePicker,
+          onRemoveAttachment: removeAttachment,
+          submitMode,
+          attachmentProcessing: fileProcessingState,
+          disclaimerVisible: showInputDisclaimer,
+          slashCommands: {
+            isOpen: slashCommands.isAutocompleteVisible,
+            onKeyDown: slashCommands.handleKeyDown,
+            list: slashCommands.AutocompleteComponent,
+          },
+        }}
+      />
+
+      {/* Keep the disclaimer independent from Composer so a full input UI
+          replacement cannot accidentally remove configured safety copy. */}
+      {showInputDisclaimer && (
+        <Slot
+          component={components?.Disclaimer}
+          fallback={DefaultDisclaimer}
+          props={{ text: strings.input.disclaimer }}
+        />
+      )}
 
       <style>{`
         /* Markdown content styles */
diff --git a/packages/client/src/components/UseAIChatSlots.test.tsx b/packages/client/src/components/UseAIChatSlots.test.tsx
new file mode 100644
index 00000000..0ab5aa4a
--- /dev/null
+++ b/packages/client/src/components/UseAIChatSlots.test.tsx
@@ -0,0 +1,225 @@
+import React from 'react';
+import { describe, test, expect, mock } from 'bun:test';
+import { fireEvent, render } from '@testing-library/react';
+import { UseAIChatPanel } from './UseAIChatPanel';
+import type {
+  ChatComposerSlotProps,
+  ChatDisclaimerSlotProps,
+  ChatEmptyStateSlotProps,
+  ChatHeaderSlotProps,
+  ChatMessageSlotProps,
+  ChatPendingIndicatorSlotProps,
+  ChatToolApprovalSlotProps,
+  UseAIChatComponentOverrides,
+} from './chatSlots';
+import type { PersistedMessage } from '../providers/chatRepository/types';
+
+const message: PersistedMessage = {
+  id: 'message-1',
+  role: 'assistant',
+  content: 'Built-in message',
+  createdAt: new Date(0),
+};
+
+function renderPanel(
+  components?: UseAIChatComponentOverrides,
+  overrides: Partial<React.ComponentProps<typeof UseAIChatPanel>> = {}
+) {
+  return render(
+    <UseAIChatPanel
+      onSendMessage={mock(() => {})}
+      messages={[message]}
+      loading
+      connected
+      streamingText="Streaming"
+      pendingApprovals={[{
+        toolCallId: 'tool-1',
+        toolCallName: 'fillForm',
+        toolCallArgs: { field: 'name' },
+      }]}
+      onApproveToolCall={mock(() => {})}
+      onRejectToolCall={mock(() => {})}
+      components={components}
+      {...overrides}
+    />
+  );
+}
+
+describe('UseAIChat component slots', () => {
+  test('keeps the built-in UI when no overrides are provided', () => {
+    const { getByText, getByTestId } = renderPanel();
+
+    expect(getByText('Built-in message')).toBeInTheDocument();
+    expect(getByText('Streaming')).toBeInTheDocument();
+    expect(getByTestId('chat-message-assistant')).toBeInTheDocument();
+    expect(getByTestId('chat-message-assistant-streaming')).toBeInTheDocument();
+  });
+
+  test('replaces all populated chat regions and exposes their state', () => {
+    const onApproveToolCall = mock(() => {});
+    const onRejectToolCall = mock((_reason?: string) => {});
+    const Header = ({ currentChatId }: ChatHeaderSlotProps) => (
+      <div data-testid="custom-header">{currentChatId}</div>
+    );
+    const Message = ({ message: slotMessage, streaming }: ChatMessageSlotProps) => (
+      <div data-testid="custom-message" data-streaming={String(streaming)}>
+        {slotMessage.content as string}
+      </div>
+    );
+    const ToolApproval = ({ approvals, onApprove, onReject }: ChatToolApprovalSlotProps) => (
+      <div data-testid="custom-approval">
+        {approvals[0].toolCallName}
+        <button data-testid="custom-approve" onClick={onApprove}>Approve</button>
+        <button data-testid="custom-reject" onClick={() => onReject('Not now')}>Reject</button>
+      </div>
+    );
+    // A full replacement intentionally omits children. ToolApproval must still
+    // render because approval controls are required to resume the pending run.
+    const Composer = ({ pendingApprovals }: ChatComposerSlotProps) => (
+      <div data-testid="custom-composer" data-pending={pendingApprovals.length} />
+    );
+    const Disclaimer = ({ text }: ChatDisclaimerSlotProps) => (
+      <div data-testid="custom-disclaimer">Notice: {text}</div>
+    );
+
+    const { getAllByTestId, getByTestId, queryByTestId } = renderPanel(
+      { Header, Message, ToolApproval, Composer, Disclaimer },
+      {
+        currentChatId: 'chat-custom',
+        onApproveToolCall,
+        onRejectToolCall,
+        enabledFeatures: { inputDisclaimer: true },
+      }
+    );
+
+    expect(getByTestId('custom-header')).toHaveTextContent('chat-custom');
+    // Both the persisted message and the streaming answer go through Message.
+    const messages = getAllByTestId('custom-message');
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toHaveTextContent('Built-in message');
+    expect(messages[1]).toHaveTextContent('Streaming');
+    expect(getByTestId('custom-approval')).toHaveTextContent('fillForm');
+    expect(getByTestId('custom-composer')).toHaveAttribute('data-pending', '1');
+    expect(getByTestId('custom-disclaimer')).toHaveTextContent('AI can make mistakes');
+    expect(queryByTestId('chat-message-assistant')).toBeNull();
+    expect(queryByTestId('chat-message-assistant-streaming')).toBeNull();
+
+    fireEvent.click(getByTestId('custom-approve'));
+    fireEvent.click(getByTestId('custom-reject'));
+    expect(onApproveToolCall).toHaveBeenCalledTimes(1);
+    expect(onRejectToolCall).toHaveBeenCalledWith('Not now');
+  });
+
+  test('routes the streaming answer through the Message slot', () => {
+    const Message = ({ message: slotMessage, streaming, streamingReasoning, streamingParts, isLast }: ChatMessageSlotProps) => (
+      <div
+        data-testid={`slot-${slotMessage.id}`}
+        data-streaming={String(streaming)}
+        data-reasoning={streamingReasoning}
+        data-parts={streamingParts.map((part) => part.kind).join(',')}
+        data-last={String(isLast)}
+      >
+        {slotMessage.content as string}
+      </div>
+    );
+
+    const { getByTestId } = renderPanel(
+      { Message },
+      {
+        streamingMessageId: 'message-2',
+        streamingReasoning: 'Weighing options',
+        streamingParts: [
+          { kind: 'reasoning', text: 'Weighing options' },
+          { kind: 'tool_call', toolCallId: 'tc1', name: 'search', args: '{}' },
+        ],
+      }
+    );
+
+    const persisted = getByTestId('slot-message-1');
+    expect(persisted).toHaveAttribute('data-streaming', 'false');
+    expect(persisted).toHaveAttribute('data-reasoning', '');
+    expect(persisted).toHaveAttribute('data-parts', '');
+    expect(persisted).toHaveAttribute('data-last', 'false');
+
+    // The provisional entry carries the id the answer will be persisted under,
+    // so the slot keeps the same instance when the run finishes.
+    const streamingBubble = getByTestId('slot-message-2');
+    expect(streamingBubble).toHaveTextContent('Streaming');
+    expect(streamingBubble).toHaveAttribute('data-streaming', 'true');
+    expect(streamingBubble).toHaveAttribute('data-reasoning', 'Weighing options');
+    // The ordered parts let a slot keep the run's steps apart while it streams.
+    expect(streamingBubble).toHaveAttribute('data-parts', 'reasoning,tool_call');
+    expect(streamingBubble).toHaveAttribute('data-last', 'true');
+  });
+
+  const PendingIndicator = ({ executingTool }: ChatPendingIndicatorSlotProps) => (
+    <div data-testid="custom-pending">{executingTool?.displayText}</div>
+  );
+  const executingTool = { toolCallId: 'tool-1', name: 'fillForm', displayText: 'Filling the form' };
+
+  test('renders PendingIndicator before the answer starts arriving', () => {
+    const { getByTestId } = renderPanel(
+      { PendingIndicator },
+      { streamingText: '', executingTool }
+    );
+
+    expect(getByTestId('custom-pending')).toHaveTextContent('Filling the form');
+  });
+
+  test('drops PendingIndicator once the answer starts arriving', () => {
+    const { queryByTestId } = renderPanel({ PendingIndicator }, { executingTool });
+
+    expect(queryByTestId('custom-pending')).toBeNull();
+  });
+
+  test('lets EmptyState send a suggestion', () => {
+    const onSendMessage = mock(() => {});
+    const EmptyState = ({ suggestions, onSelectSuggestion }: ChatEmptyStateSlotProps) => (
+      <button data-testid="custom-empty" onClick={() => onSelectSuggestion(suggestions[0])}>
+        {suggestions[0]}
+      </button>
+    );
+
+    const { getByTestId } = renderPanel(
+      { EmptyState },
+      {
+        messages: [],
+        loading: false,
+        suggestions: ['Explain this page'],
+        pendingApprovals: [],
+        onSendMessage,
+      }
+    );
+
+    fireEvent.click(getByTestId('custom-empty'));
+    expect(onSendMessage).toHaveBeenCalledWith('Explain this page');
+  });
+
+  test('lets a custom Composer control input and submission', () => {
+    const onSendMessage = mock(() => {});
+    const Composer = ({ input, onInputChange, onSend, canSend }: ChatComposerSlotProps) => (
+      <div>
+        <span data-testid="custom-input-value">{input}</span>
+        <button data-testid="custom-set-input" onClick={() => onInputChange('Hello')}>Set</button>
+        <button data-testid="custom-send" disabled={!canSend} onClick={onSend}>Send</button>
+      </div>
+    );
+
+    const { getByTestId } = renderPanel(
+      { Composer },
+      {
+        messages: [],
+        loading: false,
+        pendingApprovals: [],
+        onSendMessage,
+      }
+    );
+
+    fireEvent.click(getByTestId('custom-set-input'));
+    expect(getByTestId('custom-input-value')).toHaveTextContent('Hello');
+    expect(getByTestId('custom-send')).not.toBeDisabled();
+    fireEvent.click(getByTestId('custom-send'));
+
+    expect(onSendMessage).toHaveBeenCalledWith('Hello', undefined);
+  });
+});
diff --git a/packages/client/src/components/chatSlots/DefaultComposer.tsx b/packages/client/src/components/chatSlots/DefaultComposer.tsx
new file mode 100644
index 00000000..1f0ea00f
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultComposer.tsx
@@ -0,0 +1,269 @@
+import React, { useEffect, useRef } from 'react';
+import { FileChip } from '../FileChip';
+import { useStrings, useTheme } from '../../theme';
+import { shouldSubmitOnEnter } from '../../utils/keyboard';
+import type { ChatComposerSlotProps } from './types';
+
+/** Tallest the textarea grows to before it starts scrolling. */
+const MAX_TEXTAREA_HEIGHT = 160;
+
+/** The message input: attachments, slash-command autocomplete, send/stop. */
+export function DefaultComposer({
+  input,
+  connected,
+  loading,
+  placeholder,
+  canSend,
+  canAbort,
+  attachments,
+  fileUploadEnabled,
+  fileError,
+  pendingApprovals,
+  onInputChange,
+  onSend,
+  onAbort,
+  onOpenFilePicker,
+  onRemoveAttachment,
+  submitMode,
+  attachmentProcessing,
+  disclaimerVisible,
+  slashCommands,
+}: ChatComposerSlotProps) {
+  const theme = useTheme();
+  const strings = useStrings();
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Auto-resize the textarea to its content, up to MAX_TEXTAREA_HEIGHT.
+  useEffect(() => {
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+
+    // Reset to single row to measure actual content height
+    textarea.style.height = 'auto';
+    textarea.style.height = `${Math.min(textarea.scrollHeight, MAX_TEXTAREA_HEIGHT)}px`;
+  }, [input]);
+
+  const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    onInputChange(e.target.value);
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    // Slash command navigation claims the key first.
+    if (slashCommands.onKeyDown(e)) return;
+
+    if (shouldSubmitOnEnter(e, submitMode)) {
+      e.preventDefault();
+      onSend();
+    }
+  };
+
+  return (
+    <div
+      style={{
+        padding: disclaimerVisible ? '16px 16px 0' : '16px',
+        borderTop: `1px solid ${theme.borderColor}`,
+        ...(pendingApprovals.length > 0 ? { display: 'none' } : {}),
+      }}
+    >
+    {/* File error message */}
+    {fileError && (
+      <div
+        data-testid="file-error"
+        style={{
+          marginBottom: '8px',
+          padding: '8px 12px',
+          background: theme.errorBackground,
+          color: theme.errorTextColor,
+          borderRadius: '6px',
+          fontSize: '13px',
+        }}
+      >
+        {fileError}
+      </div>
+    )}
+
+    {/* File chips */}
+    {attachments.length > 0 && (
+      <div
+        data-testid="file-attachments"
+        style={{
+          display: 'flex',
+          flexWrap: 'wrap',
+          gap: '8px',
+          marginBottom: '8px',
+        }}
+      >
+        {attachments.map((attachment) => (
+          <FileChip
+            key={attachment.id}
+            attachment={attachment}
+            onRemove={() => onRemoveAttachment(attachment.id)}
+            disabled={loading}
+            processingState={attachmentProcessing.get(attachment.id)}
+          />
+        ))}
+      </div>
+    )}
+
+    {/* Input container - single border around everything */}
+    <div
+      style={{
+        border: `1px solid ${theme.borderColor}`,
+        borderRadius: '12px',
+        background: theme.backgroundColor,
+        overflow: 'hidden',
+        position: 'relative',
+      }}
+    >
+        {/* Command Autocomplete */}
+        {slashCommands.list}
+
+        {/* Textarea area */}
+        <textarea
+          ref={textareaRef}
+          data-testid="chat-input"
+          className="chat-input"
+          value={input}
+          onChange={handleInputChange}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          disabled={!connected || loading || pendingApprovals.length > 0}
+          rows={1}
+          style={{
+            width: '100%',
+            padding: '10px 14px 6px',
+            border: 'none',
+            fontSize: '14px',
+            lineHeight: '1.4',
+            resize: 'none',
+            maxHeight: `${MAX_TEXTAREA_HEIGHT}px`,
+            fontFamily: 'inherit',
+            outline: 'none',
+            background: 'transparent',
+            overflowY: 'auto',
+            boxSizing: 'border-box',
+          }}
+        />
+
+        {/* Bottom toolbar - fixed */}
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            padding: '4px 8px',
+          }}
+        >
+          {/* Left side - file picker */}
+          <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+            {fileUploadEnabled && (
+              <button
+                data-testid="file-picker-button"
+                onClick={onOpenFilePicker}
+                disabled={!connected || loading || pendingApprovals.length > 0}
+                style={{
+                  padding: '4px',
+                  background: 'transparent',
+                  border: `1px solid ${theme.borderColor}`,
+                  borderRadius: '50%',
+                  cursor: connected && !loading && pendingApprovals.length === 0 ? 'pointer' : 'not-allowed',
+                  color: theme.secondaryTextColor,
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  width: '28px',
+                  height: '28px',
+                  transition: 'all 0.15s',
+                  opacity: connected && !loading && pendingApprovals.length === 0 ? 1 : 0.5,
+                }}
+                onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+                  if (connected && !loading && pendingApprovals.length === 0) {
+                    e.currentTarget.style.color = theme.primaryColor;
+                    e.currentTarget.style.borderColor = theme.primaryColor;
+                  }
+                }}
+                onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+                  e.currentTarget.style.color = theme.secondaryTextColor;
+                  e.currentTarget.style.borderColor = theme.borderColor;
+                }}
+                title={strings.fileUpload.attachFiles}
+              >
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+                  <line x1="12" y1="5" x2="12" y2="19" />
+                  <line x1="5" y1="12" x2="19" y2="12" />
+                </svg>
+              </button>
+            )}
+          </div>
+
+          {/* Right side - send / stop button.
+              While loading and a stop handler is wired up, swap in a stop
+              button so the user can interrupt streaming. Disabled when a
+              tool is currently executing — that branch can't be safely
+              cancelled in Phase 1 because the tool's side effects have
+              already run on the client. */}
+          {(() => {
+            if (loading && onAbort) {
+              return (
+                <button
+                  data-testid="chat-stop-button"
+                  className="chat-stop-button"
+                  onClick={onAbort}
+                  disabled={!canAbort}
+                  title={canAbort ? 'Stop generating' : 'Cannot stop while a tool is running'}
+                  aria-label="Stop generating"
+                  style={{
+                    padding: '6px',
+                    background: canAbort ? theme.stopButtonBackground : theme.buttonDisabledBackground,
+                    color: theme.secondaryTextColor,
+                    border: 'none',
+                    borderRadius: '50%',
+                    cursor: canAbort ? 'pointer' : 'not-allowed',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    width: '32px',
+                    height: '32px',
+                    transition: 'all 0.2s',
+                  }}
+                >
+                  <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" stroke="none">
+                    <rect x="6" y="6" width="12" height="12" rx="2" />
+                  </svg>
+                </button>
+              );
+            }
+            return (
+              <button
+                data-testid="chat-send-button"
+                className="chat-send-button"
+                onClick={onSend}
+                disabled={!canSend}
+                style={{
+                  padding: '6px',
+                  background: canSend ? theme.primaryGradient : theme.buttonDisabledBackground,
+                  color: canSend ? 'white' : theme.secondaryTextColor,
+                  border: 'none',
+                  borderRadius: '50%',
+                  cursor: canSend ? 'pointer' : 'not-allowed',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  width: '32px',
+                  height: '32px',
+                  transition: 'all 0.2s',
+                }}
+              >
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+                  <line x1="12" y1="19" x2="12" y2="5" />
+                  <polyline points="5 12 12 5 19 12" />
+                </svg>
+              </button>
+            );
+          })()}
+        </div>
+      </div>
+
+    </div>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/DefaultDisclaimer.tsx b/packages/client/src/components/chatSlots/DefaultDisclaimer.tsx
new file mode 100644
index 00000000..98f724f3
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultDisclaimer.tsx
@@ -0,0 +1,22 @@
+import React from 'react';
+import { useTheme } from '../../theme';
+import type { ChatDisclaimerSlotProps } from './types';
+
+/** The notice under the composer reminding the user the AI can be wrong. */
+export function DefaultDisclaimer({ text }: ChatDisclaimerSlotProps) {
+  const theme = useTheme();
+
+  return (
+    <div
+      data-testid="chat-input-disclaimer"
+      style={{
+        padding: '8px 16px 16px',
+        fontSize: '12px',
+        lineHeight: 1.3,
+        color: theme.disclaimerTextColor,
+      }}
+    >
+      {text}
+    </div>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/DefaultEmptyState.tsx b/packages/client/src/components/chatSlots/DefaultEmptyState.tsx
new file mode 100644
index 00000000..1b34acdb
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultEmptyState.tsx
@@ -0,0 +1,83 @@
+import React from 'react';
+import { useStrings, useTheme } from '../../theme';
+import type { ChatEmptyStateSlotProps } from './types';
+
+/** The greeting and suggestion buttons shown before a chat has any messages. */
+export function DefaultEmptyState({
+  suggestions,
+  connected,
+  loading,
+  onSelectSuggestion,
+}: ChatEmptyStateSlotProps) {
+  const theme = useTheme();
+  const strings = useStrings();
+  const interactive = connected && !loading;
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        padding: '40px 20px',
+        gap: '20px',
+      }}
+    >
+      <div style={{ textAlign: 'center', color: theme.secondaryTextColor, fontSize: '14px' }}>
+        <p style={{ margin: 0, fontSize: '32px', marginBottom: '12px' }}>💬</p>
+        <p style={{ margin: 0 }}>{strings.emptyChat.startConversation}</p>
+        <p style={{ margin: '8px 0 0', fontSize: '12px' }}>
+          {strings.emptyChat.askMeToHelp}
+        </p>
+      </div>
+
+      {suggestions.length > 0 && (
+        <div
+          style={{
+            display: 'grid',
+            gridTemplateColumns: '1fr',
+            gap: '8px',
+            width: '100%',
+            maxWidth: '320px',
+          }}
+        >
+          {suggestions.map((suggestion, index) => (
+            <button
+              key={index}
+              data-testid="chat-suggestion-button"
+              onClick={() => onSelectSuggestion(suggestion)}
+              disabled={!interactive}
+              style={{
+                padding: '10px 14px',
+                background: theme.backgroundColor,
+                border: `1px solid ${theme.borderColor}`,
+                borderRadius: '8px',
+                fontSize: '13px',
+                color: theme.textColor,
+                cursor: interactive ? 'pointer' : 'not-allowed',
+                textAlign: 'left',
+                transition: 'all 0.2s',
+                lineHeight: '1.4',
+                opacity: interactive ? 1 : 0.5,
+              }}
+              onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+                if (interactive) {
+                  e.currentTarget.style.background = theme.hoverBackground;
+                  e.currentTarget.style.transform = 'translateY(-1px)';
+                  e.currentTarget.style.boxShadow = '0 2px 8px rgba(0, 0, 0, 0.08)';
+                }
+              }}
+              onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+                e.currentTarget.style.background = theme.backgroundColor;
+                e.currentTarget.style.transform = 'translateY(0)';
+                e.currentTarget.style.boxShadow = 'none';
+              }}
+            >
+              {suggestion}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/DefaultHeader.tsx b/packages/client/src/components/chatSlots/DefaultHeader.tsx
new file mode 100644
index 00000000..a9a1c80e
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultHeader.tsx
@@ -0,0 +1,425 @@
+import React, { useState } from 'react';
+import { useDropdownState } from '../../hooks/useDropdownState';
+import { useStrings, useTheme } from '../../theme';
+import { getDisplayTextFromContent } from '../../utils/messageContent';
+import type { Chat } from '../../providers/chatRepository/types';
+import type { AgentInfo } from '../../types';
+import type { ChatHeaderSlotProps } from './types';
+
+/**
+ * The title bar: chat history picker, agent picker, connection status, and the
+ * new/delete chat controls.
+ */
+export function DefaultHeader({
+  messages,
+  currentChatId,
+  availableAgents,
+  defaultAgent,
+  selectedAgent,
+  closeButton,
+  onNewChat,
+  onDeleteChat,
+  onListChats,
+  onLoadChat,
+  onAgentChange,
+}: ChatHeaderSlotProps) {
+  const theme = useTheme();
+  const strings = useStrings();
+  const chatHistoryDropdown = useDropdownState();
+  const agentDropdown = useDropdownState();
+  const [chatHistory, setChatHistory] = useState<Array<Omit<Chat, 'messages'>>>([]);
+
+  const handleNewChat = async () => {
+    if (onNewChat) {
+      await onNewChat();
+    }
+  };
+
+  const handleDeleteChat = async () => {
+    if (onDeleteChat && currentChatId && confirm(strings.header.deleteConfirm)) {
+      await onDeleteChat(currentChatId);
+      if (onNewChat) {
+        await onNewChat();
+      }
+    }
+  };
+
+  const handleLoadChat = async (chatId: string) => {
+    if (onLoadChat) {
+      await onLoadChat(chatId);
+      chatHistoryDropdown.close();
+    }
+  };
+
+  return (
+    <>
+    <div
+      style={{
+        padding: '12px 16px',
+        borderBottom: `1px solid ${theme.borderColor}`,
+        background: theme.backgroundColor,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: '12px',
+      }}
+    >
+      {/* Left side: Chat dropdown */}
+      <div style={{ flex: 1, minWidth: 0, position: 'relative' }}>
+        {onListChats ? (
+          <button
+            data-testid="chat-history-dropdown-button"
+            onClick={async () => {
+              const chats = await onListChats();
+              setChatHistory(chats);
+              chatHistoryDropdown.toggle();
+            }}
+            style={{
+              background: 'transparent',
+              border: 'none',
+              padding: '6px 8px',
+              cursor: 'pointer',
+              display: 'flex',
+              alignItems: 'center',
+              gap: '8px',
+              fontSize: '14px',
+              fontWeight: '600',
+              color: theme.textColor,
+              borderRadius: '6px',
+              transition: 'background 0.2s',
+              width: '100%',
+              textAlign: 'left',
+              overflow: 'hidden',
+            }}
+            onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+              e.currentTarget.style.background = theme.hoverBackground;
+            }}
+            onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+              e.currentTarget.style.background = 'transparent';
+            }}
+          >
+            <span style={{
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              whiteSpace: 'nowrap',
+              flex: 1,
+              minWidth: 0,
+            }}>
+              {/* Get current chat title */}
+              {(() => {
+                if (messages.length > 0) {
+                  const firstUserMsg = messages.find((m) => m.role === 'user');
+                  if (firstUserMsg) {
+                    const textContent = getDisplayTextFromContent(firstUserMsg.content);
+                    const maxLength = 30;
+                    return textContent.length > maxLength
+                      ? textContent.substring(0, maxLength) + '...'
+                      : textContent || strings.header.newChat;
+                  }
+                }
+                return strings.header.newChat;
+              })()}
+            </span>
+            <svg width="12" height="12" viewBox="0 0 12 12" fill="none" style={{ flexShrink: 0 }}>
+              <path d="M3 4.5L6 7.5L9 4.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+            </svg>
+          </button>
+        ) : (
+          <div style={{ fontSize: '14px', fontWeight: '600', color: theme.textColor, padding: '6px 8px' }}>
+            {strings.header.aiAssistant}
+          </div>
+        )}
+      </div>
+
+      {/* Right side: Actions */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}>
+        {/* Model selector */}
+        {availableAgents && availableAgents.length > 1 && onAgentChange && (
+          <div style={{ position: 'relative' }}>
+            <button
+              data-testid="agent-selector"
+              onClick={agentDropdown.toggle}
+              style={{
+                background: 'transparent',
+                border: 'none',
+                padding: '6px 8px',
+                cursor: 'pointer',
+                display: 'flex',
+                alignItems: 'center',
+                gap: '4px',
+                fontSize: '13px',
+                fontWeight: '500',
+                color: theme.secondaryTextColor,
+                borderRadius: '6px',
+                transition: 'all 0.2s',
+              }}
+              onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+                e.currentTarget.style.background = theme.hoverBackground;
+                e.currentTarget.style.color = theme.textColor;
+              }}
+              onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+                e.currentTarget.style.background = 'transparent';
+                e.currentTarget.style.color = theme.secondaryTextColor;
+              }}
+              title="Select AI model"
+            >
+              <span style={{
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                maxWidth: '120px',
+              }}>
+                {(() => {
+                  const agent = availableAgents.find((a: AgentInfo) => a.id === (selectedAgent ?? defaultAgent));
+                  return agent?.name || 'AI';
+                })()}
+              </span>
+              <svg width="10" height="10" viewBox="0 0 12 12" fill="none" style={{ flexShrink: 0 }}>
+                <path d="M3 4.5L6 7.5L9 4.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+              </svg>
+            </button>
+
+            {/* Agent Selector Dropdown */}
+            {agentDropdown.isOpen && (
+              <div
+                style={{
+                  position: 'absolute',
+                  top: '100%',
+                  left: '50%',
+                  transform: 'translateX(-50%)',
+                  marginTop: '4px',
+                  minWidth: '180px',
+                  maxWidth: '280px',
+                  background: theme.backgroundColor,
+                  borderRadius: '8px',
+                  boxShadow: '0 4px 16px rgba(0, 0, 0, 0.15)',
+                  zIndex: 1003,
+                  overflow: 'hidden',
+                  padding: '4px',
+                }}
+              >
+                {availableAgents.map((agent: AgentInfo) => {
+                  const isSelected = agent.id === (selectedAgent ?? defaultAgent);
+                  return (
+                    <div
+                      key={agent.id}
+                      data-testid="agent-option"
+                      onClick={() => {
+                        onAgentChange(agent.id === defaultAgent ? null : agent.id);
+                        agentDropdown.close();
+                      }}
+                      style={{
+                        padding: '8px 12px',
+                        background: isSelected ? theme.activeBackground : 'transparent',
+                        borderRadius: '6px',
+                        cursor: 'pointer',
+                        transition: 'background 0.15s',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'space-between',
+                        gap: '8px',
+                      }}
+                      onMouseEnter={(e: React.MouseEvent<HTMLDivElement>) => {
+                        if (!isSelected) {
+                          e.currentTarget.style.background = theme.hoverBackground;
+                        }
+                      }}
+                      onMouseLeave={(e: React.MouseEvent<HTMLDivElement>) => {
+                        if (!isSelected) {
+                          e.currentTarget.style.background = 'transparent';
+                        }
+                      }}
+                    >
+                      <div style={{ flex: 1, minWidth: 0 }}>
+                        <div style={{
+                          fontSize: '13px',
+                          fontWeight: isSelected ? '600' : '500',
+                          color: isSelected ? theme.primaryColor : theme.textColor,
+                        }}>
+                          {agent.name}
+                        </div>
+                        {agent.annotation && (
+                          <div style={{
+                            fontSize: '11px',
+                            color: theme.secondaryTextColor,
+                            marginTop: '2px',
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            whiteSpace: 'nowrap',
+                          }}>
+                            {agent.annotation}
+                          </div>
+                        )}
+                      </div>
+                      {isSelected && (
+                        <svg width="14" height="14" viewBox="0 0 14 14" fill="none" style={{ flexShrink: 0 }}>
+                          <path d="M2 7L5.5 10.5L12 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"/>
+                        </svg>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        )}
+
+        {/* New Chat button */}
+        {onNewChat && (
+          <button
+            data-testid="new-chat-button"
+            onClick={handleNewChat}
+            style={{
+              background: 'transparent',
+              border: 'none',
+              borderRadius: '6px',
+              padding: '6px 8px',
+              color: theme.secondaryTextColor,
+              fontSize: '13px',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              display: 'flex',
+              alignItems: 'center',
+              gap: '4px',
+            }}
+            onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+              e.currentTarget.style.background = theme.hoverBackground;
+              e.currentTarget.style.color = theme.textColor;
+            }}
+            onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+              e.currentTarget.style.background = 'transparent';
+              e.currentTarget.style.color = theme.secondaryTextColor;
+            }}
+            title={strings.header.newChat}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+              <path d="M8 3.5V12.5M3.5 8H12.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"/>
+            </svg>
+          </button>
+        )}
+
+        {/* Delete button */}
+        {onDeleteChat && messages.length > 0 && (
+          <button
+            data-testid="delete-chat-button"
+            onClick={handleDeleteChat}
+            style={{
+              background: 'transparent',
+              border: 'none',
+              borderRadius: '6px',
+              padding: '6px 8px',
+              color: theme.secondaryTextColor,
+              fontSize: '13px',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+            }}
+            onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+              e.currentTarget.style.background = theme.hoverBackground;
+              e.currentTarget.style.color = theme.textColor;
+            }}
+            onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+              e.currentTarget.style.background = 'transparent';
+              e.currentTarget.style.color = theme.secondaryTextColor;
+            }}
+            title={strings.header.deleteChat}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+              <path d="M2 4H14M6.5 7V11M9.5 7V11M3 4L4 13C4 13.5304 4.21071 14.0391 4.58579 14.4142C4.96086 14.7893 5.46957 15 6 15H10C10.5304 15 11.0391 14.7893 11.4142 14.4142C11.7893 14.0391 12 13.5304 12 13L13 4M5.5 4V2.5C5.5 2.23478 5.60536 1.98043 5.79289 1.79289C5.98043 1.60536 6.23478 1.5 6.5 1.5H9.5C9.76522 1.5 10.0196 1.60536 10.2071 1.79289C10.3946 1.98043 10.5 2.23478 10.5 2.5V4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+            </svg>
+          </button>
+        )}
+
+        {/* Optional close button (passed in for floating mode) */}
+        {closeButton}
+      </div>
+      </div>
+      {/* Chat History Dropdown */}
+      {chatHistoryDropdown.isOpen && onListChats && (
+        <div
+          style={{
+            position: 'absolute',
+            top: '60px',
+            left: '16px',
+            width: '320px',
+            maxHeight: '400px',
+            background: theme.backgroundColor,
+            borderRadius: '8px',
+            boxShadow: theme.panelShadow,
+            zIndex: 1003,
+            display: 'flex',
+            flexDirection: 'column',
+            overflow: 'hidden',
+          }}
+        >
+          {/* Chat List */}
+          <div
+            style={{
+              flex: 1,
+              overflowY: 'auto',
+              padding: '8px',
+            }}
+          >
+            {chatHistory.length === 0 ? (
+              <div
+                style={{
+                  textAlign: 'center',
+                  color: theme.secondaryTextColor,
+                  padding: '32px 16px',
+                  fontSize: '13px',
+                }}
+              >
+                <p style={{ margin: 0 }}>{strings.chatHistory.noChatHistory}</p>
+              </div>
+            ) : (
+              chatHistory.map((chat) => (
+                <div
+                  key={chat.id}
+                  data-testid="chat-history-item"
+                  onClick={() => handleLoadChat(chat.id)}
+                  style={{
+                    padding: '10px 12px',
+                    marginBottom: '4px',
+                    background: currentChatId === chat.id ? theme.activeBackground : 'transparent',
+                    borderRadius: '6px',
+                    cursor: 'pointer',
+                    transition: 'background 0.15s',
+                  }}
+                  onMouseEnter={(e: React.MouseEvent<HTMLDivElement>) => {
+                    if (currentChatId !== chat.id) {
+                      e.currentTarget.style.background = theme.hoverBackground;
+                    }
+                  }}
+                  onMouseLeave={(e: React.MouseEvent<HTMLDivElement>) => {
+                    if (currentChatId !== chat.id) {
+                      e.currentTarget.style.background = 'transparent';
+                    }
+                  }}
+                >
+                  <div style={{ fontSize: '13px', fontWeight: '500', color: theme.textColor, marginBottom: '4px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                    {chat.title || strings.header.newChat}
+                  </div>
+                  <div style={{ fontSize: '11px', color: theme.secondaryTextColor }}>
+                    {new Date(chat.updatedAt).toLocaleDateString([], { month: 'short', day: 'numeric' })}
+                    {currentChatId === chat.id && (
+                      <span style={{
+                        marginLeft: '8px',
+                        color: theme.primaryColor,
+                        fontWeight: '600',
+                      }}>
+                        • {strings.chatHistory.active}
+                      </span>
+                    )}
+                  </div>
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Backdrops to close dropdowns */}
+      {chatHistoryDropdown.Backdrop}
+      {agentDropdown.Backdrop}
+    </>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/DefaultMessage.tsx b/packages/client/src/components/chatSlots/DefaultMessage.tsx
new file mode 100644
index 00000000..d817e647
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultMessage.tsx
@@ -0,0 +1,241 @@
+import React, { useState } from 'react';
+import { useStrings, useTheme } from '../../theme';
+import { getDisplayTextFromContent, getTextFromContent } from '../../utils/messageContent';
+import { MarkdownContent } from '../MarkdownContent';
+import { FilePlaceholder } from '../FileChip';
+import { Reasoning } from '../Reasoning';
+import { FeedbackButton } from './FeedbackButton';
+import { fileChipInfo, hasFileContent } from './messageFiles';
+import type { PersistedContentPart } from '../../providers/chatRepository/types';
+import type { ChatMessageSlotProps } from './types';
+
+/** One chat bubble: the message body plus its reasoning, files and feedback. */
+export function DefaultMessage({
+  message,
+  streaming,
+  streamingReasoning,
+  feedbackEnabled,
+  onFeedback,
+  saveAsCommand,
+}: ChatMessageSlotProps) {
+  const theme = useTheme();
+  const strings = useStrings();
+  const [hovered, setHovered] = useState(false);
+
+  // Info notices (e.g. the abort "generation stopped" bubble) are display-only
+  // system messages. Render a compact, centered pill: no reasoning dropdown,
+  // markdown, feedback, or hover affordances.
+  if (message.displayMode === 'info') {
+    return (
+      <div
+        data-testid="chat-message-info"
+        className="chat-message chat-message-info"
+        style={{ display: 'flex', justifyContent: 'center', padding: '2px 0' }}
+      >
+        <div
+          style={{
+            maxWidth: '80%',
+            padding: '6px 12px',
+            borderRadius: '12px',
+            background: theme.assistantMessageBackground,
+            color: theme.secondaryTextColor,
+            fontSize: '12px',
+            lineHeight: '1.4',
+            textAlign: 'center',
+            wordWrap: 'break-word',
+          }}
+        >
+          {getDisplayTextFromContent(message.content)}
+        </div>
+      </div>
+    );
+  }
+
+  // The provisional bubble is deliberately kept out of `chat-message-assistant`
+  // and `chat-message-content`: the E2E suites wait on those test ids to mean
+  // "the answer is done", and a bubble that appears with the first token would
+  // satisfy that wait mid-stream. Only the attributes change when the answer is
+  // persisted, so the elements themselves, and any selection inside them, are
+  // untouched.
+  const messageTestId = streaming ? 'chat-message-assistant-streaming' : `chat-message-${message.role}`;
+  const contentTestId = streaming ? 'chat-message-content-streaming' : 'chat-message-content';
+  const text = getTextFromContent(message.content);
+
+  return (
+    <div
+      data-testid={messageTestId}
+      className={`chat-message chat-message-${message.role}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: message.role === 'user' ? 'flex-end' : 'flex-start',
+      }}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+    >
+    <div
+      style={{
+        position: 'relative',
+        maxWidth: '80%',
+      }}
+    >
+      {/* Save as command button - appears on hover for user messages */}
+      {hovered && saveAsCommand && !saveAsCommand.isEditing && (
+        <button
+          data-testid="save-command-button"
+          onClick={(e) => {
+            e.stopPropagation();
+            saveAsCommand.start();
+          }}
+          title="Save as slash command"
+          style={{
+            position: 'absolute',
+            top: '-8px',
+            right: '-8px',
+            width: '24px',
+            height: '24px',
+            borderRadius: '50%',
+            border: 'none',
+            background: theme.backgroundColor,
+            boxShadow: '0 2px 6px rgba(0, 0, 0, 0.15)',
+            cursor: 'pointer',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: theme.primaryColor,
+            transition: 'all 0.15s',
+            zIndex: 10,
+          }}
+          onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+            e.currentTarget.style.transform = 'scale(1.1)';
+            e.currentTarget.style.boxShadow = '0 3px 8px rgba(0, 0, 0, 0.2)';
+          }}
+          onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+            e.currentTarget.style.transform = 'scale(1)';
+            e.currentTarget.style.boxShadow = '0 2px 6px rgba(0, 0, 0, 0.15)';
+          }}
+        >
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z" />
+            <polyline points="17 21 17 13 7 13 7 21" />
+            <polyline points="7 3 7 8 15 8" />
+          </svg>
+        </button>
+      )}
+      <div
+        data-testid={contentTestId}
+        className={`chat-message-content${message.role === 'assistant' ? ' markdown-content' : ''}`}
+        style={{
+          padding: '10px 14px',
+          borderRadius: saveAsCommand?.isEditing
+            ? '12px 12px 0 0'
+            : '12px',
+          background: message.displayMode === 'error'
+            ? theme.errorBackground
+            : message.role === 'user'
+            ? theme.primaryGradient
+            : theme.assistantMessageBackground,
+          color: message.displayMode === 'error'
+            ? theme.errorTextColor
+            : message.role === 'user' ? 'white' : theme.textColor,
+          fontSize: '14px',
+          lineHeight: '1.5',
+          wordWrap: 'break-word',
+        }}
+      >
+      {/* Render file placeholders for user messages with files */}
+      {message.role === 'user' && hasFileContent(message.content) && (
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: '6px', marginBottom: '8px' }}>
+          {message.content.flatMap((part: PersistedContentPart, idx: number) => {
+            const info = fileChipInfo(part);
+            return info
+              ? [<FilePlaceholder key={idx} name={info.name} size={info.size} />]
+              : [];
+          })}
+        </div>
+      )}
+      {message.role === 'assistant' ? (
+        <>
+          {streaming && streamingReasoning && (
+            <Reasoning
+              reasoningParts={[]}
+              isStreaming={true}
+              streamingText={streamingReasoning}
+              theme={theme}
+              strings={strings}
+            />
+          )}
+          {!streaming && message.reasoningParts && message.reasoningParts.length > 0 && (
+            <Reasoning
+              reasoningParts={message.reasoningParts}
+              theme={theme}
+              strings={strings}
+            />
+          )}
+          {streaming && !text ? (
+            <span className="dots" style={{ opacity: 0.6 }}>...</span>
+          ) : (
+            <MarkdownContent content={getTextFromContent(message.content)} />
+          )}
+        </>
+      ) : (
+        // User/tool bubbles: display-only text so transformed_file
+        // (e.g. OCR body) isn't dumped into the chat bubble.
+        getDisplayTextFromContent(message.content)
+      )}
+      </div>
+      {/* Inline save command UI - glued to chat bubble */}
+      {saveAsCommand?.editor}
+    </div>
+    {/* Feedback buttons - only for assistant messages with traceId */}
+    {message.role === 'assistant' && !streaming && message.traceId && feedbackEnabled && onFeedback && (
+      <div
+        data-testid="feedback-buttons"
+        style={{
+          display: 'flex',
+          gap: '4px',
+          marginTop: '4px',
+          padding: '0 4px',
+        }}
+      >
+        <FeedbackButton
+          type="upvote"
+          isSelected={message.feedback === 'upvote'}
+          onClick={() => {
+            const newFeedback = message.feedback === 'upvote' ? null : 'upvote';
+            onFeedback(message.id, message.traceId!, newFeedback);
+          }}
+          selectedColor={theme.primaryColor}
+          unselectedColor={theme.secondaryTextColor}
+        />
+        <FeedbackButton
+          type="downvote"
+          isSelected={message.feedback === 'downvote'}
+          onClick={() => {
+            const newFeedback = message.feedback === 'downvote' ? null : 'downvote';
+            onFeedback(message.id, message.traceId!, newFeedback);
+          }}
+          selectedColor={theme.errorTextColor}
+          unselectedColor={theme.secondaryTextColor}
+        />
+      </div>
+    )}
+    {!streaming && (
+      <div
+        data-testid="message-timestamp"
+        style={{
+          fontSize: '11px',
+          color: theme.secondaryTextColor,
+          marginTop: '4px',
+          padding: '0 4px',
+        }}
+      >
+        {message.createdAt.toLocaleTimeString([], {
+          hour: '2-digit',
+          minute: '2-digit'
+        })}
+      </div>
+    )}
+    </div>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/DefaultPendingIndicator.tsx b/packages/client/src/components/chatSlots/DefaultPendingIndicator.tsx
new file mode 100644
index 00000000..343c25c2
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultPendingIndicator.tsx
@@ -0,0 +1,67 @@
+import React from 'react';
+import { useStrings, useTheme } from '../../theme';
+import type { ChatPendingIndicatorSlotProps } from './types';
+
+/**
+ * The bubble shown between a run starting and its answer producing a first
+ * token, and while a send-time file transformation runs.
+ */
+export function DefaultPendingIndicator({ fileProcessing }: ChatPendingIndicatorSlotProps) {
+  const theme = useTheme();
+  const strings = useStrings();
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'flex-start',
+      }}
+    >
+      <div
+        className="markdown-content"
+        style={{
+          padding: '10px 14px',
+          borderRadius: '12px',
+          background: theme.assistantMessageBackground,
+          fontSize: '14px',
+          lineHeight: '1.5',
+          color: theme.textColor,
+          maxWidth: '80%',
+        }}
+      >
+        {fileProcessing && fileProcessing.status === 'processing' ? (
+          <div>
+            <span style={{ opacity: 0.6 }}>{strings.input.processingFile}</span>
+            {fileProcessing.progress != null && (
+              <>
+                <span style={{ opacity: 0.6, marginLeft: '4px' }}>
+                  {Math.round(fileProcessing.progress)}%
+                </span>
+                <div style={{
+                  marginTop: '6px',
+                  height: '4px',
+                  borderRadius: '2px',
+                  background: theme.borderColor,
+                  overflow: 'hidden',
+                }}>
+                  <div style={{
+                    height: '100%',
+                    width: `${fileProcessing.progress}%`,
+                    borderRadius: '2px',
+                    background: theme.primaryColor,
+                    transition: 'width 0.3s ease',
+                  }} />
+                </div>
+              </>
+            )}
+            {fileProcessing.progress == null && (
+              <span className="dots" style={{ marginLeft: '4px' }}>...</span>
+            )}
+          </div>
+        ) : (
+          <span className="dots" style={{ opacity: 0.6 }}>...</span>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/DefaultToolApproval.tsx b/packages/client/src/components/chatSlots/DefaultToolApproval.tsx
new file mode 100644
index 00000000..df83ecd3
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultToolApproval.tsx
@@ -0,0 +1,31 @@
+import React from 'react';
+import { useStrings, useTheme } from '../../theme';
+import { ToolApprovalDialog } from '../ToolApprovalDialog';
+import type { ChatToolApprovalSlotProps } from './types';
+
+/** Confirmation controls for tool calls the AI may not run unattended. */
+export function DefaultToolApproval({ approvals, onApprove, onReject }: ChatToolApprovalSlotProps) {
+  const theme = useTheme();
+  const strings = useStrings();
+
+  return (
+    <div
+      style={{
+        padding: '16px',
+        borderTop: `1px solid ${theme.borderColor}`,
+      }}
+    >
+      <ToolApprovalDialog
+        toolCallName={approvals[0].toolCallName}
+        toolCallArgs={approvals[0].toolCallArgs}
+        annotations={approvals[0].annotations}
+        toolCount={approvals.length}
+        pendingTools={approvals}
+        onApprove={onApprove}
+        onReject={onReject}
+        theme={theme}
+        strings={strings}
+      />
+    </div>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/FeedbackButton.tsx b/packages/client/src/components/chatSlots/FeedbackButton.tsx
new file mode 100644
index 00000000..fb1357e3
--- /dev/null
+++ b/packages/client/src/components/chatSlots/FeedbackButton.tsx
@@ -0,0 +1,88 @@
+import React, { useRef } from 'react';
+
+/**
+ * Props for the FeedbackButton component.
+ */
+interface FeedbackButtonProps {
+  /** The type of feedback this button represents */
+  type: 'upvote' | 'downvote';
+  /** Whether this feedback type is currently selected */
+  isSelected: boolean;
+  /** Callback when clicked */
+  onClick: () => void;
+  /** Color when selected */
+  selectedColor: string;
+  /** Color when not selected */
+  unselectedColor: string;
+}
+
+/**
+ * Thumbs up/down feedback button with pop animation.
+ */
+export function FeedbackButton({ type, isSelected, onClick, selectedColor, unselectedColor }: FeedbackButtonProps) {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  const handleClick = () => {
+    // Pop animation only on select, not de-select
+    if (!isSelected && buttonRef.current) {
+      buttonRef.current.style.transform = 'scale(1.3)';
+      setTimeout(() => {
+        if (buttonRef.current) {
+          buttonRef.current.style.transform = 'scale(1)';
+        }
+      }, 150);
+    }
+    onClick();
+  };
+
+  const thumbsUpPath = "M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9a2 2 0 0 0-2-2.3zM7 22H4a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h3";
+  const thumbsDownPath = "M10 15v4a3 3 0 0 0 3 3l4-9V2H5.72a2 2 0 0 0-2 1.7l-1.38 9a2 2 0 0 0 2 2.3zm7-13h2.67A2.31 2.31 0 0 1 22 4v7a2.31 2.31 0 0 1-2.33 2H17";
+
+  return (
+    <button
+      ref={buttonRef}
+      data-testid={`feedback-${type}`}
+      onClick={handleClick}
+      title={type === 'upvote' ? 'Good response' : 'Poor response'}
+      style={{
+        background: 'transparent',
+        border: 'none',
+        padding: '4px',
+        cursor: 'pointer',
+        color: isSelected ? selectedColor : unselectedColor,
+        opacity: isSelected ? 1 : 0.5,
+        transition: 'all 0.15s',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        borderRadius: '4px',
+        transform: 'scale(1)',
+      }}
+      onMouseEnter={(e: React.MouseEvent<HTMLButtonElement>) => {
+        if (!isSelected) {
+          e.currentTarget.style.opacity = '0.8';
+          e.currentTarget.style.color = selectedColor;
+        }
+      }}
+      onMouseLeave={(e: React.MouseEvent<HTMLButtonElement>) => {
+        if (!isSelected) {
+          e.currentTarget.style.opacity = '0.5';
+          e.currentTarget.style.color = unselectedColor;
+        }
+      }}
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill={isSelected ? 'currentColor' : 'none'}
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d={type === 'upvote' ? thumbsUpPath : thumbsDownPath} />
+      </svg>
+    </button>
+  );
+}
diff --git a/packages/client/src/components/chatSlots/Slot.tsx b/packages/client/src/components/chatSlots/Slot.tsx
new file mode 100644
index 00000000..0ccb11e0
--- /dev/null
+++ b/packages/client/src/components/chatSlots/Slot.tsx
@@ -0,0 +1,30 @@
+import React from 'react';
+import type { ChatSlotProps } from './types';
+
+interface SlotProps<P extends ChatSlotProps> {
+  /** The host's replacement for this region, if it supplied one. */
+  component?: React.ComponentType<P>;
+  /** The built-in implementation, handed to the override as `children`. */
+  fallback: React.ComponentType<P>;
+  props: Omit<P, 'children'>;
+}
+
+/**
+ * Renders one region of the chat, preferring the host's component over the
+ * built-in one.
+ *
+ * The built-in implementation is passed to an override as `children` so it can
+ * be decorated rather than replaced. It is created as an element, not rendered,
+ * so an override that ignores `children` costs nothing.
+ *
+ * @internal
+ */
+export function Slot<P extends ChatSlotProps>({
+  component: Override,
+  fallback: Fallback,
+  props,
+}: SlotProps<P>) {
+  const built = React.createElement(Fallback, props as P);
+  if (!Override) return built;
+  return React.createElement(Override, { ...props, children: built } as P);
+}
diff --git a/packages/client/src/components/chatSlots/index.ts b/packages/client/src/components/chatSlots/index.ts
new file mode 100644
index 00000000..07d49e6d
--- /dev/null
+++ b/packages/client/src/components/chatSlots/index.ts
@@ -0,0 +1,9 @@
+export * from './types';
+export { Slot } from './Slot';
+export { DefaultHeader } from './DefaultHeader';
+export { DefaultEmptyState } from './DefaultEmptyState';
+export { DefaultMessage } from './DefaultMessage';
+export { DefaultPendingIndicator } from './DefaultPendingIndicator';
+export { DefaultComposer } from './DefaultComposer';
+export { DefaultToolApproval } from './DefaultToolApproval';
+export { DefaultDisclaimer } from './DefaultDisclaimer';
diff --git a/packages/client/src/components/chatSlots/messageFiles.ts b/packages/client/src/components/chatSlots/messageFiles.ts
new file mode 100644
index 00000000..f8f1a263
--- /dev/null
+++ b/packages/client/src/components/chatSlots/messageFiles.ts
@@ -0,0 +1,24 @@
+import type { PersistedContentPart, PersistedMessageContent } from '../../providers/chatRepository/types';
+
+/**
+ * Helper that checks whether `content` includes a file attachment. Covers both
+ * the metadata-only `file` and the ref-based `attachment_ref`; both are rendered as
+ * a name/size FilePlaceholder.
+ */
+export function hasFileContent(content: PersistedMessageContent): content is PersistedContentPart[] {
+  return (
+    Array.isArray(content) &&
+    content.some(part => part.type === 'file' || part.type === 'attachment_ref')
+  );
+}
+
+/** Extracts name + size from a file-bearing persisted part for the FilePlaceholder shown on reload. */
+export function fileChipInfo(part: PersistedContentPart): { name: string; size: number } | null {
+  if (part.type === 'file') {
+    return { name: part.file.name, size: part.file.size };
+  }
+  if (part.type === 'attachment_ref') {
+    return { name: part.name, size: part.size };
+  }
+  return null;
+}
diff --git a/packages/client/src/components/chatSlots/types.ts b/packages/client/src/components/chatSlots/types.ts
new file mode 100644
index 00000000..eef8be1b
--- /dev/null
+++ b/packages/client/src/components/chatSlots/types.ts
@@ -0,0 +1,186 @@
+import type React from 'react';
+import type { AgentInfo, FeedbackValue, ToolAnnotations } from '../../types';
+import type { Chat, PersistedMessage } from '../../providers/chatRepository/types';
+import type { FileAttachment, FileProcessingState } from '../../fileUpload/types';
+import type { ChatStreamingPart, ExecutingToolDisplay } from '../../hooks/useServerEvents';
+import type { SubmitMode } from '../../utils/keyboard';
+
+/** A tool call that is waiting for user approval. */
+export interface ChatToolApproval {
+  toolCallId: string;
+  toolCallName: string;
+  toolCallArgs: Record<string, unknown>;
+  annotations?: ToolAnnotations;
+}
+
+/** Common contract for chat component overrides. */
+export interface ChatSlotProps {
+  /** The built-in UI. Render this to decorate it, or omit it to replace it. */
+  children?: React.ReactNode;
+}
+
+export interface ChatHeaderSlotProps extends ChatSlotProps {
+  connected: boolean;
+  messages: PersistedMessage[];
+  currentChatId: string | null;
+  availableAgents: AgentInfo[];
+  defaultAgent: string | null;
+  selectedAgent: string | null;
+  closeButton?: React.ReactNode;
+  onNewChat?: () => Promise<string | void>;
+  onDeleteChat?: (chatId: string) => Promise<void>;
+  onListChats?: () => Promise<Array<Omit<Chat, 'messages'>>>;
+  onLoadChat?: (chatId: string) => Promise<void>;
+  onAgentChange?: (agentId: string | null) => void;
+}
+
+export interface ChatEmptyStateSlotProps extends ChatSlotProps {
+  suggestions: string[];
+  connected: boolean;
+  loading: boolean;
+  onSelectSuggestion: (suggestion: string) => void;
+}
+
+export interface ChatMessageSlotProps extends ChatSlotProps {
+  /**
+   * While `streaming` is true this is the provisional entry for the answer that
+   * is still arriving: `content` holds the text received so far, and `createdAt`,
+   * `traceId`, `feedback` and `reasoningParts` are not populated yet. It carries
+   * the id the answer will be persisted under, so the same slot instance keeps
+   * rendering it once the run finishes.
+   *
+   * The slot itself keeps its React key across that handoff, but the keys it
+   * gives its own children must match on both sides too. Deriving them from
+   * `streamingParts` while streaming and from `sourceMessages` afterwards
+   * produces different keys for the same text, which remounts it and drops any
+   * selection the user was making. Key by position within the turn rather than
+   * by message id: a turn's earlier steps only get their ids once the turn is
+   * persisted, so an id-derived key cannot be stable for them.
+   */
+  message: PersistedMessage;
+  index: number;
+  isLast: boolean;
+  /**
+   * The raw messages this entry was built from, in the order they were
+   * produced: the per-step assistant messages with their `toolCalls` and
+   * `reasoningParts`, and the `tool` messages holding each call's result.
+   * Merging into one bubble drops all of that, so render from here instead when
+   * the turn should read as a timeline. Empty while `streaming` is true.
+   */
+  sourceMessages: PersistedMessage[];
+  /** Whether this message is the answer currently being streamed. */
+  streaming: boolean;
+  /**
+   * Extended-thinking text received so far, with every step's reasoning joined
+   * into one string. Prefer `streamingParts` when the steps should stay apart.
+   * Only populated while `streaming` is true; once persisted the reasoning is
+   * on `message.reasoningParts`.
+   */
+  streamingReasoning: string;
+  /**
+   * The answer so far, split into the parts the model emitted and kept in
+   * order: reasoning, text and tool calls as they happened. This is the
+   * streaming counterpart of `sourceMessages`, so a slot can render a run the
+   * same way while it happens and after it is persisted. Empty unless
+   * `streaming` is true.
+   */
+  streamingParts: ChatStreamingPart[];
+  feedbackEnabled: boolean;
+  onFeedback?: (messageId: string, traceId: string, feedback: FeedbackValue) => void;
+  /**
+   * Present on user messages when saving one as a slash command is available.
+   * Absent when the feature is disabled or the host provided no save handler.
+   */
+  saveAsCommand?: ChatSaveAsCommand;
+}
+
+/** Turning a user message into a reusable slash command. */
+export interface ChatSaveAsCommand {
+  /** Whether the inline naming editor for this message is open. */
+  isEditing: boolean;
+  /** Opens the inline naming editor. */
+  start: () => void;
+  /** Saves the message as a command under `name`, resolving to its id. */
+  save: (name: string) => Promise<string>;
+  /** The built-in naming editor. Render it to reuse it, or build your own with `save`. */
+  editor: React.ReactNode;
+}
+
+/**
+ * The placeholder shown after a run starts but before the answer produces its
+ * first token, and while a send-time file transformation (e.g. OCR) runs. Once
+ * text or reasoning arrives the answer renders through the `Message` slot
+ * instead, so this stops being rendered.
+ */
+export interface ChatPendingIndicatorSlotProps extends ChatSlotProps {
+  executingTool: ExecutingToolDisplay | null;
+  fileProcessing: FileProcessingState | null;
+}
+
+export interface ChatComposerSlotProps extends ChatSlotProps {
+  input: string;
+  connected: boolean;
+  loading: boolean;
+  placeholder: string;
+  canSend: boolean;
+  canAbort: boolean;
+  attachments: FileAttachment[];
+  fileUploadEnabled: boolean;
+  fileError: string | null;
+  pendingApprovals: ChatToolApproval[];
+  onInputChange: (value: string) => void;
+  onSend: () => void;
+  onAbort?: () => void;
+  onOpenFilePicker: () => void;
+  onRemoveAttachment: (attachmentId: string) => void;
+  /** How the Enter key should behave; see `UseAIChatProps.submitMode`. */
+  submitMode: SubmitMode;
+  /** Per-attachment transformation progress (e.g. OCR), keyed by attachment id. */
+  attachmentProcessing: Map<string, FileProcessingState>;
+  /**
+   * Whether a disclaimer renders directly below the composer. The built-in
+   * composer drops its bottom padding when it does.
+   */
+  disclaimerVisible: boolean;
+  /**
+   * The `/`-triggered command autocomplete. Wire `onKeyDown` into the input and
+   * render `list` to keep completion working; ignore it to drop the feature.
+   * `onInputChange` is already folded into this slot's own `onInputChange`.
+   */
+  slashCommands: ChatSlashCommands;
+}
+
+/** The `/`-triggered command autocomplete attached to the composer input. */
+export interface ChatSlashCommands {
+  /** Whether the autocomplete list is currently open. */
+  isOpen: boolean;
+  /** Feed key events here first; returns true when the autocomplete consumed the key. */
+  onKeyDown: (event: React.KeyboardEvent) => boolean;
+  /** The built-in autocomplete list, positioned relative to the composer input. */
+  list: React.ReactNode;
+}
+
+export interface ChatToolApprovalSlotProps extends ChatSlotProps {
+  approvals: ChatToolApproval[];
+  onApprove: () => void;
+  onReject: (reason?: string) => void;
+}
+
+export interface ChatDisclaimerSlotProps extends ChatSlotProps {
+  /** The configured disclaimer text. */
+  text: string;
+}
+
+/** Components that can replace individual regions of the built-in chat UI. */
+export interface UseAIChatComponents {
+  Header: React.ComponentType<ChatHeaderSlotProps>;
+  EmptyState: React.ComponentType<ChatEmptyStateSlotProps>;
+  Message: React.ComponentType<ChatMessageSlotProps>;
+  PendingIndicator: React.ComponentType<ChatPendingIndicatorSlotProps>;
+  Composer: React.ComponentType<ChatComposerSlotProps>;
+  ToolApproval: React.ComponentType<ChatToolApprovalSlotProps>;
+  Disclaimer: React.ComponentType<ChatDisclaimerSlotProps>;
+}
+
+/** Partial component overrides; omitted regions use the built-in implementation. */
+export type UseAIChatComponentOverrides = Partial<UseAIChatComponents>;
diff --git a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
new file mode 100644
index 00000000..f483109f
--- /dev/null
+++ b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
@@ -0,0 +1,98 @@
+import { describe, it, expect, mock } from 'bun:test';
+import { renderHook, act } from '@testing-library/react';
+import { useServerEvents } from './useServerEvents';
+import { defaultStrings } from '../theme/strings';
+import { EventType } from '../types';
+import type { UseToolSystemReturn } from './useToolSystem';
+import type { UseAIClient } from '../client';
+
+function makeToolSystem(): UseToolSystemReturn {
+  return {
+    aggregatedToolsRef: { current: {} },
+    executeToolCall: mock(async () => undefined),
+    storePendingToolCall: mock(),
+    handleApprovalRequest: mock(),
+  } as unknown as UseToolSystemReturn;
+}
+
+function makeClient() {
+  return {
+    messages: [],
+    currentMessageContent: '',
+    currentReasoningBlocks: [],
+    currentRunId: 'run-1',
+    finalizeRun: mock(() => {}),
+    currentToolCalls: new Map(),
+  } as unknown as UseAIClient;
+}
+
+function setup() {
+  const { result } = renderHook(() =>
+    useServerEvents({ toolSystem: makeToolSystem(), saveAIResponse: mock(async () => {}), strings: defaultStrings }),
+  );
+  return { result, client: makeClient() };
+}
+
+/**
+ * `streamingText` and `streamingReasoning` flatten a whole run into two
+ * strings, so a multi-step run's thinking arrives as one block. `streamingParts`
+ * keeps the step boundaries the run actually had.
+ */
+describe('useServerEvents — streaming parts', () => {
+  it('keeps each step of reasoning separate instead of concatenating them', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_START, messageId: 'r1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_CONTENT, messageId: 'r1', delta: 'First I check the time.' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_END, messageId: 'r1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_START, messageId: 'r2' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_CONTENT, messageId: 'r2', delta: 'Then I add the numbers.' });
+    });
+
+    expect(result.current.streamingParts).toEqual([
+      { kind: 'reasoning', text: 'First I check the time.' },
+      { kind: 'reasoning', text: 'Then I add the numbers.' },
+    ]);
+    // The flattened string keeps its existing shape for the built-in bubble.
+    expect(result.current.streamingReasoning).toBe('First I check the time.\n\nThen I add the numbers.');
+  });
+
+  it('interleaves reasoning, tool calls and text in the order they arrived', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_START, messageId: 'r1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_CONTENT, messageId: 'r1', delta: 'Need the time.' });
+      await result.current.handleServerEvent(client, { type: EventType.TOOL_CALL_START, toolCallId: 'tc1', toolCallName: 'getServerTime' });
+      await result.current.handleServerEvent(client, { type: EventType.TOOL_CALL_ARGS, toolCallId: 'tc1', delta: '{"tz":' });
+      await result.current.handleServerEvent(client, { type: EventType.TOOL_CALL_ARGS, toolCallId: 'tc1', delta: '"UTC"}' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_START, messageId: 'm1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm1', delta: 'It is noon.' });
+    });
+
+    expect(result.current.streamingParts).toEqual([
+      { kind: 'reasoning', text: 'Need the time.' },
+      { kind: 'tool_call', toolCallId: 'tc1', name: 'getServerTime', args: '{"tz":"UTC"}' },
+      { kind: 'text', text: 'It is noon.' },
+    ]);
+  });
+
+  it('clears the parts when the run finishes', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_START, messageId: 'm1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm1', delta: 'Done.' });
+    });
+    expect(result.current.streamingParts).toHaveLength(1);
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_FINISHED, threadId: 't', runId: 'run-1' });
+    });
+    expect(result.current.streamingParts).toEqual([]);
+  });
+});
diff --git a/packages/client/src/hooks/useServerEvents.ts b/packages/client/src/hooks/useServerEvents.ts
index 6c5b44f3..584df2cf 100644
--- a/packages/client/src/hooks/useServerEvents.ts
+++ b/packages/client/src/hooks/useServerEvents.ts
@@ -3,6 +3,7 @@ import type {
   AGUIEvent,
   ToolCallStartEvent,
   ToolCallEndEvent,
+  ToolCallArgsEvent,
   RunErrorEvent,
   RunFinishedEvent,
   TextMessageContentEvent,
@@ -35,7 +36,24 @@ export interface UseServerEventsOptions {
   strings: UseAIStrings;
 }
 
+/**
+ * One piece of the answer currently being produced, in the order the model
+ * emitted it. `streamingText` and `streamingReasoning` flatten a whole run into
+ * two strings, which loses the step boundaries; this keeps them, so a run that
+ * thinks, calls a tool, thinks again and answers can be shown as it happened.
+ */
+export type ChatStreamingPart =
+  | { kind: 'reasoning'; text: string }
+  | { kind: 'text'; text: string }
+  /** Args arrive as a JSON string, incomplete until the call is fully received. */
+  | { kind: 'tool_call'; toolCallId: string; name: string; args: string };
+
 export interface ExecutingToolDisplay {
+  /** @example "toolu_01abc123" */
+  toolCallId: string;
+  /** Registered tool name, e.g. "searchDocs". */
+  name: string;
+  /** The tool's `title` annotation, or a generic fallback when it has none. */
   displayText: string;
 }
 
@@ -62,6 +80,8 @@ export interface UseServerEventsReturn {
   streamingChatIdRef: React.MutableRefObject<string | null>;
   /** Current streaming reasoning text from extended thinking */
   streamingReasoning: string;
+  /** The in-flight answer split into ordered parts; empty between runs. */
+  streamingParts: ChatStreamingPart[];
   /**
    * Handles a server event. Called from the provider's client subscription.
    * Takes the client instance so it can access client-internal state
@@ -97,6 +117,7 @@ export function useServerEvents({
   const [loading, setLoading] = useState(false);
   const [streamingText, setStreamingText] = useState('');
   const [streamingReasoning, setStreamingReasoning] = useState('');
+  const [streamingParts, setStreamingParts] = useState<ChatStreamingPart[]>([]);
   const [streamingMessageId, setStreamingMessageId] = useState<string | null>(null);
   // Mirror of streamingMessageId for the stable event handler.
   const streamingMessageIdRef = useRef<string | null>(null);
@@ -120,6 +141,7 @@ export function useServerEvents({
   // Executing tool state for UI display
   const [executingToolRaw, setExecutingTool] = useState<{
     toolCallId: string;
+    name: string;
     title: string | null;
   } | null>(null);
   const executingToolFallbackRef = useRef<string | null>(null);
@@ -128,6 +150,17 @@ export function useServerEvents({
     setStreamingText('');
   }, []);
 
+  /** Appends `delta` to the trailing part of `kind`, starting one if needed. */
+  const appendToPart = useCallback((kind: 'reasoning' | 'text', delta: string) => {
+    setStreamingParts(prev => {
+      const last = prev[prev.length - 1];
+      if (last?.kind === kind) {
+        return [...prev.slice(0, -1), { ...last, text: last.text + delta }];
+      }
+      return [...prev, { kind, text: delta }];
+    });
+  }, []);
+
   // Keep refs to avoid stale closures in the event handler
   // (the handler is captured once per client lifecycle, but these deps may change)
   const toolSystemRef = useRef(toolSystem);
@@ -183,6 +216,7 @@ export function useServerEvents({
   const resetRunUiState = useCallback(() => {
     setStreamingText('');
     setStreamingReasoning('');
+    setStreamingParts([]);
     setStreamingMessageId(null);
     streamingMessageIdRef.current = null;
     streamingChatIdRef.current = null;
@@ -204,20 +238,31 @@ export function useServerEvents({
       runIdAtRunStartRef.current = client.currentRunId ?? undefined;
       hasTextFromPriorStepRef.current = false;
       setStreamingReasoning('');
+      setStreamingParts([]);
       const messageId = generateMessageId();
       streamingMessageIdRef.current = messageId;
       setStreamingMessageId(messageId);
     } else if (event.type === EventType.REASONING_MESSAGE_START) {
       // Add paragraph separator between reasoning from different steps
       setStreamingReasoning(prev => prev ? prev + '\n\n' : prev);
+      setStreamingParts(prev => [...prev, { kind: 'reasoning', text: '' }]);
     } else if (event.type === EventType.REASONING_MESSAGE_CONTENT) {
       const reasoningEvent = event as ReasoningMessageContentEvent;
       setStreamingReasoning(prev => prev + reasoningEvent.delta);
+      appendToPart('reasoning', reasoningEvent.delta);
     } else if (event.type === EventType.TEXT_MESSAGE_START) {
       // Add paragraph separator between steps so combined text reads naturally
       if (hasTextFromPriorStepRef.current) {
         setStreamingText(prev => prev + '\n\n');
       }
+      setStreamingParts(prev => [...prev, { kind: 'text', text: '' }]);
+    } else if (event.type === EventType.TOOL_CALL_ARGS) {
+      const argsEvent = event as ToolCallArgsEvent;
+      setStreamingParts(prev => prev.map(part =>
+        part.kind === 'tool_call' && part.toolCallId === argsEvent.toolCallId
+          ? { ...part, args: part.args + argsEvent.delta }
+          : part
+      ));
     } else if (event.type === EventType.TOOL_CALL_START) {
       const e = event as ToolCallStartEvent & Partial<ToolCallStartExtensions>;
 
@@ -230,7 +275,11 @@ export function useServerEvents({
         executingToolFallbackRef.current = fallbacks[Math.floor(Math.random() * fallbacks.length)];
       }
 
-      setExecutingTool({ toolCallId: e.toolCallId, title });
+      setExecutingTool({ toolCallId: e.toolCallId, name: e.toolCallName, title });
+      setStreamingParts(prev => [
+        ...prev,
+        { kind: 'tool_call', toolCallId: e.toolCallId, name: e.toolCallName, args: '' },
+      ]);
     } else if (event.type === EventType.TOOL_CALL_END) {
       const toolCallEnd = event as ToolCallEndEvent;
       const toolCallId = toolCallEnd.toolCallId;
@@ -268,6 +317,7 @@ export function useServerEvents({
       const contentEvent = event as TextMessageContentEvent;
       hasTextFromPriorStepRef.current = true;
       setStreamingText(prev => prev + contentEvent.delta);
+      appendToPart('text', contentEvent.delta);
     } else if (event.type === EventType.TEXT_MESSAGE_END) {
       // Don't clear streaming text here — wait for RUN_FINISHED so text
       // stays visible across multi-step runs (no flash between steps).
@@ -310,7 +360,9 @@ export function useServerEvents({
   }, [resetRunUiState]);
 
   // Compute display value for UI
-  const executingTool = executingToolRaw ? {
+  const executingTool: ExecutingToolDisplay | null = executingToolRaw ? {
+    toolCallId: executingToolRaw.toolCallId,
+    name: executingToolRaw.name,
     displayText: executingToolRaw.title ?? executingToolFallbackRef.current ?? strings.toolExecution.fallbackMessages[0],
   } : null;
 
@@ -323,6 +375,7 @@ export function useServerEvents({
     executingTool,
     streamingChatIdRef,
     streamingReasoning,
+    streamingParts,
     handleServerEvent,
     handleDisconnect,
   };
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index 6f7009ae..f56e564f 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -27,7 +27,34 @@ export { UseAIFloatingChatWrapper, CloseButton } from './components/UseAIFloatin
 export { UseAIFloatingButton } from './components/UseAIFloatingButton';
 export { UseAIChat } from './components/UseAIChat';
 export type { UseAIChatProps } from './components/UseAIChat';
+export type {
+  ChatSlotProps,
+  ChatHeaderSlotProps,
+  ChatEmptyStateSlotProps,
+  ChatMessageSlotProps,
+  ChatPendingIndicatorSlotProps,
+  ChatComposerSlotProps,
+  ChatToolApprovalSlotProps,
+  ChatDisclaimerSlotProps,
+  ChatToolApproval,
+  ChatSaveAsCommand,
+  ChatSlashCommands,
+  UseAIChatComponents,
+  UseAIChatComponentOverrides,
+} from './components/chatSlots';
+// The built-in implementations, so an override can reuse or wrap one instead of
+// rebuilding a region from scratch.
+export {
+  DefaultHeader,
+  DefaultEmptyState,
+  DefaultMessage,
+  DefaultPendingIndicator,
+  DefaultComposer,
+  DefaultToolApproval,
+  DefaultDisclaimer,
+} from './components/chatSlots';
 export type { SubmitMode } from './utils/keyboard';
+export type { MergedMessage } from './utils/mergeAssistantMessages';
 
 export type { UseAIOptions, UseAIResult } from './useAI';
 export type { UseAIWorkflowResult, TriggerWorkflowOptions, WorkflowProgress } from './useAIWorkflow';
@@ -148,6 +175,7 @@ export type {
   UseServerEventsOptions,
   UseServerEventsReturn,
   ExecutingToolDisplay,
+  ChatStreamingPart,
 } from './hooks/useServerEvents';
 
 // Message queue
diff --git a/packages/client/src/providers/useAIProvider.tsx b/packages/client/src/providers/useAIProvider.tsx
index 005922b8..45faf3c6 100644
--- a/packages/client/src/providers/useAIProvider.tsx
+++ b/packages/client/src/providers/useAIProvider.tsx
@@ -21,10 +21,14 @@ import { useToolSystem, type RegisterToolsOptions } from '../hooks/useToolSystem
 import type { SubmitMode } from '../utils/keyboard';
 import { usePromptState } from '../hooks/usePromptState';
 import { useFeedback } from '../hooks/useFeedback';
-import { useServerEvents } from '../hooks/useServerEvents';
+import { useServerEvents, type ChatStreamingPart } from '../hooks/useServerEvents';
 import { useMessageQueue, type SendMessageOptions } from '../hooks/useMessageQueue';
 import { ThemeContext, StringsContext, defaultTheme, defaultStrings } from '../theme';
 import type { UseAITheme, UseAIStrings } from '../theme';
+import type { UseAIChatComponentOverrides } from '../components/chatSlots';
+
+/** Stable identity so a hidden chat's streaming parts do not re-render consumers. */
+const EMPTY_STREAMING_PARTS: ChatStreamingPart[] = [];
 
 // ── Context Types ───────────────────────────────────────────────────────────
 
@@ -256,6 +260,8 @@ export interface UseAIProviderProps extends UseAIConfig {
   systemPrompt?: string;
   CustomButton?: React.ComponentType<FloatingButtonProps> | null;
   CustomChat?: React.ComponentType<ChatPanelProps> | null;
+  /** Default component overrides for every built-in chat rendered by this provider. */
+  chatComponents?: UseAIChatComponentOverrides;
   /**
    * Custom chat repository for message persistence.
    * Defaults to LocalStorageChatRepository if not provided.
@@ -464,6 +470,7 @@ export function UseAIProvider({
   systemPrompt,
   CustomButton,
   CustomChat,
+  chatComponents,
   chatRepository,
   forwardedPropsProvider,
   fileUploadConfig: fileUploadConfigProp,
@@ -771,6 +778,8 @@ export function UseAIProvider({
     ? serverEvents.streamingReasoning : '';
   const effectiveStreamingMessageId = serverEvents.streamingChatIdRef.current === chatManagement.displayedChatId
     ? serverEvents.streamingMessageId : null;
+  const effectiveStreamingParts = serverEvents.streamingChatIdRef.current === chatManagement.displayedChatId
+    ? serverEvents.streamingParts : EMPTY_STREAMING_PARTS;
 
   const chatUIContextValue: ChatUIContextValue = {
     connected,
@@ -781,6 +790,7 @@ export function UseAIProvider({
     streamingText: effectiveStreamingText,
     streamingReasoning: effectiveStreamingReasoning,
     streamingMessageId: effectiveStreamingMessageId,
+    streamingParts: effectiveStreamingParts,
     suggestions: promptState.aggregatedSuggestions,
     fileUploadConfig,
     fileProcessing: fileProcessingState,
@@ -822,6 +832,7 @@ export function UseAIProvider({
       submit: feedback.submitFeedback,
     },
     submitMode,
+    components: chatComponents,
   };
 
   const isUIDisabled = CustomButton === null || CustomChat === null;
@@ -837,6 +848,7 @@ export function UseAIProvider({
     streamingText: effectiveStreamingText,
     streamingReasoning: effectiveStreamingReasoning,
     streamingMessageId: effectiveStreamingMessageId,
+    streamingParts: effectiveStreamingParts,
     currentChatId: chatManagement.displayedChatId,
     onNewChat: chatManagement.createNewChat,
     onLoadChat: chatManagement.loadChat,
@@ -861,6 +873,7 @@ export function UseAIProvider({
     onApproveToolCall: toolSystem.pendingApprovals.length > 0 ? toolSystem.approveAll : undefined,
     onRejectToolCall: toolSystem.pendingApprovals.length > 0 ? toolSystem.rejectAll : undefined,
     submitMode,
+    components: chatComponents,
   };
 
   const renderDefaultChat = () => {
diff --git a/packages/client/src/utils/mergeAssistantMessages.test.ts b/packages/client/src/utils/mergeAssistantMessages.test.ts
index 29f6f2d4..59fd41ac 100644
--- a/packages/client/src/utils/mergeAssistantMessages.test.ts
+++ b/packages/client/src/utils/mergeAssistantMessages.test.ts
@@ -183,6 +183,51 @@ describe('mergeAssistantMessagesForDisplay', () => {
     expect(result[2].displayMode).toBe('info');
   });
 
+  it('keeps the whole turn in sourceMessages, in the order it was produced', () => {
+    const result = mergeAssistantMessagesForDisplay([
+      msg({ id: '1', role: 'user', content: 'Find the docs' }),
+      msg({ id: '2', role: 'assistant', content: 'Searching.', toolCalls: [tc('tc1', 'search')] }),
+      msg({ id: '3', role: 'tool', content: '{"sources":[]}', toolCallId: 'tc1' }),
+      msg({ id: '4', role: 'assistant', content: 'Here it is.' }),
+    ]);
+
+    expect(result.map((m) => m.sourceMessages.map((source) => source.id))).toEqual([
+      ['1'],
+      ['2', '3', '4'],
+    ]);
+    // The tool call and its result survive here even though merging drops both.
+    const turn = result[1].sourceMessages;
+    expect(turn[0].toolCalls?.[0].id).toBe('tc1');
+    expect(turn[1].content).toBe('{"sources":[]}');
+  });
+
+  it('does not carry one turn\'s sources into the next', () => {
+    const result = mergeAssistantMessagesForDisplay([
+      msg({ id: '1', role: 'user', content: 'First' }),
+      msg({ id: '2', role: 'assistant', content: 'One.' }),
+      msg({ id: '3', role: 'user', content: 'Second' }),
+      msg({ id: '4', role: 'assistant', content: 'Two.' }),
+    ]);
+
+    expect(result[3].sourceMessages.map((source) => source.id)).toEqual(['4']);
+  });
+
+  it('does not carry sources out of a turn that only made a silent tool call', () => {
+    // Aborting while a tool runs stores a turn with no assistant text and no
+    // reasoning, so nothing is flushed at the turn boundary.
+    const result = mergeAssistantMessagesForDisplay([
+      msg({ id: '1', role: 'user', content: 'First' }),
+      msg({ id: '2', role: 'assistant', content: '', toolCalls: [tc('tc1', 'search')] }),
+      msg({ id: '3', role: 'tool', content: '{}', toolCallId: 'tc1' }),
+      msg({ id: '4', role: 'assistant', content: 'Generation stopped.', displayMode: 'info' }),
+      msg({ id: '5', role: 'user', content: 'Second' }),
+      msg({ id: '6', role: 'assistant', content: 'Two.' }),
+    ]);
+
+    const answer = result[result.length - 1];
+    expect(answer.sourceMessages.map((source) => source.id)).toEqual(['6']);
+  });
+
   it('keeps an info notice standalone after a plain text reply', () => {
     const result = mergeAssistantMessagesForDisplay([
       msg({ id: '1', role: 'user', content: 'Hi' }),
diff --git a/packages/client/src/utils/mergeAssistantMessages.ts b/packages/client/src/utils/mergeAssistantMessages.ts
index e218a07f..37ee181e 100644
--- a/packages/client/src/utils/mergeAssistantMessages.ts
+++ b/packages/client/src/utils/mergeAssistantMessages.ts
@@ -2,6 +2,14 @@ import type { PersistedMessage, PersistedMessageContent } from '../providers/cha
 import type { ReasoningPart } from '../types';
 import { getTextFromContent } from './messageContent';
 
+/**
+ * A display message plus the raw messages it was built from, in the order they
+ * were produced. Merging is lossy on purpose (see below), so `sourceMessages`
+ * keeps the per-step tool calls, tool results and reasoning available to
+ * anything that wants to render the turn as a timeline rather than one bubble.
+ */
+export type MergedMessage = PersistedMessage & { sourceMessages: PersistedMessage[] };
+
 /**
  * Merges consecutive assistant messages within each turn into a single
  * display message, combining their text with paragraph separators.
@@ -9,7 +17,8 @@ import { getTextFromContent } from './messageContent';
  * This preserves the per-step data structure (needed for correct LLM context)
  * while presenting a unified view to the user.
  *
- * - Tool messages are filtered out (not shown in UI)
+ * - Tool messages are filtered out of the merged content, but stay in the
+ *   turn's `sourceMessages`
  * - Intermediate assistant messages (with toolCalls) have their text merged
  *   into the final text-only assistant message of the same turn
  * - Reasoning parts from all steps are collected into the merged message
@@ -18,11 +27,19 @@ import { getTextFromContent } from './messageContent';
  *   are never merged into assistant turn content, and they flush any pending
  *   text into its own message first so it doesn't fold into the notice.
  */
-export function mergeAssistantMessagesForDisplay(messages: PersistedMessage[]): PersistedMessage[] {
-  const result: PersistedMessage[] = [];
+export function mergeAssistantMessagesForDisplay(messages: PersistedMessage[]): MergedMessage[] {
+  const result: MergedMessage[] = [];
   let pendingTexts: string[] = [];
   let pendingIds: string[] = [];
   let pendingReasoningParts: ReasoningPart[] = [];
+  let pendingSources: PersistedMessage[] = [];
+
+  const resetPending = () => {
+    pendingTexts = [];
+    pendingIds = [];
+    pendingReasoningParts = [];
+    pendingSources = [];
+  };
 
   const flushPending = () => {
     if (pendingTexts.length > 0 || pendingReasoningParts.length > 0) {
@@ -31,16 +48,21 @@ export function mergeAssistantMessagesForDisplay(messages: PersistedMessage[]):
         role: 'assistant',
         content: pendingTexts.join('\n\n'),
         createdAt: new Date(),
+        sourceMessages: pendingSources,
         ...(pendingReasoningParts.length > 0 ? { reasoningParts: pendingReasoningParts } : {}),
       });
-      pendingTexts = [];
-      pendingIds = [];
-      pendingReasoningParts = [];
     }
+    // Reset unconditionally: a turn whose assistant messages only carried tool
+    // calls fills `pendingSources` while leaving text and reasoning empty, and
+    // those sources must not be handed to the next turn's merged message.
+    resetPending();
   };
 
   for (const msg of messages) {
     if (msg.role === 'tool') {
+      // Not rendered by the built-in bubble, but kept as a source so a custom
+      // Message slot can read the result a tool call produced.
+      pendingSources.push(msg);
       continue;
     }
 
@@ -48,7 +70,7 @@ export function mergeAssistantMessagesForDisplay(messages: PersistedMessage[]):
       // System notice — flush the in-progress assistant text as its own
       // message, then keep the notice standalone (no merge, no displayMode leak).
       flushPending();
-      result.push(msg);
+      result.push({ ...msg, sourceMessages: [msg] });
       continue;
     }
 
@@ -58,6 +80,7 @@ export function mergeAssistantMessagesForDisplay(messages: PersistedMessage[]):
       if (msg.toolCalls && msg.toolCalls.length > 0) {
         // Intermediate assistant with tool calls — accumulate text and reasoning, skip message
         pendingIds.push(msg.id);
+        pendingSources.push(msg);
         if (text) {
           pendingTexts.push(text);
         }
@@ -76,16 +99,15 @@ export function mergeAssistantMessagesForDisplay(messages: PersistedMessage[]):
         result.push({
           ...msg,
           content: combined || '',
+          sourceMessages: [...pendingSources, msg],
           ...(allReasoningParts && allReasoningParts.length > 0 ? { reasoningParts: allReasoningParts } : {}),
         });
-        pendingTexts = [];
-        pendingIds = [];
-        pendingReasoningParts = [];
+        resetPending();
       }
     } else {
       // User message — flush any pending text and reset for next turn
       flushPending();
-      result.push(msg);
+      result.push({ ...msg, sourceMessages: [msg] });
     }
   }
 

From 8bb76cb30006aca92945764de5ba782017ae2c14 Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:21:37 +0900
Subject: [PATCH 02/12] feat(client): flatten a run's parts into what one
 bubble shows

A turn's persisted messages are merged into a single bubble at render time by
mergeAssistantMessagesForDisplay. The in-flight answer has no equivalent, so
`getTextFromStreamingParts` and `getReasoningPartsFromStreamingParts` do the
same reduction over the run's ordered parts.

Both join with a blank line and skip empty steps because the merge does: the
provisional bubble and the persisted one render into the same element, and a
different string remounts it, dropping the user's text selection. A test pins
the two flattenings against each other for the same run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/client/src/index.ts                  |  4 ++
 .../client/src/utils/streamingParts.test.ts   | 68 +++++++++++++++++++
 packages/client/src/utils/streamingParts.ts   | 27 ++++++++
 3 files changed, 99 insertions(+)
 create mode 100644 packages/client/src/utils/streamingParts.test.ts
 create mode 100644 packages/client/src/utils/streamingParts.ts

diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index f56e564f..6caed550 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -55,6 +55,10 @@ export {
 } from './components/chatSlots';
 export type { SubmitMode } from './utils/keyboard';
 export type { MergedMessage } from './utils/mergeAssistantMessages';
+export {
+  getTextFromStreamingParts,
+  getReasoningPartsFromStreamingParts,
+} from './utils/streamingParts';
 
 export type { UseAIOptions, UseAIResult } from './useAI';
 export type { UseAIWorkflowResult, TriggerWorkflowOptions, WorkflowProgress } from './useAIWorkflow';
diff --git a/packages/client/src/utils/streamingParts.test.ts b/packages/client/src/utils/streamingParts.test.ts
new file mode 100644
index 00000000..0c911a07
--- /dev/null
+++ b/packages/client/src/utils/streamingParts.test.ts
@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'bun:test';
+import { getReasoningPartsFromStreamingParts, getTextFromStreamingParts } from './streamingParts';
+import { mergeAssistantMessagesForDisplay } from './mergeAssistantMessages';
+import type { PersistedMessage } from '../providers/chatRepository/types';
+import type { ChatStreamingPart } from '../hooks/useServerEvents';
+
+/** A run that thinks, calls a tool, thinks again and answers in two steps. */
+const PARTS: ChatStreamingPart[] = [
+  { kind: 'reasoning', text: 'Need the time.' },
+  { kind: 'tool_call', toolCallId: 'tc1', name: 'getServerTime', args: '{}' },
+  { kind: 'text', text: 'Checking the clock.' },
+  { kind: 'reasoning', text: 'Now the sum.' },
+  { kind: 'text', text: 'It is noon.' },
+];
+
+describe('getTextFromStreamingParts', () => {
+  it('joins the text steps with a blank line and ignores the rest', () => {
+    expect(getTextFromStreamingParts(PARTS)).toBe('Checking the clock.\n\nIt is noon.');
+  });
+
+  // A part is pushed on TEXT_MESSAGE_START, before any delta arrives, so an
+  // empty one exists for a render. Joining it would prepend a blank line.
+  it('skips a step that has not received any text yet', () => {
+    expect(getTextFromStreamingParts([{ kind: 'text', text: '' }, { kind: 'text', text: 'A' }])).toBe('A');
+  });
+
+  it('is empty for a run that has only thought so far', () => {
+    expect(getTextFromStreamingParts([{ kind: 'reasoning', text: 'Hmm.' }])).toBe('');
+  });
+
+  /**
+   * The provisional bubble and the persisted one render one after the other
+   * into the same element. A different string remounts it, dropping the text
+   * selection the user was making, so the two flattenings must agree.
+   */
+  it('produces the string mergeAssistantMessagesForDisplay produces for the same run', () => {
+    const persisted: PersistedMessage[] = [
+      { id: 'u1', role: 'user', content: 'what time is it?', createdAt: new Date(0) },
+      {
+        id: 'a1',
+        role: 'assistant',
+        content: 'Checking the clock.',
+        createdAt: new Date(0),
+        toolCalls: [{ id: 'tc1', type: 'function' as const, function: { name: 'getServerTime', arguments: '{}' } }],
+      },
+      { id: 't1', role: 'tool', content: 'noon', createdAt: new Date(0) },
+      { id: 'a2', role: 'assistant', content: 'It is noon.', createdAt: new Date(0) },
+    ];
+
+    const merged = mergeAssistantMessagesForDisplay(persisted);
+    const assistant = merged.find((message) => message.role === 'assistant');
+
+    expect(assistant?.content).toBe(getTextFromStreamingParts(PARTS));
+  });
+});
+
+describe('getReasoningPartsFromStreamingParts', () => {
+  it('keeps each step of reasoning as its own part', () => {
+    expect(getReasoningPartsFromStreamingParts(PARTS)).toEqual([
+      { text: 'Need the time.' },
+      { text: 'Now the sum.' },
+    ]);
+  });
+
+  it('skips a step that has not received any reasoning yet', () => {
+    expect(getReasoningPartsFromStreamingParts([{ kind: 'reasoning', text: '' }])).toEqual([]);
+  });
+});
diff --git a/packages/client/src/utils/streamingParts.ts b/packages/client/src/utils/streamingParts.ts
new file mode 100644
index 00000000..0d2ffca7
--- /dev/null
+++ b/packages/client/src/utils/streamingParts.ts
@@ -0,0 +1,27 @@
+import type { ChatStreamingPart } from '../hooks/useServerEvents';
+import type { ReasoningPart } from '../types';
+
+/**
+ * Flattening the ordered parts of an in-flight run into what one bubble shows.
+ * This is display-only: the run itself is kept as parts, and persisted as the
+ * per-step messages `mergeAssistantMessagesForDisplay` merges.
+ *
+ * Both helpers join with a blank line and skip empty steps because that is what
+ * the merge does (`pendingTexts` only collects steps that produced text, joined
+ * with '\n\n'). A bubble built from parts and the same bubble built from the
+ * persisted message must produce an identical string: the two render one after
+ * the other into the same element, and a difference remounts it, dropping any
+ * selection the user was making.
+ */
+export function getTextFromStreamingParts(parts: ChatStreamingPart[]): string {
+  return parts
+    .flatMap((part) => (part.kind === 'text' && part.text ? [part.text] : []))
+    .join('\n\n');
+}
+
+/** The reasoning so far, in the shape a persisted turn carries it. */
+export function getReasoningPartsFromStreamingParts(parts: ChatStreamingPart[]): ReasoningPart[] {
+  return parts.flatMap((part) =>
+    part.kind === 'reasoning' && part.text ? [{ text: part.text }] : [],
+  );
+}

From dd795d00d6338d409c2b22edba27cab0de6ae30b Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:21:56 +0900
Subject: [PATCH 03/12] refactor(client): pass the streamed answer as parts
 only

`streamingText` and `streamingReasoning` were kept as state next to
`streamingParts`, and their `\n\n` insertion existed only to reproduce what
mergeAssistantMessagesForDisplay produces for the persisted turn. So the same
join lived in three places, and they already disagreed: a REASONING_MESSAGE_START
that received no delta left an empty part, which the parts-based join turned into
a leading blank line and the string-based one did not.

The run is now kept as parts alone and flattened where it is displayed.
useServerEvents drops both strings and the separator bookkeeping,
`clearStreamingText` becomes `clearStreamingParts`, and DefaultMessage derives
the bubble's text and reasoning from the parts. The provisional message's
`content` is empty as a result: the slot decides how to render the answer, so
the panel no longer pre-flattens it.

Removes `streamingText` / `streamingReasoning` from the useServerEvents return
value, from UseAIChatPanelProps, and from the props handed to CustomChat, which
now receives `streamingParts` instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../client/src/components/UseAIChat.test.tsx  | 11 +++--
 packages/client/src/components/UseAIChat.tsx  |  6 ---
 .../UseAIChatPanel.selection.test.tsx         | 37 ++++++++++++----
 .../client/src/components/UseAIChatPanel.tsx  | 20 ++++-----
 .../src/components/UseAIChatSlots.test.tsx    | 20 ++++-----
 .../components/chatSlots/DefaultMessage.tsx   | 19 +++++---
 .../client/src/components/chatSlots/types.ts  | 23 +++++-----
 .../src/hooks/useServerEvents.abort.test.tsx  |  2 +-
 .../useServerEvents.streamingParts.test.tsx   |  8 ++--
 packages/client/src/hooks/useServerEvents.ts  | 43 ++++---------------
 .../client/src/providers/useAIProvider.tsx    | 19 ++------
 11 files changed, 90 insertions(+), 118 deletions(-)

diff --git a/packages/client/src/components/UseAIChat.test.tsx b/packages/client/src/components/UseAIChat.test.tsx
index d647cf31..291bf41c 100644
--- a/packages/client/src/components/UseAIChat.test.tsx
+++ b/packages/client/src/components/UseAIChat.test.tsx
@@ -11,8 +11,7 @@ function createContextValue(overrides: Partial<ChatUIContextValue> = {}): ChatUI
     loading: false,
     sendMessage: mock(async () => {}),
     messages: [],
-    streamingText: '',
-    streamingReasoning: '',
+    streamingParts: [],
     streamingMessageId: null,
     suggestions: [],
     fileUploadConfig: undefined,
@@ -73,10 +72,10 @@ describe('UseAIChat', () => {
     expect(queryByTestId('provider-header')).toBeNull();
   });
 
-  test('passes streaming reasoning through to UseAIChatPanel', () => {
+  test('passes the streaming parts through to UseAIChatPanel', () => {
     const ctx = createContextValue({
       loading: true,
-      streamingReasoning: 'First thought...',
+      streamingParts: [{ kind: 'reasoning', text: 'First thought...' }],
     });
 
     const { getByTestId, getByText } = render(
@@ -95,7 +94,7 @@ describe('UseAIChat', () => {
   test('renders the streaming answer under the id it will be persisted with', () => {
     const ctx = createContextValue({
       loading: true,
-      streamingText: 'partial answer',
+      streamingParts: [{ kind: 'text', text: 'partial answer' }],
       streamingMessageId: 'msg-assistant',
     });
 
@@ -116,7 +115,7 @@ describe('UseAIChat', () => {
     };
     rerender(
       <__UseAIChatContext.Provider
-        value={createContextValue({ messages: [persisted], streamingText: '', streamingMessageId: null })}
+        value={createContextValue({ messages: [persisted], streamingParts: [], streamingMessageId: null })}
       >
         <UseAIChat />
       </__UseAIChatContext.Provider>
diff --git a/packages/client/src/components/UseAIChat.tsx b/packages/client/src/components/UseAIChat.tsx
index c587cd42..ab805b81 100644
--- a/packages/client/src/components/UseAIChat.tsx
+++ b/packages/client/src/components/UseAIChat.tsx
@@ -28,10 +28,6 @@ export interface ChatUIContextValue {
   abortRun: () => void;
   /** Current messages in the conversation */
   messages: PersistedMessage[];
-  /** Currently streaming text from assistant (real-time updates) */
-  streamingText: string;
-  /** Currently streaming reasoning text from extended thinking */
-  streamingReasoning: string;
   /**
    * Id the streaming answer will be persisted under, or null when no run is
    * streaming into the displayed chat. Passing it to the panel lets the
@@ -221,8 +217,6 @@ export function UseAIChat({ floating = false, submitMode, components }: UseAICha
     messages: ctx.messages,
     loading: ctx.loading,
     connected: ctx.connected,
-    streamingText: ctx.streamingText,
-    streamingReasoning: ctx.streamingReasoning,
     streamingMessageId: ctx.streamingMessageId,
     streamingParts: ctx.streamingParts,
     currentChatId: ctx.history.currentId,
diff --git a/packages/client/src/components/UseAIChatPanel.selection.test.tsx b/packages/client/src/components/UseAIChatPanel.selection.test.tsx
index 6028b4fa..0aa9cbe5 100644
--- a/packages/client/src/components/UseAIChatPanel.selection.test.tsx
+++ b/packages/client/src/components/UseAIChatPanel.selection.test.tsx
@@ -2,11 +2,22 @@ import React from 'react';
 import { describe, test, expect, beforeEach } from 'bun:test';
 import { render } from '@testing-library/react';
 import { UseAIChatPanel, type UseAIChatPanelProps } from './UseAIChatPanel';
+import type { ChatStreamingPart } from '../hooks/useServerEvents';
 import type { PersistedMessage } from '../providers/chatRepository/types';
 
 const ANSWER = 'The first paragraph.\n\nThe second paragraph.';
 const STREAMING_ID = 'msg-assistant';
 
+/**
+ * The panel is only handed the run's ordered parts; the bubble flattens them.
+ * A two-paragraph answer arrives as two text parts, the same shape a two-step
+ * run produces, so the flattened string must match the persisted `ANSWER`.
+ */
+const ANSWER_PARTS: ChatStreamingPart[] = [
+  { kind: 'text', text: 'The first paragraph.' },
+  { kind: 'text', text: 'The second paragraph.' },
+];
+
 const userMessage: PersistedMessage = {
   id: 'msg-user',
   role: 'user',
@@ -41,7 +52,7 @@ function panelProps(overrides: Partial<UseAIChatPanelProps> = {}): UseAIChatPane
     messages: [userMessage],
     loading: true,
     connected: true,
-    streamingText: ANSWER,
+    streamingParts: ANSWER_PARTS,
     streamingMessageId: STREAMING_ID,
     ...overrides,
   };
@@ -88,10 +99,16 @@ describe('streaming answer rendered as a provisional message', () => {
   });
 
   test('keeps the selection as more text arrives', () => {
-    const { container, rerender } = render(<UseAIChatPanel {...panelProps({ streamingText: ANSWER })} />);
+    const { container, rerender } = render(<UseAIChatPanel {...panelProps()} />);
     selectText(container, 'first paragraph');
 
-    rerender(<UseAIChatPanel {...panelProps({ streamingText: `${ANSWER}\n\nThe third paragraph.` })} />);
+    rerender(
+      <UseAIChatPanel
+        {...panelProps({
+          streamingParts: [...ANSWER_PARTS, { kind: 'text', text: 'The third paragraph.' }],
+        })}
+      />
+    );
 
     expect(window.getSelection()!.toString()).toBe('first paragraph');
   });
@@ -102,7 +119,7 @@ describe('streaming answer rendered as a provisional message', () => {
 
     rerender(
       <UseAIChatPanel
-        {...panelProps({ loading: false, streamingText: '', streamingMessageId: null, messages: [userMessage, assistantMessage] })}
+        {...panelProps({ loading: false, streamingParts: [], streamingMessageId: null, messages: [userMessage, assistantMessage] })}
       />
     );
 
@@ -124,7 +141,7 @@ describe('streaming answer rendered as a provisional message', () => {
 
     rerender(
       <UseAIChatPanel
-        {...panelProps({ loading: false, streamingText: '', streamingMessageId: null, messages: [userMessage, assistantMessage] })}
+        {...panelProps({ loading: false, streamingParts: [], streamingMessageId: null, messages: [userMessage, assistantMessage] })}
       />
     );
 
@@ -140,7 +157,7 @@ describe('streaming answer rendered as a provisional message', () => {
 
     rerender(
       <UseAIChatPanel
-        {...panelProps({ loading: false, streamingText: '', streamingMessageId: null, messages: [userMessage, assistantMessage] })}
+        {...panelProps({ loading: false, streamingParts: [], streamingMessageId: null, messages: [userMessage, assistantMessage] })}
       />
     );
 
@@ -157,7 +174,7 @@ describe('streaming answer rendered as a provisional message', () => {
       <UseAIChatPanel
         {...panelProps({
           loading: false,
-          streamingText: '',
+          streamingParts: [],
           streamingMessageId: null,
           messages: [userMessage, assistantMessage, abortNotice],
         })}
@@ -180,14 +197,16 @@ describe('streaming answer rendered as a provisional message', () => {
   });
 
   test('shows the plain loading indicator before any text streams', () => {
-    const { container } = render(<UseAIChatPanel {...panelProps({ streamingText: '', streamingReasoning: '' })} />);
+    const { container } = render(<UseAIChatPanel {...panelProps({ streamingParts: [] })} />);
     expect(assistantBubbles(container)).toHaveLength(0);
     expect(container.querySelector('.dots')).not.toBeNull();
   });
 
   test('shows the loading indicator inside the bubble while only reasoning streams', () => {
     const { container } = render(
-      <UseAIChatPanel {...panelProps({ streamingText: '', streamingReasoning: 'thinking...' })} />
+      <UseAIChatPanel
+        {...panelProps({ streamingParts: [{ kind: 'reasoning', text: 'thinking...' }] })}
+      />
     );
     const bubbles = assistantBubbles(container);
     expect(bubbles).toHaveLength(1);
diff --git a/packages/client/src/components/UseAIChatPanel.tsx b/packages/client/src/components/UseAIChatPanel.tsx
index 98871868..fc6b3394 100644
--- a/packages/client/src/components/UseAIChatPanel.tsx
+++ b/packages/client/src/components/UseAIChatPanel.tsx
@@ -65,13 +65,10 @@ export interface UseAIChatPanelProps {
   messages: Message[];
   loading: boolean;
   connected: boolean;
-  /** Currently streaming text from assistant (real-time updates) */
-  streamingText?: string;
-  /** Currently streaming reasoning text from extended thinking */
-  streamingReasoning?: string;
   /**
-   * The in-flight answer split into ordered parts. Handed to the `Message`
-   * slot; the built-in bubble renders `streamingText`/`streamingReasoning`.
+   * The in-flight answer split into ordered parts, and the only form the
+   * streamed answer is passed in. Flattening it into what one bubble shows is
+   * the `Message` slot's job.
    */
   streamingParts?: ChatStreamingPart[];
   /**
@@ -151,8 +148,6 @@ export function UseAIChatPanel({
   messages,
   loading,
   connected,
-  streamingText = '',
-  streamingReasoning = '',
   streamingParts = EMPTY_STREAMING_PARTS,
   streamingMessageId = null,
   currentChatId,
@@ -203,14 +198,16 @@ export function UseAIChatPanel({
   // the same key, so React updates the existing bubble instead of replacing it,
   // and a text selection inside it survives. saveAIResponse appends the
   // persisted message one render before the streaming state clears, so the
-  // provisional entry is skipped once a message with that id exists.
+  // provisional entry is skipped once a message with that id exists. `content`
+  // stays empty: the answer is passed as `streamingParts`, and the slot decides
+  // how to render it.
   const provisionalMessage: DisplayMessage | null =
-    (streamingText || streamingReasoning) &&
+    streamingParts.length > 0 &&
     !(streamingMessageId && displayMessages.some((m) => m.id === streamingMessageId))
       ? {
           id: streamingMessageId ?? PROVISIONAL_MESSAGE_ID,
           role: 'assistant',
-          content: streamingText,
+          content: '',
           createdAt: PROVISIONAL_CREATED_AT,
           sourceMessages: [],
           streaming: true,
@@ -393,7 +390,6 @@ export function UseAIChatPanel({
               isLast: index === renderedMessages.length - 1,
               sourceMessages: message.sourceMessages,
               streaming: !!message.streaming,
-              streamingReasoning: message.streaming ? streamingReasoning : '',
               streamingParts: message.streaming ? streamingParts : EMPTY_STREAMING_PARTS,
               feedbackEnabled: !!feedbackEnabled,
               onFeedback,
diff --git a/packages/client/src/components/UseAIChatSlots.test.tsx b/packages/client/src/components/UseAIChatSlots.test.tsx
index 0ab5aa4a..ea910d6f 100644
--- a/packages/client/src/components/UseAIChatSlots.test.tsx
+++ b/packages/client/src/components/UseAIChatSlots.test.tsx
@@ -13,6 +13,7 @@ import type {
   UseAIChatComponentOverrides,
 } from './chatSlots';
 import type { PersistedMessage } from '../providers/chatRepository/types';
+import { getTextFromStreamingParts } from '../utils/streamingParts';
 
 const message: PersistedMessage = {
   id: 'message-1',
@@ -31,7 +32,7 @@ function renderPanel(
       messages={[message]}
       loading
       connected
-      streamingText="Streaming"
+      streamingParts={[{ kind: 'text', text: 'Streaming' }]}
       pendingApprovals={[{
         toolCallId: 'tool-1',
         toolCallName: 'fillForm',
@@ -61,9 +62,9 @@ describe('UseAIChat component slots', () => {
     const Header = ({ currentChatId }: ChatHeaderSlotProps) => (
       <div data-testid="custom-header">{currentChatId}</div>
     );
-    const Message = ({ message: slotMessage, streaming }: ChatMessageSlotProps) => (
+    const Message = ({ message: slotMessage, streaming, streamingParts }: ChatMessageSlotProps) => (
       <div data-testid="custom-message" data-streaming={String(streaming)}>
-        {slotMessage.content as string}
+        {streaming ? getTextFromStreamingParts(streamingParts) : (slotMessage.content as string)}
       </div>
     );
     const ToolApproval = ({ approvals, onApprove, onReject }: ChatToolApprovalSlotProps) => (
@@ -111,15 +112,14 @@ describe('UseAIChat component slots', () => {
   });
 
   test('routes the streaming answer through the Message slot', () => {
-    const Message = ({ message: slotMessage, streaming, streamingReasoning, streamingParts, isLast }: ChatMessageSlotProps) => (
+    const Message = ({ message: slotMessage, streaming, streamingParts, isLast }: ChatMessageSlotProps) => (
       <div
         data-testid={`slot-${slotMessage.id}`}
         data-streaming={String(streaming)}
-        data-reasoning={streamingReasoning}
         data-parts={streamingParts.map((part) => part.kind).join(',')}
         data-last={String(isLast)}
       >
-        {slotMessage.content as string}
+        {streaming ? getTextFromStreamingParts(streamingParts) : (slotMessage.content as string)}
       </div>
     );
 
@@ -127,17 +127,16 @@ describe('UseAIChat component slots', () => {
       { Message },
       {
         streamingMessageId: 'message-2',
-        streamingReasoning: 'Weighing options',
         streamingParts: [
           { kind: 'reasoning', text: 'Weighing options' },
           { kind: 'tool_call', toolCallId: 'tc1', name: 'search', args: '{}' },
+          { kind: 'text', text: 'Streaming' },
         ],
       }
     );
 
     const persisted = getByTestId('slot-message-1');
     expect(persisted).toHaveAttribute('data-streaming', 'false');
-    expect(persisted).toHaveAttribute('data-reasoning', '');
     expect(persisted).toHaveAttribute('data-parts', '');
     expect(persisted).toHaveAttribute('data-last', 'false');
 
@@ -146,9 +145,8 @@ describe('UseAIChat component slots', () => {
     const streamingBubble = getByTestId('slot-message-2');
     expect(streamingBubble).toHaveTextContent('Streaming');
     expect(streamingBubble).toHaveAttribute('data-streaming', 'true');
-    expect(streamingBubble).toHaveAttribute('data-reasoning', 'Weighing options');
     // The ordered parts let a slot keep the run's steps apart while it streams.
-    expect(streamingBubble).toHaveAttribute('data-parts', 'reasoning,tool_call');
+    expect(streamingBubble).toHaveAttribute('data-parts', 'reasoning,tool_call,text');
     expect(streamingBubble).toHaveAttribute('data-last', 'true');
   });
 
@@ -160,7 +158,7 @@ describe('UseAIChat component slots', () => {
   test('renders PendingIndicator before the answer starts arriving', () => {
     const { getByTestId } = renderPanel(
       { PendingIndicator },
-      { streamingText: '', executingTool }
+      { streamingParts: [], executingTool }
     );
 
     expect(getByTestId('custom-pending')).toHaveTextContent('Filling the form');
diff --git a/packages/client/src/components/chatSlots/DefaultMessage.tsx b/packages/client/src/components/chatSlots/DefaultMessage.tsx
index d817e647..a9cd13cd 100644
--- a/packages/client/src/components/chatSlots/DefaultMessage.tsx
+++ b/packages/client/src/components/chatSlots/DefaultMessage.tsx
@@ -1,6 +1,10 @@
 import React, { useState } from 'react';
 import { useStrings, useTheme } from '../../theme';
 import { getDisplayTextFromContent, getTextFromContent } from '../../utils/messageContent';
+import {
+  getReasoningPartsFromStreamingParts,
+  getTextFromStreamingParts,
+} from '../../utils/streamingParts';
 import { MarkdownContent } from '../MarkdownContent';
 import { FilePlaceholder } from '../FileChip';
 import { Reasoning } from '../Reasoning';
@@ -13,7 +17,7 @@ import type { ChatMessageSlotProps } from './types';
 export function DefaultMessage({
   message,
   streaming,
-  streamingReasoning,
+  streamingParts,
   feedbackEnabled,
   onFeedback,
   saveAsCommand,
@@ -59,7 +63,11 @@ export function DefaultMessage({
   // untouched.
   const messageTestId = streaming ? 'chat-message-assistant-streaming' : `chat-message-${message.role}`;
   const contentTestId = streaming ? 'chat-message-content-streaming' : 'chat-message-content';
-  const text = getTextFromContent(message.content);
+  // One bubble per turn, so the run's ordered parts are flattened the same way
+  // mergeAssistantMessagesForDisplay flattens the persisted turn. Both sides
+  // must yield the same string for the handoff to leave the element alone.
+  const text = streaming ? getTextFromStreamingParts(streamingParts) : getTextFromContent(message.content);
+  const streamingReasoningParts = streaming ? getReasoningPartsFromStreamingParts(streamingParts) : [];
 
   return (
     <div
@@ -156,11 +164,10 @@ export function DefaultMessage({
       )}
       {message.role === 'assistant' ? (
         <>
-          {streaming && streamingReasoning && (
+          {streaming && streamingReasoningParts.length > 0 && (
             <Reasoning
-              reasoningParts={[]}
+              reasoningParts={streamingReasoningParts}
               isStreaming={true}
-              streamingText={streamingReasoning}
               theme={theme}
               strings={strings}
             />
@@ -175,7 +182,7 @@ export function DefaultMessage({
           {streaming && !text ? (
             <span className="dots" style={{ opacity: 0.6 }}>...</span>
           ) : (
-            <MarkdownContent content={getTextFromContent(message.content)} />
+            <MarkdownContent content={text} />
           )}
         </>
       ) : (
diff --git a/packages/client/src/components/chatSlots/types.ts b/packages/client/src/components/chatSlots/types.ts
index eef8be1b..a8ea8cc3 100644
--- a/packages/client/src/components/chatSlots/types.ts
+++ b/packages/client/src/components/chatSlots/types.ts
@@ -44,10 +44,10 @@ export interface ChatEmptyStateSlotProps extends ChatSlotProps {
 export interface ChatMessageSlotProps extends ChatSlotProps {
   /**
    * While `streaming` is true this is the provisional entry for the answer that
-   * is still arriving: `content` holds the text received so far, and `createdAt`,
-   * `traceId`, `feedback` and `reasoningParts` are not populated yet. It carries
-   * the id the answer will be persisted under, so the same slot instance keeps
-   * rendering it once the run finishes.
+   * is still arriving: `content` is empty and `createdAt`, `traceId`, `feedback`
+   * and `reasoningParts` are not populated yet, so read the answer from
+   * `streamingParts`. It carries the id the answer will be persisted under, so
+   * the same slot instance keeps rendering it once the run finishes.
    *
    * The slot itself keeps its React key across that handoff, but the keys it
    * gives its own children must match on both sides too. Deriving them from
@@ -70,19 +70,16 @@ export interface ChatMessageSlotProps extends ChatSlotProps {
   sourceMessages: PersistedMessage[];
   /** Whether this message is the answer currently being streamed. */
   streaming: boolean;
-  /**
-   * Extended-thinking text received so far, with every step's reasoning joined
-   * into one string. Prefer `streamingParts` when the steps should stay apart.
-   * Only populated while `streaming` is true; once persisted the reasoning is
-   * on `message.reasoningParts`.
-   */
-  streamingReasoning: string;
   /**
    * The answer so far, split into the parts the model emitted and kept in
    * order: reasoning, text and tool calls as they happened. This is the
    * streaming counterpart of `sourceMessages`, so a slot can render a run the
-   * same way while it happens and after it is persisted. Empty unless
-   * `streaming` is true.
+   * same way while it happens and after it is persisted, and it is the only
+   * place the streamed answer is available. Empty unless `streaming` is true.
+   *
+   * `getTextFromStreamingParts` and `getReasoningPartsFromStreamingParts`
+   * flatten it the way a persisted turn is flattened, for a slot that wants one
+   * bubble rather than a timeline.
    */
   streamingParts: ChatStreamingPart[];
   feedbackEnabled: boolean;
diff --git a/packages/client/src/hooks/useServerEvents.abort.test.tsx b/packages/client/src/hooks/useServerEvents.abort.test.tsx
index 3a662698..9f68d6ac 100644
--- a/packages/client/src/hooks/useServerEvents.abort.test.tsx
+++ b/packages/client/src/hooks/useServerEvents.abort.test.tsx
@@ -114,7 +114,7 @@ describe('useServerEvents — abort handling', () => {
     ]);
 
     expect(result.current.loading).toBe(false);
-    expect(result.current.streamingText).toBe('');
+    expect(result.current.streamingParts).toEqual([]);
   });
 
   it('stopping mid tool-execution saves the tool_use/tool_result pair to history so the next turn stays valid', async () => {
diff --git a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
index f483109f..738945c5 100644
--- a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
+++ b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
@@ -34,9 +34,9 @@ function setup() {
 }
 
 /**
- * `streamingText` and `streamingReasoning` flatten a whole run into two
- * strings, so a multi-step run's thinking arrives as one block. `streamingParts`
- * keeps the step boundaries the run actually had.
+ * The parts are the only form the in-flight answer is kept in, so they must
+ * carry the step boundaries the run actually had. Flattening them into what one
+ * bubble shows happens in the UI; see utils/streamingParts.test.ts.
  */
 describe('useServerEvents — streaming parts', () => {
   it('keeps each step of reasoning separate instead of concatenating them', async () => {
@@ -55,8 +55,6 @@ describe('useServerEvents — streaming parts', () => {
       { kind: 'reasoning', text: 'First I check the time.' },
       { kind: 'reasoning', text: 'Then I add the numbers.' },
     ]);
-    // The flattened string keeps its existing shape for the built-in bubble.
-    expect(result.current.streamingReasoning).toBe('First I check the time.\n\nThen I add the numbers.');
   });
 
   it('interleaves reasoning, tool calls and text in the order they arrived', async () => {
diff --git a/packages/client/src/hooks/useServerEvents.ts b/packages/client/src/hooks/useServerEvents.ts
index 584df2cf..c7c48808 100644
--- a/packages/client/src/hooks/useServerEvents.ts
+++ b/packages/client/src/hooks/useServerEvents.ts
@@ -38,9 +38,9 @@ export interface UseServerEventsOptions {
 
 /**
  * One piece of the answer currently being produced, in the order the model
- * emitted it. `streamingText` and `streamingReasoning` flatten a whole run into
- * two strings, which loses the step boundaries; this keeps them, so a run that
- * thinks, calls a tool, thinks again and answers can be shown as it happened.
+ * emitted it. A run that thinks, calls a tool, thinks again and answers keeps
+ * those boundaries here, so the UI can show it as it happened. Flattening the
+ * parts into what one bubble shows is the UI's job (see `utils/streamingParts`).
  */
 export type ChatStreamingPart =
   | { kind: 'reasoning'; text: string }
@@ -62,8 +62,6 @@ export interface UseServerEventsReturn {
   loading: boolean;
   /** Set the loading state (e.g., when sending a message) */
   setLoading: React.Dispatch<React.SetStateAction<boolean>>;
-  /** Current streaming text from the AI response */
-  streamingText: string;
   /**
    * Id the streaming answer will be persisted under, allocated at RUN_STARTED
    * and cleared when the run ends. The chat panel renders the streaming answer
@@ -72,14 +70,12 @@ export interface UseServerEventsReturn {
    * @example "msg_1723972800000_k3j9x2a"
    */
   streamingMessageId: string | null;
-  /** Clear streaming text (e.g., when starting a new message) */
-  clearStreamingText: () => void;
+  /** Drop the in-flight answer (e.g., when starting a new message) */
+  clearStreamingParts: () => void;
   /** Currently executing tool info for UI display, or null */
   executingTool: ExecutingToolDisplay | null;
-  /** Ref tracking which chat the current streaming text belongs to */
+  /** Ref tracking which chat the in-flight answer belongs to */
   streamingChatIdRef: React.MutableRefObject<string | null>;
-  /** Current streaming reasoning text from extended thinking */
-  streamingReasoning: string;
   /** The in-flight answer split into ordered parts; empty between runs. */
   streamingParts: ChatStreamingPart[];
   /**
@@ -115,8 +111,6 @@ export function useServerEvents({
   strings,
 }: UseServerEventsOptions): UseServerEventsReturn {
   const [loading, setLoading] = useState(false);
-  const [streamingText, setStreamingText] = useState('');
-  const [streamingReasoning, setStreamingReasoning] = useState('');
   const [streamingParts, setStreamingParts] = useState<ChatStreamingPart[]>([]);
   const [streamingMessageId, setStreamingMessageId] = useState<string | null>(null);
   // Mirror of streamingMessageId for the stable event handler.
@@ -134,10 +128,6 @@ export function useServerEvents({
   // still link saved partial responses back to the trace.
   const runIdAtRunStartRef = useRef<string | undefined>(undefined);
 
-  // Tracks whether prior steps in this run emitted text, so we can insert
-  // a paragraph separator (\n\n) in streamingText between steps.
-  const hasTextFromPriorStepRef = useRef<boolean>(false);
-
   // Executing tool state for UI display
   const [executingToolRaw, setExecutingTool] = useState<{
     toolCallId: string;
@@ -146,8 +136,8 @@ export function useServerEvents({
   } | null>(null);
   const executingToolFallbackRef = useRef<string | null>(null);
 
-  const clearStreamingText = useCallback(() => {
-    setStreamingText('');
+  const clearStreamingParts = useCallback(() => {
+    setStreamingParts([]);
   }, []);
 
   /** Appends `delta` to the trailing part of `kind`, starting one if needed. */
@@ -214,8 +204,6 @@ export function useServerEvents({
   }, []);
 
   const resetRunUiState = useCallback(() => {
-    setStreamingText('');
-    setStreamingReasoning('');
     setStreamingParts([]);
     setStreamingMessageId(null);
     streamingMessageIdRef.current = null;
@@ -236,25 +224,16 @@ export function useServerEvents({
       // so messages added after this point are from the AI turn.
       messageCountAtRunStartRef.current = client.messages.length;
       runIdAtRunStartRef.current = client.currentRunId ?? undefined;
-      hasTextFromPriorStepRef.current = false;
-      setStreamingReasoning('');
       setStreamingParts([]);
       const messageId = generateMessageId();
       streamingMessageIdRef.current = messageId;
       setStreamingMessageId(messageId);
     } else if (event.type === EventType.REASONING_MESSAGE_START) {
-      // Add paragraph separator between reasoning from different steps
-      setStreamingReasoning(prev => prev ? prev + '\n\n' : prev);
       setStreamingParts(prev => [...prev, { kind: 'reasoning', text: '' }]);
     } else if (event.type === EventType.REASONING_MESSAGE_CONTENT) {
       const reasoningEvent = event as ReasoningMessageContentEvent;
-      setStreamingReasoning(prev => prev + reasoningEvent.delta);
       appendToPart('reasoning', reasoningEvent.delta);
     } else if (event.type === EventType.TEXT_MESSAGE_START) {
-      // Add paragraph separator between steps so combined text reads naturally
-      if (hasTextFromPriorStepRef.current) {
-        setStreamingText(prev => prev + '\n\n');
-      }
       setStreamingParts(prev => [...prev, { kind: 'text', text: '' }]);
     } else if (event.type === EventType.TOOL_CALL_ARGS) {
       const argsEvent = event as ToolCallArgsEvent;
@@ -315,8 +294,6 @@ export function useServerEvents({
       ts.handleApprovalRequest(e);
     } else if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
       const contentEvent = event as TextMessageContentEvent;
-      hasTextFromPriorStepRef.current = true;
-      setStreamingText(prev => prev + contentEvent.delta);
       appendToPart('text', contentEvent.delta);
     } else if (event.type === EventType.TEXT_MESSAGE_END) {
       // Don't clear streaming text here — wait for RUN_FINISHED so text
@@ -369,12 +346,10 @@ export function useServerEvents({
   return {
     loading,
     setLoading,
-    streamingText,
     streamingMessageId,
-    clearStreamingText,
+    clearStreamingParts,
     executingTool,
     streamingChatIdRef,
-    streamingReasoning,
     streamingParts,
     handleServerEvent,
     handleDisconnect,
diff --git a/packages/client/src/providers/useAIProvider.tsx b/packages/client/src/providers/useAIProvider.tsx
index 45faf3c6..26b017a6 100644
--- a/packages/client/src/providers/useAIProvider.tsx
+++ b/packages/client/src/providers/useAIProvider.tsx
@@ -239,10 +239,8 @@ export interface ChatPanelProps {
   loading: boolean;
   /** Whether the client is connected to the server */
   connected: boolean;
-  /** Optional currently streaming text from assistant */
-  streamingText?: string;
-  /** Optional currently streaming reasoning text from extended thinking */
-  streamingReasoning?: string;
+  /** The in-flight answer split into ordered parts; empty between runs */
+  streamingParts?: ChatStreamingPart[];
   /** Optional array of suggestion strings to display when chat is empty */
   suggestions?: string[];
   /** List of available agents from the server */
@@ -648,7 +646,7 @@ export function UseAIProvider({
   const handleSendMessage = useCallback(async (message: string, attachments?: FileAttachment[], messageForwardedProps?: UseAIForwardedProps) => {
     if (!clientRef.current) return;
 
-    serverEvents.clearStreamingText();
+    serverEvents.clearStreamingParts();
 
     const activatedChatId = chatManagement.activatePendingChat();
     const activeChatId = activatedChatId || chatManagement.currentChatId;
@@ -772,10 +770,6 @@ export function UseAIProvider({
 
   // ── Chat UI ─────────────────────────────────────────────────────────────
 
-  const effectiveStreamingText = serverEvents.streamingChatIdRef.current === chatManagement.displayedChatId
-    ? serverEvents.streamingText : '';
-  const effectiveStreamingReasoning = serverEvents.streamingChatIdRef.current === chatManagement.displayedChatId
-    ? serverEvents.streamingReasoning : '';
   const effectiveStreamingMessageId = serverEvents.streamingChatIdRef.current === chatManagement.displayedChatId
     ? serverEvents.streamingMessageId : null;
   const effectiveStreamingParts = serverEvents.streamingChatIdRef.current === chatManagement.displayedChatId
@@ -787,8 +781,6 @@ export function UseAIProvider({
     sendMessage: handleSendMessage,
     abortRun,
     messages,
-    streamingText: effectiveStreamingText,
-    streamingReasoning: effectiveStreamingReasoning,
     streamingMessageId: effectiveStreamingMessageId,
     streamingParts: effectiveStreamingParts,
     suggestions: promptState.aggregatedSuggestions,
@@ -845,8 +837,6 @@ export function UseAIProvider({
     messages,
     loading: serverEvents.loading,
     connected,
-    streamingText: effectiveStreamingText,
-    streamingReasoning: effectiveStreamingReasoning,
     streamingMessageId: effectiveStreamingMessageId,
     streamingParts: effectiveStreamingParts,
     currentChatId: chatManagement.displayedChatId,
@@ -899,8 +889,7 @@ export function UseAIProvider({
         messages={messages}
         loading={serverEvents.loading}
         connected={connected}
-        streamingText={effectiveStreamingText}
-        streamingReasoning={effectiveStreamingReasoning}
+        streamingParts={effectiveStreamingParts}
         suggestions={promptState.aggregatedSuggestions}
         availableAgents={availableAgents}
         defaultAgent={defaultAgent}

From acd404f051257ca0dff928afc9617c7a6b8b5b59 Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Tue, 1 Sep 2026 15:22:02 +0900
Subject: [PATCH 04/12] refactor(client): drop Reasoning's streamingText prop

Its only caller now hands the in-flight reasoning over as `reasoningParts`, the
same shape a persisted turn carries, so the separate string branch appended
nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/client/src/components/Reasoning.tsx | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/packages/client/src/components/Reasoning.tsx b/packages/client/src/components/Reasoning.tsx
index ff5270a4..0bcf7445 100644
--- a/packages/client/src/components/Reasoning.tsx
+++ b/packages/client/src/components/Reasoning.tsx
@@ -54,9 +54,9 @@ function ChevronIcon({ color, size = 16, rotated }: { color: string; size?: numb
 }
 
 export interface ReasoningProps {
+  /** Every step's reasoning, whether the run is still in flight or persisted. */
   reasoningParts: ReasoningPart[];
   isStreaming?: boolean;
-  streamingText?: string;
   theme: UseAITheme;
   strings: UseAIStrings;
 }
@@ -64,7 +64,6 @@ export interface ReasoningProps {
 export function Reasoning({
   reasoningParts,
   isStreaming = false,
-  streamingText,
   theme,
   strings,
 }: ReasoningProps) {
@@ -72,11 +71,7 @@ export function Reasoning({
 
   const toggle = useCallback(() => setIsOpen(prev => !prev), []);
 
-  // Combine completed parts + streaming block
-  const allText = [
-    ...reasoningParts.map(p => p.text),
-    ...(isStreaming && streamingText ? [streamingText] : []),
-  ].join('\n\n');
+  const allText = reasoningParts.map(p => p.text).join('\n\n');
 
   const headerContent = isStreaming
     ? <ShimmerText text={strings.thinking.inProgress} theme={theme} />

From 5e3048cbcddb64fb64f447489a7cb8e42cbca86d Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:43:41 +0900
Subject: [PATCH 05/12] fix(client): cut a streamed reasoning part at the block
 end event

A new reasoning part was opened only on REASONING_MESSAGE_START. A provider
that streams reasoning deltas without a start chunk emits one START per step,
so the deltas of a second block landed in the block that had already ended and
the two texts were joined into one part. The persisted turn splits on END
instead (client.ts pushes one block per END), so the thinking text changed the
moment the run finished.

REASONING_MESSAGE_END now marks the open part as closed and the next delta
opens a new one, which puts the boundary in the same place on both sides.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../useServerEvents.streamingParts.test.tsx   | 22 +++++++++++++++++++
 packages/client/src/hooks/useServerEvents.ts  | 19 +++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
index 738945c5..9a788c9e 100644
--- a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
+++ b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
@@ -57,6 +57,28 @@ describe('useServerEvents — streaming parts', () => {
     ]);
   });
 
+  // A provider that streams reasoning deltas without a start chunk gets one
+  // REASONING_MESSAGE_START for the whole step, so the block boundary the
+  // persisted turn keeps (one block per REASONING_MESSAGE_END) has to come off
+  // END here too. Otherwise the second block's text joins the first one and the
+  // thinking text changes the moment the run finishes.
+  it('starts a new reasoning part after a block ended, without a second start', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_START, messageId: 'r1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_CONTENT, messageId: 'r1', delta: 'First I check the time.' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_END, messageId: 'r1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_CONTENT, messageId: 'r1', delta: 'Then I add the numbers.' });
+    });
+
+    expect(result.current.streamingParts).toEqual([
+      { kind: 'reasoning', text: 'First I check the time.' },
+      { kind: 'reasoning', text: 'Then I add the numbers.' },
+    ]);
+  });
+
   it('interleaves reasoning, tool calls and text in the order they arrived', async () => {
     const { result, client } = setup();
 
diff --git a/packages/client/src/hooks/useServerEvents.ts b/packages/client/src/hooks/useServerEvents.ts
index c7c48808..b7422e97 100644
--- a/packages/client/src/hooks/useServerEvents.ts
+++ b/packages/client/src/hooks/useServerEvents.ts
@@ -136,6 +136,14 @@ export function useServerEvents({
   } | null>(null);
   const executingToolFallbackRef = useRef<string | null>(null);
 
+  // Set on REASONING_MESSAGE_END so the next reasoning delta opens a new part.
+  // The server normally opens every block with REASONING_MESSAGE_START, but a
+  // provider that streams deltas without a start chunk gets only one START per
+  // step, and those deltas would otherwise land in the block that already
+  // ended. The persisted side splits on END too (client.ts pushes one block per
+  // END), so both sides cut the reasoning at the same boundary.
+  const reasoningPartEndedRef = useRef(false);
+
   const clearStreamingParts = useCallback(() => {
     setStreamingParts([]);
   }, []);
@@ -224,15 +232,22 @@ export function useServerEvents({
       // so messages added after this point are from the AI turn.
       messageCountAtRunStartRef.current = client.messages.length;
       runIdAtRunStartRef.current = client.currentRunId ?? undefined;
+      reasoningPartEndedRef.current = false;
       setStreamingParts([]);
       const messageId = generateMessageId();
       streamingMessageIdRef.current = messageId;
       setStreamingMessageId(messageId);
     } else if (event.type === EventType.REASONING_MESSAGE_START) {
+      reasoningPartEndedRef.current = false;
       setStreamingParts(prev => [...prev, { kind: 'reasoning', text: '' }]);
     } else if (event.type === EventType.REASONING_MESSAGE_CONTENT) {
       const reasoningEvent = event as ReasoningMessageContentEvent;
-      appendToPart('reasoning', reasoningEvent.delta);
+      if (reasoningPartEndedRef.current) {
+        reasoningPartEndedRef.current = false;
+        setStreamingParts(prev => [...prev, { kind: 'reasoning', text: reasoningEvent.delta }]);
+      } else {
+        appendToPart('reasoning', reasoningEvent.delta);
+      }
     } else if (event.type === EventType.TEXT_MESSAGE_START) {
       setStreamingParts(prev => [...prev, { kind: 'text', text: '' }]);
     } else if (event.type === EventType.TOOL_CALL_ARGS) {
@@ -295,6 +310,8 @@ export function useServerEvents({
     } else if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
       const contentEvent = event as TextMessageContentEvent;
       appendToPart('text', contentEvent.delta);
+    } else if (event.type === EventType.REASONING_MESSAGE_END) {
+      reasoningPartEndedRef.current = true;
     } else if (event.type === EventType.TEXT_MESSAGE_END) {
       // Don't clear streaming text here — wait for RUN_FINISHED so text
       // stays visible across multi-step runs (no flash between steps).

From 22790c7547114fbdaae718c4ed44b6118254d606 Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:43:49 +0900
Subject: [PATCH 06/12] fix(client): keep the reasoning dropdown open when a
 run finishes

The streaming reasoning and the persisted reasoning were two conditionals at
different positions in DefaultMessage's fragment, so the handoff unmounted one
Reasoning and mounted the other, collapsing a dropdown the user had opened
mid-stream. Both sides now feed one element, with `isStreaming` following the
`streaming` flag.

The pending indicator had a second problem in the same window: from the render
that appends the persisted answer until the streaming state clears, the
provisional entry is gone but `loading` is still true, so an empty bubble was
drawn under the finished answer. The panel now checks for the persisted answer
as well.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../UseAIChatPanel.selection.test.tsx         | 34 ++++++++++++++++++-
 .../client/src/components/UseAIChatPanel.tsx  | 12 +++++--
 .../components/chatSlots/DefaultMessage.tsx   | 20 +++++------
 3 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/packages/client/src/components/UseAIChatPanel.selection.test.tsx b/packages/client/src/components/UseAIChatPanel.selection.test.tsx
index 0aa9cbe5..2c0ecac6 100644
--- a/packages/client/src/components/UseAIChatPanel.selection.test.tsx
+++ b/packages/client/src/components/UseAIChatPanel.selection.test.tsx
@@ -1,6 +1,6 @@
 import React from 'react';
 import { describe, test, expect, beforeEach } from 'bun:test';
-import { render } from '@testing-library/react';
+import { fireEvent, render } from '@testing-library/react';
 import { UseAIChatPanel, type UseAIChatPanelProps } from './UseAIChatPanel';
 import type { ChatStreamingPart } from '../hooks/useServerEvents';
 import type { PersistedMessage } from '../providers/chatRepository/types';
@@ -194,6 +194,38 @@ describe('streaming answer rendered as a provisional message', () => {
       <UseAIChatPanel {...panelProps({ messages: [userMessage, assistantMessage] })} />
     );
     expect(assistantBubbles(container)).toHaveLength(1);
+    // `loading` is still true in that render, so the pending indicator would
+    // otherwise draw a second, empty bubble under the finished answer.
+    expect(container.querySelector('.dots')).toBeNull();
+  });
+
+  // Both sides of the handoff render one Reasoning element in the same
+  // position, so React updates it instead of replacing it. Two conditionals
+  // would remount it and collapse what the user had opened.
+  test('keeps the reasoning dropdown open when the answer is persisted', () => {
+    const streamingProps = panelProps({
+      streamingParts: [{ kind: 'reasoning', text: 'Checking the time.' }, ...ANSWER_PARTS],
+    });
+    const { container, rerender } = render(<UseAIChatPanel {...streamingProps} />);
+
+    fireEvent.click(container.querySelector('[data-testid="thinking-toggle"]')!);
+    expect(container.querySelector('[data-testid="thinking-content"]')).not.toBeNull();
+
+    rerender(
+      <UseAIChatPanel
+        {...panelProps({
+          loading: false,
+          streamingParts: [],
+          streamingMessageId: null,
+          messages: [
+            userMessage,
+            { ...assistantMessage, reasoningParts: [{ text: 'Checking the time.' }] },
+          ],
+        })}
+      />
+    );
+
+    expect(container.querySelector('[data-testid="thinking-content"]')).not.toBeNull();
   });
 
   test('shows the plain loading indicator before any text streams', () => {
diff --git a/packages/client/src/components/UseAIChatPanel.tsx b/packages/client/src/components/UseAIChatPanel.tsx
index fc6b3394..ca786776 100644
--- a/packages/client/src/components/UseAIChatPanel.tsx
+++ b/packages/client/src/components/UseAIChatPanel.tsx
@@ -193,6 +193,13 @@ export function UseAIChatPanel({
   const displayMessages = mergeAssistantMessagesForDisplay(messages);
   const showInputDisclaimer = !!features.inputDisclaimer && displayMessages.length > 0;
 
+  // True from the render that appends the persisted answer until the streaming
+  // state clears. In that window the provisional entry below is gone but
+  // `loading` is still true, so the pending indicator has to check this as well
+  // or it draws a stray bubble under the finished answer.
+  const persistedStreamingAnswer =
+    !!streamingMessageId && displayMessages.some((m) => m.id === streamingMessageId);
+
   // The streaming answer is shown as a provisional assistant message under the
   // id it will be persisted with. When the persisted message arrives it takes
   // the same key, so React updates the existing bubble instead of replacing it,
@@ -202,8 +209,7 @@ export function UseAIChatPanel({
   // stays empty: the answer is passed as `streamingParts`, and the slot decides
   // how to render it.
   const provisionalMessage: DisplayMessage | null =
-    streamingParts.length > 0 &&
-    !(streamingMessageId && displayMessages.some((m) => m.id === streamingMessageId))
+    streamingParts.length > 0 && !persistedStreamingAnswer
       ? {
           id: streamingMessageId ?? PROVISIONAL_MESSAGE_ID,
           role: 'assistant',
@@ -398,7 +404,7 @@ export function UseAIChatPanel({
           />
         ))}
 
-        {loading && !provisionalMessage && (
+        {loading && !provisionalMessage && !persistedStreamingAnswer && (
           <Slot
             component={components?.PendingIndicator}
             fallback={DefaultPendingIndicator}
diff --git a/packages/client/src/components/chatSlots/DefaultMessage.tsx b/packages/client/src/components/chatSlots/DefaultMessage.tsx
index a9cd13cd..1c1116ab 100644
--- a/packages/client/src/components/chatSlots/DefaultMessage.tsx
+++ b/packages/client/src/components/chatSlots/DefaultMessage.tsx
@@ -67,7 +67,12 @@ export function DefaultMessage({
   // mergeAssistantMessagesForDisplay flattens the persisted turn. Both sides
   // must yield the same string for the handoff to leave the element alone.
   const text = streaming ? getTextFromStreamingParts(streamingParts) : getTextFromContent(message.content);
-  const streamingReasoningParts = streaming ? getReasoningPartsFromStreamingParts(streamingParts) : [];
+  // One element for both sides of the handoff: two conditionals would sit at
+  // different positions in the fragment below, so React would unmount one and
+  // mount the other, collapsing a dropdown the user had opened mid-stream.
+  const reasoningParts = streaming
+    ? getReasoningPartsFromStreamingParts(streamingParts)
+    : message.reasoningParts ?? [];
 
   return (
     <div
@@ -164,17 +169,10 @@ export function DefaultMessage({
       )}
       {message.role === 'assistant' ? (
         <>
-          {streaming && streamingReasoningParts.length > 0 && (
+          {reasoningParts.length > 0 && (
             <Reasoning
-              reasoningParts={streamingReasoningParts}
-              isStreaming={true}
-              theme={theme}
-              strings={strings}
-            />
-          )}
-          {!streaming && message.reasoningParts && message.reasoningParts.length > 0 && (
-            <Reasoning
-              reasoningParts={message.reasoningParts}
+              reasoningParts={reasoningParts}
+              isStreaming={streaming}
               theme={theme}
               strings={strings}
             />

From 3d6ac9ddcbcec247e7b3663b1e90e7cbdc1cce0a Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:43:54 +0900
Subject: [PATCH 07/12] feat(client): hand streamingMessageId to a custom chat
 panel

A panel passed through CustomChat received the run's parts but not the id they
will be persisted under, so it could not render the in-flight answer under that
id and its bubble was replaced rather than updated when the run finished. The
built-in panel and the chat UI context already had it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/client/src/providers/useAIProvider.tsx | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/client/src/providers/useAIProvider.tsx b/packages/client/src/providers/useAIProvider.tsx
index 26b017a6..b7b74739 100644
--- a/packages/client/src/providers/useAIProvider.tsx
+++ b/packages/client/src/providers/useAIProvider.tsx
@@ -241,6 +241,13 @@ export interface ChatPanelProps {
   connected: boolean;
   /** The in-flight answer split into ordered parts; empty between runs */
   streamingParts?: ChatStreamingPart[];
+  /**
+   * Id the streaming answer will be persisted under, or null between runs.
+   * Render the in-flight answer under this id to let the persisted answer take
+   * the same React key, so the bubble is updated instead of replaced and a
+   * selection inside it survives.
+   */
+  streamingMessageId?: string | null;
   /** Optional array of suggestion strings to display when chat is empty */
   suggestions?: string[];
   /** List of available agents from the server */
@@ -890,6 +897,7 @@ export function UseAIProvider({
         loading={serverEvents.loading}
         connected={connected}
         streamingParts={effectiveStreamingParts}
+        streamingMessageId={effectiveStreamingMessageId}
         suggestions={promptState.aggregatedSuggestions}
         availableAgents={availableAgents}
         defaultAgent={defaultAgent}

From 517741521943263fcda122ec885396c90431ff6f Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:44:00 +0900
Subject: [PATCH 08/12] docs: point slots at the streaming-parts flatteners

The section still said `streamingText` and `streamingReasoning` were available
on the message slot; both were removed when the run became parts only. Name the
two exported helpers the built-in bubble uses instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b0c4b838..f163f49b 100644
--- a/README.md
+++ b/README.md
@@ -796,8 +796,11 @@ function Message({ message, streaming, streamingParts }: ChatMessageSlotProps) {
 ```
 
 A run that thinks, calls a tool, thinks again and answers gives four parts in
-that order. `streamingText` and `streamingReasoning` are still there, each
-flattening the whole run into one string; the built-in bubble uses those.
+that order. A slot that wants one bubble instead of the pieces can flatten them
+the way the built-in bubble does, with the exported `getTextFromStreamingParts`
+(the text of every step, joined with a blank line) and
+`getReasoningPartsFromStreamingParts` (the reasoning in the shape a persisted
+turn carries it).
 
 `PendingIndicator` covers the gap between the run starting and the first token
 arriving, plus send-time file processing. It receives `executingTool` and

From 22d689ad007eb6873e6d25df997c22d8f98c4cc1 Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:44:08 +0900
Subject: [PATCH 09/12] fix(example): group a streamed turn's parts per step in
 the timeline

buildStreamingTimeline emitted the parts in arrival order, but a persisted
message records no order between its text and its tool calls, so buildTimeline
always puts the text first. A step whose tool call arrived before its text saw
the card and the prose swap places when the run finished, remounting both. The
parts are now grouped per step and each step emits reasoning, text, then tool
calls, and the text is trimmed and joined the way the persisted side does it.

Two smaller fixes alongside: a citation's `url` comes from a tool and `new URL`
throws on a relative or malformed one, which would unmount the chat since
nothing above renders an error boundary, so the hostname line is dropped
instead; and the message bubble no longer shows "Completed." for a run that has
started but has no entries yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../example/src/pages/CustomSlotsDemoPage.tsx |   5 +-
 apps/example/src/pages/orbitTimeline.tsx      | 124 +++++++++++++-----
 2 files changed, 92 insertions(+), 37 deletions(-)

diff --git a/apps/example/src/pages/CustomSlotsDemoPage.tsx b/apps/example/src/pages/CustomSlotsDemoPage.tsx
index a83b7f96..83644b1a 100644
--- a/apps/example/src/pages/CustomSlotsDemoPage.tsx
+++ b/apps/example/src/pages/CustomSlotsDemoPage.tsx
@@ -182,7 +182,10 @@ function OrbitMessage({
             <span>{new Date(message.createdAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}</span>
           )}
         </div>
-        {entries.length === 0 ? (
+        {/* A run has its parts before it has content: the meta line above is
+            already saying it is writing, so the bubble stays empty until the
+            first entry arrives. */}
+        {entries.length === 0 && !streaming ? (
           <OrbitProse text={text || 'Completed.'} />
         ) : (
           entries.map((entry) => {
diff --git a/apps/example/src/pages/orbitTimeline.tsx b/apps/example/src/pages/orbitTimeline.tsx
index e1c35da9..842ac731 100644
--- a/apps/example/src/pages/orbitTimeline.tsx
+++ b/apps/example/src/pages/orbitTimeline.tsx
@@ -225,36 +225,72 @@ export function buildTimeline(sourceMessages: PersistedMessage[]): TimelineEntry
   return entries;
 }
 
+/** One step's parts, held back until the step's order is known. */
+interface StreamingStep {
+  reasoning: string[];
+  text: string;
+  tools: Extract<ChatStreamingPart, { kind: 'tool_call' }>[];
+}
+
 /**
- * The same flattening for a run still in flight. The parts already arrive in
- * order, so this only reshapes them; results are not known yet, which is what
- * leaves the tool cards in their pending state.
+ * The same flattening for a run still in flight. Results are not known yet,
+ * which is what leaves the tool cards in their pending state.
+ *
+ * The parts arrive in the order the model emitted them, but a step's text and
+ * its tool calls are emitted in either order and a persisted message records no
+ * order between the two, so `buildTimeline` always puts the text first. The
+ * parts are grouped per step here and emitted in that same order, otherwise a
+ * step whose tool call came first would see its card and its prose swap places
+ * when the run finishes, remounting both.
  *
  * Ordinals are counted exactly as `buildTimeline` counts them, which is what
- * keeps an entry's key stable when the run finishes and the persisted turn
- * takes over. Both walk the same turn in the same order and drop blank text the
- * same way, so the nth text entry here is the nth text entry there.
+ * keeps an entry's key stable across that handoff: the nth text entry here is
+ * the nth text entry there.
  */
 export function buildStreamingTimeline(parts: ChatStreamingPart[]): TimelineEntry[] {
+  const steps: StreamingStep[] = [];
+  let step: StreamingStep | undefined;
+
+  for (const part of parts) {
+    // A step ends with its tool calls, so anything else after one starts the next.
+    if (!step || (part.kind !== 'tool_call' && step.tools.length > 0)) {
+      step = { reasoning: [], text: '', tools: [] };
+      steps.push(step);
+    }
+
+    if (part.kind === 'tool_call') step.tools.push(part);
+    else if (part.kind === 'reasoning') step.reasoning.push(part.text);
+    // Joined without a separator, as `messageText` joins a message's text parts.
+    else step.text += part.text;
+  }
+
+  const entries: TimelineEntry[] = [];
   const ordinals = { reasoning: 0, text: 0 };
+  for (const { reasoning, text, tools } of steps) {
+    for (const thought of reasoning) {
+      if (thought.trim()) {
+        entries.push({ kind: 'reasoning', key: `r${ordinals.reasoning++}`, text: thought });
+      }
+    }
 
-  return parts.flatMap((part) => {
-    if (part.kind === 'tool_call') {
-      return [{
-        kind: 'tool' as const,
-        key: part.toolCallId,
-        toolCallId: part.toolCallId,
-        name: part.name,
-        args: parseJson(part.args),
-      }];
+    // Trimmed, as `buildTimeline` trims a message's text: the two strings have
+    // to match exactly or the prose element is replaced at the handoff.
+    if (text.trim()) {
+      entries.push({ kind: 'text', key: `t${ordinals.text++}`, text: text.trim() });
+    }
+
+    for (const tool of tools) {
+      entries.push({
+        kind: 'tool',
+        key: tool.toolCallId,
+        toolCallId: tool.toolCallId,
+        name: tool.name,
+        args: parseJson(tool.args),
+      });
     }
-    if (!part.text.trim()) return [];
+  }
 
-    const key = part.kind === 'reasoning'
-      ? `r${ordinals.reasoning++}`
-      : `t${ordinals.text++}`;
-    return [{ kind: part.kind, key, text: part.text }];
-  });
+  return entries;
 }
 
 export function OrbitReasoning({ text, open }: { text: string; open?: boolean }) {
@@ -327,26 +363,42 @@ export function collectSources(entries: TimelineEntry[]): OrbitSource[] {
   return [...byUrl.values()];
 }
 
+/**
+ * A tool can put anything in `url`, and `new URL` throws on a relative or
+ * malformed one. Nothing above this renders an error boundary, so a throw here
+ * would unmount the whole chat; drop the hostname line instead.
+ */
+function sourceHostname(url: string): string | null {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+
 export function OrbitCitations({ sources }: { sources: OrbitSource[] }) {
   return (
     <div className="orbit-citations" data-testid="orbit-citations">
       <p className="orbit-kicker">SOURCES</p>
       <div className="orbit-citation-row">
-        {sources.map((source, index) => (
-          <a
-            key={source.url}
-            className="orbit-citation"
-            href={source.url}
-            target="_blank"
-            rel="noreferrer"
-            data-testid="orbit-citation"
-          >
-            <span>{index + 1}</span>
-            <strong>{source.title}</strong>
-            {source.snippet && <small>{source.snippet}</small>}
-            <em>{new URL(source.url).hostname}</em>
-          </a>
-        ))}
+        {sources.map((source, index) => {
+          const hostname = sourceHostname(source.url);
+          return (
+            <a
+              key={source.url}
+              className="orbit-citation"
+              href={source.url}
+              target="_blank"
+              rel="noreferrer"
+              data-testid="orbit-citation"
+            >
+              <span>{index + 1}</span>
+              <strong>{source.title}</strong>
+              {source.snippet && <small>{source.snippet}</small>}
+              {hostname && <em>{hostname}</em>}
+            </a>
+          );
+        })}
       </div>
     </div>
   );

From dbd5c2e23db6e156c256d564a64a7e176e0819c2 Mon Sep 17 00:00:00 2001
From: masudahiroto <96814344+masudahiroto@users.noreply.github.com>
Date: Wed, 2 Sep 2026 12:53:14 +0900
Subject: [PATCH 10/12] docs: trim the chat slots section to the essentials

The streaming, flattener and timeline walkthroughs duplicated what
/custom-slots-demo already shows in working code.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md | 59 +++++--------------------------------------------------
 1 file changed, 5 insertions(+), 54 deletions(-)

diff --git a/README.md b/README.md
index f163f49b..75ce94a4 100644
--- a/README.md
+++ b/README.md
@@ -758,6 +758,9 @@ Available slots are `Header`, `EmptyState`, `Message`, `PendingIndicator`,
 `Composer`, `ToolApproval`, and `Disclaimer`. Provider-level `chatComponents` apply to all
 chat instances. A specific `<UseAIChat components={...} />` takes precedence.
 
+The answer being streamed goes through `Message` too, as a provisional entry
+carrying the id it will be persisted under, so `streaming` tells the two apart.
+
 Each region's built-in implementation is exported as `DefaultHeader`,
 `DefaultMessage` and so on, taking exactly the props its slot receives. Reuse
 one when only part of a region needs to change:
@@ -775,60 +778,8 @@ function Message(props: ChatMessageSlotProps) {
 }
 ```
 
-The answer being streamed goes through `Message` too, as a provisional entry
-carrying the id it will be persisted under. `streaming` tells the two apart, and
-`streamingParts` holds the answer so far as the ordered pieces the model emitted:
-
-```tsx
-function Message({ message, streaming, streamingParts }: ChatMessageSlotProps) {
-  if (!streaming) return <PersistedTurn message={message} />;
-
-  return (
-    <div className="my-message is-streaming">
-      {streamingParts.map((part, index) => {
-        if (part.kind === 'reasoning') return <Thinking key={index} text={part.text} />;
-        if (part.kind === 'tool_call') return <ToolCard key={index} name={part.name} />;
-        return <Body key={index} text={part.text} />;
-      })}
-    </div>
-  );
-}
-```
-
-A run that thinks, calls a tool, thinks again and answers gives four parts in
-that order. A slot that wants one bubble instead of the pieces can flatten them
-the way the built-in bubble does, with the exported `getTextFromStreamingParts`
-(the text of every step, joined with a blank line) and
-`getReasoningPartsFromStreamingParts` (the reasoning in the shape a persisted
-turn carries it).
-
-`PendingIndicator` covers the gap between the run starting and the first token
-arriving, plus send-time file processing. It receives `executingTool` and
-`fileProcessing`, and stops rendering once the answer starts arriving.
-
-### Rendering a turn as a timeline
-
-The built-in bubble shows one turn as a single block of text: the tool calls,
-their results and the per-step reasoning are merged away. `sourceMessages` hands
-those back, in the order the model produced them, so a `Message` slot can lay
-the turn out step by step instead:
-
-```tsx
-function Message({ sourceMessages }: ChatMessageSlotProps) {
-  return sourceMessages.flatMap((source) => {
-    if (source.role === 'tool') return [];          // consumed as a call's result
-    return [
-      ...(source.reasoningParts ?? []).map((part) => <Thinking text={part.text} />),
-      <Prose content={source.content} />,
-      ...(source.toolCalls ?? []).map((call) => <ToolCard call={call} />),
-    ];
-  });
-}
-```
-
-A `tool` message carries the result of the call with the matching `toolCallId`,
-so anything a tool returned (citations, a table, a chart) is available to render
-under the answer. `apps/example` has a working page: `/custom-slots-demo`.
+A working example of every slot, including a turn rendered as a timeline, lives
+in `apps/example` at `/custom-slots-demo`.
 
 You can also disable them by passing `null`:
 

From c3c4e8988d73f2ba776ce919b4154d6c9216f205 Mon Sep 17 00:00:00 2001
From: Zachary Davison <zachary.davison@meetsmore.com>
Date: Wed, 2 Sep 2026 10:51:26 +0200
Subject: [PATCH 11/12] Make CustomSlotsDemoPage look like the other pages and
 not AI slop horror.

---
 .../example/src/pages/CustomSlotsDemoPage.tsx | 167 +++++++++---------
 1 file changed, 86 insertions(+), 81 deletions(-)

diff --git a/apps/example/src/pages/CustomSlotsDemoPage.tsx b/apps/example/src/pages/CustomSlotsDemoPage.tsx
index 83644b1a..7ff8a0ad 100644
--- a/apps/example/src/pages/CustomSlotsDemoPage.tsx
+++ b/apps/example/src/pages/CustomSlotsDemoPage.tsx
@@ -14,6 +14,8 @@ import {
   type PersistedMessageContent,
   type UseAIChatComponentOverrides,
 } from '@meetsmore-oss/use-ai-client';
+import { CollapsibleCode } from '../components/CollapsibleCode';
+import { docStyles } from '../styles/docStyles';
 import {
   OrbitCitations,
   OrbitProse,
@@ -399,15 +401,40 @@ const computeOrbitalPeriod = defineTool(
   }
 );
 
-const SLOT_NAMES = ['Header', 'Empty state', 'Messages', 'Pending indicator', 'Composer', 'Tool approval', 'Disclaimer'];
-
-const RENDERING_NOTES = [
-  'Tool calls as cards, in the turn',
-  'LaTeX in assistant prose',
-  'Sources pinned under the answer',
-  'Reasoning inline, step by step',
+const SLOT_NAMES = [
+  'Header: brand mark, agent picker, connection status',
+  'Empty state: kicker, intro, prompt list',
+  'Message: the whole turn, drawn as a timeline',
+  'Pending indicator: writing dots on the message meta line',
+  'Composer: textarea, attachments, send and stop',
+  'Tool approval: inline approve and reject row',
+  'Disclaimer: footer line under the composer',
 ];
 
+const CODE_EXAMPLE = `import {
+  UseAIChat,
+  type ChatMessageSlotProps,
+  type UseAIChatComponentOverrides,
+} from '@meetsmore-oss/use-ai-client';
+
+function OrbitMessage({ message, sourceMessages, streaming, streamingParts }: ChatMessageSlotProps) {
+  const entries = streaming ? buildStreamingTimeline(streamingParts) : buildTimeline(sourceMessages);
+
+  return <article className="orbit-message">{entries.map(renderEntry)}</article>;
+}
+
+const orbitComponents: UseAIChatComponentOverrides = {
+  Header: OrbitHeader,
+  EmptyState: OrbitEmptyState,
+  Message: OrbitMessage,
+  PendingIndicator: OrbitPendingIndicator,
+  Composer: OrbitComposer,
+  ToolApproval: OrbitToolApproval,
+  Disclaimer: OrbitDisclaimer,
+};
+
+<UseAIChat components={orbitComponents} />`;
+
 export default function CustomSlotsDemoPage() {
   useAI({
     tools: { searchHandbook, computeOrbitalPeriod },
@@ -420,49 +447,66 @@ export default function CustomSlotsDemoPage() {
   });
 
   return (
-    <div className="custom-slots-demo" data-testid="custom-slots-demo-page">
+    <div className="custom-slots-demo" style={docStyles.container} data-testid="custom-slots-demo-page">
       <style>{orbitStyles}</style>
-      <section className="orbit-page-intro">
-        <div>
-          <p className="orbit-page-kicker">COMPONENT SLOTS / LIVE EXAMPLE</p>
-          <h1>Same engine.<br /><em>A different character.</em></h1>
-        </div>
-        <div className="orbit-page-note">
-          <span>07</span>
-          <p>Every visible region below is supplied by the consuming app. Protocol, state, and streaming stay inside use-ai.</p>
-        </div>
-      </section>
+      <h1 style={docStyles.title}>Component Slots Demo</h1>
+
+      <div style={docStyles.infoCard}>
+        <h2 style={docStyles.subtitle}>About</h2>
+        <p style={docStyles.text}>
+          Pass <code style={docStyles.code}>components</code> to{' '}
+          <code style={docStyles.code}>UseAIChat</code> to replace a region of the chat with your own
+          component. This page replaces all seven regions. The protocol, the state and the streaming
+          stay inside use-ai.
+        </p>
+        <ul style={docStyles.list}>
+          {SLOT_NAMES.map((name) => (
+            <li key={name}>{name}</li>
+          ))}
+        </ul>
+      </div>
 
-      <section className="orbit-demo-grid">
+      <div style={docStyles.demoCard}>
+        <h2 style={docStyles.subtitle}>Live Demo</h2>
+        <p style={docStyles.text}>
+          Ask a question to see the slots draw a turn. The page registers two tools:{' '}
+          <code style={docStyles.code}>searchHandbook</code> returns sources, and{' '}
+          <code style={docStyles.code}>computeOrbitalPeriod</code> returns a formula in LaTeX.
+        </p>
         <div className="orbit-chat-shell">
           <div className="orbit-chat-accent" />
           <div className="orbit-chat" data-testid="orbit-chat">
             <UseAIChat components={orbitComponents} />
           </div>
         </div>
+      </div>
 
-        <aside className="orbit-specimen-card">
-          <p className="orbit-page-kicker">OVERRIDDEN REGIONS</p>
-          <h2>Slots, not a theme preset.</h2>
-          <p>
-            These are regular React components receiving live chat state and callbacks. Change markup, layout, or behavior without forking the chat client.
-          </p>
-          <ol>
-            {SLOT_NAMES.map((name, index) => (
-              <li key={name}><span>0{index + 1}</span>{name}</li>
-            ))}
-          </ol>
-          <p className="orbit-page-kicker">BUILT FROM sourceMessages</p>
-          <ul className="orbit-notes">
-            {RENDERING_NOTES.map((note) => (
-              <li key={note}>{note}</li>
-            ))}
-          </ul>
-          <div className="orbit-code-line">
-            <code>{'<UseAIChat components={orbitComponents} />'}</code>
-          </div>
-        </aside>
-      </section>
+      <div style={docStyles.definitionCard}>
+        <h2 style={docStyles.subtitle}>Code Example</h2>
+        <CollapsibleCode>{CODE_EXAMPLE}</CollapsibleCode>
+      </div>
+
+      <div style={docStyles.contextCard}>
+        <h2 style={docStyles.subtitle}>How It Works</h2>
+        <ul style={docStyles.list}>
+          <li>Each slot is a React component. It receives the live chat state and the callbacks as props.</li>
+          <li>
+            The <code style={docStyles.code}>Message</code> slot builds the timeline from{' '}
+            <code style={docStyles.code}>sourceMessages</code>: reasoning, tool cards and prose, in the
+            order the model produced them.
+          </li>
+          <li>
+            While the answer streams, the same slot reads{' '}
+            <code style={docStyles.code}>streamingParts</code>. The layout therefore does not change when
+            the run finishes.
+          </li>
+          <li>Tool results carry sources. The slot pins the sources under the answer.</li>
+          <li>
+            Render <code style={docStyles.code}>children</code> to decorate a built-in region. Omit{' '}
+            <code style={docStyles.code}>children</code> to replace the region.
+          </li>
+        </ul>
+      </div>
     </div>
   );
 }
@@ -472,25 +516,8 @@ const orbitStyles = `
     --orbit-ink: #11182b;
     --orbit-lime: #d7ff3f;
     --orbit-coral: #ff6b57;
-    min-height: 100vh;
-    padding: 52px clamp(24px, 5vw, 72px) 72px;
-    box-sizing: border-box;
-    color: var(--orbit-ink);
-    background:
-      radial-gradient(circle at 90% 4%, rgba(255, 107, 87, .19), transparent 27%),
-      linear-gradient(115deg, rgba(17, 24, 43, .045) 1px, transparent 1px),
-      #f1f2e9;
-    background-size: auto, 34px 34px, auto;
-    font-family: Inter, ui-sans-serif, system-ui, sans-serif;
   }
-  .orbit-page-intro { display: flex; justify-content: space-between; align-items: end; gap: 40px; max-width: 1180px; margin: 0 auto 42px; }
-  .orbit-page-kicker, .orbit-kicker, .orbit-eyebrow { margin: 0; font-size: 10px; line-height: 1.2; font-weight: 800; letter-spacing: .19em; }
-  .orbit-page-intro h1 { margin: 13px 0 0; font-size: clamp(38px, 5vw, 68px); line-height: .96; letter-spacing: -.055em; font-weight: 760; }
-  .orbit-page-intro h1 em, .orbit-empty h2 em { color: var(--orbit-coral); font-family: Georgia, serif; font-weight: 400; }
-  .orbit-page-note { display: flex; align-items: start; gap: 14px; width: min(360px, 100%); padding-bottom: 5px; }
-  .orbit-page-note > span { display: grid; place-items: center; flex: 0 0 44px; height: 44px; background: var(--orbit-lime); border: 1px solid var(--orbit-ink); border-radius: 50%; font-size: 13px; font-weight: 800; }
-  .orbit-page-note p { margin: 0; font-size: 13px; line-height: 1.55; color: #555b68; }
-  .orbit-demo-grid { display: grid; grid-template-columns: minmax(520px, 1fr) 310px; gap: 24px; max-width: 1180px; margin: 0 auto; align-items: stretch; }
+  .orbit-kicker, .orbit-eyebrow { margin: 0; font-size: 10px; line-height: 1.2; font-weight: 800; letter-spacing: .19em; }
   .orbit-chat-shell { display: grid; position: relative; min-height: 680px; overflow: hidden; background: var(--orbit-ink); border-radius: 26px; box-shadow: 0 26px 70px rgba(17, 24, 43, .18); }
   .orbit-chat-accent { position: absolute; top: -55px; right: -42px; width: 190px; height: 190px; border: 34px solid rgba(215, 255, 63, .11); border-radius: 50%; pointer-events: none; z-index: 1; }
   .orbit-chat { min-height: 0; position: relative; z-index: 2; }
@@ -565,9 +592,6 @@ const orbitStyles = `
   .orbit-citation strong { color: #e8eae3; font-size: 11px; line-height: 1.3; }
   .orbit-citation small { color: #8e96a8; font-size: 10px; line-height: 1.4; }
   .orbit-citation em { color: #747d91; font-size: 9px; font-style: normal; }
-  .orbit-notes { list-style: none; margin: 0 0 18px; padding: 0; display: grid; gap: 6px; }
-  .orbit-notes li { position: relative; padding-left: 15px; color: #626775; font-size: 11px; line-height: 1.5; }
-  .orbit-notes li::before { content: ''; position: absolute; left: 0; top: 6px; width: 6px; height: 6px; border-radius: 2px; background: var(--orbit-coral); }
   .orbit-avatar-pulse { animation: orbit-pulse 1.6s ease-in-out infinite; }
   .orbit-writing { display: flex; align-items: center; gap: 3px; text-transform: none; letter-spacing: 0; }
   .orbit-writing i { width: 3px; height: 3px; background: var(--orbit-lime); border-radius: 50%; animation: orbit-dot 1s ease-in-out infinite; }
@@ -599,29 +623,10 @@ const orbitStyles = `
   .orbit-approval small { color: #aab0bf; font-size: 9px; }
   .orbit-approval button { padding: 7px 9px; color: #c4c9d3; background: transparent; border: 1px solid rgba(255,255,255,.13); border-radius: 7px; cursor: pointer; font: 600 9px inherit; }
   .orbit-approval button.is-approve { color: var(--orbit-ink); background: var(--orbit-coral); border-color: var(--orbit-coral); }
-  .orbit-specimen-card { display: flex; flex-direction: column; min-height: 680px; box-sizing: border-box; padding: 28px 26px; background: #fffdf5; border: 1px solid rgba(17,24,43,.13); border-radius: 26px; }
-  .orbit-specimen-card h2 { margin: 16px 0 10px; font-family: Georgia, serif; font-size: 28px; line-height: 1.05; font-weight: 400; letter-spacing: -.025em; }
-  .orbit-specimen-card > p:not(.orbit-page-kicker) { margin: 0; color: #626775; font-size: 12px; line-height: 1.6; }
-  .orbit-specimen-card ol { list-style: none; margin: 27px 0; padding: 0; border-top: 1px solid #dadbd4; }
-  .orbit-specimen-card li { display: flex; gap: 13px; padding: 11px 0; border-bottom: 1px solid #dadbd4; font-size: 12px; font-weight: 700; }
-  .orbit-specimen-card li span { color: var(--orbit-coral); font-size: 9px; font-weight: 800; }
-  .orbit-code-line { margin-top: auto; padding: 13px; color: #edf0e5; background: var(--orbit-ink); border-radius: 10px; overflow: hidden; }
-  .orbit-code-line code { font-size: 9px; white-space: nowrap; }
   @keyframes orbit-pulse { 50% { box-shadow: 0 0 0 6px rgba(215,255,63,.08); } }
   @keyframes orbit-dot { 50% { opacity: .25; transform: translateY(-2px); } }
-  @media (max-width: 1050px) {
-    .orbit-demo-grid { grid-template-columns: 1fr; }
-    .orbit-specimen-card { min-height: auto; }
-    .orbit-specimen-card ol { display: grid; grid-template-columns: 1fr 1fr; gap: 0 18px; }
-    .orbit-code-line { margin-top: 8px; }
-  }
   @media (max-width: 720px) {
-    .custom-slots-demo { padding: 32px 14px 48px; }
-    .orbit-page-intro { display: block; }
-    .orbit-page-note { margin-top: 24px; }
-    .orbit-demo-grid { display: block; }
     .orbit-chat-shell { min-height: 650px; }
-    .orbit-specimen-card { margin-top: 18px; }
     .orbit-composer-actions small { display: none; }
     .orbit-agent-name, .orbit-agent-select { display: none; }
   }

From 71cbbf0cd04f970042f6d70dfda70ac8ebae9b99 Mon Sep 17 00:00:00 2001
From: Zachary Davison <zachary.davison@meetsmore.com>
Date: Wed, 2 Sep 2026 11:16:26 +0200
Subject: [PATCH 12/12] Fixes.

---
 .env.example                                  |  4 +-
 CLAUDE.md                                     |  1 +
 README.md                                     | 22 ++++++-
 apps/example/src/pages/MultiAgentPage.tsx     |  2 +-
 apps/use-ai-server-app/src/index.ts           | 10 ++-
 .../client/src/components/UseAIChatPanel.tsx  |  9 ++-
 .../src/components/UseAIChatSlots.test.tsx    | 16 +++++
 .../client/src/components/chatSlots/types.ts  |  7 +-
 .../useServerEvents.streamingParts.test.tsx   | 64 ++++++++++++++++++-
 packages/client/src/hooks/useServerEvents.ts  | 63 ++++++++++++++----
 .../client/src/utils/streamingParts.test.ts   | 33 +++++++++-
 packages/client/src/utils/streamingParts.ts   | 12 ++++
 packages/server/src/server.ts                 |  2 +-
 13 files changed, 217 insertions(+), 28 deletions(-)

diff --git a/.env.example b/.env.example
index 8d715703..e5f5288f 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,8 @@
 # AI Provider (at least one required)
 ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-# ANTHROPIC_MODEL=claude-sonnet-4-20250514
+# ANTHROPIC_MODEL=claude-opus-5
+# Required when the key above is identity-linked (scoped to all workspaces).
+# ANTHROPIC_WORKSPACE_ID=wrkspc_xxxxxxxxxxxxxxxxxxxxxxx
 # OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 # OPENAI_MODEL=gpt-4-turbo
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 43662375..e51248f5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,6 +51,7 @@ bun run kill                   # Kill processes on ports 3000, 3002, 8081
 
 **Server:**
 - `ANTHROPIC_API_KEY` (required)
+- `ANTHROPIC_WORKSPACE_ID` (required for an identity-linked key): sent as the `anthropic-workspace-id` header
 - `LOG_FORMAT` (optional): `pretty` (default) or `json`
 - `RATE_LIMIT_MAX_REQUESTS` (optional): Max requests per window (0 = unlimited)
 - `RATE_LIMIT_WINDOW_MS` (optional): Window in ms (default: 60000)
diff --git a/README.md b/README.md
index 75ce94a4..84ce4d36 100644
--- a/README.md
+++ b/README.md
@@ -131,7 +131,7 @@ services:
       # - OPENAI_API_KEY=${OPENAI_API_KEY}
 
       # Optional: Model selection
-      # - ANTHROPIC_MODEL=claude-sonnet-4-20250514
+      # - ANTHROPIC_MODEL=claude-opus-5
       # - OPENAI_MODEL=gpt-4-turbo
 
       # Optional: Server configuration
@@ -758,6 +758,21 @@ Available slots are `Header`, `EmptyState`, `Message`, `PendingIndicator`,
 `Composer`, `ToolApproval`, and `Disclaimer`. Provider-level `chatComponents` apply to all
 chat instances. A specific `<UseAIChat components={...} />` takes precedence.
 
+**Migrating a `CustomChat` from 1.17:** `ChatPanelProps` no longer carries
+`streamingText` and `streamingReasoning`, and `ReasoningProps` no longer carries
+`streamingText`. The in-flight answer now arrives as `streamingParts`, the
+ordered parts of the run. Flatten them with the exported helpers:
+
+```tsx
+import {
+  getTextFromStreamingParts,
+  getReasoningPartsFromStreamingParts,
+} from '@meetsmore-oss/use-ai-client';
+
+const streamingText = getTextFromStreamingParts(streamingParts);
+const streamingReasoning = getReasoningPartsFromStreamingParts(streamingParts);
+```
+
 The answer being streamed goes through `Message` too, as a provisional entry
 carrying the id it will be persisted under, so `streaming` tells the two apart.
 
@@ -985,7 +1000,8 @@ For most use cases, you can just use `@meetsmore-oss/use-ai-server` as-is, and c
 ```bash
 # AI Provider (at least one required)
 ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-# ANTHROPIC_MODEL=claude-sonnet-4-20250514
+# ANTHROPIC_MODEL=claude-opus-5
+# ANTHROPIC_WORKSPACE_ID=wrkspc_xxxxxxxxxxxxxxxxxxxxxxx  # Required for an identity-linked key
 # OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 # OPENAI_MODEL=gpt-4-turbo
 
@@ -1028,7 +1044,7 @@ const server = new UseAIServer({
     'claude': new AISDKAgent({
       name: 'Claude',
       annotation: 'Powered by Anthropic', // shown in agent selector UI
-      hooks: { loadConfig: () => ({ model: anthropic('claude-sonnet-4-20250514') }) },
+      hooks: { loadConfig: () => ({ model: anthropic('claude-opus-5') }) },
     })
   },
   defaultAgent: 'claude',
diff --git a/apps/example/src/pages/MultiAgentPage.tsx b/apps/example/src/pages/MultiAgentPage.tsx
index 2660619b..43c0f2fb 100644
--- a/apps/example/src/pages/MultiAgentPage.tsx
+++ b/apps/example/src/pages/MultiAgentPage.tsx
@@ -91,7 +91,7 @@ new UseAIServer({
   agents: {
     claude: new AISDKAgent({
       name: 'Claude',
-      hooks: { loadConfig: () => ({ model: anthropic('claude-sonnet-4-20250514') }) },
+      hooks: { loadConfig: () => ({ model: anthropic('claude-opus-5') }) },
     }),
     gpt: new AISDKAgent({
       name: 'GPT-4o',
diff --git a/apps/use-ai-server-app/src/index.ts b/apps/use-ai-server-app/src/index.ts
index 9098a096..4e596581 100644
--- a/apps/use-ai-server-app/src/index.ts
+++ b/apps/use-ai-server-app/src/index.ts
@@ -41,6 +41,9 @@ function createAgents(): { agents: Record<string, Agent>; defaultAgent: string }
     ? createGateway({ apiKey: process.env.AI_GATEWAY_API_KEY })
     : undefined;
   const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+  // An identity-linked Anthropic key acts inside a workspace, and the API
+  // rejects a request that does not name one.
+  const anthropicWorkspaceId = process.env.ANTHROPIC_WORKSPACE_ID;
   const openaiApiKey = process.env.OPENAI_API_KEY;
 
   // Temperature can be set via env var (useful for E2E tests to reduce flakiness)
@@ -117,8 +120,11 @@ function createAgents(): { agents: Record<string, Agent>; defaultAgent: string }
     const modelId = process.env.AI_GATEWAY_CLAUDE_MODEL || 'anthropic/claude-haiku-4.5';
     addAgent('claude', 'Claude', gateway(modelId), modelId, true, claudeProviderOptions);
   } else if (anthropicApiKey) {
-    const modelId = process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-20250514';
-    const model = createAnthropic({ apiKey: anthropicApiKey })(modelId);
+    const modelId = process.env.ANTHROPIC_MODEL || 'claude-opus-5';
+    const model = createAnthropic({
+      apiKey: anthropicApiKey,
+      ...(anthropicWorkspaceId ? { headers: { 'anthropic-workspace-id': anthropicWorkspaceId } } : {}),
+    })(modelId);
     addAgent('claude', 'Claude', model, modelId, false, claudeProviderOptions);
   }
 
diff --git a/packages/client/src/components/UseAIChatPanel.tsx b/packages/client/src/components/UseAIChatPanel.tsx
index ca786776..b20b3cd8 100644
--- a/packages/client/src/components/UseAIChatPanel.tsx
+++ b/packages/client/src/components/UseAIChatPanel.tsx
@@ -1,7 +1,8 @@
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useState, useRef, useEffect, useMemo } from 'react';
 import type { Chat, PersistedMessage } from '../providers/chatRepository/types';
 import { getDisplayTextFromContent } from '../utils/messageContent';
 import { mergeAssistantMessagesForDisplay, type MergedMessage } from '../utils/mergeAssistantMessages';
+import { hasStreamedAnswerContent } from '../utils/streamingParts';
 import type { SubmitMode } from '../utils/keyboard';
 import type { AgentInfo, FeedbackValue, EnabledFeatures } from '../types';
 import { DEFAULT_ENABLED_FEATURES } from '../types';
@@ -190,7 +191,9 @@ export function UseAIChatPanel({
   // combined with the final text-only message. Tool messages are filtered out.
   // This preserves per-step data structure (for LLM context) while showing
   // a unified bubble to the user.
-  const displayMessages = mergeAssistantMessagesForDisplay(messages);
+  // Memoized: a run re-renders the panel on every streamed token, and the merge
+  // walks the whole conversation.
+  const displayMessages = useMemo(() => mergeAssistantMessagesForDisplay(messages), [messages]);
   const showInputDisclaimer = !!features.inputDisclaimer && displayMessages.length > 0;
 
   // True from the render that appends the persisted answer until the streaming
@@ -209,7 +212,7 @@ export function UseAIChatPanel({
   // stays empty: the answer is passed as `streamingParts`, and the slot decides
   // how to render it.
   const provisionalMessage: DisplayMessage | null =
-    streamingParts.length > 0 && !persistedStreamingAnswer
+    hasStreamedAnswerContent(streamingParts) && !persistedStreamingAnswer
       ? {
           id: streamingMessageId ?? PROVISIONAL_MESSAGE_ID,
           role: 'assistant',
diff --git a/packages/client/src/components/UseAIChatSlots.test.tsx b/packages/client/src/components/UseAIChatSlots.test.tsx
index ea910d6f..e3bf6266 100644
--- a/packages/client/src/components/UseAIChatSlots.test.tsx
+++ b/packages/client/src/components/UseAIChatSlots.test.tsx
@@ -164,6 +164,22 @@ describe('UseAIChat component slots', () => {
     expect(getByTestId('custom-pending')).toHaveTextContent('Filling the form');
   });
 
+  // TOOL_CALL_START opens a part, but a tool call is not the answer speaking.
+  // Handing that window to the provisional bubble draws an empty bubble and
+  // makes `executingTool` unreachable.
+  test('keeps PendingIndicator while a tool runs before the answer starts', () => {
+    const { getByTestId, queryByTestId } = renderPanel(
+      { PendingIndicator },
+      {
+        streamingParts: [{ kind: 'tool_call', toolCallId: 'tool-1', name: 'fillForm', args: '{}' }],
+        executingTool,
+      }
+    );
+
+    expect(getByTestId('custom-pending')).toHaveTextContent('Filling the form');
+    expect(queryByTestId('chat-message-assistant-streaming')).toBeNull();
+  });
+
   test('drops PendingIndicator once the answer starts arriving', () => {
     const { queryByTestId } = renderPanel({ PendingIndicator }, { executingTool });
 
diff --git a/packages/client/src/components/chatSlots/types.ts b/packages/client/src/components/chatSlots/types.ts
index a8ea8cc3..2b14647c 100644
--- a/packages/client/src/components/chatSlots/types.ts
+++ b/packages/client/src/components/chatSlots/types.ts
@@ -105,12 +105,15 @@ export interface ChatSaveAsCommand {
 
 /**
  * The placeholder shown after a run starts but before the answer produces its
- * first token, and while a send-time file transformation (e.g. OCR) runs. Once
- * text or reasoning arrives the answer renders through the `Message` slot
+ * first token, and while a send-time file transformation (e.g. OCR) runs. A
+ * tool call that runs before the answer says anything falls in this window too.
+ * Once text or reasoning arrives the answer renders through the `Message` slot
  * instead, so this stops being rendered.
  */
 export interface ChatPendingIndicatorSlotProps extends ChatSlotProps {
+  /** The tool the run is waiting on, or null when it is not running one. */
   executingTool: ExecutingToolDisplay | null;
+  /** The transformation running over an attachment, or null when none runs. */
   fileProcessing: FileProcessingState | null;
 }
 
diff --git a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
index 9a788c9e..8267ed93 100644
--- a/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
+++ b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
@@ -96,10 +96,72 @@ describe('useServerEvents — streaming parts', () => {
     expect(result.current.streamingParts).toEqual([
       { kind: 'reasoning', text: 'Need the time.' },
       { kind: 'tool_call', toolCallId: 'tc1', name: 'getServerTime', args: '{"tz":"UTC"}' },
-      { kind: 'text', text: 'It is noon.' },
+      { kind: 'text', text: 'It is noon.', messageId: 'm1' },
     ]);
   });
 
+  // The persisted turn keeps one assistant message per step, so a step's text
+  // is one string there. Reasoning that arrives between two text deltas of the
+  // same step must therefore not cut the text in two: the flattened parts would
+  // gain a blank line the persisted message does not have, and the bubble would
+  // change the moment the run finishes.
+  it('keeps a step\'s text in one part when reasoning arrives between its deltas', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_START, messageId: 'm1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm1', delta: 'It is ' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_START, messageId: 'r1' });
+      await result.current.handleServerEvent(client, { type: EventType.REASONING_MESSAGE_CONTENT, messageId: 'r1', delta: 'Check the clock.' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm1', delta: 'noon.' });
+    });
+
+    expect(result.current.streamingParts).toEqual([
+      { kind: 'text', text: 'It is noon.', messageId: 'm1' },
+      { kind: 'reasoning', text: 'Check the clock.' },
+    ]);
+  });
+
+  it('starts a new text part for the next step', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_START, messageId: 'm1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm1', delta: 'Checking.' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_END, messageId: 'm1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_START, messageId: 'm2' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm2', delta: 'It is noon.' });
+    });
+
+    expect(result.current.streamingParts).toEqual([
+      { kind: 'text', text: 'Checking.', messageId: 'm1' },
+      { kind: 'text', text: 'It is noon.', messageId: 'm2' },
+    ]);
+  });
+
+  // Every argument token of every tool call arrives as its own event, and the
+  // whole panel re-renders on each new array. A run that is not building the
+  // named call has nothing to change.
+  it('keeps the same parts array when no tool call matches the args event', async () => {
+    const { result, client } = setup();
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.RUN_STARTED, threadId: 't', runId: 'run-1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_START, messageId: 'm1' });
+      await result.current.handleServerEvent(client, { type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm1', delta: 'Working.' });
+    });
+
+    const before = result.current.streamingParts;
+
+    await act(async () => {
+      await result.current.handleServerEvent(client, { type: EventType.TOOL_CALL_ARGS, toolCallId: 'unknown', delta: '{}' });
+    });
+
+    expect(result.current.streamingParts).toBe(before);
+  });
+
   it('clears the parts when the run finishes', async () => {
     const { result, client } = setup();
 
diff --git a/packages/client/src/hooks/useServerEvents.ts b/packages/client/src/hooks/useServerEvents.ts
index b7422e97..bc0f88d2 100644
--- a/packages/client/src/hooks/useServerEvents.ts
+++ b/packages/client/src/hooks/useServerEvents.ts
@@ -7,6 +7,7 @@ import type {
   RunErrorEvent,
   RunFinishedEvent,
   TextMessageContentEvent,
+  TextMessageStartEvent,
   ToolCallStartExtensions,
   ToolApprovalRequestEvent,
   ReasoningMessageContentEvent,
@@ -44,7 +45,12 @@ export interface UseServerEventsOptions {
  */
 export type ChatStreamingPart =
   | { kind: 'reasoning'; text: string }
-  | { kind: 'text'; text: string }
+  /**
+   * `messageId` is the id of the assistant message this text is persisted as,
+   * so deltas of one step reach one part even when reasoning interrupts them.
+   * @example "msg_01abc123"
+   */
+  | { kind: 'text'; text: string; messageId?: string }
   /** Args arrive as a JSON string, incomplete until the call is fully received. */
   | { kind: 'tool_call'; toolCallId: string; name: string; args: string };
 
@@ -148,14 +154,36 @@ export function useServerEvents({
     setStreamingParts([]);
   }, []);
 
-  /** Appends `delta` to the trailing part of `kind`, starting one if needed. */
-  const appendToPart = useCallback((kind: 'reasoning' | 'text', delta: string) => {
+  /**
+   * Appends `delta` to this step's text part, starting one if needed.
+   *
+   * The step's part is found by id rather than taken from the end, because
+   * reasoning can arrive between two text deltas of the same step. Splitting
+   * there would join the two halves with a blank line the persisted message
+   * does not have, and the answer would change as the run finishes.
+   */
+  const appendText = useCallback((messageId: string | undefined, delta: string) => {
+    setStreamingParts(prev => {
+      for (let index = prev.length - 1; index >= 0; index--) {
+        const part = prev[index];
+        if (part.kind === 'text' && part.messageId === messageId) {
+          const next = [...prev];
+          next[index] = { ...part, text: part.text + delta };
+          return next;
+        }
+      }
+      return [...prev, { kind: 'text', text: delta, messageId }];
+    });
+  }, []);
+
+  /** Appends `delta` to the trailing reasoning part, starting one if needed. */
+  const appendReasoning = useCallback((delta: string) => {
     setStreamingParts(prev => {
       const last = prev[prev.length - 1];
-      if (last?.kind === kind) {
+      if (last?.kind === 'reasoning') {
         return [...prev.slice(0, -1), { ...last, text: last.text + delta }];
       }
-      return [...prev, { kind, text: delta }];
+      return [...prev, { kind: 'reasoning', text: delta }];
     });
   }, []);
 
@@ -246,17 +274,26 @@ export function useServerEvents({
         reasoningPartEndedRef.current = false;
         setStreamingParts(prev => [...prev, { kind: 'reasoning', text: reasoningEvent.delta }]);
       } else {
-        appendToPart('reasoning', reasoningEvent.delta);
+        appendReasoning(reasoningEvent.delta);
       }
     } else if (event.type === EventType.TEXT_MESSAGE_START) {
-      setStreamingParts(prev => [...prev, { kind: 'text', text: '' }]);
+      const startEvent = event as TextMessageStartEvent;
+      setStreamingParts(prev => [...prev, { kind: 'text', text: '', messageId: startEvent.messageId }]);
     } else if (event.type === EventType.TOOL_CALL_ARGS) {
       const argsEvent = event as ToolCallArgsEvent;
-      setStreamingParts(prev => prev.map(part =>
-        part.kind === 'tool_call' && part.toolCallId === argsEvent.toolCallId
-          ? { ...part, args: part.args + argsEvent.delta }
-          : part
-      ));
+      setStreamingParts(prev => {
+        // One event per argument token, so an unchanged run must keep its array:
+        // a new one re-renders the whole panel for nothing.
+        for (let index = 0; index < prev.length; index++) {
+          const part = prev[index];
+          if (part.kind === 'tool_call' && part.toolCallId === argsEvent.toolCallId) {
+            const next = [...prev];
+            next[index] = { ...part, args: part.args + argsEvent.delta };
+            return next;
+          }
+        }
+        return prev;
+      });
     } else if (event.type === EventType.TOOL_CALL_START) {
       const e = event as ToolCallStartEvent & Partial<ToolCallStartExtensions>;
 
@@ -309,7 +346,7 @@ export function useServerEvents({
       ts.handleApprovalRequest(e);
     } else if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
       const contentEvent = event as TextMessageContentEvent;
-      appendToPart('text', contentEvent.delta);
+      appendText(contentEvent.messageId, contentEvent.delta);
     } else if (event.type === EventType.REASONING_MESSAGE_END) {
       reasoningPartEndedRef.current = true;
     } else if (event.type === EventType.TEXT_MESSAGE_END) {
diff --git a/packages/client/src/utils/streamingParts.test.ts b/packages/client/src/utils/streamingParts.test.ts
index 0c911a07..d7f577d9 100644
--- a/packages/client/src/utils/streamingParts.test.ts
+++ b/packages/client/src/utils/streamingParts.test.ts
@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'bun:test';
-import { getReasoningPartsFromStreamingParts, getTextFromStreamingParts } from './streamingParts';
+import {
+  getReasoningPartsFromStreamingParts,
+  getTextFromStreamingParts,
+  hasStreamedAnswerContent,
+} from './streamingParts';
 import { mergeAssistantMessagesForDisplay } from './mergeAssistantMessages';
 import type { PersistedMessage } from '../providers/chatRepository/types';
 import type { ChatStreamingPart } from '../hooks/useServerEvents';
@@ -66,3 +70,30 @@ describe('getReasoningPartsFromStreamingParts', () => {
     expect(getReasoningPartsFromStreamingParts([{ kind: 'reasoning', text: '' }])).toEqual([]);
   });
 });
+
+describe('hasStreamedAnswerContent', () => {
+  it('is true once a step has produced text', () => {
+    expect(hasStreamedAnswerContent([{ kind: 'text', text: 'A' }])).toBe(true);
+  });
+
+  it('is true once a step has produced reasoning', () => {
+    expect(hasStreamedAnswerContent([{ kind: 'reasoning', text: 'Hmm.' }])).toBe(true);
+  });
+
+  // A tool call runs before the answer says anything. The bubble would be empty
+  // for the whole call, and the pending indicator that names the running tool
+  // would be suppressed behind it.
+  it('is false while only a tool call has started', () => {
+    expect(hasStreamedAnswerContent([
+      { kind: 'tool_call', toolCallId: 'tc1', name: 'search', args: '' },
+    ])).toBe(false);
+  });
+
+  it('is false for a step opened before its first delta', () => {
+    expect(hasStreamedAnswerContent([{ kind: 'text', text: '' }])).toBe(false);
+  });
+
+  it('is false between runs', () => {
+    expect(hasStreamedAnswerContent([])).toBe(false);
+  });
+});
diff --git a/packages/client/src/utils/streamingParts.ts b/packages/client/src/utils/streamingParts.ts
index 0d2ffca7..8f67e6f4 100644
--- a/packages/client/src/utils/streamingParts.ts
+++ b/packages/client/src/utils/streamingParts.ts
@@ -25,3 +25,15 @@ export function getReasoningPartsFromStreamingParts(parts: ChatStreamingPart[]):
     part.kind === 'reasoning' && part.text ? [{ text: part.text }] : [],
   );
 }
+
+/**
+ * Whether the answer itself has started, that is, whether any step has produced
+ * text or reasoning.
+ *
+ * A tool call opens a part before the answer says anything, and a step opens an
+ * empty text part before its first delta. Neither is something to show, so the
+ * run stays with the pending indicator until this turns true.
+ */
+export function hasStreamedAnswerContent(parts: ChatStreamingPart[]): boolean {
+  return parts.some((part) => part.kind !== 'tool_call' && part.text.length > 0);
+}
diff --git a/packages/server/src/server.ts b/packages/server/src/server.ts
index 26d48eb8..f9169118 100644
--- a/packages/server/src/server.ts
+++ b/packages/server/src/server.ts
@@ -66,7 +66,7 @@ export type { ClientSession } from './agents/types';
  *   apiKey: process.env.ANTHROPIC_API_KEY,
  * });
  * const claudeAgent = new AISDKAgent({
- *   hooks: { loadConfig: () => ({ model: anthropic('claude-sonnet-4-20250514') }) },
+ *   hooks: { loadConfig: () => ({ model: anthropic('claude-opus-5') }) },
  * });
  * const server = new UseAIServer({
  *   port: 8081,