@assistant-ui/mcp-docs-server 0.1.34 → 0.1.36

package/.docs/raw/docs/guides/headless-composer-input.mdx

@@ -0,0 +1,113 @@
+---
+title: Headless Composer Input
+description: Build a custom composer input while keeping assistant-ui composer state and send gating.
+platforms: ["react"]
+---
+
+`ComposerPrimitive.Input` is still the recommended composer input for most apps. It owns autosize, keyboard shortcuts, IME handling, paste-to-attachment, focus behavior, and trigger-popover keyboard integration.
+
+Use `unstable_useComposerInput` when you already own the input surface, such as a custom editor, a `contentEditable` surface, or a textarea wrapper whose behavior cannot be expressed through `ComposerPrimitive.Input`'s props, `asChild`, or `render` APIs.
+
+<Callout type="warn">
+  This API is marked unstable and may change without notice. It is a thin bridge
+  to composer text and send state, not a replacement implementation of
+  `ComposerPrimitive.Input`.
+</Callout>
+
+## Usage
+
+Render the custom input inside a composer and mirror text changes into the assistant-ui composer state:
+
+```tsx
+"use client";
+
+import {
+  ComposerPrimitive,
+  unstable_useComposerInput,
+  unstable_useTriggerPopoverAriaProps,
+} from "@assistant-ui/react";
+
+function HeadlessComposer() {
+  const composer = unstable_useComposerInput();
+  const popoverAria = unstable_useTriggerPopoverAriaProps();
+
+  return (
+    <ComposerPrimitive.Root>
+      <textarea
+        aria-label="Message"
+        value={composer.value}
+        disabled={composer.isDisabled}
+        onChange={(event) => {
+          composer.setText(event.currentTarget.value);
+        }}
+        onKeyDown={(event) => {
+          if (event.nativeEvent.isComposing) return;
+
+          if (event.key === "Enter" && !event.shiftKey) {
+            event.preventDefault();
+
+            if (composer.canSend) {
+              composer.send();
+            }
+          }
+        }}
+        {...popoverAria}
+      />
+      <ComposerPrimitive.Send />
+    </ComposerPrimitive.Root>
+  );
+}
+```
+
+`composer.send()` exposes the same send action used by `ComposerPrimitive.Send`, including send options such as `composer.send({ steer: true })`. It is a no-op unless `composer.canSend` is `true`; check `canSend` in custom keyboard handlers to keep your event handling explicit.
+
+## Hook Result
+
+| Field | Description |
+| --- | --- |
+| `value` | Current composer text. Returns `""` when the composer is not editing. |
+| `setText(text)` | Writes text into the composer while it is editing. |
+| `send(options?)` | Sends the current composer message when `canSend` is `true`; otherwise a no-op. |
+| `isDisabled` | Combines the hook's `disabled` option with assistant-ui disabled sources, such as thread disabled state and active dictation input lock. |
+| `canSend` | Matches `ComposerPrimitive.Send` gating, then also respects `isDisabled`. |
+
+Pass `disabled` when your editor has an additional read-only state:
+
+```tsx
+const composer = unstable_useComposerInput({
+  disabled: editorReadOnly,
+});
+```
+
+## What You Still Own
+
+The hook does not recreate the behavior of `ComposerPrimitive.Input`. Your input or editor remains responsible for:
+
+- Enter/newline shortcuts, steer shortcuts, escape/cancel behavior, and any other keyboard behavior.
+- IME and composition handling.
+- Cursor and selection tracking.
+- Autosize and focus management.
+- Paste/drop attachment behavior.
+- Rich text state, serialization, and DOM synchronization for `contentEditable` or editor-library integrations.
+
+For styled textareas, prefer `ComposerPrimitive.Input`. Reach for the headless hook when the editor has its own model or DOM lifecycle and assistant-ui should only supply composer state and send gating.
+
+## Trigger Popovers
+
+`unstable_useTriggerPopoverAriaProps` returns the combobox ARIA attributes for the currently open trigger popover:
+
+```tsx
+const popoverAria = unstable_useTriggerPopoverAriaProps();
+
+<textarea {...popoverAria} />;
+```
+
+Spread these props last so they can mirror `ComposerPrimitive.Input` when a popover is open.
+
+This helper only describes the open popover to assistive technology. It does not wire a custom editor into mention or slash-command keyboard handling, cursor tracking, or item insertion. For the full built-in trigger-popover experience, use `ComposerPrimitive.Input`; for richer editors, integrate the trigger UI with the editor's own selection and keyboard model.
+
+## Related
+
+- [Composer primitives](/docs/primitives/composer)
+- [Composer Trigger Popover](/docs/ui/composer-trigger-popover)
+- [Input History](/docs/guides/input-history)

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

@@ -68,6 +68,9 @@ Render specialized message content.
   <Card title="LaTeX" href="/docs/guides/latex">
     Render math via React Markdown or Streamdown, with streaming-safe escape rules.
   </Card>
+  <Card title="Thread Virtualization" href="/docs/guides/virtualization">
+    Render very long threads with @tanstack/react-virtual and per-index message rendering.
+  </Card>
 </Cards>
 
 ## Audio

package/.docs/raw/docs/guides/input-history.mdx

@@ -0,0 +1,55 @@
+---
+title: Input History
+description: Terminal-style ArrowUp/ArrowDown recall of previously sent messages in the assistant-ui React composer.
+platforms: ["react"]
+---
+
+Input history lets users press ArrowUp in an empty composer to recall previously sent messages, newest first, like a shell prompt. ArrowDown steps back toward the newest entry and finally restores the draft that was being typed when browsing started.
+
+<Callout type="warn">
+  This API is marked unstable and may change without notice.
+</Callout>
+
+## Usage
+
+Spread the hook's bundle onto `ComposerPrimitive.Input`:
+
+```tsx
+import {
+  ComposerPrimitive,
+  unstable_useComposerInputHistory,
+} from "@assistant-ui/react";
+
+const Composer = () => {
+  const history = unstable_useComposerInputHistory();
+
+  return (
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input {...history} />
+      <ComposerPrimitive.Send />
+    </ComposerPrimitive.Root>
+  );
+};
+```
+
+The history ring is derived live from the current thread's user messages (trimmed, with adjacent duplicates collapsed), so it needs no persistence or configuration.
+
+## Behavior
+
+- ArrowUp starts recall only when the composer is empty (whitespace-only drafts count as empty and are restored on the way back down).
+- While a recalled multi-line message is shown, arrows move the caret line by line; recall only steps when the caret is on the first line (ArrowUp) or last line (ArrowDown).
+- An open mention or slash-command popover keeps owning the arrow keys; the hook yields whenever a trigger popover is active.
+- IME composition, modifier keys, text selections, and events a preceding handler already `preventDefault`ed are left untouched.
+- Switching threads or sending a message resets the browse position.
+- The hook is inert on edit composers.
+
+To interleave your own ArrowUp handling ahead of history (for example, stepping through queued messages), compose your handler before the hook's and call `preventDefault` when you consume the key:
+
+```tsx
+<ComposerPrimitive.Input
+  onKeyDown={(e) => {
+    myHandler(e);
+    history.onKeyDown(e);
+  }}
+/>
+```

package/.docs/raw/docs/guides/latex.mdx

@@ -106,47 +106,53 @@ By default, remark-math (react-markdown path) supports:
 
 ## Supporting Alternative LaTeX Delimiters
 
-Many language models generate LaTeX using different delimiter formats:
-- `\(...\)` for inline math
-- `\[...\]` for display math
-- Custom formats like `[/math]...[/math]`
+Many language models emit math in delimiters that remark-math does not recognize:
+- `\(...\)` for inline math and `\[...\]` for display math
+- custom tags like `[/math]...[/math]` and `[/inline]...[/inline]`
 
-You can use the `preprocess` prop on `MarkdownTextPrimitive` to normalize these formats before parsing:
+`@assistant-ui/react-markdown` exports `normalizeMathDelimiters`, which rewrites these to the `$...$` and `$$...$$` form remark-math parses. Pass it to the `preprocess` prop of `MarkdownTextPrimitive`:
 
 ```tsx title="/components/assistant-ui/markdown-text.tsx"
-import { MarkdownTextPrimitive } from "@assistant-ui/react-markdown";
+import {
+  MarkdownTextPrimitive,
+  normalizeMathDelimiters, // [!code ++]
+} from "@assistant-ui/react-markdown";
 
 const MarkdownTextImpl = () => {
   return (
     <MarkdownTextPrimitive
       remarkPlugins={[remarkGfm, remarkMath]}
       rehypePlugins={[rehypeKatex]}
-      preprocess={normalizeCustomMathTags} // [!code ++]
+      preprocess={normalizeMathDelimiters} // [!code ++]
       className="aui-md"
       components={defaultComponents}
     />
   );
 };
+```
 
-// Your LaTeX preprocessing function
-function normalizeCustomMathTags(input: string): string {
-  return (
-    input
-      // Convert [/math]...[/math] to $$...$$
-      .replace(/\[\/math\]([\s\S]*?)\[\/math\]/g, (_, content) => `$$${content.trim()}$$`)
+The individual transforms `rewriteLatexBracketDelimiters` and `rewriteCustomMathTags` are exported too, for finer control over which delimiters are normalized.
+
+<Callout type="info">
+  Using [Streamdown](/docs/ui/streamdown) as your renderer? The same helpers are exported from `@assistant-ui/react-streamdown` and accepted by the `preprocess` prop of `StreamdownTextPrimitive`.
+</Callout>
 
-      // Convert [/inline]...[/inline] to $...$
-      .replace(/\[\/inline\]([\s\S]*?)\[\/inline\]/g, (_, content) => `$${content.trim()}$`)
+### Currency amounts
 
-      // Convert \( ... \) to $...$ (inline math) - handles both single and double backslashes
-      .replace(/\\{1,2}\(([\s\S]*?)\\{1,2}\)/g, (_, content) => `$${content.trim()}$`)
+With single-dollar inline math enabled (the default on the react-markdown path), remark-math reads a lone `$` as a math delimiter, so prose such as `$5 ... $10` is parsed as math. `escapeCurrencyDollars` escapes a `$` immediately followed by a digit so currency survives, while leaving the `$$` of display math intact. Compose it with the delimiter normalization:
 
-      // Convert \[ ... \] to $$...$$ (block math) - handles both single and double backslashes
-      .replace(/\\{1,2}\[([\s\S]*?)\\{1,2}\]/g, (_, content) => `$$${content.trim()}$$`)
-  );
-}
+```tsx title="/components/assistant-ui/markdown-text.tsx"
+import {
+  normalizeMathDelimiters,
+  escapeCurrencyDollars, // [!code ++]
+} from "@assistant-ui/react-markdown";
+
+<MarkdownTextPrimitive
+  preprocess={(text) => escapeCurrencyDollars(normalizeMathDelimiters(text))} // [!code ++]
+  // ...
+/>;
 ```
 
 <Callout type="tip">
-Inside `MarkdownTextPrimitive`, the streamed text first passes through `preprocess` (delimiter normalization) and then through `useSmooth` (character-by-character accumulation), and only then reaches the markdown parser. Both run before remark-math sees the text, so delimiter replacement and the streaming smoothing are streaming-safe — partially-received delimiters are accumulated in the smoothing buffer rather than parsed mid-fragment.
+Inside `MarkdownTextPrimitive`, the streamed text first passes through `preprocess` (delimiter normalization) and then through `useSmooth` (character by character accumulation), and only then reaches the markdown parser. Both run before remark-math sees the text, so delimiter replacement and the streaming smoothing stay streaming safe; a partially received delimiter is accumulated in the smoothing buffer rather than parsed mid fragment.
 </Callout>

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

@@ -8,12 +8,9 @@ Mentions let users type `@` in the composer to open a popover picker, select an
 
 ## How It Works
 
-```
-User types "@"  →  Trigger detected  →  Adapter provides categories/items
-                                              ↓
-              Directive inserted  ←  User selects item from popover
-                   ↓
-         Message sent with ":tool[Label]{name=id}" in text
+```mermaid
+flowchart LR
+    type["User types @"] --> trigger["Trigger detected"] --> adapter["Adapter provides<br/>categories / items"] --> select["User selects item<br/>from popover"] --> insert["Directive inserted"] --> sent["Message sent with<br/>:tool[Label]{name=id} text"]
 ```
 
 The mention system has three layers:
@@ -85,7 +82,35 @@ const myAdapter: Unstable_TriggerAdapter = {
 
 ### Async Mention Search
 
-The adapter interface is synchronous, but the data it reads can come from any async source. Load results into React state (or a query cache) and read the current snapshot inside the adapter methods. The adapter re-creates on each render, so the popover always sees the latest results.
+The built-in `unstable_useLiveCompletionAdapter` wraps an async fetcher with debouncing, stale-request cancellation (results for an outdated query are dropped), and a single-entry cache. Its `search` returns the last results synchronously and schedules a debounced fetch when the query changes; when results arrive the returned `adapter` re-creates, which re-runs the popover lookup so the fresh items render. It also reports `isLoading`, which you pass to the popover to show a loading state.
+
+```tsx
+import {
+  unstable_useLiveCompletionAdapter,
+  unstable_defaultDirectiveFormatter,
+} from "@assistant-ui/react";
+import { ComposerTriggerPopover } from "@/components/assistant-ui/composer-trigger-popover";
+
+function MentionPopover() {
+  const mentions = unstable_useLiveCompletionAdapter({
+    fetcher: async (query) => {
+      const users = await fetchUsers(query);
+      return users.map((u) => ({ id: u.id, type: "user", label: u.name }));
+    },
+  });
+
+  return (
+    <ComposerTriggerPopover
+      char="@"
+      adapter={mentions.adapter}
+      isLoading={mentions.isLoading}
+      directive={{ formatter: unstable_defaultDirectiveFormatter }}
+    />
+  );
+}
+```
+
+The adapter interface is itself synchronous, so you can also wire async data by hand when you need a custom cache, no debounce, or an existing query client. Load results into React state (or a query cache) and read the current snapshot inside the adapter methods. The adapter re-creates on each render, so the popover always sees the latest results.
 
 **With React state and `useEffect`:**
 

package/.docs/raw/docs/guides/slash-commands.mdx

@@ -8,12 +8,9 @@ Slash commands let users type `/` in the composer to open a popover, browse avai
 
 ## How It Works
 
-```
-User types "/"  →  Trigger detected  →  Adapter provides commands
-                                              ↓
-              Callback fired  ←  User selects command from popover
-                   ↓
-       Directive chip left in composer (or removed if removeOnExecute)
+```mermaid
+flowchart LR
+    type["User types /"] --> trigger["Trigger detected"] --> adapter["Adapter provides<br/>commands"] --> select["User selects command<br/>from popover"] --> callback["Callback fired"] --> chip["Directive chip left in composer<br/>(or removed if removeOnExecute)"]
 ```
 
 The slash command system is built on the same [trigger popover architecture](#trigger-popover-architecture) as mentions. A slash command declares its behavior with a `<TriggerPopover.Action>` sub-primitive whose `onExecute` callback fires when an item is chosen.

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

@@ -57,24 +57,22 @@ const runtime = useChatRuntime({
 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 { ActionBarPrimitive, AuiIf } from "@assistant-ui/react";
 import { AudioLinesIcon, StopCircleIcon } from "lucide-react";
 
 const AssistantActionBar = () => {
-  const isSpeaking = useMessageTTS();
-
   return (
     <ActionBarPrimitive.Root>
-      {!isSpeaking && (
+      <AuiIf condition={(s) => s.message.speech == null}>
         <ActionBarPrimitive.Speak>
           <AudioLinesIcon />
         </ActionBarPrimitive.Speak>
-      )}
-      {isSpeaking && (
+      </AuiIf>
+      <AuiIf condition={(s) => s.message.speech != null}>
         <ActionBarPrimitive.StopSpeaking>
           <StopCircleIcon />
         </ActionBarPrimitive.StopSpeaking>
-      )}
+      </AuiIf>
       <ActionBarPrimitive.Copy />
     </ActionBarPrimitive.Root>
   );

package/.docs/raw/docs/guides/virtualization.mdx

@@ -0,0 +1,133 @@
+---
+title: Thread Virtualization
+description: Render very long threads with @tanstack/react-virtual, with ThreadPrimitive.Unstable_MessageById and ThreadPrimitive.MessageByIndex.
+platforms: ["react"]
+---
+
+Virtualization mounts only the messages near the viewport and represents the rest as empty space, so a thread with thousands of messages scrolls like one with twenty. assistant-ui does not ship a virtualized thread component; this guide shows the supported composition, extracted from a production consumer and available as a runnable example: [`examples/with-virtualized-thread`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-virtualized-thread).
+
+## Do you need this?
+
+Probably not. The default kit already renders message bodies with `content-visibility: auto` and `contain-intrinsic-size`, which skips paint work for off-screen messages, and `ThreadPrimitive.Viewport` handles auto-scroll. That covers typical threads. Reach for virtualization when React mount and update cost itself becomes the bottleneck: threads with hundreds to thousands of messages, or very heavy per-message content, where typing latency degrades because every message stays mounted.
+
+## Rendering Messages By Id
+
+For virtualized rows, use message ids as the row identity. `unstable_useThreadMessageIds` returns the thread's ids with stable array identity across content-only updates, and `ThreadPrimitive.Unstable_MessageById` renders one message with the same `components` surface as `MessageByIndex`. Unknown ids render `null`, which is useful when a virtual row unmounts after a message was removed.
+
+```tsx
+const MESSAGE_COMPONENTS = { UserMessage, AssistantMessage };
+
+const messageIds = unstable_useThreadMessageIds();
+
+return messageIds.map((messageId) => (
+  <ThreadPrimitive.Unstable_MessageById
+    key={messageId}
+    messageId={messageId}
+    components={MESSAGE_COMPONENTS}
+  />
+));
+```
+
+<Callout type="warn">
+  `unstable_useThreadMessageIds` and `ThreadPrimitive.Unstable_MessageById` are
+  experimental and may change in any release.
+</Callout>
+
+## Rendering Messages By Index
+
+`ThreadPrimitive.MessageByIndex` is still supported and is the smaller API when
+you already have a stable index from a fixed-order list. It renders a single
+message at that index and memoizes on the index plus the per-field `components`
+identity:
+
+```tsx
+const MESSAGE_COMPONENTS = { UserMessage, AssistantMessage };
+
+<ThreadPrimitive.MessageByIndex index={index} components={MESSAGE_COMPONENTS} />;
+```
+
+For virtualizers, prefer the id-based API above when you can. Index rows are more
+fragile when messages are inserted, removed, reordered, or when a virtual row
+briefly outlives the item it was created for.
+
+## Grouping into turns
+
+The example virtualizes per user turn (a user message plus the responses that follow it), which gives the virtualizer stable, meaningfully sized items. Keep the id and role together in a stable row shape so the turn array only rebuilds when message membership or roles change:
+
+```tsx
+type MessageRow = {
+  id: string;
+  role: "user" | "assistant" | "system";
+};
+
+const useThreadMessageRows = (): readonly MessageRow[] => {
+  const prevRowsRef = useRef<readonly MessageRow[]>([]);
+
+  return useAuiState((s) => {
+    const messages = s.thread.messages;
+    const prev = prevRowsRef.current;
+    if (
+      prev.length === messages.length &&
+      prev.every((row, index) => {
+        const message = messages[index]!;
+        return row.id === message.id && row.role === message.role;
+      })
+    ) {
+      return prev;
+    }
+
+    const next = messages.map(({ id, role }) => ({ id, role }));
+    prevRowsRef.current = next;
+    return next;
+  });
+};
+
+const messageRows = useThreadMessageRows();
+const turns = useMemo(
+  () => buildTurns(messageRows),
+  [messageRows],
+);
+```
+
+Then each virtual turn renders the ids it owns:
+
+```tsx
+{turn.messageIds.map((messageId) => (
+  <ThreadPrimitive.Unstable_MessageById
+    key={messageId}
+    messageId={messageId}
+    components={MESSAGE_COMPONENTS}
+  />
+))}
+```
+
+## Padding spacers, not absolute positioning
+
+Render the virtual items in normal document flow inside a spacer div whose `paddingTop`/`paddingBottom` represent the unmounted regions. Items remain regular flow children, so message CSS (including `position: sticky` patterns and the kit styling) keeps working, and `virtualizer.measureElement` records real heights as items mount:
+
+```tsx
+const items = virtualizer.getVirtualItems();
+const paddingTop = items[0]?.start ?? 0;
+const paddingBottom = Math.max(
+  0,
+  virtualizer.getTotalSize() - (items.at(-1)?.end ?? 0),
+);
+```
+
+## Owning the scroll element
+
+The composition owns its scroll container instead of using `ThreadPrimitive.Viewport`: the built-in auto-scroll assumes every message is mounted, and its resize-driven re-pin can fight the virtualizer's measurement adjustments. Three pieces replace it:
+
+1. **Auto-follow.** A ResizeObserver on the content wrapper re-pins the scroller to the bottom while a sticky flag is armed. The flag disarms when the user scrolls up (detected as `scrollTop` decreasing while `scrollHeight` and `clientHeight` are stable, the same heuristic the built-in viewport uses, plus wheel-up and touchmove) and re-arms when the user returns to the bottom.
+2. **Measurement guard.** While pinned at the bottom, the virtualizer's own scroll adjustments on item re-measurement are suppressed via a custom `scrollToFn`; without this the two scroll writers fight and the view rubber-bands during streaming.
+3. **Run-start jump.** A `useLayoutEffect` observes `s.thread.isRunning` flipping to true and jumps to the bottom before paint, so a just-sent message never flashes below the fold. The `thread.runStart` event is deprecated; deriving the transition from state is the supported path.
+
+The production consumer this is extracted from disables streaming auto-follow entirely as a product choice; the example keeps following because it matches `ThreadPrimitive.Viewport`'s default behavior. Both are valid, and the disarm guard makes either safe.
+
+## Try it
+
+```sh
+npx assistant-ui@latest create my-app
+```
+
+Then copy `app/VirtualizedThread.tsx`, `app/MyRuntimeProvider.tsx`, and `app/seed-messages.ts` from [the example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-virtualized-thread), or clone the repo and run `pnpm --filter with-virtualized-thread dev`.

package/.docs/raw/docs/guides/voice.mdx

@@ -156,8 +156,9 @@ class MyVoiceAdapter implements RealtimeVoiceAdapter {
 
 The session status follows the same pattern as other adapters:
 
-```
-starting → running → ended
+```mermaid
+flowchart LR
+    starting["starting"] --> running["running"] --> ended["ended"]
 ```
 
 The `ended` status includes a `reason`:

package/.docs/raw/docs/ink/hooks.mdx

@@ -62,7 +62,7 @@ useAuiEvent("thread.runStart", (payload) => {
 
 ### useNotification
 
-Ring the terminal bell and emit an OSC desktop notification when the assistant finishes a run, stops with an error, or pauses for human approval.
+Ring the terminal bell and emit an OSC desktop notification when the assistant finishes a run, stops with an error, or pauses for user input.
 
 ```tsx
 import { useNotification } from "@assistant-ui/react-ink";
@@ -130,7 +130,7 @@ const runtime = useLocalRuntime(chatModel, {
 | `adapters.feedback` | `FeedbackAdapter` | Adapter for message feedback (thumbs up/down) |
 | `adapters.suggestion` | `SuggestionAdapter` | Adapter for suggested prompts |
 | `cloud` | `AssistantCloud` | Cloud instance for thread persistence via `@assistant-ui/cloud` |
-| `unstable_humanToolNames` | `string[]` | Tool names that trigger a run interruption to wait for human/external approval |
+| `unstable_humanToolNames` | `string[]` | Tool names that pause the run until a result is added via `addResult` |
 
 ### useRemoteThreadListRuntime
 

package/.docs/raw/docs/integrations/attachments/custom-adapter.mdx

@@ -9,18 +9,10 @@ For the adapter contract itself, see [adapters](/docs/runtimes/concepts/adapters
 
 ## How it works
 
-```
-composer add  ──►  POST /api/upload (presign)  ──►  PUT to object storage
-                                                    │
-                                                    ▼
-                                    PendingAttachment with the public URL
-                                                    │
-composer send  ◄────────────────────────────────────┘
-                   │
-                   └─►  send() emits a content part with the URL
-                                                    │
-                                                    ▼
-                                                AI SDK passes URL to the model
+```mermaid
+flowchart LR
+    add["composer add"] --> presign["POST /api/upload<br/>(presign)"] --> put["PUT to object storage"] --> pending["PendingAttachment<br/>with the public URL"]
+    pending --> send["composer send"] --> part["send() emits a<br/>content part with the URL"] --> model["AI SDK passes<br/>URL to the model"]
 ```
 
 Three ideas to internalize before reading the code:

package/.docs/raw/docs/integrations/auth/better-auth.mdx

@@ -9,16 +9,13 @@ This page covers the non-cloud path. AssistantCloud users should see [cloud auth
 
 ## How it works
 
-```
-browser  ──►  /api/auth/[...all]  ──►  better-auth handlers
-              /api/chat                 │
-              /api/threads/*            │
-                  │                     │
-                  ▼                     ▼
-         auth.api.getSession({ headers })  ──►  session.user.id
-                                                     │
-                                                     ▼
-                                          scope queries by userId
+```mermaid
+flowchart LR
+    browser["browser"] --> routes["/api/auth/[...all]<br/>/api/chat<br/>/api/threads/*"]
+    routes --> handlers["better-auth handlers"]
+    routes --> session["auth.api.getSession({ headers })"]
+    handlers --> session
+    session --> uid["session.user.id"] --> scope["scope queries by userId"]
 ```
 
 Three integration points:

package/.docs/raw/docs/integrations/auth/clerk.mdx

@@ -9,15 +9,9 @@ If you use AssistantCloud, see [cloud authorization](/docs/cloud/authorization)
 
 ## How it works
 
-```
-browser  ──►  clerkMiddleware (proxy.ts)  ──►  /api/chat
-                                               /api/threads/*
-                                                   │
-                                                   ▼
-                                          auth() returns { userId }
-                                                   │
-                                                   ▼
-                                       scope queries by userId
+```mermaid
+flowchart LR
+    browser["browser"] --> mw["clerkMiddleware<br/>(proxy.ts)"] --> routes["/api/chat<br/>/api/threads/*"] --> auth["auth() returns { userId }"] --> scope["scope queries by userId"]
 ```
 
 Three places Clerk touches the integration:

package/.docs/raw/docs/integrations/auth/next-auth.mdx

@@ -9,14 +9,9 @@ If you use AssistantCloud, see [cloud authorization](/docs/cloud) instead; cloud
 
 ## How it works
 
-```
-browser  ──►  /api/chat               ──►  auth() returns session
-              /api/threads/*               │
-                                           ▼
-                                  scope queries by session.user.id
-                                           │
-                                           ▼
-                                       database
+```mermaid
+flowchart LR
+    browser["browser"] --> routes["/api/chat<br/>/api/threads/*"] --> auth["auth() returns session"] --> scope["scope queries by<br/>session.user.id"] --> db["database"]
 ```
 
 Three places auth touches the integration:

package/.docs/raw/docs/integrations/frameworks/ai-sdk.mdx

@@ -13,11 +13,14 @@ If you arrived here looking to wire up your first chat: jump to [AI SDK v6 quick
 
 ## Where it slots in
 
-```
-client  ──►  useChatRuntime (react-ai-sdk)  ──►  /api/chat (streamText)  ──►  provider
-                │
-                └─ thread state, tool calls, attachments,
-                   speech / dictation / feedback adapters
+```mermaid
+flowchart LR
+    client["client"]
+    runtime["useChatRuntime (react-ai-sdk)<br/>(thread state · tool calls · attachments<br/>speech · dictation · feedback adapters)"]
+    api["/api/chat<br/>(streamText)"]
+    provider["provider"]
+
+    client --> runtime --> api --> provider
 ```
 
 `@assistant-ui/react-ai-sdk` wraps the AI SDK's `useChat` hook and exposes it as an assistant-ui runtime. The runtime owns conversation state on the client; your `/api/chat` route returns a UI message stream from `streamText`. Everything else (tools, attachments, observability, gateways, custom persistence) layers on top of this base.