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

package/.docs/raw/docs/primitives/message.mdx

@@ -117,7 +117,7 @@ For most new code, prefer `MessagePrimitive.Parts` with a `children` render func
 Tool call parts resolve in this order:
 
 1. **`tools.Override`**: if provided inline through the deprecated `components` prop, handles **all** tool calls
-2. **Globally registered tools**: tools registered via `makeAssistantTool` / `useAssistantToolUI`
+2. **Globally registered tools**: tools registered via `Tools({ toolkit })`
 3. **`tools.by_name[toolName]`**: per-`MessagePrimitive.Parts` inline overrides from the deprecated `components` prop
 4. **`tools.Fallback`**: catch-all for unmatched tool calls from the deprecated `components` prop
 5. **`part.toolUI`**: the resolved tool UI exposed directly in the children render function
@@ -250,17 +250,16 @@ Renders each content part with type-based component resolution.
 
 ### GroupedParts
 
-Groups adjacent message parts into a nested tree. Use `groupBy` to return group keys for parts that should be grouped, then switch on `part.type` in the render function. Group cases render `children`; leaf cases render their own UI.
+Groups adjacent message parts into a nested tree. Use `groupBy` to map each part to a group-key path, then switch on `part.type` in the render function. Group cases render `children`; leaf cases render their own UI. Prefer the `groupPartByType` helper for the common `part.type → path` case.
 
 ```tsx
+import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
+
 <MessagePrimitive.GroupedParts
-  groupBy={(part) => {
-    if (part.type === "reasoning")
-      return ["group-chainOfThought", "group-reasoning"];
-    if (part.type === "tool-call")
-      return ["group-chainOfThought", "group-tool"];
-    return null;
-  }}
+  groupBy={groupPartByType({
+    reasoning: ["group-chainOfThought", "group-reasoning"],
+    "tool-call": ["group-chainOfThought", "group-tool"],
+  })}
 >
   {({ part, children }) => {
     switch (part.type) {
@@ -514,7 +513,7 @@ import { MessagePrimitive, AuiIf } from "@assistant-ui/react";
 </MessagePrimitive.Root>;
 ```
 
-`s.message.status` is a discriminated union of `running | requires-action | complete | incomplete`, defined only on assistant messages. The `role === "assistant"` guard keeps the predicate type-safe. For tool-call-driven generative UI that defers rendering inside the part itself, see [Deferred Rendering](/docs/guides/tool-ui#deferred-rendering) in the Generative UI guide.
+`s.message.status` is a discriminated union of `running | requires-action | complete | incomplete`, defined only on assistant messages. The `role === "assistant"` guard keeps the predicate type-safe. For tool-call-driven generative UI that defers rendering inside the part itself, see [Deferred Rendering](/docs/tools/tool-ui#deferred-rendering) in the Generative UI guide.
 
 ### Legacy and Unstable APIs
 

package/.docs/raw/docs/react-native/hooks.mdx

@@ -114,52 +114,54 @@ const runtime = useRemoteThreadListRuntime({
 
 ## Model Context Hooks
 
-### useAssistantTool
+### Tools
 
-Register a tool with an optional UI renderer. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.
+Author tools in a `"use generative"` file with `defineToolkit`, the same API as on the web ([Defining Tools](/docs/tools/defining-tools)). The tool definition is forwarded to the model; when the model calls it, the `execute` function runs and the `render` component displays the result.
 
-```tsx
-import { useAssistantTool } from "@assistant-ui/react-native";
-
-useAssistantTool({
-  toolName: "get_weather",
-  description: "Get the current weather for a city",
-  parameters: {
-    type: "object",
-    properties: {
-      city: { type: "string" },
+Add the [`@assistant-ui/metro`](https://www.npmjs.com/package/@assistant-ui/metro) plugin so Metro compiles the `"use generative"` directive:
+
+```js title="metro.config.js"
+const { getDefaultConfig } = require("expo/metro-config");
+const { withAui } = require("@assistant-ui/metro");
+
+module.exports = withAui(getDefaultConfig(__dirname));
+```
+
+```tsx title="weather-toolkit.tsx"
+"use generative";
+
+import { defineToolkit } from "@assistant-ui/react-native";
+import { Text, View } from "react-native";
+import { z } from "zod";
+
+export default defineToolkit({
+  get_weather: {
+    description: "Get the current weather for a city",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => {
+      "use client";
+      const res = await fetch(`https://api.weather.example/${city}`);
+      return res.json();
     },
-    required: ["city"],
+    render: ({ args, result }) => (
+      <View>
+        <Text>
+          {args.city}: {result?.temperature}°F
+        </Text>
+      </View>
+    ),
   },
-  execute: async ({ city }) => {
-    const res = await fetch(`https://api.weather.example/${city}`);
-    return res.json();
-  },
-  render: ({ args, result }) => (
-    <View>
-      <Text>{args.city}: {result?.temperature}°F</Text>
-    </View>
-  ),
 });
 ```
 
-### useAssistantToolUI
+```tsx title="ToolProvider.tsx"
+import { AuiProvider, Tools, useAui } from "@assistant-ui/react-native";
+import toolkit from "./weather-toolkit";
 
-Register only a UI renderer for a tool (without tool definition or execute function).
-
-```tsx
-import { useAssistantToolUI } from "@assistant-ui/react-native";
-
-useAssistantToolUI({
-  toolName: "get_weather",
-  render: ({ args, result, status }) => (
-    <View>
-      {status?.type === "running"
-        ? <Text>Loading weather for {args.city}...</Text>
-        : <Text>{args.city}: {result?.temperature}°F</Text>}
-    </View>
-  ),
-});
+function ToolProvider({ children }: { children: React.ReactNode }) {
+  const aui = useAui({ tools: Tools({ toolkit }) });
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+}
 ```
 
 ### useAssistantDataUI
@@ -193,49 +195,30 @@ useAssistantInstructions("You are a helpful weather assistant.");
 
 Wrap a tool UI component so that inline state updates (from a parent component's render) are reflected without remounting. Use this when the render function closes over props that change over time.
 
-```tsx
-import { useInlineRender } from "@assistant-ui/react-native";
-
-const stableRender = useInlineRender(({ args, result }) => (
-  <Text>{someOuterProp}: {result?.value}</Text>
-));
-
-useAssistantToolUI({ toolName: "my_tool", render: stableRender });
-```
-
-### makeAssistantTool
-
-Create a component that registers a tool when mounted. Useful for declarative tool registration.
-
-```tsx
-import { makeAssistantTool } from "@assistant-ui/react-native";
-
-const WeatherTool = makeAssistantTool({
-  toolName: "get_weather",
-  description: "Get weather",
-  parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
-  execute: async ({ city }) => ({ temperature: 72 }),
-  render: ({ args, result }) => <Text>{args.city}: {result?.temperature}°F</Text>,
-});
-
-// Mount inside AssistantRuntimeProvider to register
-<WeatherTool />
+```tsx title="my-tool-toolkit.tsx"
+import { defineToolkit, useInlineRender } from "@assistant-ui/react-native";
+import { Text } from "react-native";
+import { useMemo } from "react";
+
+export function useMyToolToolkit(someOuterProp: string) {
+  const stableRender = useInlineRender(({ args, result }) => (
+    <Text>{someOuterProp}: {result?.value}</Text>
+  ));
+
+  return useMemo(
+    () =>
+      defineToolkit({
+        my_tool: {
+          type: "backend",
+          render: stableRender,
+        },
+      }),
+    [stableRender],
+  );
+}
 ```
 
-### makeAssistantToolUI
-
-Create a component that registers only a tool UI renderer when mounted.
-
-```tsx
-import { makeAssistantToolUI } from "@assistant-ui/react-native";
-
-const WeatherToolUI = makeAssistantToolUI({
-  toolName: "get_weather",
-  render: ({ args, result }) => <Text>{args.city}: {result?.temperature}°F</Text>,
-});
-
-<WeatherToolUI />
-```
+Import the toolkit hook, pass its result to `useAui({ tools: Tools({ toolkit }) })`, and provide the returned `aui` with `AuiProvider`, as shown in the [Tools](#tools) section above.
 
 ### makeAssistantDataUI
 

package/.docs/raw/docs/react-native/migration.mdx

@@ -9,7 +9,7 @@ If you already have an assistant-ui web app, most of your code transfers directl
 
 - **Runtime setup** — `useChatRuntime`, `useLocalRuntime`, `ChatModelAdapter`, and all runtime options work identically.
 - **AI SDK integration** — `@assistant-ui/react-ai-sdk` works with React Native. Your `useChatRuntime` + `AssistantChatTransport` setup transfers directly.
-- **Tool definitions** — `useAssistantTool`, `makeAssistantTool`, and tool UI renderers use the same API.
+- **Tool definitions** — `Tools({ toolkit })` and toolkit renderers use the same API.
 - **State hooks** — `useAuiState`, `useAui`, and selector patterns are the same.
 - **Backend code** — Your API routes, streaming endpoints, and server-side logic need zero changes.
 

package/.docs/raw/docs/react-native/primitives.mdx

@@ -338,7 +338,7 @@ Container `View` for a single message.
 
 ### MessagePrimitive.Content
 
-Renders message content parts using render-prop functions instead of the component-map approach used by `MessagePrimitive.Parts`. Each part type receives a `part` object and its `index`. Registered tool UIs (via `useAssistantTool`) are automatically dispatched and take priority over `renderToolCall`.
+Renders message content parts using render-prop functions instead of the component-map approach used by `MessagePrimitive.Parts`. Each part type receives a `part` object and its `index`. Registered toolkit renderers are automatically dispatched and take priority over `renderToolCall`.
 
 ```tsx
 <MessagePrimitive.Content
@@ -364,7 +364,7 @@ Renders message content parts using render-prop functions instead of the compone
 
 ### MessagePrimitive.Parts
 
-Renders message content parts via a `components` prop. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to components provided here. A default `Text` component using React Native's `<Text>` is provided out of the box.
+Renders message content parts via a `components` prop. Tool call and data parts automatically render registered toolkit renderers and data UIs (via `useAssistantDataUI`), falling back to components provided here. A default `Text` component using React Native's `<Text>` is provided out of the box.
 
 ```tsx
 <MessagePrimitive.Parts>

package/.docs/raw/docs/runtimes/a2a/client-and-hooks.mdx

@@ -19,6 +19,7 @@ const client = new A2AClient({
   headers: { Authorization: "Bearer <token>" },
   tenant: "my-org",
   extensions: ["urn:a2a:ext:my-extension"],
+  fetchOptions: { credentials: "include" },
 });
 ```
 
@@ -37,6 +38,7 @@ const runtime = useA2ARuntime({ client });
 | `headers` | `Record<string, string>` or `() => Record<string, string>` | Static or dynamic headers (e.g. for auth tokens). |
 | `tenant` | `string` | Tenant ID for multi-tenant servers (prepended to URL paths). |
 | `extensions` | `string[]` | Extension URIs to negotiate via `A2A-Extensions` header. |
+| `fetchOptions` | `RequestInit` (partial) | Extra fetch options applied to every request (e.g. `{ credentials: "include" }`). `headers`, `body`, `method`, and `signal` are managed internally. |
 
 ### Client methods
 
@@ -67,6 +69,7 @@ Pass either a pre-built `client` or a `baseUrl` (the runtime creates a client fo
 | `tenant` | `string` | Tenant ID for multi-tenant servers. Only used with `baseUrl`. |
 | `headers` | `Record<string, string>` or `() => Record<string, string>` | Headers for the auto-created client. |
 | `extensions` | `string[]` | Extension URIs to negotiate. Only used with `baseUrl`. |
+| `fetchOptions` | `RequestInit` (partial) | Extra fetch options for the auto-created client (e.g. `{ credentials: "include" }`). `headers`, `body`, `method`, and `signal` are managed internally. Only used with `baseUrl`. |
 | `contextId` | `string` | Initial context ID for the conversation. |
 | `configuration` | `A2ASendMessageConfiguration` | Default send message configuration. |
 | `onError` | `(error: Error) => void` | Error callback. |

package/.docs/raw/docs/runtimes/ag-ui/runtime-options.mdx

@@ -29,6 +29,47 @@ Reference for the runtime's API surface. Start with [quickstart](/docs/runtimes/
 | History | `adapters.history` | Per-thread message persistence. |
 | Thread list | `adapters.threadList` | Multi-thread switching (experimental, see below). |
 
+## Loading conversation history
+
+If your backend exposes the persisted AG-UI messages of a conversation (for
+example a `GET /agents/state` endpoint), use `fromAgUiMessages` to convert them
+to assistant-ui messages and return them from the history adapter so the thread
+is restored on page load:
+
+```tsx
+import { fromAgUiMessages } from "@assistant-ui/react-ag-ui";
+import { ExportedMessageRepository } from "@assistant-ui/react";
+
+const runtime = useAgUiRuntime({
+  agent,
+  adapters: {
+    history: {
+      async load() {
+        const { messages } = await fetch("/agents/state").then((r) => r.json());
+        return ExportedMessageRepository.fromArray(fromAgUiMessages(messages));
+      },
+      async append({ message }) {
+        // persist the newly sent message on your backend
+      },
+    },
+  },
+});
+```
+
+Messages sent during the session are always forwarded to the agent through the
+run input, independent of `append`. A no-op `append` is therefore only safe when
+your backend already persists the conversation on its own; otherwise those
+messages are gone on the next page load.
+
+`fromAgUiMessages` accepts an optional second argument: pass
+`{ showThinking: false }` to match a runtime configured with
+`showThinking: false`, so imported reasoning messages are dropped at conversion
+time, the same way a live run never stores them.
+
+`fromAgUiMessages` reconstructs the text, reasoning, and tool calls of each
+message. Non-text message content such as images and files is not restored, so a
+backend that persists multimodal messages loads only their text on reload.
+
 ## Thread list (experimental)
 
 <Callout type="warn">

package/.docs/raw/docs/runtimes/ai-sdk/v6.mdx

@@ -254,7 +254,7 @@ export async function POST(req: Request) {
 }
 ```
 
-Frontend tools are registered through `useAui` (see the [tools guide](/docs/guides/tools)) and serialized for the backend via `frontendTools`.
+Frontend tools are registered through `useAui` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
 
 ## Multi-step tool calls
 
@@ -286,6 +286,127 @@ export async function POST(req: Request) {
 
 Without a `stopWhen`, AI SDK runs a single inference step. Set `stepCountIs` (or one of AI SDK's other stop conditions) when your tools chain multiple calls.
 
+## Server-side tool approval
+
+AI SDK v6 lets a tool gate its own execution with `needsApproval`. The server pauses, emits an `approval-requested` part, and resumes once the client posts an approval response. assistant-ui surfaces the gate as `approval` on the tool part and adds a `respondToApproval` prop on the renderer, so tool components stay decoupled from `chatHelpers`.
+
+On the backend, mark the tool with `needsApproval` (boolean or function):
+
+```ts title="@/app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages, tool } from "ai";
+import { z } from "zod";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(messages),
+    tools: {
+      deploy: tool({
+        description: "Deploy the current build to an environment.",
+        inputSchema: z.object({ target: z.string() }),
+        needsApproval: ({ input }) => input.target === "production",
+        execute: async ({ target }) => ({ deployed: target }),
+      }),
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+On the client, configure `useChat` with `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses` so the response is sent back to the server when the user decides:
+
+```tsx title="@/app/page.tsx"
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import {
+  AssistantRuntimeProvider,
+  useAISDKRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export default function Page() {
+  const chat = useChat({
+    api: "/api/chat",
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+  });
+  const runtime = useAISDKRuntime(chat);
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+Render the gate with a toolkit entry. The `approval` field carries the gate state, and `respondToApproval` is the only correct way to acknowledge it (it reads the approval id from the part):
+
+```tsx title="@/app/page.tsx"
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import {
+  AssistantRuntimeProvider,
+  defineToolkit,
+  Tools,
+  useAui,
+} from "@assistant-ui/react";
+import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
+import { Thread } from "@/components/assistant-ui/thread";
+
+const toolkit = defineToolkit({
+  deploy: {
+    type: "backend",
+    render: ({ args, approval, respondToApproval, result }) => {
+      if (approval?.approved === undefined) {
+        return (
+          <div>
+            <p>Approve deploy to {args.target}?</p>
+            <button onClick={() => respondToApproval({ approved: true })}>
+              Approve
+            </button>
+            <button
+              onClick={() =>
+                respondToApproval({ approved: false, reason: "user denied" })
+              }
+            >
+              Deny
+            </button>
+          </div>
+        );
+      }
+      if (approval?.approved === false) return <p>Denied</p>;
+      if (result === undefined) return <p>Approved, deploying…</p>;
+      return <p>Deployed {result.deployed}</p>;
+    },
+  },
+});
+
+export default function Page() {
+  const chat = useChat({
+    api: "/api/chat",
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+  });
+  const runtime = useAISDKRuntime(chat);
+  const aui = useAui({ tools: Tools({ toolkit }) });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+See the [tool UI guide](/docs/tools/tool-ui#server-side-approval-gates) for the full three-state semantics of `approval.approved` and the `isAutomatic` flag.
+
 ## Quote context
 
 assistant-ui's composer can attach quote metadata to user messages (e.g. when the user selects text and clicks "Quote"). On the server, `injectQuoteContext` flattens that metadata into a markdown blockquote prefix so the LLM sees the quoted text:

package/.docs/raw/docs/runtimes/concepts/architecture.mdx

@@ -7,8 +7,8 @@ assistant-ui exposes runtime integrations at three layers. Understanding which l
 
 ## The three layers
 
-```mermaid
-graph TD
+<Flow.Root
+  llm={`graph TD
     subgraph Framework["Framework adapters"]
       A1[react-ai-sdk]
       A2[react-langgraph]
@@ -34,8 +34,50 @@ graph TD
     A6 --> C2
     A7 --> C2
     P1 --> C1
-    P2 --> C2
-```
+    P2 --> C2`}
+>
+  <Flow.Canvas
+    edges={[
+      { from: "datastream", to: "local", route: "down", midFrac: 0.4, laneOffset: -60 },
+      { from: "transport", to: "external", route: "down", midFrac: 0.65, toOffset: -14 },
+      { from: "adapters", to: "external", route: "down", midFrac: 0.4, toOffset: 14 },
+    ]}
+  >
+    <div className="grid max-w-2xl grid-cols-[1fr_1.6fr] gap-4">
+      <Flow.Group>
+        <Flow.GroupLabel>Protocol layers</Flow.GroupLabel>
+        <Flow.Column className="items-stretch gap-5">
+          <Flow.Row className="justify-start">
+            <Flow.Node flowId="datastream">DataStream</Flow.Node>
+          </Flow.Row>
+          <Flow.Row className="justify-end">
+            <Flow.Node flowId="transport">AssistantTransport</Flow.Node>
+          </Flow.Row>
+        </Flow.Column>
+      </Flow.Group>
+      <Flow.Group flowId="adapters">
+        <Flow.GroupLabel>Framework adapters</Flow.GroupLabel>
+        <Flow.Row className="flex-wrap justify-start">
+          <Flow.Node>react-ai-sdk</Flow.Node>
+          <Flow.Node>react-langgraph</Flow.Node>
+          <Flow.Node>react-langchain</Flow.Node>
+          <Flow.Node>react-google-adk</Flow.Node>
+          <Flow.Node>react-a2a</Flow.Node>
+          <Flow.Node>react-ag-ui</Flow.Node>
+          <Flow.Node>react-opencode</Flow.Node>
+        </Flow.Row>
+      </Flow.Group>
+    </div>
+    <div className="h-14" aria-hidden />
+    <Flow.Group className="mx-auto w-fit">
+      <Flow.GroupLabel>Core runtimes</Flow.GroupLabel>
+      <Flow.Row className="gap-10">
+        <Flow.Node flowId="local">LocalRuntime</Flow.Node>
+        <Flow.Node flowId="external">ExternalStoreRuntime</Flow.Node>
+      </Flow.Row>
+    </Flow.Group>
+  </Flow.Canvas>
+</Flow.Root>
 
 Each upper layer is implemented in terms of a lower one. You can drop down a layer whenever you need more control, but most users start at the framework layer and never touch the others.
 

package/.docs/raw/docs/runtimes/concepts/threads.mdx

@@ -287,6 +287,12 @@ A few invariants worth knowing when wiring a custom UI on top of `loadMore()`:
       description: "Persist title changes from the UI.",
       required: true,
     },
+    {
+      name: "updateCustom",
+      type: "(remoteId: string, custom: Record<string, unknown> | undefined) => Promise<void>",
+      description:
+        "Optional. Persist replacement custom metadata from `aui.threadListItem().updateCustom(custom)`.",
+    },
     {
       name: "archive",
       type: "(remoteId: string) => Promise<void>",
@@ -355,7 +361,7 @@ function ThreadListItemMeta() {
 }
 ```
 
-`custom` is preserved across `rename`, `archive`, `unarchive`, and `generateTitle`. To mutate it, return updated values from a subsequent `fetch()` or call `runtime.threads.reload()`.
+`custom` is preserved across `rename`, `archive`, `unarchive`, and `generateTitle`. To replace it from your UI, implement `RemoteThreadListAdapter.updateCustom` and call `aui.threadListItem().updateCustom(custom)`. The cloud adapter persists this through `cloud.threads.update(threadId, { metadata })`. If your adapter mutates thread metadata through a separate application path, return the updated values from `fetch()` or call `aui.threads().reload()` to re-run `list()`.
 
 ## ExternalStoreThreadListAdapter
 

package/.docs/raw/docs/runtimes/custom/assistant-transport.mdx

@@ -25,11 +25,17 @@ If you only need message streaming, [DataStream](/docs/runtimes/custom/data-stre
 
 ## Mental model
 
-```mermaid
-graph LR
+<Flow.Root
+  llm={`graph LR
     Frontend -->|Commands| Agent[Agent server]
-    Agent -->|State snapshots| Frontend
-```
+    Agent -->|State snapshots| Frontend`}
+>
+  <Flow.Row>
+    <Flow.Node>Frontend</Flow.Node>
+    <Flow.Arrow label="Commands" reverseLabel="State snapshots" length={150} />
+    <Flow.Node>Agent server</Flow.Node>
+  </Flow.Row>
+</Flow.Root>
 
 The frontend receives state snapshots and converts them to React components. The UI is a stateless view on top of the agent state.
 
@@ -37,21 +43,57 @@ The agent server receives commands from the frontend. When a user interacts with
 
 ### Command lifecycle
 
-```mermaid
-graph LR
+<Flow.Root
+  llm={`graph LR
     queued -->|sent to backend| in_transit
-    in_transit -->|backend processes| applied
-```
+    in_transit -->|backend processes| applied`}
+>
+  <Flow.Row>
+    <Flow.Node>queued</Flow.Node>
+    <Flow.Arrow label="sent to backend" length={120} />
+    <Flow.Node>in_transit</Flow.Node>
+    <Flow.Arrow label="backend processes" length={132} />
+    <Flow.Node>applied</Flow.Node>
+  </Flow.Row>
+</Flow.Root>
 
 The runtime alternates between **idle** (no active backend request) and **sending** (request in flight). When a new command is created while idle, it is sent immediately; otherwise it is queued until the current request completes.
 
-```mermaid
-graph LR
+<Flow.Root
+  llm={`graph LR
     idle -->|new command| sending
     sending -->|request completes| check{check queue}
     check -->|queue has commands| sending
-    check -->|queue empty| idle
-```
+    check -->|queue empty| idle`}
+>
+  <Flow.Canvas
+    edges={[
+      {
+        from: "check",
+        to: "sending",
+        route: "loop-bottom",
+        label: "queue has commands",
+        laneOffset: 28,
+      },
+      {
+        from: "check",
+        to: "idle",
+        route: "loop-bottom",
+        label: "queue empty",
+        laneOffset: 60,
+      },
+    ]}
+  >
+    <Flow.Row>
+      <Flow.Node flowId="idle">idle</Flow.Node>
+      <Flow.Arrow label="new command" length={108} />
+      <Flow.Node flowId="sending">sending</Flow.Node>
+      <Flow.Arrow label="request completes" length={132} />
+      <Flow.Node flowId="check" variant="decision">check queue</Flow.Node>
+    </Flow.Row>
+    <div className="h-20" aria-hidden />
+  </Flow.Canvas>
+</Flow.Root>
 
 To implement this you build two pieces: