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

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

@@ -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.

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.

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

@@ -15,8 +15,9 @@ This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph
 
 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

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/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.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/ag-ui/runtime-options.mdx

@@ -68,6 +68,8 @@ time, the same way a live run never stores them.
 
 `fromAgUiMessages` reconstructs the text, reasoning, and tool calls of each message. Multimodal user input (`image`, `audio`, `video`, and `document` parts, as well as legacy `binary` parts) is restored as attachments on the user message, so a backend that persists multimodal messages shows them again on reload and re-sends them on the next run. Legacy `binary` parts that only reference a file id are not restored.
 
+An assistant message whose tool call has no matching tool result is reconstructed with `requires-action` status, the same status the runtime derives for a pending tool call, so a reloaded human-in-the-loop call (for example an `ask_user` tool) is actionable rather than stuck. This matches how every other external-store runtime surfaces a pending tool call on reload. The AG-UI wire snapshot carries no run outcome, so a tool call that a successful run intentionally left without a result is also surfaced as actionable.
+
 ## Thread list (experimental)
 
 <Callout type="warn">
@@ -131,6 +133,25 @@ await runtime.unstable_submitInterruptResponses(
 );
 ```
 
+### Steering away from an interrupt
+
+When the user ignores the interrupt UI and just sends a new message, use the `useAgUiSteerAway` hook. Every open interrupt defaults to `status: "cancelled"`, the new message is appended, and the run resumes with `resume: ResumeEntry[]` on the wire. With no pending interrupts it behaves like a normal append.
+
+```tsx
+const steerAway = useAgUiSteerAway();
+
+// the user typed a new message instead of answering the interrupt
+await steerAway("actually, let's do something else");
+```
+
+The message accepts a plain string or a partial `AppendMessage` (the parent defaults to the current head, which is the interrupted assistant message). Pass `responses` to override the status of specific interrupts; the rest still default to cancelled.
+
+```tsx
+await steerAway("continue without the file", [
+  { interruptId: "tool-1", status: "resolved", payload: { approved: true } },
+]);
+```
+
 ## Supported events
 
 The runtime parses the AG-UI event stream and maps each event type to assistant-ui state.

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -299,6 +299,54 @@ runtime.thread.import(repo);
 
 Each message must have an explicit `id` and `parentId`; messages with the same `parentId` create branches. Parents must appear before children in the array.
 
+### Exporting a snapshot
+
+`thread.import()` has a counterpart, `thread.export()`, which captures the current thread (including its full branch tree) as a serializable `ExportedMessageRepository`. Use it to persist a conversation and re-import it later:
+
+```tsx
+// capture the current thread as a serializable snapshot
+const repo = runtime.thread.export();
+await saveToBackend(JSON.stringify(repo));
+
+// later, restore it into a runtime
+runtime.thread.import(repo);
+```
+
+The exported shape round-trips through `thread.import()` directly, so the same value is both your persistence format and what you load back.
+
+### Persisting branch selection
+
+If you store the full branch tree outside assistant-ui, persist the selected branch head too and pass it back as `messageRepository.headId`. `setMessages` still performs the branch switch; `unstable_onBranchChange` is an additional signal that fires after an explicit `switchToBranch` action, such as a BranchPicker click.
+
+```tsx
+const runtime = useExternalStoreRuntime({
+  messageRepository: {
+    messages: storedMessages,
+    headId: selectedHeadId,
+  },
+  setMessages: (messages) => {
+    setVisibleMessages(messages);
+  },
+  unstable_onBranchChange: ({ headId, visibleMessageIds }) => {
+    saveSelectedBranch({
+      headId,
+      visibleMessageIds,
+    });
+  },
+  onNew,
+});
+```
+
+`headId` is the canonical persisted head of the visible branch. Optimistic or transient message ids are not surfaced there. `visibleMessageIds` is the currently visible path in order, which can include an optimistic leaf while `headId` points to its persisted ancestor.
+
+The callback only fires for explicit branch switches, and consecutive switches that resolve to the same canonical head are de-duped. It does not fire on adapter resync, `messageRepository` reset, append, edit/regenerate, content-only updates, or while the thread is running.
+
+<Callout type="warn">
+  `unstable_onBranchChange` is under active development and may change without
+  notice. It complements `setMessages`; it does not enable branch switching by
+  itself.
+</Callout>
+
 ## Tool calling
 
 Handle tool results by updating the matching tool-call entry:
@@ -717,6 +765,12 @@ useExternalStoreRuntime({
       type: "(messages: readonly T[]) => void",
       description: "Update messages (required for branch switching).",
     },
+    {
+      name: "unstable_onBranchChange",
+      type: "(event: ExternalStoreBranchChange) => void",
+      description:
+        "Called after an explicit branch switch with the canonical persisted head id and visible message path. Complements setMessages and is unstable.",
+    },
     {
       name: "onEdit",
       type: "(message: AppendMessage) => Promise<void>",