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

package/.docs/raw/docs/{(docs)/guides → guides}/context-api.mdx

@@ -1,6 +1,7 @@
 ---
 title: Context API
 description: Read and update assistant state to build custom components.
+platforms: ["react"]
 ---
 
 The Context API provides direct access to assistant-ui's state management system, enabling you to build custom components that integrate seamlessly with the assistant runtime.
@@ -211,6 +212,8 @@ aui.attachment().getState();
 // ThreadList actions
 aui.threads().switchToNewThread();
 aui.threads().switchToThread(threadId);
+aui.threads().reload();
+await aui.threads().getLoadThreadsPromise();
 aui.threads().getState();
 
 // ThreadListItem actions
@@ -233,9 +236,9 @@ aui.chainOfThought().getState();
 aui.chainOfThought().setCollapsed(collapsed);
 aui.chainOfThought().part({ index: 0 });
 
-// ModelContext actions
-aui.modelContext().getState();
+// ModelContext actions — see /docs/copilots/model-context for full usage
 aui.modelContext().register(provider);
+aui.modelContext().getState();
 
 // Tools actions
 aui.tools().setToolUI(toolName, render);
@@ -355,9 +358,14 @@ const partByToolCall = aui.message().part({ toolCallId: "call_123" });
 // Access attachment by index
 const attachment = aui.composer().attachment({ index: 0 }).getState();
 
-// Access thread list item by ID or index
+// Access thread list item by ID, index, or the "main" selector
 const threadItem = aui.threads().item({ id: "thread_123" });
 const threadByIndex = aui.threads().item({ index: 0 });
+const archivedThread = aui.threads().item({ index: 0, archived: true });
+
+// Traverse to the main thread directly
+const mainThread = aui.threads().thread("main");
+const message = aui.threads().thread("main").message({ id: "msg_123" });
 ```
 
 ## Common Patterns
@@ -490,9 +498,9 @@ const isRunning = useAuiState((s) => s.thread.isRunning);
 
 | Scope          | Key State Properties                                                                             | Description                                        |
 | -------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
-| ThreadList     | `mainThreadId`, `newThreadId`, `threadIds`, `archivedThreadIds`, `isLoading`, `threadItems`     | Manages all available conversation threads         |
-| ThreadListItem | `id`, `title`, `status`, `remoteId`, `externalId`                                               | Individual thread metadata and status              |
-| Thread         | `isRunning`, `isLoading`, `isDisabled`, `isEmpty`, `messages`, `capabilities`, `suggestions`    | Active conversation state and message history      |
+| ThreadList     | `mainThreadId`, `newThreadId`, `threadIds`, `archivedThreadIds`, `isLoading`, `threadItems` (`readonly ThreadListItemState[]`) | Manages all available conversation threads |
+| ThreadListItem | `id`, `title`, `status`, `remoteId`, `externalId`, `custom?: Record<string, unknown>`           | Individual thread metadata and status; `custom` carries arbitrary per-thread metadata set by remote runtimes |
+| Thread         | `isRunning` (may be explicitly set by the runtime rather than derived from last-message status), `isLoading`, `isDisabled`, `isEmpty`, `messages`, `capabilities`, `suggestions` | Active conversation state and message history |
 | Message        | `role`, `content`, `status`, `attachments`, `parts`, `parentId`, `branchNumber`, `branchCount`, `isLast`, `index` | Individual message content and metadata |
 | Part           | `type`, `status`, `text`, `toolCallId`, `toolName`                                              | Content parts within messages (text, tool calls)   |
 | ChainOfThought | `parts`, `collapsed`, `status`                                                                   | Reasoning steps grouped within a message           |
@@ -500,13 +508,15 @@ const isRunning = useAuiState((s) => s.thread.isRunning);
 | Attachment     | `id`, `type`, `name`, `contentType`, `status`                                                   | File attachments metadata and content              |
 | Suggestions    | `suggestions`                                                                                    | Collection of follow-up message suggestions        |
 | Suggestion     | `title`, `label`, `prompt`                                                                       | Individual suggestion with title, label, and prompt |
-| ModelContext   | *(empty — use `register()` / `getToolCallParams()` methods)*                                     | Model context and tool registration                |
+| ModelContext   | *(empty — use `register()` / `getToolCallParams()` methods; see [Model Context](/docs/copilots/model-context))* | System instructions, tools, and context providers |
 
 ### Available Actions by Scope
 
+The table below covers the most commonly used actions. For the full catalog, see the [API Reference](/docs/api-reference/overview).
+
 | Scope          | Actions                                                                                                           | Use Cases                                  |
 | -------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `item(selector)`, `thread("main")`, `getState()`                    | Thread navigation and creation             |
+| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `reload()`, `getLoadThreadsPromise()`, `item(selector)`, `thread("main")`, `getState()` | Thread navigation, creation, and sync |
 | ThreadListItem | `switchTo()`, `rename(title)`, `archive()`, `unarchive()`, `delete()`, `getState()`                              | Thread management operations               |
 | Thread         | `append(message)`, `startRun(config)`, `resumeRun(config)`, `cancelRun()`, `reset()`, `export()`, `import(repository)`, `message(selector)`, `composer()`, `getState()` | Message handling and conversation control |
 | Message        | `reload()`, `speak()`, `stopSpeaking()`, `submitFeedback(feedback)`, `switchToBranch(options)`, `getCopyText()`, `part(selector)`, `attachment(selector)`, `composer()`, `setIsCopied(value)`, `setIsHovering(value)`, `getState()` | Message interactions and regeneration |
@@ -516,20 +526,38 @@ const isRunning = useAuiState((s) => s.thread.isRunning);
 | Attachment     | `remove()`, `getState()`                                                                                          | File management                            |
 | Suggestions    | `suggestion({ index })`, `getState()`                                                                             | Access follow-up suggestions               |
 | Suggestion     | `getState()`                                                                                                      | Read individual suggestion data            |
-| ModelContext   | `register(provider)`, `getState()`                                                                                | Register model context providers           |
-
-### Common Events
-
-| Event                         | Description                   |
-| ----------------------------- | ----------------------------- |
-| `thread.runStart`             | Assistant starts generating   |
-| `thread.runEnd`               | Assistant finishes generating |
-| `thread.initialize`           | Thread is initialized         |
-| `thread.modelContextUpdate`   | Model context is updated      |
-| `composer.send`               | Message is sent               |
-| `composer.attachmentAdd`      | Attachment added to composer  |
-| `threadListItem.switchedTo`   | Switched to a thread          |
-| `threadListItem.switchedAway` | Switched away from a thread   |
+| ModelContext   | `register(provider)`, `getState()`                                                                                | Register providers; full details in [Model Context](/docs/copilots/model-context) |
+
+### Events vs State Observation
+
+`useAuiEvent` is the escape hatch for **transient occurrences that are not derivable from state**. State-derivable transitions (attachment list changing, run progress, thread switching) should be observed with `useAuiState`, not subscribed via events.
+
+The rule of thumb:
+
+1. Can you read the new value from state right now? → use `useAuiState`.
+2. Are you the caller and want immediate feedback? → catch the rejection / read the return value.
+3. Did something happen that has no representation in state at all? → use `useAuiEvent`.
+
+Most existing events are kept for backward compatibility but duplicate state. They are marked `@deprecated` in the type definitions; new code should follow the rule above.
+
+#### Currently Recommended (Truly Transient)
+
+| Event                         | When It Fires                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------- |
+| `composer.attachmentAddError` | An `addAttachment()` call failed. Payload `reason` discriminates `no-adapter` / `not-accepted` / `adapter-error`. `no-adapter` and `not-accepted` are non-state-derivable. `adapter-error` is partially state-derivable: if the adapter produced any attachment before failing, the errored attachment also appears in `composer.attachments` with `status.reason === "error"`. The event additionally surfaces a human-readable `message` (and the underlying `Error` instance via the low-level `runtime.unstable_on("attachmentAddError")` API; `useAuiEvent` payloads omit it because raw `Error` objects are not store-serializable). |
+| `thread.modelContextUpdate`   | The model context provider notified a change. The model context lives in a provider, not in thread state, so this event has no state-derivable equivalent. |
+
+#### Legacy (State-Derivable, Prefer `useAuiState`)
+
+These events fire at the same transition you can observe via state. They are kept for backward compatibility but new code should observe state instead.
+
+| Legacy Event                                 | Observe Instead                                                |
+| -------------------------------------------- | -------------------------------------------------------------- |
+| `composer.send`                              | composer `text` clearing                                       |
+| `composer.attachmentAdd`                     | composer `attachments`                                         |
+| `thread.runStart` / `runEnd`                 | thread `isRunning` flipping to `true` / `false`                |
+| `thread.initialize`                          | thread `messages` becoming non-empty (or `isEmpty` flipping)   |
+| `threadListItem.switchedTo` / `switchedAway` | compare `s.threads.mainThreadId` against `s.threadListItem.id` |
 
 ## Troubleshooting
 

package/.docs/raw/docs/{(docs)/guides → guides}/dictation.mdx

@@ -1,5 +1,7 @@
 ---
 title: Speech-to-Text (Dictation)
+description: Let users speak into the composer using Web Speech API or a custom dictation adapter.
+platforms: ["react"]
 ---
 
 import { DictationSample } from "@/components/docs/samples/dictation";

package/.docs/raw/docs/guides/editing.mdx

@@ -0,0 +1,102 @@
+---
+title: Message Editing
+description: Allow users to edit their messages with custom editor interfaces.
+platforms: ["react"]
+---
+
+## Mental Model
+
+Editing re-submits a message from a past point in the conversation and creates a new branch. The messages after the edited one are discarded, and the assistant generates a fresh response from that point forward. Each user message has an independent edit composer; only one can be active at a time.
+
+The recommended way to wire this up is via the `children` render prop on `ThreadPrimitive.Messages`, branching on `message.role` and on `message.composer.isEditing` to swap in an edit composer when needed.
+
+## Enabling Edit Support
+
+```tsx
+import {
+  ActionBarPrimitive,
+  ComposerPrimitive,
+  MessagePrimitive,
+  ThreadPrimitive,
+} from "@assistant-ui/react";
+
+const Thread = () => {
+  return (
+    <ThreadPrimitive.Root>
+      <ThreadPrimitive.Viewport>
+        <ThreadPrimitive.Messages>
+          {({ message }) => {
+            if (message.role === "user") {
+              if (message.composer.isEditing) return <UserEditComposer />;
+              return <UserMessage />;
+            }
+            return <AssistantMessage />;
+          }}
+        </ThreadPrimitive.Messages>
+      </ThreadPrimitive.Viewport>
+    </ThreadPrimitive.Root>
+  );
+};
+
+const UserMessage = () => {
+  return (
+    <MessagePrimitive.Root>
+      {/* message content */}
+      <ActionBarPrimitive.Root>
+        <ActionBarPrimitive.Edit />
+      </ActionBarPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+};
+
+const UserEditComposer = () => {
+  return (
+    <MessagePrimitive.Root>
+      <ComposerPrimitive.Root>
+        <ComposerPrimitive.Input />
+        <ComposerPrimitive.Cancel />
+        <ComposerPrimitive.Send />
+      </ComposerPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+};
+
+const AssistantMessage = () => {
+  return <MessagePrimitive.Root>{/* message content */}</MessagePrimitive.Root>;
+};
+```
+
+`ActionBarPrimitive.Edit` calls `aui.composer().beginEdit()` under the hood and is disabled when the composer is already in edit mode.
+
+`ComposerPrimitive.Cancel` calls `aui.composer().cancel()`, which exits edit mode and restores the original message content. See [Composer primitives](/docs/primitives/composer) for the full composer API.
+
+## Detecting Edit Mode
+
+The `isEditing` flag is available on both `ThreadComposerState` and `EditComposerState`, so `useAuiState((s) => s.composer.isEditing)` works inside any composer context. The more idiomatic path is to rely on the `UserEditComposer` slot in the render function (shown above), which scopes the component tree automatically and avoids manual state checks.
+
+## Imperative API
+
+`aui.composer().beginEdit()` is the programmatic entry point for entering edit mode on a message. Use it for headless or keyboard-shortcut-driven flows where `ActionBarPrimitive.Edit` is not rendered:
+
+```tsx
+import { useAui } from "@assistant-ui/react";
+
+const EditButton = () => {
+  const aui = useAui();
+  return (
+    <button onClick={() => aui.composer().beginEdit()}>Edit</button>
+  );
+};
+```
+
+`aui.composer().cancel()` exits edit mode without re-submitting.
+
+## Editing While Streaming
+
+If a user triggers edit mode while the assistant is still generating a response, the in-progress run is cancelled and a new branch is started from the edited message. The hook does not block this. If your UI should prevent editing during streaming, gate the edit button on the thread run state before rendering `ActionBarPrimitive.Edit` or calling `beginEdit()`.
+
+## References
+
+- [ActionBar primitives](/docs/primitives/action-bar) — `ActionBarPrimitive.Edit` and related actions
+- [Composer primitives](/docs/primitives/composer) — full composer anatomy including `Cancel`, `Send`, and `Input`
+- [Message primitives](/docs/primitives/message) — `MessagePrimitive.Root` and content parts

package/.docs/raw/docs/guides/index.mdx

@@ -0,0 +1,103 @@
+---
+title: Overview
+description: Practical patterns for building features with assistant-ui.
+platforms: ["react"]
+---
+
+Guides are task-oriented walkthroughs for building specific features on top of assistant-ui. They sit between the [Primitives](/docs/primitives) (low-level building blocks) and [Components](/docs/ui/thread) (pre-styled installs) — pick a guide when you know what you want to build and need the recommended pattern.
+
+## Composer
+
+Extend the message input with file attachments, mentions, slash commands, voice, and quoting.
+
+<Cards>
+  <Card title="Attachments" href="/docs/guides/attachments">
+    Let users attach files, images, and documents to messages. Covers upload adapters, validation, and the typed `attachmentAddError` event.
+  </Card>
+  <Card title="Mentions" href="/docs/guides/mentions">
+    `@`-style triggers that insert directives into the composer. Sync and async search patterns.
+  </Card>
+  <Card title="Slash Commands" href="/docs/guides/slash-commands">
+    `/`-style commands with arguments, async loading, and combining with mentions.
+  </Card>
+  <Card title="Quoting" href="/docs/guides/quoting">
+    Selection toolbar, programmatic `setQuote`, and forwarding quote context to the LLM.
+  </Card>
+  <Card title="Dictation" href="/docs/guides/dictation">
+    Speech-to-text into the composer using `DictationAdapter` and `ComposerPrimitive.Dictate`.
+  </Card>
+</Cards>
+
+## Messages
+
+Customize how messages render, are edited, branched, and suggested.
+
+<Cards>
+  <Card title="Suggestions" href="/docs/guides/suggestions">
+    Welcome-screen prompts, dynamic suggestions, and the `AuiIf` empty-thread pattern.
+  </Card>
+  <Card title="Editing" href="/docs/guides/editing">
+    Edit user messages with `UserEditComposer`, `beginEdit()`, and edit-during-streaming behavior.
+  </Card>
+  <Card title="Branching" href="/docs/guides/branching">
+    Navigate alternative message versions with `BranchPickerPrimitive`, reload, and direct branch-id navigation.
+  </Card>
+  <Card title="Message Timing" href="/docs/guides/message-timing">
+    Display response duration and stream timing with `useMessageTiming` (experimental).
+  </Card>
+</Cards>
+
+## Tools & Generative UI
+
+Connect tools to the LLM and render their outputs as interactive UI.
+
+<Cards>
+  <Card title="Tools" href="/docs/guides/tools">
+    Define tools with the Toolkit API, stream args, handle cancellation, and integrate with AI SDK / LangGraph / LangChain.
+  </Card>
+  <Card title="Tool UI" href="/docs/guides/tool-ui">
+    Render tool calls and `DataMessagePart` into custom components, with fallback handling.
+  </Card>
+  <Card title="Interactables" href="/docs/guides/interactables">
+    Persisted, schema-validated interactive UI driven by AI state.
+  </Card>
+  <Card title="Multi-Agent" href="/docs/guides/multi-agent">
+    Sub-agent message attribution via `ToolCallMessagePart.messages` and LangGraph subgraph events.
+  </Card>
+</Cards>
+
+## Display
+
+Render specialized message content.
+
+<Cards>
+  <Card title="Chain of Thought" href="/docs/guides/chain-of-thought">
+    Display the assistant's reasoning steps in a collapsible accordion.
+  </Card>
+  <Card title="LaTeX" href="/docs/guides/latex">
+    Render math via React Markdown or Streamdown, with streaming-safe escape rules.
+  </Card>
+</Cards>
+
+## Audio
+
+Voice input and output.
+
+<Cards>
+  <Card title="Voice" href="/docs/guides/voice">
+    Realtime bidirectional audio with `RealtimeVoiceAdapter` and `createVoiceSession`.
+  </Card>
+  <Card title="Speech" href="/docs/guides/speech">
+    Text-to-speech for assistant messages via `SpeechSynthesisAdapter`.
+  </Card>
+</Cards>
+
+## Programmatic
+
+Read and drive runtime state from your own code.
+
+<Cards>
+  <Card title="Context API" href="/docs/guides/context-api">
+    Access threads, messages, composer, and tool state via `useAui` and the runtime scope tree.
+  </Card>
+</Cards>

package/.docs/raw/docs/{(docs)/guides → guides}/interactables.mdx

@@ -1,6 +1,7 @@
 ---
 title: Interactables
 description: Persistent UI whose state can be read and updated by the AI assistant.
+platforms: ["react"]
 ---
 
 import { InteractableSample } from "@/components/docs/samples/interactable";
@@ -344,6 +345,49 @@ const aui = useAui({
 });
 ```
 
+## Streaming Updates
+
+While the AI is generating tool arguments, `useInteractableState` reflects the partial state in real time as fields stream in. You can use the partial state itself plus the thread's running status to show a skeleton UI while the AI is mid-stream:
+
+```tsx
+import { useAuiState } from "@assistant-ui/react";
+
+function TaskBoard() {
+  const id = useAssistantInteractable("taskBoard", config);
+  const [state] = useInteractableState(id, taskBoardInitialState);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+
+  const isLoading = isRunning && state.tasks.length === 0;
+
+  return (
+    <div>
+      <h2>Tasks</h2>
+      {isLoading ? (
+        <div className="animate-pulse h-8 rounded bg-muted" />
+      ) : (
+        <ul>
+          {state.tasks.map((task) => (
+            <li key={task.id}>{task.title}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+The state object updates progressively as the AI streams in each field, so partial renders work without any extra wiring. Use the runtime's `isRunning` to distinguish "still streaming, no fields yet" from "model returned an empty result".
+
+## Schema Evolution
+
+<Callout type="warn">
+  If you change a Zod schema after state has been persisted, the imported snapshot may silently mis-match the new shape. The adapter does a shallow merge, so extra fields are preserved and missing fields keep their initial values, but type mismatches are not caught at runtime. To avoid silent corruption, version your schema key (e.g. `"taskBoard_v2"`) or namespace it by schema hash whenever you make breaking changes. Alternatively, add a migration step in your `importState` call.
+</Callout>
+
+## Unmount Behavior
+
+When a component that called `useAssistantInteractable` unmounts, the interactable is unregistered from the AI's tool list and system prompt. However, its state is preserved in the `Interactables` scope. When the component mounts again with the same name and id, the scope re-merges the preserved state rather than resetting to `initialState`. This means transient unmounts (such as React Strict Mode double-mounts or tab switches) do not lose state.
+
 ## Full Example
 
 See the complete [with-interactables example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-interactables) for a working implementation featuring:
@@ -352,3 +396,8 @@ See the complete [with-interactables example](https://github.com/assistant-ui/as
 - **Sticky Notes** — multi-instance interactables with selection and partial updates
 - **localStorage persistence** — state survives page refresh via `setPersistenceAdapter`
 - **Sync indicator** — spinning icon while a save is in-flight (`isPending`)
+
+## Related
+
+- [Generative UI](/docs/guides/tool-ui) — Inline tool call UIs rendered inside messages
+- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by a LangGraph graph alongside messages

package/.docs/raw/docs/{(docs)/guides → guides}/latex.mdx

@@ -1,21 +1,24 @@
 ---
 title: LaTeX
 description: Render mathematical expressions in chat messages using KaTeX.
+platforms: ["react"]
 ---
 
+import { PackageManagerTabs } from "@/components/docs/fumadocs/install/package-manager-tabs";
 
 Render LaTeX mathematical expressions in chat messages using KaTeX.
 
-<Callout type="warn">LaTeX rendering is not enabled in markdown by default.</Callout>
+<Callout type="warn">LaTeX rendering is not enabled by default.</Callout>
+
+<Tabs items={["react-markdown", "Streamdown"]}>
+  <Tab value="react-markdown">
 
 <Steps>
   <Step>
 
 ### Install dependencies
 
-```bash
-npm i katex rehype-katex remark-math
-```
+<PackageManagerTabs packages={["katex", "rehype-katex", "remark-math"]} />
 
   </Step>
   <Step>
@@ -53,9 +56,50 @@ export const MarkdownText = memo(MarkdownTextImpl);
   </Step>
 </Steps>
 
+  </Tab>
+  <Tab value="Streamdown">
+
+<Callout type="info">
+  Using [Streamdown](/docs/ui/streamdown) as your renderer? Math support is a first-party plugin — no remark or rehype packages needed.
+</Callout>
+
+<Steps>
+  <Step>
+
+### Install dependencies
+
+<PackageManagerTabs packages={["@streamdown/math", "katex"]} />
+
+  </Step>
+  <Step>
+
+### Add KaTeX CSS to your layout
+
+```tsx title="/app/layout.tsx"
+import "katex/dist/katex.min.css"; // [!code ++]
+```
+
+  </Step>
+  <Step>
+
+### Pass the `math` plugin to `StreamdownTextPrimitive`
+
+```tsx title="/components/assistant-ui/streamdown-text.tsx"
+import { math } from "@streamdown/math"; // [!code ++]
+import "katex/dist/katex.min.css";       // [!code ++]
+
+<StreamdownTextPrimitive plugins={{ math }} /> // [!code ++]
+```
+
+  </Step>
+</Steps>
+
+  </Tab>
+</Tabs>
+
 ## Supported Formats
 
-By default, remark-math supports:
+By default, remark-math (react-markdown path) supports:
 - `$...$` for inline math
 - `$$...$$` for display math
 - Fenced code blocks with the `math` language identifier
@@ -67,7 +111,7 @@ Many language models generate LaTeX using different delimiter formats:
 - `\[...\]` for display math
 - Custom formats like `[/math]...[/math]`
 
-You can use the `preprocess` prop to normalize these formats:
+You can use the `preprocess` prop on `MarkdownTextPrimitive` to normalize these formats before parsing:
 
 ```tsx title="/components/assistant-ui/markdown-text.tsx"
 import { MarkdownTextPrimitive } from "@assistant-ui/react-markdown";
@@ -104,6 +148,5 @@ function normalizeCustomMathTags(input: string): string {
 ```
 
 <Callout type="tip">
-The preprocessing function runs before markdown parsing, allowing you to transform any delimiter format into the standard `$` and `$$` format.
+Inside `MarkdownTextPrimitive`, the streamed text first passes through `preprocess` (delimiter normalization) and then through `useSmooth` (character-by-character accumulation), and only then reaches the markdown parser. Both run before remark-math sees the text, so delimiter replacement and the streaming smoothing are streaming-safe — partially-received delimiters are accumulated in the smoothing buffer rather than parsed mid-fragment.
 </Callout>
-