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

package/.docs/raw/docs/migrations/v0-14.mdx

@@ -0,0 +1,297 @@
+---
+title: Migration to v0.14
+description: Drops APIs deprecated since v0.11/v0.12, and primitives migrate from components prop to children render functions.
+---
+
+Version 0.14 finishes deprecation cycles started in v0.11 and v0.12, and replaces the `components` prop on primitives with a children render function pattern. If your app is on v0.13 and free of deprecation warnings, the only required change is the children API migration.
+
+## Automatic Migration
+
+The codemod that ships with the CLI handles the v0.12 hook renames (`useAssistantApi` → `useAui`, etc.) which are also removed in v0.14:
+
+```bash
+npx assistant-ui@latest upgrade
+```
+
+The other removals listed below are simple renames you can apply with find-and-replace.
+
+## Hook Aliases Removed
+
+These thin aliases existed only for backwards compatibility:
+
+| Removed                              | Replacement                  |
+| ------------------------------------ | ---------------------------- |
+| `useAssistantApi`                    | `useAui`                     |
+| `useAssistantState`                  | `useAuiState`                |
+| `useAssistantEvent`                  | `useAuiEvent`                |
+| `AssistantIf`                        | `AuiIf`                      |
+| `useLocalThreadRuntime`              | `useLocalRuntime`            |
+| `unstable_useRemoteThreadListRuntime`| `useRemoteThreadListRuntime` |
+| `unstable_useCloudThreadListAdapter` | `useCloudThreadListAdapter`  |
+| `unstable_RemoteThreadListAdapter`   | `RemoteThreadListAdapter`    |
+| `unstable_InMemoryThreadListAdapter` | `InMemoryThreadListAdapter`  |
+
+## Runtime API Cleanups
+
+### `AssistantRuntime`
+
+| Removed                                  | Replacement                               |
+| ---------------------------------------- | ----------------------------------------- |
+| `runtime.threadList`                     | `runtime.threads`                         |
+| `runtime.switchToNewThread()`            | `runtime.threads.switchToNewThread()`     |
+| `runtime.switchToThread(id)`             | `runtime.threads.switchToThread(id)`      |
+| `runtime.registerModelConfigProvider(p)` | `runtime.registerModelContextProvider(p)` |
+| `runtime.reset({ initialMessages })`     | `runtime.thread.reset(initialMessages)`   |
+
+### `ThreadRuntime`
+
+| Removed                                    | Replacement                         |
+| ------------------------------------------ | ----------------------------------- |
+| `thread.startRun(parentId)` (positional)   | `thread.startRun({ parentId })`     |
+| `thread.unstable_resumeRun(config)`        | `thread.resumeRun(config)`          |
+| `thread.unstable_loadExternalState(state)` | `thread.importExternalState(state)` |
+| `thread.getModelConfig()`                  | `thread.getModelContext()`          |
+
+### `MessageState` / `MessageRuntime`
+
+The duplicate top-level `submittedFeedback` field has been removed. It has always been mirrored from `message.metadata.submittedFeedback`, which remains the source of truth:
+
+```tsx
+// Before
+useAuiState((s) => s.message.submittedFeedback);
+
+// After
+useAuiState((s) => s.message.metadata.submittedFeedback);
+```
+
+### `ChatModelRunOptions`
+
+If you wrote a custom `ChatModelAdapter`, the legacy alias `options.config` (which mirrored `options.context`) is gone:
+
+```ts
+// Before
+const adapter: ChatModelAdapter = {
+  async run({ messages, config }) {
+    /* config.tools, config.config, ... */
+  },
+};
+
+// After
+const adapter: ChatModelAdapter = {
+  async run({ messages, context }) {
+    /* context.tools, context.config, ... */
+  },
+};
+```
+
+## External Store Helpers
+
+`getExternalStoreMessage` (singular) has been removed. Use `getExternalStoreMessages` (plural), which always returns an array — even when only one source message is bound:
+
+```ts
+// Before
+const original = getExternalStoreMessage<MyMessage>(threadMessage);
+
+// After
+const [original] = getExternalStoreMessages<MyMessage>(threadMessage);
+```
+
+## Assistant Transport Helpers
+
+`toAISDKTools` and `getEnabledTools` (re-exported from `@assistant-ui/react`) have been removed. Both wrapped functionality that's now exposed directly by `assistant-stream`:
+
+```ts
+// Before
+import { toAISDKTools } from "@assistant-ui/react";
+const schemas = toAISDKTools(tools);
+
+// After
+import { toToolsJSONSchema } from "assistant-stream";
+const schemas = toToolsJSONSchema(tools);
+```
+
+`toToolsJSONSchema` filters out `disabled` and `backend` tools by default. To replicate the old `toAISDKTools` behavior exactly (include all tools regardless), pass `{ filter: () => true }`.
+
+## react-langgraph
+
+`useLangGraphRuntime`'s `onSwitchToThread` option has been removed. Use `load`, which has the same signature plus an optional `AbortSignal`:
+
+```ts
+// Before
+useLangGraphRuntime({
+  stream,
+  onSwitchToThread: async (threadId) => {
+    return await fetchThread(threadId);
+  },
+});
+
+// After
+useLangGraphRuntime({
+  stream,
+  load: async (threadId, { signal } = {}) => {
+    return await fetchThread(threadId, { signal });
+  },
+});
+```
+
+## Children API for Primitives
+
+Version 0.14 replaces the `components` prop on primitives with a children render function pattern. This gives you full control over rendering with simple inline logic.
+
+### ThreadPrimitive.Messages
+
+**Before:**
+
+```tsx
+<ThreadPrimitive.Messages
+  components={{
+    UserMessage,
+    EditComposer,
+    AssistantMessage,
+  }}
+/>
+```
+
+**After:**
+
+```tsx
+<ThreadPrimitive.Messages>
+  {({ message }) => {
+    if (message.composer.isEditing) return <EditComposer />;
+    if (message.role === "user") return <UserMessage />;
+    return <AssistantMessage />;
+  }}
+</ThreadPrimitive.Messages>
+```
+
+### MessagePrimitive.Parts
+
+**Before:**
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    Text: MarkdownText,
+    Reasoning,
+    tools: { Fallback: ToolFallback },
+  }}
+/>
+```
+
+**After:**
+
+```tsx
+<MessagePrimitive.Parts>
+  {({ part }) => {
+    if (part.type === "text") return <MarkdownText />;
+    if (part.type === "reasoning") return <Reasoning {...part} />;
+    if (part.type === "tool-call")
+      return part.toolUI ?? <ToolFallback {...part} />;
+    return null;
+  }}
+</MessagePrimitive.Parts>
+```
+
+### `part.toolUI` and `part.dataRendererUI`
+
+Tool-call parts now expose a `toolUI` property that resolves to the registered tool UI (via `useAssistantToolUI` / `makeAssistantToolUI`) or `null` if none is registered. Data parts similarly expose `dataRendererUI`.
+
+```tsx
+// Renders the registered tool UI if available, otherwise ToolFallback
+if (part.type === "tool-call")
+  return part.toolUI ?? <ToolFallback {...part} />;
+
+// Renders the registered data renderer if available
+if (part.type === "data")
+  return part.dataRendererUI ?? null;
+```
+
+### Returning `null`
+
+Returning `null` from the children function renders registered tool UIs and data renderer UIs automatically via the registry. To explicitly render nothing (suppressing registered UIs), return `<></>`.
+
+```tsx
+<MessagePrimitive.Parts>
+  {({ part }) => {
+    if (part.type === "text") return <MarkdownText />;
+    return null; // registered tool/data UIs still render
+  }}
+</MessagePrimitive.Parts>
+```
+
+### ThreadPrimitive.Suggestions
+
+**Before:**
+
+```tsx
+<ThreadPrimitive.Suggestions
+  components={{ Suggestion: SuggestionItem }}
+/>
+```
+
+**After:**
+
+```tsx
+<ThreadPrimitive.Suggestions>
+  {() => <SuggestionItem />}
+</ThreadPrimitive.Suggestions>
+```
+
+### ThreadListPrimitive.Items
+
+**Before:**
+
+```tsx
+<ThreadListPrimitive.Items
+  components={{ ThreadListItem: MyThreadListItem }}
+/>
+```
+
+**After:**
+
+```tsx
+<ThreadListPrimitive.Items>
+  {() => <MyThreadListItem />}
+</ThreadListPrimitive.Items>
+```
+
+### Attachments
+
+**Before:**
+
+```tsx
+<ComposerPrimitive.Attachments
+  components={{ Attachment: MyAttachment }}
+/>
+```
+
+**After:**
+
+```tsx
+<ComposerPrimitive.Attachments>
+  {() => <MyAttachment />}
+</ComposerPrimitive.Attachments>
+```
+
+### `addResult` / `resume` on enriched part state
+
+When using the children API, tool-call parts include `addResult` and `resume` methods directly on the part object. This means `<ToolFallback {...part} />` works without needing a wrapper component to provide these methods.
+
+### Backwards Compatibility
+
+The `components` prop is still supported on all primitives but is deprecated and will be removed in a future version.
+
+## Still Deprecated (not removed)
+
+Some APIs marked `@deprecated` are intentionally kept for one more release to give downstream runtimes time to migrate:
+
+- `ThreadState.threadId` and `ThreadState.metadata` — use `useThreadListItem()` (see [v0.12 guide](/docs/migrations/v0-12)). Will be removed in a future minor release.
+- Legacy context hooks under `legacy-runtime/hooks/*` (`useThreadRuntime`, `useMessageRuntime`, etc.) — replaced by `useAui()` / `useAuiState()` in v0.12. The codemod migrates these.
+- Primitive `If` components (`ThreadIf`, `MessageIf`, `ComposerIf`, `ThreadEmpty`) — replaced by `AuiIf`. The codemod migrates these.
+
+You'll continue to see deprecation warnings on these; expect removal in a future minor release.
+
+## Getting Help
+
+- File issues at https://github.com/assistant-ui/assistant-ui/issues
+- See the [deprecation policy](/docs/migrations/deprecation-policy) for the support window

package/.docs/raw/docs/primitives/action-bar.mdx

@@ -1,6 +1,7 @@
 ---
 title: ActionBar
 description: Build message action buttons with auto-hide, copy state, and intelligent disabling.
+platforms: ["react"]
 ---
 
 import { ActionBarPrimitiveSample } from "@/components/docs/samples/action-bar-primitive";

package/.docs/raw/docs/primitives/assistant-modal.mdx

@@ -1,6 +1,7 @@
 ---
 title: AssistantModal
 description: A floating chat popover with a fixed-position trigger button that opens a chat panel.
+platforms: ["react"]
 ---
 
 import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";

package/.docs/raw/docs/primitives/attachment.mdx

@@ -1,6 +1,7 @@
 ---
 title: Attachment
 description: File and image attachment rendering for the composer and messages.
+platforms: ["react"]
 ---
 
 import { AttachmentSample } from "@/components/docs/samples/attachment";

package/.docs/raw/docs/primitives/branch-picker.mdx

@@ -1,6 +1,7 @@
 ---
 title: BranchPicker
 description: Navigate between message branches, which are alternative responses the user can flip through.
+platforms: ["react"]
 ---
 
 import { BranchPickerPrimitiveSample } from "@/components/docs/samples/branch-picker-primitive";

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

@@ -1,15 +1,19 @@
 ---
 title: ChainOfThought
 description: Collapsible accordion for grouping reasoning steps and tool calls.
+platforms: ["react"]
 ---
 
 import { ChainOfThoughtPrimitiveSample } from "@/components/docs/samples/chain-of-thought-primitive";
-import { ChainOfThoughtPrimitive as ChainOfThoughtPrimitiveDocs } from "@/generated/primitiveDocs";
+import {
+  ChainOfThoughtPrimitive as ChainOfThoughtPrimitiveDocs,
+  MessagePrimitive as MessagePrimitiveDocs,
+} from "@/generated/primitiveDocs";
 
-The ChainOfThought primitive groups consecutive reasoning and tool-call parts into a collapsible accordion. Reasoning models emit reasoning tokens and tool calls before producing a final answer. This primitive lets you collapse those intermediate steps behind a "Thinking" toggle.
+The ChainOfThought primitive is the legacy accordion API for grouped reasoning and tool-call parts. Reasoning models emit reasoning tokens and tool calls before producing a final answer.
 
-<Callout type="info">
-Grouped Chain of Thought currently plugs into `MessagePrimitive.Parts` via `components.ChainOfThought`. If you're wiring grouped CoT, use that API.
+<Callout type="warn">
+For new grouped reasoning/tool-call UI, use `MessagePrimitive.GroupedParts`. `ChainOfThoughtPrimitive` and `components.ChainOfThought` remain available for maintaining existing code.
 </Callout>
 
 <Tabs items={["Preview", "Code"]}>
@@ -18,105 +22,106 @@ Grouped Chain of Thought currently plugs into `MessagePrimitive.Parts` via `comp
   </Tab>
   <Tab>
 ```tsx
-import {
-  AuiIf,
-  ChainOfThoughtPrimitive,
-  MessagePrimitive,
-} from "@assistant-ui/react";
+import { MessagePrimitive } from "@assistant-ui/react";
 
 function AssistantMessage() {
   return (
     <MessagePrimitive.Root>
-      <MessagePrimitive.Parts>
-        {({ part }) => {
-          if (part.type === "text") return <MyText />;
+      <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;
         }}
-      </MessagePrimitive.Parts>
-      <ChainOfThought />
+      >
+        {({ part, children }) => {
+          switch (part.type) {
+            case "group-chainOfThought":
+              return <ThinkingAccordion>{children}</ThinkingAccordion>;
+            case "group-reasoning":
+              return <ReasoningGroup>{children}</ReasoningGroup>;
+            case "group-tool":
+              return <ToolGroup>{children}</ToolGroup>;
+            case "text":
+              return <MyText />;
+            case "reasoning":
+              return <MyReasoning {...part} />;
+            case "tool-call":
+              return part.toolUI ?? <MyToolFallback {...part} />;
+            default:
+              return null;
+          }
+        }}
+      </MessagePrimitive.GroupedParts>
     </MessagePrimitive.Root>
   );
 }
-
-function ChainOfThought() {
-  return (
-    <ChainOfThoughtPrimitive.Root className="my-2 rounded-lg border">
-      <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2.5 font-medium text-sm hover:bg-muted/50">
-        Thinking
-      </ChainOfThoughtPrimitive.AccordionTrigger>
-      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
-        <ChainOfThoughtPrimitive.Parts
-          components={{
-            Reasoning: ({ text }) => (
-              <p className="whitespace-pre-wrap px-4 py-2 text-muted-foreground text-sm italic">
-                {text}
-              </p>
-            ),
-            tools: {
-              Fallback: ({ toolName, status }) => (
-                <div className="flex items-center gap-2 px-4 py-2 text-sm">
-                  <span className="font-medium">{toolName}</span>
-                  <span className="text-muted-foreground">
-                    {status.type === "running" ? "running..." : "done"}
-                  </span>
-                </div>
-              ),
-            },
-          }}
-        />
-      </AuiIf>
-    </ChainOfThoughtPrimitive.Root>
-  );
-}
 ```
   </Tab>
 </Tabs>
 
-## Quick Start
+## Recommended: GroupedParts
 
-Render your normal message parts with `MessagePrimitive.Parts`, then place a `ChainOfThought` component alongside them inside the same `MessagePrimitive.Root`:
+Group reasoning and tool-call parts directly in your assistant message:
 
 ```tsx
-import {
-  ChainOfThoughtPrimitive,
-  MessagePrimitive,
-} from "@assistant-ui/react";
+import { MessagePrimitive } from "@assistant-ui/react";
 
 <MessagePrimitive.Root>
-  <MessagePrimitive.Parts>
-    {({ part }) => {
-      if (part.type === "text") return <MyText />;
+  <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;
     }}
-  </MessagePrimitive.Parts>
-  <MyChainOfThought />
+  >
+    {({ part, children }) => {
+      switch (part.type) {
+        case "group-chainOfThought":
+          return <ThinkingAccordion>{children}</ThinkingAccordion>;
+        case "group-reasoning":
+          return <ReasoningGroup>{children}</ReasoningGroup>;
+        case "group-tool":
+          return <ToolGroup>{children}</ToolGroup>;
+        case "text":
+          return <MyText />;
+        case "reasoning":
+          return <MyReasoning {...part} />;
+        case "tool-call":
+          return part.toolUI ?? <MyToolFallback {...part} />;
+        default:
+          return null;
+      }
+    }}
+  </MessagePrimitive.GroupedParts>
 </MessagePrimitive.Root>
-
-function MyChainOfThought() {
-  return (
-    <ChainOfThoughtPrimitive.Root>
-      <ChainOfThoughtPrimitive.AccordionTrigger>
-        Thinking
-      </ChainOfThoughtPrimitive.AccordionTrigger>
-      <ChainOfThoughtPrimitive.Parts />
-    </ChainOfThoughtPrimitive.Root>
-  );
-}
 ```
 
-`Root` renders a `<div>`, `AccordionTrigger` renders a `<button>` that toggles the collapsed state, and `Parts` renders the grouped reasoning and tool-call parts.
+### GroupedParts API Reference
+
+<PrimitivesTypeTable type="MessagePrimitiveGroupedPartsProps" parameters={MessagePrimitiveDocs.GroupedParts.props} />
+
+## Legacy: ChainOfThoughtPrimitive
+
+### Quick Start
+
+Render your normal message parts with `MessagePrimitive.Parts`, then place a `ChainOfThought` component alongside them inside the same `MessagePrimitive.Root` only when maintaining older code that already uses the ChainOfThought primitive.
 
 <Callout type="info">
 Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRuntimeProvider` with a runtime (for example `useLocalRuntime(...)`). See [Pick a Runtime](/docs/runtimes/pick-a-runtime).
 </Callout>
 
-## Core Concepts
+### Concepts
 
-### How Grouping Works
+#### How Grouping Works
 
-`ChainOfThoughtPrimitive.Parts` reads the current message's grouped reasoning and tool-call context. In practice, render your normal text/image/data parts with `MessagePrimitive.Parts`, and render `ChainOfThoughtPrimitive` separately where you want the collapsible reasoning block to appear.
+`ChainOfThoughtPrimitive.Parts` reads the current message's grouped reasoning and tool-call context from the legacy `components.ChainOfThought` path. New code should use `MessagePrimitive.GroupedParts` instead.
 
-### Collapsed State
+#### Collapsed State
 
 The accordion starts collapsed by default. `AccordionTrigger` toggles between collapsed and expanded. Use `AuiIf` to conditionally render parts based on the collapsed state:
 
@@ -135,7 +140,7 @@ import { AuiIf, ChainOfThoughtPrimitive } from "@assistant-ui/react";
 </ChainOfThoughtPrimitive.Root>
 ```
 
-### Chevron Indicators
+#### Chevron Indicators
 
 Use `AuiIf` to show directional icons that reflect the current state:
 
@@ -154,9 +159,9 @@ import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
 </ChainOfThoughtPrimitive.AccordionTrigger>
 ```
 
-### Parts Components
+#### Parts Components
 
-`ChainOfThoughtPrimitive.Parts` accepts a `components` prop to control how each part type renders:
+`ChainOfThoughtPrimitive.Parts` accepts a deprecated `components` prop to control how each part type renders:
 
 ```tsx
 <ChainOfThoughtPrimitive.Parts
@@ -186,9 +191,9 @@ import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
 | `components.tools.Fallback` | `ToolCallMessagePartComponent` | Fallback for tool-call parts |
 | `components.Layout` | `ComponentType<PropsWithChildren>` | Wrapper around each rendered part |
 
-## Parts
+### Parts API Reference
 
-### Root
+#### Root
 
 Container for the chain-of-thought disclosure UI. Renders a `<div>` element unless `asChild` is set.
 
@@ -198,7 +203,7 @@ Container for the chain-of-thought disclosure UI. Renders a `<div>` element unle
 </ChainOfThoughtPrimitive.Root>
 ```
 
-### AccordionTrigger
+#### AccordionTrigger
 
 Trigger that toggles the collapsed state. Renders a `<button>` element unless `asChild` is set.
 
@@ -208,7 +213,7 @@ Trigger that toggles the collapsed state. Renders a `<button>` element unless `a
 </ChainOfThoughtPrimitive.AccordionTrigger>
 ```
 
-### Parts
+#### Parts
 
 Renders reasoning and tool-call parts. This component does not track collapsed state internally, so control visibility with `AuiIf` as shown in the patterns below.
 
@@ -233,9 +238,9 @@ Renders reasoning and tool-call parts. This component does not track collapsed s
 
 <PrimitivesTypeTable type="ChainOfThoughtPrimitivePartsProps" parameters={ChainOfThoughtPrimitiveDocs.Parts.props} />
 
-## Patterns
+### Patterns
 
-### Minimal Accordion
+#### Minimal Accordion
 
 ```tsx
 function ChainOfThought() {
@@ -260,7 +265,7 @@ function ChainOfThought() {
 }
 ```
 
-### With Tool Calls
+#### With Tool Calls
 
 ```tsx
 function ChainOfThought() {
@@ -298,11 +303,11 @@ function ChainOfThought() {
 }
 ```
 
-## Relationship to Components
+### Relationship to Components
 
-The [Chain of Thought guide](/docs/guides/chain-of-thought) covers end-to-end setup including backend configuration with reasoning models. See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a full working implementation.
+The [Chain of Thought guide](/docs/guides/chain-of-thought) covers end-to-end setup with `MessagePrimitive.GroupedParts`, including backend configuration with reasoning models. See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a full working implementation.
 
-## API Reference
+### API Reference
 
 For the complete guide including backend configuration, see [Chain of Thought](/docs/guides/chain-of-thought). For prop details, see the [ChainOfThoughtPrimitive source](https://github.com/assistant-ui/assistant-ui/tree/main/packages/react/src/primitives/chainOfThought).