@runtypelabs/persona 4.8.0 → 4.10.0

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 };

package/src/context-mentions-inline-entry.test.ts

@@ -0,0 +1,136 @@
+// @vitest-environment jsdom
+
+import { describe, it, expect, vi } from "vitest";
+import { mountInlineComposer } from "./context-mentions-inline-entry";
+import type { AgentWidgetContextMentionRef } from "./types";
+
+const renderToken = (ref: AgentWidgetContextMentionRef): HTMLElement => {
+  const el = document.createElement("span");
+  el.textContent = `@${ref.label}`;
+  return el;
+};
+
+const makeTextarea = (): HTMLTextAreaElement => {
+  const ta = document.createElement("textarea");
+  document.body.appendChild(ta);
+  return ta;
+};
+
+const appRef: AgentWidgetContextMentionRef = {
+  sourceId: "files",
+  itemId: "app",
+  label: "App.tsx",
+};
+
+describe("mountInlineComposer", () => {
+  it("mirrors the textarea's inline styles onto the contenteditable (no visual pop)", () => {
+    const ta = makeTextarea();
+    ta.className = "persona-composer-textarea";
+    ta.style.maxHeight = "60px";
+    ta.style.overflowY = "auto";
+    ta.style.fontWeight = "500";
+    ta.setAttribute("placeholder", "Ask about a file…");
+
+    const handle = mountInlineComposer({ textarea: ta, renderToken });
+    const el = handle.element;
+
+    expect(el.style.maxHeight).toBe("60px");
+    expect(el.style.overflowY).toBe("auto");
+    expect(el.style.fontWeight).toBe("500");
+    expect(el.className).toContain("persona-composer-textarea");
+    // Placeholder + accessible name mirror across.
+    expect(el.getAttribute("data-placeholder")).toBe("Ask about a file…");
+    expect(el.getAttribute("aria-label")).toBe("Ask about a file…");
+    handle.destroy();
+  });
+
+  it("maps the shimmed `placeholder` property onto data-placeholder", () => {
+    const ta = makeTextarea();
+    const handle = mountInlineComposer({ textarea: ta, renderToken });
+    const el = handle.element as unknown as HTMLTextAreaElement;
+
+    el.placeholder = "Type here";
+    expect(handle.element.getAttribute("data-placeholder")).toBe("Type here");
+    expect(handle.element.getAttribute("aria-label")).toBe("Type here");
+    expect(el.placeholder).toBe("Type here");
+    handle.destroy();
+  });
+
+  it("preserves an explicit host aria-label when placeholder updates land after swap", () => {
+    const ta = makeTextarea();
+    ta.setAttribute("aria-label", "Message support");
+    ta.setAttribute("placeholder", "Ask about a file…");
+
+    const handle = mountInlineComposer({ textarea: ta, renderToken });
+    const el = handle.element as unknown as HTMLTextAreaElement;
+    expect(handle.element.getAttribute("aria-label")).toBe("Message support");
+
+    // ui.ts updateCopy assigns truthy placeholder text on every config update;
+    // the host's accessible name must survive it.
+    el.placeholder = "Ask about a file…";
+    expect(handle.element.getAttribute("aria-label")).toBe("Message support");
+    expect(handle.element.getAttribute("data-placeholder")).toBe("Ask about a file…");
+    handle.destroy();
+  });
+
+  it("keeps a placeholder-derived aria-label in sync and clears it on empty", () => {
+    const ta = makeTextarea();
+    ta.setAttribute("placeholder", "Type a message");
+    const handle = mountInlineComposer({ textarea: ta, renderToken });
+    const el = handle.element as unknown as HTMLTextAreaElement;
+    expect(handle.element.getAttribute("aria-label")).toBe("Type a message");
+
+    el.placeholder = "First update";
+    expect(handle.element.getAttribute("aria-label")).toBe("First update");
+    el.placeholder = "Second update";
+    expect(handle.element.getAttribute("aria-label")).toBe("Second update");
+
+    // Empty placeholder leaves no stale accessible name behind.
+    el.placeholder = "";
+    expect(handle.element.getAttribute("aria-label")).toBeNull();
+    handle.destroy();
+  });
+
+  it("exposes ordered contentSegments via getInlineMessageFields", () => {
+    const ta = makeTextarea();
+    const handle = mountInlineComposer({ textarea: ta, renderToken });
+    handle.input.setValueWithCaret("Check ", 6);
+    handle.input.insertMentionAtSelection!(appRef);
+
+    const fields = (
+      handle.element as unknown as {
+        getInlineMessageFields: () => {
+          contentSegments: Array<{
+            kind: string;
+            text?: string;
+            ref?: { label?: string };
+          }>;
+        };
+      }
+    ).getInlineMessageFields();
+
+    const kinds = fields.contentSegments.map((s) => s.kind);
+    expect(kinds).toContain("mention");
+    const mention = fields.contentSegments.find((s) => s.kind === "mention");
+    expect(mention?.ref?.label).toBe("App.tsx");
+    handle.destroy();
+  });
+
+  it("untracks tokens when the shim value setter clears the composer", () => {
+    const ta = makeTextarea();
+    const onMentionRemoved = vi.fn();
+    const handle = mountInlineComposer({
+      textarea: ta,
+      renderToken,
+      onMentionRemoved,
+    });
+    const el = handle.element as unknown as HTMLTextAreaElement;
+    const id = handle.input.insertMentionAtSelection!(appRef);
+
+    // Programmatic `value =` (voice/clear path) drops the token DOM; the shim must
+    // fire the adapter's reconcile so the manager aborts that mention's resolve.
+    el.value = "";
+    expect(onMentionRemoved).toHaveBeenCalledWith(id);
+    handle.destroy();
+  });
+});

package/src/context-mentions-inline-entry.ts

@@ -0,0 +1,226 @@
+/**
+ * Inline-mention chunk entry — the HEAVY, DOM-bearing half of inline mode. Loaded
+ * on composer mount when `contextMentions.display === "inline"` and NEVER
+ * statically imported on the core path (the IIFE build marks
+ * `@runtypelabs/persona/context-mentions-inline` external; ESM/CJS mark the same
+ * subpath external via `build:client`). This is the only place the
+ * contenteditable engine + `composer-document` enter the widget at runtime.
+ *
+ * `mountInlineComposer` builds a contenteditable `ComposerInputCapability` that
+ * visually mirrors the live `<textarea>` and migrates its current value + caret.
+ * It does NOT touch the DOM tree or rebind listeners — the caller (`ui.ts`) swaps
+ * the element in place and re-points the composer's event handlers, because those
+ * live in the core and the chunk must stay free of that wiring.
+ */
+
+import {
+  createContentEditableComposerInput,
+  type ContentEditableComposerInputOptions,
+} from "./utils/composer-contenteditable";
+import { documentToMessageFields } from "./utils/composer-document";
+import type { ComposerInputCapability } from "./utils/composer-input";
+import type {
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionRef,
+} from "./types";
+
+/**
+ * Display/transcript fields a sent inline-mode message carries, derived from the
+ * live composer document. Computed in THIS chunk (it owns `composer-document.ts`
+ * at runtime) and read by the core `ui.ts` submit path via `getInlineMessageFields`
+ * below, so the core never imports the document model.
+ */
+export interface InlineComposerMessageFields {
+  content: string;
+  contextMentions: AgentWidgetContextMentionRef[];
+  contentSegments: AgentWidgetContentSegment[];
+}
+
+/**
+ * The `<textarea>`-shaped element the inline composer swaps in. Beyond the
+ * textarea API shims it also exposes `getInlineMessageFields()` so the core
+ * submit path can read the ordered document segments without importing the
+ * document model. `ui.ts` references this via a structural (type-only) shape.
+ */
+export type InlineComposerElement = HTMLElement & {
+  getInlineMessageFields: () => InlineComposerMessageFields;
+};
+
+export interface InlineComposerMountContext {
+  /** The live composer textarea to migrate from (value + caret + look). */
+  textarea: HTMLTextAreaElement;
+  /**
+   * Build a token's full element. Supplied by the CORE orchestrator (which owns
+   * `createMentionTokenElement` + the shared icon renderer) so this lazy chunk
+   * never bundles the icon set — it already ships in core. The adapter marks the
+   * returned element `contenteditable="false"` and stamps `data-mention-id`.
+   */
+  renderToken: (ref: AgentWidgetContextMentionRef) => HTMLElement;
+  /**
+   * Fired when a token is deleted from the composer (backspace/cut). The caller
+   * routes this to `engine.untrackMention(id)` so the manager aborts its resolve.
+   */
+  onMentionRemoved?: (id: string) => void;
+}
+
+export interface InlineComposerHandle {
+  /** The contenteditable input surface; hand this to `mountContextMentions`. */
+  input: ComposerInputCapability;
+  /** The contenteditable root element to swap in for the textarea. */
+  element: HTMLElement;
+  /** Detach the adapter's listeners on unmount. */
+  destroy: () => void;
+}
+
+let idSeq = 0;
+/** Page-unique mention id (composer-scoped; only needs uniqueness within a doc). */
+const generateId = (): string => `pmention-${++idSeq}`;
+
+/**
+ * Copy the visual hooks that make the contenteditable read like the textarea it
+ * replaces. The composer sets most of its look via INLINE styles at runtime (font
+ * vars from config, the `maxHeight`/`overflowY` auto-resize cap, border/outline
+ * stripping — see `composer-parts.ts` and `ui.ts` `updateCopy`), not just utility
+ * classes, so copy every inline style property across as well; otherwise the
+ * contenteditable falls back to its CSS defaults (a taller max-height, a different
+ * font) and visibly pops on swap. Also mirror the classes, the placeholder, and
+ * the accessible name.
+ */
+function mirrorTextareaLook(
+  textarea: HTMLTextAreaElement,
+  el: HTMLElement
+): void {
+  el.className = `${textarea.className} persona-composer-contenteditable`.trim();
+  // Copy every inline style property (font*, lineHeight, maxHeight, overflowY,
+  // border, outline, background, padding, color, …) so the box model + typography
+  // match exactly. Iterating keeps this in sync as the composer's inline styles
+  // evolve, without re-enumerating a fixed property list here. Skip `height`: the
+  // textarea's auto-resize sets it to a fixed px on input, but the contenteditable
+  // grows with its content (capped by the copied `maxHeight`/`overflowY`), so a
+  // frozen height would clip it.
+  for (let i = 0; i < textarea.style.length; i++) {
+    const prop = textarea.style.item(i);
+    if (prop === "height") continue;
+    el.style.setProperty(
+      prop,
+      textarea.style.getPropertyValue(prop),
+      textarea.style.getPropertyPriority(prop)
+    );
+  }
+  const placeholder = textarea.getAttribute("placeholder");
+  if (placeholder) {
+    el.setAttribute("data-placeholder", placeholder);
+    // Carry the placeholder in aria-placeholder (its correct role) rather than
+    // overloading the accessible name with it.
+    el.setAttribute("aria-placeholder", placeholder);
+  }
+  // Stable accessible name: prefer an explicit host/config aria-label on the
+  // textarea (ui.ts stamps config input copy there); fall back to the placeholder
+  // text for parity with chip mode (the plain textarea's name is its placeholder)
+  // so inline mode never regresses to an unnamed field.
+  const label = textarea.getAttribute("aria-label") ?? placeholder;
+  if (label) el.setAttribute("aria-label", label);
+}
+
+/**
+ * Make the contenteditable element quack like a `<textarea>` for the specific API
+ * surface the host composer code touches (`value`, `selectionStart/End`,
+ * `setSelectionRange`). This lets `ui.ts` keep reading/writing the composer the
+ * same way after the swap without threading the capability through every call
+ * site (doSubmit clears `value`; history sets `value` + caret; the send gate
+ * reads `value`). Everything is delegated to the capability so the document stays
+ * the source of truth. NOTE: `value` writes render PLAIN TEXT (no tokens) — inline
+ * history recall is plain-text in v1; tokens survive only within a live session.
+ */
+function shimTextareaApi(
+  el: HTMLElement,
+  input: ComposerInputCapability,
+  // True when the host stamped an explicit aria-label on the textarea. Its
+  // accessible name is authoritative, so placeholder writes must not clobber it.
+  hasHostLabel: boolean
+): void {
+  Object.defineProperty(el, "value", {
+    configurable: true,
+    get: () => input.getValue(),
+    set: (v: string) => {
+      input.setValueWithCaret(v, v.length);
+      // `setValueWithCaret` rebuilds the DOM as plain text (dropping any token
+      // spans) but does NOT itself run the adapter's removal reconcile. Fire an
+      // input event so vanished tokens untrack (the manager aborts their resolve)
+      // — otherwise a programmatic `value =` (voice transcript, clear, history
+      // recall) leaves stale resolved context tracked against the next send.
+      input.dispatchInput();
+    },
+  });
+  // The contenteditable reads its placeholder from `data-placeholder`, so a plain
+  // `.placeholder =` (e.g. `ui.ts` `updateCopy` after the swap, which assigns
+  // truthy placeholder text on every config update) would no-op. Map the textarea
+  // `placeholder` property onto the attribute. Only touch the accessible name when
+  // it is placeholder-derived — an explicit host aria-label must survive.
+  Object.defineProperty(el, "placeholder", {
+    configurable: true,
+    get: () => el.getAttribute("data-placeholder") ?? "",
+    set: (v: string) => {
+      if (v) {
+        el.setAttribute("data-placeholder", v);
+        el.setAttribute("aria-placeholder", v);
+        if (!hasHostLabel) el.setAttribute("aria-label", v);
+      } else {
+        el.removeAttribute("data-placeholder");
+        el.removeAttribute("aria-placeholder");
+        // Clear the placeholder-derived name too, so no stale label lingers.
+        if (!hasHostLabel) el.removeAttribute("aria-label");
+      }
+    },
+  });
+  Object.defineProperty(el, "selectionStart", {
+    configurable: true,
+    get: () => input.getSelection().start,
+  });
+  Object.defineProperty(el, "selectionEnd", {
+    configurable: true,
+    get: () => input.getSelection().end,
+  });
+  (el as unknown as HTMLTextAreaElement).setSelectionRange = (
+    start: number,
+    end: number
+  ) => input.setSelection(start ?? 0, end ?? start ?? 0);
+}
+
+export function mountInlineComposer(
+  ctx: InlineComposerMountContext
+): InlineComposerHandle {
+  const { textarea } = ctx;
+  const options: ContentEditableComposerInputOptions = {
+    generateId,
+    // Token DOM (incl. icon + any host `renderMentionToken`) is built in core and
+    // passed in, so this chunk stays free of the icon renderer.
+    renderToken: ctx.renderToken,
+    onMentionRemoved: ctx.onMentionRemoved,
+    placeholder: textarea.getAttribute("placeholder") ?? undefined,
+  };
+  const capability = createContentEditableComposerInput(options);
+  const el = capability.element;
+  // Capture before mirroring/shimming: whether the accessible name is an explicit
+  // host label (authoritative) or placeholder-derived (kept in sync with copy).
+  const hasHostLabel = textarea.getAttribute("aria-label") != null;
+  mirrorTextareaLook(textarea, el);
+  shimTextareaApi(el, capability, hasHostLabel);
+
+  // Expose the ordered document as sent-message fields for the core submit path.
+  // Computed here (this chunk owns `composer-document.ts`) so `ui.ts` can attach
+  // `contentSegments` to the user message without importing the document model.
+  (el as InlineComposerElement).getInlineMessageFields = () =>
+    documentToMessageFields(capability.getDocument?.() ?? { blocks: [] });
+
+  // Migrate current text + caret. Anything typed before the swap is plain text
+  // (tokens can't exist yet — the menu chunk gates selection), so this is lossless.
+  const caret = textarea.selectionStart ?? textarea.value.length;
+  capability.setValueWithCaret(textarea.value, caret);
+
+  return {
+    input: capability,
+    element: el,
+    destroy: capability.destroy,
+  };
+}

package/src/context-mentions-inline-loader.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  loadContextMentionsInline,
+  setContextMentionsInlineLoader,
+  type ContextMentionsInlineModule,
+} from "./context-mentions-inline-loader";
+
+const fakeModule = {
+  mountInlineComposer: vi.fn(),
+} as unknown as ContextMentionsInlineModule;
+
+describe("loadContextMentionsInline", () => {
+  it("retries after a rejected load instead of caching the failure forever", async () => {
+    const loader = vi
+      .fn<() => Promise<ContextMentionsInlineModule>>()
+      .mockRejectedValueOnce(new Error("network"))
+      .mockResolvedValueOnce(fakeModule);
+    setContextMentionsInlineLoader(loader);
+
+    // First call surfaces the rejection to the caller.
+    await expect(loadContextMentionsInline()).rejects.toThrow("network");
+    // A later call retries (the failed promise was not cached) and resolves.
+    await expect(loadContextMentionsInline()).resolves.toBe(fakeModule);
+    expect(loader).toHaveBeenCalledTimes(2);
+
+    // Once resolved, the module is cached (no third loader call).
+    await expect(loadContextMentionsInline()).resolves.toBe(fakeModule);
+    expect(loader).toHaveBeenCalledTimes(2);
+  });
+});

package/src/context-mentions-inline-loader.ts

@@ -0,0 +1,36 @@
+/**
+ * Loader indirection for the lazy inline-mention chunk (core bundle, tiny).
+ *
+ * Sibling of `context-mentions-loader.ts`. The IIFE/CDN entry (`index-global.ts`)
+ * registers a loader that imports the standalone `context-mentions-inline.js`
+ * chunk from a sibling URL; ESM/CJS consumers fall back to the package's
+ * `./context-mentions-inline` subpath — which `build:client` marks external, so
+ * the contenteditable engine is NOT inlined into `dist/index.{js,cjs}` and stays
+ * out of the core bundle. (A relative `./context-mentions-inline-entry` import
+ * would be inlined by the no-splitting build, defeating the split.)
+ *
+ * This is loaded on composer mount when `contextMentions.display === "inline"`,
+ * distinct from the chip menu chunk which loads on the first `@`/click.
+ */
+
+import { createChunkLoader } from "./utils/chunk-loader";
+import type {
+  InlineComposerMountContext,
+  InlineComposerHandle,
+} from "./context-mentions-inline-entry";
+
+export type ContextMentionsInlineModule = {
+  mountInlineComposer: (ctx: InlineComposerMountContext) => InlineComposerHandle;
+};
+
+// Memoization + rejection-retry semantics live in `createChunkLoader`.
+// `resetOnSetLoader` mirrors this loader's original behavior: registering a new
+// loader source invalidates whatever the previous loader produced (so a
+// mid-session swap for test injection takes effect deterministically).
+const { setLoader, load } = createChunkLoader<ContextMentionsInlineModule>({
+  fallbackImport: () => import("@runtypelabs/persona/context-mentions-inline"),
+  resetOnSetLoader: true,
+});
+
+export const setContextMentionsInlineLoader = setLoader;
+export const loadContextMentionsInline = load;

package/src/context-mentions-inline.ts

@@ -0,0 +1,15 @@
+/**
+ * Public entry for the lazy inline-mention chunk (`dist/context-mentions-inline.js`).
+ *
+ * Loaded on composer mount when `contextMentions.display === "inline"`. Carries
+ * the contenteditable engine (`composer-document`, `composer-contenteditable`)
+ * so chip-only and feature-off sites never download it. See
+ * `context-mentions-inline-loader.ts` and the loader registration in
+ * `index-global.ts`.
+ */
+
+export { mountInlineComposer } from "./context-mentions-inline-entry";
+export type {
+  InlineComposerMountContext,
+  InlineComposerHandle,
+} from "./context-mentions-inline-entry";

package/src/context-mentions-loader.ts

@@ -0,0 +1,32 @@
+/**
+ * Loader indirection for the lazy context-mentions chunk (core bundle, tiny).
+ *
+ * Mirrors `markdown-parsers-loader.ts`: the IIFE/CDN entry (`index-global.ts`)
+ * registers a loader that imports the standalone `context-mentions.js` chunk
+ * from a sibling URL. ESM/CJS consumers fall back to importing the package's
+ * `./context-mentions` subpath — which `build:client` marks external, so the
+ * runtime is NOT inlined into `dist/index.{js,cjs}` and stays out of the core
+ * bundle until first use. (A relative `./context-mentions-entry` import would be
+ * inlined by the no-splitting build, defeating the whole point.)
+ */
+
+import { createChunkLoader } from "./utils/chunk-loader";
+import type {
+  ContextMentionMountContext,
+  ContextMentionEngine,
+} from "./context-mentions-entry";
+
+export type ContextMentionsModule = {
+  mountContextMentions: (ctx: ContextMentionMountContext) => ContextMentionEngine;
+};
+
+// IIFE/CDN: sibling-URL chunk via the registered loader.
+// ESM/CJS fallback: the package's own `./context-mentions` subpath (external, so
+// the runtime chunk is code-split out of dist/index.{js,cjs} rather than
+// inlined). Memoization + rejection-retry semantics live in `createChunkLoader`.
+const { setLoader, load } = createChunkLoader<ContextMentionsModule>({
+  fallbackImport: () => import("@runtypelabs/persona/context-mentions"),
+});
+
+export const setContextMentionsLoader = setLoader;
+export const loadContextMentions = load;

package/src/context-mentions.ts

@@ -0,0 +1,16 @@
+/**
+ * Standalone context-mentions chunk (`dist/context-mentions.js`).
+ *
+ * The IIFE/CDN widget bundle marks `./context-mentions-entry` external so the
+ * mention runtime is excluded from the core payload; this file is built as a
+ * self-contained sibling chunk (`tsup.context-mentions.config.ts`) and loaded on
+ * demand by the loader registered in `index-global.ts`. ESM/CJS consumers import
+ * the entry directly. See `docs/context-mentions-plan.md`.
+ */
+
+export { mountContextMentions } from "./context-mentions-entry";
+export type {
+  ContextMentionMountContext,
+  ContextMentionEngine,
+  MentionSubmitBundle,
+} from "./context-mentions-entry";