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

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

package/.docs/raw/docs/ui/directive-text.mdx

@@ -0,0 +1,113 @@
+---
+title: Directive Text
+description: Render mention directives as inline chips in user messages.
+---
+
+import { DirectiveTextSample } from "@/components/docs/samples/directive-text";
+
+<DirectiveTextSample />
+
+`DirectiveText` parses the directive syntax written by [`ComposerTriggerPopover`](/docs/ui/composer-trigger-popover) (default: `:type[label]{name=id}`) and renders each segment as an inline chip. Use it as the `Text` component in user messages so the raw directive syntax never shows up.
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Add `directive-text`
+
+<InstallCommand shadcn={["directive-text"]} />
+
+This adds `/components/assistant-ui/directive-text.tsx` with `DirectiveText` and the `createDirectiveText(formatter, options?)` factory.
+
+  </Step>
+  <Step>
+
+### Use in user messages
+
+Pass `DirectiveText` as the `Text` component in `MessagePrimitive.Parts`:
+
+```tsx title="components/assistant-ui/thread.tsx"
+import { DirectiveText } from "@/components/assistant-ui/directive-text";
+
+const UserMessage = () => (
+  <MessagePrimitive.Root>
+    <MessagePrimitive.Parts components={{ Text: DirectiveText }} />
+  </MessagePrimitive.Root>
+);
+```
+
+Keep your markdown renderer (e.g. `MarkdownText`) for assistant messages — assistants rarely emit directive syntax.
+
+  </Step>
+</Steps>
+
+## Icons per Directive Type
+
+`DirectiveText` ships icon-free by default — every parsed segment renders as a plain label chip regardless of its `type`. To add icons, use the `createDirectiveText` factory and pass an `iconMap` that routes each `type` string to an icon component, plus an optional `fallbackIcon` for unmapped types:
+
+```tsx
+import { createDirectiveText } from "@/components/assistant-ui/directive-text";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+import { FileTextIcon, SparklesIcon, UserIcon, WrenchIcon } from "lucide-react";
+
+const DirectiveTextWithIcons = createDirectiveText(
+  unstable_defaultDirectiveFormatter,
+  {
+    iconMap: {
+      tool: WrenchIcon,
+      user: UserIcon,
+      file: FileTextIcon,
+    },
+    fallbackIcon: SparklesIcon,
+  },
+);
+
+<MessagePrimitive.Parts components={{ Text: DirectiveTextWithIcons }} />;
+```
+
+A matching `iconMap` / `fallbackIcon` option is accepted by [`ComposerTriggerPopover`](/docs/ui/composer-trigger-popover), where it routes `item.metadata.icon` strings instead of `type` — keeping icon configuration consistent across the composer and the rendered message.
+
+## Custom Formatter
+
+The default format is `:type[label]{name=id}`. For a different format, build a custom `Unstable_DirectiveFormatter` and wrap it with `createDirectiveText`:
+
+```tsx
+import type { Unstable_DirectiveFormatter } from "@assistant-ui/core";
+import { createDirectiveText } from "@/components/assistant-ui/directive-text";
+
+const slashFormatter: Unstable_DirectiveFormatter = {
+  serialize: (item) => `/${item.id}`,
+  parse: (text) => {
+    /* return alternating text / mention segments */
+  },
+};
+
+const SlashDirectiveText = createDirectiveText(slashFormatter);
+```
+
+Pass the **same formatter** to the composer trigger's `directive={{ formatter }}` (or `action={{ formatter }}`) so insertion and rendering stay consistent.
+
+## Customizing the Chip
+
+Because `directive-text.tsx` is copied into your project, you can also edit it directly — swap the chip styling, read `data-directive-id` to link to a detail page, or replace the chip wrapper entirely.
+
+## API Reference
+
+### `DirectiveText`
+
+A `TextMessagePartComponent` that parses `:type[label]{name=id}` directives and renders them as inline chips. Uses the default formatter from `@assistant-ui/core` and renders chips without icons. For per-type icons, build a component with `createDirectiveText(formatter, { iconMap })`.
+
+### `createDirectiveText(formatter, options?)`
+
+Factory that returns a `TextMessagePartComponent` bound to a custom `Unstable_DirectiveFormatter`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `iconMap` | `Record<string, ComponentType<{ className?: string }>>` | Maps a directive segment's `type` to an icon rendered inside the chip |
+| `fallbackIcon` | `ComponentType<{ className?: string }>` | Icon used when no `iconMap` entry matches. When neither option resolves, the chip renders without an icon. |
+
+## Related
+
+- [Composer Trigger Popover](/docs/ui/composer-trigger-popover) — the picker that inserts directives
+- [Mentions guide](/docs/guides/mentions) — directive format, backend parsing

package/.docs/raw/docs/ui/reasoning.mdx

@@ -23,22 +23,26 @@ This adds a `/components/assistant-ui/reasoning.tsx` file to your project.
 
 ### Use in your application
 
-Pass the `Reasoning` and `ReasoningGroup` components to the `MessagePrimitive.Parts` component:
+Pass the `Reasoning` and `ReasoningGroup` components to `MessagePrimitive.Parts` via the `components` prop. Using them together is the recommended default — `ReasoningGroup` wraps consecutive reasoning parts in a collapsible container for a smooth out-of-the-box UI.
 
-```tsx title="/app/components/assistant-ui/thread.tsx" {2,10-11}
+```tsx title="/app/components/assistant-ui/thread.tsx"
 import { MessagePrimitive } from "@assistant-ui/react";
-import { Reasoning } from "@/components/assistant-ui/reasoning";
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
+import { Reasoning, ReasoningGroup } from "@/components/assistant-ui/reasoning"; // [!code ++]
 
 const AssistantMessage: FC = () => {
   return (
     <MessagePrimitive.Root className="...">
       <div className="...">
-        <MessagePrimitive.Parts>
-          {({ part }) => {
-            if (part.type === "reasoning") return <Reasoning {...part} />;
-            return null;
+        <MessagePrimitive.Parts
+          components={{
+            Text: MarkdownText,
+            Reasoning, // [!code ++]
+            ReasoningGroup, // [!code ++]
+            tools: { Fallback: ToolFallback },
           }}
-        </MessagePrimitive.Parts>
+        />
       </div>
       <AssistantActionBar />
       <BranchPicker className="..." />
@@ -57,7 +61,7 @@ The component consists of two parts:
 1. `Reasoning`: Renders individual reasoning message part content (with markdown support)
 2. `ReasoningGroup`: Wraps consecutive reasoning parts in a collapsible container
 
-Consecutive reasoning parts are automatically grouped together by the `ReasoningGroup` component.
+Consecutive reasoning parts are automatically grouped together by `ReasoningGroup`. We recommend using both together as the default — you can drop `ReasoningGroup` or build your own layout with the composable API below if you need more flexibility.
 
 > When using the composable API, `Reasoning.Text` is a plain container. Add `<MarkdownText />` for markdown rendering.
 

package/dist/utils/logger.js

@@ -1,7 +1,7 @@
 import { IS_PREPARE_MODE } from "../constants.js";
 export const logger = {
     debug: (message, ...args) => {
-        if (process.env["DEBUG"]) {
+        if (process.env.DEBUG) {
             console.debug(`[DEBUG] ${message}`, ...args);
         }
     },

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -39,8 +39,8 @@
   "devDependencies": {
     "@types/node": "^25.6.0",
     "tsx": "^4.21.0",
-    "vitest": "^4.1.4",
-    "@assistant-ui/x-buildutils": "0.0.5"
+    "vitest": "^4.1.5",
+    "@assistant-ui/x-buildutils": "0.0.6"
   },
   "publishConfig": {
     "access": "public",

package/src/utils/logger.ts

@@ -2,7 +2,7 @@ import { IS_PREPARE_MODE } from "../constants.js";
 
 export const logger = {
   debug: (message: string, ...args: any[]) => {
-    if (process.env["DEBUG"]) {
+    if (process.env.DEBUG) {
       console.debug(`[DEBUG] ${message}`, ...args);
     }
   },

package/.docs/raw/docs/ui/mention.mdx

@@ -1,168 +0,0 @@
----
-title: Mention
-description: Let users @-mention tools in the composer with a keyboard-navigable popover picker and inline chips.
----
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `composer-mention`
-
-<InstallCommand shadcn={["composer-mention"]} />
-
-This adds a `/components/assistant-ui/composer-mention.tsx` file with `ComposerMentionPopover`, `ComposerMentionRoot`, and `DirectiveText`.
-
-  </Step>
-  <Step>
-
-### Wrap the Composer
-
-Wrap your composer with `ComposerMentionPopover.Root` and add `<ComposerMentionPopover />` inside:
-
-```tsx title="components/assistant-ui/thread.tsx" {1,7,10}
-import { ComposerMentionPopover } from "@/components/assistant-ui/composer-mention";
-
-const Composer = () => {
-  return (
-    <ComposerMentionPopover.Root>
-      <ComposerPrimitive.Root>
-        <ComposerPrimitive.Input placeholder="Type @ to mention a tool..." />
-        <ComposerPrimitive.Send />
-        <ComposerMentionPopover />
-      </ComposerPrimitive.Root>
-    </ComposerMentionPopover.Root>
-  );
-};
-```
-
-The popover automatically shows registered tools when the user types `@`.
-
-  </Step>
-  <Step>
-
-### Render Mentions in User Messages
-
-Use `DirectiveText` as the `Text` component for **user messages** so mention directives render as inline chips instead of raw `:tool[label]` syntax:
-
-```tsx title="components/assistant-ui/thread.tsx" {1,8}
-import { DirectiveText } from "@/components/assistant-ui/composer-mention";
-
-const UserMessage = () => {
-  return (
-    <MessagePrimitive.Root>
-      <MessagePrimitive.Parts
-        components={{
-          Text: DirectiveText,
-        }}
-      />
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-<Callout>
-  `DirectiveText` renders plain text with mention chips. For assistant messages
-  that contain markdown, keep using your markdown renderer (e.g. `MarkdownText`).
-</Callout>
-
-  </Step>
-</Steps>
-
-## With Lexical Rich Editor
-
-For inline mention chips in the composer (not just the popover), use `LexicalComposerInput` from `@assistant-ui/react-lexical`:
-
-```bash
-npm install @assistant-ui/react-lexical lexical @lexical/react
-```
-
-Replace `ComposerPrimitive.Input` with `LexicalComposerInput`:
-
-```tsx title="components/assistant-ui/thread.tsx" {1,8}
-import { LexicalComposerInput } from "@assistant-ui/react-lexical";
-
-const Composer = () => {
-  return (
-    <ComposerMentionPopover.Root>
-      <ComposerPrimitive.Root>
-        <LexicalComposerInput placeholder="Type @ to mention a tool..." />
-        <ComposerPrimitive.Send />
-        <ComposerMentionPopover />
-      </ComposerPrimitive.Root>
-    </ComposerMentionPopover.Root>
-  );
-};
-```
-
-`LexicalComposerInput` auto-wires to `MentionContext` — no extra props needed. Selected mentions appear as inline chips that are treated as atomic units (select, delete, undo as a whole).
-
-## Custom Formatter
-
-The default directive format is `:type[label]{name=id}`. To use a custom format, pass a `formatter` to both the mention root and the message renderer:
-
-```tsx
-import { ComposerMentionPopover } from "@/components/assistant-ui/composer-mention";
-import { createDirectiveText } from "@/components/assistant-ui/composer-mention";
-
-const myFormatter = {
-  serialize: (item) => `@${item.id}`,
-  parse: (text) => [{ kind: "text", text }], // implement your parsing
-};
-
-// In composer (textarea path):
-<ComposerMentionPopover.Root formatter={myFormatter}>
-  ...
-</ComposerMentionPopover.Root>
-
-// In composer (Lexical path — also pass formatter):
-<ComposerMentionPopover.Root formatter={myFormatter}>
-  <ComposerPrimitive.Root>
-    <LexicalComposerInput formatter={myFormatter} />
-    ...
-  </ComposerPrimitive.Root>
-</ComposerMentionPopover.Root>
-
-// In user messages:
-const MyDirectiveText = createDirectiveText(myFormatter);
-<MessagePrimitive.Parts components={{ Text: MyDirectiveText }} />
-```
-
-## Keyboard Navigation
-
-The mention popover supports full keyboard navigation out of the box:
-
-| 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) |
-
-## Components
-
-### `ComposerMentionPopover.Root`
-
-Wraps the composer with mention context and a tool mention adapter. Provides the `@`-trigger detection, keyboard navigation, and popover state.
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `adapter` | `Unstable_MentionAdapter` | Tool adapter | Custom mention adapter |
-| `trigger` | `string` | `"@"` | Character(s) that open the popover |
-| `formatter` | `Unstable_DirectiveFormatter` | Default | Custom directive serializer/parser |
-| `formatLabel` | `(name: string) => string` | Title case | Format tool names for display |
-| `categoryLabel` | `string` | `"Tools"` | Label for the tools category |
-
-### `ComposerMentionPopover`
-
-Pre-built popover containing categories and items lists. Only renders when the `@` trigger is active.
-
-### `DirectiveText`
-
-A `TextMessagePartComponent` that parses `:type[label]{name=id}` directives and renders them as styled inline chips.
-
-### `createDirectiveText(formatter)`
-
-Factory function that creates a `TextMessagePartComponent` using a custom `Unstable_DirectiveFormatter`.