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

package/.docs/raw/docs/(docs)/guides/mentions.mdx

@@ -0,0 +1,406 @@
+---
+title: Mentions
+description: Let users @-mention tools or custom items in the composer to guide the LLM.
+---
+
+Mentions let users type `@` in the composer to open a popover picker, select an item (e.g. a tool), and insert a directive into the message text. The LLM can then use the directive as a hint.
+
+## How It Works
+
+```
+User types "@"  →  Trigger detected  →  Adapter provides categories/items
+                                              ↓
+              Directive inserted  ←  User selects item from popover
+                   ↓
+         Message sent with ":tool[Label]{name=id}" in text
+```
+
+The mention system has three layers:
+
+1. **Trigger detection** — watches the composer text for a trigger character (`@` by default) and extracts the query
+2. **Adapter** — provides the categories and items to display in the popover (e.g. registered tools)
+3. **Formatter** — serializes a selected item into directive text (`:type[label]{name=id}`) and parses it back for rendering
+
+## Quick Start
+
+The fastest path is the pre-built [Mention UI component](/docs/ui/mention), which wires everything together with a single shadcn component:
+
+```bash
+npx shadcn@latest add "https://r.assistant-ui.com/composer-mention"
+```
+
+See the [Mention UI guide](/docs/ui/mention) for setup steps.
+
+The rest of this guide covers the underlying concepts and customization points.
+
+## Mention Adapter
+
+A `Unstable_MentionAdapter` provides the data for the popover. All methods are **synchronous** — use external state management (React Query, SWR, local state) for async data, then expose loaded results through the adapter.
+
+```ts
+import type { Unstable_MentionAdapter } from "@assistant-ui/core";
+
+const myAdapter: Unstable_MentionAdapter = {
+  categories() {
+    return [
+      { id: "tools", label: "Tools" },
+      { id: "users", label: "Users" },
+    ];
+  },
+
+  categoryItems(categoryId) {
+    if (categoryId === "tools") {
+      return [
+        { id: "search", type: "tool", label: "Search" },
+        { id: "calculator", type: "tool", label: "Calculator" },
+      ];
+    }
+    if (categoryId === "users") {
+      return [
+        { id: "alice", type: "user", label: "Alice" },
+        { id: "bob", type: "user", label: "Bob" },
+      ];
+    }
+    return [];
+  },
+
+  // Optional — global search across all categories
+  search(query) {
+    const lower = query.toLowerCase();
+    const all = [
+      ...this.categoryItems("tools"),
+      ...this.categoryItems("users"),
+    ];
+    return all.filter(
+      (item) =>
+        item.label.toLowerCase().includes(lower) ||
+        item.id.toLowerCase().includes(lower),
+    );
+  },
+};
+```
+
+Pass the adapter to `MentionRoot`:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={myAdapter}>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input placeholder="Type @ to mention..." />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+### Built-in Tool Adapter
+
+For the common case of mentioning registered tools, use `unstable_useToolMentionAdapter`:
+
+```tsx
+import { unstable_useToolMentionAdapter } from "@assistant-ui/react";
+
+const adapter = unstable_useToolMentionAdapter({
+  // Format tool names for display (default: raw name)
+  formatLabel: (name) =>
+    name.replaceAll("_", " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+
+  // Custom category label (default: "Tools")
+  categoryLabel: "Tools",
+
+  // Explicit tool list (overrides model context tools)
+  // tools: [{ id: "search", type: "tool", label: "Search" }],
+
+  // Include model context tools alongside explicit tools
+  // includeModelContextTools: true,
+});
+```
+
+The adapter automatically reads tools from the model context (registered via `Tools()` or `useAssistantTool`). When `tools` is provided, model context tools are excluded unless `includeModelContextTools` is set to `true`.
+
+## Directive Format
+
+When a user selects a mention item, it is serialized into the composer text as a **directive**. The default format is:
+
+```
+:type[label]{name=id}
+```
+
+For example, selecting a tool named "get_weather" with label "Get Weather" produces:
+
+```
+:tool[Get Weather]{name=get_weather}
+```
+
+When `id` equals `label`, the `{name=…}` attribute is omitted for brevity:
+
+```
+:tool[search]
+```
+
+### Custom Formatter
+
+Implement `Unstable_DirectiveFormatter` to use a different format:
+
+```ts
+import type { Unstable_DirectiveFormatter } from "@assistant-ui/core";
+
+const slashFormatter: Unstable_DirectiveFormatter = {
+  serialize(item) {
+    return `/${item.id}`;
+  },
+
+  parse(text) {
+    const segments = [];
+    const re = /\/(\w+)/g;
+    let lastIndex = 0;
+    let match;
+
+    while ((match = re.exec(text)) !== null) {
+      if (match.index > lastIndex) {
+        segments.push({ kind: "text" as const, text: text.slice(lastIndex, match.index) });
+      }
+      segments.push({
+        kind: "mention" as const,
+        type: "tool",
+        label: match[1]!,
+        id: match[1]!,
+      });
+      lastIndex = re.lastIndex;
+    }
+
+    if (lastIndex < text.length) {
+      segments.push({ kind: "text" as const, text: text.slice(lastIndex) });
+    }
+
+    return segments;
+  },
+};
+```
+
+Pass it to both the mention root and the message renderer:
+
+```tsx
+// Composer
+<ComposerPrimitive.Unstable_MentionRoot adapter={adapter} formatter={slashFormatter}>
+  ...
+</ComposerPrimitive.Unstable_MentionRoot>
+
+// User messages
+const SlashDirectiveText = createDirectiveText(slashFormatter);
+<MessagePrimitive.Parts components={{ Text: SlashDirectiveText }} />
+```
+
+## Textarea vs Lexical
+
+The mention system supports two input modes:
+
+| | Textarea (default) | Lexical |
+| --- | --- | --- |
+| **Input component** | `ComposerPrimitive.Input` | `LexicalComposerInput` |
+| **Mention display in composer** | Raw directive text (`:tool[Label]`) | Inline chips (atomic nodes) |
+| **Dependencies** | None | `@assistant-ui/react-lexical`, `lexical`, `@lexical/react` |
+| **Best for** | Simple setups, minimal bundle | Rich editing, polished UX |
+
+With **textarea**, selecting a mention inserts the directive string directly into the text. The user sees `:tool[Get Weather]{name=get_weather}` in the input.
+
+With **Lexical**, selected mentions appear as styled inline chips that behave as atomic units — they can be selected, deleted, and undone as a whole. The underlying text still uses the directive format.
+
+```tsx
+import { LexicalComposerInput } from "@assistant-ui/react-lexical";
+
+<ComposerPrimitive.Unstable_MentionRoot adapter={adapter}>
+  <ComposerPrimitive.Root>
+    <LexicalComposerInput placeholder="Type @ to mention..." />
+    <ComposerPrimitive.Send />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+`LexicalComposerInput` auto-wires to the mention context — no extra props needed.
+
+## Rendering Mentions in Messages
+
+Use `DirectiveText` as the `Text` component for user messages so directives render as inline chips instead of raw syntax:
+
+```tsx
+import { DirectiveText } from "@/components/assistant-ui/composer-mention";
+
+<MessagePrimitive.Parts
+  components={{
+    Text: DirectiveText,
+  }}
+/>
+```
+
+For assistant messages, keep using your markdown renderer (e.g. `MarkdownText`) — the LLM typically does not emit directive syntax.
+
+For a custom formatter, use `createDirectiveText`:
+
+```tsx
+import { createDirectiveText } from "@/components/assistant-ui/composer-mention";
+
+const MyDirectiveText = createDirectiveText(myFormatter);
+```
+
+## Processing Mentions on the Backend
+
+The message text arrives at your backend with directives inline. Parse them to extract mentioned items:
+
+```ts
+// Default format: :type[label]{name=id}
+const DIRECTIVE_RE = /:([\w-]+)\[([^\]]+)\](?:\{name=([^}]+)\})?/g;
+
+function parseMentions(text: string) {
+  const mentions = [];
+  let match;
+  while ((match = DIRECTIVE_RE.exec(text)) !== null) {
+    mentions.push({
+      type: match[1],        // e.g. "tool"
+      label: match[2],       // e.g. "Get Weather"
+      id: match[3] ?? match[2], // e.g. "get_weather"
+    });
+  }
+  return mentions;
+}
+
+// Example:
+// parseMentions("Use :tool[Get Weather]{name=get_weather} to check")
+// → [{ type: "tool", label: "Get Weather", id: "get_weather" }]
+```
+
+You can use the extracted mentions to:
+- Force-enable specific tools for the LLM call
+- Add context about mentioned users or documents to the system prompt
+- Log which tools users request most often
+
+## Reading Mention State
+
+Use `unstable_useMentionContext` to programmatically access the mention popover state:
+
+```tsx
+import { unstable_useMentionContext } from "@assistant-ui/react";
+
+function MyComponent() {
+  const mention = unstable_useMentionContext();
+
+  // mention.open — whether the popover is visible
+  // mention.query — current search text after "@"
+  // mention.categories — filtered category list
+  // mention.items — filtered item list
+  // mention.highlightedIndex — keyboard-navigated index
+  // mention.isSearchMode — true when global search is active
+  // mention.selectItem(item) — programmatically select an item
+  // mention.close() — close the popover
+}
+```
+
+This hook must be used within a `ComposerPrimitive.Unstable_MentionRoot`.
+
+## Building a Custom Popover
+
+Use the mention primitives to build a fully custom popover:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={adapter}>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input />
+
+    <ComposerPrimitive.Unstable_MentionPopover className="popover">
+      <ComposerPrimitive.Unstable_MentionBack>
+        ← Back
+      </ComposerPrimitive.Unstable_MentionBack>
+
+      <ComposerPrimitive.Unstable_MentionCategories>
+        {(categories) =>
+          categories.map((cat) => (
+            <ComposerPrimitive.Unstable_MentionCategoryItem
+              key={cat.id}
+              categoryId={cat.id}
+            >
+              {cat.label}
+            </ComposerPrimitive.Unstable_MentionCategoryItem>
+          ))
+        }
+      </ComposerPrimitive.Unstable_MentionCategories>
+
+      <ComposerPrimitive.Unstable_MentionItems>
+        {(items) =>
+          items.map((item) => (
+            <ComposerPrimitive.Unstable_MentionItem
+              key={item.id}
+              item={item}
+            >
+              {item.label}
+            </ComposerPrimitive.Unstable_MentionItem>
+          ))
+        }
+      </ComposerPrimitive.Unstable_MentionItems>
+    </ComposerPrimitive.Unstable_MentionPopover>
+
+    <ComposerPrimitive.Send />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+### Primitives Reference
+
+| Primitive | Description |
+| --- | --- |
+| `Unstable_MentionRoot` | Provider — wraps the composer with trigger detection, keyboard navigation, and popover state |
+| `Unstable_MentionPopover` | Container — only renders when a trigger is active (`role="listbox"`) |
+| `Unstable_MentionCategories` | Render-function for the top-level category list |
+| `Unstable_MentionCategoryItem` | Button that drills into a category (`role="option"`, auto `data-highlighted`) |
+| `Unstable_MentionItems` | Render-function for items within the active category or search results |
+| `Unstable_MentionItem` | Button that inserts a mention (`role="option"`, auto `data-highlighted`) |
+| `Unstable_MentionBack` | Button that navigates back from items to categories |
+
+See the [Composer API reference](/docs/api-reference/primitives/composer) for full prop details.
+
+## Combining with Slash Commands
+
+Mentions and [slash commands](/docs/guides/slash-commands) can coexist on the same composer. Both are built on the same [trigger popover architecture](/docs/guides/slash-commands#trigger-popover-architecture) — nest both roots and they work independently:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={mentionAdapter}>
+  <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+      <ComposerPrimitive.Send />
+
+      {/* Mention popover (shows on @) */}
+      <ComposerPrimitive.Unstable_MentionPopover>
+        <ComposerPrimitive.Unstable_MentionCategories>
+          {(categories) => categories.map((cat) => (
+            <ComposerPrimitive.Unstable_MentionCategoryItem key={cat.id} categoryId={cat.id}>
+              {cat.label}
+            </ComposerPrimitive.Unstable_MentionCategoryItem>
+          ))}
+        </ComposerPrimitive.Unstable_MentionCategories>
+        <ComposerPrimitive.Unstable_MentionItems>
+          {(items) => items.map((item) => (
+            <ComposerPrimitive.Unstable_MentionItem key={item.id} item={item}>
+              {item.label}
+            </ComposerPrimitive.Unstable_MentionItem>
+          ))}
+        </ComposerPrimitive.Unstable_MentionItems>
+      </ComposerPrimitive.Unstable_MentionPopover>
+
+      {/* Slash command popover (shows on /) */}
+      <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+        <ComposerPrimitive.Unstable_TriggerPopoverItems>
+          {(items) => items.map((item, index) => (
+            <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
+              {item.label}
+            </ComposerPrimitive.Unstable_TriggerPopoverItem>
+          ))}
+        </ComposerPrimitive.Unstable_TriggerPopoverItems>
+      </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+    </ComposerPrimitive.Root>
+  </ComposerPrimitive.Unstable_SlashCommandRoot>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+## Related
+
+- [Mention UI Component](/docs/ui/mention) — pre-built shadcn component
+- [Slash Commands Guide](/docs/guides/slash-commands) — `/` command system built on the same architecture
+- [Tools Guide](/docs/guides/tools) — register tools that appear in the mention picker
+- [Composer Primitives](/docs/primitives/composer) — underlying composer primitives

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

@@ -0,0 +1,275 @@
+---
+title: Slash Commands
+description: Let users type / in the composer to trigger predefined actions from a popover picker.
+---
+
+Slash commands let users type `/` in the composer to open a popover, browse available commands, and execute one. Unlike [mentions](/docs/guides/mentions) (which insert text into the message), slash commands trigger **actions** — the `/command` text is removed from the composer and a callback fires.
+
+## How It Works
+
+```
+User types "/"  →  Trigger detected  →  Adapter provides commands
+                                              ↓
+              Command executed  ←  User selects command from popover
+                   ↓
+        "/command" text removed from composer
+```
+
+The slash command system is built on the same [trigger popover architecture](#trigger-popover-architecture) as mentions. It has two layers:
+
+1. **Adapter** — provides the list of available commands (flat list by default, or categorized for advanced use)
+2. **SlashCommandRoot** — a convenience wrapper that pre-configures the trigger character (`/`) and action-based select behavior
+
+## Quick Start
+
+### 1. Define Commands
+
+```tsx
+import {
+  unstable_useSlashCommandAdapter,
+  ComposerPrimitive,
+} from "@assistant-ui/react";
+
+// Define commands outside the component for a stable reference
+const COMMANDS = [
+  {
+    name: "summarize",
+    description: "Summarize the conversation",
+    execute: () => console.log("Summarize!"),
+  },
+  {
+    name: "translate",
+    description: "Translate text to another language",
+    execute: () => console.log("Translate!"),
+  },
+  {
+    name: "help",
+    description: "List all available commands",
+  },
+];
+
+function MyComposer() {
+  const slashAdapter = unstable_useSlashCommandAdapter({
+    commands: COMMANDS,
+  });
+
+  return (
+    <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+      <ComposerPrimitive.Root>
+        <ComposerPrimitive.Input placeholder="Type / for commands..." />
+        <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+
+        <ComposerPrimitive.Unstable_TriggerPopoverPopover className="popover">
+          <ComposerPrimitive.Unstable_TriggerPopoverItems>
+            {(items) =>
+              items.map((item, index) => (
+                <ComposerPrimitive.Unstable_TriggerPopoverItem
+                  key={item.id}
+                  item={item}
+                  index={index}
+                  className="popover-item"
+                >
+                  <strong>{item.label}</strong>
+                  {item.description && <span>{item.description}</span>}
+                </ComposerPrimitive.Unstable_TriggerPopoverItem>
+              ))
+            }
+          </ComposerPrimitive.Unstable_TriggerPopoverItems>
+        </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+      </ComposerPrimitive.Root>
+    </ComposerPrimitive.Unstable_SlashCommandRoot>
+  );
+}
+```
+
+### 2. Handle Command Selection
+
+There are two ways to handle command execution:
+
+**Via `execute` on each item** — define the action inline in the command definition:
+
+```ts
+{ name: "summarize", execute: () => runSummarize() }
+```
+
+**Via `onSelect` prop** — handle all commands in one place:
+
+```tsx
+<ComposerPrimitive.Unstable_SlashCommandRoot
+  adapter={slashAdapter}
+  onSelect={(item) => {
+    switch (item.id) {
+      case "summarize": runSummarize(); break;
+      case "translate": runTranslate(); break;
+    }
+  }}
+>
+```
+
+Both `execute` and `onSelect` fire when a command is selected. Use whichever pattern fits your code.
+
+## Custom Adapter
+
+The `unstable_useSlashCommandAdapter` hook uses a **flat list** — all commands show immediately when `/` is typed, with search filtering as the user types. This is the recommended UX for most cases.
+
+For **categorized navigation** (drill-down into groups), build the adapter manually. Return categories from `categories()` and items from `categoryItems()`. The popover will show categories first, then items within the selected category:
+
+```ts
+import type { Unstable_SlashCommandAdapter } from "@assistant-ui/core";
+
+const adapter: Unstable_SlashCommandAdapter = {
+  categories() {
+    return [
+      { id: "actions", label: "Actions" },
+      { id: "export", label: "Export" },
+    ];
+  },
+
+  categoryItems(categoryId) {
+    if (categoryId === "actions") {
+      return [
+        { id: "summarize", type: "command", label: "/summarize", description: "Summarize the conversation" },
+        { id: "translate", type: "command", label: "/translate", description: "Translate text" },
+      ];
+    }
+    if (categoryId === "export") {
+      return [
+        { id: "pdf", type: "command", label: "/export pdf", description: "Export as PDF" },
+        { id: "markdown", type: "command", label: "/export md", description: "Export as Markdown" },
+      ];
+    }
+    return [];
+  },
+
+  // Optional — enables search across all categories
+  search(query) {
+    const lower = query.toLowerCase();
+    const all = [...this.categoryItems("actions"), ...this.categoryItems("export")];
+    return all.filter(
+      (item) => item.label.toLowerCase().includes(lower) || item.description?.toLowerCase().includes(lower),
+    );
+  },
+};
+```
+
+When using a categorized adapter, add `TriggerPopoverCategories` to your popover UI:
+
+```tsx
+<ComposerPrimitive.Unstable_TriggerPopoverPopover>
+  <ComposerPrimitive.Unstable_TriggerPopoverBack>← Back</ComposerPrimitive.Unstable_TriggerPopoverBack>
+  <ComposerPrimitive.Unstable_TriggerPopoverCategories>
+    {(categories) => categories.map((cat) => (
+      <ComposerPrimitive.Unstable_TriggerPopoverCategoryItem key={cat.id} categoryId={cat.id}>
+        {cat.label}
+      </ComposerPrimitive.Unstable_TriggerPopoverCategoryItem>
+    ))}
+  </ComposerPrimitive.Unstable_TriggerPopoverCategories>
+  <ComposerPrimitive.Unstable_TriggerPopoverItems>
+    {(items) => items.map((item, index) => (
+      <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
+        {item.label}
+      </ComposerPrimitive.Unstable_TriggerPopoverItem>
+    ))}
+  </ComposerPrimitive.Unstable_TriggerPopoverItems>
+</ComposerPrimitive.Unstable_TriggerPopoverPopover>
+```
+
+## Combining with Mentions
+
+Slash commands and mentions can coexist on the same composer. Nest both roots — the [plugin protocol](#trigger-popover-architecture) ensures they don't conflict:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={mentionAdapter}>
+  <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+      <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+
+      {/* Mention popover — shows when @ is typed */}
+      <ComposerPrimitive.Unstable_MentionPopover>
+        <ComposerPrimitive.Unstable_MentionCategories>
+          {(categories) => categories.map((cat) => (
+            <ComposerPrimitive.Unstable_MentionCategoryItem key={cat.id} categoryId={cat.id}>
+              {cat.label}
+            </ComposerPrimitive.Unstable_MentionCategoryItem>
+          ))}
+        </ComposerPrimitive.Unstable_MentionCategories>
+        <ComposerPrimitive.Unstable_MentionItems>
+          {(items) => items.map((item) => (
+            <ComposerPrimitive.Unstable_MentionItem key={item.id} item={item}>
+              {item.label}
+            </ComposerPrimitive.Unstable_MentionItem>
+          ))}
+        </ComposerPrimitive.Unstable_MentionItems>
+      </ComposerPrimitive.Unstable_MentionPopover>
+
+      {/* Slash command popover — shows when / is typed */}
+      <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+        <ComposerPrimitive.Unstable_TriggerPopoverItems>
+          {(items) => items.map((item, index) => (
+            <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
+              {item.label}
+            </ComposerPrimitive.Unstable_TriggerPopoverItem>
+          ))}
+        </ComposerPrimitive.Unstable_TriggerPopoverItems>
+      </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+    </ComposerPrimitive.Root>
+  </ComposerPrimitive.Unstable_SlashCommandRoot>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+Each root provides its own `TriggerPopoverContext`. When the user types `@`, the mention popover opens. When they type `/`, the slash command popover opens. Keyboard events route to whichever popover is active.
+
+## Keyboard Navigation
+
+Same keyboard bindings as mentions:
+
+| 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) |
+
+## Trigger Popover Architecture
+
+Both mentions and slash commands are built on a generic **trigger popover** system:
+
+- `ComposerPrimitive.Unstable_TriggerPopoverRoot` — the generic root, parameterized by trigger character and select behavior
+- `ComposerPrimitive.Unstable_MentionRoot` — preset with `trigger="@"` and `onSelect: insertDirective`
+- `ComposerPrimitive.Unstable_SlashCommandRoot` — preset with `trigger="/"` and `onSelect: action`
+
+The trigger popover primitives (`TriggerPopoverPopover`, `TriggerPopoverItems`, etc.) are shared across both. You can also use `TriggerPopoverRoot` directly to build custom trigger systems with other characters (e.g. `:` for emoji).
+
+### ComposerInput Plugin Protocol
+
+Under the hood, each trigger root registers a **ComposerInputPlugin** with the composer input. This is a generic protocol that decouples the input from any specific trigger:
+
+```ts
+type ComposerInputPlugin = {
+  handleKeyDown(e: KeyboardEvent): boolean;
+  setCursorPosition(pos: number): void;
+};
+```
+
+The input iterates over registered plugins for keyboard events and cursor changes. This is what enables multiple trigger roots to coexist without conflict.
+
+## Primitives Reference
+
+| Primitive | Description |
+| --- | --- |
+| `Unstable_SlashCommandRoot` | Convenience wrapper — `TriggerPopoverRoot` with `trigger="/"` and action behavior |
+| `Unstable_TriggerPopoverRoot` | Generic root — configurable trigger character and select behavior |
+| `Unstable_TriggerPopoverPopover` | Container — only renders when a trigger is active (`role="listbox"`) |
+| `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 |
+
+## Related
+
+- [Mentions Guide](/docs/guides/mentions) — `@`-mention system built on the same architecture
+- [Suggestions Guide](/docs/guides/suggestions) — static follow-up prompts (different from slash commands)
+- [Composer Primitives](/docs/primitives/composer) — underlying composer primitives