@assistant-ui/mcp-docs-server 0.1.38 → 0.2.0

package/.docs/raw/docs/guides/electron.mdx

@@ -0,0 +1,369 @@
+---
+title: Electron
+description: Run assistant-ui in an Electron renderer with a hosted backend or a secure, streaming preload and IPC bridge.
+platforms: ["react"]
+---
+
+assistant-ui works in Electron through `@assistant-ui/react`. The renderer is a React DOM environment, so there is no separate `@assistant-ui/electron` package to install. The Electron-specific decision is where model requests run and how the renderer reaches them.
+
+<Callout type="warn">
+  Never put a provider API key in renderer code, a `VITE_*` variable, or a preload script. Bundled values are readable by anyone with the app. Keep remote credentials on your backend, or keep local credentials in the main process and provision them with an OS-backed secret store.
+</Callout>
+
+## Choose a connection pattern
+
+| Pattern | Use it when | Runtime |
+| --- | --- | --- |
+| Hosted backend | You already have an AI SDK endpoint, need server auth or persistence, or ship the app to other people | `useChatRuntime` with an absolute HTTPS URL |
+| Local main process | The desktop app owns the provider or agent process and must work without your web backend | `useLocalRuntime` with a narrow preload/IPC bridge |
+
+```mermaid
+flowchart LR
+  Renderer["Electron renderer<br/>assistant-ui React"] -->|"absolute HTTPS"| Backend["Hosted chat backend"]
+  Renderer -->|"window.assistantAI"| Preload["context-isolated preload"]
+  Preload -->|"transferred MessagePort"| Main["Electron main process"]
+  Backend --> Provider["Model or agent"]
+  Main --> Provider
+```
+
+Do not send an SDK client, assistant-ui runtime, callback, `AbortSignal`, or `File` through IPC. Electron IPC uses structured clone semantics; define a small data-only protocol instead.
+
+## Pattern 1: hosted backend
+
+This is the smallest integration. Keep your existing AI SDK chat route and point `AssistantChatTransport` at its public URL.
+
+```tsx title="renderer/assistant-runtime.tsx"
+import type { ReactNode } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  AssistantChatTransport,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+
+const transport = new AssistantChatTransport({
+  api: "https://api.example.com/chat",
+});
+
+export function ElectronRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useChatRuntime({ transport });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+The URL must be absolute in a packaged app. A relative value such as `/api/chat` targets the renderer's `file://` or custom-protocol origin, not your deployed backend. Configure the backend's CORS policy for the packaged origin, allow the endpoint in `connect-src`, and authenticate requests as you would from any desktop client.
+
+The endpoint must return the AI SDK UI message stream consumed by `AssistantChatTransport`. See the [AI SDK runtime guide](/docs/runtimes/ai-sdk/v7) for the backend route and tool-calling setup.
+
+## Pattern 2: local main process
+
+Use this pattern when the Electron main process calls the model or runs a local agent. Keep `contextIsolation: true`, `sandbox: true`, and `nodeIntegration: false` on the `BrowserWindow`. Register `registerAssistantIpc(mainWindow)` after creating the trusted window.
+
+The following example is intentionally text-only. It streams one request over a dedicated `MessagePort`; closing that port propagates assistant-ui's Stop action to an `AbortController` in the main process.
+
+### 1. Define a data-only protocol
+
+Place the shared types somewhere all three Electron bundles can import.
+
+```ts title="shared/assistant-ipc.ts"
+export const ASSISTANT_STREAM_CHANNEL = "assistant:stream";
+
+export type ChatMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string };
+
+export type ChatRequest = {
+  system?: string;
+  messages: ChatMessage[];
+};
+
+export type ChatEvent =
+  | { type: "delta"; text: string }
+  | { type: "done" }
+  | { type: "error"; message: string };
+
+export type AssistantAI = {
+  streamChat(
+    request: ChatRequest,
+    onEvent: (event: ChatEvent) => void,
+  ): () => void;
+};
+```
+
+### 2. Expose one preload capability
+
+Expose the smallest API the renderer needs, not `ipcRenderer` itself. The callback receives only validated event data, never Electron's privileged IPC event object.
+
+```ts title="preload/assistant.ts"
+import { contextBridge, ipcRenderer } from "electron";
+import {
+  ASSISTANT_STREAM_CHANNEL,
+  type AssistantAI,
+  type ChatEvent,
+} from "./shared";
+
+const assistantAI: AssistantAI = {
+  streamChat(request, onEvent) {
+    const { port1, port2 } = new MessageChannel();
+    const onMessage = (event: MessageEvent<ChatEvent>) => onEvent(event.data);
+
+    port1.addEventListener("message", onMessage);
+    port1.start();
+    ipcRenderer.postMessage(ASSISTANT_STREAM_CHANNEL, request, [port2]);
+
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      port1.removeEventListener("message", onMessage);
+      port1.close();
+    };
+  },
+};
+
+contextBridge.exposeInMainWorld("assistantAI", assistantAI);
+```
+
+Declare the context-bridge API for renderer TypeScript:
+
+```ts title="renderer/electron.d.ts"
+import type { AssistantAI } from "./shared";
+
+declare global {
+  interface Window {
+    assistantAI: AssistantAI;
+  }
+}
+
+export {};
+```
+
+### 3. Stream from the main process
+
+Install the provider packages in the Electron main-process bundle:
+
+```sh
+pnpm add ai @ai-sdk/openai
+```
+
+The handler checks both the sending `WebContents` and its main frame, validates the untrusted payload and bounds its size before calling the model. Set `OPENAI_API_KEY` only in the main-process environment.
+
+```ts title="main/assistant-ipc.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+import { ipcMain, type BrowserWindow, type IpcMainEvent } from "electron";
+import {
+  ASSISTANT_STREAM_CHANNEL,
+  type ChatEvent,
+  type ChatRequest,
+} from "./shared";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isChatRequest = (value: unknown): value is ChatRequest => {
+  if (!isRecord(value) || !Array.isArray(value.messages)) return false;
+  if (value.system !== undefined && typeof value.system !== "string") {
+    return false;
+  }
+  if (value.messages.length > 200) return false;
+
+  let totalLength = typeof value.system === "string" ? value.system.length : 0;
+  for (const message of value.messages) {
+    if (!isRecord(message)) return false;
+    if (message.role !== "user" && message.role !== "assistant") return false;
+    if (typeof message.content !== "string") return false;
+    totalLength += message.content.length;
+    if (totalLength > 1_000_000) return false;
+  }
+
+  return true;
+};
+
+export function registerAssistantIpc(mainWindow: BrowserWindow) {
+  const handleStream = (event: IpcMainEvent, request: unknown) => {
+    const [port] = event.ports;
+    if (!port) return;
+
+    if (
+      event.sender !== mainWindow.webContents ||
+      event.senderFrame !== mainWindow.webContents.mainFrame
+    ) {
+      port.close();
+      return;
+    }
+
+    port.start();
+    if (!isChatRequest(request)) {
+      port.postMessage({
+        type: "error",
+        message: "Invalid chat request.",
+      } satisfies ChatEvent);
+      port.close();
+      return;
+    }
+
+    const abortController = new AbortController();
+    port.once("close", () => abortController.abort());
+    const send = (message: ChatEvent) => port.postMessage(message);
+
+    void (async () => {
+      try {
+        const result = streamText({
+          model: openai("gpt-5.4-mini"),
+          messages: request.messages,
+          ...(request.system ? { system: request.system } : {}),
+          abortSignal: abortController.signal,
+        });
+
+        for await (const text of result.textStream) {
+          send({ type: "delta", text });
+        }
+        send({ type: "done" });
+      } catch (error) {
+        if (abortController.signal.aborted) return;
+        console.error("Assistant stream failed", error);
+        send({ type: "error", message: "The model request failed." });
+      }
+    })();
+  };
+
+  ipcMain.on(ASSISTANT_STREAM_CHANNEL, handleStream);
+  mainWindow.once("closed", () => {
+    ipcMain.removeListener(ASSISTANT_STREAM_CHANNEL, handleStream);
+  });
+}
+```
+
+If your app can open more than one trusted assistant window, register a unique channel per window or route requests through one application-level registry. A global `ipcMain.on` listener should not be re-registered under the same channel for every window.
+
+### 4. Adapt IPC to assistant-ui
+
+`ChatModelAdapter` yields complete snapshots, so the renderer accumulates each IPC delta before yielding it. Its cleanup function closes the port on Stop, unmount, or completion.
+
+```tsx title="renderer/assistant-runtime.tsx"
+import type { ReactNode } from "react";
+import {
+  AssistantRuntimeProvider,
+  useLocalRuntime,
+  type ChatModelAdapter,
+} from "@assistant-ui/react";
+import type { ChatMessage } from "./shared";
+
+const ipcChatModel: ChatModelAdapter = {
+  async *run({ messages, context, abortSignal }) {
+    abortSignal.throwIfAborted();
+
+    const system = [context.system];
+    const serializedMessages: ChatMessage[] = [];
+
+    for (const message of messages) {
+      const text = message.content
+        .flatMap((part) => (part.type === "text" ? [part.text] : []))
+        .join("\n");
+      if (!text) continue;
+
+      if (message.role === "system") system.push(text);
+      if (message.role === "user") {
+        serializedMessages.push({ role: "user", content: text });
+      }
+      if (message.role === "assistant") {
+        serializedMessages.push({ role: "assistant", content: text });
+      }
+    }
+
+    const systemText = system.filter(Boolean).join("\n\n");
+    let stop: (() => void) | undefined;
+    let removeAbortListener: (() => void) | undefined;
+    const deltas = new ReadableStream<string>({
+      start(controller) {
+        let settled = false;
+        const close = () => {
+          if (settled) return;
+          settled = true;
+          controller.close();
+        };
+        const fail = (error: unknown) => {
+          if (settled) return;
+          settled = true;
+          controller.error(error);
+        };
+
+        stop = window.assistantAI.streamChat(
+          {
+            ...(systemText ? { system: systemText } : {}),
+            messages: serializedMessages,
+          },
+          (event) => {
+            if (event.type === "delta") controller.enqueue(event.text);
+            if (event.type === "done") close();
+            if (event.type === "error") fail(new Error(event.message));
+          },
+        );
+
+        const onAbort = () => {
+          stop?.();
+          fail(abortSignal.reason);
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () =>
+          abortSignal.removeEventListener("abort", onAbort);
+        if (abortSignal.aborted) onAbort();
+      },
+      cancel() {
+        stop?.();
+      },
+    });
+
+    const reader = deltas.getReader();
+    let fullText = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        fullText += value;
+        yield { content: [{ type: "text", text: fullText }] };
+      }
+    } finally {
+      removeAbortListener?.();
+      stop?.();
+      reader.releaseLock();
+    }
+  },
+};
+
+export function ElectronRuntimeProvider({ children }: { children: ReactNode }) {
+  const runtime = useLocalRuntime(ipcChatModel);
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Wrap your existing assistant-ui thread with `ElectronRuntimeProvider`. Primitives and installed UI components work exactly as they do in a browser React app.
+
+## Extend the protocol deliberately
+
+The local example drops every non-text content part. Add explicit structured-clone-safe fields before claiming support for more features:
+
+- Attachments: pass bounded `ArrayBuffer` data or an app-owned file reference after validating type, size, and path in the main process. Do not pass browser `File` objects.
+- Tools: define serializable tool-call and tool-result events, and validate every tool invocation in the privileged process. Never expose a generic shell or filesystem IPC method.
+- Reasoning and metadata: add distinct event variants and map them to the corresponding assistant-ui content parts.
+- Thread persistence: store serializable thread data in the main process or use a remote thread-list adapter; do not try to transfer a runtime object.
+
+## Packaged-app checklist
+
+- Use an absolute HTTPS endpoint, a privileged custom protocol, or the preload bridge. Relative `/api/*` routes that worked against a development server will not follow your backend after packaging.
+- Serve local content through a custom protocol instead of `file://` when possible, and define a restrictive Content Security Policy. Do not disable `webSecurity` to work around origin errors.
+- Validate every IPC sender and every payload in the main process. Treat renderer data as untrusted even when the renderer is local.
+- Intercept new windows and external links with `webContents.setWindowOpenHandler`; do not let model-generated links create unrestricted Electron windows.
+- If you render remote HTML with `SafeContentFrame`, allow its documented host in `frame-src`. Ordinary text and Markdown rendering need no Electron-specific change.
+- Test the packaged build, not only the Vite or Webpack development server. The scheme, origin, preload path, CSP, and environment loading can all differ.
+
+For the underlying platform constraints, see Electron's official guides to [IPC and MessagePorts](https://www.electronjs.org/docs/latest/tutorial/message-ports), [context isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation), and the [security checklist](https://www.electronjs.org/docs/latest/tutorial/security).

package/.docs/raw/docs/guides/index.mdx

@@ -95,3 +95,23 @@ Read and drive runtime state from your own code.
     Access threads, messages, composer, and tool state via `useAui` and the runtime scope tree.
   </Card>
 </Cards>
+
+## Providers
+
+Alternative ways to connect a model.
+
+<Cards>
+  <Card title="ChatGPT Subscription" href="/docs/guides/chatgpt-subscription">
+    Run your app locally on a ChatGPT Plus or Pro plan via Codex OAuth, no API key required.
+  </Card>
+</Cards>
+
+## Environments
+
+Run assistant-ui outside a conventional browser deployment.
+
+<Cards>
+  <Card title="Electron" href="/docs/guides/electron">
+    Connect an Electron renderer to a hosted backend or a secure, streaming preload/IPC bridge.
+  </Card>
+</Cards>

package/.docs/raw/docs/guides/mentions.mdx

@@ -25,9 +25,7 @@ Under the hood, mentions are one kind of [trigger popover](/docs/guides/slash-co
 
 The fastest path is the pre-built [Mention UI components](/docs/ui/composer-trigger-popover), which wire everything together with two shadcn components — the popover picker and the message-side chip renderer:
 
-```bash
-npx shadcn@latest add "https://r.assistant-ui.com/composer-trigger-popover" "https://r.assistant-ui.com/directive-text"
-```
+<InstallCommand shadcn={["composer-trigger-popover", "directive-text"]} />
 
 See the [Composer Trigger Popover](/docs/ui/composer-trigger-popover) and [Directive Text](/docs/ui/directive-text) guides for setup steps.
 
@@ -414,6 +412,36 @@ import { LexicalComposerInput } from "@assistant-ui/react-lexical";
 
 `LexicalComposerInput` automatically discovers every `Directive` trigger registered under `TriggerPopoverRoot` and renders their selections as inline chips.
 
+### Custom Lexical Plugins
+
+Children of `LexicalComposerInput` render inside the `LexicalComposer` context after the built-in plugins, so standard Lexical plugin components built on `useLexicalComposerContext` work for editor concerns the mention system does not cover, such as paste normalization or length limits. Custom plugins import Lexical APIs directly, so install `lexical` and `@lexical/react` as direct dependencies of your app. The example below registers an update listener that flags messages over a maximum length.
+
+```tsx
+import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import { useEffect } from "react";
+import { $getRoot } from "lexical";
+
+function MaxLengthPlugin({ maxLength }: { maxLength: number }) {
+  const [editor] = useLexicalComposerContext();
+
+  useEffect(() => {
+    return editor.registerUpdateListener(({ editorState }) => {
+      editorState.read(() => {
+        if ($getRoot().getTextContent().length > maxLength) {
+          console.warn(`Message exceeds ${maxLength} characters`);
+        }
+      });
+    });
+  }, [editor, maxLength]);
+
+  return null;
+}
+
+<LexicalComposerInput placeholder="Ask anything...">
+  <MaxLengthPlugin maxLength={2000} />
+</LexicalComposerInput>
+```
+
 ## Rendering Mentions in Messages
 
 Use `DirectiveText` as the `Text` component for user messages so directives render as inline chips instead of raw syntax. See the [Directive Text](/docs/ui/directive-text) guide for setup and customization.

package/.docs/raw/docs/guides/quoting.mdx

@@ -127,7 +127,7 @@ function CustomQuoteDisplay() {
 
 ## Programmatic API
 
-Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread().composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer().setQuote()` when it is rendered inside a thread:
+Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread.composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer.setQuote()` when it is rendered inside a thread:
 
 ```tsx
 import { useAui } from "@assistant-ui/react";
@@ -136,14 +136,14 @@ function MyComponent() {
   const aui = useAui();
 
   const quoteText = () => {
-    aui.thread().composer().setQuote({
+    aui.thread.composer().setQuote({
       text: "The text to quote",
       messageId: "msg-123",
     });
   };
 
   const clearQuote = () => {
-    aui.thread().composer().setQuote(undefined);
+    aui.thread.composer().setQuote(undefined);
   };
 
   return (

package/.docs/raw/docs/guides/resumable-stream-deployment.mdx

@@ -143,7 +143,7 @@ Per-tenant prefixes also make incident response cheaper. A `SCAN MATCH aui:app:t
 
 ## Observability hooks
 
-`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Each hook is invoked synchronously around the underlying store call; throwing inside a hook surfaces as a producer error.
+`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Hook exceptions and rejected promises are reported through `console.error` without affecting stream output or stored lifecycle status.
 
 ```ts title="/lib/resumable-context.ts"
 import { createResumableStreamContext } from "assistant-stream/resumable";
@@ -170,7 +170,7 @@ export const resumableContext = createResumableStreamContext({
 });
 ```
 
-Keep hook bodies cheap. They run on the producer's hot path and any latency they add becomes streaming latency seen by the client.
+Keep synchronous hook work cheap. `onAcquire` runs on the `run()` request path for producers and consumers alike, while the remaining hooks run on the producer's streaming hot path. Returned promises are observed for failures but are not awaited.
 
 ## Resource limits
 

package/.docs/raw/docs/guides/resumable-streams.mdx

@@ -112,7 +112,12 @@ export default function Page() {
       }),
     [],
   );
-  const runtime = useChatRuntime({ transport });
+  const runtime = useChatRuntime({
+    transport,
+    onResumeError: (error) => {
+      console.error("Could not resume the previous response", error);
+    },
+  });
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -122,6 +127,8 @@ export default function Page() {
 }
 ```
 
+`onResumeError` runs when the client finds a stored stream id but the reconnect attempt fails. Use it to show a toast, report telemetry, or mark the thread as needing retry; assistant-ui still clears the stale stream id after the callback runs.
+
 `createResumableSessionStorage` returns a `ResumableClientStorage` backed by `window.sessionStorage`. Pass `{ key }` to namespace per route or per chat surface, or supply your own implementation of the three methods (`getStreamId`, `setStreamId`, `clear`). If you are running on a transport that already wraps `fetch` or `prepareReconnectToStreamRequest`, the `resumable` option composes with your existing handlers.
 
 The default finish detector scans the SSE body for the AI SDK `"type":"finish"` marker. Override `isFinishEvent` on the `resumable` option when you ship a custom encoder.
@@ -208,3 +215,7 @@ Both helpers default to the data-stream encoder; pass `encoder: () => new Assist
 ```sh
 npx assistant-ui create my-app -e with-resumable-stream
 ```
+
+To drop the resumable chat and resume routes into an existing project (in-memory store only; upgrade via [Storage choices](#storage-choices)):
+
+<InstallCommand shadcn={["ai-sdk-backend-resumable"]} />

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

@@ -8,11 +8,13 @@ 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.
 
+Speech is the read-aloud mode: one message at a time, text to audio. For a live duplex conversation, see [Realtime Voice](/docs/guides/voice). For push-to-talk input into the composer, see [Dictation](/docs/guides/dictation).
+
 <SpeechSample />
 
 ## SpeechSynthesisAdapter
 
-The `SpeechSynthesisAdapter` interface has a single method:
+The adapter has a single method. The type lives in `@assistant-ui/core` and is re-exported from `@assistant-ui/react`:
 
 ```tsx
 import type { SpeechSynthesisAdapter } from "@assistant-ui/react";
@@ -22,26 +24,30 @@ type SpeechSynthesisAdapter = {
 };
 ```
 
-`speak` is called with the plain text of an assistant message and must return an `Utterance` object:
+`speak` receives the plain text of an assistant message and returns an `Utterance`:
 
 ```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 };
+namespace SpeechSynthesisAdapter {
+  type Status =
+    | { type: "starting" | "running" }
+    | {
+        type: "ended";
+        reason: "finished" | "cancelled" | "error";
+        error?: unknown;
+      };
+
+  type Utterance = {
+    status: Status;
+    cancel: () => void;
+    subscribe: (callback: () => void) => Unsubscribe;
+  };
+}
 ```
 
-Currently the following built-in adapter is available:
-
-- `WebSpeechSynthesisAdapter`: uses the browser's `Web Speech API` (`SpeechSynthesis`)
-
 ## WebSpeechSynthesisAdapter
 
+The built-in adapter uses the browser's Web Speech API (`SpeechSynthesis` / `SpeechSynthesisUtterance`):
+
 ```tsx
 import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
 
@@ -52,7 +58,9 @@ const runtime = useChatRuntime({
 });
 ```
 
-## UI
+When a speech adapter is provided, `capabilities.speech` is set to `true` automatically.
+
+## UI: ActionBarPrimitive.Speak
 
 The default action bar does not include a speech button. Add `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking` to your assistant message action bar:
 
@@ -79,21 +87,17 @@ const AssistantActionBar = () => {
 };
 ```
 
-`ActionBarPrimitive.Speak` is automatically disabled when no speech adapter is configured.
+`ActionBarPrimitive.Speak` is disabled when no speech adapter is configured. While playback is active, `message.speech` holds the current speech state so the UI can switch to `StopSpeaking`.
 
-## Custom Adapters
+## Custom adapters
 
-Implement `SpeechSynthesisAdapter` to call any external TTS API:
+Implement `SpeechSynthesisAdapter` to call any external TTS provider. Fetch audio from your API, play it with `HTMLAudioElement`, and drive utterance status through `subscribe`:
 
 ```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;
-  }
+  constructor(private apiUrl: string) {}
 
   speak(text: string): SpeechSynthesisAdapter.Utterance {
     const subscribers = new Set<() => void>();
@@ -104,7 +108,10 @@ export class CustomTTSAdapter implements SpeechSynthesisAdapter {
       for (const cb of subscribers) cb();
     };
 
-    const finish = (reason: "finished" | "cancelled" | "error", error?: unknown) => {
+    const finish = (
+      reason: "finished" | "cancelled" | "error",
+      error?: unknown,
+    ) => {
       if (status.type === "ended") return;
       status = { type: "ended", reason, error };
       notify();
@@ -117,17 +124,20 @@ export class CustomTTSAdapter implements SpeechSynthesisAdapter {
     })
       .then((res) => res.blob())
       .then((blob) => {
+        if (status.type === "ended") return;
         audio = new Audio(URL.createObjectURL(blob));
         status = { type: "running" };
         notify();
         audio.onended = () => finish("finished");
         audio.onerror = (e) => finish("error", e);
-        audio.play();
+        audio.play().catch((err) => finish("error", err));
       })
       .catch((err) => finish("error", err));
 
     return {
-      get status() { return status; },
+      get status() {
+        return status;
+      },
       cancel: () => {
         audio?.pause();
         finish("cancelled");
@@ -141,14 +151,22 @@ export class CustomTTSAdapter implements SpeechSynthesisAdapter {
 }
 ```
 
-Wire it up the same way as the built-in adapter:
+Wire it on the same `adapters.speech` slot as the built-in adapter:
 
 ```tsx
 import { CustomTTSAdapter } from "@/lib/custom-tts-adapter";
 
 const runtime = useChatRuntime({
   adapters: {
-    speech: new CustomTTSAdapter({ apiUrl: "/api/tts" }),
+    speech: new CustomTTSAdapter("/api/tts"),
   },
 });
 ```
+
+Use this shape for any provider TTS (OpenAI, ElevenLabs, cloud speech APIs, and so on). Keep the server route responsible for API keys; the adapter only needs a URL that returns audio bytes.
+
+## Related guides
+
+- [Realtime Voice](/docs/guides/voice): duplex voice sessions with `RealtimeVoiceAdapter`, `createVoiceSession`, and the voice UI component.
+- [Dictation](/docs/guides/dictation): speech-to-text into the composer with `DictationAdapter` and `ComposerPrimitive.Dictate`.
+- [Speech and Dictation API reference](/docs/api-reference/voice/speech-dictation): generated type docs.