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

package/.docs/raw/docs/cloud/langgraph.mdx

@@ -36,6 +36,9 @@ Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-
 
 Add the following environment variables to your project:
 
+<PlatformTabs>
+<Tab value="React">
+
 ```bash title=".env.local"
 # Frontend API URL from your cloud project settings
 NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
@@ -44,6 +47,31 @@ NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
 ASSISTANT_API_KEY=your-api-key-here
 ```
 
+</Tab>
+<Tab value="React Native">
+
+```bash title=".env"
+# Client API URL from your cloud project settings
+EXPO_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
+
+# API key for server-side operations; do not ship this in your app bundle
+ASSISTANT_API_KEY=your-api-key-here
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```bash title=".env"
+# Client API URL from your cloud project settings
+ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
+
+# API key for server-side operations; do not ship this in your CLI bundle
+ASSISTANT_API_KEY=your-api-key-here
+```
+
+</Tab>
+</PlatformTabs>
+
 </Step>
 
 <Step>
@@ -52,8 +80,24 @@ ASSISTANT_API_KEY=your-api-key-here
 
 Install the required packages:
 
+<PlatformTabs>
+<Tab value="React">
+
 <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph"]} />
 
+</Tab>
+<Tab value="React Native">
+
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-langgraph", "assistant-cloud"]} />
+
+</Tab>
+<Tab value="React Ink">
+
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-langgraph", "assistant-cloud", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
 </Step>
 
 <Step>
@@ -62,6 +106,9 @@ Install the required packages:
 
 Create a runtime provider that integrates LangGraph with assistant-cloud. Choose between anonymous mode for demos/prototypes or authenticated mode for production:
 
+<PlatformTabs>
+<Tab value="React">
+
 <Tabs items={["Anonymous", "Authenticated (Clerk)"]}>
 
 <Tab value="Anonymous">
@@ -204,6 +251,135 @@ export function MyRuntimeProvider({
 
 </Tabs>
 
+</Tab>
+<Tab value="React Native">
+
+```tsx title="components/runtime-provider.tsx"
+import { useMemo, type ReactNode } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import { AssistantCloud } from "assistant-cloud";
+import {
+  type LangChainMessage,
+  useLangGraphRuntime,
+} from "@assistant-ui/react-langgraph";
+import { createThread, deleteThread, getThreadState, sendMessage } from "@/lib/chatApi";
+
+async function getAssistantToken() {
+  // Return a user token from your auth provider.
+  return "...";
+}
+
+export function MyRuntimeProvider({ children }: { children: ReactNode }) {
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env.EXPO_PUBLIC_ASSISTANT_BASE_URL!,
+        authToken: getAssistantToken,
+      }),
+    [],
+  );
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({
+        threadId: externalId,
+        messages,
+      });
+    },
+    create: async () => {
+      const { thread_id } = await createThread();
+      return { externalId: thread_id };
+    },
+    load: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages:
+          (state.values as { messages?: LangChainMessage[] }).messages ?? [],
+      };
+    },
+    delete: async (externalId) => {
+      await deleteThread(externalId);
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="runtime-provider.tsx"
+import { useMemo, type ReactNode } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import { AssistantCloud } from "assistant-cloud";
+import {
+  type LangChainMessage,
+  useLangGraphRuntime,
+} from "@assistant-ui/react-langgraph";
+import { createThread, deleteThread, getThreadState, sendMessage } from "./chat-api.js";
+
+async function getAssistantToken() {
+  // Return a user token from your auth provider.
+  return "...";
+}
+
+export function MyRuntimeProvider({ children }: { children: ReactNode }) {
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env.ASSISTANT_BASE_URL!,
+        authToken: getAssistantToken,
+      }),
+    [],
+  );
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({
+        threadId: externalId,
+        messages,
+      });
+    },
+    create: async () => {
+      const { thread_id } = await createThread();
+      return { externalId: thread_id };
+    },
+    load: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages:
+          (state.values as { messages?: LangChainMessage[] }).messages ?? [],
+      };
+    },
+    delete: async (externalId) => {
+      await deleteThread(externalId);
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
 <Callout type="info">
   The `useLangGraphRuntime` hook accepts `cloud`, `create`, `load`, and `delete` parameters for simplified thread management. The runtime handles the thread lifecycle internally.
 
@@ -220,6 +396,9 @@ export function MyRuntimeProvider({
 
 Install the thread list component:
 
+<PlatformTabs>
+<Tab value="React">
+
 <Tabs items={["assistant-ui", "shadcn (namespace)", "shadcn"]}>
   <Tab>
 
@@ -260,17 +439,110 @@ export default function ChatPage() {
 }
 ```
 
+</Tab>
+<Tab value="React Native">
+
+Follow the [React Native setup](/docs/react-native) for `Thread`, then compose it with the native thread-list primitives:
+
+```tsx title="app/chat.tsx"
+import { Text, View } from "react-native";
+import {
+  ThreadListItemPrimitive,
+  ThreadListPrimitive,
+} from "@assistant-ui/react-native";
+import { Thread } from "@/components/assistant-ui/thread";
+
+function ThreadList() {
+  return (
+    <ThreadListPrimitive.Root>
+      <ThreadListPrimitive.New>
+        <Text>New chat</Text>
+      </ThreadListPrimitive.New>
+      <ThreadListPrimitive.Items
+        renderItem={({ threadId }) => (
+          <ThreadListItemPrimitive.Root key={threadId}>
+            <ThreadListItemPrimitive.Trigger>
+              <ThreadListItemPrimitive.Title fallback="New conversation" />
+            </ThreadListItemPrimitive.Trigger>
+          </ThreadListItemPrimitive.Root>
+        )}
+      />
+    </ThreadListPrimitive.Root>
+  );
+}
+
+export default function ChatPage() {
+  return (
+    <MyRuntimeProvider>
+      <View style={{ flex: 1 }}>
+        <ThreadList />
+        <Thread />
+      </View>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+Follow the [Ink setup](/docs/ink) for `Thread`, then compose it with the terminal thread-list primitives:
+
+```tsx title="chat.tsx"
+import { Box, Text } from "ink";
+import {
+  ThreadListItemPrimitive,
+  ThreadListPrimitive,
+} from "@assistant-ui/react-ink";
+import { Thread } from "./components/thread.js";
+
+function ThreadList() {
+  return (
+    <ThreadListPrimitive.Root>
+      <ThreadListPrimitive.New>
+        <Text color="green">[New chat]</Text>
+      </ThreadListPrimitive.New>
+      <ThreadListPrimitive.Items
+        renderItem={({ threadId }) => (
+          <ThreadListItemPrimitive.Root key={threadId}>
+            <ThreadListItemPrimitive.Trigger>
+              <ThreadListItemPrimitive.Title fallback="New conversation" />
+            </ThreadListItemPrimitive.Trigger>
+          </ThreadListItemPrimitive.Root>
+        )}
+      />
+    </ThreadListPrimitive.Root>
+  );
+}
+
+export function ChatPage() {
+  return (
+    <MyRuntimeProvider>
+      <Box flexDirection="column">
+        <ThreadList />
+        <Thread />
+      </Box>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
 </Step>
 
 </Steps>
 
 ## Authentication
 
-The examples above show two authentication modes:
+The React runtime-provider tab shows two authentication modes:
 
-- **Anonymous**: Suitable for demos and prototypes. Creates a browser session-based user ID.
+- **Anonymous**: Suitable for React demos and prototypes. Creates a browser session-based user ID.
 - **Authenticated**: For production use with user accounts. The authenticated example uses [Clerk](https://clerk.com/), but you can integrate any auth provider.
 
+The React Native and React Ink tabs use explicit `authToken` callbacks, which is the recommended shape outside browser-session-based demos.
+
 For other authentication providers or custom implementations, see the [Cloud Authorization](/docs/cloud/authorization) guide.
 
 ## Next Steps

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.
+title: File Attachments
+description: Let users attach images, PDFs, and other files to AI chat messages in React. Drag-drop, paste, and vision-model support, built into assistant-ui.
+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,11 +114,11 @@ 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
 
-Send images to vision-capable LLMs like GPT-4V, Claude 3, or Gemini Pro Vision:
+Send images to vision-capable LLMs like GPT-5.4, Claude Sonnet 4.6, or Gemini Pro Vision:
 
 ```tsx
 import {
@@ -305,7 +276,7 @@ const MyModelAdapter: ChatModelAdapter = {
         msg.role === "user" &&
         msg.content.some((part) => part.type === "image")
       ) {
-        // Format for GPT-4V or similar vision models
+        // Format for GPT-5.4 or similar vision models
         return {
           role: "user",
           content: msg.content.map((part) => {
@@ -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: Edit messages or regenerate AI responses, then switch between alternative replies. Branching navigation built into assistant-ui's React chat UI.
+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.