@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/organized/code-examples/with-tap-runtime.md

@@ -368,6 +368,7 @@ export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
               <div className="flex items-center gap-2">
                 <span className="text-muted-foreground text-sm">Controls:</span>
                 <button
+                  type="button"
                   onClick={() => {
                     updateCurrentThreadMessages((prev) => [
                       ...prev,
@@ -383,6 +384,7 @@ export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
                   Add User Message
                 </button>
                 <button
+                  type="button"
                   onClick={() => {
                     updateCurrentThreadMessages((prev) => [
                       ...prev,
@@ -400,12 +402,14 @@ export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
                   Add Assistant Message
                 </button>
                 <button
+                  type="button"
                   onClick={() => setIsRunning(!isRunning)}
                   className="rounded-md bg-accent px-3 py-1 font-medium text-accent-foreground text-sm hover:bg-accent/80"
                 >
                   {isRunning ? "Stop" : "Start"} Running
                 </button>
                 <button
+                  type="button"
                   onClick={() => updateCurrentThreadMessages(() => [])}
                   className="rounded-md bg-destructive px-3 py-1 font-medium text-sm text-white hover:bg-destructive/90"
                 >
@@ -597,22 +601,22 @@ export default nextConfig;
     "@assistant-ui/ui": "workspace:*",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.8.0",
-    "next": "^16.2.3",
+    "lucide-react": "^1.14.0",
+    "next": "^16.2.4",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.2.2",
+    "@tailwindcss/postcss": "^4.2.4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.9",
-    "tailwindcss": "^4.2.2",
+    "postcss": "^8.5.14",
+    "tailwindcss": "^4.2.4",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }
 

package/.docs/raw/docs/(docs)/cli.mdx

@@ -1,6 +1,7 @@
 ---
 title: CLI
 description: Scaffold projects, add components, and manage updates from the command line.
+platforms: ["react"]
 ---
 
 Use the `assistant-ui` CLI to quickly set up new projects and add components to existing ones.
@@ -68,7 +69,7 @@ Use `--example` to create a project from one of the monorepo examples with full
 | `with-artifacts` | HTML artifact rendering with live preview | `npx assistant-ui create my-app -e with-artifacts` |
 | `with-langgraph` | LangGraph agent with custom tools | `npx assistant-ui create my-app -e with-langgraph` |
 | `with-cloud` | Assistant Cloud persistence | `npx assistant-ui create my-app -e with-cloud` |
-| `with-ag-ui` | AG-UI protocol integration | `npx assistant-ui create my-app -e with-ag-ui` |
+| `with-ag-ui` | [AG-UI protocol](/docs/runtimes/ag-ui) integration | `npx assistant-ui create my-app -e with-ag-ui` |
 | `with-assistant-transport` | Custom backend via Assistant Transport | `npx assistant-ui create my-app -e with-assistant-transport` |
 | `with-chain-of-thought` | Chain-of-thought with JS execution | `npx assistant-ui create my-app -e with-chain-of-thought` |
 | `with-external-store` | External message store | `npx assistant-ui create my-app -e with-external-store` |

package/.docs/raw/docs/(docs)/copilots/assistant-frame.mdx

@@ -1,6 +1,7 @@
 ---
 title: Assistant Frame API
 description: Share model context across iframe boundaries
+platforms: ["react"]
 ---
 
 The Assistant Frame API enables iframes to provide model context (tools and instructions) to a parent window's assistant. This is particularly useful for embedded applications, plugins, or sandboxed components that need to contribute capabilities to the main assistant.

package/.docs/raw/docs/(docs)/copilots/make-assistant-tool-ui.mdx

@@ -1,11 +1,18 @@
 ---
 title: makeAssistantToolUI
 description: Register custom UI components to render tool executions and their status.
+platforms: ["react"]
 ---
 
-<Callout type="warn">
-  `makeAssistantToolUI` is deprecated. Use the `Tools()` API instead. See the
-  [Tools guide](/docs/guides/tools) for the recommended approach.
+<Callout type="info">
+  Prefer pre-registering tool UIs via the [`Tools()` API](/docs/guides/tools)
+  (set `render` on the tool definition) or by mounting `makeAssistantToolUI`
+  near the root of your tree. A tool UI that is only registered while a
+  specific component is mounted will not appear when chat history is replayed
+  or during server-side rendering, since the registering component may not be
+  mounted at that point. Tool execution can still be registered dynamically
+  via [`makeAssistantTool`](/docs/copilots/make-assistant-tool); this caveat
+  applies specifically to the UI render function.
 </Callout>
 
 The `makeAssistantToolUI` utility is used to register a tool UI component with the Assistant.

package/.docs/raw/docs/(docs)/copilots/make-assistant-tool.mdx

@@ -1,11 +1,16 @@
 ---
 title: makeAssistantTool
 description: Create React components that provide reusable tools to the assistant.
+platforms: ["react"]
 ---
 
-<Callout type="warn">
-  `makeAssistantTool` is deprecated. Use the `Tools()` API instead. See the
-  [Tools guide](/docs/guides/tools) for the recommended approach.
+<Callout type="info">
+  For most apps, the [`Tools()` API](/docs/guides/tools) is an easier starting
+  point: tool definitions live in a toolkit object rather than the component
+  tree. `makeAssistantTool` is fully supported and remains a good fit when a
+  tool's availability is tied to a component being mounted, for example a
+  product-specific tool that should only be exposed while that product's UI is
+  on screen (the [intelligent components](/docs/copilots/motivation) pattern).
 </Callout>
 
 `makeAssistantTool` creates a React component that provides a tool to the assistant. This is useful for defining reusable tools that can be composed into your application.

package/.docs/raw/docs/(docs)/copilots/make-assistant-visible.mdx

@@ -1,6 +1,7 @@
 ---
 title: makeAssistantVisible
 description: Make React components visible and interactive to assistants via higher-order component wrapping.
+platforms: ["react"]
 ---
 
 `makeAssistantVisible` is a higher-order component (HOC) that makes React components "visible" by the assistant, allowing it to understand and interact with the component's HTML structure.

package/.docs/raw/docs/(docs)/copilots/model-context.mdx

@@ -1,6 +1,7 @@
 ---
 title: Model Context
 description: Configure assistant behavior through system instructions, tools, and context providers.
+platforms: ["react"]
 ---
 
 Model Context is the foundation of intelligence in assistant-ui components. It provides configuration and capabilities to the assistant through a context provider system.

package/.docs/raw/docs/(docs)/copilots/motivation.mdx

@@ -1,6 +1,7 @@
 ---
 title: Intelligent Components
 description: Add intelligence to React components through readable interfaces and assistant tools.
+platforms: ["react"]
 ---
 
 React revolutionized web development with components that combine logic, structure, and style. Now, with assistant-ui, we're adding a fourth dimension: intelligence. Let's learn how to build smart components through a practical banking app example.

package/.docs/raw/docs/(docs)/copilots/use-assistant-instructions.mdx

@@ -1,6 +1,7 @@
 ---
 title: useAssistantInstructions
 description: React hook for setting system instructions to guide assistant behavior.
+platforms: ["react"]
 ---
 
 `useAssistantInstructions` is a React hook that allows you to set system instructions for your assistant-ui components.

package/.docs/raw/docs/(docs)/devtools.mdx

@@ -1,6 +1,7 @@
 ---
 title: DevTools
 description: Inspect runtime state, context, and events in the browser.
+platforms: ["react"]
 ---
 
 

package/.docs/raw/docs/(docs)/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Introduction
 description: Beautiful, enterprise-grade AI chat interfaces for React, React Native, and terminal applications.
+platforms: ["react"]
 ---
 
 import { PanelsTopLeft, Database, Terminal } from "lucide-react";

package/.docs/raw/docs/(docs)/installation.mdx

@@ -1,6 +1,7 @@
 ---
 title: Installation
 description: Get assistant-ui running in 5 minutes with npm and your first chat component.
+platforms: ["react"]
 ---
 
 

package/.docs/raw/docs/(docs)/rtl.mdx

@@ -0,0 +1,80 @@
+---
+title: RTL Support
+description: Use assistant-ui with right-to-left languages like Arabic, Hebrew, and Persian.
+platforms: ["react"]
+---
+
+Components shipped through `@assistant-ui/ui` (npm) and the shadcn registry (`npx shadcn@latest add https://r.assistant-ui.com/...`) use logical Tailwind classes (`ms-*`, `pe-*`, `text-start`, `end-*`, `border-s`, ...). They flip automatically under `dir="rtl"` and render byte-identically under `dir="ltr"` (the default) — there is nothing to opt out of.
+
+If you scaffolded from one of our templates (e.g. `npx assistant-ui@latest create -t default`), the generated `components/` folder still uses physical classes (`ml-*`, `text-left`, ...). Run shadcn's built-in migration **once** to convert both the shadcn primitives and assistant-ui's wrappers:
+
+```sh
+# shadcn primitives under components/ui/
+npx shadcn@latest migrate rtl
+
+# assistant-ui wrappers (pass a custom glob)
+npx shadcn@latest migrate rtl 'components/assistant-ui/**/*.tsx'
+```
+
+Commit the diff and do not re-run. The upstream migration is not fully idempotent on repeat runs ([#9891](https://github.com/shadcn-ui/ui/pull/9891)); you may end up with duplicated `rtl:translate-x-*` classes.
+
+After migrating, follow the setup below.
+
+## Setup
+
+### 1. Install the `direction` component
+
+```sh
+npx shadcn@latest add https://r.assistant-ui.com/direction.json
+```
+
+This adds `components/ui/direction.tsx`, a thin re-export of Radix UI's `DirectionProvider` and `useDirection`. It ensures Radix popovers, dropdowns, and menus pick up the current direction.
+
+### 2. Set `dir` on your root element
+
+```tsx title="app/layout.tsx"
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ar" dir="rtl">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### 3. Wrap your app with `DirectionProvider`
+
+```tsx title="app/providers.tsx"
+"use client";
+
+import { DirectionProvider } from "@/components/ui/direction";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <DirectionProvider dir="rtl">{children}</DirectionProvider>;
+}
+```
+
+For apps that need to switch direction at runtime, drive `dir` from state and also update `document.documentElement.dir` to keep Tailwind's `[dir=rtl]` selector in sync.
+
+## How it works
+
+Every physical class (`ml-4`, `text-left`, `right-3`, `border-l`, ...) in `@assistant-ui/ui` is authored in logical form (`ms-4`, `text-start`, `end-3`, `border-s`, ...). Logical properties resolve to the matching physical side based on the ancestor with a `dir` attribute:
+
+| Class | `dir="ltr"` | `dir="rtl"` |
+| ----- | ----------- | ----------- |
+| `ms-4` | `margin-left: 1rem` | `margin-right: 1rem` |
+| `pe-2` | `padding-right: 0.5rem` | `padding-left: 0.5rem` |
+| `end-3` | `right: 0.75rem` | `left: 0.75rem` |
+| `text-start` | `text-align: left` | `text-align: right` |
+| `border-s` | `border-left` | `border-right` |
+
+A handful of Tailwind utilities have no logical equivalent, so we ship both the LTR value and an `rtl:` override:
+
+- `translate-x-*`: emits `-translate-x-*` plus `rtl:translate-x-*` (sign-flipped).
+- `space-x-*` / `divide-x-*`: emits the original plus `rtl:space-x-reverse` / `rtl:divide-x-reverse`.
+
+## Known edges
+
+- **Radix `data-[side=left|right]:slide-in-from-*`** animations are intentionally preserved as physical. Radix's `DirectionProvider` already flips the emitted `data-side` value, so no rewrite is needed.
+- **Third-party components and template scaffolds** may still use physical classes. Run `npx shadcn@latest migrate rtl` once per project (optionally with a path glob) to convert them. Do not re-run — see the note about upstream idempotency in the intro.
+- **Text that mixes LTR and RTL content** (e.g., English code inside Arabic prose) relies on the browser's bidi algorithm. Wrap unambiguous spans with `<bdi>` or `dir="ltr"` if you need to pin direction locally.

package/.docs/raw/docs/(reference)/api-reference/adapters/attachments.mdx

@@ -0,0 +1,34 @@
+---
+title: Attachment Adapters
+description: Upload and compose file attachment handlers.
+---
+
+Attachment adapters control how files become assistant-ui attachments.
+
+```tsx
+import {
+  CompositeAttachmentAdapter,
+  SimpleImageAttachmentAdapter,
+  SimpleTextAttachmentAdapter,
+  useLocalRuntime,
+} from "@assistant-ui/react";
+
+const attachments = new CompositeAttachmentAdapter([
+  new SimpleImageAttachmentAdapter(),
+  new SimpleTextAttachmentAdapter(),
+]);
+
+const runtime = useLocalRuntime(chatModelAdapter, {
+  adapters: { attachments },
+});
+```
+
+## Common Exports
+
+- `AttachmentAdapter` is the interface for custom attachment handling.
+- `SimpleImageAttachmentAdapter` converts supported image files.
+- `SimpleTextAttachmentAdapter` converts supported text files.
+- `CompositeAttachmentAdapter` tries multiple attachment adapters in order.
+- `CloudFileAttachmentAdapter` uploads files through Assistant Cloud.
+
+For a custom implementation guide, see [Custom Attachment Adapter](/docs/integrations/attachments/custom-adapter).

package/.docs/raw/docs/(reference)/api-reference/adapters/feedback-speech.mdx

@@ -0,0 +1,41 @@
+---
+title: Feedback and Speech Adapters
+description: Capture message feedback and connect speech or dictation.
+---
+
+## Feedback
+
+`FeedbackAdapter` receives message feedback submitted through action primitives or runtime actions.
+
+```tsx
+const runtime = useLocalRuntime(chatModelAdapter, {
+  adapters: {
+    feedback: {
+      submit: async ({ message, type }) => {
+        await fetch("/api/feedback", {
+          method: "POST",
+          body: JSON.stringify({ messageId: message.id, type }),
+        });
+      },
+    },
+  },
+});
+```
+
+## Speech
+
+`SpeechSynthesisAdapter` controls text-to-speech playback. `WebSpeechSynthesisAdapter` provides a browser implementation.
+
+```tsx
+import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
+
+const runtime = useLocalRuntime(chatModelAdapter, {
+  adapters: {
+    speech: new WebSpeechSynthesisAdapter(),
+  },
+});
+```
+
+## Dictation and Suggestions
+
+Runtime adapters can also provide dictation and suggestion behavior. Dictation powers composer voice input; suggestions power prompt suggestions rendered by thread and suggestion primitives.

package/.docs/raw/docs/(reference)/api-reference/adapters/index.mdx

@@ -0,0 +1,26 @@
+---
+title: Overview
+description: Interfaces for persistence, files, speech, dictation, feedback, suggestions, and runtime composition.
+---
+
+{/* AUTO-GENERATED by scripts/generate-api-reference-overviews.mts */}
+{/* Do not edit manually. */}
+
+Adapters let you replace runtime behavior without replacing the UI. They are usually passed through runtime options or provided by integration packages.
+
+## Pages
+
+<Cards>
+  <Card title={"Runtime Adapter Context"} href={"/docs/api-reference/adapters/runtime"}>
+    {"Provide runtime adapters through React context."}
+  </Card>
+  <Card title={"Attachment Adapters"} href={"/docs/api-reference/adapters/attachments"}>
+    {"Upload and compose file attachment handlers."}
+  </Card>
+  <Card title={"Persistence Adapters"} href={"/docs/api-reference/adapters/persistence"}>
+    {"Persist message history and thread lists."}
+  </Card>
+  <Card title={"Feedback and Speech Adapters"} href={"/docs/api-reference/adapters/feedback-speech"}>
+    {"Capture message feedback and connect speech or dictation."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/adapters/persistence.mdx

@@ -0,0 +1,34 @@
+---
+title: Persistence Adapters
+description: Persist message history and thread lists.
+---
+
+assistant-ui has two persistence layers:
+
+- `ThreadHistoryAdapter` persists messages for a single runtime thread.
+- `RemoteThreadListAdapter` manages a backend-backed list of threads, including creating, loading, archiving, deleting, and title generation.
+
+## Thread History
+
+```tsx
+const runtime = useLocalRuntime(chatModelAdapter, {
+  adapters: {
+    history: myHistoryAdapter,
+  },
+});
+```
+
+Use a history adapter when the app has one active thread or when thread list management lives somewhere else.
+
+## Remote Thread Lists
+
+```tsx
+const runtime = useRemoteThreadListRuntime({
+  adapter: myRemoteThreadListAdapter,
+  runtimeHook: () => useLocalRuntime(chatModelAdapter),
+});
+```
+
+Use a remote thread list adapter when your backend owns conversation metadata and users can switch between many threads.
+
+Assistant Cloud provides managed persistence through `AssistantCloud` and cloud runtime helpers. See [Threads](/docs/runtimes/concepts/threads) for the full threading model.

package/.docs/raw/docs/(reference)/api-reference/adapters/runtime.mdx

@@ -0,0 +1,31 @@
+---
+title: Runtime Adapter Context
+description: Provide runtime adapters through React context.
+---
+
+`RuntimeAdapterProvider` lets framework integrations provide adapters around a runtime hook instead of threading them through every hook call.
+
+```tsx
+import {
+  RuntimeAdapterProvider,
+  useLocalRuntime,
+} from "@assistant-ui/react";
+
+function RuntimeRoot({ children }) {
+  return (
+    <RuntimeAdapterProvider
+      adapters={{
+        history,
+        attachments,
+        feedback,
+      }}
+    >
+      {children}
+    </RuntimeAdapterProvider>
+  );
+}
+```
+
+Runtime hooks merge context adapters with hook-specific options. Hook options are the right place for per-runtime configuration; the provider is useful when an integration or backend wrapper owns the adapter setup.
+
+Use `useRuntimeAdapters` only when building a runtime integration that needs to read the adapter context directly.

package/.docs/raw/docs/(reference)/api-reference/context-providers/index.mdx

@@ -0,0 +1,20 @@
+---
+title: Overview
+description: Context providers that establish assistant-ui runtime and message-part scopes.
+---
+
+{/* AUTO-GENERATED by scripts/generate-api-reference-overviews.mts */}
+{/* Do not edit manually. */}
+
+Context providers establish the scopes that primitives and hooks read from. Most apps only use `AssistantRuntimeProvider` directly; lower-level providers are for custom renderers and advanced composition.
+
+## Pages
+
+<Cards>
+  <Card title={"<AssistantRuntimeProvider />"} href={"/docs/api-reference/context-providers/assistant-runtime-provider"}>
+    {"Root provider that connects your runtime to assistant-ui components."}
+  </Card>
+  <Card title={"<TextMessagePartProvider />"} href={"/docs/api-reference/context-providers/text-message-part-provider"}>
+    {"Context provider for reusing text components outside of message content."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/hooks/index.mdx

@@ -0,0 +1,26 @@
+---
+title: Overview
+description: Reactive state, runtime creation, model context, and utility hooks for React.
+---
+
+{/* AUTO-GENERATED by scripts/generate-api-reference-overviews.mts */}
+{/* Do not edit manually. */}
+
+Hooks are the programmatic layer of `@assistant-ui/react`. Use them when primitives are not enough: reading state, creating runtimes, registering tools, wiring model context, or building custom behavior around the assistant runtime.
+
+## Pages
+
+<Cards>
+  <Card title={"State Hooks"} href={"/docs/api-reference/hooks/state"}>
+    {"Read assistant state and call runtime actions."}
+  </Card>
+  <Card title={"Runtime Hooks"} href={"/docs/api-reference/hooks/runtimes"}>
+    {"Hooks for creating assistant runtimes."}
+  </Card>
+  <Card title={"Model Context Hooks"} href={"/docs/api-reference/hooks/model-context"}>
+    {"Register instructions, tools, tool UIs, and data renderers."}
+  </Card>
+  <Card title={"Utility Hooks"} href={"/docs/api-reference/hooks/utilities"}>
+    {"Focused helpers for message parts, quotes, timing, and viewport behavior."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/hooks/model-context.mdx

@@ -0,0 +1,72 @@
+---
+title: Model Context Hooks
+description: Register instructions, tools, tool UIs, and data renderers.
+---
+
+Model context hooks let React components contribute model-facing configuration while they are mounted.
+
+## Instructions
+
+```tsx
+import { useAssistantInstructions } from "@assistant-ui/react";
+
+useAssistantInstructions("Answer with concise examples.");
+```
+
+## Tools
+
+`useAssistantTool` registers a tool definition, optional `execute` function, and optional renderer.
+
+```tsx
+import { useAssistantTool } from "@assistant-ui/react";
+
+useAssistantTool({
+  toolName: "get_weather",
+  description: "Get the current weather for a city",
+  parameters: {
+    type: "object",
+    properties: {
+      city: { type: "string" },
+    },
+    required: ["city"],
+  },
+  execute: async ({ city }) => ({ city, temperature: 72 }),
+  render: ({ args, result }) => (
+    <div>
+      {args.city}: {result?.temperature}F
+    </div>
+  ),
+});
+```
+
+## Tool UI
+
+Use `useAssistantToolUI` when the backend or model already owns the tool definition and the frontend only needs to render calls.
+
+```tsx
+import { useAssistantToolUI } from "@assistant-ui/react";
+
+useAssistantToolUI({
+  toolName: "get_weather",
+  render: ({ args, result, status }) => (
+    <div>{status.type === "running" ? "Loading..." : result?.summary}</div>
+  ),
+});
+```
+
+## Data UI
+
+`useAssistantDataUI` renders named data message parts.
+
+```tsx
+import { useAssistantDataUI } from "@assistant-ui/react";
+
+useAssistantDataUI({
+  name: "weather_card",
+  render: ({ data }) => <WeatherCard data={data} />,
+});
+```
+
+## Declarative Registration
+
+`makeAssistantTool` and `makeAssistantToolUI` create components that register model context when mounted. They are useful when tools should live in JSX alongside the feature that owns them.

package/.docs/raw/docs/(reference)/api-reference/hooks/runtimes.mdx

@@ -0,0 +1,41 @@
+---
+title: Runtime Hooks
+description: Hooks for creating assistant runtimes.
+---
+
+Runtime hooks create the `AssistantRuntime` passed to `AssistantRuntimeProvider`.
+
+```tsx
+import {
+  AssistantRuntimeProvider,
+  useLocalRuntime,
+} from "@assistant-ui/react";
+
+function App() {
+  const runtime = useLocalRuntime(chatModelAdapter);
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## Core Runtime Hooks
+
+- [`useLocalRuntime`](/docs/runtimes/custom/local-runtime) creates a runtime from a `ChatModelAdapter`.
+- [`useRemoteThreadListRuntime`](/docs/runtimes/concepts/threads) adds backend-backed thread list management.
+- [`useExternalStoreRuntime`](/docs/runtimes/custom/external-store) adapts an external message store.
+- [`useAssistantTransportRuntime`](/docs/runtimes/custom/assistant-transport) consumes assistant-stream transport events.
+
+## Integration Runtime Hooks
+
+- [`useChatRuntime`](/docs/runtimes/ai-sdk/overview) adapts AI SDK chat helpers.
+- [`useDataStreamRuntime`](/docs/runtimes/custom/data-stream) adapts assistant-stream data streams.
+- [`useLangGraphRuntime`](/docs/runtimes/langgraph/overview) adapts LangGraph.
+- [`useCloudThreadListRuntime`](/docs/cloud) uses Assistant Cloud for thread persistence.
+
+## Runtime Options
+
+Most runtime hooks accept adapters for persistence, attachments, speech, dictation, feedback, and suggestions. See [Adapters](/docs/api-reference/adapters) for the adapter map.

package/.docs/raw/docs/(reference)/api-reference/hooks/state.mdx

@@ -0,0 +1,48 @@
+---
+title: State Hooks
+description: Read assistant state and call runtime actions.
+---
+
+## useAuiState
+
+`useAuiState` is the primary hook for reactive state. Pass a selector and the component re-renders when the selected value changes.
+
+```tsx
+import { useAuiState } from "@assistant-ui/react";
+
+const messages = useAuiState((s) => s.thread.messages);
+const isRunning = useAuiState((s) => s.thread.isRunning);
+const composerText = useAuiState((s) => s.composer.text);
+```
+
+Selectors are scoped by context. Inside a message primitive, `s.message` refers to that message; inside an attachment primitive, `s.attachment` refers to that attachment.
+
+## useAui
+
+`useAui` returns the runtime action API. Use it for imperative operations such as sending composer text, cancelling a run, switching threads, or submitting feedback.
+
+```tsx
+import { useAui } from "@assistant-ui/react";
+
+const aui = useAui();
+
+aui.composer().setText("Hello");
+aui.composer().send();
+aui.thread().cancelRun();
+```
+
+Runtime action and state shapes are documented in the [Runtime State](/docs/api-reference/runtimes/assistant-runtime) section.
+
+## useAuiEvent
+
+`useAuiEvent` subscribes to runtime events without using the event as render state.
+
+```tsx
+import { useAuiEvent } from "@assistant-ui/react";
+
+useAuiEvent("thread.runStart", (payload) => {
+  console.log("Run started", payload);
+});
+```
+
+Use `useAuiEvent` for analytics, logging, or side effects that should not cause UI re-renders.