@runtypelabs/persona 4.8.0 → 4.9.0

package/src/markdown-parsers-loader.ts

@@ -1,3 +1,4 @@
+import { createChunkLoader } from "./utils/chunk-loader";
 import type { Marked } from "marked";
 import type DOMPurify from "dompurify";
 
@@ -6,19 +7,22 @@ export type MarkdownParsersModule = {
   DOMPurify: typeof DOMPurify;
 };
 
-let loader: (() => Promise<MarkdownParsersModule>) | null = null;
-let moduleCache: MarkdownParsersModule | null = null;
-let loadPromise: Promise<MarkdownParsersModule> | null = null;
+// Memoization + rejection-retry semantics live in `createChunkLoader`. The
+// ESM/CJS fallback imports `./markdown-parsers-entry` directly; the IIFE/CDN
+// build registers a loader that fetches the `markdown-parsers.js` chunk.
+const { setLoader, load, provide, getSync } =
+  createChunkLoader<MarkdownParsersModule>({
+    fallbackImport: () => import("./markdown-parsers-entry"),
+  });
 
 // Surfaces that want to self-heal when the lazy `markdown-parsers.js` chunk
 // lands. See `onMarkdownParsersReady` below for why this is centralized.
 const readySubscribers = new Set<() => void>();
 
-// Flip `moduleCache` and fan out to everyone waiting to re-render, exactly once
-// per subscriber. Called from BOTH the eager (`provideMarkdownParsers`) and lazy
+// Fan out to everyone waiting to re-render, exactly once per subscriber.
+// Called from BOTH the eager (`provideMarkdownParsers`) and lazy
 // (`loadMarkdownParsers`) paths so a subscriber can't miss the transition.
-const markParsersReady = (mod: MarkdownParsersModule): MarkdownParsersModule => {
-  moduleCache = mod;
+const notifyParsersReady = (): void => {
   // Snapshot + clear first: fire-once semantics, and a callback that re-subscribes
   // (it won't — `onMarkdownParsersReady` no-ops once ready) can't loop.
   const subs = [...readySubscribers];
@@ -31,11 +35,25 @@ const markParsersReady = (mod: MarkdownParsersModule): MarkdownParsersModule =>
       /* subscriber threw: swallow so the remaining re-renders still run */
     }
   }
-  return mod;
 };
 
-export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>) => {
-  loader = l;
+export const setMarkdownParsersLoader = setLoader;
+
+// On a failed chunk load (404, ad blocker, offline), `createChunkLoader`
+// resets its cached promise so a later call retries. Pending subscribers are
+// KEPT — a surface that rendered escaped during the failed attempt must still
+// heal when a retry (kicked by a new subscriber or an explicit
+// loadMarkdownParsers() call) succeeds; dropping them left that surface
+// escaped forever after a transient failure. They're only retained while the
+// parsers stay unloaded — success releases them (fire-once in
+// `notifyParsersReady`), and callers can unsubscribe.
+export const loadMarkdownParsers = (): Promise<MarkdownParsersModule> => {
+  const cached = getSync();
+  if (cached) return Promise.resolve(cached);
+  return load().then((mod) => {
+    notifyParsersReady();
+    return mod;
+  });
 };
 
 /**
@@ -58,12 +76,13 @@ export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>
  * Fires at most once per subscription.
  */
 export const onMarkdownParsersReady = (cb: () => void): (() => void) => {
-  if (moduleCache) return () => {};
+  if (getSync()) return () => {};
   readySubscribers.add(cb);
   // Ensure the chunk is actually being fetched; harmless if already in flight.
   // Swallow rejection here — on failure the subscriber stays registered (see
-  // `onLoadFailure`) and the surface keeps its escaped fallback until a retry
-  // succeeds; this catch only avoids an unhandled rejection.
+  // the note on `loadMarkdownParsers`) and the surface keeps its escaped
+  // fallback until a retry succeeds; this catch only avoids an unhandled
+  // rejection.
   void loadMarkdownParsers().catch(() => {});
   return () => {
     readySubscribers.delete(cb);
@@ -79,36 +98,8 @@ export const onMarkdownParsersReady = (cb: () => void): (() => void) => {
  * it lazy-loads the `markdown-parsers.js` chunk instead.
  */
 export const provideMarkdownParsers = (mod: MarkdownParsersModule): void => {
-  markParsersReady(mod);
+  provide(mod);
+  notifyParsersReady();
 };
 
-// On a failed chunk load (404, ad blocker, offline), don't cache the rejected
-// promise: reset it so a later subscribe/load call can retry. Pending
-// subscribers are KEPT — a surface that rendered escaped during the failed
-// attempt must still heal when a retry (kicked by a new subscriber or an
-// explicit loadMarkdownParsers() call) succeeds; dropping them here left that
-// surface escaped forever after a transient failure. They're only retained
-// while the parsers stay unloaded — success releases them (fire-once in
-// `markParsersReady`), and callers can unsubscribe. On a permanently failing
-// setup they persist for the page's life, which is the price of healing.
-// Re-throw so awaiters of loadMarkdownParsers() still observe the rejection.
-const onLoadFailure = (err: unknown): never => {
-  loadPromise = null;
-  throw err;
-};
-
-export const loadMarkdownParsers = (): Promise<MarkdownParsersModule> => {
-  if (moduleCache) return Promise.resolve(moduleCache);
-  if (loadPromise) return loadPromise;
-  if (!loader) {
-    // Fallback for regular ESM/CJS consumers (they import directly)
-    loadPromise = import("./markdown-parsers-entry").then(markParsersReady, onLoadFailure);
-    return loadPromise;
-  }
-  loadPromise = loader().then(markParsersReady, onLoadFailure);
-  return loadPromise;
-};
-
-export const getMarkdownParsersSync = (): MarkdownParsersModule | null => {
-  return moduleCache;
-};
+export const getMarkdownParsersSync = getSync;

package/src/plugin-kit.test.ts

@@ -188,6 +188,46 @@ describe("createPopover", () => {
     expect(content.getRootNode()).toBe(shadow);
   });
 
+  it("anchors vertically to a verticalOffset when placement is top-start", () => {
+    const { anchor, content } = setup();
+    anchor.getBoundingClientRect = () =>
+      ({
+        left: 100,
+        right: 400,
+        top: 200,
+        bottom: 260,
+        width: 300,
+        height: 60,
+        x: 100,
+        y: 200,
+        toJSON: () => ({}),
+      }) as DOMRect;
+    content.getBoundingClientRect = () =>
+      ({
+        width: 180,
+        height: 100,
+        left: 0,
+        right: 180,
+        top: 0,
+        bottom: 100,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    const popover = createPopover({
+      anchor,
+      content,
+      placement: "top-start",
+      offset: 6,
+      verticalOffset: () => 40,
+    });
+    popover.open();
+
+    // anchorTop = 200 + 40 = 240 → top = 240 - 6 - 100 = 134
+    expect(content.style.top).toBe("134px");
+  });
+
   it("destroy removes content and detaches listeners", () => {
     vi.useFakeTimers();
     const onDismiss = vi.fn();

package/src/plugin-kit.ts

@@ -117,6 +117,23 @@ export interface PopoverOptions {
   offset?: number;
   /** Set `content`'s `min-width` to the anchor's width. Default `false`. */
   matchAnchorWidth?: boolean;
+  /**
+   * Horizontal anchoring override for `*-start` placements. Returns the desired
+   * left offset in px measured from the anchor's LEFT edge (e.g. the `@` trigger's
+   * x within the composer), or `null` to left-align with the anchor as usual. When
+   * this option is present the content is content-sized and capped to the anchor's
+   * width, and the resolved left is clamped so the content never overflows the
+   * anchor's left/right edges (Slack-style: a near-right trigger shifts the menu
+   * left to fit). Omit it entirely for plain anchor-left/right placement.
+   */
+  horizontalOffset?: () => number | null;
+  /**
+   * Vertical anchoring override for `top-*` placements. Returns the desired
+   * anchor point's top offset in px measured from the anchor's TOP edge (e.g.
+   * the trigger line's top within the composer), or `null` to use the anchor's
+   * top edge as usual.
+   */
+  verticalOffset?: () => number | null;
   /**
    * Inline `z-index` for `content`. Default `2147483000` so it overlays the rest
    * of the widget. Pass `null` to leave z-index to your own CSS.
@@ -175,6 +192,8 @@ export function createPopover(options: PopoverOptions): PopoverHandle {
     placement = "bottom-start",
     offset = 6,
     matchAnchorWidth = false,
+    horizontalOffset,
+    verticalOffset,
     zIndex = 2147483000,
     onOpen,
     onDismiss,
@@ -189,16 +208,31 @@ export function createPopover(options: PopoverOptions): PopoverHandle {
     const rect = anchor.getBoundingClientRect();
     content.style.position = "fixed";
     if (matchAnchorWidth) content.style.minWidth = `${rect.width}px`;
+    // Trigger-anchored mode: content is sized to its own contents but never wider
+    // than the composer, so it can shift horizontally within the composer's span.
+    if (horizontalOffset) content.style.maxWidth = `${rect.width}px`;
+
+    // Single content measurement per reposition (after width constraints apply).
+    const contentRect = content.getBoundingClientRect();
 
+    const offY = verticalOffset?.() ?? null;
+    const anchorTop = offY != null ? rect.top + offY : rect.top;
     const top =
       placement === "top-start" || placement === "top-end"
-        ? rect.top - offset - content.getBoundingClientRect().height
+        ? anchorTop - offset - contentRect.height
         : rect.bottom + offset;
 
-    const left =
-      placement === "bottom-end" || placement === "top-end"
-        ? rect.right - content.getBoundingClientRect().width
-        : rect.left;
+    const isEnd = placement === "bottom-end" || placement === "top-end";
+    // Default: anchor left (or anchor right for `*-end`). Trigger-anchored mode
+    // (offset present and non-null) overrides with the clamped trigger position so
+    // the menu never overflows the anchor's edges — a near-right trigger shifts it
+    // left to fit (Slack-style). A null offset falls back to the default.
+    let left = isEnd ? rect.right - contentRect.width : rect.left;
+    const off = horizontalOffset?.() ?? null;
+    if (off != null) {
+      const maxLeft = Math.max(rect.left, rect.right - contentRect.width);
+      left = Math.min(Math.max(rect.left + off, rect.left), maxLeft);
+    }
 
     content.style.top = `${top}px`;
     content.style.left = `${left}px`;

package/src/session.mentions.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+import { AgentWidgetSession } from "./session";
+import type {
+  AgentWidgetMessage,
+  AgentWidgetRequestPayload,
+  ContentPart,
+} from "./types";
+import type { MentionSubmitBundle } from "./context-mentions-entry";
+
+/** A closed, empty SSE stream so `dispatch` completes with no events. */
+function closedStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream({ start: (c) => c.close() });
+}
+
+/**
+ * Regression coverage for the mention/command submit path:
+ * - an empty-text, chip-only submit must NOT render the "[Image]" fallback
+ *   (that fallback is for image-only turns);
+ * - a `command: "server"` mention's `resolve().context` must ride to the
+ *   backend under request `context.mentions` (the c1 dispatch channel).
+ */
+describe("AgentWidgetSession — mention/command submit", () => {
+  function makeSession(captured: { payload?: AgentWidgetRequestPayload }) {
+    let messages: AgentWidgetMessage[] = [];
+    let status = "idle";
+    let streaming = false;
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: "http://localhost:8000",
+        customFetch: async (_url, _init, payload) => {
+          captured.payload = payload;
+          return { ok: true, body: closedStream() } as unknown as Response;
+        },
+      },
+      {
+        onMessagesChanged: (m) => {
+          messages = m;
+        },
+        onStatusChanged: (s) => {
+          status = s;
+        },
+        onStreamingChanged: (s) => {
+          streaming = s;
+        },
+        onError: () => {},
+      }
+    );
+    return {
+      session,
+      user: () => messages.find((m) => m.role === "user"),
+      status: () => status,
+      streaming: () => streaming,
+    };
+  }
+
+  it("renders no [Image] fallback for a command-only submit and forwards context.mentions", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, user } = makeSession(captured);
+
+    // A server skill: `/lookup 1042` resolved to structured context, namespaced
+    // `{ [sourceId]: { [itemId]: context } }` exactly as the manager builds it.
+    const context = { commands: { lookup: { intent: "lookup-order", orderId: "1042" } } };
+    const refs = [{ sourceId: "commands", itemId: "lookup", label: "lookup" }];
+    const bundle: MentionSubmitBundle = {
+      blocks: [],
+      contentParts: [],
+      context,
+    };
+
+    await session.sendMessage("", {
+      mentions: {
+        refs,
+        finalize: async () => bundle,
+      },
+    });
+
+    const msg = user();
+    expect(msg).toBeDefined();
+    // The bug: an empty-text, mention-only submit used to display "[Image]".
+    expect(msg!.content).toBe("");
+    expect(msg!.content).not.toBe("[Image]");
+    // The command chip echoes immediately as a ref.
+    expect(msg!.contextMentions).toEqual(refs);
+    // Structured server-command data is merged onto the message…
+    expect(msg!.mentionContext).toEqual(context);
+    // …and rides to the backend under request `context.mentions`.
+    expect(captured.payload?.context).toMatchObject({ mentions: context });
+  });
+
+  it("merges resolved @-mention llmContent into the dispatched snapshot", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session } = makeSession(captured);
+
+    await session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: async (): Promise<MentionSubmitBundle> => ({
+          blocks: ["```App.tsx\nFILE BODY\n```"],
+          contentParts: [],
+          context: {},
+        }),
+      },
+    });
+
+    const dispatched = (captured.payload?.messages ?? []).find(
+      (m) => m.role === "user"
+    );
+    // The client collapses `llmContent` into the payload `content` field via the
+    // content-priority chain, so the model must see the resolved file body
+    // appended to the typed prose — not just the raw "summarize this".
+    const sent = dispatched?.content;
+    expect(typeof sent).toBe("string");
+    expect(sent as string).toContain("FILE BODY");
+    expect(sent as string).toContain("summarize this");
+    // Mention blocks lead; the typed prose lands last (joined by a blank line).
+    expect(sent as string).toBe("```App.tsx\nFILE BODY\n```\n\nsummarize this");
+  });
+
+  it("still renders the [Image] fallback for an image-only submit", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, user } = makeSession(captured);
+
+    const contentParts: ContentPart[] = [
+      { type: "image", image: "data:image/png;base64,abc123", mimeType: "image/png" },
+    ];
+    await session.sendMessage("", { contentParts });
+
+    expect(user()!.content).toBe("[Image]");
+  });
+
+  it("cancel() during a pending mention finalize aborts the turn without dispatching", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, status, streaming } = makeSession(captured);
+
+    let releaseFinalize!: (bundle: MentionSubmitBundle) => void;
+    const pending = new Promise<MentionSubmitBundle>((resolve) => {
+      releaseFinalize = resolve;
+    });
+
+    const sent = session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: () => pending,
+      },
+    });
+
+    // Stop mid-resolution, then let finalize settle: dispatch must not fire.
+    session.cancel();
+    releaseFinalize({ blocks: ["```App.tsx\nBODY\n```"], contentParts: [], context: {} });
+    await sent;
+
+    expect(captured.payload).toBeUndefined();
+    expect(status()).toBe("idle");
+    expect(streaming()).toBe(false);
+  });
+
+  it("dispatches a normal mention submit once finalize resolves", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, streaming } = makeSession(captured);
+
+    await session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: async (): Promise<MentionSubmitBundle> => ({
+          blocks: ["```App.tsx\nBODY\n```"],
+          contentParts: [],
+          context: {},
+        }),
+      },
+    });
+
+    expect(captured.payload).toBeDefined();
+    expect(streaming()).toBe(false);
+  });
+});

package/src/session.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { AgentWidgetSession, AgentWidgetSessionStatus } from './session';
-import { AgentWidgetMessage } from './types';
+import { AgentWidgetMessage, AgentWidgetContentSegment } from './types';
 
 describe('AgentWidgetSession - Message Injection', () => {
   let session: AgentWidgetSession;
@@ -369,6 +369,51 @@ describe('AgentWidgetSession - Message Injection', () => {
   });
 });
 
+describe('AgentWidgetSession - inline contentSegments', () => {
+  const originalFetch = global.fetch;
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  const makeHangingSession = () => {
+    // A never-settling fetch keeps the turn in-flight so the appended user
+    // message can be inspected without a dispatch-error bubble replacing it.
+    global.fetch = vi.fn().mockImplementation(() => new Promise(() => {}));
+    return new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+  };
+
+  it('stores ordered contentSegments on the sent user message', () => {
+    const session = makeHangingSession();
+    const segments: AgentWidgetContentSegment[] = [
+      { kind: 'text', text: 'Check ' },
+      { kind: 'mention', ref: { sourceId: 'files', itemId: 'app', label: 'App.tsx' } },
+      { kind: 'text', text: ' please' },
+    ];
+    void session.sendMessage('Check @App.tsx please', {
+      contentSegments: segments,
+    });
+    const userMsg = session.getMessages().find((m) => m.role === 'user');
+    // Segments must land on the stored (sequence-normalized) copy, not just the
+    // orphaned input literal — this is the fix for the dead inline-token branch.
+    expect(userMsg?.contentSegments).toEqual(segments);
+  });
+
+  it('omits contentSegments for a plain message', () => {
+    const session = makeHangingSession();
+    void session.sendMessage('plain message');
+    const userMsg = session.getMessages().find((m) => m.role === 'user');
+    expect(userMsg?.contentSegments).toBeUndefined();
+  });
+});
+
 describe('AgentWidgetSession - cancel()', () => {
   const originalFetch = global.fetch;
 
@@ -404,9 +449,12 @@ describe('AgentWidgetSession - cancel()', () => {
 
     // Kick off the dispatch but don't await: we want it in-flight when we cancel.
     const dispatchPromise = session.sendMessage('Hello');
-    // Let the session set up the AbortController and call fetch.
-    await Promise.resolve();
-    await Promise.resolve();
+    // Drain microtasks until the session has set up the AbortController and
+    // called fetch (payload building is async, so the exact tick count is not a
+    // contract — wait for the observable effect instead).
+    for (let i = 0; i < 20 && capturedSignal === null; i++) {
+      await Promise.resolve();
+    }
 
     expect(streaming).toBe(true);
     expect(session.isStreaming()).toBe(true);

package/src/session.ts

@@ -27,7 +27,7 @@ import {
   generateUserMessageId,
   generateAssistantMessageId
 } from "./utils/message-id";
-import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "./utils/content";
+import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT, createTextPart, hasImages } from "./utils/content";
 import {
   buildArtifactRefRawContent,
   resolveArtifactDisplayMode
@@ -37,8 +37,11 @@ import type {
   VoiceStatus,
   VoiceConfig,
   ReadAloudState,
-  SpeechEngine
+  SpeechEngine,
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionRef
 } from "./types";
+import type { MentionSubmitBundle } from "./utils/context-mention-manager";
 import {
   createVoiceProvider,
   isVoiceSupported,
@@ -1129,17 +1132,92 @@ export class AgentWidgetSession {
     });
   }
 
+  /**
+   * Resolve the gathered mentions and merge them into the user message's
+   * model-visible content. Default path is `llmAppend` → `llmContent` (or a text
+   * `contentPart` when parts are present, since `contentParts` wins the priority
+   * chain); the opt-in structured `context` lands on `mentionContext` for the
+   * client to namespace into the request `context`. Failures were already
+   * dropped by `finalize()`.
+   */
+  private async applyMentionBundle(
+    userMessage: AgentWidgetMessage,
+    typedText: string,
+    finalize: () => Promise<MentionSubmitBundle>
+  ): Promise<void> {
+    let bundle: MentionSubmitBundle;
+    try {
+      bundle = await finalize();
+    } catch {
+      return; // resolution failed entirely; send the typed text as-is
+    }
+
+    // Blocks arrive pre-formatted from the mention layer (fenced/document/custom
+    // per `contextMentions.llmFormat`); the session just joins them and appends
+    // the typed prose last.
+    const block = bundle.blocks.join("\n\n");
+    const llmText = [block, typedText].filter(Boolean).join("\n\n");
+
+    const hasAttachments =
+      Array.isArray(userMessage.contentParts) &&
+      userMessage.contentParts.length > 0;
+    const hasMentionParts = bundle.contentParts.length > 0;
+
+    if (hasAttachments) {
+      // The typed text already rides as a content part; add the block + mention
+      // parts ahead of the existing attachment parts (mentions first).
+      const parts: ContentPart[] = [];
+      if (block) parts.push(createTextPart(block));
+      parts.push(...bundle.contentParts);
+      parts.push(...userMessage.contentParts!);
+      userMessage.contentParts = parts;
+    } else if (hasMentionParts) {
+      const parts: ContentPart[] = [];
+      if (llmText) parts.push(createTextPart(llmText));
+      parts.push(...bundle.contentParts);
+      userMessage.contentParts = parts;
+    } else if (block) {
+      userMessage.llmContent = llmText;
+    }
+
+    if (Object.keys(bundle.context).length > 0) {
+      userMessage.mentionContext = bundle.context;
+    }
+  }
+
   public async sendMessage(
     rawInput: string,
     options?: {
       viaVoice?: boolean;
       /** Multi-modal content parts (e.g., images) to include with the message */
       contentParts?: ContentPart[];
+      /**
+       * Context mentions gathered from the composer. `refs` echo immediately as
+       * chips; `finalize()` resolves any pending/submit sources just before
+       * dispatch (after the instant echo) and the bundle is merged into this
+       * message's model-visible content.
+       */
+      mentions?: {
+        refs: AgentWidgetContextMentionRef[];
+        finalize: () => Promise<MentionSubmitBundle>;
+      };
+      /**
+       * Ordered prose + mention segments for inline-mode display (`display:
+       * "inline"`). Stored on the user message so its bubble re-renders `@tokens`
+       * in place (and suppresses the chip row). Display/transcript only — the
+       * model still sees resolved bodies via the `mentions` bundle above.
+       */
+      contentSegments?: AgentWidgetContentSegment[];
     }
   ) {
     const input = rawInput.trim();
-    // Allow sending if there's text OR attachments
-    if (!input && (!options?.contentParts || options.contentParts.length === 0)) return;
+    // Allow sending if there's text OR attachments OR mentions
+    if (
+      !input &&
+      (!options?.contentParts || options.contentParts.length === 0) &&
+      (!options?.mentions || options.mentions.refs.length === 0)
+    )
+      return;
 
     this.stopSpeaking();
     this.abortController?.abort();
@@ -1160,25 +1238,63 @@ export class AgentWidgetSession {
     // the proxy path auto-generates a different id than `assistantMessageId`.
     this.activeAssistantMessageId = null;
 
+    // Fallback display text ONLY when the sole content is image attachments.
+    // A mention/command-only submit (empty text + a chip) must NOT read as
+    // "[Image]"; it renders its chips with empty text instead.
+    const imageOnlyFallback =
+      options?.contentParts && hasImages(options.contentParts)
+        ? IMAGE_ONLY_MESSAGE_FALLBACK_TEXT
+        : "";
+
     const userMessage: AgentWidgetMessage = {
       id: userMessageId,
       role: "user",
-      content: input || IMAGE_ONLY_MESSAGE_FALLBACK_TEXT, // Display text (fallback if only images)
+      content: input || imageOnlyFallback, // Display text (fallback if only images)
       createdAt: new Date().toISOString(),
       sequence: this.nextSequence(),
       viaVoice: options?.viaVoice || false,
       // Include contentParts if provided (for multi-modal messages)
       ...(options?.contentParts && options.contentParts.length > 0 && {
         contentParts: options.contentParts
+      }),
+      // Echo mention chips immediately (refs only; payloads merged below).
+      ...(options?.mentions && options.mentions.refs.length > 0 && {
+        contextMentions: options.mentions.refs
+      }),
+      // Inline mode: ordered display segments for in-prose `@token` rendering.
+      ...(options?.contentSegments && options.contentSegments.length > 0 && {
+        contentSegments: options.contentSegments
       })
     };
 
     this.appendMessage(userMessage);
     this.setStreaming(true);
 
+    // Assign the fresh controller BEFORE the mention await so cancel() (or a
+    // superseding sendMessage) during finalize() aborts THIS turn, not a stale
+    // prior controller.
     const controller = new AbortController();
     this.abortController = controller;
 
+    // Resolve + merge mentions AFTER the instant echo but BEFORE dispatch, so
+    // the model sees the context while the user's bubble already rendered.
+    // `appendMessage` stores a sequence-normalized COPY (see `ensureSequence`),
+    // so mutate THAT live reference — not the orphaned `userMessage` literal —
+    // or the merged `llmContent`/`contentParts`/`mentionContext` never reach the
+    // dispatch snapshot below. Re-emit so any merged parts also reach the UI.
+    if (options?.mentions) {
+      const stored =
+        this.messages.find((m) => m.id === userMessageId) ?? userMessage;
+      await this.applyMentionBundle(stored, input, options.mentions.finalize);
+      // A cancel() or new sendMessage during finalize aborted this controller
+      // (and replaced/nulled the shared ref). Bail without dispatching and
+      // leave whatever idle/streaming state that caller already set.
+      if (controller.signal.aborted || this.abortController !== controller) {
+        return;
+      }
+      this.callbacks.onMessagesChanged([...this.messages]);
+    }
+
     const snapshot = [...this.messages];
 
     try {