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

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"
                 >
@@ -598,21 +602,21 @@ export default nextConfig;
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.8.0",
-    "next": "^16.2.3",
+    "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.10",
+    "tailwindcss": "^4.2.4",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }
 

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

@@ -17,30 +17,32 @@ User types "@"  →  Trigger detected  →  Adapter provides categories/items
 
 The mention system has three layers:
 
-1. **Trigger detection** — watches the composer text for a trigger character (`@` by default) and extracts the query
+1. **Trigger detection** — the composer input watches 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
 
+Under the hood, mentions are one kind of [trigger popover](/docs/guides/slash-commands#trigger-popover-architecture). A mention declares its behavior with a `<TriggerPopover.Directive>` sub-primitive, which writes the formatter-serialized directive into the composer on selection.
+
 ## Quick Start
 
-The fastest path is the pre-built [Mention UI component](/docs/ui/mention), which wires everything together with a single shadcn component:
+The fastest path is the pre-built [Mention UI components](/docs/ui/composer-trigger-popover), which wire everything together with two shadcn components — the popover picker and the message-side chip renderer:
 
 ```bash
-npx shadcn@latest add "https://r.assistant-ui.com/composer-mention"
+npx shadcn@latest add "https://r.assistant-ui.com/composer-trigger-popover" "https://r.assistant-ui.com/directive-text"
 ```
 
-See the [Mention UI guide](/docs/ui/mention) for setup steps.
+See the [Composer Trigger Popover](/docs/ui/composer-trigger-popover) and [Directive Text](/docs/ui/directive-text) guides for setup steps.
 
 The rest of this guide covers the underlying concepts and customization points.
 
-## Mention Adapter
+## Trigger 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.
+A `Unstable_TriggerAdapter` 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";
+import type { Unstable_TriggerAdapter } from "@assistant-ui/core";
 
-const myAdapter: Unstable_MentionAdapter = {
+const myAdapter: Unstable_TriggerAdapter = {
   categories() {
     return [
       { id: "tools", label: "Tools" },
@@ -80,40 +82,142 @@ const myAdapter: Unstable_MentionAdapter = {
 };
 ```
 
-Pass the adapter to `MentionRoot`:
+Pass the adapter to `TriggerPopover` and declare a `Directive` sub-primitive to bind the insertion behavior:
 
 ```tsx
-<ComposerPrimitive.Unstable_MentionRoot adapter={myAdapter}>
+import { ComposerPrimitive } from "@assistant-ui/react";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
   <ComposerPrimitive.Root>
     <ComposerPrimitive.Input placeholder="Type @ to mention..." />
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="@"
+      adapter={myAdapter}
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Directive
+        formatter={unstable_defaultDirectiveFormatter}
+      />
+      <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) => (
+            <ComposerPrimitive.Unstable_TriggerPopoverItem
+              key={item.id}
+              item={item}
+            >
+              {item.label}
+            </ComposerPrimitive.Unstable_TriggerPopoverItem>
+          ))
+        }
+      </ComposerPrimitive.Unstable_TriggerPopoverItems>
+    </ComposerPrimitive.Unstable_TriggerPopover>
   </ComposerPrimitive.Root>
-</ComposerPrimitive.Unstable_MentionRoot>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
 ```
 
-### Built-in Tool Adapter
+Exactly one behavior sub-primitive (`Directive` or `Action`) is allowed per `TriggerPopover`. The parent reads the registered behavior and wires the selection machinery.
 
-For the common case of mentioning registered tools, use `unstable_useToolMentionAdapter`:
+### Built-in Mention Adapter
+
+`unstable_useMentionAdapter` covers the common cases: mention registered tools, add your own items, mix tools with custom items, or show multi-category drill-down.
+
+**Tools from model context (default):**
 
 ```tsx
-import { unstable_useToolMentionAdapter } from "@assistant-ui/react";
+import { unstable_useMentionAdapter } from "@assistant-ui/react";
+
+const mention = unstable_useMentionAdapter();
+// → { adapter, directive } — spread into <ComposerTriggerPopover {...mention} />
+// Default: single "Tools" category reading from useAssistantTool registrations
+```
 
-const adapter = unstable_useToolMentionAdapter({
-  // Format tool names for display (default: raw name)
-  formatLabel: (name) =>
-    name.replaceAll("_", " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+**Custom items only (no tools):**
 
-  // Custom category label (default: "Tools")
-  categoryLabel: "Tools",
+```tsx
+const mention = unstable_useMentionAdapter({
+  items: [
+    { id: "alice", type: "user", label: "Alice", icon: "User" },
+    { id: "bob", type: "user", label: "Bob", icon: "User" },
+  ],
+});
+```
 
-  // Explicit tool list (overrides model context tools)
-  // tools: [{ id: "search", type: "tool", label: "Search" }],
+**Mix custom items with model-context tools (flat):**
 
-  // Include model context tools alongside explicit tools
-  // includeModelContextTools: true,
+```tsx
+const mention = unstable_useMentionAdapter({
+  items: [{ id: "kb", type: "doc", label: "Knowledge Base", icon: "Book" }],
+  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`.
+**Multi-category drill-down:**
+
+```tsx
+const mention = unstable_useMentionAdapter({
+  categories: [
+    {
+      id: "users",
+      label: "Users",
+      items: [
+        { id: "alice", type: "user", label: "Alice", icon: "User" },
+        { id: "bob", type: "user", label: "Bob", icon: "User" },
+      ],
+    },
+    {
+      id: "files",
+      label: "Files",
+      items: [
+        { id: "readme", type: "file", label: "README.md", icon: "FileText" },
+      ],
+    },
+  ],
+  // Tools auto-appended as their own category (default id "tools", label "Tools")
+  includeModelContextTools: true,
+});
+```
+
+**Tool formatting and category override:**
+
+```tsx
+const mention = unstable_useMentionAdapter({
+  categories: [{ id: "users", label: "Users", items: [...] }],
+  includeModelContextTools: {
+    category: { id: "integrations", label: "Integrations" },
+    formatLabel: (name) =>
+      name.replaceAll("_", " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+    icon: "Wrench",
+  },
+});
+```
+
+**Options summary:**
+
+| Option | Type | Behavior |
+| --- | --- | --- |
+| `items` | `Unstable_Mention[]` | Flat list (ignored when `categories` is set) |
+| `categories` | `{id, label, items}[]` | Drill-down groups |
+| `includeModelContextTools` | `boolean \| object` | Default: `true` iff neither `items` nor `categories` |
+| `formatter` | `Unstable_DirectiveFormatter` | Override directive serialization (default: `unstable_defaultDirectiveFormatter`) |
+| `onInserted` | `(item) => void` | Fires after the directive is inserted into the composer |
+| `iconMap` | `Record<string, IconComponent>` | Maps `metadata.icon` / category `id` strings to React components |
+| `fallbackIcon` | `IconComponent` | Fallback when no entry in `iconMap` matches |
+
+`icon` on each mention is a shortcut for `metadata.icon` that the picker UI resolves via `iconMap`. Dedup between custom items and model-context tools is by `id` — explicit items win.
+
+The hook returns `{ adapter, directive, iconMap?, fallbackIcon? }` — spread into `<ComposerTriggerPopover {...mention} />` for one-line wiring. Callers consuming the raw primitives instead destructure: `mention.adapter`, `mention.directive.formatter`, etc.
 
 ## Directive Format
 
@@ -175,13 +279,17 @@ const slashFormatter: Unstable_DirectiveFormatter = {
 };
 ```
 
-Pass it to both the mention root and the message renderer:
+Pass it to the trigger's `Directive` sub-primitive and the message renderer:
 
 ```tsx
 // Composer
-<ComposerPrimitive.Unstable_MentionRoot adapter={adapter} formatter={slashFormatter}>
+<ComposerPrimitive.Unstable_TriggerPopover
+  char="@"
+  adapter={adapter}
+>
+  <ComposerPrimitive.Unstable_TriggerPopover.Directive formatter={slashFormatter} />
   ...
-</ComposerPrimitive.Unstable_MentionRoot>
+</ComposerPrimitive.Unstable_TriggerPopover>
 
 // User messages
 const SlashDirectiveText = createDirectiveText(slashFormatter);
@@ -206,22 +314,29 @@ With **Lexical**, selected mentions appear as styled inline chips that behave as
 ```tsx
 import { LexicalComposerInput } from "@assistant-ui/react-lexical";
 
-<ComposerPrimitive.Unstable_MentionRoot adapter={adapter}>
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
   <ComposerPrimitive.Root>
     <LexicalComposerInput placeholder="Type @ to mention..." />
     <ComposerPrimitive.Send />
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="@"
+      adapter={adapter}
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Directive formatter={formatter} />
+      ...
+    </ComposerPrimitive.Unstable_TriggerPopover>
   </ComposerPrimitive.Root>
-</ComposerPrimitive.Unstable_MentionRoot>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
 ```
 
-`LexicalComposerInput` auto-wires to the mention context — no extra props needed.
+`LexicalComposerInput` automatically discovers every `Directive` trigger registered under `TriggerPopoverRoot` and renders their selections as inline chips.
 
 ## 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";
+import { DirectiveText } from "@/components/assistant-ui/directive-text";
 
 <MessagePrimitive.Parts
   components={{
@@ -235,7 +350,7 @@ For assistant messages, keep using your markdown renderer (e.g. `MarkdownText`)
 For a custom formatter, use `createDirectiveText`:
 
 ```tsx
-import { createDirectiveText } from "@/components/assistant-ui/composer-mention";
+import { createDirectiveText } from "@/components/assistant-ui/directive-text";
 
 const MyDirectiveText = createDirectiveText(myFormatter);
 ```
@@ -273,134 +388,158 @@ You can use the extracted mentions to:
 
 ## Reading Mention State
 
-Use `unstable_useMentionContext` to programmatically access the mention popover state:
+Use `unstable_useTriggerPopoverScopeContext` inside the `TriggerPopover` to programmatically access the popover state for that trigger:
 
 ```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
+import { unstable_useTriggerPopoverScopeContext } from "@assistant-ui/react";
+
+function MyPopoverContent() {
+  const scope = unstable_useTriggerPopoverScopeContext();
+
+  // scope.open — whether the popover is visible
+  // scope.query — current search text after the trigger
+  // scope.categories — filtered category list
+  // scope.items — filtered item list
+  // scope.highlightedIndex — keyboard-navigated index
+  // scope.isSearchMode — true when global search is active
+  // scope.selectItem(item) — programmatically select an item
+  // scope.close() — close the popover
+
+  return null;
 }
 ```
 
-This hook must be used within a `ComposerPrimitive.Unstable_MentionRoot`.
+This hook must be used inside a `ComposerPrimitive.Unstable_TriggerPopover`.
+
+To iterate every registered trigger (e.g. from a custom input implementation), use `unstable_useTriggerPopoverTriggers` inside `TriggerPopoverRoot`.
 
 ## Building a Custom Popover
 
-Use the mention primitives to build a fully custom popover:
+Use the trigger popover primitives to build a fully custom popover:
 
 ```tsx
-<ComposerPrimitive.Unstable_MentionRoot adapter={adapter}>
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
   <ComposerPrimitive.Root>
     <ComposerPrimitive.Input />
 
-    <ComposerPrimitive.Unstable_MentionPopover className="popover">
-      <ComposerPrimitive.Unstable_MentionBack>
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="@"
+      adapter={adapter}
+      className="popover"
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Directive formatter={formatter} />
+
+      <ComposerPrimitive.Unstable_TriggerPopoverBack>
         ← Back
-      </ComposerPrimitive.Unstable_MentionBack>
+      </ComposerPrimitive.Unstable_TriggerPopoverBack>
 
-      <ComposerPrimitive.Unstable_MentionCategories>
+      <ComposerPrimitive.Unstable_TriggerPopoverCategories>
         {(categories) =>
           categories.map((cat) => (
-            <ComposerPrimitive.Unstable_MentionCategoryItem
+            <ComposerPrimitive.Unstable_TriggerPopoverCategoryItem
               key={cat.id}
               categoryId={cat.id}
             >
               {cat.label}
-            </ComposerPrimitive.Unstable_MentionCategoryItem>
+            </ComposerPrimitive.Unstable_TriggerPopoverCategoryItem>
           ))
         }
-      </ComposerPrimitive.Unstable_MentionCategories>
+      </ComposerPrimitive.Unstable_TriggerPopoverCategories>
 
-      <ComposerPrimitive.Unstable_MentionItems>
+      <ComposerPrimitive.Unstable_TriggerPopoverItems>
         {(items) =>
           items.map((item) => (
-            <ComposerPrimitive.Unstable_MentionItem
+            <ComposerPrimitive.Unstable_TriggerPopoverItem
               key={item.id}
               item={item}
             >
               {item.label}
-            </ComposerPrimitive.Unstable_MentionItem>
+            </ComposerPrimitive.Unstable_TriggerPopoverItem>
           ))
         }
-      </ComposerPrimitive.Unstable_MentionItems>
-    </ComposerPrimitive.Unstable_MentionPopover>
+      </ComposerPrimitive.Unstable_TriggerPopoverItems>
+    </ComposerPrimitive.Unstable_TriggerPopover>
 
     <ComposerPrimitive.Send />
   </ComposerPrimitive.Root>
-</ComposerPrimitive.Unstable_MentionRoot>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
 ```
 
 ### 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 |
+| `Unstable_TriggerPopoverRoot` | Root provider — groups one or more triggers, manages plugin registry |
+| `Unstable_TriggerPopover` | Declares a trigger (id, char, adapter) and renders the popover container |
+| `Unstable_TriggerPopover.Directive` | Behavior sub-primitive — inserts a formatted directive into the composer on selection |
+| `Unstable_TriggerPopover.Action` | Behavior sub-primitive — runs a callback on selection; inserts a 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 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:
+Mentions and [slash commands](/docs/guides/slash-commands) coexist on the same composer — they're both just triggers on the shared `TriggerPopoverRoot`:
 
 ```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>
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+    <ComposerPrimitive.Send />
+
+    {/* Mention popover (shows on @) */}
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="@"
+      adapter={mention.adapter}
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Directive {...mention.directive} />
+      <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) => (
+          <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item}>
+            {item.label}
+          </ComposerPrimitive.Unstable_TriggerPopoverItem>
+        ))}
+      </ComposerPrimitive.Unstable_TriggerPopoverItems>
+    </ComposerPrimitive.Unstable_TriggerPopover>
+
+    {/* Slash command popover (shows on /) */}
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="/"
+      adapter={slashAdapter}
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Action
+        formatter={unstable_defaultDirectiveFormatter}
+        onExecute={(item) => commandHandlers[item.id]?.()}
+      />
+      <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_TriggerPopover>
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
 ```
 
+Each `TriggerPopover` declares its own scope — its popover UI reads state only from that declaration, so `@` and `/` never collide.
+
 ## Related
 
-- [Mention UI Component](/docs/ui/mention) — pre-built shadcn component
+- [ComposerTriggerPopover UI Component](/docs/ui/composer-trigger-popover) — pre-built shadcn component
+- [DirectiveText UI Component](/docs/ui/directive-text) — renders mention chips in user messages
 - [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