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

package/.docs/raw/docs/guides/resumable-stream-stores.mdx

@@ -0,0 +1,152 @@
+---
+title: Custom Resumable Stream Stores
+description: Implement the ResumableStreamStore interface to back resumable streams with Postgres, Cloudflare Durable Objects, Upstash REST, InstantDB, or any other backend.
+platforms: ["react"]
+---
+
+The built-in InMemory and Redis adapters cover most deployments. Write your own `ResumableStreamStore` when you need a backend you already operate (Postgres, MySQL), an edge-native primitive (Cloudflare Durable Objects, Workers KV), an HTTP-only key-value service (Upstash REST), or a realtime database (InstantDB). The contract is six async methods over an opaque `streamId` and a monotonic byte log.
+
+## Interface walkthrough
+
+The full interface lives in `assistant-stream/resumable`:
+
+```ts title="packages/assistant-stream/src/resumable/types.ts"
+export interface ResumableStreamStore {
+  acquire(
+    streamId: string,
+    options?: ResumableStreamAcquireOptions,
+  ): Promise<ResumableStreamRole>;
+  append(streamId: string, chunk: Uint8Array): Promise<void>;
+  finalize(
+    streamId: string,
+    status: "done" | "error",
+    error?: string,
+  ): Promise<void>;
+  read(
+    streamId: string,
+    cursor: string,
+    signal: AbortSignal,
+  ): AsyncIterable<ResumableStreamEntry>;
+  status(streamId: string): Promise<ResumableStreamStatus>;
+  delete(streamId: string): Promise<void>;
+}
+```
+
+`acquire(streamId, options?)` arbitrates ownership. The first caller for a given `streamId` resolves to `"producer"`; every later caller, including those arriving after `finalize`, resolves to `"consumer"`. Implementations must perform the check and the insert atomically (see below). `options.ttlMs` overrides the store default for this stream; honor it when you set the expiration timestamp.
+
+`append(streamId, chunk)` adds a `Uint8Array` to the log under a fresh, monotonically increasing cursor. Callers expect the chunk to be observable to `read` before the promise resolves. Implementations should refresh the TTL on each call so a stream that is still actively producing does not expire mid-flight, and should reject when the stream is missing or already finalized.
+
+`finalize(streamId, status, error?)` flips the stream into a terminal state. Pending and future `read` iterables drain buffered entries and then either complete (`"done"`) or throw with `error` (`"error"`). Implementations must make `finalize` idempotent: a duplicate call with the same status is a no-op, and the producer task may retry on transient errors.
+
+`read(streamId, cursor, signal)` is the only streaming method. It yields every entry whose cursor sorts strictly after the supplied `cursor`, then waits for new appends, then completes when the stream finalizes. Aborting `signal` resolves the iterable cleanly without throwing. Networked stores typically combine a bounded fetch loop with pub/sub, long-poll, or notify wakeups; do not busy-loop.
+
+`status(streamId)` returns one of `"streaming" | "done" | "error" | "missing"` synchronously with respect to the underlying store. It exists so the context can decide whether to start a new producer or attach a consumer without holding a `read` iterator open.
+
+`delete(streamId)` removes all state for the stream. It must be a no-op when the stream does not exist, and it should cause active `read` iterables to terminate (treat outstanding readers as if the stream finalized).
+
+## Acquire semantics
+
+`acquire` is the only method that requires linearizability across processes. Two route handlers that race to start the same `streamId` must see exactly one `"producer"` result; the loser becomes a `"consumer"` and replays the winner's bytes. A single-process store can guard a `Map` with a synchronous `if (!map.has(id)) map.set(id, ...)`. Networked stores need a primitive that does the check and the insert in one round trip:
+
+- Redis: `SET key value NX EX ttl`, or `INCR` against a per-stream counter.
+- Postgres: `INSERT ... ON CONFLICT (stream_id) DO NOTHING RETURNING ...`.
+- Durable Objects: a single object instance per `streamId` plus a boolean field.
+- Upstash REST: `set` with `nx=true`.
+
+If your backend cannot offer atomicity, do not paper over it with read-then-write; you will silently produce two writers for the same stream under contention, and consumers will observe interleaved bytes.
+
+## The cursor contract
+
+Cursors are opaque strings. Callers never inspect them; the store assigns them, the context echoes them back on the next `read` call, and the store uses them to resume from the correct position. Two rules:
+
+- Cursors must be strictly monotonic per stream. Whatever scheme you pick (sequence number, ULID, Postgres `bigserial`, Redis stream id), entry N+1 sorts after entry N.
+- The empty string means start from the beginning. `read(streamId, "", signal)` yields every entry the store has, oldest first.
+
+You do not need cross-stream ordering. You do need a deterministic mapping from cursor back to position so that `read` can resume a consumer that disconnected mid-replay.
+
+## A worked example
+
+A `Map`-backed implementation suitable for a single-process server. It is deliberately small and skips TTL eviction; treat it as a starting point for a custom backend rather than a replacement for `createInMemoryResumableStreamStore`.
+
+```ts title="/lib/map-resumable-store.ts"
+import type { ResumableStreamStore } from "assistant-stream/resumable";
+
+type State = {
+  entries: { cursor: string; chunk: Uint8Array }[];
+  seq: number;
+  final?: { status: "done" | "error"; error?: string };
+  waiters: Array<() => void>;
+};
+
+export function createMapResumableStreamStore(): ResumableStreamStore {
+  const streams = new Map<string, State>();
+  const wake = (s: State) => s.waiters.splice(0).forEach((fn) => fn());
+  return {
+    async acquire(id) {
+      if (streams.has(id)) return "consumer";
+      streams.set(id, { entries: [], seq: 0, waiters: [] });
+      return "producer";
+    },
+    async append(id, chunk) {
+      const s = streams.get(id);
+      if (!s || s.final) throw new Error(`Cannot append: ${id}`);
+      s.entries.push({ cursor: (++s.seq).toString(36), chunk });
+      wake(s);
+    },
+    async finalize(id, status, error) {
+      const s = streams.get(id);
+      if (!s || s.final) return;
+      s.final = { status, error };
+      wake(s);
+    },
+    async *read(id, cursor, signal) {
+      const s = streams.get(id);
+      if (!s) throw new Error(`Stream not found: ${id}`);
+      let i = cursor === "" ? 0 : Number.parseInt(cursor, 36);
+      while (!signal.aborted) {
+        while (i < s.entries.length) yield s.entries[i++]!;
+        if (s.final) {
+          if (s.final.status === "error") throw new Error(s.final.error);
+          return;
+        }
+        await new Promise<void>((r) => {
+          s.waiters.push(r);
+          signal.addEventListener("abort", () => r(), { once: true });
+        });
+      }
+    },
+    async status(id) {
+      const s = streams.get(id);
+      return !s ? "missing" : s.final ? s.final.status : "streaming";
+    },
+    async delete(id) {
+      const s = streams.get(id);
+      if (!s) return;
+      streams.delete(id);
+      s.final ??= { status: "done" };
+      wake(s);
+    },
+  };
+}
+```
+
+## TTL and eviction
+
+`acquire` receives `options.ttlMs`; if absent, fall back to a store-level default (the built-in stores use 24 hours). Refresh the expiration on every `append` and on `finalize` so a stream that finishes near the deadline still has time to be consumed. Persist the TTL alongside the entries so a worker reading the stream much later can decide whether the data is still valid.
+
+When a stream expires, treat it the same as `finalize(streamId, "error", "Stream expired")`: any active `read` iterable must throw or terminate, and `status` must transition to `"missing"` once the eviction has run. Stores backed by Redis or a similar TTL-aware engine can lean on the engine's own expiration; SQL-backed stores need a periodic sweep, and Durable Objects can use `setAlarm`.
+
+## Wiring it up
+
+`createResumableStreamContext` takes any object that satisfies `ResumableStreamStore`. There is no registry and no extra configuration; pass your instance as `store`:
+
+```ts title="/lib/resumable-context.ts"
+import { createResumableStreamContext } from "assistant-stream/resumable";
+import { createMapResumableStreamStore } from "@/lib/map-resumable-store";
+
+export const resumableContext = createResumableStreamContext({
+  store: createMapResumableStreamStore(),
+});
+```
+
+From this point the route handlers in [Resumable Streams](/docs/guides/resumable-streams) work unchanged: `resumableContext.run(streamId, makeStream)` calls your `acquire`, `append`, and `finalize`, and `resumableContext.resume(streamId)` calls your `read`.

package/.docs/raw/docs/guides/resumable-streams.mdx

@@ -0,0 +1,210 @@
+---
+title: "Resumable Streams"
+description: Persist an in-flight LLM response on the server so the client can reload, lose its connection, or open a new tab and pick up the same stream.
+platforms: ["react"]
+---
+
+`assistant-stream/resumable` lets you continue a streaming LLM response across client reconnects. The server keeps writing to a store while the original request is in flight; if the browser reloads or loses its connection, a follow-up request replays the persisted bytes plus any new ones until the producer finalizes.
+
+It works with any encoder that already ships in `assistant-stream` (the AI SDK UI message stream, the data stream protocol, the assistant transport SSE format, or your own), because persistence happens at the byte level after encoding.
+
+## What it solves
+
+A user sends a long prompt, walks away, and reloads the tab. Without resumable streams the LLM call is wasted; with them the client picks up where it left off. The same flow handles dropped mobile connections and lets a stream started on one device be read on another, gated by an opaque stream id.
+
+If your responses are short or you do not care about reload survival, the standard `streamText().toUIMessageStreamResponse()` path is enough.
+
+## Server side: minimum wiring
+
+Construct a `ResumableStreamContext` once per process and reuse it across requests. The context is the seam between your route handlers and the storage backend.
+
+```ts title="/lib/resumable-context.ts"
+import {
+  createInMemoryResumableStreamStore,
+  createResumableStreamContext,
+} from "assistant-stream/resumable";
+
+const store = createInMemoryResumableStreamStore();
+export const resumableContext = createResumableStreamContext({ store });
+```
+
+In your chat route, wrap the response body in `ctx.run(streamId, makeStream)`. The first caller for `streamId` becomes the producer (your `makeStream` callback runs); later callers and reconnects become consumers that replay the persisted bytes.
+
+```ts title="/app/api/chat/route.ts"
+import { streamText } from "ai";
+import { RESUMABLE_STREAM_ID_HEADER } from "assistant-stream/resumable";
+import { resumableContext } from "@/lib/resumable-context";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const streamId = crypto.randomUUID();
+
+  const result = streamText({ /* model, messages, tools, ... */ });
+  const sourceBody = result.toUIMessageStreamResponse().body!;
+
+  const stream = await resumableContext.run(streamId, () => sourceBody);
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      [RESUMABLE_STREAM_ID_HEADER]: streamId,
+    },
+  });
+}
+```
+
+A separate GET endpoint replays the persisted bytes for reconnecting clients. `ctx.resume(streamId)` returns `null` when no stream exists; use `ctx.requireResume(streamId)` if you prefer to surface a `ResumableStreamError` with code `"missing"` instead.
+
+```ts title="/app/api/chat/resume/[streamId]/route.ts"
+import { RESUMABLE_STREAM_ID_HEADER } from "assistant-stream/resumable";
+import { resumableContext } from "@/lib/resumable-context";
+
+export async function GET(
+  _req: Request,
+  ctx: { params: Promise<{ streamId: string }> },
+) {
+  const { streamId } = await ctx.params;
+  const stream = await resumableContext.resume(streamId);
+  if (!stream) {
+    return new Response(JSON.stringify({ error: "stream not found" }), {
+      status: 404,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      [RESUMABLE_STREAM_ID_HEADER]: streamId,
+    },
+  });
+}
+```
+
+The context exposes two more verbs: `ctx.status(streamId)` returns `"streaming" | "done" | "error" | "missing"`, and `ctx.delete(streamId)` removes all persisted state for a stream and terminates active readers. The remaining options on `createResumableStreamContext` (`onAcquire`, `onAppend`, `onFinalize`, `onError`) are observability hooks covered in [Resumable Stream Deployment](/docs/guides/resumable-stream-deployment).
+
+## Client side: native integration
+
+`@assistant-ui/react-ai-sdk` ships a `resumable` option on `AssistantChatTransport`. It captures the stream id from the response header, redirects `chat.resumeStream()` reconnects to your resume route, and clears the stored id when the response finishes naturally. Pair it with `useChatRuntime`, which fires `chat.resumeStream()` on mount whenever a pending id is present in storage.
+
+```tsx title="/app/page.tsx"
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  AssistantChatTransport,
+  createResumableSessionStorage,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { useMemo } from "react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+const storage = createResumableSessionStorage();
+
+export default function Page() {
+  const transport = useMemo(
+    () =>
+      new AssistantChatTransport({
+        api: "/api/chat",
+        resumable: {
+          storage,
+          resumeApi: (streamId) => `/api/chat/resume/${streamId}`,
+        },
+      }),
+    [],
+  );
+  const runtime = useChatRuntime({ transport });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`createResumableSessionStorage` returns a `ResumableClientStorage` backed by `window.sessionStorage`. Pass `{ key }` to namespace per route or per chat surface, or supply your own implementation of the three methods (`getStreamId`, `setStreamId`, `clear`). If you are running on a transport that already wraps `fetch` or `prepareReconnectToStreamRequest`, the `resumable` option composes with your existing handlers.
+
+The default finish detector scans the SSE body for the AI SDK `"type":"finish"` marker. Override `isFinishEvent` on the `resumable` option when you ship a custom encoder.
+
+## Storage choices
+
+The core package ships `createInMemoryResumableStreamStore` for development and tests. State lives in a process-local `Map`, so it does not survive a server restart. Useful options include `defaultTtlMs`, `maxChunkBytes`, `maxEntriesPerStream`, `maxStreams`, and `gcIntervalMs` for periodic eviction.
+
+For production, use one of the optional Redis adapters via the `assistant-stream/resumable/redis` (node-redis v5) or `assistant-stream/resumable/ioredis` sub-paths. Both adapters batch the per-append `XADD` and TTL refresh into a single pipelined round trip, store chunk values as binary, and accept the same `keyPrefix`, `defaultTtlMs`, `pollIntervalMs`, and `maxChunkBytes` options. Cluster routing works because each stream's keys share a `{streamId}` hash tag.
+
+```ts title="/lib/resumable-context.ts"
+import {
+  createResumableStreamContext,
+  type ResumableStreamStore,
+} from "assistant-stream/resumable";
+
+async function createStore(): Promise<ResumableStreamStore> {
+  if (!process.env.REDIS_URL) {
+    const { createInMemoryResumableStreamStore } = await import(
+      "assistant-stream/resumable"
+    );
+    return createInMemoryResumableStreamStore();
+  }
+  const { createClient } = await import("redis");
+  const { createRedisResumableStreamStore } = await import(
+    "assistant-stream/resumable/redis"
+  );
+  const client = createClient({ url: process.env.REDIS_URL });
+  await client.connect();
+  return createRedisResumableStreamStore(client);
+}
+
+export const resumableContext = createResumableStreamContext({
+  store: await createStore(),
+});
+```
+
+For Postgres, Cloudflare Durable Objects, Upstash REST, or any other backend, implement the `ResumableStreamStore` interface directly. See [Custom Resumable Stream Stores](/docs/guides/resumable-stream-stores) for the contract walkthrough and a worked example.
+
+## Production checklist
+
+- **Auth.** The resume route in the snippets above will serve any caller that knows the stream id. Bind `streamId` to the requesting user at acquire time and verify the binding inside the resume handler. Treat the id as opaque, not as a credential; it leaks via response headers, `sessionStorage`, browser history, and access logs.
+- **`waitUntil` on serverless.** On Vercel and Cloudflare the request handler is killed once the response returns, which interrupts the producer task. Pass `after` from `next/server` (or your platform's `ctx.waitUntil`) when constructing the context so the task survives past the response: `createResumableStreamContext({ store, waitUntil: after })`.
+- **TTL.** Streams expire 24 hours after the last write by default. Configure with `defaultTtlMs` on the store, or override per deployment via `ttlMs` on the context. Match TTLs across the store, any owner-binding key, and any signed cookie that references a `streamId`.
+- **Stream id format.** The Redis adapters validate `streamId` against `/^[A-Za-z0-9_.:-]{1,256}$/` to keep keys well-formed. UUIDv4 is fine.
+
+For the full treatment of authorization, multi-tenant key prefixes, observability hooks, resource limits, and incident response, see [Resumable Stream Deployment](/docs/guides/resumable-stream-deployment).
+
+A new `ResumableStreamError` class is exported from `assistant-stream/resumable` with codes `"missing" | "exists" | "finalized" | "invalid-id"`; catch it in the resume route to distinguish "stream gone" from other failures.
+
+## Helpers for `AssistantStreamController` callbacks
+
+If you produce streams via `createAssistantStream` rather than the AI SDK, the package ships two helpers that bridge the controller-callback style and any encoder to the store:
+
+```ts
+import {
+  createResumableAssistantStreamResponse,
+  createResumeAssistantStreamResponse,
+} from "assistant-stream/resumable";
+import { resumableContext } from "@/lib/resumable-context";
+
+// POST handler
+return createResumableAssistantStreamResponse({
+  context: resumableContext,
+  streamId,
+  callback: (controller) => {
+    /* same shape as createAssistantStreamResponse */
+  },
+});
+
+// GET resume handler
+return createResumeAssistantStreamResponse({
+  context: resumableContext,
+  streamId,
+});
+```
+
+Both helpers default to the data-stream encoder; pass `encoder: () => new AssistantTransportEncoder()` (or any custom encoder) to override. They set the `x-resumable-stream-id` response header automatically, which is what `AssistantChatTransport`'s `resumable` adapter looks for.
+
+## Example app
+
+[`examples/with-resumable-stream`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-resumable-stream) is a runnable Next.js app that uses `useChat`, the `resumable` transport option, and `useChatRuntime`. It falls back to a built-in mock when `OPENAI_API_KEY` is unset, and switches the store from in-memory to Redis when `REDIS_URL` is set.
+
+```sh
+npx assistant-ui create my-app -e with-resumable-stream
+```

package/.docs/raw/docs/{(docs)/guides → guides}/slash-commands.mdx

@@ -1,6 +1,7 @@
 ---
 title: Slash Commands
-description: Let users type / in the composer to trigger predefined actions from a popover picker.
+description: Trigger predefined actions in your AI chat by typing / — slash command palette with popover, search, and action handlers in React via assistant-ui.
+platforms: ["react"]
 ---
 
 Slash commands let users type `/` in the composer to open a popover, browse available commands, and execute one. Unlike [mentions](/docs/guides/mentions) (which only insert a directive into the message), slash commands additionally fire an **action callback** at the moment of selection.
@@ -89,6 +90,17 @@ function MyComposer() {
 
 The label defaults to `/${id}`; override via `label` on the command. Icons are strings that your `iconMap` on the picker UI resolves to components (see [ComposerTriggerPopover](/docs/ui/composer-trigger-popover)).
 
+### `unstable_useSlashCommandAdapter` options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `commands` | `Unstable_SlashCommand[]` | — | Command definitions — each has `id`, optional `label`, `description`, `icon`, and an `execute` callback (required) |
+| `removeOnExecute` | `boolean` | `false` | When `true`, strips the trigger text from the composer after executing instead of leaving a directive chip |
+| `iconMap` | `Record<string, IconComponent>` | — | Maps `metadata.icon` / category `id` strings to React icon components; forwarded to `ComposerTriggerPopover` |
+| `fallbackIcon` | `IconComponent` | — | Fallback when no `iconMap` entry matches; forwarded to `ComposerTriggerPopover` |
+
+The hook returns `{ adapter, action, iconMap?, fallbackIcon? }` — spread directly into `<ComposerTriggerPopover char="/" {...slash} />` for one-line wiring.
+
 ### 2. Controlling the Chip
 
 By default, a selected `/summarize` is converted into a directive chip (`:command[/summarize]{name=summarize}`) in the composer text and the command's `execute` fires. This keeps an audit trail of which commands were invoked.
@@ -236,57 +248,111 @@ Slash commands and mentions live under the same `TriggerPopoverRoot`. Declare on
 
 Each `TriggerPopover` is its own scope — the `@` popover and the `/` popover read state from their own declaration and never collide. Keyboard events route to whichever popover is currently active.
 
-## Keyboard Navigation
+## Commands with Arguments
+
+Some commands accept inline arguments typed after the command word — for example `/translate en` or `/ask what is TypeScript`. Because the adapter's `search` method receives the full text after `/`, you can split on the first space to separate the command from its arguments:
 
-Same keyboard bindings as mentions:
+```tsx
+const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
+  {
+    id: "translate",
+    description: "Translate to a language, e.g. /translate en",
+    execute: () => {/* arguments extracted separately, see below */},
+  },
+  {
+    id: "ask",
+    description: "Ask about a topic, e.g. /ask what is TypeScript",
+    execute: () => {/* arguments extracted separately, see below */},
+  },
+];
 
-| Key | Action |
-| --- | --- |
-| <Kbd>ArrowDown</Kbd> | Highlight next item |
-| <Kbd>ArrowUp</Kbd> | Highlight previous item |
-| <Kbd>Enter</Kbd> | Execute highlighted command / drill into category |
-| <Kbd>Escape</Kbd> | Close popover |
-| <Kbd>Backspace</Kbd> | Go back to categories (when query is empty) |
+function MyComposer() {
+  const composerRef = useRef<HTMLTextAreaElement>(null);
+  const slash = unstable_useSlashCommandAdapter({
+    commands: SLASH_COMMANDS.map((cmd) => ({
+      ...cmd,
+      execute: () => {
+        // Read the full composer text to extract arguments
+        const raw = composerRef.current?.value ?? "";
+        // Match "/<id> <args>" at start of input
+        const match = raw.match(new RegExp(`^\\/${cmd.id}\\s+(.*)`));
+        const args = match?.[1]?.trim() ?? "";
+        handleCommand(cmd.id, args);
+      },
+    })),
+    removeOnExecute: true,
+  });
 
-## Trigger Popover Architecture
+  return (
+    <ComposerPrimitive.Unstable_TriggerPopoverRoot>
+      <ComposerPrimitive.Root>
+        <ComposerPrimitive.Input ref={composerRef} placeholder="Type / for commands..." />
+        <ComposerPrimitive.Unstable_TriggerPopover char="/" adapter={slash.adapter}>
+          <ComposerPrimitive.Unstable_TriggerPopover.Action {...slash.action} />
+          <ComposerPrimitive.Unstable_TriggerPopoverItems>
+            {(items) => items.map((item, i) => (
+              <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={i}>
+                <strong>{item.label}</strong>
+                {item.description && <span>{item.description}</span>}
+              </ComposerPrimitive.Unstable_TriggerPopoverItem>
+            ))}
+          </ComposerPrimitive.Unstable_TriggerPopoverItems>
+        </ComposerPrimitive.Unstable_TriggerPopover>
+        <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+      </ComposerPrimitive.Root>
+    </ComposerPrimitive.Unstable_TriggerPopoverRoot>
+  );
+}
+```
+
+`removeOnExecute: true` strips the `/translate en` text from the composer so the argument is consumed by the handler rather than sent to the LLM.
+
+## Async Command Loading
 
-Both mentions and slash commands are built on a generic **trigger popover** system:
+The adapter interface is synchronous, but the command list can come from any async source. Load commands into state (or a query cache) and pass the current snapshot to the hook. Because `unstable_useSlashCommandAdapter` re-runs on every render, the adapter always reflects the latest list.
 
-- `ComposerPrimitive.Unstable_TriggerPopoverRoot` — root provider that groups triggers and owns the input plugin registry
-- `ComposerPrimitive.Unstable_TriggerPopover` — declares one trigger (id, char, adapter) and renders its popover container
-- Behavior sub-primitives — exactly one per `TriggerPopover`:
-  - `Unstable_TriggerPopover.Directive` — writes a formatted directive on selection ("mention" path)
-  - `Unstable_TriggerPopover.Action` — fires a callback on selection ("slash" path); inserts a chip by default, strip with `removeOnExecute`
-- Shared sub-primitives (`TriggerPopoverCategories`, `TriggerPopoverItems`, `TriggerPopoverBack`) live inside a `TriggerPopover`
+**With React state:**
 
-You can declare any number of triggers under one root and mix behavior types.
+```tsx
+function MyComposer() {
+  const [commands, setCommands] = useState<Unstable_SlashCommand[]>([]);
 
-### ComposerInput Plugin Protocol
+  useEffect(() => {
+    fetchAvailableCommands().then(setCommands);
+  }, []);
 
-Under the hood, each `TriggerPopover` registers a **ComposerInputPlugin** with the composer input. This is a generic protocol that decouples the input from any specific trigger:
+  const slash = unstable_useSlashCommandAdapter({ commands });
 
-```ts
-type ComposerInputPlugin = {
-  handleKeyDown(e: KeyboardEvent): boolean;
-  setCursorPosition(pos: number): void;
-};
+  return (/* ... */);
+}
+```
+
+**With React Query:**
+
+```tsx
+function MyComposer() {
+  const { data: commands = [] } = useQuery({
+    queryKey: ["slash-commands"],
+    queryFn: fetchAvailableCommands,
+  });
+
+  const slash = unstable_useSlashCommandAdapter({ commands });
+
+  return (/* ... */);
+}
 ```
 
-The input iterates over registered plugins for keyboard events and cursor changes. This is what enables multiple triggers to coexist without conflict.
+## Keyboard Navigation
+
+See [ComposerTriggerPopover keyboard navigation](/docs/ui/composer-trigger-popover#keyboard-navigation) for the full key bindings table.
+
+## Trigger Popover Architecture
+
+Both mentions and slash commands are built on a generic trigger popover system where each `Unstable_TriggerPopover` declares one trigger character, an adapter, and exactly one behavior sub-primitive (`Directive` or `Action`). Multiple triggers coexist under a single `Unstable_TriggerPopoverRoot`. See the [Composer Primitives](/docs/primitives/composer) reference for the complete API.
 
 ## Primitives Reference
 
-| Primitive | Description |
-| --- | --- |
-| `Unstable_TriggerPopoverRoot` | Root — groups triggers, provides input plugin registry |
-| `Unstable_TriggerPopover` | Declares a trigger and renders its popover container |
-| `Unstable_TriggerPopover.Directive` | Behavior sub-primitive — inserts a formatted directive on selection |
-| `Unstable_TriggerPopover.Action` | Behavior sub-primitive — runs `onExecute` on selection; chip-by-default |
-| `Unstable_TriggerPopoverCategories` | Render-function for the top-level category list |
-| `Unstable_TriggerPopoverCategoryItem` | Button that drills into a category (`role="option"`, auto `data-highlighted`) |
-| `Unstable_TriggerPopoverItems` | Render-function for items within the active category or search results |
-| `Unstable_TriggerPopoverItem` | Button that selects an item (`role="option"`, auto `data-highlighted`) |
-| `Unstable_TriggerPopoverBack` | Button that navigates back from items to categories |
+See the [Composer Primitives](/docs/primitives/composer) reference for the full list of trigger popover primitives and their props.
 
 ## Related