@runtypelabs/persona 4.7.0 → 4.9.0

package/src/utils/context-mention-orchestrator.ts

@@ -0,0 +1,348 @@
+/**
+ * Core-bundle orchestrator for context mentions.
+ *
+ * Tiny by design: it renders the affordance button + chip row immediately (so
+ * the feature is discoverable before any heavy code loads), then lazy-loads and
+ * mounts the mention runtime on first `@`/click via `context-mentions-loader`.
+ * Everything heavy (controller, manager, menu, chip) lives in the lazy chunk and
+ * is reached only through the dynamic import — never statically. Sites that
+ * leave `contextMentions` off still pay a small eager cost (this orchestrator +
+ * the affordance button + the exported source helpers, ~3 kB gz — the same on
+ * ESM and the CDN); the ~15 kB runtime stays out of the core bundle until first
+ * use. See `docs/context-mentions-plan.md` (Bundle strategy).
+ */
+
+import { createNode } from "./dom";
+import { parseAnyTrigger, isMenuOpeningInput } from "./mention-trigger";
+import { normalizeMentionChannels, type NormalizedMentionChannel } from "./mention-channels";
+import { createMentionButton } from "../components/context-mention-button";
+import { loadContextMentions } from "../context-mentions-loader";
+import { loadContextMentionsInline } from "../context-mentions-inline-loader";
+import { createMentionTokenElement } from "./mention-token";
+import type { ComposerInputCapability } from "./composer-input";
+import type {
+  ContextMentionEngine,
+  InlineCommandResult,
+} from "../context-mentions-entry";
+import type { MentionSubmitBundle } from "./context-mention-manager";
+import type {
+  AgentWidgetConfig,
+  AgentWidgetContextMentionRef,
+  AgentWidgetMessage,
+} from "../types";
+
+export interface ContextMentionOrchestrator {
+  /**
+   * Affordance button wrappers to place in the composer — one per channel that
+   * opts into `showButton` (empty when all channels hide their button). The `@`
+   * channel defaults to shown; extra `/`-style channels default to hidden.
+   */
+  affordanceButtons: HTMLElement[];
+  /** Chip row to place above the textarea. */
+  contextRow: HTMLElement;
+  /** Call on composer `input`; pass the event's `inputType` for paste gating. */
+  handleInput: (inputType?: string) => void;
+  /** Call FIRST in the composer keydown handler; returns true when consumed. */
+  handleKeydown: (event: KeyboardEvent) => boolean;
+  isMenuOpen: () => boolean;
+  hasMentions: () => boolean;
+  collectForSubmit: () =>
+    | { refs: AgentWidgetContextMentionRef[]; finalize: () => Promise<MentionSubmitBundle> }
+    | null;
+  /**
+   * Dispatch a leading inline slash command in the composer `text` at submit
+   * (Slack-style). Loads the runtime if a command-channel trigger leads the text
+   * and it isn't loaded yet; returns null when there's no inline command.
+   */
+  takeInlineCommand: (text: string) => Promise<InlineCommandResult | null>;
+  clear: () => void;
+  /** Warm the chunk (e.g. on composer focus) so the first `@` is instant. */
+  prefetch: () => void;
+  /**
+   * Register a callback fired when the composer element is swapped for the inline
+   * contenteditable surface (`display: "inline"`), so the host can move its
+   * composer listeners onto the new element. Fires immediately if the swap has
+   * already happened; never fires in chip mode.
+   */
+  onComposerSwap: (
+    cb: (next: HTMLElement, prev: HTMLElement) => void
+  ) => void;
+  destroy: () => void;
+}
+
+export function createContextMentionOrchestrator(opts: {
+  config: AgentWidgetConfig;
+  textarea: HTMLTextAreaElement;
+  /** Popover anchor — the composer form/pill. */
+  anchor: HTMLElement;
+  getMessages: () => AgentWidgetMessage[];
+  /**
+   * Widget container that will host the mention live regions. The regions are
+   * created inside the lazy engine chunk on mount — never here — so the
+   * live-region helper stays out of the core bundle.
+   */
+  liveRegionHost: HTMLElement | ShadowRoot;
+  popoverContainer?: HTMLElement | ShadowRoot;
+}): ContextMentionOrchestrator | null {
+  const mentionConfig = opts.config.contextMentions;
+  if (!mentionConfig?.enabled) return null;
+
+  // Normalize the primary `@` channel + any extra `triggers` channels, then drop
+  // channels with no sources. A config may ship ONLY extra channels (a `/`-only
+  // widget), leaving the default `@` channel empty — that channel must not paint
+  // a button or match its trigger.
+  const channels: NormalizedMentionChannel[] = normalizeMentionChannels(
+    mentionConfig
+  ).filter((c) => c.sources.length > 0);
+  if (channels.length === 0) {
+    if (typeof console !== "undefined") {
+      console.warn(
+        "[Persona] contextMentions.enabled is true but no sources were provided; mentions are disabled."
+      );
+    }
+    return null;
+  }
+
+  // Command channels expose `matchCommand` on their sources. A cheap eager check
+  // so a plain-text send never loads the runtime just to look for a command.
+  const commandChannels = channels.filter((c) =>
+    c.sources.some((s) => typeof s.matchCommand === "function")
+  );
+  const looksLikeCommand = (text: string): boolean =>
+    commandChannels.some((c) => {
+      if (!c.trigger) return false;
+      // Match the live trigger parser: a line-start command may lead ANY line,
+      // input-start only the first, anywhere the whole text (unchanged).
+      if (c.position === "line-start") {
+        return text.split("\n").some((line) => line.startsWith(c.trigger));
+      }
+      const line = c.position === "anywhere" ? text : text.split("\n")[0];
+      return line.startsWith(c.trigger);
+    });
+
+  // Analytics: `persona:mention:*` DOM events on window (opened / searched /
+  // selected / rejected / resolve-error). Best-effort, guarded for SSR.
+  const emit = (event: string, detail: unknown) => {
+    if (typeof window === "undefined") return;
+    try {
+      window.dispatchEvent(
+        new CustomEvent(`persona:mention:${event}`, { detail })
+      );
+    } catch {
+      /* CustomEvent unavailable — ignore */
+    }
+  };
+
+  const contextRow = createNode("div", {
+    className: "persona-mention-context-row",
+    attrs: { "data-persona-mention-context-row": "" },
+  });
+
+  let engine: ContextMentionEngine | null = null;
+  let mountPromise: Promise<ContextMentionEngine | null> | null = null;
+
+  // Inline display (`display: "inline"`): the composer is upgraded from the live
+  // textarea to a contenteditable surface on mount (via the lazy inline chunk).
+  // `composerEl` tracks whichever element is current so the eager pre-engine
+  // handlers read the right one; `inlineInput` is the contenteditable capability
+  // handed to the controller when the menu engine mounts.
+  let composerEl: HTMLElement = opts.textarea;
+  let inlineInput: ComposerInputCapability | null = null;
+  let inlineDestroy: (() => void) | null = null;
+  let swapListener:
+    | ((next: HTMLElement, prev: HTMLElement) => void)
+    | null = null;
+  let swapped: { next: HTMLElement; prev: HTMLElement } | null = null;
+
+  const ensureEngine = (): Promise<ContextMentionEngine | null> => {
+    if (engine) return Promise.resolve(engine);
+    if (mountPromise) return mountPromise;
+    const attempt = loadContextMentions()
+      .then((mod) => {
+        engine = mod.mountContextMentions({
+          mentionConfig,
+          textarea: opts.textarea,
+          // Inline mode hands the pre-built contenteditable capability; chip mode
+          // leaves this undefined and the entry builds a textarea adapter.
+          composerInput: inlineInput ?? undefined,
+          anchor: opts.anchor,
+          contextRow,
+          getMessages: opts.getMessages,
+          getConfig: () => opts.config,
+          liveRegionHost: opts.liveRegionHost,
+          popoverContainer: opts.popoverContainer,
+          onPickerOpenChange,
+          emit,
+        });
+        return engine;
+      })
+      .catch((err) => {
+        if (typeof console !== "undefined") {
+          console.warn("[Persona] Failed to load context mentions runtime", err);
+        }
+        // A transient chunk-load failure must not disable mentions for the whole
+        // session: clear the cached promise so the next trigger retries (the
+        // chunk loader resets its own loadPromise on rejection). Concurrent
+        // callers awaiting `attempt` still each resolve to null cleanly.
+        if (mountPromise === attempt) mountPromise = null;
+        return null;
+      });
+    mountPromise = attempt;
+    return attempt;
+  };
+
+  // Load the inline chunk and swap the textarea for the contenteditable surface.
+  // The textarea stays live during the fetch; anything typed before the swap is
+  // plain text (tokens require the menu chunk), so migration is lossless. A failed
+  // fetch simply leaves the textarea in place — inline degrades to chip behavior.
+  const setupInlineComposer = (): void => {
+    loadContextMentionsInline()
+      .then((mod) => {
+        const handle = mod.mountInlineComposer({
+          textarea: opts.textarea,
+          // Built in core (owns the icon renderer + any host token override), so
+          // the inline chunk never bundles the icon set.
+          renderToken: (ref) =>
+            createMentionTokenElement(ref, {
+              render: mentionConfig.renderMentionToken,
+            }),
+          onMentionRemoved: (id) => engine?.untrackMention(id),
+        });
+        inlineInput = handle.input;
+        inlineDestroy = handle.destroy;
+        const prev = composerEl;
+        prev.replaceWith(handle.element);
+        composerEl = handle.element;
+        swapped = { next: handle.element, prev };
+        swapListener?.(handle.element, prev);
+        // If the menu engine already mounted (user opened the menu before the
+        // inline chunk resolved), it is bound to a textarea adapter around the
+        // now-detached textarea — a dead menu for the session. Rebind it to the
+        // live contenteditable: only the menu layer re-mounts, so a mention the
+        // user COMMITTED pre-swap (chip + in-flight resolve) survives and still
+        // finalizes at submit — it stays a valid chip, since inline tokens can't
+        // be retro-inserted into text already typed. Rebind closes any open menu,
+        // which is acceptable; a dead menu (or a discarded mention) is not. When
+        // the mount is still in flight it may capture the pre-swap textarea
+        // adapter, so rebind once it lands (no-op if it picked up `inlineInput`).
+        if (engine) {
+          engine.rebindComposer(handle.input);
+        } else if (mountPromise) {
+          void mountPromise.then((e) => e?.rebindComposer(handle.input));
+        }
+      })
+      .catch((err) => {
+        if (typeof console !== "undefined") {
+          console.warn("[Persona] Failed to load inline mention composer", err);
+        }
+      });
+  };
+  if (mentionConfig.display === "inline") setupInlineComposer();
+
+  // One affordance button per channel that opts into `showButton`. Each opens
+  // ITS channel's picker (no char inserted) via the channel's trigger.
+  const buttonPartsList: ReturnType<typeof createMentionButton>[] = [];
+  // Address a button by its channel trigger so `onPickerOpenChange` can flip the
+  // right button's aria-expanded/aria-controls when the picker opens/closes.
+  const buttonByTrigger = new Map<string, HTMLButtonElement>();
+  for (const channel of channels) {
+    if (!channel.showButton) continue;
+    const parts = createMentionButton({
+      config: {
+        ...mentionConfig,
+        buttonIconName: channel.buttonIconName,
+        buttonTooltipText: channel.buttonTooltipText,
+      },
+      buttonSize: opts.config.sendButton?.size,
+      onOpen: () => {
+        void ensureEngine().then((e) => e?.openMenu(channel.trigger));
+      },
+    });
+    buttonPartsList.push(parts);
+    buttonByTrigger.set(channel.trigger, parts.button);
+  }
+
+  // Reflect the picker's open state on the affordance button that opened it: set
+  // aria-controls to the menu it now owns while open, and drop it on close (a
+  // dangling aria-controls to a torn-down listbox is invalid).
+  const onPickerOpenChange = (
+    open: boolean,
+    trigger: string,
+    listboxId: string
+  ): void => {
+    const button = buttonByTrigger.get(trigger);
+    if (!button) return;
+    button.setAttribute("aria-expanded", open ? "true" : "false");
+    if (open) button.setAttribute("aria-controls", listboxId);
+    else button.removeAttribute("aria-controls");
+  };
+
+  return {
+    affordanceButtons: buttonPartsList.map((p) => p.wrapper),
+    contextRow,
+
+    handleInput: (inputType) => {
+      if (engine) {
+        engine.handleInput();
+        return;
+      }
+      if (!isMenuOpeningInput(inputType)) return;
+      // `composerEl` is the textarea (chip) or the swapped contenteditable
+      // (inline); both expose `.value`/`.selectionStart` (the inline element via
+      // textarea-compatible shims), so the eager trigger check is uniform.
+      const el = composerEl as HTMLTextAreaElement;
+      const caret = el.selectionStart ?? 0;
+      if (parseAnyTrigger(el.value, caret, channels)) {
+        void ensureEngine().then((e) => e?.handleInput());
+      }
+    },
+
+    handleKeydown: (event) => {
+      if (engine?.isMenuOpen()) return engine.handleKeydown(event);
+      // Backspace-removes-last-chip is a chip-mode affordance; inline tokens are
+      // deleted in the contenteditable itself (which untracks via the adapter).
+      // Gate on the RUNTIME mode (`swapped` = the contenteditable actually mounted),
+      // not the config: when the inline chunk fails to load the widget degrades to
+      // chips while config still says "inline", and this affordance must survive.
+      if (
+        event.key === "Backspace" &&
+        engine?.hasMentions() &&
+        !swapped
+      ) {
+        const ta = composerEl as HTMLTextAreaElement;
+        const atStart = ta.selectionStart === 0 && ta.selectionEnd === 0;
+        if (ta.value.length === 0 || atStart) {
+          if (engine.removeLastChip()) {
+            event.preventDefault();
+            return true;
+          }
+        }
+      }
+      return false;
+    },
+
+    isMenuOpen: () => engine?.isMenuOpen() ?? false,
+    hasMentions: () => engine?.hasMentions() ?? false,
+    collectForSubmit: () => engine?.collectForSubmit() ?? null,
+    takeInlineCommand: async (text) => {
+      if (!looksLikeCommand(text)) return null;
+      const e = engine ?? (await ensureEngine());
+      return e?.dispatchInlineCommand(text) ?? null;
+    },
+    clear: () => engine?.clear(),
+    prefetch: () => {
+      void loadContextMentions().catch(() => {});
+    },
+    onComposerSwap: (cb) => {
+      swapListener = cb;
+      // If the swap already happened before the host registered, replay it now.
+      if (swapped) cb(swapped.next, swapped.prev);
+    },
+    destroy: () => {
+      engine?.destroy();
+      inlineDestroy?.();
+      for (const parts of buttonPartsList) parts.wrapper.remove();
+      contextRow.remove();
+    },
+  };
+}

package/src/utils/icons.ts

@@ -13,6 +13,7 @@ import {
   Check,
   Clipboard,
   ClipboardCopy,
+  CodeXml,
   Copy,
   File as FileIcon,
   FileCode,
@@ -162,6 +163,7 @@ const LUCIDE_ICONS = {
   "check": Check,
   "clipboard": Clipboard,
   "clipboard-copy": ClipboardCopy,
+  "code-xml": CodeXml,
   "copy": Copy,
   "file": FileIcon,
   "file-code": FileCode,

package/src/utils/live-region.test.ts

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createLiveRegion } from "./live-region";
+
+describe("createLiveRegion", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("sets politeness/atomic/role attributes for a polite region", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const region = createLiveRegion("polite", host);
+    const el = host.querySelector<HTMLElement>("[data-persona-mention-live-region]")!;
+    expect(el.getAttribute("aria-live")).toBe("polite");
+    expect(el.getAttribute("aria-atomic")).toBe("true");
+    expect(el.getAttribute("role")).toBe("status");
+    expect(el.classList.contains("persona-sr-only")).toBe(true);
+    region.destroy();
+  });
+
+  it("uses role=alert for an assertive region", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    createLiveRegion("assertive", host);
+    const el = host.querySelector<HTMLElement>("[data-persona-mention-live-region]")!;
+    expect(el.getAttribute("aria-live")).toBe("assertive");
+    expect(el.getAttribute("role")).toBe("alert");
+  });
+
+  it("announce clears synchronously then sets the message on the next task", () => {
+    vi.useFakeTimers();
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const region = createLiveRegion("polite", host);
+    const el = host.querySelector<HTMLElement>("[data-persona-mention-live-region]")!;
+    region.announce("2 results");
+    // Cleared synchronously; the message lands only after the macrotask runs.
+    expect(el.textContent).toBe("");
+    vi.runAllTimers();
+    expect(el.textContent).toBe("2 results");
+  });
+
+  it("identical consecutive announcements each produce a fresh write", () => {
+    vi.useFakeTimers();
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const region = createLiveRegion("polite", host);
+    const el = host.querySelector<HTMLElement>("[data-persona-mention-live-region]")!;
+
+    region.announce("2 results");
+    vi.runAllTimers();
+    expect(el.textContent).toBe("2 results");
+
+    // A repeat must clear first so the a11y tree re-serializes the reset.
+    region.announce("2 results");
+    expect(el.textContent).toBe("");
+    vi.runAllTimers();
+    expect(el.textContent).toBe("2 results");
+  });
+
+  it("a rapid second announce supersedes the first (old message never lands)", () => {
+    vi.useFakeTimers();
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const region = createLiveRegion("polite", host);
+    const el = host.querySelector<HTMLElement>("[data-persona-mention-live-region]")!;
+
+    region.announce("2 results");
+    region.announce("5 results");
+    vi.runAllTimers();
+    // Only the newest message is ever written.
+    expect(el.textContent).toBe("5 results");
+  });
+
+  it("hosts in the light DOM (document.body) with inline sr-only styles when the host is shadow-rooted", () => {
+    const shell = document.createElement("div");
+    document.body.appendChild(shell);
+    const shadow = shell.attachShadow({ mode: "open" });
+    const inner = document.createElement("div");
+    shadow.appendChild(inner);
+
+    createLiveRegion("polite", inner);
+    // Not inside the shadow root…
+    expect(shadow.querySelector("[data-persona-mention-live-region]")).toBeNull();
+    // …but on document.body, with inline visually-hidden styling.
+    const el = document.body.querySelector<HTMLElement>(
+      "[data-persona-mention-live-region]"
+    )!;
+    expect(el.parentNode).toBe(document.body);
+    expect(el.style.position).toBe("absolute");
+    expect(el.style.width).toBe("1px");
+  });
+
+  it("destroy removes the node", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const region = createLiveRegion("polite", host);
+    expect(host.querySelector("[data-persona-mention-live-region]")).not.toBeNull();
+    region.destroy();
+    expect(host.querySelector("[data-persona-mention-live-region]")).toBeNull();
+  });
+});

package/src/utils/live-region.ts

@@ -0,0 +1,94 @@
+/**
+ * Reusable ARIA live-region helper for screen-reader announcements.
+ *
+ * Politeness maps to a matching role so assistive tech treats each region
+ * correctly: `"polite"` → `role="status"` (queued behind current speech),
+ * `"assertive"` → `role="alert"` (interrupts). `aria-atomic="true"` makes the
+ * whole message re-read on every update rather than just the changed text node.
+ *
+ * Shadow-DOM hosting (per the mention-a11y decision): a visually-hidden live
+ * region nested inside a shadow root is inconsistently surfaced by assistive
+ * technologies, so when the resolved host lives inside a Shadow DOM we host the
+ * region in the LIGHT DOM (`document.body`) instead and apply the sr-only styles
+ * inline (the widget's prefixed `widget.css` may not reach `document.body`).
+ * Outside a shadow root the region stays in the given host and relies on the
+ * `persona-sr-only` class.
+ *
+ * NOTE (pre-existing limitation): this helper is currently only wired for the
+ * context-mention live regions. The widget's GENERAL live region (`ui.ts`,
+ * `data-persona-live-region`) still renders inside the shadow root under
+ * `useShadowDom` and is intentionally left untouched here — narrowing the fix to
+ * the mention regions keeps the change surface small.
+ */
+
+/** Visually-hidden styling applied inline when hosting on `document.body`. */
+const SR_ONLY_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  margin: "-1px",
+  padding: "0",
+  overflow: "hidden",
+  clip: "rect(0 0 0 0)",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  border: "0",
+};
+
+export type LiveRegionPoliteness = "polite" | "assertive";
+
+export interface LiveRegion {
+  /** Re-announce `message`; clears first so identical repeats still speak. */
+  announce: (message: string) => void;
+  /** Remove the region node from the DOM. */
+  destroy: () => void;
+}
+
+/**
+ * Create an ARIA live region hosted per the Shadow-DOM decision above.
+ * `host` is the element (or shadow root) the widget renders into; the helper
+ * inspects its root node to decide between light-DOM and in-host placement.
+ */
+export function createLiveRegion(
+  politeness: LiveRegionPoliteness,
+  host: HTMLElement | ShadowRoot
+): LiveRegion {
+  const el = document.createElement("div");
+  el.className = "persona-sr-only";
+  el.setAttribute("aria-live", politeness);
+  el.setAttribute("aria-atomic", "true");
+  el.setAttribute("role", politeness === "assertive" ? "alert" : "status");
+  el.setAttribute("data-persona-mention-live-region", "");
+
+  const root = host.getRootNode();
+  const inShadow =
+    typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot;
+  if (inShadow) {
+    // Host in the light DOM with inline sr-only styles (widget.css may not reach
+    // document.body).
+    Object.assign(el.style, SR_ONLY_STYLE);
+    document.body.appendChild(el);
+  } else {
+    host.appendChild(el);
+  }
+
+  // Clear and set must land in separate tasks: browsers serialize the a11y tree
+  // once per task, so a synchronous clear+set hides the reset and identical
+  // repeats never re-announce.
+  let pendingSet: ReturnType<typeof setTimeout> | undefined;
+
+  return {
+    announce: (message: string) => {
+      if (pendingSet !== undefined) clearTimeout(pendingSet);
+      el.textContent = "";
+      pendingSet = setTimeout(() => {
+        pendingSet = undefined;
+        el.textContent = message;
+      }, 0);
+    },
+    destroy: () => {
+      if (pendingSet !== undefined) clearTimeout(pendingSet);
+      el.remove();
+    },
+  };
+}

package/src/utils/mention-channels.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared normalization of the public `contextMentions` config into trigger
+ * channels. Both the core orchestrator (which paints affordance buttons) and the
+ * lazy controller (which drives the menu/search) derive their channel list from
+ * here, so the field-mapping and per-channel defaults live in exactly one place.
+ *
+ * Type-only imports of the public config types keep this module runtime-pure
+ * (no DOM), matching `mention-trigger.ts`.
+ */
+
+import type {
+  AgentWidgetContextMentionConfig,
+  AgentWidgetContextMentionSource,
+} from "../types";
+import type { MentionTriggerPosition } from "./mention-trigger";
+
+/**
+ * A trigger channel normalized from config: the primary `@` channel (from the
+ * legacy top-level fields) followed by any extra `triggers` channels. This is a
+ * superset of what each consumer needs — the orchestrator reads the button
+ * fields, the controller reads sources/search — and satisfies `MentionTriggerSpec`
+ * so it can be passed straight to `parseAnyTrigger`. Channels are NOT filtered
+ * here; each caller drops empty ones per its own policy.
+ */
+export type NormalizedMentionChannel = {
+  trigger: string;
+  position: MentionTriggerPosition;
+  allowSpaces: boolean;
+  sources: AgentWidgetContextMentionSource[];
+  searchPlaceholder?: string;
+  /** Primary defaults to shown; extra channels default to hidden (typed-only). */
+  showButton: boolean;
+  buttonIconName?: string;
+  buttonTooltipText?: string;
+};
+
+export function normalizeMentionChannels(
+  cfg: AgentWidgetContextMentionConfig
+): NormalizedMentionChannel[] {
+  const primary: NormalizedMentionChannel = {
+    trigger: cfg.trigger ?? "@",
+    position: cfg.triggerPosition ?? "anywhere",
+    allowSpaces: false,
+    sources: Array.isArray(cfg.sources) ? cfg.sources : [],
+    searchPlaceholder: cfg.searchPlaceholder,
+    showButton: cfg.showButton !== false,
+    buttonIconName: cfg.buttonIconName,
+    buttonTooltipText: cfg.buttonTooltipText,
+  };
+  const extra: NormalizedMentionChannel[] = (cfg.triggers ?? []).map((ch) => ({
+    trigger: ch.trigger,
+    position: ch.triggerPosition ?? "anywhere",
+    allowSpaces: ch.allowSpaces ?? false,
+    sources: Array.isArray(ch.sources) ? ch.sources : [],
+    searchPlaceholder: ch.searchPlaceholder,
+    // Extra channels (e.g. `/`) default to NO button to keep the composer's
+    // action cluster uncluttered — typed-trigger only unless opted in.
+    showButton: ch.showButton === true,
+    buttonIconName: ch.buttonIconName,
+    buttonTooltipText: ch.buttonTooltipText,
+  }));
+  return [primary, ...extra];
+}