@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -1,36 +1,50 @@
 ---
 title: ExternalStoreRuntime
-description: Bring your own Redux, Zustand, or state manager.
+description: Bring your own redux, zustand, or state manager.
 ---
 
+`ExternalStoreRuntime` bridges your existing state management with assistant-ui. You provide messages and callbacks; the runtime renders whatever you give it. UI features turn on based on which callbacks are present.
 
-## Overview
+## When to use it
 
-`ExternalStoreRuntime` bridges your existing state management with assistant-ui components. It requires an `ExternalStoreAdapter<TMessage>` that handles communication between your state and the UI.
+Pick `ExternalStoreRuntime` when:
 
-**Key differences from `LocalRuntime`:**
+- You already keep messages in redux, zustand, tanstack-query, or another store, and want to keep them there.
+- You want full control over message state, persistence, and synchronization.
+- You have a custom message format and need automatic conversion to assistant-ui's format.
 
-- **You own the state** - Full control over message state, thread management, and persistence logic
-- **Bring your own state management** - Works with Redux, Zustand, TanStack Query, or any React state library
-- **Custom message formats** - Use your backend's message structure with automatic conversion
+If you do not have an existing store, use [`LocalRuntime`](/docs/runtimes/custom/local-runtime) instead; it is lower-friction.
 
-<Callout type="warn">
-  `ExternalStoreRuntime` gives you total control over state (persist, sync,
-  share), but you must wire up every callback.
-</Callout>
+## Architecture
+
+```mermaid
+graph TD
+    A[Your state] -->|messages| B[ExternalStoreAdapter]
+    B --> C[ExternalStoreRuntime]
+    C --> D[assistant-ui components]
+    D -->|user actions| B
+    B -->|state updates| A
+```
 
-## Example Implementation
+Key idea: you own the state, the adapter translates between your format and assistant-ui's. UI features are capability-based; if you provide `setMessages`, branching turns on; if you provide `onEdit`, editing turns on; etc.
 
-```tsx twoslash title="app/MyRuntimeProvider.tsx"
-type MyMessage = {
-  role: "user" | "assistant";
-  content: string;
-};
-const backendApi = async (input: string): Promise<MyMessage> => {
-  return { role: "assistant", content: "Hello, world!" };
-};
+## Quickstart
+
+<Steps>
+<Step>
+
+### Install
+
+<InstallCommand npm={["@assistant-ui/react"]} />
+
+</Step>
+<Step>
+
+### Create the runtime provider
+
+```tsx title="app/MyRuntimeProvider.tsx"
+"use client";
 
-// ---cut---
 import { useState, ReactNode } from "react";
 import {
   useExternalStoreRuntime,
@@ -39,37 +53,33 @@ import {
   AssistantRuntimeProvider,
 } from "@assistant-ui/react";
 
-const convertMessage = (message: MyMessage): ThreadMessageLike => {
-  return {
-    role: message.role,
-    content: [{ type: "text", text: message.content }],
-  };
+type MyMessage = { role: "user" | "assistant"; content: string };
+
+const convertMessage = (message: MyMessage): ThreadMessageLike => ({
+  role: message.role,
+  content: [{ type: "text", text: message.content }],
+});
+
+const backendApi = async (input: string): Promise<MyMessage> => {
+  return { role: "assistant", content: "Hello, world!" };
 };
 
 export function MyRuntimeProvider({
   children,
-}: Readonly<{
-  children: ReactNode;
-}>) {
+}: Readonly<{ children: ReactNode }>) {
   const [isRunning, setIsRunning] = useState(false);
   const [messages, setMessages] = useState<MyMessage[]>([]);
 
   const onNew = async (message: AppendMessage) => {
-    if (message.content[0]?.type !== "text")
+    if (message.content[0]?.type !== "text") {
       throw new Error("Only text messages are supported");
-
+    }
     const input = message.content[0].text;
-    setMessages((currentConversation) => [
-      ...currentConversation,
-      { role: "user", content: input },
-    ]);
+    setMessages((prev) => [...prev, { role: "user", content: input }]);
 
     setIsRunning(true);
-    const assistantMessage = await backendApi(input);
-    setMessages((currentConversation) => [
-      ...currentConversation,
-      assistantMessage,
-    ]);
+    const assistant = await backendApi(input);
+    setMessages((prev) => [...prev, assistant]);
     setIsRunning(false);
   };
 
@@ -88,159 +98,32 @@ export function MyRuntimeProvider({
 }
 ```
 
-## When to Use
-
-Use `ExternalStoreRuntime` if you need:
-
-- **Full control over message state** - Manage messages with Redux, Zustand, TanStack Query, or any React state management library
-- **Custom multi-thread implementation** - Build your own thread management system with custom storage
-- **Integration with existing state** - Keep chat state in your existing state management solution
-- **Custom message formats** - Use your backend's message structure with automatic conversion
-- **Complex synchronization** - Sync messages with external data sources, databases, or multiple clients
-- **Custom persistence logic** - Implement your own storage patterns and caching strategies
-
-## Key Features
-
-<Cards>
-  <Card
-    title="State Management Integration"
-    description="Works seamlessly with Redux, Zustand, TanStack Query, and more"
-  />
-  <Card
-    title="Message Conversion"
-    description="Automatic conversion between your message format and assistant-ui's format"
-  />
-  <Card
-    title="Real-time Streaming"
-    description="Built-in support for streaming responses and progressive updates"
-  />
-  <Card
-    title="Thread Management"
-    description="Multi-conversation support with archiving and thread switching"
-  />
-</Cards>
-
-## Architecture
+</Step>
+<Step>
 
-### How It Works
+### Use in your app
 
-`ExternalStoreRuntime` acts as a bridge between your state management and assistant-ui:
+```tsx title="app/page.tsx"
+import { Thread } from "@/components/assistant-ui/thread";
+import { MyRuntimeProvider } from "./MyRuntimeProvider";
 
-```mermaid
-graph TD
-    A[Your State Management] -->|messages| B[ExternalStoreAdapter]
-    B --> C[ExternalStoreRuntime]
-    C --> D[assistant-ui Components]
-    D -->|user actions| B
-    B -->|state updates| A
+export default function Page() {
+  return (
+    <MyRuntimeProvider>
+      <Thread />
+    </MyRuntimeProvider>
+  );
+}
 ```
 
-### Key Concepts
-
-1. **State Ownership** - You own and control all message state
-2. **Adapter Pattern** - The adapter translates between your state and assistant-ui
-3. **Capability-Based Features** - UI features are enabled based on which handlers you provide
-4. **Message Conversion** - Automatic conversion between your message format and assistant-ui's format
-5. **Optimistic Updates** - Built-in handling for streaming and loading states
-
-## Getting Started
-
-<Steps>
-  <Step>
-    ### Install Dependencies
-
-    <InstallCommand npm={["@assistant-ui/react"]} />
-
-  </Step>
-
-  <Step>
-    ### Create Runtime Provider
-
-    ```tsx title="app/MyRuntimeProvider.tsx"
-    "use client";
-
-    import { ThreadMessageLike } from "@assistant-ui/react";
-    import { AppendMessage } from "@assistant-ui/react";
-    import {
-      AssistantRuntimeProvider,
-      useExternalStoreRuntime,
-    } from "@assistant-ui/react";
-    import { useState } from "react";
-
-    const convertMessage = (message: ThreadMessageLike, idx: number) => {
-      return message;
-    };
-
-    export function MyRuntimeProvider({
-      children,
-    }: Readonly<{
-      children: React.ReactNode;
-    }>) {
-      const [messages, setMessages] = useState<readonly ThreadMessageLike[]>([]);
-
-      const onNew = async (message: AppendMessage) => {
-        if (message.content.length !== 1 || message.content[0]?.type !== "text")
-          throw new Error("Only text content is supported");
-
-        const userMessage: ThreadMessageLike = {
-          role: "user",
-          content: [{ type: "text", text: message.content[0].text }],
-        };
-        setMessages((currentMessages) => [...currentMessages, userMessage]);
-
-        // normally you would perform an API call here to get the assistant response
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-
-        const assistantMessage: ThreadMessageLike = {
-          role: "assistant",
-          content: [{ type: "text", text: "Hello, world!" }],
-        };
-        setMessages((currentMessages) => [...currentMessages, assistantMessage]);
-      };
-
-      const runtime = useExternalStoreRuntime<ThreadMessageLike>({
-        messages,
-        setMessages,
-        onNew,
-        convertMessage,
-      });
-
-      return (
-        <AssistantRuntimeProvider runtime={runtime}>
-          {children}
-        </AssistantRuntimeProvider>
-      );
-    }
-    ```
-
-  </Step>
-
-  <Step>
-    ### Use in Your App
-
-    ```tsx title="app/page.tsx"
-    import { Thread } from "@/components/assistant-ui/thread";
-    import { MyRuntimeProvider } from "./MyRuntimeProvider";
-
-    export default function Page() {
-      return (
-        <MyRuntimeProvider>
-          <Thread />
-        </MyRuntimeProvider>
-      );
-    }
-    ```
-
-  </Step>
+</Step>
 </Steps>
 
-## Implementation Patterns
-
-### Message Conversion
+## Message conversion
 
-Two approaches for converting your message format:
+Two approaches.
 
-#### 1. Simple Conversion (Recommended)
+### Inline `convertMessage`
 
 ```tsx
 const convertMessage = (message: MyMessage): ThreadMessageLike => ({
@@ -257,9 +140,9 @@ const runtime = useExternalStoreRuntime({
 });
 ```
 
-#### 2. Advanced Conversion with `useExternalMessageConverter`
+### `useExternalMessageConverter` (with join strategy)
 
-For complex scenarios with performance optimization:
+For performance optimization or when you need to merge adjacent assistant messages:
 
 ```tsx
 import { useExternalMessageConverter } from "@assistant-ui/react";
@@ -269,98 +152,53 @@ const convertedMessages = useExternalMessageConverter({
     role: message.role,
     content: [{ type: "text", text: message.text }],
     id: message.id,
-    createdAt: new Date(message.timestamp),
   }),
   messages,
   isRunning: false,
-  joinStrategy: "concat-content", // Merge adjacent assistant messages
+  joinStrategy: "concat-content", // merges adjacent assistant messages
 });
 
 const runtime = useExternalStoreRuntime({
   messages: convertedMessages,
   onNew,
-  // No convertMessage needed - already converted
 });
 ```
 
-### Join Strategy
+`joinStrategy` controls how adjacent assistant messages combine: `concat-content` (default) merges them into one; `none` keeps them separate.
 
-Controls how adjacent assistant messages are combined:
+## Handler matrix
 
-- **`concat-content`** (default): Merges adjacent assistant messages into one
-- **`none`**: Keeps all messages separate
+Each handler enables a specific UI feature.
 
-This is useful when your backend sends multiple message chunks that should appear as a single message in the UI.
-
-<Callout type="info">
-  `useExternalMessageConverter` provides performance optimization for complex
-  message conversion scenarios. For simpler cases, consider using the basic
-  `convertMessage` approach shown above.
-</Callout>
+| Handler | Enables |
+| --- | --- |
+| `onNew` | Sending new user messages (required) |
+| `setMessages` | Branch switching |
+| `onEdit` | Message edit button |
+| `onReload` | Regenerate button |
+| `onCancel` | Cancel button while generating |
+| `onAddToolResult` | Client-side tool result handoff |
 
-### Essential Handlers
-
-#### Basic Chat (onNew only)
-
-```tsx
-const runtime = useExternalStoreRuntime({
-  messages,
-  onNew: async (message) => {
-    // Add user message to state
-    const userMsg = { role: "user", content: message.content };
-    setMessages([...messages, userMsg]);
-
-    // Get AI response
-    const response = await callAI(message);
-    setMessages([...messages, userMsg, response]);
-  },
-});
-```
+## Streaming responses
 
-#### Full-Featured Chat
-
-```tsx
-const runtime = useExternalStoreRuntime({
-  messages,
-  setMessages, // Enables branch switching
-  onNew, // Required
-  onEdit, // Enables message editing
-  onReload, // Enables regeneration
-  onCancel, // Enables cancellation
-});
-```
-
-<Callout type="info">
-  Each handler you provide enables specific UI features: - `setMessages` →
-  Branch switching - `onEdit` → Message editing - `onReload` → Regenerate button
-  - `onCancel` → Cancel button during generation
-</Callout>
-
-### Streaming Responses
-
-Implement real-time streaming with progressive updates:
+Stream by mutating the assistant message in place:
 
 ```tsx
 const onNew = async (message: AppendMessage) => {
-  // Add user message
-  const userMessage: ThreadMessageLike = {
+  const userMsg: ThreadMessageLike = {
     role: "user",
     content: message.content,
     id: generateId(),
   };
-  setMessages((prev) => [...prev, userMessage]);
+  setMessages((prev) => [...prev, userMsg]);
 
-  // Create placeholder for assistant message
   setIsRunning(true);
   const assistantId = generateId();
-  const assistantMessage: ThreadMessageLike = {
-    role: "assistant",
-    content: [{ type: "text", text: "" }],
-    id: assistantId,
-  };
-  setMessages((prev) => [...prev, assistantMessage]);
+  setMessages((prev) => [
+    ...prev,
+    { role: "assistant", content: [{ type: "text", text: "" }], id: assistantId },
+  ]);
 
-  // Stream response
   const stream = await api.streamChat(message);
   for await (const chunk of stream) {
     setMessages((prev) =>
@@ -369,10 +207,7 @@ const onNew = async (message: AppendMessage) => {
           ? {
               ...m,
               content: [
-                {
-                  type: "text",
-                  text: (m.content[0] as any).text + chunk,
-                },
+                { type: "text", text: (m.content[0] as any).text + chunk },
               ],
             }
           : m,
@@ -383,52 +218,30 @@ const onNew = async (message: AppendMessage) => {
 };
 ```
 
-### Message Editing
-
-Enable message editing by implementing the `onEdit` handler:
-
-<Callout type="info">
-  You can implement `onEdit(editedMessage)` to handle user-initiated edits in
-  your external store. This enables features like "edit and re-run" on your
-  backend.
-</Callout>
+## Message editing
 
 ```tsx
 const onEdit = async (message: AppendMessage) => {
-  // Find the index where to insert the edited message
   const index = messages.findIndex((m) => m.id === message.parentId) + 1;
-
-  // Keep messages up to the parent
   const newMessages = [...messages.slice(0, index)];
-
-  // Add the edited message
-  const editedMessage: ThreadMessageLike = {
+  newMessages.push({
     role: "user",
     content: message.content,
-    id: message.id || generateId(),
-  };
-  newMessages.push(editedMessage);
-
+    id: message.id ?? generateId(),
+  });
   setMessages(newMessages);
 
-  // Generate new response
   setIsRunning(true);
   const response = await api.chat(message);
-  newMessages.push({
-    role: "assistant",
-    content: response.content,
-    id: generateId(),
-  });
+  newMessages.push({ role: "assistant", content: response.content, id: generateId() });
   setMessages(newMessages);
   setIsRunning(false);
 };
 ```
 
-### Branching Support
+## Branching
 
-The `messages` array path assumes a linear conversation — each message's parent is the previous message. To support branching (e.g. regenerating responses creates alternative branches), use `ExportedMessageRepository.fromBranchableArray()` combined with `thread.import()`.
-
-Each message must have an explicit `id` and `parentId`. Messages with the same `parentId` create branches:
+The linear `messages` array assumes each message's parent is the previous one. For branching (e.g. multiple regenerations), use `ExportedMessageRepository.fromBranchableArray()` and import via `thread.import()`:
 
 ```tsx
 import {
@@ -436,60 +249,45 @@ import {
   useExternalStoreRuntime,
 } from "@assistant-ui/react";
 
-// Your messages from the backend, each with an id and parentId
 const backendMessages = [
   { id: "user-1", role: "user", content: "Hello", parentId: null },
   { id: "asst-1", role: "assistant", content: "Hi!", parentId: "user-1" },
-  // A second response to the same user message = a branch
-  { id: "asst-2", role: "assistant", content: "Hey!", parentId: "user-1" },
+  { id: "asst-2", role: "assistant", content: "Hey!", parentId: "user-1" }, // branch
 ];
 
-// Convert to ExportedMessageRepository
 const repo = ExportedMessageRepository.fromBranchableArray(
   backendMessages.map((m) => ({
     message: { id: m.id, role: m.role, content: m.content },
     parentId: m.parentId,
   })),
-  { headId: "asst-1" }, // which branch to display initially
+  { headId: "asst-1" },
 );
 
-// Import into the runtime
 runtime.thread.import(repo);
 ```
 
-<Callout type="warn">
-  Messages in the array must be ordered so that parents appear before their
-  children. Each message **must** have an `id` field set.
-</Callout>
+Each message must have an explicit `id` and `parentId`; messages with the same `parentId` create branches. Parents must appear before children in the array.
 
-### Tool Calling
+## Tool calling
 
-Support tool calls with proper result handling:
+Handle tool results by updating the matching tool-call entry:
 
 ```tsx
 const onAddToolResult = (options: AddToolResultOptions) => {
   setMessages((prev) =>
-    prev.map((message) => {
-      if (message.id === options.messageId) {
-        // Update the specific tool call with its result
-        return {
-          ...message,
-          content: message.content.map((part) => {
-            if (
+    prev.map((message) =>
+      message.id === options.messageId
+        ? {
+            ...message,
+            content: message.content.map((part) =>
               part.type === "tool-call" &&
               part.toolCallId === options.toolCallId
-            ) {
-              return {
-                ...part,
-                result: options.result,
-              };
-            }
-            return part;
-          }),
-        };
-      }
-      return message;
-    }),
+                ? { ...part, result: options.result }
+                : part,
+            ),
+          }
+        : message,
+    ),
   );
 };
 
@@ -497,336 +295,38 @@ const runtime = useExternalStoreRuntime({
   messages,
   onNew,
   onAddToolResult,
-  // ... other props
 });
 ```
 
-#### Automatic Tool Result Matching
+The runtime automatically matches tool results to their tool calls by `toolCallId` and groups related messages for display.
 
-The runtime automatically matches tool results with their corresponding tool calls. When messages are converted and joined:
+## Attachments
 
-1. **Tool Call Tracking** - The runtime tracks tool calls by their `toolCallId`
-2. **Result Association** - Tool results are automatically associated with their corresponding calls
-3. **Message Grouping** - Related tool messages are intelligently grouped together
+Attachments use the standard adapter contract, see [adapters](/docs/runtimes/concepts/adapters#attachment-adapter):
 
 ```tsx
-// Example: Tool call and result in separate messages
-const messages = [
-  {
-    role: "assistant",
-    content: [
-      {
-        type: "tool-call",
-        toolCallId: "call_123",
-        toolName: "get_weather",
-        args: { location: "San Francisco" },
-      },
-    ],
-  },
-  {
-    role: "tool",
-    content: [
-      {
-        type: "tool-result",
-        toolCallId: "call_123",
-        result: { temperature: 72, condition: "sunny" },
-      },
-    ],
-  },
-];
-
-// These are automatically matched and grouped by the runtime
-```
-
-### File Attachments
-
-Enable file uploads with the attachment adapter:
-
-```tsx
-const attachmentAdapter: AttachmentAdapter = {
-  accept: "image/*,application/pdf,.txt,.md",
-  async add({ file }) {
-    // Upload file to your server
-    const formData = new FormData();
-    formData.append("file", file);
-
-    const response = await fetch("/api/upload", {
-      method: "POST",
-      body: formData,
-    });
-
-    const { id } = await response.json();
-    return {
-      id,
-      type: "document",
-      name: file.name,
-      file,
-      status: { type: "requires-action", reason: "composer-send" },
-    };
-  },
-  async remove(attachment) {
-    // Remove file from server
-    await fetch(`/api/upload/${attachment.id}`, {
-      method: "DELETE",
-    });
-  },
-  async send(attachment) {
-    // Convert pending attachment to complete attachment when message is sent
-    return {
-      ...attachment,
-      status: { type: "complete" },
-      content: [{ type: "text", text: `File: ${attachment.name}` }],
-    };
-  },
-};
-
 const runtime = useExternalStoreRuntime({
   messages,
   onNew,
-  adapters: {
-    attachments: attachmentAdapter,
-  },
-});
-```
-
-### Thread Management
-
-#### Managing Thread Context
-
-When implementing multi-thread support with `ExternalStoreRuntime`, you need to carefully manage thread context across your application. Here's a comprehensive approach:
-
-```tsx
-// Create a context for thread management
-const ThreadContext = createContext<{
-  currentThreadId: string;
-  setCurrentThreadId: (id: string) => void;
-  threads: Map<string, ThreadMessageLike[]>;
-  setThreads: React.Dispatch<
-    React.SetStateAction<Map<string, ThreadMessageLike[]>>
-  >;
-}>({
-  currentThreadId: "default",
-  setCurrentThreadId: () => {},
-  threads: new Map(),
-  setThreads: () => {},
+  adapters: { attachments: myAttachmentAdapter },
 });
-
-// Thread provider component
-export function ThreadProvider({ children }: { children: ReactNode }) {
-  const [threads, setThreads] = useState<Map<string, ThreadMessageLike[]>>(
-    new Map([["default", []]]),
-  );
-  const [currentThreadId, setCurrentThreadId] = useState("default");
-
-  return (
-    <ThreadContext.Provider
-      value={{ currentThreadId, setCurrentThreadId, threads, setThreads }}
-    >
-      {children}
-    </ThreadContext.Provider>
-  );
-}
-
-// Hook for accessing thread context
-export function useThreadContext() {
-  const context = useContext(ThreadContext);
-  if (!context) {
-    throw new Error("useThreadContext must be used within ThreadProvider");
-  }
-  return context;
-}
 ```
 
-#### Complete Thread Implementation
-
-Here's a full implementation with proper context management:
-
-```tsx
-function ChatWithThreads() {
-  const { currentThreadId, setCurrentThreadId, threads, setThreads } =
-    useThreadContext();
-  const [threadList, setThreadList] = useState<ExternalStoreThreadData[]>([
-    { id: "default", status: "regular", title: "New Chat" },
-  ]);
-
-  // Get messages for current thread
-  const currentMessages = threads.get(currentThreadId) || [];
-
-  const threadListAdapter: ExternalStoreThreadListAdapter = {
-    threadId: currentThreadId,
-    threads: threadList.filter((t) => t.status === "regular"),
-    archivedThreads: threadList.filter((t) => t.status === "archived"),
-
-    onSwitchToNewThread: () => {
-      const newId = `thread-${Date.now()}`;
-      setThreadList((prev) => [
-        ...prev,
-        {
-          id: newId,
-          status: "regular",
-          title: "New Chat",
-        },
-      ]);
-      setThreads((prev) => new Map(prev).set(newId, []));
-      setCurrentThreadId(newId);
-    },
-
-    onSwitchToThread: (threadId) => {
-      setCurrentThreadId(threadId);
-    },
-
-    onRename: (threadId, newTitle) => {
-      setThreadList((prev) =>
-        prev.map((t) =>
-          t.id === threadId ? { ...t, title: newTitle } : t,
-        ),
-      );
-    },
-
-    onArchive: (threadId) => {
-      setThreadList((prev) =>
-        prev.map((t) =>
-          t.id === threadId ? { ...t, status: "archived" } : t,
-        ),
-      );
-    },
-
-    onDelete: (threadId) => {
-      setThreadList((prev) => prev.filter((t) => t.id !== threadId));
-      setThreads((prev) => {
-        const next = new Map(prev);
-        next.delete(threadId);
-        return next;
-      });
-      if (currentThreadId === threadId) {
-        setCurrentThreadId("default");
-      }
-    },
-  };
-
-  const runtime = useExternalStoreRuntime({
-    messages: currentMessages,
-    setMessages: (messages) => {
-      setThreads((prev) => new Map(prev).set(currentThreadId, messages));
-    },
-    onNew: async (message) => {
-      // Handle new message for current thread
-      // Your implementation here
-    },
-    adapters: {
-      threadList: threadListAdapter,
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <ThreadList />
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-
-// App component with proper context wrapping
-export function App() {
-  return (
-    <ThreadProvider>
-      <ChatWithThreads />
-    </ThreadProvider>
-  );
-}
-```
-
-#### Thread Context Best Practices
-
-<Callout type="info">
-  **Critical**: When using `ExternalStoreRuntime` with threads, the
-  `currentThreadId` must be consistent across all components and handlers.
-  Mismatched thread IDs will cause messages to appear in wrong threads or
-  disappear entirely.
-</Callout>
-
-1. **Centralize Thread State**: Always use a context or global state management solution to ensure thread ID consistency:
-
-```tsx
-// ❌ Bad: Local state in multiple components
-function ThreadList() {
-  const [currentThreadId, setCurrentThreadId] = useState("default");
-  // This won't sync with the runtime!
-}
-
-// ✅ Good: Shared context
-function ThreadList() {
-  const { currentThreadId, setCurrentThreadId } = useThreadContext();
-  // Thread ID is synchronized everywhere
-}
-```
-
-2. **Sync Thread Changes**: Ensure all thread-related operations update both the thread ID and messages:
-
-```tsx
-// ❌ Bad: Only updating thread ID
-onSwitchToThread: (threadId) => {
-  setCurrentThreadId(threadId);
-  // Messages won't update!
-};
-
-// ✅ Good: Complete state update
-onSwitchToThread: (threadId) => {
-  setCurrentThreadId(threadId);
-  // Messages automatically update via currentMessages = threads.get(currentThreadId)
-};
-```
-
-3. **Handle Edge Cases**: Always provide fallbacks for missing threads:
-
-```tsx
-// Ensure thread always exists
-const currentMessages = threads.get(currentThreadId) || [];
-
-// Initialize new threads properly
-const initializeThread = (threadId: string) => {
-  if (!threads.has(threadId)) {
-    setThreads((prev) => new Map(prev).set(threadId, []));
-  }
-};
-```
-
-4. **Persist Thread State**: For production apps, sync thread state with your backend:
-
-```tsx
-// Save thread state to backend
-useEffect(() => {
-  const saveThread = async () => {
-    await api.saveThread(currentThreadId, threads.get(currentThreadId) || []);
-  };
-
-  const debounced = debounce(saveThread, 1000);
-  debounced();
+## Multi-thread
 
-  return () => debounced.cancel();
-}, [currentThreadId, threads]);
-```
+`ExternalStoreRuntime` uses `ExternalStoreThreadListAdapter` (synchronous, inline). See [threads](/docs/runtimes/concepts/threads#externalstorethreadlistadapter) for the contract and best practices on keeping `currentThreadId` in sync with your store.
 
-## Integration Examples
+## Integration examples
 
-### Redux Integration
+### Redux
 
 ```tsx title="app/chatSlice.ts"
-// Using Redux Toolkit (recommended)
 import { createSlice, PayloadAction } from "@reduxjs/toolkit";
 import { ThreadMessageLike } from "@assistant-ui/react";
 
-interface ChatState {
-  messages: ThreadMessageLike[];
-  isRunning: boolean;
-}
-
 const chatSlice = createSlice({
   name: "chat",
-  initialState: {
-    messages: [] as ThreadMessageLike[],
-    isRunning: false,
-  },
+  initialState: { messages: [] as ThreadMessageLike[], isRunning: false },
   reducers: {
     setMessages: (state, action: PayloadAction<ThreadMessageLike[]>) => {
       state.messages = action.payload;
@@ -841,23 +341,15 @@ const chatSlice = createSlice({
 });
 
 export const { setMessages, addMessage, setIsRunning } = chatSlice.actions;
-export const selectMessages = (state: RootState) => state.chat.messages;
-export const selectIsRunning = (state: RootState) => state.chat.isRunning;
-export default chatSlice.reducer;
+```
 
-// ReduxRuntimeProvider.tsx
+```tsx title="app/ReduxRuntimeProvider.tsx"
 import { useSelector, useDispatch } from "react-redux";
-import {
-  selectMessages,
-  selectIsRunning,
-  addMessage,
-  setMessages,
-  setIsRunning,
-} from "./chatSlice";
+import { useExternalStoreRuntime, AssistantRuntimeProvider } from "@assistant-ui/react";
 
 export function ReduxRuntimeProvider({ children }) {
-  const messages = useSelector(selectMessages);
-  const isRunning = useSelector(selectIsRunning);
+  const messages = useSelector((s: RootState) => s.chat.messages);
+  const isRunning = useSelector((s: RootState) => s.chat.isRunning);
   const dispatch = useDispatch();
 
   const runtime = useExternalStoreRuntime({
@@ -865,7 +357,6 @@ export function ReduxRuntimeProvider({ children }) {
     isRunning,
     setMessages: (messages) => dispatch(setMessages(messages)),
     onNew: async (message) => {
-      // Add user message
       dispatch(
         addMessage({
           role: "user",
@@ -874,8 +365,6 @@ export function ReduxRuntimeProvider({ children }) {
           createdAt: new Date(),
         }),
       );
-
-      // Generate response
       dispatch(setIsRunning(true));
       const response = await api.chat(message);
       dispatch(
@@ -898,10 +387,9 @@ export function ReduxRuntimeProvider({ children }) {
 }
 ```
 
-### Zustand Integration (v5)
+### Zustand
 
 ```tsx title="app/chatStore.ts"
-// Using Zustand v5 with TypeScript
 import { create } from "zustand";
 import { immer } from "zustand/middleware/immer";
 import { ThreadMessageLike } from "@assistant-ui/react";
@@ -912,53 +400,32 @@ interface ChatState {
   addMessage: (message: ThreadMessageLike) => void;
   setMessages: (messages: ThreadMessageLike[]) => void;
   setIsRunning: (isRunning: boolean) => void;
-  updateMessage: (id: string, updates: Partial<ThreadMessageLike>) => void;
 }
 
-// Zustand v5 requires the extra parentheses for TypeScript
-const useChatStore = create<ChatState>()(
+export const useChatStore = create<ChatState>()(
   immer((set) => ({
     messages: [],
     isRunning: false,
-
-    addMessage: (message) =>
-      set((state) => {
-        state.messages.push(message);
-      }),
-
-    setMessages: (messages) =>
-      set((state) => {
-        state.messages = messages;
-      }),
-
-    setIsRunning: (isRunning) =>
-      set((state) => {
-        state.isRunning = isRunning;
-      }),
-
-    updateMessage: (id, updates) =>
-      set((state) => {
-        const index = state.messages.findIndex((m) => m.id === id);
-        if (index !== -1) {
-          Object.assign(state.messages[index], updates);
-        }
-      }),
+    addMessage: (message) => set((s) => { s.messages.push(message); }),
+    setMessages: (messages) => set((s) => { s.messages = messages; }),
+    setIsRunning: (isRunning) => set((s) => { s.isRunning = isRunning; }),
   })),
 );
+```
 
-// ZustandRuntimeProvider.tsx
+```tsx title="app/ZustandRuntimeProvider.tsx"
 import { useShallow } from "zustand/shallow";
+import { useExternalStoreRuntime, AssistantRuntimeProvider } from "@assistant-ui/react";
 
 export function ZustandRuntimeProvider({ children }) {
-  // Use useShallow to prevent unnecessary re-renders
   const { messages, isRunning, addMessage, setMessages, setIsRunning } =
     useChatStore(
-      useShallow((state) => ({
-        messages: state.messages,
-        isRunning: state.isRunning,
-        addMessage: state.addMessage,
-        setMessages: state.setMessages,
-        setIsRunning: state.setIsRunning,
+      useShallow((s) => ({
+        messages: s.messages,
+        isRunning: s.isRunning,
+        addMessage: s.addMessage,
+        setMessages: s.setMessages,
+        setIsRunning: s.setIsRunning,
       })),
     );
 
@@ -967,21 +434,18 @@ export function ZustandRuntimeProvider({ children }) {
     isRunning,
     setMessages,
     onNew: async (message) => {
-      // Add user message
       addMessage({
         role: "user",
         content: message.content,
         id: `msg-${Date.now()}`,
         createdAt: new Date(),
       });
-
-      // Generate response
       setIsRunning(true);
       const response = await api.chat(message);
       addMessage({
         role: "assistant",
         content: response.content,
-        id: `msg-${Date.now()}-assistant`,
+        id: `msg-${Date.now()}-a`,
         createdAt: new Date(),
       });
       setIsRunning(false);
@@ -996,98 +460,56 @@ export function ZustandRuntimeProvider({ children }) {
 }
 ```
 
-### TanStack Query Integration
+### TanStack Query
 
-```tsx title="app/chatQueries.ts"
-// Using TanStack Query v5 with TypeScript
+```tsx
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { ThreadMessageLike, AppendMessage } from "@assistant-ui/react";
+import { useExternalStoreRuntime } from "@assistant-ui/react";
 
-// Query key factory pattern
-export const messageKeys = {
+const messageKeys = {
   all: ["messages"] as const,
   thread: (threadId: string) => [...messageKeys.all, threadId] as const,
 };
 
-// TanStackQueryRuntimeProvider.tsx
 export function TanStackQueryRuntimeProvider({ children }) {
   const queryClient = useQueryClient();
-  const threadId = "main"; // Or from context/props
+  const threadId = "main";
 
   const { data: messages = [] } = useQuery({
     queryKey: messageKeys.thread(threadId),
     queryFn: () => fetchMessages(threadId),
-    staleTime: 1000 * 60 * 5, // Consider data fresh for 5 minutes
   });
 
   const sendMessage = useMutation({
     mutationFn: api.chat,
-
-    // Optimistic updates with proper TypeScript types
     onMutate: async (message: AppendMessage) => {
-      // Cancel any outgoing refetches
       await queryClient.cancelQueries({
         queryKey: messageKeys.thread(threadId),
       });
-
-      // Snapshot the previous value
-      const previousMessages = queryClient.getQueryData<ThreadMessageLike[]>(
-        messageKeys.thread(threadId),
-      );
-
-      // Optimistically update with typed data
-      const optimisticMessage: ThreadMessageLike = {
-        role: "user",
-        content: message.content,
-        id: `temp-${Date.now()}`,
-        createdAt: new Date(),
-      };
-
-      queryClient.setQueryData<ThreadMessageLike[]>(
+      const previous = queryClient.getQueryData<ThreadMessageLike[]>(
         messageKeys.thread(threadId),
-        (old = []) => [...old, optimisticMessage],
       );
-
-      return { previousMessages, tempId: optimisticMessage.id };
-    },
-
-    onSuccess: (response, variables, context) => {
-      // Replace optimistic message with real data
       queryClient.setQueryData<ThreadMessageLike[]>(
         messageKeys.thread(threadId),
-        (old = []) => {
-          // Remove temp message and add real ones
-          return old
-            .filter((m) => m.id !== context?.tempId)
-            .concat([
-              {
-                role: "user",
-                content: variables.content,
-                id: `user-${Date.now()}`,
-                createdAt: new Date(),
-              },
-              response,
-            ]);
-        },
+        (old = []) => [
+          ...old,
+          {
+            role: "user",
+            content: message.content,
+            id: `temp-${Date.now()}`,
+            createdAt: new Date(),
+          },
+        ],
       );
+      return { previous };
     },
-
-    onError: (error, variables, context) => {
-      // Rollback to previous messages on error
-      if (context?.previousMessages) {
-        queryClient.setQueryData(
-          messageKeys.thread(threadId),
-          context.previousMessages,
-        );
+    onError: (_err, _msg, context) => {
+      if (context?.previous) {
+        queryClient.setQueryData(messageKeys.thread(threadId), context.previous);
       }
     },
-
-    onSettled: () => {
-      // Always refetch after error or success
-      queryClient.invalidateQueries({
-        queryKey: messageKeys.thread(threadId),
-      });
-    },
+    onSettled: () =>
+      queryClient.invalidateQueries({ queryKey: messageKeys.thread(threadId) }),
   });
 
   const runtime = useExternalStoreRuntime({
@@ -1096,7 +518,6 @@ export function TanStackQueryRuntimeProvider({ children }) {
     onNew: async (message) => {
       await sendMessage.mutateAsync(message);
     },
-    // Enable message editing
     setMessages: (newMessages) => {
       queryClient.setQueryData(messageKeys.thread(threadId), newMessages);
     },
@@ -1110,103 +531,28 @@ export function TanStackQueryRuntimeProvider({ children }) {
 }
 ```
 
-## Key Features
-
-### Automatic Optimistic Updates
-
-When `isRunning` becomes true, the runtime automatically shows an optimistic assistant message:
-
-```tsx
-// Your code
-setIsRunning(true);
-
-// Runtime automatically:
-// 1. Shows empty assistant message with { type: "running" } status
-// 2. Displays typing indicator
-// 3. Updates status to { type: "complete", reason: "unknown" } when isRunning becomes false
-```
-
-### Message Status Management
+## Working with external messages
 
-Assistant messages get automatic status updates:
+### `getExternalStoreMessages`
 
-- `{ type: "running" }` - When `isRunning` is true
-- `{ type: "complete", reason: "unknown" }` - When `isRunning` becomes false
-- `{ type: "incomplete", reason: "cancelled" }` - When cancelled via `onCancel`
-
-### Tool Result Matching
-
-The runtime automatically matches tool results with their calls:
-
-```tsx
-// Tool call and result can be in separate messages
-const messages = [
-  {
-    role: "assistant",
-    content: [
-      {
-        type: "tool-call",
-        toolCallId: "call_123",
-        toolName: "get_weather",
-        args: { location: "SF" },
-      },
-    ],
-  },
-  {
-    role: "tool",
-    content: [
-      {
-        type: "tool-result",
-        toolCallId: "call_123",
-        result: { temp: 72 },
-      },
-    ],
-  },
-];
-// Runtime automatically associates these
-```
-
-## Working with External Messages
-
-### Converting Back to Your Format
-
-Use `getExternalStoreMessages` to access your original messages:
+Retrieve your original message format from any assistant-ui state:
 
 ```tsx
-import { getExternalStoreMessages } from "@assistant-ui/react";
+import { getExternalStoreMessages, useAuiState } from "@assistant-ui/react";
 
-const MyComponent = () => {
+function MyComponent() {
   const originalMessages = useAuiState((s) => getExternalStoreMessages(s.message));
   // originalMessages is MyMessage[] (your original type)
-};
+}
 ```
 
-<Callout type="info">
-  After the chat finishes, use `getExternalStoreMessages(runtime)` to convert
-  back to your domain model. Refer to the API reference for return structures
-  and edge-case behaviors.
-</Callout>
-
-<Callout type="warning">
-  `getExternalStoreMessages` may return multiple messages for a single UI
-  message. This happens because assistant-ui merges adjacent assistant and tool
-  messages for display.
+<Callout type="warn">
+`getExternalStoreMessages` may return multiple messages for a single UI message; assistant-ui merges adjacent assistant and tool messages for display.
 </Callout>
 
-### Message part Access
-
-```tsx
-const ToolUI = makeAssistantToolUI({
-  render: () => {
-    const originalMessages = useAuiState((s) => getExternalStoreMessages(s.part));
-    // Access original message data for this message part
-  },
-});
-```
-
-### Binding External Messages Manually
+### `bindExternalStoreMessage`
 
-Use `bindExternalStoreMessage` to attach your original message to a `ThreadMessage` or message part object. This is useful when you construct `ThreadMessage` objects yourself (outside of the built-in message converter) and want `getExternalStoreMessages` to work with them.
+Attach your original message to a `ThreadMessage` you constructed manually (outside the built-in converter):
 
 ```tsx
 import {
@@ -1214,574 +560,245 @@ import {
   getExternalStoreMessages,
 } from "@assistant-ui/react";
 
-// Attach your original message to a ThreadMessage
 bindExternalStoreMessage(threadMessage, originalMessage);
-
-// Later, retrieve it
 const original = getExternalStoreMessages(threadMessage);
 ```
 
+`bindExternalStoreMessage` is a no-op if the target already has a bound message. It mutates the target in place.
+
 <Callout type="warn">
-  This API is experimental and may change without notice.
+This API is experimental and may change without notice.
 </Callout>
 
-`bindExternalStoreMessage` is a no-op if the target already has a bound message. It mutates the target object in place.
-
-## Debugging
-
-### Common Debugging Scenarios
-
-```tsx
-// Debug message conversion
-const convertMessage = (message: MyMessage): ThreadMessageLike => {
-  console.log("Converting message:", message);
-  const converted = {
-    role: message.role,
-    content: [{ type: "text", text: message.content }],
-  };
-  console.log("Converted to:", converted);
-  return converted;
-};
-
-// Debug adapter calls
-const onNew = async (message: AppendMessage) => {
-  console.log("onNew called with:", message);
-  // ... implementation
-};
-
-// Enable verbose logging
-const runtime = useExternalStoreRuntime({
-  messages,
-  onNew: (...args) => {
-    console.log("Runtime onNew:", args);
-    return onNew(...args);
-  },
-  // ... other props
-});
-```
+## Best practices
 
-## Best Practices
+1. **Immutable updates.** Always create new arrays:
+   ```tsx
+   setMessages([...messages, newMessage]); // not messages.push(newMessage)
+   ```
+2. **Stable handler references.** Memoize `onNew`, `onEdit`, etc. with `useCallback` to avoid recreating the runtime.
+3. **Use `useShallow`** with zustand to prevent unnecessary re-renders.
 
-### 1. Immutable Updates
+## Common pitfalls
 
-Always create new arrays when updating messages:
+**Edit / regenerate / cancel buttons missing.** Each requires its handler:
 
 ```tsx
-// ❌ Wrong - mutating array
-messages.push(newMessage);
-setMessages(messages);
-
-// ✅ Correct - new array
-setMessages([...messages, newMessage]);
-```
-
-### 2. Stable Handler References
-
-Memoize handlers to prevent runtime recreation:
-
-```tsx
-const onNew = useCallback(
-  async (message: AppendMessage) => {
-    // Handle new message
-  },
-  [
-    /* dependencies */
-  ],
-);
-
-const runtime = useExternalStoreRuntime({
+useExternalStoreRuntime({
   messages,
-  onNew, // Stable reference
+  onNew, // required
+  setMessages, // branch switching
+  onEdit, // edit
+  onReload, // regenerate
+  onCancel, // cancel
 });
 ```
 
-### 3. Performance Optimization
-
-```tsx
-// For large message lists
-const recentMessages = useMemo(
-  () => messages.slice(-50), // Show last 50 messages
-  [messages],
-);
-
-// For expensive conversions
-const convertMessage = useCallback((msg) => {
-  // Conversion logic
-}, []);
-```
-
-## `LocalRuntime` vs `ExternalStoreRuntime`
-
-### When to Choose Which
-
-| Scenario                         | Recommendation                                               |
-| -------------------------------- | ------------------------------------------------------------ |
-| Quick prototype                  | `LocalRuntime`                                               |
-| Using Redux/Zustand              | `ExternalStoreRuntime`                                       |
-| Need Assistant Cloud integration | `LocalRuntime`                                               |
-| Custom thread storage            | Both (`LocalRuntime` with adapter or `ExternalStoreRuntime`) |
-| Simple single thread             | `LocalRuntime`                                               |
-| Complex state logic              | `ExternalStoreRuntime`                                       |
-
-### Feature Comparison
-
-| Feature          | `LocalRuntime`              | `ExternalStoreRuntime` |
-| ---------------- | --------------------------- | ---------------------- |
-| State Management | Built-in                    | You provide            |
-| Multi-thread     | Via Cloud or custom adapter | Via adapter            |
-| Message Format   | ThreadMessage               | Any (with conversion)  |
-| Setup Complexity | Low                         | Medium                 |
-| Flexibility      | Medium                      | High                   |
-
-## Common Pitfalls
-
-<Callout type="error">
-**Features not appearing**: Each UI feature requires its corresponding handler:
-
-```tsx
-// ❌ No edit button
-const runtime = useExternalStoreRuntime({ messages, onNew });
-
-// ✅ Edit button appears
-const runtime = useExternalStoreRuntime({ messages, onNew, onEdit });
-```
-
-</Callout>
-
-<Callout type="warning">
-
-**State not updating**: Common causes:
-
-1. Mutating arrays instead of creating new ones
-2. Missing `setMessages` for branch switching
-3. Not handling async operations properly
-4. Incorrect message format conversion
-
-</Callout>
-
-### Debugging Checklist
-
-- Are you creating new arrays when updating messages?
-- Did you provide all required handlers for desired features?
-- Is your `convertMessage` returning valid `ThreadMessageLike`?
-- Are you properly handling `isRunning` state?
-- For threads: Is your thread list adapter complete?
-
-### Thread-Specific Debugging
-
-Common thread context issues and solutions:
-
-**Messages disappearing when switching threads:**
-
-```tsx
-// Check 1: Ensure currentThreadId is consistent
-console.log("Runtime threadId:", threadListAdapter.threadId);
-console.log("Current threadId:", currentThreadId);
-console.log("Messages for thread:", threads.get(currentThreadId));
-
-// Check 2: Verify setMessages uses correct thread
-setMessages: (messages) => {
-  console.log("Setting messages for thread:", currentThreadId);
-  setThreads((prev) => new Map(prev).set(currentThreadId, messages));
-};
-```
-
-**Thread list not updating:**
+**State not updating.** check for: array mutation instead of new arrays, missing `setMessages`, broken async handling, or invalid `convertMessage` output.
 
-```tsx
-// Ensure threadList state is properly managed
-onSwitchToNewThread: () => {
-  const newId = `thread-${Date.now()}`;
-  console.log("Creating new thread:", newId);
-
-  // All three updates must happen together
-  setThreadList((prev) => [...prev, newThreadData]);
-  setThreads((prev) => new Map(prev).set(newId, []));
-  setCurrentThreadId(newId);
-};
-```
-
-**Messages going to wrong thread:**
-
-```tsx
-// Add validation to prevent race conditions
-const validateThreadContext = () => {
-  const runtimeThread = threadListAdapter.threadId;
-  const contextThread = currentThreadId;
-
-  if (runtimeThread !== contextThread) {
-    console.error("Thread mismatch!", { runtimeThread, contextThread });
-    throw new Error("Thread context mismatch");
-  }
-};
-
-// Call before any message operation
-onNew: async (message) => {
-  validateThreadContext();
-  // ... handle message
-};
-```
+**Messages going to the wrong thread.** the runtime's `currentThreadId` and your store's selected thread must stay in sync. Centralize thread id in a context, never in component-local state. See [threads](/docs/runtimes/concepts/threads#externalstorethreadlistadapter).
 
-## API Reference
+## API reference
 
 ### `ExternalStoreAdapter`
 
-The main interface for connecting your state to assistant-ui.
-
 <ParametersTable
   type="ExternalStoreAdapter<T>"
   parameters={[
     {
       name: "messages",
       type: "readonly T[]",
-      description: "Array of messages from your state",
+      description: "Array of messages from your state.",
       required: true,
     },
     {
       name: "onNew",
       type: "(message: AppendMessage) => Promise<void>",
-      description: "Handler for new messages from the user",
+      description: "Handler for new messages from the user.",
       required: true,
     },
     {
       name: "isRunning",
       type: "boolean",
       description:
-        "Whether the assistant is currently generating a response. When true, shows optimistic assistant message",
+        "Whether the assistant is currently generating a response. When true, shows an optimistic assistant message and flows directly to thread.isRunning.",
       default: "false",
     },
     {
       name: "isDisabled",
       type: "boolean",
-      description: "Whether the chat input should be disabled",
+      description: "Whether the chat input should be disabled.",
       default: "false",
     },
+    {
+      name: "isLoading",
+      type: "boolean",
+      description:
+        "Whether the adapter is in a loading state. Displays a loading indicator instead of the composer.",
+    },
     {
       name: "suggestions",
       type: "readonly ThreadSuggestion[]",
-      description: "Suggested prompts to display",
+      description: "Suggested prompts to display.",
     },
     {
       name: "extras",
       type: "unknown",
-      description: "Additional data accessible via runtime.extras",
+      description: "Additional data accessible via runtime.extras.",
     },
     {
       name: "setMessages",
       type: "(messages: readonly T[]) => void",
-      description: "Update messages (required for branch switching)",
+      description: "Update messages (required for branch switching).",
     },
     {
       name: "onEdit",
       type: "(message: AppendMessage) => Promise<void>",
-      description: "Handler for message edits (required for edit feature)",
+      description: "Handler for message edits (required for edit feature).",
     },
     {
       name: "onReload",
-      type: "(parentId: string | null, config: StartRunConfig) => Promise<void>",
+      type: "(parentId: string | Null, config: StartRunConfig) => Promise<void>",
       description:
-        "Handler for regenerating messages (required for reload feature)",
+        "Handler for regenerating messages (required for reload feature).",
     },
     {
       name: "onCancel",
       type: "() => Promise<void>",
-      description: "Handler for cancelling the current generation",
+      description: "Handler for cancelling the current generation.",
     },
     {
       name: "onAddToolResult",
-      type: "(options: AddToolResultOptions) => Promise<void> | void",
-      description: "Handler for adding tool call results",
+      type: "(options: AddToolResultOptions) => Promise<void> | Void",
+      description: "Handler for adding tool call results.",
     },
     {
       name: "onResume",
       type: "(config: ResumeRunConfig) => Promise<void>",
       description:
-        "Handler for resuming an interrupted run (e.g. after a page reload mid-generation)",
+        "Handler for resuming an interrupted run (e.g. after a page reload mid-generation).",
     },
     {
       name: "onResumeToolCall",
       type: "(options: { toolCallId: string; payload: unknown }) => void",
       description:
-        "Handler for resuming a suspended tool call (used with human-in-the-loop tool execution)",
-    },
-    {
-      name: "isLoading",
-      type: "boolean",
-      description:
-        "Whether the adapter is in a loading state (e.g. initial data fetch). Displays a loading indicator instead of the composer",
+        "Handler for resuming a suspended tool call (used with human-in-the-loop tool execution).",
     },
     {
       name: "messageRepository",
       type: "ExportedMessageRepository",
       description:
-        "Pre-built message repository with branching history. Use instead of `messages` when you need to restore branch state",
+        "Pre-built message repository with branching history. Use instead of messages when you need to restore branch state.",
     },
     {
       name: "state",
       type: "ReadonlyJSONValue",
       description:
-        "Opaque serializable state passed to `onLoadExternalState` during thread import",
+        "Opaque serializable state passed to onLoadExternalState during thread import.",
     },
     {
       name: "onImport",
       type: "(messages: readonly ThreadMessage[]) => void",
       description:
-        "Called when the runtime imports messages into the external store (e.g. on thread switch)",
+        "Called when the runtime imports messages into the external store (e.g. on thread switch).",
     },
     {
       name: "onExportExternalState",
       type: "() => any",
       description:
-        "Called to retrieve external state when the runtime exports a thread snapshot",
+        "Called to retrieve external state when the runtime exports a thread snapshot.",
     },
     {
       name: "onLoadExternalState",
       type: "(state: any) => void",
       description:
-        "Called with previously exported external state when restoring a thread snapshot",
+        "Called with previously exported external state when restoring a thread snapshot.",
     },
     {
       name: "convertMessage",
       type: "(message: T, index: number) => ThreadMessageLike",
       description:
-        "Convert your message format to assistant-ui format. Not needed if using ThreadMessage type",
+        "Convert your message format to assistant-ui format. Not needed if using ThreadMessage type.",
     },
     {
       name: "adapters",
       type: "object",
-      description: "Feature adapters (same as LocalRuntime)",
-      children: [
-        {
-          type: "adapters",
-          parameters: [
-            {
-              name: "attachments",
-              type: "AttachmentAdapter",
-              description: "Enable file attachments",
-            },
-            {
-              name: "speech",
-              type: "SpeechSynthesisAdapter",
-              description: "Enable text-to-speech",
-            },
-            {
-              name: "dictation",
-              type: "DictationAdapter",
-              description: "Enable speech-to-text dictation",
-            },
-            {
-              name: "feedback",
-              type: "FeedbackAdapter",
-              description: "Enable message feedback",
-            },
-            {
-              name: "threadList",
-              type: "ExternalStoreThreadListAdapter",
-              description: "Enable multi-thread management",
-            },
-          ],
-        },
-      ],
+      description:
+        "Capability adapters: attachments, speech, dictation, feedback, threadList. See /docs/runtimes/concepts/adapters.",
     },
     {
       name: "unstable_capabilities",
       type: "object",
-      description: "Configure runtime capabilities",
-      children: [
-        {
-          type: "unstable_capabilities",
-          parameters: [
-            {
-              name: "copy",
-              type: "boolean",
-              description: "Enable message copy feature",
-              default: "true",
-            },
-          ],
-        },
-      ],
+      description:
+        "Configure runtime capabilities (e.g. copy). Unstable, may change.",
     },
   ]}
 />
 
 ### `ThreadMessageLike`
 
-A flexible message format that can be converted to assistant-ui's internal format.
-
 <ParametersTable
   type="ThreadMessageLike"
   parameters={[
     {
       name: "role",
       type: '"assistant" | "user" | "system"',
-      description: "The role of the message sender",
+      description: "The role of the message sender.",
       required: true,
     },
     {
       name: "content",
-      type: "string | readonly MessagePart[]",
-      description: "Message content as string or structured message parts. Supports `data-*` prefixed types (e.g. `{ type: \"data-workflow\", data: {...} }`) which are automatically converted to DataMessagePart.",
+      type: "string | Readonly MessagePart[]",
+      description:
+        "Message content as string or structured message parts. Supports data-* prefixed types (e.g. { type: \"data-workflow\", data: {...} }) which are automatically converted to DataMessagePart.",
       required: true,
     },
     {
       name: "id",
       type: "string",
-      description: "Unique identifier for the message",
+      description: "Unique identifier for the message.",
     },
     {
       name: "createdAt",
       type: "Date",
-      description: "Timestamp when the message was created",
+      description: "Timestamp when the message was created.",
     },
     {
       name: "status",
       type: "MessageStatus",
       description:
-        "Status of assistant messages ({ type: \"running\" }, { type: \"complete\" }, { type: \"incomplete\" })",
+        'Status of assistant messages ({ type: "running" }, { type: "complete" }, { type: "incomplete" }).',
     },
     {
       name: "attachments",
       type: "readonly CompleteAttachment[]",
-      description: "File attachments (user messages only). Attachment `type` accepts custom strings beyond \"image\" | \"document\" | \"file\", and `contentType` is optional.",
+      description:
+        'File attachments (user messages only). Type accepts custom strings beyond "image" | "document" | "file"; contentType is optional.',
     },
     {
       name: "metadata",
       type: "object",
-      description: "Additional message metadata",
-      children: [
-        {
-          type: "metadata",
-          parameters: [
-            {
-              name: "steps",
-              type: "readonly ThreadStep[]",
-              description: "Tool call steps for assistant messages",
-            },
-            {
-              name: "custom",
-              type: "Record<string, unknown>",
-              description: "Custom metadata for your application",
-            },
-          ],
-        },
-      ],
+      description: "Additional message metadata (steps, custom fields).",
     },
   ]}
 />
 
-### `ExternalStoreThreadListAdapter`
-
-Enable multi-thread support with custom thread management.
+## Related
 
-<ParametersTable
-  type="ExternalStoreThreadListAdapter"
-  parameters={[
-    {
-      name: "threadId",
-      type: "string",
-      description:
-        "ID of the current active thread. **Deprecated** — this API is still under active development and might change without notice.",
-    },
-    {
-      name: "isLoading",
-      type: "boolean",
-      description: "Whether the thread list is currently loading",
-    },
-    {
-      name: "threads",
-      type: "readonly ExternalStoreThreadData<\"regular\">[]",
-      description: "Array of active threads. Each entry is an `ExternalStoreThreadData` object.",
-    },
-    {
-      name: "archivedThreads",
-      type: "readonly ExternalStoreThreadData<\"archived\">[]",
-      description: "Array of archived threads. Each entry is an `ExternalStoreThreadData` object.",
-    },
-    {
-      name: "onSwitchToNewThread",
-      type: "() => Promise<void> | void",
-      description:
-        "Handler for creating a new thread. **Deprecated** — this API is still under active development and might change without notice.",
-    },
-    {
-      name: "onSwitchToThread",
-      type: "(threadId: string) => Promise<void> | void",
-      description:
-        "Handler for switching to an existing thread. **Deprecated** — this API is still under active development and might change without notice.",
-    },
-    {
-      name: "onRename",
-      type: "(threadId: string, newTitle: string) => Promise<void> | void",
-      description: "Handler for renaming a thread",
-    },
-    {
-      name: "onArchive",
-      type: "(threadId: string) => Promise<void> | void",
-      description: "Handler for archiving a thread",
-    },
-    {
-      name: "onUnarchive",
-      type: "(threadId: string) => Promise<void> | void",
-      description: "Handler for unarchiving a thread",
-    },
-    {
-      name: "onDelete",
-      type: "(threadId: string) => Promise<void> | void",
-      description: "Handler for deleting a thread",
-    },
-  ]}
-/>
-
-<Callout type="info">
-  The thread list adapter enables multi-thread support. Without it, the runtime
-  only manages the current conversation.
-</Callout>
-
-### `ExternalStoreThreadData`
-
-Represents a single thread entry in the thread list.
-
-<ParametersTable
-  type="ExternalStoreThreadData<TState>"
-  parameters={[
-    {
-      name: "id",
-      type: "string",
-      description: "Unique local identifier for the thread",
-      required: true,
-    },
-    {
-      name: "status",
-      type: '"regular" | "archived"',
-      description: "Whether the thread is active or archived",
-      required: true,
-    },
-    {
-      name: "title",
-      type: "string",
-      description: "Display title for the thread",
-    },
-    {
-      name: "remoteId",
-      type: "string",
-      description: "Remote/server-side identifier for the thread (used for persistence)",
-    },
-    {
-      name: "externalId",
-      type: "string",
-      description: "External system identifier for the thread (e.g. from a third-party service)",
-    },
-  ]}
-/>
-
-### Related Runtime APIs
-
-- [AssistantRuntime API](/docs/api-reference/runtimes/assistant-runtime) - Core runtime interface and methods
-- [ThreadRuntime API](/docs/api-reference/runtimes/thread-runtime) - Thread-specific operations and state management
-- [Runtime Providers](/docs/api-reference/context-providers/assistant-runtime-provider) - Context providers for runtime integration
-
-## Related Resources
-
-- [Pick a Runtime Guide](/docs/runtimes/pick-a-runtime)
-- [`LocalRuntime` Documentation](/docs/runtimes/custom/local)
-- [Examples Repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-external-store)
+<Cards>
+  <Card
+    title="LocalRuntime"
+    description="Simpler core runtime when you do not have your own state store."
+    href="/docs/runtimes/custom/local-runtime"
+  />
+  <Card
+    title="Adapters"
+    description="Attachments, speech, feedback, history, suggestions."
+    href="/docs/runtimes/concepts/adapters"
+  />
+  <Card
+    title="Threads"
+    description="ExternalStoreThreadListAdapter for multi-thread."
+    href="/docs/runtimes/concepts/threads"
+  />
+</Cards>