@assistant-ui/mcp-docs-server 0.1.28 → 0.1.30

package/.docs/raw/docs/runtimes/langgraph/index.mdx

@@ -3,6 +3,10 @@ title: Getting Started
 description: Connect to LangGraph Cloud API for agent workflows with streaming.
 ---
 
+<Callout type="info">
+  If you are already using `@langchain/react`'s `useStream` hook, the alternative [`@assistant-ui/react-langchain`](/docs/runtimes/langchain) adapter may fit better. `@assistant-ui/react-langgraph` (this page) integrates with `@langchain/langgraph-sdk` directly and has the broader feature set — subgraph events, UI messages, message metadata, end-to-end cancellation. See the [comparison](/docs/runtimes/langchain/comparison).
+</Callout>
+
 ## Requirements
 
 You need a LangGraph Cloud API server. You can start a server locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or use [LangSmith](https://www.langchain.com/langsmith) for a hosted version.
@@ -60,6 +64,8 @@ NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
 ```tsx twoslash title="@/app/api/[...path]/route.ts"
 import { NextRequest, NextResponse } from "next/server";
 
+export const runtime = "edge";
+
 function getCorsHeaders() {
   return {
     "Access-Control-Allow-Origin": "*",
@@ -84,6 +90,7 @@ async function handleRequest(req: NextRequest, method: string) {
       headers: {
         "x-api-key": process.env["LANGCHAIN_API_KEY"] || "",
       },
+      signal: req.signal,
     };
 
     if (["POST", "PUT", "PATCH"].includes(method)) {
@@ -142,45 +149,15 @@ export const OPTIONS = () =>
 // @filename: /lib/chatApi.ts
 
 // ---cut---
-import { Client, type ThreadState } from "@langchain/langgraph-sdk";
-import { LangChainMessage, LangGraphCommand } from "@assistant-ui/react-langgraph";
-
-const createClient = () => {
-  const apiUrl = process.env["NEXT_PUBLIC_LANGGRAPH_API_URL"] || "/api";
-  return new Client({
-    apiUrl,
-  });
-};
-
-export const createThread = async () => {
-  const client = createClient();
-  return client.threads.create();
-};
-
-export const getThreadState = async (
-  threadId: string,
-): Promise<ThreadState<{ messages: LangChainMessage[] }>> => {
-  const client = createClient();
-  return client.threads.getState(threadId);
-};
-
-export const sendMessage = async (params: {
-  threadId: string;
-  messages?: LangChainMessage[];
-  command?: LangGraphCommand;
-}) => {
-  const client = createClient();
-  return client.runs.stream(
-    params.threadId,
-    process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
-    {
-      input: params.messages?.length
-        ? { messages: params.messages }
-        : null,
-      command: params.command,
-      streamMode: ["messages", "updates"],
-    },
-  );
+import { Client } from "@langchain/langgraph-sdk";
+
+export const createClient = () => {
+  const apiUrl =
+    process.env["NEXT_PUBLIC_LANGGRAPH_API_URL"] ||
+    (typeof window !== "undefined"
+      ? new URL("/api", window.location.href).href
+      : "/api");
+  return new Client({ apiUrl });
 };
 ```
 
@@ -196,32 +173,41 @@ export const sendMessage = async (params: {
 // ---cut---
 "use client";
 
+import { useMemo } from "react";
 import { Thread } from "@/components/assistant-ui/thread";
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+import {
+  unstable_createLangGraphStream,
+  useLangGraphRuntime,
+  type LangChainMessage,
+} from "@assistant-ui/react-langgraph";
 
-import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
+import { createClient } from "@/lib/chatApi";
 
-export function MyAssistant() {
-  const runtime = useLangGraphRuntime({
-    stream: async function* (messages, { initialize, command }) {
-      const { externalId } = await initialize();
-      if (!externalId) throw new Error("Thread not found");
+const ASSISTANT_ID = process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!;
 
-      const generator = await sendMessage({
-        threadId: externalId,
-        messages,
-        command,
-      });
+export function MyAssistant() {
+  const client = useMemo(() => createClient(), []);
+  const stream = useMemo(
+    () =>
+      unstable_createLangGraphStream({
+        client,
+        assistantId: ASSISTANT_ID,
+      }),
+    [client],
+  );
 
-      yield* generator;
-    },
+  const runtime = useLangGraphRuntime({
+    unstable_allowCancellation: true,
+    stream,
     create: async () => {
-      const { thread_id } = await createThread();
+      const { thread_id } = await client.threads.create();
       return { externalId: thread_id };
     },
     load: async (externalId) => {
-      const state = await getThreadState(externalId);
+      const state = await client.threads.getState<{
+        messages: LangChainMessage[];
+      }>(externalId);
       return {
         messages: state.values.messages,
         interrupts: state.tasks[0]?.interrupts,
@@ -320,18 +306,38 @@ const runtime = useLangGraphRuntime({
   stream: async (messages, { initialize, ...config }) => { /* ... */ },
   eventHandlers: {
     onMessageChunk: (chunk, metadata) => {
-      // Fired for each chunk in messages-tuple mode
-      // metadata contains langgraph_step, langgraph_node, ls_model_name, etc.
+      // Fired for each chunk in messages-tuple mode.
+      // `metadata` contains langgraph_step, langgraph_node, ls_model_name, etc.
+      // For pipe-namespaced events emitted by subgraphs (e.g. `messages|tools:call_abc`),
+      // `metadata.namespace` holds the suffix ("tools:call_abc"). Use it to attribute
+      // a chunk to a specific subgraph.
     },
     onValues: (values) => {
-      // Fired when a "values" event is received
+      // Fired when a top-level `values` event is received.
+      // Subgraph `values` events are routed to `onSubgraphValues` instead.
     },
     onUpdates: (updates) => {
-      // Fired when an "updates" event is received
+      // Fired when a top-level `updates` event is received.
+      // Subgraph `updates` events are routed to `onSubgraphUpdates` instead.
+    },
+    onSubgraphValues: (namespace, values) => {
+      // Fired when a subgraph `values|<namespace>` event is received
+      // (e.g. `namespace === "tools:call_abc"`). Use this to observe
+      // subgraph-internal state without mixing it into `onValues`.
+    },
+    onSubgraphUpdates: (namespace, updates) => {
+      // Fired when a subgraph `updates|<namespace>` event is received.
     },
     onMetadata: (metadata) => { /* thread metadata */ },
     onInfo: (info) => { /* informational messages */ },
-    onError: (error) => { /* stream errors */ },
+    onError: (error) => {
+      // Fired for both top-level and subgraph errors.
+    },
+    onSubgraphError: (namespace, error) => {
+      // Additionally fired for subgraph errors with the namespace.
+      // Use to attribute a subgraph failure to its source without marking
+      // the parent message as incomplete (that only happens for top-level errors).
+    },
     onCustomEvent: (type, data) => { /* custom events */ },
   },
 });
@@ -396,6 +402,51 @@ const runtime = useLangGraphRuntime({
 
 See the [Cloud Persistence guide](/docs/cloud/langgraph) for detailed setup instructions.
 
+### Custom Thread List
+
+To surface pre-existing LangGraph `thread_id`s in the thread picker without running assistant-cloud, pass a `RemoteThreadListAdapter` via `unstable_threadListAdapter`. A common implementation backs `list()` with `client.threads.search()` and `initialize()` with `client.threads.create()`.
+
+```typescript
+import type { RemoteThreadListAdapter } from "@assistant-ui/react";
+import { Client } from "@langchain/langgraph-sdk";
+
+const client = new Client({ apiUrl: process.env.NEXT_PUBLIC_LANGGRAPH_API_URL });
+
+const threadListAdapter: RemoteThreadListAdapter = {
+  async list() {
+    const threads = await client.threads.search({ limit: 50 });
+    return {
+      threads: threads.map((t) => ({
+        status: "regular",
+        remoteId: t.thread_id,
+        externalId: t.thread_id,
+        title: (t.metadata as { title?: string } | undefined)?.title,
+      })),
+    };
+  },
+  async initialize() {
+    const t = await client.threads.create();
+    return { remoteId: t.thread_id, externalId: t.thread_id };
+  },
+  async delete(remoteId) {
+    await client.threads.delete(remoteId);
+  },
+  // rename, archive, unarchive, fetch, generateTitle — see link below
+};
+
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) { /* ... */ },
+  load: async (externalId) => { /* ... */ },
+  unstable_threadListAdapter: threadListAdapter,
+});
+```
+
+Setting `remoteId === externalId` keeps the ids assistant-ui stores aligned with the LangGraph thread ids your `load` and `stream` callbacks receive. See the [Custom Thread List guide](/docs/runtimes/custom/custom-thread-list) for the full adapter contract.
+
+<Callout type="info">
+  When `unstable_threadListAdapter` is provided, the `cloud`, `create`, and `delete` options are ignored — the adapter owns the full thread-list lifecycle.
+</Callout>
+
 ## Message Editing & Regeneration
 
 LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, you need to provide a `getCheckpointId` callback that resolves the appropriate checkpoint for server-side forking.
@@ -469,3 +520,180 @@ LangGraph supports interrupting the execution flow to request user input or hand
 3. The runtime will automatically restore the interrupt state when switching threads
 
 This feature is particularly useful for applications that require user approval flows, multi-step forms, or any other interactive elements that might span multiple thread switches.
+
+## Generative UI (`ui_message`)
+
+LangGraph's [Generative UI](https://docs.langchain.com/langsmith/generative-ui-react) lets your graph emit structured UI components alongside assistant messages via `push_ui_message` (Python) or `typedUi().push()` (TypeScript). The assistant-ui LangGraph adapter translates these into [`DataMessagePart`s](/docs/guides/tool-ui) on the associated assistant message, which you render with the existing `makeAssistantDataUI` API.
+
+### Enable the `custom` stream mode
+
+UI messages are emitted through LangGraph's `custom` stream channel. Make sure your `sendMessage` helper includes `"custom"` in `streamMode`:
+
+```ts
+streamMode: ["messages", "updates", "custom"]
+```
+
+Alternatively, if your graph accumulates UI messages in state under the `ui` key (the default for `typedUi`), `"values"` also works — the adapter reads both paths.
+
+### Custom state key
+
+If your graph uses a non-default `stateKey` with `typedUi(config, { stateKey: "my_ui" })` on the server, pass the matching `uiStateKey` option to `useLangGraphRuntime` on the client:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) { /* ... */ },
+  uiStateKey: "my_ui",
+});
+```
+
+This only affects the `values` stream path — the `custom` channel carries each UI event individually and doesn't rely on the state key.
+
+### Emit a UI message from your graph
+
+```python title="Python"
+from langgraph.graph.ui import push_ui_message
+from langchain_core.messages import AIMessage
+
+async def chart_node(state, config):
+    message = AIMessage(id="msg-1", content="Here's your chart.")
+    push_ui_message(
+        "chart",
+        {"series": [1, 2, 3], "title": "Sales"},
+        message=message,  # Links the UI to this AI message
+    )
+    return {"messages": [message]}
+```
+
+```ts title="TypeScript"
+import { typedUi } from "@langchain/langgraph-sdk/react-ui/server";
+import type { ComponentRegistry } from "./components";
+
+export async function chartNode(state, config) {
+  const ui = typedUi<ComponentRegistry>(config);
+  const message = { id: "msg-1", type: "ai", content: "Here's your chart." };
+  ui.push(
+    { name: "chart", props: { series: [1, 2, 3], title: "Sales" } },
+    { message },
+  );
+  return { messages: [message] };
+}
+```
+
+Passing `message` (Python) or `{ message }` (TypeScript) is what links the UI component to a specific assistant message — the adapter reads `metadata.message_id` to attach the generated `DataMessagePart` to the correct message in the thread.
+
+### Register a renderer on the client
+
+```tsx title="@/components/ChartUI.tsx"
+import { makeAssistantDataUI } from "@assistant-ui/react";
+
+type ChartProps = {
+  series: number[];
+  title: string;
+};
+
+export const ChartUI = makeAssistantDataUI<ChartProps>({
+  name: "chart",
+  render: ({ data }) => (
+    <div>
+      <h3>{data.title}</h3>
+      <Chart series={data.series} />
+    </div>
+  ),
+});
+```
+
+Mount the component once somewhere inside the `AssistantRuntimeProvider` tree. It renders nothing itself — it only registers the renderer:
+
+```tsx title="@/components/MyAssistant.tsx"
+<AssistantRuntimeProvider runtime={runtime}>
+  <ChartUI />
+  <Thread />
+</AssistantRuntimeProvider>
+```
+
+When a matching UI message arrives, the adapter appends a `{ type: "data", name: "chart", data: { series, title } }` part to the parent assistant message and the registered component renders inline.
+
+### Register renderers via `uiComponents`
+
+Instead of mounting separate `makeAssistantDataUI` components, you can register renderers directly on the runtime hook via the `uiComponents` option:
+
+```tsx title="@/components/MyAssistant.tsx"
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) { /* ... */ },
+  uiComponents: {
+    renderers: {
+      chart: ({ data }) => <Chart series={data.series} title={data.title} />,
+      table: ({ data }) => <DataTable rows={data.rows} />,
+    },
+  },
+});
+```
+
+Static `renderers` are matched by `ui_message` name. If no match is found, the part renders nothing unless a `fallback` is provided.
+
+### Dynamic loading with `fallback`
+
+LangSmith's [Generative UI](https://docs.langchain.com/langsmith/generative-ui-react) supports colocating UI code with your graph and loading it at runtime via `LoadExternalComponent`. The `fallback` option handles any `ui_message` name that has no static renderer:
+
+```tsx title="@/components/MyAssistant.tsx"
+import { LoadExternalComponent } from "@langchain/langgraph-sdk/react-ui";
+
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) { /* ... */ },
+  uiComponents: {
+    fallback: ({ name, data }) => (
+      <LoadExternalComponent name={name} props={data} />
+    ),
+    renderers: {
+      chart: ({ data }) => <Chart {...data} />,
+    },
+  },
+});
+```
+
+With this setup:
+- A `ui_message` with `name: "chart"` renders the static `Chart` component
+- Any other name (e.g. `"dashboard"`, `"form"`) is handled by `fallback`, which fetches the component from LangSmith at runtime
+
+The `fallback` component receives the same props as any data renderer: `name`, `data`, and part state metadata. This lets you pass the component name and props straight through to `LoadExternalComponent`.
+
+### Semantics
+
+The adapter mirrors the reducer in `@langchain/langgraph-sdk/react-ui` exactly:
+
+- UI messages are keyed by their own `id`. Pushing the same id again **replaces** the existing entry
+- Passing `metadata: { merge: true }` shallow-merges `props` onto the previous entry
+- Emitting `{ type: "remove-ui", id }` (via `delete_ui_message` / `ui.delete(id)`) removes the entry
+- UI messages without `metadata.message_id` are held in the runtime but not injected into any message; use `useLangGraphUIMessages()` to access the raw list if needed
+
+### Restore persisted UI messages on thread switch
+
+If your graph persists UI messages in state via `typedUi`, return them from the `load` callback so they're restored when the user switches threads or refreshes the page:
+
+```tsx
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) { /* ... */ },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      uiMessages: state.values.ui,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+});
+```
+
+Without this, each reload starts with an empty UI list even though the messages themselves are loaded.
+
+### Escape hatch: `useLangGraphUIMessages`
+
+```tsx
+import { useLangGraphUIMessages } from "@assistant-ui/react-langgraph";
+
+function Sidebar() {
+  const uiMessages = useLangGraphUIMessages();
+  // Filter, group, or render UI messages outside the thread
+  return <>{uiMessages.map(/* ... */)}</>;
+}
+```

package/.docs/raw/docs/runtimes/pick-a-runtime.mdx

@@ -11,7 +11,8 @@ Choosing the right runtime is crucial for your assistant-ui implementation. This
 graph TD
     A[What's your starting point?] --> B{Existing Framework?}
     B -->|Vercel AI SDK| C[Use AI SDK Integration]
-    B -->|LangGraph| D[Use LangGraph Runtime]
+    B -->|LangGraph via langgraph-sdk| D1[Use react-langgraph]
+    B -->|LangChain via @langchain/react useStream| D2[Use react-langchain]
     B -->|LangServe| E[Use LangServe Runtime]
     B -->|Mastra| F[Use Mastra Runtime]
     B -->|AG-UI Protocol| J[Use AG-UI Runtime]
@@ -55,9 +56,14 @@ For popular frameworks, we provide ready-to-use integrations built on top of our
   />
   <Card
     title="LangGraph"
-    description="For complex agent workflows with LangChain's graph framework"
+    description="Integrates with `@langchain/langgraph-sdk` directly. Broader feature set: subgraph events, UI messages, message metadata, cancellation."
     href="/docs/runtimes/langgraph"
   />
+  <Card
+    title="LangChain useStream"
+    description="Wraps `useStream` from `@langchain/react`. Lighter-weight, stays aligned with upstream. Fewer features today."
+    href="/docs/runtimes/langchain"
+  />
   <Card
     title="LangServe"
     description="For LangChain applications deployed with LangServe"
@@ -87,13 +93,14 @@ For popular frameworks, we provide ready-to-use integrations built on top of our
 The pre-built integrations (AI SDK, LangGraph, etc.) are **not separate runtime types**. They're convenient wrappers built on top of our core runtimes:
 
 - **AI SDK Integration** → Built on `LocalRuntime` with streaming adapter
-- **LangGraph Runtime** → Built on `LocalRuntime` with graph execution adapter
+- **LangGraph Runtime** → Built on `ExternalStoreRuntime`, integrates with `@langchain/langgraph-sdk`
+- **LangChain useStream Runtime** → Built on `ExternalStoreRuntime`, wraps `useStream` from `@langchain/react`
 - **LangServe Runtime** → Built on `LocalRuntime` with LangServe client adapter
 - **Mastra Runtime** → Built on `LocalRuntime` with workflow adapter
 - **AG-UI Runtime** → Built on `LocalRuntime` with AG-UI protocol adapter
 - **A2A Runtime** → Built on `LocalRuntime` with Agent-to-Agent protocol adapter
 
-This means you get all the benefits of `LocalRuntime` (automatic state management, built-in features) with zero configuration for your specific framework.
+This means pre-built integrations give you assistant-ui's features — state management, streaming, UI primitives — with zero configuration for your specific framework, regardless of whether the adapter happens to build on `LocalRuntime` or `ExternalStoreRuntime` internally. The list above tells you which core runtime each adapter uses.
 
 ### When to Use Pre-Built vs Core Runtimes
 
@@ -228,6 +235,7 @@ Explore our implementation examples:
    - [`LocalRuntime` Guide](/docs/runtimes/custom/local)
    - [`ExternalStoreRuntime` Guide](/docs/runtimes/custom/external-store)
    - [LangGraph Integration](/docs/runtimes/langgraph)
+   - [LangChain useStream Integration](/docs/runtimes/langchain)
 3. **Start with an example** from our [examples repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples)
 4. **Add features progressively** using adapters
 5. **Consider Assistant Cloud** for production persistence

package/.docs/raw/docs/ui/composer-trigger-popover.mdx

@@ -0,0 +1,199 @@
+---
+title: Composer Trigger Popover
+description: Reusable picker UI for @ mentions, / slash commands, and any other character-triggered popover.
+---
+
+import { ComposerTriggerPopoverSample } from "@/components/docs/samples/composer-trigger-popover";
+
+<ComposerTriggerPopoverSample />
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Add `composer-trigger-popover`
+
+<InstallCommand shadcn={["composer-trigger-popover"]} />
+
+This adds `/components/assistant-ui/composer-trigger-popover.tsx` — a generic picker UI (Categories + Items + Back) driven by an adapter and one of two behavior props: `directive` (insert a chip) or `action` (run a callback).
+
+  </Step>
+  <Step>
+
+### Wrap the composer
+
+Place `ComposerPrimitive.Unstable_TriggerPopoverRoot` around your composer. Any number of `ComposerTriggerPopover` declarations can live inside — each with its own trigger character, adapter, and behavior prop.
+
+```tsx title="components/assistant-ui/thread.tsx"
+import { ComposerPrimitive } from "@assistant-ui/react";
+import { ComposerTriggerPopover } from "@/components/assistant-ui/composer-trigger-popover";
+
+const Composer = () => (
+  <ComposerPrimitive.Unstable_TriggerPopoverRoot>
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+      <ComposerPrimitive.Send />
+
+      {/* triggers declared here */}
+    </ComposerPrimitive.Root>
+  </ComposerPrimitive.Unstable_TriggerPopoverRoot>
+);
+```
+
+  </Step>
+</Steps>
+
+## @ Mention
+
+Pair the popover with `unstable_useMentionAdapter` — the hook returns a spreadable `{ adapter, directive }` bundle so selecting an item writes a `:tool[Label]{name=id}` directive into the composer text.
+
+```tsx
+import { unstable_useMentionAdapter } from "@assistant-ui/react";
+import { WrenchIcon } from "lucide-react";
+
+const mention = unstable_useMentionAdapter();
+
+<ComposerTriggerPopover
+  char="@"
+  {...mention}
+  fallbackIcon={WrenchIcon}
+/>;
+```
+
+Override formatter or add an `onInserted` callback via hook options: `unstable_useMentionAdapter({ formatter, onInserted })`.
+
+`unstable_useMentionAdapter` also accepts `items` (flat custom list), `categories` (multi-category drill-down), and `includeModelContextTools` for fine-grained control. See the [Mentions guide](/docs/guides/mentions#built-in-mention-adapter).
+
+Render selected mentions as chips in user messages with [`DirectiveText`](/docs/ui/directive-text). For inline chips **inside** the composer, use [`LexicalComposerInput`](/docs/guides/mentions#textarea-vs-lexical).
+
+## / Slash Command
+
+Use [`unstable_useSlashCommandAdapter`](/docs/guides/slash-commands) to bundle commands (data + `execute`) into `{ adapter, action }` — then plug both into `ComposerTriggerPopover`. By default a directive chip is left in the composer as an audit trail; pass `removeOnExecute` to strip the `/command` text entirely. `iconMap` maps `metadata.icon` strings on items and categories to Lucide icons.
+
+```tsx
+import {
+  unstable_useSlashCommandAdapter,
+  type Unstable_SlashCommand,
+} from "@assistant-ui/react";
+import { FileTextIcon, GlobeIcon, LanguagesIcon, SlashIcon } from "lucide-react";
+
+const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
+  {
+    id: "summarize",
+    description: "Summarize the conversation",
+    icon: "FileText",
+    execute: () => {/* ... */},
+  },
+  {
+    id: "translate",
+    description: "Translate to another language",
+    icon: "Languages",
+    execute: () => {/* ... */},
+  },
+  {
+    id: "search",
+    description: "Search the web",
+    icon: "Globe",
+    execute: () => {/* ... */},
+  },
+];
+
+function SlashComposer() {
+  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
+
+  return (
+    <ComposerTriggerPopover
+      char="/"
+      {...slash}
+      iconMap={{
+        FileText: FileTextIcon,
+        Languages: LanguagesIcon,
+        Globe: GlobeIcon,
+      }}
+      fallbackIcon={SlashIcon}
+    />
+  );
+}
+```
+
+## Combining Triggers
+
+Multiple popovers coexist under one `TriggerPopoverRoot`. Each reads state from its own declaration, so `@` and `/` never collide.
+
+```tsx
+const commandHandlers: Record<string, () => void> = {
+  summarize: () => {/* ... */},
+  translate: () => {/* ... */},
+};
+
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+
+    <ComposerTriggerPopover
+      char="@"
+      adapter={mentionAdapter}
+      directive={{ formatter: unstable_defaultDirectiveFormatter }}
+      fallbackIcon={WrenchIcon}
+    />
+    <ComposerTriggerPopover
+      char="/"
+      adapter={slashAdapter}
+      action={{
+        formatter: unstable_defaultDirectiveFormatter,
+        onExecute: (item) => commandHandlers[item.id]?.(),
+      }}
+      iconMap={slashIcons}
+      fallbackIcon={SlashIcon}
+    />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+| --- | --- |
+| <Kbd>ArrowDown</Kbd> | Highlight next item |
+| <Kbd>ArrowUp</Kbd> | Highlight previous item |
+| <Kbd>Enter</Kbd> | Select highlighted item / drill into category |
+| <Kbd>Escape</Kbd> | Close popover |
+| <Kbd>Backspace</Kbd> | Go back to categories (when query is empty) |
+
+## API Reference
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `char` | `string` | — | Trigger character, e.g. `"@"` or `"/"` (required; unique within the root) |
+| `adapter` | `Unstable_TriggerAdapter` | — | Provides categories, items, and search (required) |
+| `directive` | `{ formatter, onInserted?, chip? }` | — | Enables directive-insert behavior. Mutually exclusive with `action`. |
+| `action` | `{ formatter, onExecute, removeOnExecute?, chip? }` | — | Enables action behavior. Mutually exclusive with `directive`. |
+| `iconMap` | `Record<string, IconComponent>` | — | Maps `item.metadata.icon` / `category.metadata.icon` strings to icons |
+| `fallbackIcon` | `IconComponent` | `SparklesIcon` | Icon used when no `iconMap` entry matches |
+| `backLabel` | `string` | `"Back"` | Back button label |
+| `emptyCategoriesLabel` | `string` | `"No items available"` | Shown when no categories are available |
+| `emptyItemsLabel` | `string` | `"No matching items"` | Shown when no items match |
+
+All other props (`className`, etc.) forward to the underlying popover `div`.
+
+### `directive` object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `formatter` | `Unstable_DirectiveFormatter` | Serializes the selected item into the directive text written to the composer |
+| `onInserted` | `(item) => void` | Optional callback fired after the directive has been inserted |
+
+### `action` object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `formatter` | `Unstable_DirectiveFormatter` | Serializes the selected item into the chip left behind (unused when `removeOnExecute`) |
+| `onExecute` | `(item) => void` | Callback fired when an item is selected |
+| `removeOnExecute` | `boolean` | When `true`, strips the trigger text instead of leaving a chip. Default `false`. |
+
+## Related
+
+- [Directive Text](/docs/ui/directive-text) — renderer for mention chips in user messages
+- [Mentions guide](/docs/guides/mentions) — `@`-mention architecture and formatter details
+- [Slash Commands guide](/docs/guides/slash-commands) — `/`-command architecture