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

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

@@ -1,6 +1,7 @@
 ---
 title: Attachments
 description: Let users attach files, images, and documents to messages.
+platforms: ["react"]
 ---
 
 import { AttachmentSample } from "@/components/docs/samples/attachment";
@@ -57,37 +58,7 @@ const runtime = useChatRuntime();
 
 ### Add UI Components
 
-Integrate attachment components into your chat interface:
-
-```tsx title="/components/assistant-ui/thread.tsx"
-// In your Composer component
-import {
-  ComposerAttachments,
-  ComposerAddAttachment,
-} from "@/components/assistant-ui/attachment";
-
-const Composer = () => {
-  return (
-    <ComposerPrimitive.Root>
-      <ComposerAttachments />
-      <ComposerAddAttachment />
-      <ComposerPrimitive.Input placeholder="Type a message..." />
-    </ComposerPrimitive.Root>
-  );
-};
-
-// In your UserMessage component
-import { UserMessageAttachments } from "@/components/assistant-ui/attachment";
-
-const UserMessage = () => {
-  return (
-    <MessagePrimitive.Root>
-      <UserMessageAttachments />
-      <MessagePrimitive.Parts />
-    </MessagePrimitive.Root>
-  );
-};
-```
+Integrate the attachment components into your chat interface. See [Attachment UI components](/docs/ui/attachment) for the full install and usage guide.
 
   </Step>
 </Steps>
@@ -143,7 +114,7 @@ const compositeAdapter = new CompositeAttachmentAdapter([
 
 ## Creating Custom Attachment Adapters
 
-Build your own adapters for specialized file handling. Below are complete examples for common use cases.
+Build your own adapters for specialized file handling. Below are complete examples for common use cases. For `PendingAttachment` and `CompleteAttachment` type definitions, see [Attachment types](/docs/ui/attachment#attachment-types).
 
 ### Vision-Capable Image Adapter
 
@@ -364,7 +335,7 @@ Provide real-time upload progress using async generators:
 
 ```tsx
 class UploadAttachmentAdapter implements AttachmentAdapter {
-  accept = "*/*";
+  accept = "*";
 
   async *add({ file }: { file: File }) {
     const id = generateId();
@@ -391,8 +362,8 @@ class UploadAttachmentAdapter implements AttachmentAdapter {
       } as PendingAttachment;
     }
 
-    // Return final pending state
-    return {
+    // Yield final progress so the 100% state reaches the composer
+    yield {
       id,
       type: "file",
       name: file.name,
@@ -490,6 +461,40 @@ class ValidatedImageAdapter implements AttachmentAdapter {
 }
 ```
 
+To surface failures in the UI, subscribe to `composer.attachmentAddError`. It fires whenever an add operation produces a failure, in either of two ways:
+
+1. `addAttachment()` rejects: no adapter is configured, the file type does not match `accept`, or the adapter's `add()` throws.
+2. `addAttachment()` resolves but the adapter returned (or, for async-iterator adapters, yielded) an attachment whose `status.reason === "error"`. The promise resolves successfully, yet the event still fires so the UI can react.
+
+The event payload carries a `reason` discriminator and a human-readable `message`, so you can branch UI on the failure mode:
+
+| `reason`         | When It Fires                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------------ |
+| `no-adapter`     | `addAttachment(File)` was called but no `AttachmentAdapter` is configured.                             |
+| `not-accepted`   | The file's content type (or filename extension) did not match `adapter.accept`. External `CreateAttachment` descriptors also trigger this when their `contentType` does not match `adapter.accept`. |
+| `adapter-error`  | The adapter's `add()` threw, or returned/yielded an attachment with `status.reason === "error"`. If the adapter produced any attachment before failing, the errored attachment is also visible in `composer.attachments`; if it threw before producing one, the event is the only signal. |
+
+```tsx
+import { toast } from "sonner"; // or your toast library of choice
+import { useAuiEvent } from "@assistant-ui/react";
+
+function AttachmentErrorToast() {
+  useAuiEvent("composer.attachmentAddError", ({ reason, message, error }) => {
+    if (reason === "not-accepted") {
+      toast.error("This file type is not supported.");
+    } else if (reason === "no-adapter") {
+      toast.error("Attachments are not configured for this composer.");
+    } else {
+      if (error) console.error(error); // underlying Error, useful for logging
+      toast.error(message || "Attachment failed to upload.");
+    }
+  });
+  return null;
+}
+```
+
+`attachmentId` is included when the failure is associated with an attachment that was registered (typically `adapter-error` cases). It is `undefined` for `no-adapter` and `not-accepted` failures because those reject before any attachment is registered.
+
 ### External Source Attachments
 
 Add attachments from external sources (URLs, API data, CMS references) without needing a `File` object or an `AttachmentAdapter`:
@@ -513,7 +518,7 @@ await aui.composer().addAttachment({
 });
 ```
 
-External attachments are added as complete attachments directly — they skip the `AttachmentAdapter` entirely and can be removed without one.
+External attachments are added as complete attachments directly. They bypass the `AttachmentAdapter`'s `add()` step (no upload), but `adapter.accept` is still enforced when an `AttachmentAdapter` is configured: a `CreateAttachment` whose `contentType` does not match `adapter.accept` is rejected and emits `composer.attachmentAddError`. If `contentType` is omitted, the descriptor's filename extension is matched against `adapter.accept` only when `accept` itself contains explicit extension entries (e.g. `.png,.pdf`); MIME-wildcard `accept` strings such as `image/*` always require a matching `contentType`. When no `AttachmentAdapter` is configured, external attachments are added without any content-type check, and they can be removed without an adapter.
 
 ### Multiple File Selection
 

package/.docs/raw/docs/guides/branching.mdx

@@ -0,0 +1,76 @@
+---
+title: Message Branching
+description: Navigate between alternative message versions created by editing or reloading.
+platforms: ["react"]
+---
+
+import { BranchingSample } from "@/components/docs/samples/branching";
+
+Branching lets users navigate between alternative versions of a message. A new branch is created when:
+
+- A user message is edited
+- An assistant message is reloaded (reload creates a new branch on the same message)
+
+Branches are automatically tracked by assistant-ui by observing changes to the `messages` array.
+
+## Shortest Working Pattern
+
+<BranchingSample />
+
+Place a branch picker inside your message component:
+
+```tsx
+import { BranchPickerPrimitive } from "@assistant-ui/react";
+
+const BranchPicker = () => (
+  <BranchPickerPrimitive.Root hideWhenSingleBranch>
+    <BranchPickerPrimitive.Previous />
+    <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+    <BranchPickerPrimitive.Next />
+  </BranchPickerPrimitive.Root>
+);
+```
+
+`BranchPickerPrimitive.Previous` and `.Next` automatically disable at branch boundaries and while a run is in flight (unless the runtime supports `switchBranchDuringRun`). For the full primitive API, see [BranchPickerPrimitive](/docs/primitives/branch-picker).
+
+## Triggering Reload
+
+`ActionBarPrimitive.Reload` creates a new branch on an assistant message and re-runs from there:
+
+```tsx
+import { ActionBarPrimitive, MessagePrimitive } from "@assistant-ui/react";
+
+const AssistantMessage = () => (
+  <MessagePrimitive.Root>
+    <MessagePrimitive.Parts />
+    <ActionBarPrimitive.Root>
+      <ActionBarPrimitive.Reload />
+    </ActionBarPrimitive.Root>
+  </MessagePrimitive.Root>
+);
+```
+
+`Reload` is disabled while `thread.isRunning` or `thread.isDisabled` is true. See [ActionBarPrimitive](/docs/primitives/action-bar) for the full reference.
+
+## Programmatic Branch Navigation
+
+For headless or keyboard-shortcut flows, navigate directly to a branch by id via `aui.message().switchToBranch`:
+
+```tsx
+import { useAui } from "@assistant-ui/react";
+
+const SwitchToBranch = ({ branchId }: { branchId: string }) => {
+  const aui = useAui();
+  return (
+    <button onClick={() => aui.message().switchToBranch({ branchId })}>
+      Go to branch
+    </button>
+  );
+};
+```
+
+This must be called inside a message context (e.g. nested within `MessagePrimitive.Root`).
+
+## Grouped Parts After Branching
+
+Each branch is a distinct message version with its own content parts. `MessagePrimitive.GroupedParts` provides hierarchical adjacent grouping of those parts, useful when a message mixes tool calls and text across branches. See the [MessagePrimitive](/docs/primitives/message) reference for `GroupedParts` usage.

package/.docs/raw/docs/guides/chain-of-thought.mdx

@@ -0,0 +1,166 @@
+---
+title: Chain of Thought
+description: Group reasoning and tool calls into a collapsible accordion UI.
+platforms: ["react"]
+---
+
+LLMs often produce reasoning steps and tool calls in succession. Chain of Thought lets you visually group these consecutive parts into a single collapsible accordion, giving users a clean "thinking" UI.
+
+## Overview
+
+When a model like OpenAI's `o4-mini` responds, it may emit a sequence of reasoning tokens and tool calls before producing its final text answer. Use `MessagePrimitive.GroupedParts` to group those adjacent reasoning and tool-call parts into a single collapsible "thinking" section.
+
+<Callout type="info">
+The older `components.ChainOfThought` prop on `MessagePrimitive.Parts` and `components` prop on `ChainOfThoughtPrimitive.Parts` are legacy APIs. They still work for existing code, but new code should use `MessagePrimitive.GroupedParts`.
+</Callout>
+
+## Quick Start
+
+<Steps>
+  <Step>
+
+### Wire GroupedParts into your assistant message
+
+Return the same top-level group for reasoning and tool calls, with nested groups for each type:
+
+```tsx
+import {
+  MessagePrimitive,
+} from "@assistant-ui/react";
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import {
+  Reasoning,
+  ReasoningContent,
+  ReasoningRoot,
+  ReasoningText,
+  ReasoningTrigger,
+} from "@/components/assistant-ui/reasoning";
+import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
+import {
+  ToolGroupContent,
+  ToolGroupRoot,
+  ToolGroupTrigger,
+} from "@/components/assistant-ui/tool-group";
+import type { FC } from "react";
+
+const AssistantMessage: FC = () => {
+  return (
+    <MessagePrimitive.Root>
+      <MessagePrimitive.GroupedParts
+        groupBy={(part) => {
+          if (part.type === "reasoning")
+            return ["group-chainOfThought", "group-reasoning"];
+          if (part.type === "tool-call")
+            return ["group-chainOfThought", "group-tool"];
+          return null;
+        }}
+      >
+        {({ part, children }) => {
+          switch (part.type) {
+            case "group-chainOfThought":
+              return <div className="my-2">{children}</div>;
+            case "group-reasoning": {
+              const running = part.status.type === "running";
+              return (
+                <ReasoningRoot defaultOpen={running}>
+                  <ReasoningTrigger active={running} />
+                  <ReasoningContent aria-busy={running}>
+                    <ReasoningText>{children}</ReasoningText>
+                  </ReasoningContent>
+                </ReasoningRoot>
+              );
+            }
+            case "group-tool":
+              return (
+                <ToolGroupRoot>
+                  <ToolGroupTrigger
+                    count={part.indices.length}
+                    active={part.status.type === "running"}
+                  />
+                  <ToolGroupContent>{children}</ToolGroupContent>
+                </ToolGroupRoot>
+              );
+            case "text":
+              return <MarkdownText />;
+            case "reasoning":
+              return <Reasoning {...part} />;
+            case "tool-call":
+              return part.toolUI ?? <ToolFallback {...part} />;
+            default:
+              return null;
+          }
+        }}
+      </MessagePrimitive.GroupedParts>
+    </MessagePrimitive.Root>
+  );
+};
+```
+
+  </Step>
+  <Step>
+
+### Use a Reasoning Model
+
+Chain of Thought is most useful with models that produce reasoning tokens (e.g. OpenAI `o4-mini`). Here's an example backend route using the AI SDK:
+
+```tsx title="app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("o4-mini"),
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+  </Step>
+</Steps>
+
+## LangGraph
+
+Chain-of-thought parts are surfaced by the AI SDK's built-in reasoning stream. LangGraph does not emit reasoning tokens in that format, so reasoning grouping will not activate automatically. If you want to display reasoning text from a LangGraph agent, emit it as a custom data part from your graph and render it with `makeAssistantDataUI`. See [generative UI with LangGraph](/docs/runtimes/langgraph/generative-ui) for details.
+
+## Legacy: ChainOfThoughtPrimitive
+
+### Reading Collapsed State
+
+For existing `ChainOfThoughtPrimitive` code, use `AuiIf` to conditionally render based on the accordion state:
+
+```tsx
+import { AuiIf, ChainOfThoughtPrimitive } from "@assistant-ui/react";
+import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
+
+const ChainOfThoughtAccordionTrigger = () => {
+  return (
+    <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 text-sm">
+      <AuiIf condition={(s) => s.chainOfThought.collapsed}>
+        <ChevronRightIcon className="size-4" />
+      </AuiIf>
+      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
+        <ChevronDownIcon className="size-4" />
+      </AuiIf>
+      Thinking
+    </ChainOfThoughtPrimitive.AccordionTrigger>
+  );
+};
+```
+
+### API Reference
+
+For lower-level legacy compatibility details, see the [`ChainOfThought` primitive reference](/docs/primitives/chain-of-thought).
+
+## Full Example
+
+See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a working implementation with tool calls and reasoning.
+
+## Related Guides
+
+- [Reasoning](/docs/ui/reasoning) — reasoning UI primitives for grouped parts
+- [Generative UI](/docs/guides/tool-ui) — custom UI for tool calls
+- [Tools](/docs/guides/tools) — defining and using tools

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