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

package/.docs/raw/docs/guides/speech.mdx

@@ -0,0 +1,156 @@
+---
+title: Text-to-Speech (Speech Synthesis)
+description: Read messages aloud with Web Speech API or a custom TTS adapter.
+platforms: ["react"]
+---
+
+import { SpeechSample } from "@/components/docs/samples/speech";
+
+assistant-ui supports text-to-speech via the `SpeechSynthesisAdapter` interface. When a speech adapter is configured, users can trigger playback for any assistant message.
+
+<SpeechSample />
+
+## SpeechSynthesisAdapter
+
+The `SpeechSynthesisAdapter` interface has a single method:
+
+```tsx
+import type { SpeechSynthesisAdapter } from "@assistant-ui/react";
+
+type SpeechSynthesisAdapter = {
+  speak: (text: string) => SpeechSynthesisAdapter.Utterance;
+};
+```
+
+`speak` is called with the plain text of an assistant message and must return an `Utterance` object:
+
+```tsx
+type Utterance = {
+  status: SpeechSynthesisAdapter.Status;
+  cancel: () => void;
+  subscribe: (callback: () => void) => Unsubscribe;
+};
+
+type Status =
+  | { type: "starting" | "running" }
+  | { type: "ended"; reason: "finished" | "cancelled" | "error"; error?: unknown };
+```
+
+Currently the following built-in adapter is available:
+
+- `WebSpeechSynthesisAdapter`: uses the browser's `Web Speech API` (`SpeechSynthesis`)
+
+## WebSpeechSynthesisAdapter
+
+```tsx
+import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
+
+const runtime = useChatRuntime({
+  adapters: {
+    speech: new WebSpeechSynthesisAdapter(),
+  },
+});
+```
+
+## UI
+
+The default action bar does not include a speech button. Add `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking` to your assistant message action bar:
+
+```tsx
+import { ActionBarPrimitive, useMessageTTS } from "@assistant-ui/react";
+import { AudioLinesIcon, StopCircleIcon } from "lucide-react";
+
+const AssistantActionBar = () => {
+  const isSpeaking = useMessageTTS();
+
+  return (
+    <ActionBarPrimitive.Root>
+      {!isSpeaking && (
+        <ActionBarPrimitive.Speak>
+          <AudioLinesIcon />
+        </ActionBarPrimitive.Speak>
+      )}
+      {isSpeaking && (
+        <ActionBarPrimitive.StopSpeaking>
+          <StopCircleIcon />
+        </ActionBarPrimitive.StopSpeaking>
+      )}
+      <ActionBarPrimitive.Copy />
+    </ActionBarPrimitive.Root>
+  );
+};
+```
+
+`ActionBarPrimitive.Speak` is automatically disabled when no speech adapter is configured.
+
+## Custom Adapters
+
+Implement `SpeechSynthesisAdapter` to call any external TTS API:
+
+```tsx title="lib/custom-tts-adapter.ts"
+import type { SpeechSynthesisAdapter } from "@assistant-ui/react";
+
+export class CustomTTSAdapter implements SpeechSynthesisAdapter {
+  private apiUrl: string;
+
+  constructor(options: { apiUrl: string }) {
+    this.apiUrl = options.apiUrl;
+  }
+
+  speak(text: string): SpeechSynthesisAdapter.Utterance {
+    const subscribers = new Set<() => void>();
+    let status: SpeechSynthesisAdapter.Status = { type: "starting" };
+    let audio: HTMLAudioElement | null = null;
+
+    const notify = () => {
+      for (const cb of subscribers) cb();
+    };
+
+    const finish = (reason: "finished" | "cancelled" | "error", error?: unknown) => {
+      if (status.type === "ended") return;
+      status = { type: "ended", reason, error };
+      notify();
+    };
+
+    fetch(this.apiUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text }),
+    })
+      .then((res) => res.blob())
+      .then((blob) => {
+        audio = new Audio(URL.createObjectURL(blob));
+        status = { type: "running" };
+        notify();
+        audio.onended = () => finish("finished");
+        audio.onerror = (e) => finish("error", e);
+        audio.play();
+      })
+      .catch((err) => finish("error", err));
+
+    return {
+      get status() { return status; },
+      cancel: () => {
+        audio?.pause();
+        finish("cancelled");
+      },
+      subscribe: (cb) => {
+        subscribers.add(cb);
+        return () => subscribers.delete(cb);
+      },
+    };
+  }
+}
+```
+
+Wire it up the same way as the built-in adapter:
+
+```tsx
+import { CustomTTSAdapter } from "@/lib/custom-tts-adapter";
+
+const runtime = useChatRuntime({
+  adapters: {
+    speech: new CustomTTSAdapter({ apiUrl: "/api/tts" }),
+  },
+});
+```

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

@@ -1,6 +1,7 @@
 ---
 title: Suggestions
 description: Display suggested prompts to help users get started with your assistant.
+platforms: ["react"]
 ---
 
 Suggestions are pre-defined prompts that help users discover what your assistant can do. They appear in the welcome screen and provide a quick way to start conversations.
@@ -85,7 +86,7 @@ The default Thread component from the shadcn registry already includes suggestio
 
 ### Customizing Suggestion Display
 
-If you want to customize how suggestions are displayed, you can modify your Thread component:
+If you want to customize how suggestions are displayed, you can modify your Thread component. The idiomatic pattern is to wrap the suggestions in `AuiIf` so they only appear when the thread is empty:
 
 ```tsx
 import {
@@ -96,17 +97,18 @@ import {
 
 const ThreadWelcome = () => {
   return (
-    <div className="flex flex-col items-center justify-center">
-      <h1>Welcome!</h1>
-      <p>How can I help you today?</p>
-
-      {/* Display suggestions */}
-      <div className="grid grid-cols-2 gap-2">
-        <ThreadPrimitive.Suggestions>
-          {() => <SuggestionItem />}
-        </ThreadPrimitive.Suggestions>
+    <AuiIf condition={(s) => s.thread.isEmpty}>
+      <div className="flex flex-col items-center justify-center">
+        <h1>Welcome!</h1>
+        <p>How can I help you today?</p>
+
+        <div className="grid grid-cols-2 gap-2">
+          <ThreadPrimitive.Suggestions>
+            {() => <SuggestionItem />}
+          </ThreadPrimitive.Suggestions>
+        </div>
       </div>
-    </div>
+    </AuiIf>
   );
 };
 
@@ -126,53 +128,13 @@ const SuggestionItem = () => {
 };
 ```
 
-## Suggestion Primitives
-
-### ThreadPrimitive.Suggestions
-
-Renders all suggestions from the suggestions scope.
-
-```tsx
-<ThreadPrimitive.Suggestions>
-  {() => <CustomSuggestionComponent />}
-</ThreadPrimitive.Suggestions>
-```
-
-### SuggestionPrimitive.Title
-
-Displays the suggestion's title (the first part when using object format, or the full text when using strings).
-
-```tsx
-<SuggestionPrimitive.Title />
-```
-
-### SuggestionPrimitive.Description
+### Dismissal
 
-Displays the suggestion's description/label (only shown when using object format).
+Suggestions dismiss automatically once the user sends a message because `thread.isEmpty` becomes false. No extra state management is needed. If you want to dismiss suggestions without sending (for example, after a user clicks away), manage a local boolean and combine it with the `AuiIf` condition or a plain conditional render.
 
-```tsx
-<SuggestionPrimitive.Description />
-```
-
-### SuggestionPrimitive.Trigger
-
-A button that triggers the suggestion action when clicked.
-
-```tsx
-<SuggestionPrimitive.Trigger
-  send={true}
-  clearComposer={true}
-  asChild
->
-  <button>Click me</button>
-</SuggestionPrimitive.Trigger>
-```
-
-**Props:**
+## Suggestion Primitives
 
-- `send` (boolean): When true, automatically sends the message. When false, only populates the composer.
-- `clearComposer` (boolean, default: true): When `send` is false, determines if the composer is cleared before adding the suggestion (true) or if the suggestion is appended (false).
-- `asChild` (boolean): Merge props with child element instead of rendering a button.
+The primitives available for rendering suggestions are `ThreadPrimitive.Suggestions`, `ThreadPrimitive.SuggestionByIndex`, `SuggestionPrimitive.Title`, `SuggestionPrimitive.Description`, and `SuggestionPrimitive.Trigger`. `ThreadPrimitive.SuggestionByIndex` is useful when you need layout control over a specific suggestion slot rather than iterating all of them. For the full prop reference and usage patterns, see the [Suggestion primitive docs](/docs/primitives/suggestion).
 
 ## Dynamic Suggestions
 
@@ -213,30 +175,6 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## Context-Aware Suggestions
-
-Suggestions can be tailored to different contexts or user intents:
-
-```tsx
-const suggestions = [
-  {
-    title: "Code Review",
-    label: "Get feedback on your code",
-    prompt: "Can you review this code for me?",
-  },
-  {
-    title: "Debug Help",
-    label: "Find and fix issues",
-    prompt: "Help me debug this error",
-  },
-  {
-    title: "Best Practices",
-    label: "Learn recommended patterns",
-    prompt: "What are the best practices for this?",
-  },
-];
-```
-
 ## Best Practices
 
 1. **Keep suggestions concise**: Use clear, actionable prompts that users can understand at a glance
@@ -246,11 +184,11 @@ const suggestions = [
 5. **Limit the number**: 3-6 suggestions work best to avoid overwhelming users
 6. **Make them actionable**: Each suggestion should lead to a meaningful interaction
 
-## Migration from Legacy API
+## Switching from `ThreadPrimitive.Suggestion`
 
-If you're using the deprecated `ThreadPrimitive.Suggestion` component, migrate to the new API:
+If your codebase uses the inline `ThreadPrimitive.Suggestion` component (which renders one suggestion at a time with hardcoded `prompt` / `send` props), you can move to the runtime-driven `Suggestions()` API for centralized configuration. The inline component is still supported, but the runtime-driven approach scales better when suggestions need to update dynamically.
 
-### Before (Deprecated)
+### Inline form
 
 ```tsx
 <ThreadPrimitive.Suggestion
@@ -259,7 +197,7 @@ If you're using the deprecated `ThreadPrimitive.Suggestion` component, migrate t
 />
 ```
 
-### After (Recommended)
+### Runtime-driven form
 
 1. Configure suggestions in your runtime provider:
 

package/.docs/raw/docs/{(docs)/guides → guides}/tool-ui.mdx

@@ -1,6 +1,7 @@
 ---
 title: Generative UI
 description: Render tool calls as interactive UI instead of plain text.
+platforms: ["react"]
 ---
 
 import { ToolUISample } from "@/components/docs/samples/tool-ui";
@@ -26,7 +27,7 @@ There are two main approaches to creating tool UIs in assistant-ui:
 
 ### 1. Client-Defined Tools (`makeAssistantTool`)
 
-If you're creating tools on the client side, use `makeAssistantTool` to register them with the assistant context. Then create a UI component with `makeAssistantToolUI`:
+If you're creating tools on the client side, use `makeAssistantTool` to register them with the assistant context. Then create a UI component with `makeAssistantToolUI`. This component-based API coexists with the [Tools()](/docs/guides/tools) toolkit API; pick whichever fits your codebase better.
 
 ```tsx
 import { makeAssistantTool, tool } from "@assistant-ui/react";
@@ -503,44 +504,97 @@ render: ({ status, args }) => {
 };
 ```
 
-### Field-Level Validation
+### Deferred Rendering
 
-<Callout type="warn">
-  `useToolArgsFieldStatus` is not currently exported from `@assistant-ui/react`.
-  The hook exists internally but is not part of the public API. This section is
-  included for reference and may become available in a future release.
+<Callout type="info">
+This section applies when the model **drives** the component through a tool call (args arrive incrementally and you want to wait for the final shape). If your backend or orchestrator pushes the component instead, prefer [Data-Part Generative UI](#data-part-generative-ui) with `makeAssistantDataUI`. Data parts arrive as terminal events, so the renderer only fires once with the final data, no deferred rendering needed.
 </Callout>
 
-Use `useToolArgsFieldStatus` to show validation states:
+Sometimes you want to capture a tool call's streaming arguments but only render the final UI once the call completes. This is useful when partial args would render misleading or jarring intermediate states (a chart that flashes through half-populated data), when the component is expensive to mount (heavy visualizations, embedded iframes, third-party widgets), or when the model controls *whether* the component appears at all.
+
+#### Inline at the end of streaming
+
+Return `null` from the tool UI's `render` until `status.type === "complete"`. The streaming args still arrive in `args` as the model emits them, you just ignore them until the call is done:
+
+```tsx
+const ChartToolUI = makeAssistantToolUI<
+  { title: string; series: number[] },
+  void
+>({
+  toolName: "renderChart",
+  render: ({ args, status }) => {
+    if (status.type !== "complete") return null;
+    return <Chart title={args.title} data={args.series} />;
+  },
+});
+```
+
+The chart mounts once, with the final args, after streaming finishes. No re-renders during the stream.
+
+The same `render` shape works inside the [`Tools()`](/docs/guides/tools) toolkit's `render` field, with `useAssistantToolUI`, and with `MessagePrimitive.Parts`'s inline `tools.by_name` overrides. The deferred-rendering pattern applies regardless of how you registered the tool UI.
+
+#### Below the message body
+
+If the component should sit *outside* the message parts (for example, a card attached under the avatar block rather than inline with text), gate at the message level with [`AuiIf`](/docs/api-reference/primitives/assistant-if) and read `s.message.status`:
 
 ```tsx
-import { useToolArgsFieldStatus } from "@assistant-ui/react";
+import { MessagePrimitive, AuiIf, useAuiState } from "@assistant-ui/react";
+
+function PostMessageCard() {
+  const parts = useAuiState((s) => s.message.parts);
+  const chartCall = parts.find(
+    (p) => p.type === "tool-call" && p.toolName === "renderChart",
+  );
+  if (!chartCall) return null;
+  return <Chart {...chartCall.args} />;
+}
+
+<MessagePrimitive.Root>
+  <MessagePrimitive.Parts />
+
+  <AuiIf
+    condition={(s) =>
+      s.message.role === "assistant" &&
+      s.message.status?.type === "complete"
+    }
+  >
+    <PostMessageCard />
+  </AuiIf>
+</MessagePrimitive.Root>;
+```
+
+The `AuiIf` predicate fires whenever the assistant state changes; children mount only when both checks pass. `PostMessageCard` then reads the captured tool-call part from `s.message.parts` and renders from its args.
+
+For the opposite pattern (showing partial data as it streams in), see [Field-Level Streaming State](#field-level-streaming-state) and [Partial Results & Streaming](#partial-results--streaming) below.
+
+### Field-Level Streaming State
+
+Use `useToolArgsStatus` to react to per-field streaming state. The hook returns a `propStatus` map where each top-level key in the args object resolves from `"streaming"` to `"complete"` as the partial JSON arrives. Call it inside a tool-call message part context:
 
-const FormToolUI = makeAssistantToolUI({
+```tsx
+import { useToolArgsStatus } from "@assistant-ui/react";
+
+const FormToolUI = makeAssistantToolUI<{ email: string; phone: string }, unknown>({
   toolName: "submitForm",
   render: ({ args }) => {
-    const emailStatus = useToolArgsFieldStatus(["email"]);
-    const phoneStatus = useToolArgsFieldStatus(["phone"]);
+    const { propStatus } = useToolArgsStatus<{ email: string; phone: string }>();
 
     return (
       <form className="space-y-4">
         <div>
           <input
             type="email"
-            value={args.email}
-            className={emailStatus.type === "running" ? "loading" : ""}
+            value={args.email ?? ""}
+            className={propStatus.email === "streaming" ? "loading" : ""}
             disabled
           />
-          {emailStatus.type === "incomplete" && (
-            <span className="text-red-500">Invalid email</span>
-          )}
         </div>
 
         <div>
           <input
             type="tel"
-            value={args.phone}
-            className={phoneStatus.type === "running" ? "loading" : ""}
+            value={args.phone ?? ""}
+            className={propStatus.phone === "streaming" ? "loading" : ""}
             disabled
           />
         </div>
@@ -596,24 +650,7 @@ const AnalysisToolUI = makeAssistantToolUI<
 
 ### Custom Tool Fallback
 
-Provide a custom UI for tools without specific UIs:
-
-```tsx
-<Thread
-  components={{
-    ToolFallback: ({ toolName, args, result }) => (
-      <div className="tool-fallback rounded bg-gray-100 p-3">
-        <code className="text-sm">
-          {toolName}({JSON.stringify(args)})
-        </code>
-        {result && (
-          <pre className="mt-2 text-xs">{JSON.stringify(result, null, 2)}</pre>
-        )}
-      </div>
-    ),
-  }}
-/>
-```
+For tools that have no dedicated UI, add the `ToolFallback` shadcn component to your project. See the [ToolFallback install guide](/docs/ui/tool-fallback) for setup instructions and the [ToolGroup guide](/docs/ui/tool-group) for grouping consecutive tool calls into a collapsible container.
 
 ## Execution Context
 
@@ -777,6 +814,41 @@ const WeatherUI = makeAssistantToolUI({
 
 `propStatus` maps each key to `"streaming"` | `"complete"` once the key appears in the partial JSON. Keys not yet present in the stream are absent from `propStatus`.
 
+## Data-Part Generative UI
+
+Alongside tool-call rendering, assistant-ui supports a second generative UI mechanism based on `DataMessagePart`. Instead of attaching UI to a tool invocation, the backend (or the LangGraph graph) emits named data events that are appended as `{ type: "data", name, data }` parts on the parent assistant message.
+
+**When to choose which:**
+
+- **Tool UI**: the **model** decides what to render by calling a tool whose args become the component's data. Register the renderer via the [`Tools()`](/docs/guides/tools) toolkit's `render` field (recommended), or standalone with `makeAssistantToolUI` / `useAssistantToolUI` when the tool itself is defined elsewhere (backend, MCP, LangGraph). Args stream incrementally, so you observe partial state via `status` / `useToolArgsStatus` and may need [Deferred Rendering](#deferred-rendering) for components that should only mount with final data.
+- **Data UI** (`makeAssistantDataUI`): the **backend or orchestrator** decides what to render and pushes a named data event onto the assistant message. Data parts arrive as terminal events with no streaming partials, so the renderer naturally fires once with the final data.
+
+If you want a component to appear only after the message is complete and you control the backend, Data UI is usually the more direct fit; reach for Tool UI's deferred pattern when the model itself must drive the choice.
+
+Use `makeAssistantDataUI` to register a renderer for a named data part:
+
+```tsx
+import { makeAssistantDataUI } from "@assistant-ui/react";
+
+type ChartProps = { series: number[]; title: string };
+
+export const ChartUI = makeAssistantDataUI<ChartProps>({
+  name: "chart",
+  render: ({ data }) => (
+    <div>
+      <h3>{data.title}</h3>
+      <Chart series={data.series} />
+    </div>
+  ),
+});
+```
+
+Mount `<ChartUI />` once inside the `AssistantRuntimeProvider` tree; it renders nothing itself and only registers the renderer.
+
+For LangGraph-specific patterns (emitting UI from a Python/TypeScript graph node via `push_ui_message` / `typedUi`, dynamic loading with `LoadExternalComponent`, and the `useLangGraphUIMessages` escape hatch), see [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui).
+
+A fallback renderer for unmatched data parts is available internally but `setFallbackDataUI` is not yet a public API.
+
 ## Related Guides
 
 - [Tools Guide](/docs/guides/tools) - Learn how to create and use tools with AI models