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

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

@@ -1,6 +1,6 @@
 ---
 title: Thread Virtualization
-description: Render very long threads with @tanstack/react-virtual and ThreadPrimitive.MessageByIndex.
+description: Render very long threads with @tanstack/react-virtual, with ThreadPrimitive.Unstable_MessageById and ThreadPrimitive.MessageByIndex.
 platforms: ["react"]
 ---
 
@@ -10,9 +10,35 @@ Virtualization mounts only the messages near the viewport and represents the res
 
 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 index
+## Rendering Messages By Id
 
-`ThreadPrimitive.MessageByIndex` renders a single message at a given index and memoizes on the index plus per-field `components` identity. Pass a module-level components object so the memo holds and a streaming delta only re-renders the message it belongs to:
+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 };
@@ -20,15 +46,59 @@ 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
 
-Virtualizing per user turn (a user message plus the responses that follow it) gives the virtualizer stable, meaningfully sized items. Subscribe to a single signature string so the selector returns a primitive and the turn array only rebuilds when membership actually changes:
+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
-const signature = useAuiState((s) =>
-  s.thread.messages.map((m, i) => `${i}:${m.role}:${m.id}`).join("\n"),
+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],
 );
-const turns = useMemo(() => buildTurns(signature), [signature]);
+```
+
+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

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/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

@@ -5,7 +5,7 @@ description: Wire the Vercel AI SDK into a React chat UI with assistant-ui — u
 
 import { VercelIcon } from "@/components/icons/vercel";
 
-[Vercel AI SDK](https://ai-sdk.dev/) is the most common framework people pair with assistant-ui. The full setup, attachments, persistence, tool-call patterns, and version notes are documented under [runtimes/ai-sdk](/docs/runtimes/ai-sdk); this page is the entry point in the integrations tree for discoverability and architecture context.
+[Vercel AI SDK](https://ai-sdk.dev/) is the most common framework people pair with assistant-ui. The full setup, attachments, persistence, tool-call patterns, and version notes are documented under [runtimes/ai-sdk](/docs/runtimes/ai-sdk/overview); this page is the entry point in the integrations tree for discoverability and architecture context.
 
 <Callout type="info">
 If you arrived here looking to wire up your first chat: jump to [AI SDK v6 quickstart](/docs/runtimes/ai-sdk/v6). This page is a high-level pointer.
@@ -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.
@@ -55,7 +58,7 @@ AI SDK is the default choice for new projects on Next.js, Remix, or any framewor
 - You will compose with a framework like [Mastra](/docs/integrations/frameworks/mastra/overview), an [observability tool](/docs/integrations/observability/helicone), an [LLM gateway](/docs/integrations/gateways), or [tools through MCP](/docs/tools/mcp), all of which assume an AI SDK route.
 - You want first-party `frontendTools`, attachments, multi-step tool calls, token-usage metadata, and persisted history via `withFormat`.
 
-If you need streaming agent state (subgraph events, generative UI messages), look at [LangGraph](/docs/runtimes/langgraph) instead. If you have a different protocol-shaped backend (A2A, AG-UI, OpenCode), see [pick a runtime](/docs/runtimes/pick-a-runtime).
+If you need streaming agent state (subgraph events, generative UI messages), look at [LangGraph](/docs/runtimes/langgraph/overview) instead. If you have a different protocol-shaped backend (A2A, AG-UI, OpenCode), see [pick a runtime](/docs/runtimes/pick-a-runtime).
 
 ## Related
 
@@ -64,7 +67,7 @@ If you need streaming agent state (subgraph events, generative UI messages), loo
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime overview"
     description="The full runtime documentation and version selector."
-    href="/docs/runtimes/ai-sdk"
+    href="/docs/runtimes/ai-sdk/overview"
   />
   <Card
     title="Pick a runtime"

package/.docs/raw/docs/integrations/index.mdx

@@ -15,18 +15,11 @@ Integrations are wiring guides for using third-party services with assistant-ui,
 
 ## Where integrations slot in
 
-```
-client  ──►  your API route  ──►  LLM provider
-                │                    ▲
-                │                    │
-     agent      │                    │  observability
-     frameworks │                    │  proxies
-     (e.g.      │                    │  (e.g. Helicone,
-     Mastra)    │                    │   Langfuse)
-                ▼                    │
-          run on the server,         │
-          then forward calls   ──────┘
-          to the provider
+```mermaid
+flowchart LR
+    client["client"] --> route["your API route"] --> provider["LLM provider"]
+    route -->|"agent frameworks (e.g. Mastra)"| server["run on the server,<br/>then forward calls"]
+    server -->|"observability proxies (e.g. Helicone, Langfuse)"| provider
 ```
 
 Integrations live on the server. **Agent frameworks** like Mastra take over the API route. **Gateways** swap the upstream provider URL. **Observability** logs or traces every call. **Auth** gates the route and scopes per-user data. **Persistence** and **attachments** are adapter recipes for storing chat data outside the default in-memory path.
@@ -165,7 +158,7 @@ Upload chat attachments to object storage instead of inlining as data URLs.
 assistant-ui doesn't ship a guide for every tool, but most fit one of two patterns:
 
 - **Routes through your AI SDK handler** (agent frameworks, observability proxies, gateways): adapt the [Mastra full-stack](/docs/integrations/frameworks/mastra/full-stack) or [Helicone proxy](/docs/integrations/observability/helicone) pattern using the service's own SDK.
-- **Replaces the runtime entirely** (custom backends): see [custom backend](/docs/runtimes/custom).
+- **Replaces the runtime entirely** (custom backends): see [custom backend](/docs/runtimes/custom/overview).
 
 If you build something useful, [open an issue](https://github.com/assistant-ui/assistant-ui/issues) or post in [Discord](https://discord.gg/S9dwgCNEFs); the docs are open to contributions.
 

package/.docs/raw/docs/integrations/observability/helicone.mdx

@@ -11,10 +11,9 @@ Helicone is independent of which assistant-ui runtime you use. It slots in at th
 
 ## How it works
 
-```
-your server  ──►  Helicone proxy  ──►  OpenAI / Anthropic / etc.
-                  │
-                  └─ logs request, response, tokens, cost
+```mermaid
+flowchart LR
+    server["your server"] --> proxy["Helicone proxy<br/>(logs request, response, tokens, cost)"] --> provider["OpenAI / Anthropic / etc."]
 ```
 
 Calls pass through Helicone's edge before reaching the upstream provider. The proxy is transparent: response shape and streaming behavior are unchanged, you just gain a dashboard of every call.

package/.docs/raw/docs/integrations/observability/langfuse.mdx

@@ -13,11 +13,9 @@ Pick Langfuse when you want to see the agent's full call tree inside a single tu
 
 ## How it works
 
-```
-your route  ──►  AI SDK streamText (with experimental_telemetry)
-                  │
-                  ▼
-                  OpenTelemetry SDK  ──►  LangfuseSpanProcessor  ──►  Langfuse
+```mermaid
+flowchart LR
+    route["your route"] --> stream["AI SDK streamText<br/>(experimental_telemetry)"] --> otel["OpenTelemetry SDK"] --> proc["LangfuseSpanProcessor"] --> langfuse["Langfuse"]
 ```
 
 Langfuse subscribes to OpenTelemetry spans the AI SDK already emits when telemetry is enabled. No proxy, no wrapping; the SDK ships spans and Langfuse renders them.

package/.docs/raw/docs/integrations/observability/langsmith.mdx

@@ -9,14 +9,15 @@ import { VercelIcon } from "@/components/icons/vercel";
 
 [LangSmith](https://www.langchain.com/langsmith) is LangChain's observability and eval platform. If you are already in the LangChain or LangGraph ecosystem, LangSmith is the natural pairing: traces, datasets, prompt versioning, and LLM-as-judge evals share state with the rest of the LangChain stack.
 
-This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph), tracing flows through LangGraph Cloud automatically; you only need this guide when your route handler talks to AI SDK directly.
+This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview), tracing flows through LangGraph Cloud automatically; you only need this guide when your route handler talks to AI SDK directly.
 
 ## How it works
 
 LangSmith provides a wrapper around the `ai` namespace. You call `wrapAISDK(ai)`, get back the same exports (`generateText`, `streamText`, `generateObject`, `streamObject`), and use those in place of the originals. Every call is then traced.
 
-```
-your route  ──►  wrapped streamText  ──►  LangSmith client  ──►  LangSmith
+```mermaid
+flowchart LR
+    route["your route"] --> stream["wrapped streamText"] --> client["LangSmith client"] --> langsmith["LangSmith"]
 ```
 
 ## Setup
@@ -133,7 +134,7 @@ Send a message. The trace should appear in your LangSmith project within seconds
     icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
     title="LangGraph runtime"
     description="If your backend is LangGraph, tracing flows through LangGraph Cloud automatically."
-    href="/docs/runtimes/langgraph"
+    href="/docs/runtimes/langgraph/overview"
   />
   <Card
     icon={<LangfuseIcon width={20} height={20} />}

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

@@ -18,9 +18,10 @@ If you're rolling your own auth, replace `auth()` calls with whatever your stack
 
 ## How it works
 
-```
-client  ──►  /api/threads/*   (RemoteThreadListAdapter)  ──►  threads table
-             /api/messages/*  (ThreadHistoryAdapter)     ──►  messages table
+```mermaid
+flowchart LR
+    client["client"] --> threads["/api/threads/*<br/>(RemoteThreadListAdapter)"] --> tt["threads table"]
+    client --> messages["/api/messages/*<br/>(ThreadHistoryAdapter)"] --> mt["messages table"]
 ```
 
 Two adapters, two tables:

package/.docs/raw/docs/migrations/react-langgraph-v0-7.mdx

@@ -323,6 +323,6 @@ export function Provider({ children }) {
 ## Need Help?
 
 If you encounter issues during migration:
-1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph)
+1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph/overview)
 2. Review the [example implementation](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)
-3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)
+3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)

package/.docs/raw/docs/primitives/composer.mdx

@@ -103,6 +103,14 @@ import { ComposerPrimitive } from "@assistant-ui/react";
 
 The primitive's behavior (keyboard handling, disabled state, form submission) is merged onto your element. Your styles, your component, primitive wiring.
 
+<Callout type="info">
+Own the input DOM entirely, such as a `contentEditable` surface or editor
+library that cannot be expressed through `asChild` or `render`? See
+[Headless Composer Input](/docs/guides/headless-composer-input) for the
+unstable hook that supplies composer text and send gating without
+`ComposerPrimitive.Input`.
+</Callout>
+
 ### Unstable Trigger Popovers
 
 Composer includes an unstable **trigger popover** system for character-triggered popovers (e.g. `@` for mentions, `/` for slash commands). Multiple triggers coexist under a single `TriggerPopoverRoot`.

package/.docs/raw/docs/primitives/thread-list.mdx

@@ -38,12 +38,12 @@ function MyThreadList() {
 
 function ThreadListItem() {
   return (
-    <ThreadListItemPrimitive.Root className="group flex h-9 items-center rounded-lg hover:bg-muted data-active:bg-muted">
-      <ThreadListItemPrimitive.Trigger className="flex-1 truncate px-3 text-sm">
+    <ThreadListItemPrimitive.Root className="group relative flex h-9 items-center rounded-lg hover:bg-muted data-active:bg-muted has-focus-visible:bg-muted">
+      <ThreadListItemPrimitive.Trigger className="min-w-0 flex-1 truncate px-3 text-sm outline-none">
         <ThreadListItemPrimitive.Title fallback="New Chat" />
       </ThreadListItemPrimitive.Trigger>
-      <ThreadListItemMorePrimitive.Root>
-        <ThreadListItemMorePrimitive.Trigger className="mr-2 size-7 rounded-md opacity-0 group-hover:opacity-100">
+      <ThreadListItemMorePrimitive.Root sharedFocusGroup>
+        <ThreadListItemMorePrimitive.Trigger className="absolute end-1.5 top-1/2 size-7 -translate-y-1/2 rounded-md opacity-0 group-hover:opacity-100 group-has-focus-visible:opacity-100 data-[state=open]:opacity-100">
           <MoreHorizontalIcon className="size-4" />
         </ThreadListItemMorePrimitive.Trigger>
         <ThreadListItemMorePrimitive.Content className="rounded-md border bg-popover p-1 shadow-md">
@@ -118,6 +118,21 @@ Both `ThreadListPrimitive.New` and `ThreadListItemPrimitive.Root` get a `data-ac
 
 The `New` button gets `data-active` when the user is on a fresh, unsaved thread.
 
+### Keyboard Navigation
+
+Every item stays a native Tab stop, and arrow keys are layered on top. Up/Down move between items and Right focuses an item's `More` button (Left/Right are mirrored in RTL). This is built into the primitives — no prop is required.
+
+To fold the `More` menu into the same navigation, opt it in with `sharedFocusGroup`:
+
+```tsx
+<ThreadListItemMorePrimitive.Root sharedFocusGroup>
+  {/* Right opens the menu from the trigger; Left/Escape close it and
+      return focus to the trigger, keeping the highlight continuous. */}
+</ThreadListItemMorePrimitive.Root>
+```
+
+`sharedFocusGroup` joins the menu to the list's focus group, so its trigger and the open menu act as one keyboard-navigable unit: Right opens it and Left/Escape close it, synchronously restoring focus to the trigger so a `group-has-focus-visible` highlight never flickers. Enabling it forces the menu non-modal, because a focus trap and a shared focus group are mutually exclusive — the trap keeps focus inside the menu, the shared group lets it move out across the boundary. Without `sharedFocusGroup` the menu keeps its standard Radix `DropdownMenu` keyboard behavior (modal by default), so menus you already render are unchanged. Our assistant-ui [thread-list](/docs/ui/thread-list) registry component sets `sharedFocusGroup` for you.
+
 ### Items Iterator
 
 `ThreadListPrimitive.Items` now prefers a children render function, similar to `ThreadPrimitive.Messages`:
@@ -168,6 +183,15 @@ The canonical pattern composes `ThreadListItemPrimitive.Archive asChild` with `T
 
 `Archive` provides the click handler and disabled logic. `Item` provides the menu item behavior and styling. `asChild` merges them into a single element.
 
+## Accessibility
+
+The thread list leans on native button semantics and Radix's `DropdownMenu`; the arrow-key navigation is layered on top as a convenience, not a requirement.
+
+- Each `ThreadListItemPrimitive.Trigger` is a native `<button>` and its own Tab stop, so the whole list is reachable with <Kbd>Tab</Kbd> alone. The arrow keys (see [Keyboard Navigation](#keyboard-navigation)) speed traversal up, but nothing depends on them.
+- The item representing the current thread sets `aria-current="true"` (alongside `data-active`) on `ThreadListItemPrimitive.Root`, so assistive tech announces which conversation is open.
+- The `More` trigger exposes `aria-haspopup="menu"`, and its panel is a Radix `role="menu"` with `role="menuitem"` children, so screen readers announce it as a menu and the arrow keys cycle its items.
+- With `sharedFocusGroup`, the `More` menu is non-modal and joins the list's focus group: opening and closing it move focus synchronously between the trigger and the menu, so keyboard focus is never dropped and the `group-has-focus-visible` highlight never flickers. Without it, the menu keeps Radix's default modal focus trap.
+
 ## Parts
 
 ### ThreadListPrimitive
@@ -319,10 +343,10 @@ Button that deletes the current thread item. Renders a `<button>` element unless
 
 #### Root
 
-Root container for the overflow menu primitives.
+Root container for the overflow menu primitives. Pass `sharedFocusGroup` to fold the menu into the list's arrow-key navigation (see [Keyboard Navigation](#keyboard-navigation)); doing so forces it non-modal. Without it the menu honors the `modal` prop, defaulting to modal like Radix's `DropdownMenu`.
 
 ```tsx
-<ThreadListItemMorePrimitive.Root>
+<ThreadListItemMorePrimitive.Root sharedFocusGroup>
   <ThreadListItemMorePrimitive.Trigger>More</ThreadListItemMorePrimitive.Trigger>
 </ThreadListItemMorePrimitive.Root>
 ```

package/.docs/raw/docs/primitives/thread.mdx

@@ -319,6 +319,30 @@ Renders a single message at a specific index in the thread.
 
 <PrimitivesTypeTable type="ThreadPrimitiveMessageByIndexProps" parameters={ThreadPrimitiveDocs.MessageByIndex.props} />
 
+### Unstable_MessageById
+
+Renders a single message by id with the same `components` surface as
+`MessageByIndex`. Pair it with `unstable_useThreadMessageIds` for virtualized or
+custom message lists that should stay attached to messages across reordering and
+windowing. Unknown ids render `null`.
+
+```tsx
+const messageIds = unstable_useThreadMessageIds();
+
+messageIds.map((messageId) => (
+  <ThreadPrimitive.Unstable_MessageById
+    key={messageId}
+    messageId={messageId}
+    components={{ Message: MyMessage }}
+  />
+));
+```
+
+<Callout type="warn">
+  `unstable_useThreadMessageIds` and `ThreadPrimitive.Unstable_MessageById` are
+  experimental and may change in any release.
+</Callout>
+
 ### ScrollToBottom
 
 Scrolls the viewport to the bottom. Automatically disabled when already at the bottom. Renders a `<button>` element unless `asChild` is set.

package/.docs/raw/docs/runtimes/a2a/quickstart.mdx

@@ -3,7 +3,7 @@ title: Quickstart
 description: Minimal runtime and Thread setup against an A2A server.
 ---
 
-Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a).
+Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a/overview).
 
 <Steps>
 <Step>

package/.docs/raw/docs/runtimes/ag-ui/quickstart.mdx

@@ -3,7 +3,7 @@ title: Quickstart
 description: Minimal HttpAgent + useAgUiRuntime setup against an AG-UI server.
 ---
 
-Three steps to a working chat against an AG-UI agent. Assumes you have already installed the package and have an AG-UI server reachable; if not, start at [overview](/docs/runtimes/ag-ui).
+Three steps to a working chat against an AG-UI agent. Assumes you have already installed the package and have an AG-UI server reachable; if not, start at [overview](/docs/runtimes/ag-ui/overview).
 
 <Steps>
 <Step>