@runtypelabs/persona 4.7.0 → 4.9.0

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,14 +27,21 @@ 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
+} from "./utils/artifact-display";
 import type {
   VoiceProvider,
   VoiceStatus,
   VoiceConfig,
   ReadAloudState,
-  SpeechEngine
+  SpeechEngine,
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionRef
 } from "./types";
+import type { MentionSubmitBundle } from "./utils/context-mention-manager";
 import {
   createVoiceProvider,
   isVoiceSupported,
@@ -1125,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();
@@ -1156,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 {
@@ -2607,33 +2727,82 @@ export class AgentWidgetSession {
     const id =
       manual.id ||
       `art_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
-    if (manual.artifactType === "markdown") {
-      const rec: PersonaArtifactRecord = {
-        id,
-        artifactType: "markdown",
-        title: manual.title,
-        status: "complete",
-        markdown: manual.content
-      };
-      this.artifacts.set(id, rec);
-      this.selectedArtifactId = id;
-      this.emitArtifactsState();
-      return rec;
-    }
-    const rec: PersonaArtifactRecord = {
-      id,
-      artifactType: "component",
-      title: manual.title,
-      status: "complete",
-      component: manual.component,
-      props: manual.props ?? {}
-    };
+    const rec: PersonaArtifactRecord =
+      manual.artifactType === "markdown"
+        ? {
+            id,
+            artifactType: "markdown",
+            title: manual.title,
+            status: "complete",
+            markdown: manual.content,
+            ...(manual.file ? { file: manual.file } : {})
+          }
+        : {
+            id,
+            artifactType: "component",
+            title: manual.title,
+            status: "complete",
+            component: manual.component,
+            props: manual.props ?? {}
+          };
     this.artifacts.set(id, rec);
     this.selectedArtifactId = id;
     this.emitArtifactsState();
+    if (manual.transcript !== false) {
+      this.injectArtifactRefBlock(rec);
+    }
     return rec;
   }
 
+  /**
+   * Injects (or refreshes) the in-thread artifact block for a programmatically
+   * upserted artifact, matching the streamed UX: the resolved display mode
+   * picks the component ("card"/"panel" → reference card, "inline" → inline
+   * preview).
+   *
+   * Unlike the streamed path (which embeds content on `artifact_complete`),
+   * the programmatic record is complete up front, so the final markdown /
+   * file meta / component name + props are embedded immediately and the block
+   * hydrates after a refresh without the original registry state.
+   *
+   * A re-upsert of the same id rebuilds the existing block's persisted
+   * rawContent in place (the registry is not persisted, so hydration reads
+   * these props); without this the block would keep the first version's
+   * content after a refresh.
+   */
+  private injectArtifactRefBlock(rec: PersonaArtifactRecord): void {
+    const refId = `artifact-ref-${rec.id}`;
+    const displayMode = resolveArtifactDisplayMode(
+      this.config.features?.artifacts,
+      rec.artifactType
+    );
+    const rawContent = buildArtifactRefRawContent(displayMode, {
+      artifactId: rec.id,
+      title: rec.title,
+      artifactType: rec.artifactType,
+      status: "complete",
+      ...(rec.file ? { file: rec.file } : {}),
+      ...(rec.component ? { component: rec.component } : {}),
+      ...(rec.props ? { componentProps: rec.props } : {}),
+      ...(rec.markdown !== undefined ? { markdown: rec.markdown } : {})
+    });
+    // Re-upsert: mutate the STORED message (inject stores a copy via
+    // ensureSequence, so a local copy would be lost) and notify so the
+    // transcript re-renders and persistence picks up the new version.
+    const existing = this.messages.find((m) => m.id === refId);
+    if (existing) {
+      existing.rawContent = rawContent;
+      existing.streaming = false;
+      this.callbacks.onMessagesChanged([...this.messages]);
+      return;
+    }
+    this.injectAssistantMessage({
+      id: refId,
+      content: "",
+      rawContent
+    });
+  }
+
   private clearArtifactState(): void {
     if (this.artifacts.size === 0 && this.selectedArtifactId === null) return;
     this.artifacts.clear();
@@ -2657,7 +2826,8 @@ export class AgentWidgetSession {
             artifactType: "markdown",
             title: ev.title,
             status: "streaming",
-            markdown: ""
+            markdown: "",
+            ...(ev.file ? { file: ev.file } : {})
           });
         } else {
           this.artifacts.set(ev.id, {

package/src/smart-dom-reader.test.ts

@@ -4,10 +4,11 @@
 // vendored library under jsdom. The pure-mapper correctness guarantee lives in
 // utils/smart-dom-adapter.test.ts (no DOM, no library); this test confirms the
 // vendored runtime loads and the provider wires up against a real document.
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import {
   collectSmartDomContext,
-  createSmartDomReaderContextProvider
+  createSmartDomReaderContextProvider,
+  createSmartDomMentionSource
 } from "./smart-dom-reader";
 
 // jsdom implements no layout, so getBoundingClientRect()/offsetParent report the
@@ -116,6 +117,66 @@ describe("smart-dom-reader entry (jsdom)", () => {
     expect(texts).toContain("Scoped shadow action");
   });
 
+  it("mention source surfaces page elements as items and resolves text at submit", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+    expect(source.id).toBe("page");
+    expect(source.resolveOn).toBe("submit");
+
+    const items = await source.search("", { messages: [], config: {} as never, signal: new AbortController().signal });
+    const go = items.find((i) => i.label.includes("Continue"));
+    expect(go).toBeTruthy();
+    expect(go!.id).toMatch(/#go|go/); // selector is the item id
+
+    // Filtering narrows the snapshot client-side.
+    const filtered = await source.search("checkout", { messages: [], config: {} as never, signal: new AbortController().signal });
+    expect(filtered.some((i) => i.label.includes("Continue"))).toBe(true);
+
+    // resolve() reads the live element text at submit.
+    const payload = await source.resolve(go!, {
+      messages: [],
+      config: {} as never,
+      composerText: "",
+      args: "",
+      signal: new AbortController().signal,
+    });
+    expect(payload.llmAppend).toContain("Continue to checkout");
+    expect(payload.context).toMatchObject({ selector: go!.id });
+  });
+
+  it("applies mapItem to reshape surfaced items without breaking resolve", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({
+      label: "Page",
+      ...JSDOM_OPTS,
+      mapItem: (el, defaultItem) => ({
+        ...defaultItem,
+        iconName: "star",
+        description: `custom:${el.tagName}`,
+      }),
+    });
+
+    const items = await source.search("", {
+      messages: [],
+      config: {} as never,
+      signal: new AbortController().signal,
+    });
+    const go = items.find((i) => i.label.includes("Continue"));
+    expect(go).toBeTruthy();
+    expect(go!.iconName).toBe("star");
+    expect(go!.description).toMatch(/^custom:/i);
+
+    // id stays the selector, so submit-time resolve still reads the live element.
+    const payload = await source.resolve(go!, {
+      messages: [],
+      config: {} as never,
+      composerText: "",
+      args: "",
+      signal: new AbortController().signal,
+    });
+    expect(payload.llmAppend).toContain("Continue to checkout");
+  });
+
   it("provider returns formatted context under the configured key", async () => {
     document.body.innerHTML = `<main><button id="go">Continue</button></main>`;
     const provider = createSmartDomReaderContextProvider({
@@ -132,4 +193,70 @@ describe("smart-dom-reader entry (jsdom)", () => {
     document.body.innerHTML = "";
     expect(collectSmartDomContext(JSDOM_OPTS)).toEqual([]);
   });
+
+  const searchCtx = () => ({
+    messages: [],
+    config: {} as never,
+    signal: new AbortController().signal,
+  });
+
+  it("reuses the snapshot across empty-query searches within the TTL (scans once)", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+
+    // Count extractions by observing DOM reads: a spy on querySelectorAll fires
+    // per scan. Simpler and TTL-independent: mutate the DOM between the two empty
+    // searches and assert the second still returns the pre-mutation snapshot.
+    const first = await source.search("", searchCtx());
+    expect(first.some((i) => i.label.includes("Continue"))).toBe(true);
+
+    // Change the page; a rescan would surface the new element.
+    document.body.innerHTML = `<main><button id="new">Brand new action</button></main>`;
+    const second = await source.search("", searchCtx());
+    // Still the cached snapshot: no rescan happened within the TTL.
+    expect(second.some((i) => i.label.includes("Continue"))).toBe(true);
+    expect(second.some((i) => i.label.includes("Brand new"))).toBe(false);
+  });
+
+  it("rescans on an empty query once the TTL has elapsed", async () => {
+    vi.useFakeTimers();
+    try {
+      document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+      const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+
+      const first = await source.search("", searchCtx());
+      expect(first.some((i) => i.label.includes("Continue"))).toBe(true);
+
+      // Mutate the page, then advance past the 2s TTL so the next empty query rescans.
+      document.body.innerHTML = `<main><button id="new">Brand new action</button></main>`;
+      vi.advanceTimersByTime(2500);
+
+      const second = await source.search("", searchCtx());
+      expect(second.some((i) => i.label.includes("Brand new"))).toBe(true);
+      expect(second.some((i) => i.label.includes("Continue"))).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("resolves an item from a cached snapshot against the live element", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+
+    // Prime the snapshot, then re-search (cached) to get the item without rescanning.
+    await source.search("", searchCtx());
+    const items = await source.search("checkout", searchCtx());
+    const go = items.find((i) => i.label.includes("Continue"));
+    expect(go).toBeTruthy();
+
+    const payload = await source.resolve(go!, {
+      messages: [],
+      config: {} as never,
+      composerText: "",
+      args: "",
+      signal: new AbortController().signal,
+    });
+    expect(payload.llmAppend).toContain("Continue to checkout");
+    expect(payload.context).toMatchObject({ selector: go!.id });
+  });
 });

package/src/smart-dom-reader.ts

@@ -40,10 +40,16 @@ import {
   type SmartDomAdapterOptions
 } from "./utils/smart-dom-adapter";
 import { formatEnrichedContext, type EnrichedPageElement } from "./utils/dom-context";
-import type { AgentWidgetContextProvider } from "./types";
+import { defaultMentionFilter } from "./utils/mention-matcher";
+import type {
+  AgentWidgetContextProvider,
+  AgentWidgetContextMentionItem,
+  AgentWidgetContextMentionSource,
+} from "./types";
 
 export { smartDomResultToEnriched };
 export type { SmartDomAdapterOptions } from "./utils/smart-dom-adapter";
+export type { EnrichedPageElement } from "./utils/dom-context";
 
 /** Options for {@link collectSmartDomContext} and {@link createSmartDomReaderContextProvider}. */
 export interface SmartDomContextOptions extends SmartDomAdapterOptions {
@@ -132,3 +138,123 @@ export function createSmartDomReaderContextProvider(
     return { [contextKey]: formatEnrichedContext(elements) };
   };
 }
+
+/** Options for {@link createSmartDomMentionSource}. */
+export interface SmartDomMentionSourceOptions extends SmartDomContextOptions {
+  /** Source id. Default: "page". */
+  id?: string;
+  /** Group header shown in the menu. Default: "Page". */
+  label?: string;
+  /**
+   * Reshape each surfaced element into a mention item. Receives the raw
+   * {@link EnrichedPageElement} and the default-mapped item, so you can tweak
+   * one field (`{ ...defaultItem, iconName: "star" }`) or build from scratch.
+   * The returned item's `id` MUST stay a selector `resolve()` can read at submit
+   * (default: `el.selector`) unless you also override resolution. @default built-in mapping
+   */
+  mapItem?: (
+    el: EnrichedPageElement,
+    defaultItem: AgentWidgetContextMentionItem
+  ) => AgentWidgetContextMentionItem;
+}
+
+// Empty-query snapshot reuse window: the full Shadow-DOM-piercing scan is
+// synchronous and runs inside the keystroke handler, so rescanning on every `@`
+// / backspace-to-empty stalls the input. Reuse a snapshot this fresh; rescan
+// past it so a menu opened after page changes still sees current content.
+const SNAPSHOT_TTL_MS = 2000;
+
+const iconForInteractivity = (kind: EnrichedPageElement["interactivity"]): string => {
+  switch (kind) {
+    case "clickable":
+      return "mouse-pointer-click";
+    case "input":
+      return "text-cursor-input";
+    case "navigable":
+      return "link";
+    default:
+      return "text";
+  }
+};
+
+const elementToMentionItem = (
+  el: EnrichedPageElement
+): AgentWidgetContextMentionItem => {
+  const ariaLabel = el.attributes["aria-label"];
+  const raw = (ariaLabel || el.text || el.tagName).trim();
+  const label = raw.length > 48 ? `${raw.slice(0, 47)}…` : raw || el.tagName;
+  const descParts = [el.role ?? el.tagName, el.interactivity].filter(Boolean);
+  return {
+    id: el.selector, // stable key + the selector resolve() reads at submit
+    label,
+    description: descParts.join(" · "),
+    iconName: iconForInteractivity(el.interactivity),
+    group: undefined,
+  };
+};
+
+/**
+ * First-class **supported** mention source backed by smart-dom-reader: surfaces
+ * visible page elements (Shadow-DOM-piercing) as mentionable items, resolving a
+ * fresh snapshot of the chosen element's text at SUBMIT (`resolveOn: "submit"`),
+ * since the page is time-sensitive. The element list is snapshotted when the
+ * menu opens (empty query) and filtered client-side with `defaultMentionFilter`
+ * as the user types.
+ *
+ * @example
+ * ```ts
+ * import { createSmartDomMentionSource } from "@runtypelabs/persona/smart-dom-reader";
+ *
+ * initAgentWidget({
+ *   contextMentions: { enabled: true, sources: [createSmartDomMentionSource()] },
+ * });
+ * ```
+ */
+export function createSmartDomMentionSource(
+  opts: SmartDomMentionSourceOptions = {}
+): AgentWidgetContextMentionSource {
+  const id = opts.id ?? "page";
+  const label = opts.label ?? "Page";
+  let snapshot: AgentWidgetContextMentionItem[] | null = null;
+  let capturedAt = 0;
+
+  const rescan = (): AgentWidgetContextMentionItem[] => {
+    const items = collectSmartDomContext(opts).map((el) => {
+      const defaultItem = elementToMentionItem(el);
+      return opts.mapItem ? opts.mapItem(el, defaultItem) : defaultItem;
+    });
+    capturedAt = Date.now();
+    return items;
+  };
+
+  return {
+    id,
+    label,
+    resolveOn: "submit",
+    search: (query) => {
+      // Rescan on empty query only when there's no snapshot or it's staler than
+      // the TTL; reopening the menu quickly reuses the snapshot, keystrokes always
+      // filter the existing one, so we never re-scan mid-typing.
+      const stale = !snapshot || Date.now() - capturedAt > SNAPSHOT_TTL_MS;
+      if (!snapshot || (query === "" && stale)) {
+        snapshot = rescan();
+      }
+      return defaultMentionFilter(snapshot, query);
+    },
+    resolve: (item) => {
+      const doc =
+        opts.document ?? (typeof document !== "undefined" ? document : undefined);
+      let text = "";
+      try {
+        const el = doc?.querySelector(item.id);
+        text = el?.textContent?.trim() ?? "";
+      } catch {
+        /* invalid selector at resolve time — fall through to label only */
+      }
+      return {
+        llmAppend: `Page element "${item.label}" (${item.id}):\n${text || "(no text)"}`,
+        context: { selector: item.id },
+      };
+    },
+  };
+}