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

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

@@ -0,0 +1,166 @@
+---
+title: Chain of Thought UI
+description: Show AI reasoning steps and tool calls in a collapsible thinking accordion. Build chain-of-thought visualizations in React chat with assistant-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 reasoning model 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. 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("gpt-5.4-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.
+title: Assistant Context API
+description: Read and update assistant state to build custom React components in your chat UI — composable context API for thread, message, and runtime data via assistant-ui.
+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);
@@ -255,8 +258,8 @@ useAuiEvent("composer.send", (event) => {
 });
 
 // Listen to thread events
-useAuiEvent("thread.runStart", (event) => {
-  console.log("Run started in thread:", event.threadId);
+useAuiEvent("thread.modelContextUpdate", (event) => {
+  console.log("Model context updated in thread:", event.threadId);
 });
 
 // Listen to all events of a type across all scopes
@@ -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)
+title: Speech-to-Text Dictation
+description: Add voice dictation to your AI chat composer with the Web Speech API or a custom adapter. Speech-to-text in React, integrated through assistant-ui.
+platforms: ["react"]
 ---
 
 import { DictationSample } from "@/components/docs/samples/dictation";

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

@@ -0,0 +1,102 @@
+---
+title: Message Editing
+description: Let users edit their messages and regenerate AI responses with custom editor interfaces. Edit-and-resubmit patterns for React chat via assistant-ui.
+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/generative-ui.mdx

@@ -0,0 +1,142 @@
+---
+title: Generative UI
+description: Render agent-described React UI from a JSON spec with a consumer-provided component allowlist.
+---
+
+`MessagePrimitive.GenerativeUI` is a first-class primitive for rendering UI
+described by the agent at runtime as a JSON spec. Instead of hard-coding a
+component per tool, the agent emits a `generative-ui` message part containing
+a tree of components by name. assistant-ui resolves each name against a
+**consumer-provided allowlist** and renders the result.
+
+> The allowlist controls **which** components the agent may render: any name
+> not in it throws a typed `GenerativeUIRenderError` (no implicit fallback). It
+> does not constrain the props passed to those components; see [Security](#security).
+
+## Quick start
+
+### 1. Define your component allowlist
+
+```tsx title="components/gui.tsx"
+const Card = ({ title, children }) => (
+  <div className="rounded-xl border bg-card p-4 shadow-sm">
+    <div className="text-base font-semibold">{title}</div>
+    <div className="mt-2">{children}</div>
+  </div>
+);
+
+const Button = ({ label }) => (
+  <button className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground">
+    {label}
+  </button>
+);
+
+export const componentsAllowlist = { Card, Button };
+```
+
+### 2. Wire the primitive into your message renderer
+
+```tsx title="components/assistant-message.tsx"
+import { MessagePrimitive } from "@assistant-ui/react";
+import { componentsAllowlist } from "./gui";
+
+export function AssistantMessage() {
+  return (
+    <MessagePrimitive.Parts
+      components={{
+        generativeUI: { components: componentsAllowlist },
+      }}
+    />
+  );
+}
+```
+
+You can also use the standalone primitive form:
+
+```tsx
+<MessagePrimitive.GenerativeUI components={componentsAllowlist} />
+```
+
+### 3. Have the agent emit a `generative-ui` part
+
+A `GenerativeUIMessagePart` carries a JSON spec:
+
+```ts
+{
+  type: "generative-ui",
+  spec: {
+    root: {
+      component: "Card",
+      props: { title: "Welcome" },
+      children: [
+        { component: "Button", props: { label: "Get started" } },
+      ],
+    },
+  },
+}
+```
+
+Bare strings act as inline text leaves.
+
+## Spec shape
+
+```ts
+type GenerativeUINode =
+  | string
+  | {
+      component: string;             // resolved against the allowlist
+      props?: Record<string, unknown>;
+      children?: GenerativeUINode[];
+      key?: string;                   // optional stable React key
+    };
+
+type GenerativeUISpec = {
+  root: GenerativeUINode | GenerativeUINode[];
+};
+```
+
+The spec is plain JSON — easy for any agent to emit, and easy to validate
+on the server before delivery.
+
+## Streaming
+
+The primitive is stream-friendly: any partial spec renders progressively. As
+new nodes arrive (filling in `children`, refining `props`), the rendered tree
+updates without reflows or lost local state for already-mounted children.
+
+## Security
+
+The allowlist is the boundary on **which** components render: a spec can only instantiate components you put in the registry, with no `eval` and no dynamic import (names are looked up in the registry and nothing else). An unknown name throws `GenerativeUIRenderError` or invokes your `Fallback`.
+
+It does **not** constrain the `props` the agent supplies. Spec props are spread directly onto your allowlisted components, so treat every allowlisted component as receiving untrusted input: never forward agent-supplied props into `dangerouslySetInnerHTML`, validate or reject `href` / `src` values (for example block `javascript:` URLs), and avoid passing spec props anywhere they become executable. The safest allowlisted components accept only primitive, display-oriented props.
+
+## Error handling
+
+Unknown component names throw `GenerativeUIRenderError` with a typed
+`componentName` field. Catch it with a React error boundary, or pass a
+`Fallback` component to opt into a soft-fail UX:
+
+```tsx
+<MessagePrimitive.GenerativeUI
+  components={componentsAllowlist}
+  Fallback={({ component }) => (
+    <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
+      unknown component: {component}
+    </span>
+  )}
+/>
+```
+
+## Composing with other primitives
+
+`generative-ui` is a regular `MessagePart` type, so it composes cleanly with
+`MessagePrimitive.Parts`, `MessagePrimitive.PartByIndex`, and
+`MessagePrimitive.GroupedParts`. Render it alongside text, tool calls, and
+reasoning in the same message.
+
+## Why a primitive (not just a tool)
+
+Tool-call UI is great when the agent already invoked a known tool. Generative
+UI flips it: the agent _composes_ UI from a vocabulary you ship. Useful for
+forms, dashboards, status panels, multi-step flows, and anywhere the
+component library you want is broader than a single tool's render surface.

package/.docs/raw/docs/guides/image-generation.mdx

@@ -0,0 +1,74 @@
+---
+title: Image Generation
+description: Generate images in your backend and render them inline in an assistant-ui thread.
+---
+
+Image generation needs no dedicated primitive. Generate the image wherever you already run model calls (a route handler or a tool), store the result as an `ImageMessagePart`, and render it with the `@assistant-ui/ui` `Image` component.
+
+<Callout type="info">
+  This covers non-streaming generation, rendering, and actions. Streaming partial images and multi-image galleries are out of scope.
+</Callout>
+
+## Generate in your backend
+
+Call your provider from a server route. With the AI SDK that is `generateImage`; return the image as a data URI (or an object-store URL) plus any provider metadata you want to keep.
+
+```ts
+// app/api/image/route.ts
+import { generateImage } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json();
+  const result = await generateImage({
+    model: openai.image("gpt-image-1"),
+    prompt,
+  });
+  const revisedPrompt = (
+    result.providerMetadata as
+      | Record<string, Record<string, unknown>>
+      | undefined
+  )?.openai?.revisedPrompt;
+  return Response.json({
+    image: `data:${result.image.mediaType};base64,${result.image.base64}`,
+    mimeType: result.image.mediaType,
+    ...(typeof revisedPrompt === "string" && { revisedPrompt }),
+  });
+}
+```
+
+The model provider is irrelevant to rendering; swap `openai.image(...)` for any AI SDK image model.
+
+## Store it as an `ImageMessagePart`
+
+An `ImageMessagePart` only needs `image` (a `data:` URI, an `https://` URL, or a `blob:` URL) plus an optional `filename`. Keep any provenance you want to display, the prompt, a revised prompt, a model id, in your own component state or in message metadata; the part itself stays minimal.
+
+```ts
+const part: ImageMessagePart = {
+  type: "image",
+  image: result.image, // data:, https://, or blob: URL
+};
+```
+
+## Render with the `Image` component
+
+The `Image` component in `@assistant-ui/ui` handles the render states for you:
+
+1. **Running** (`status.type === "running"`) renders a spinner.
+2. **Content filter** (`status.type === "incomplete"` with `reason: "content-filter"`) renders an error card with no `<img src>`.
+3. **Complete** renders a zoomable `<img>` with optional `Image.Actions`.
+
+`Image.Actions` provides download and copy buttons, plus a regenerate button when you pass an `onRegenerate` callback. Wire it to the same generation flow you used above; debounce, rate limiting, and confirmation are your call.
+
+```tsx
+import { Image } from "@assistant-ui/ui";
+
+<>
+  <Image {...imagePart} />
+  <Image.Actions part={imagePart} onRegenerate={() => regenerate(prompt)} />
+</>;
+```
+
+## Example
+
+A complete Next.js example (with a mock fallback when `OPENAI_API_KEY` is unset) lives in [`examples/with-image-generation`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-image-generation).