@runtypelabs/persona 4.8.0 → 4.9.0

package/src/components/message-bubble.ts

@@ -1,4 +1,4 @@
-import { createElement } from "../utils/dom";
+import { createElement, createNode } from "../utils/dom";
 import {
   AgentWidgetMessage,
   AgentWidgetMessageLayoutConfig,
@@ -11,9 +11,14 @@ import {
   AudioContentPart,
   VideoContentPart,
   FileContentPart,
+  AgentWidgetContextMentionRef,
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionTokenRenderContext,
   StopReasonKind
 } from "../types";
+import { createMentionTokenElement } from "../utils/mention-token";
 import { createIconButton } from "../utils/buttons";
+import { renderLucideIcon } from "../utils/icons";
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "../utils/content";
 import {
   applyStreamBuffer,
@@ -186,6 +191,126 @@ const getMessageFileParts = (message: AgentWidgetMessage): FileContentPart[] =>
   );
 };
 
+/**
+ * Read-only context-mention pills for a sent user bubble (from
+ * `message.contextMentions`). Same compact pill look as the composer chips, but
+ * no spinner / remove control. Returns null when the message carries no mentions.
+ */
+const createMessageMentionChips = (
+  mentions: AgentWidgetContextMentionRef[] | undefined
+): HTMLElement | null => {
+  if (!mentions || mentions.length === 0) return null;
+  const row = createNode("div", {
+    className: "persona-mention-context-row persona-message-mentions",
+    attrs: { "data-message-mentions": "" },
+  });
+  row.style.display = "flex";
+  for (const ref of mentions) {
+    const chip = createNode("div", {
+      className: "persona-mention-chip persona-mention-chip-readonly",
+      attrs: { "data-status": "ready", title: ref.label },
+    });
+    const iconHost = createElement("span", "persona-mention-chip-icon");
+    const icon = renderLucideIcon(ref.iconName ?? "at-sign", 13, "currentColor", 2);
+    if (icon) iconHost.appendChild(icon);
+    chip.appendChild(iconHost);
+    chip.appendChild(
+      createNode("span", { className: "persona-mention-chip-label", text: ref.label })
+    );
+    row.appendChild(chip);
+  }
+  return row;
+};
+
+/**
+ * Render a sent user bubble's prose with atomic mention tokens in place (inline
+ * display mode, from `message.contentSegments`). Text runs become text nodes;
+ * mention segments become read-only pill tokens (shared with the composer, so a
+ * host `renderMentionToken` + per-item `color` apply here too). Display/transcript
+ * concern only — the model saw the resolved bodies via `llmContent`. Returns a
+ * document fragment for `replaceChildren`.
+ */
+export const createMessageInlineMentions = (
+  segments: AgentWidgetContentSegment[],
+  render?: (
+    ctx: AgentWidgetContextMentionTokenRenderContext
+  ) => HTMLElement
+): DocumentFragment => {
+  const frag = document.createDocumentFragment();
+  for (const seg of segments) {
+    if (seg.kind === "text") {
+      frag.appendChild(document.createTextNode(seg.text));
+      continue;
+    }
+    frag.appendChild(
+      createMentionTokenElement(seg.ref, { readonly: true, render })
+    );
+  }
+  return frag;
+};
+
+/* PUA sentinels survive escapeHtml, markdown, and DOMPurify as plain text. */
+const MENTION_PH_OPEN = "\uE000";
+const MENTION_PH_CLOSE = "\uE001";
+
+/**
+ * Render segmented prose through the full message transform (actions, markdown,
+ * postprocess, sanitize): mention slots ride the pipeline as placeholder
+ * sentinels and are swapped for atomic token elements in the parsed output.
+ * Falls back to verbatim segment rendering when a transform drops or rewrites
+ * a slot, so a mention is never lost.
+ */
+export const renderSegmentsWithTransform = (
+  contentDiv: HTMLElement,
+  segments: AgentWidgetContentSegment[],
+  transformSource: (source: string) => string,
+  render?: (
+    ctx: AgentWidgetContextMentionTokenRenderContext
+  ) => HTMLElement
+): void => {
+  // Nonce keeps user-typed sentinel lookalikes from matching a real slot.
+  const nonce = Math.random().toString(36).slice(2, 8);
+  const placeholder = (i: number) =>
+    `${MENTION_PH_OPEN}${nonce}:${i}${MENTION_PH_CLOSE}`;
+  const source = segments
+    .map((seg, i) => (seg.kind === "text" ? seg.text : placeholder(i)))
+    .join("");
+  const html = transformSource(source);
+  // String-level check runs before the parse: a slot that was dropped,
+  // entity-encoded, or split by an inserted tag fails `includes`.
+  const survived = segments.every(
+    (seg, i) => seg.kind === "text" || html.includes(placeholder(i))
+  );
+  if (!survived) {
+    contentDiv.replaceChildren(createMessageInlineMentions(segments, render));
+    return;
+  }
+  contentDiv.innerHTML = html;
+  const pattern = new RegExp(
+    `${MENTION_PH_OPEN}${nonce}:(\\d+)${MENTION_PH_CLOSE}`
+  );
+  const walker = document.createTreeWalker(contentDiv, NodeFilter.SHOW_TEXT);
+  const textNodes: Text[] = [];
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    textNodes.push(n as Text);
+  }
+  for (const node of textNodes) {
+    let current = node;
+    for (let match = pattern.exec(current.data); match; match = pattern.exec(current.data)) {
+      const seg = segments[Number(match[1])];
+      const after = current.splitText(match.index);
+      after.data = after.data.slice(match[0].length);
+      if (seg?.kind === "mention") {
+        after.parentNode?.insertBefore(
+          createMentionTokenElement(seg.ref, { readonly: true, render }),
+          after
+        );
+      }
+      current = after;
+    }
+  }
+};
+
 const createMessageImagePreviews = (
   imageParts: ImageContentPart[],
   hasVisibleText: boolean,
@@ -820,33 +945,57 @@ export const createStandardBubble = (
       )
     : (message.content ?? "");
 
-  const transformedContent = transform({
-    text: bufferedContent,
-    message,
-    streaming: Boolean(message.streaming),
-    raw: message.rawContent
-  });
-
-  let animatedContent = transformedContent;
-  if (streamAnimationActive && streamPlugin?.wrap === "char") {
-    animatedContent = wrapStreamAnimation(transformedContent, "char", message.id, {
-      skipTags: streamPlugin.skipTags,
-    });
-  } else if (streamAnimationActive && streamPlugin?.wrap === "word") {
-    animatedContent = wrapStreamAnimation(transformedContent, "word", message.id, {
-      skipTags: streamPlugin.skipTags,
+  // Feeds the two text branches below; the inline-mention branch calls the
+  // transform itself with a placeholder-bearing source built from
+  // `contentSegments` instead of `bufferedContent`. Kept lazy so that branch
+  // doesn't pay for output it never reads. `bufferedContent` stays eager —
+  // the streaming skeleton logic reads it.
+  const computeAnimatedContent = (): string => {
+    const transformedContent = transform({
+      text: bufferedContent,
+      message,
+      streaming: Boolean(message.streaming),
+      raw: message.rawContent
     });
-  }
+    if (streamAnimationActive && streamPlugin?.wrap === "char") {
+      return wrapStreamAnimation(transformedContent, "char", message.id, {
+        skipTags: streamPlugin.skipTags,
+      });
+    }
+    if (streamAnimationActive && streamPlugin?.wrap === "word") {
+      return wrapStreamAnimation(transformedContent, "word", message.id, {
+        skipTags: streamPlugin.skipTags,
+      });
+    }
+    return transformedContent;
+  };
 
   let textContentDiv: HTMLElement | null = null;
 
   if (shouldHideTextUntilPreviewFails) {
     textContentDiv = document.createElement("div");
-    textContentDiv.innerHTML = animatedContent;
+    textContentDiv.innerHTML = computeAnimatedContent();
     textContentDiv.style.display = "none";
     contentDiv.appendChild(textContentDiv);
+  } else if (message.contentSegments?.length) {
+    // Inline-mention user bubble: prose runs through the same transform
+    // pipeline as every other bubble (markdown/postprocess/sanitize apply);
+    // mention slots ride through as placeholders and come back as atomic
+    // tokens. The resolved context reached the model via `llmContent`.
+    renderSegmentsWithTransform(
+      contentDiv,
+      message.contentSegments,
+      (source) =>
+        transform({
+          text: source,
+          message,
+          streaming: Boolean(message.streaming),
+          raw: message.rawContent,
+        }),
+      options?.widgetConfig?.contextMentions?.renderMentionToken
+    );
   } else {
-    contentDiv.innerHTML = animatedContent;
+    contentDiv.innerHTML = computeAnimatedContent();
   }
 
   if (
@@ -931,6 +1080,15 @@ export const createStandardBubble = (
     }
   }
 
+  // Context mention pills (read-only) for the sent user bubble. Skipped in inline
+  // mode — the tokens render within the prose (above) instead of a separate row.
+  const mentionChips = message.contentSegments?.length
+    ? null
+    : createMessageMentionChips(message.contextMentions);
+  if (mentionChips) {
+    bubble.appendChild(mentionChips);
+  }
+
   bubble.appendChild(contentDiv);
 
   // Add timestamp below if configured

package/src/components/panel.ts

@@ -282,10 +282,8 @@ const buildComposerBarPanel = (
       className: "persona-rounded-2xl persona-p-6",
       attrs: { "data-persona-intro-card": "" },
       style: {
-        background:
-          "var(--persona-intro-card-bg, var(--persona-surface, #ffffff))",
-        boxShadow:
-          "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))",
+        background: "var(--persona-intro-card-bg, transparent)",
+        boxShadow: "var(--persona-intro-card-shadow, none)",
       },
     },
     introTitle,
@@ -416,20 +414,19 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
       "Ask anything about your account or products.",
   });
   // Background and box-shadow flow through the themable `components.introCard`
-  // tokens (--persona-intro-card-bg / --persona-intro-card-shadow), each
-  // falling back to its legacy value (`--persona-surface` / `persona-shadow-sm`)
-  // when no token is set. Docked mode keeps a flat shadow by default.
+  // tokens (--persona-intro-card-bg / --persona-intro-card-shadow); both
+  // default to flat (transparent / none). Docked mode always stays flat,
+  // even when a theme sets an introCard shadow.
   const introCard = createNode(
     "div",
     {
       className: "persona-rounded-2xl persona-p-6",
       attrs: { "data-persona-intro-card": "" },
       style: {
-        background:
-          "var(--persona-intro-card-bg, var(--persona-surface, #ffffff))",
+        background: "var(--persona-intro-card-bg, transparent)",
         boxShadow: isDockedMountMode(config)
           ? "none"
-          : "var(--persona-intro-card-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))",
+          : "var(--persona-intro-card-shadow, none)",
       },
     },
     introTitle,

package/src/context-mentions-bundle.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Bundle guard for the lazy context-mentions chunk (see
+ * `docs/context-mentions-plan.md`, Bundle strategy).
+ *
+ * The mention runtime (controller/manager/menu) must NOT land in ANY core bundle
+ * shipped to consumers — neither the CDN IIFE (`dist/index.global.js`) nor the
+ * ESM/CJS bundles (`dist/index.js` / `dist/index.cjs`). It ships as the sibling
+ * chunk `dist/context-mentions.{js,cjs}`, loaded on demand: the IIFE via a
+ * sibling URL, ESM/CJS via the external `@runtypelabs/persona/context-mentions`
+ * subpath. A stray static import would pull the runtime back in; this fails then.
+ *
+ * Skips when `dist/` hasn't been built (e.g. a test-only CI step).
+ */
+const dist = (f: string) => resolve(__dirname, "..", "dist", f);
+
+const RUNTIME_MARKERS = [
+  "persona-mention-menu", // menu component class — chunk-only
+  "persona-mention-group-header", // menu component class — chunk-only
+  // Slash-command dispatch lives in the controller (chunk-only); this literal
+  // is unique to the command path and must not leak into a core bundle.
+  "context-mention prompt resolve failed",
+];
+
+const SUBPATH = "@runtypelabs/persona/context-mentions";
+
+// Inline (contenteditable) runtime markers — unique to the inline chunk. The
+// composer contenteditable class is set only by the inline adapter/entry (in
+// widget.css it's a stylesheet rule, not a JS-bundle string), so its presence in
+// a JS bundle means the contenteditable engine leaked in.
+const INLINE_RUNTIME_MARKERS = ["persona-composer-contenteditable"];
+const INLINE_SUBPATH = "@runtypelabs/persona/context-mentions-inline";
+
+describe("context-mentions bundle split", () => {
+  const iifeBuilt =
+    existsSync(dist("index.global.js")) && existsSync(dist("context-mentions.js"));
+  const esmBuilt = existsSync(dist("index.js")) && existsSync(dist("index.cjs"));
+
+  it.runIf(iifeBuilt)("keeps the mention runtime OUT of the core IIFE bundle", () => {
+    const core = readFileSync(dist("index.global.js"), "utf8");
+    for (const marker of RUNTIME_MARKERS) {
+      expect(core.includes(marker), `IIFE bundle unexpectedly contains "${marker}"`).toBe(
+        false
+      );
+    }
+    // The loader stub (sibling-URL reference) must remain so the chunk can load.
+    expect(core).toContain("context-mentions.js");
+  });
+
+  it.runIf(esmBuilt)("keeps the mention runtime OUT of the ESM/CJS bundles", () => {
+    for (const file of ["index.js", "index.cjs"]) {
+      const core = readFileSync(dist(file), "utf8");
+      for (const marker of RUNTIME_MARKERS) {
+        expect(core.includes(marker), `${file} unexpectedly contains "${marker}"`).toBe(
+          false
+        );
+      }
+      // The runtime is reached via the external subpath, not inlined.
+      expect(core.includes(SUBPATH), `${file} must import the external subpath`).toBe(
+        true
+      );
+    }
+  });
+
+  it.runIf(iifeBuilt)("ships the mention + slash-command runtime in the sibling chunk", () => {
+    const chunk = readFileSync(dist("context-mentions.js"), "utf8");
+    expect(chunk).toContain("persona-mention-menu");
+    // Slash-command dispatch ships in the chunk, not the core.
+    expect(chunk).toContain("context-mention prompt resolve failed");
+    // The menu CSS rides with the chunk (injected on open), not eager widget.css.
+    expect(chunk).toContain(".persona-mention-option[data-active");
+    // A CJS twin exists for require()-based consumers.
+    expect(existsSync(dist("context-mentions.cjs"))).toBe(true);
+  });
+
+  // --- inline (contenteditable) chunk guards --------------------------------
+
+  const inlineBuilt = existsSync(dist("context-mentions-inline.js"));
+
+  it.runIf(iifeBuilt)(
+    "keeps the inline contenteditable engine OUT of the core IIFE bundle",
+    () => {
+      const core = readFileSync(dist("index.global.js"), "utf8");
+      for (const marker of INLINE_RUNTIME_MARKERS) {
+        expect(
+          core.includes(marker),
+          `IIFE bundle unexpectedly contains inline marker "${marker}"`
+        ).toBe(false);
+      }
+      // The inline loader stub must remain so the chunk can load on mount.
+      expect(core).toContain("context-mentions-inline.js");
+    }
+  );
+
+  it.runIf(esmBuilt)(
+    "keeps the inline contenteditable engine OUT of the ESM/CJS bundles",
+    () => {
+      for (const file of ["index.js", "index.cjs"]) {
+        const core = readFileSync(dist(file), "utf8");
+        for (const marker of INLINE_RUNTIME_MARKERS) {
+          expect(
+            core.includes(marker),
+            `${file} unexpectedly contains inline marker "${marker}"`
+          ).toBe(false);
+        }
+        // Reached via the external subpath, not inlined.
+        expect(
+          core.includes(INLINE_SUBPATH),
+          `${file} must import the external inline subpath`
+        ).toBe(true);
+      }
+    }
+  );
+
+  it.runIf(inlineBuilt)(
+    "ships the contenteditable engine in the inline chunk (with a CJS twin)",
+    () => {
+      const chunk = readFileSync(dist("context-mentions-inline.js"), "utf8");
+      expect(chunk).toContain("persona-composer-contenteditable");
+      expect(existsSync(dist("context-mentions-inline.cjs"))).toBe(true);
+    }
+  );
+
+  it.runIf(iifeBuilt)(
+    "keeps the contenteditable engine OUT of the chip chunk (capability-only reach)",
+    () => {
+      // The chip controller reaches token insertion ONLY via the capability's
+      // `insertMentionAtTrigger`, so the chip chunk must never pull the document
+      // model / contenteditable adapter. This guard is what keeps that true.
+      const chip = readFileSync(dist("context-mentions.js"), "utf8");
+      for (const marker of INLINE_RUNTIME_MARKERS) {
+        expect(
+          chip.includes(marker),
+          `chip chunk unexpectedly contains inline marker "${marker}"`
+        ).toBe(false);
+      }
+    }
+  );
+
+  it.runIf(existsSync(dist("widget.css")))(
+    "keeps menu CSS out of the eager stylesheet but keeps chip CSS",
+    () => {
+      const css = readFileSync(dist("widget.css"), "utf8");
+      expect(css).toContain(".persona-mention-chip"); // eager chip pieces stay
+      expect(css.includes(".persona-mention-menu")).toBe(false); // menu moved to chunk
+      expect(css.includes(".persona-mention-option")).toBe(false);
+    }
+  );
+
+  it.runIf(esmBuilt)("ships no lookbehind regex (Safari < 16.4 parse guard)", () => {
+    // A lookbehind literal anywhere in a core bundle is a parse-time SyntaxError
+    // on older Safari, breaking the whole widget even with mentions disabled.
+    for (const file of ["index.js", "index.cjs", "index.global.js"]) {
+      if (!existsSync(dist(file))) continue;
+      expect(readFileSync(dist(file), "utf8").includes("(?<="), `${file} has a lookbehind`).toBe(
+        false
+      );
+    }
+  });
+});

package/src/context-mentions-entry.ts

@@ -0,0 +1,185 @@
+/**
+ * Context-mentions runtime entry — the HEAVY module that assembles the menu
+ * controller + chip manager. It is NEVER statically imported on the core path:
+ * the IIFE/CDN build marks it external (`tsup.global.config.ts`) and loads the
+ * standalone `context-mentions.js` chunk from a sibling URL only when
+ * `contextMentions.enabled` and the user first interacts. The core orchestrator
+ * (`utils/context-mention-orchestrator.ts`) reaches it through
+ * `context-mentions-loader.ts`. See `docs/context-mentions-plan.md`.
+ */
+
+import { ContextMentionManager } from "./utils/context-mention-manager";
+import {
+  ContextMentionController,
+  type InlineCommandResult,
+} from "./utils/context-mention-controller";
+import {
+  createTextareaComposerInput,
+  type ComposerInputCapability,
+} from "./utils/composer-input";
+import { createLiveRegion } from "./utils/live-region";
+import type { MentionSubmitBundle } from "./utils/context-mention-manager";
+import type {
+  AgentWidgetConfig,
+  AgentWidgetContextMentionConfig,
+  AgentWidgetContextMentionRef,
+  AgentWidgetMessage,
+} from "./types";
+
+export interface ContextMentionMountContext {
+  mentionConfig: AgentWidgetContextMentionConfig;
+  textarea: HTMLTextAreaElement;
+  /**
+   * Pre-built composer input surface. Provided by the inline chunk in
+   * `display: "inline"` mode (a contenteditable adapter that replaced the
+   * textarea); omitted in chip mode, where a textarea adapter is built here.
+   */
+  composerInput?: ComposerInputCapability;
+  /** Popover anchor — the composer form/pill (menu opens upward, full width). */
+  anchor: HTMLElement;
+  /** Chip row created by the core orchestrator. */
+  contextRow: HTMLElement;
+  getMessages: () => AgentWidgetMessage[];
+  getConfig: () => AgentWidgetConfig;
+  /**
+   * Widget container that hosts the mention live regions (created here, on
+   * engine mount, so the helper stays out of the core bundle). Announcements
+   * can't fire before the engine exists, so lazy creation loses nothing.
+   */
+  liveRegionHost: HTMLElement | ShadowRoot;
+  popoverContainer?: HTMLElement | ShadowRoot;
+  /**
+   * Reflect the affordance-button picker's open state onto the button
+   * (`aria-expanded`/`aria-controls`). See the controller option of the same name.
+   */
+  onPickerOpenChange?: (open: boolean, trigger: string, listboxId: string) => void;
+  /** Emit a `persona:mention:<event>` analytics DOM event. */
+  emit?: (event: string, detail: unknown) => void;
+}
+
+export interface ContextMentionEngine {
+  /**
+   * Open the menu from an affordance button as a picker (no char inserted).
+   * Pass the channel's `trigger` to open a specific channel (e.g. `"/"`).
+   */
+  openMenu(trigger?: string): void;
+  isMenuOpen(): boolean;
+  /** Re-parse the textarea on input and open/update/close the menu. */
+  handleInput(): void;
+  /** Returns true when the key was consumed. */
+  handleKeydown(event: KeyboardEvent): boolean;
+  hasMentions(): boolean;
+  removeLastChip(): boolean;
+  /**
+   * Dispatch a leading inline slash command in the composer `text` at submit
+   * (Slack-style). Returns null when `text` isn't an inline command. See
+   * {@link InlineCommandResult}.
+   */
+  dispatchInlineCommand(text: string): Promise<InlineCommandResult | null>;
+  collectForSubmit():
+    | { refs: AgentWidgetContextMentionRef[]; finalize: () => Promise<MentionSubmitBundle> }
+    | null;
+  /**
+   * INLINE display only. Stop tracking a mention whose token the user deleted from
+   * the composer (aborts its in-flight resolve). Wired to the contenteditable
+   * adapter's removal detection by the orchestrator.
+   */
+  untrackMention(id: string): void;
+  /**
+   * Rebind the engine to a new composer input surface (the inline swap landing
+   * while the engine is already live). Only the menu layer (controller) re-mounts
+   * on the new element — the manager, with any committed chips and their
+   * in-flight resolves, survives, so a mention picked pre-swap still finalizes
+   * into the submit payload. Any open menu closes. No-op when already bound.
+   */
+  rebindComposer(input: ComposerInputCapability): void;
+  clear(): void;
+  destroy(): void;
+}
+
+export function mountContextMentions(
+  ctx: ContextMentionMountContext
+): ContextMentionEngine {
+  // Inline mode supplies a pre-built contenteditable capability; chip mode builds
+  // a textarea-backed one here. Mutable: `rebindComposer` swaps it when the inline
+  // composer replaces the textarea while the engine is already live — closures
+  // below read it at call time so they always drive the current surface.
+  let composerInput =
+    ctx.composerInput ?? createTextareaComposerInput(ctx.textarea);
+
+  // Polite region for result-count + add/remove announcements; assertive region
+  // for resolve failures. Hosted via the shared helper so they land in the light
+  // DOM when the widget renders inside a Shadow DOM (see live-region.ts).
+  const liveRegion = createLiveRegion("polite", ctx.liveRegionHost);
+  const errorRegion = createLiveRegion("assertive", ctx.liveRegionHost);
+  const announce = (message: string): void => liveRegion.announce(message);
+  const announceError = (message: string): void => errorRegion.announce(message);
+
+  const manager = new ContextMentionManager({
+    mentionConfig: ctx.mentionConfig,
+    contextRow: ctx.contextRow,
+    getMessages: ctx.getMessages,
+    getConfig: ctx.getConfig,
+    getComposerText: () => composerInput.getValue(),
+    announce,
+    announceError,
+    emit: ctx.emit,
+  });
+
+  const buildController = (): ContextMentionController =>
+    new ContextMentionController({
+      mentionConfig: ctx.mentionConfig,
+      composerInput,
+      anchor: ctx.anchor,
+      getMessages: ctx.getMessages,
+      getConfig: ctx.getConfig,
+      onSelect: (source, item, args) => manager.add(source, item, args),
+      // Inline commit: the controller inserts the token, then tracks its resolve
+      // keyed by the composer id. `reportStatus` reflects the resolve outcome onto
+      // the live token element (error styling — inline tokens carry no chip).
+      onInsertMention: (id, source, item, args) =>
+        manager.track(id, source, item, args, (status) =>
+          composerInput.setMentionStatus?.(id, status)
+        ),
+      admitMention: (source, item) => manager.admit(source, item),
+      announce,
+      popoverContainer: ctx.popoverContainer,
+      onPickerOpenChange: ctx.onPickerOpenChange,
+      emit: ctx.emit,
+    });
+
+  let controller = buildController();
+
+  return {
+    openMenu: (trigger) => controller.openFromButton(trigger),
+    isMenuOpen: () => controller.isOpen(),
+    handleInput: () => controller.onInput(),
+    handleKeydown: (event) => controller.handleKeydown(event),
+    hasMentions: () => manager.hasMentions(),
+    removeLastChip: () => manager.removeLast(),
+    dispatchInlineCommand: (text) => controller.dispatchInlineCommand(text),
+    collectForSubmit: () =>
+      manager.hasMentions() ? manager.collectForSubmit() : null,
+    untrackMention: (id) => manager.remove(id),
+    rebindComposer: (input) => {
+      if (input === composerInput) return;
+      // Re-mount ONLY the menu layer on the new surface. The manager — committed
+      // chips and their in-flight resolves — must survive: a mention picked
+      // pre-swap stays a valid chip post-swap (tokens can't be retro-inserted
+      // into text the user already typed) and still finalizes at submit.
+      controller.destroy();
+      composerInput = input;
+      controller = buildController();
+    },
+    clear: () => manager.clear(),
+    destroy: () => {
+      controller.destroy();
+      manager.clear();
+      liveRegion.destroy();
+      errorRegion.destroy();
+    },
+  };
+}
+
+export type { MentionSubmitBundle };
+export type { InlineCommandResult };