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 15ded121..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
@@ -723,6 +723,79 @@ 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.
+
+**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.
+
+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 />}
+    </>
+  );
+}
+```
+
+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`:
 
 ```tsx
@@ -927,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
 
@@ -970,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/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..7ff8a0ad
--- /dev/null
+++ b/apps/example/src/pages/CustomSlotsDemoPage.tsx
@@ -0,0 +1,633 @@
+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 { CollapsibleCode } from '../components/CollapsibleCode';
+import { docStyles } from '../styles/docStyles';
+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>
+        {/* 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) => {
+            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: 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 },
+    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" style={docStyles.container} data-testid="custom-slots-demo-page">
+      <style>{orbitStyles}</style>
+      <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>
+
+      <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>
+
+      <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>
+  );
+}
+
+const orbitStyles = `
+  .custom-slots-demo {
+    --orbit-ink: #11182b;
+    --orbit-lime: #d7ff3f;
+    --orbit-coral: #ff6b57;
+  }
+  .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; }
+  .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-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); }
+  @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: 720px) {
+    .orbit-chat-shell { min-height: 650px; }
+    .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/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/example/src/pages/orbitTimeline.tsx b/apps/example/src/pages/orbitTimeline.tsx
new file mode 100644
index 00000000..842ac731
--- /dev/null
+++ b/apps/example/src/pages/orbitTimeline.tsx
@@ -0,0 +1,405 @@
+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;
+}
+
+/** 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. 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 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 });
+      }
+    }
+
+    // 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),
+      });
+    }
+  }
+
+  return entries;
+}
+
+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()];
+}
+
+/**
+ * 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) => {
+          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>
+  );
+}
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/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/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} />
diff --git a/packages/client/src/components/UseAIChat.test.tsx b/packages/client/src/components/UseAIChat.test.tsx
index 892ed735..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,
@@ -58,10 +57,25 @@ function createContextValue(overrides: Partial<ChatUIContextValue> = {}): ChatUI
 }
 
 describe('UseAIChat', () => {
-  test('passes streaming reasoning through to UseAIChatPanel', () => {
+  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 the streaming parts through to UseAIChatPanel', () => {
     const ctx = createContextValue({
       loading: true,
-      streamingReasoning: 'First thought...',
+      streamingParts: [{ kind: 'reasoning', text: 'First thought...' }],
     });
 
     const { getByTestId, getByText } = render(
@@ -80,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',
     });
 
@@ -101,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 1a35bc87..ab805b81 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.
@@ -26,16 +28,14 @@ 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
    * 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 +94,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 +129,8 @@ export interface ChatUIContextValue {
    * @default 'enter'
    */
   submitMode?: SubmitMode;
+  /** Provider-level component overrides for the built-in chat UI. */
+  components?: UseAIChatComponentOverrides;
 }
 
 /**
@@ -169,6 +171,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,18 +203,22 @@ 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,
     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,
     onNewChat: ctx.history.create,
     onLoadChat: ctx.history.load,
@@ -233,6 +244,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.selection.test.tsx b/packages/client/src/components/UseAIChatPanel.selection.test.tsx
index 6028b4fa..2c0ecac6 100644
--- a/packages/client/src/components/UseAIChatPanel.selection.test.tsx
+++ b/packages/client/src/components/UseAIChatPanel.selection.test.tsx
@@ -1,12 +1,23 @@
 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';
 
 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],
         })}
@@ -177,17 +194,51 @@ 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', () => {
-    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 8ffdf2f2..b20b3cd8 100644
--- a/packages/client/src/components/UseAIChatPanel.tsx
+++ b/packages/client/src/components/UseAIChatPanel.tsx
@@ -1,23 +1,31 @@
-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 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';
 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 +36,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';
@@ -165,10 +66,12 @@ 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, 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[];
   /**
    * 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 +110,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 +135,8 @@ export interface UseAIChatPanelProps {
    * @default 'enter'
    */
   submitMode?: SubmitMode;
+  /** Replace individual regions while retaining the built-in behavior by default. */
+  components?: UseAIChatComponentOverrides;
 }
 
 /**
@@ -249,8 +149,7 @@ export function UseAIChatPanel({
   messages,
   loading,
   connected,
-  streamingText = '',
-  streamingReasoning = '',
+  streamingParts = EMPTY_STREAMING_PARTS,
   streamingMessageId = null,
   currentChatId,
   onNewChat,
@@ -278,6 +177,7 @@ export function UseAIChatPanel({
   onApproveToolCall,
   onRejectToolCall,
   submitMode = 'enter',
+  components,
 }: UseAIChatPanelProps) {
   const strings = useStrings();
   const theme = useTheme();
@@ -291,22 +191,34 @@ 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
+  // 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,
   // 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) &&
-    !(streamingMessageId && displayMessages.some((m) => m.id === streamingMessageId))
+    hasStreamedAnswerContent(streamingParts) && !persistedStreamingAnswer
       ? {
           id: streamingMessageId ?? PROVISIONAL_MESSAGE_ID,
           role: 'assistant',
-          content: streamingText,
+          content: '',
           createdAt: PROVISIONAL_CREATED_AT,
+          sourceMessages: [],
           streaming: true,
         }
       : null;
@@ -315,15 +227,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 +264,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 +287,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 +343,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 +374,118 @@ 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,
+              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',
+          />
+        ))}
+
+        {loading && !provisionalMessage && !persistedStreamingAnswer && (
+          <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..e3bf6266
--- /dev/null
+++ b/packages/client/src/components/UseAIChatSlots.test.tsx
@@ -0,0 +1,239 @@
+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';
+import { getTextFromStreamingParts } from '../utils/streamingParts';
+
+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
+      streamingParts={[{ kind: 'text', text: '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, streamingParts }: ChatMessageSlotProps) => (
+      <div data-testid="custom-message" data-streaming={String(streaming)}>
+        {streaming ? getTextFromStreamingParts(streamingParts) : (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, streamingParts, isLast }: ChatMessageSlotProps) => (
+      <div
+        data-testid={`slot-${slotMessage.id}`}
+        data-streaming={String(streaming)}
+        data-parts={streamingParts.map((part) => part.kind).join(',')}
+        data-last={String(isLast)}
+      >
+        {streaming ? getTextFromStreamingParts(streamingParts) : (slotMessage.content as string)}
+      </div>
+    );
+
+    const { getByTestId } = renderPanel(
+      { Message },
+      {
+        streamingMessageId: 'message-2',
+        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-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');
+    // The ordered parts let a slot keep the run's steps apart while it streams.
+    expect(streamingBubble).toHaveAttribute('data-parts', 'reasoning,tool_call,text');
+    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 },
+      { streamingParts: [], executingTool }
+    );
+
+    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 });
+
+    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..1c1116ab
--- /dev/null
+++ b/packages/client/src/components/chatSlots/DefaultMessage.tsx
@@ -0,0 +1,246 @@
+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';
+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,
+  streamingParts,
+  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';
+  // 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);
+  // 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
+      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' ? (
+        <>
+          {reasoningParts.length > 0 && (
+            <Reasoning
+              reasoningParts={reasoningParts}
+              isStreaming={streaming}
+              theme={theme}
+              strings={strings}
+            />
+          )}
+          {streaming && !text ? (
+            <span className="dots" style={{ opacity: 0.6 }}>...</span>
+          ) : (
+            <MarkdownContent content={text} />
+          )}
+        </>
+      ) : (
+        // 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..2b14647c
--- /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` 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
+   * `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;
+  /**
+   * 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, 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;
+  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. 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;
+}
+
+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.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
new file mode 100644
index 00000000..8267ed93
--- /dev/null
+++ b/packages/client/src/hooks/useServerEvents.streamingParts.test.tsx
@@ -0,0 +1,180 @@
+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() };
+}
+
+/**
+ * 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 () => {
+    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.' },
+    ]);
+  });
+
+  // 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();
+
+    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.', 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();
+
+    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..bc0f88d2 100644
--- a/packages/client/src/hooks/useServerEvents.ts
+++ b/packages/client/src/hooks/useServerEvents.ts
@@ -3,9 +3,11 @@ import type {
   AGUIEvent,
   ToolCallStartEvent,
   ToolCallEndEvent,
+  ToolCallArgsEvent,
   RunErrorEvent,
   RunFinishedEvent,
   TextMessageContentEvent,
+  TextMessageStartEvent,
   ToolCallStartExtensions,
   ToolApprovalRequestEvent,
   ReasoningMessageContentEvent,
@@ -35,7 +37,29 @@ export interface UseServerEventsOptions {
   strings: UseAIStrings;
 }
 
+/**
+ * One piece of the answer currently being produced, in the order the model
+ * 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 }
+  /**
+   * `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 };
+
 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;
 }
 
@@ -44,8 +68,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
@@ -54,14 +76,14 @@ 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[];
   /**
    * Handles a server event. Called from the provider's client subscription.
    * Takes the client instance so it can access client-internal state
@@ -95,8 +117,7 @@ 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.
   const streamingMessageIdRef = useRef<string | null>(null);
@@ -113,19 +134,57 @@ 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;
+    name: string;
     title: string | null;
   } | null>(null);
   const executingToolFallbackRef = useRef<string | null>(null);
 
-  const clearStreamingText = useCallback(() => {
-    setStreamingText('');
+  // 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([]);
+  }, []);
+
+  /**
+   * 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 === 'reasoning') {
+        return [...prev.slice(0, -1), { ...last, text: last.text + delta }];
+      }
+      return [...prev, { kind: 'reasoning', text: delta }];
+    });
   }, []);
 
   // Keep refs to avoid stale closures in the event handler
@@ -181,8 +240,7 @@ export function useServerEvents({
   }, []);
 
   const resetRunUiState = useCallback(() => {
-    setStreamingText('');
-    setStreamingReasoning('');
+    setStreamingParts([]);
     setStreamingMessageId(null);
     streamingMessageIdRef.current = null;
     streamingChatIdRef.current = null;
@@ -202,22 +260,40 @@ 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('');
+      reasoningPartEndedRef.current = false;
+      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);
+      reasoningPartEndedRef.current = false;
+      setStreamingParts(prev => [...prev, { kind: 'reasoning', text: '' }]);
     } else if (event.type === EventType.REASONING_MESSAGE_CONTENT) {
       const reasoningEvent = event as ReasoningMessageContentEvent;
-      setStreamingReasoning(prev => prev + 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');
+      if (reasoningPartEndedRef.current) {
+        reasoningPartEndedRef.current = false;
+        setStreamingParts(prev => [...prev, { kind: 'reasoning', text: reasoningEvent.delta }]);
+      } else {
+        appendReasoning(reasoningEvent.delta);
       }
+    } else if (event.type === EventType.TEXT_MESSAGE_START) {
+      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 => {
+        // 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>;
 
@@ -230,7 +306,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;
@@ -266,8 +346,9 @@ 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);
+      appendText(contentEvent.messageId, 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).
@@ -310,19 +391,20 @@ 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;
 
   return {
     loading,
     setLoading,
-    streamingText,
     streamingMessageId,
-    clearStreamingText,
+    clearStreamingParts,
     executingTool,
     streamingChatIdRef,
-    streamingReasoning,
+    streamingParts,
     handleServerEvent,
     handleDisconnect,
   };
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index 6f7009ae..6caed550 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -27,7 +27,38 @@ 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 {
+  getTextFromStreamingParts,
+  getReasoningPartsFromStreamingParts,
+} from './utils/streamingParts';
 
 export type { UseAIOptions, UseAIResult } from './useAI';
 export type { UseAIWorkflowResult, TriggerWorkflowOptions, WorkflowProgress } from './useAIWorkflow';
@@ -148,6 +179,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..b7b74739 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 ───────────────────────────────────────────────────────────
 
@@ -235,10 +239,15 @@ 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[];
+  /**
+   * 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 */
@@ -256,6 +265,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 +475,7 @@ export function UseAIProvider({
   systemPrompt,
   CustomButton,
   CustomChat,
+  chatComponents,
   chatRepository,
   forwardedPropsProvider,
   fileUploadConfig: fileUploadConfigProp,
@@ -641,7 +653,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;
@@ -765,12 +777,10 @@ 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
+    ? serverEvents.streamingParts : EMPTY_STREAMING_PARTS;
 
   const chatUIContextValue: ChatUIContextValue = {
     connected,
@@ -778,9 +788,8 @@ export function UseAIProvider({
     sendMessage: handleSendMessage,
     abortRun,
     messages,
-    streamingText: effectiveStreamingText,
-    streamingReasoning: effectiveStreamingReasoning,
     streamingMessageId: effectiveStreamingMessageId,
+    streamingParts: effectiveStreamingParts,
     suggestions: promptState.aggregatedSuggestions,
     fileUploadConfig,
     fileProcessing: fileProcessingState,
@@ -822,6 +831,7 @@ export function UseAIProvider({
       submit: feedback.submitFeedback,
     },
     submitMode,
+    components: chatComponents,
   };
 
   const isUIDisabled = CustomButton === null || CustomChat === null;
@@ -834,9 +844,8 @@ export function UseAIProvider({
     messages,
     loading: serverEvents.loading,
     connected,
-    streamingText: effectiveStreamingText,
-    streamingReasoning: effectiveStreamingReasoning,
     streamingMessageId: effectiveStreamingMessageId,
+    streamingParts: effectiveStreamingParts,
     currentChatId: chatManagement.displayedChatId,
     onNewChat: chatManagement.createNewChat,
     onLoadChat: chatManagement.loadChat,
@@ -861,6 +870,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 = () => {
@@ -886,8 +896,8 @@ export function UseAIProvider({
         messages={messages}
         loading={serverEvents.loading}
         connected={connected}
-        streamingText={effectiveStreamingText}
-        streamingReasoning={effectiveStreamingReasoning}
+        streamingParts={effectiveStreamingParts}
+        streamingMessageId={effectiveStreamingMessageId}
         suggestions={promptState.aggregatedSuggestions}
         availableAgents={availableAgents}
         defaultAgent={defaultAgent}
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] });
     }
   }
 
diff --git a/packages/client/src/utils/streamingParts.test.ts b/packages/client/src/utils/streamingParts.test.ts
new file mode 100644
index 00000000..d7f577d9
--- /dev/null
+++ b/packages/client/src/utils/streamingParts.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'bun:test';
+import {
+  getReasoningPartsFromStreamingParts,
+  getTextFromStreamingParts,
+  hasStreamedAnswerContent,
+} 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([]);
+  });
+});
+
+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
new file mode 100644
index 00000000..8f67e6f4
--- /dev/null
+++ b/packages/client/src/utils/streamingParts.ts
@@ -0,0 +1,39 @@
+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 }] : [],
+  );
+}
+
+/**
+ * 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,