@runtypelabs/persona 4.8.0 → 4.9.0

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

package/src/styles/context-mention-menu-css.ts

@@ -0,0 +1,176 @@
+/**
+ * CSS for the context-mention MENU (floating popover): search field, grouped
+ * result list, options, status/empty/error rows, retry button, and the
+ * coarse-pointer touch sizing for its rows.
+ *
+ * This lives in the lazy `context-mentions` chunk (not `widget.css`) and is
+ * injected on first menu open via `injectStyles`. Two reasons:
+ *   1. it keeps ~1 kB of menu-only CSS out of the eager core stylesheet;
+ *   2. the menu mounts into the popover container (document.body by default),
+ *      which is OUTSIDE a `useShadowDom` widget's shadow root — where the
+ *      shadow-scoped `widget.css` never reached it. Injecting at mount time puts
+ *      the rules in whichever root the menu actually lives in.
+ *
+ * The chip / context-row / affordance-button rules stay in `widget.css`: they
+ * render eagerly (restored-message chips, the always-visible add-context button)
+ * before this chunk loads.
+ */
+export const MENTION_MENU_CSS = `
+.persona-mention-menu {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  max-height: var(--persona-mention-menu-max-height, 280px);
+  overflow: hidden;
+  background: var(--persona-mention-menu-bg, var(--persona-surface, #ffffff));
+  border: 1px solid var(--persona-mention-menu-border, var(--persona-border, #e5e7eb));
+  border-radius: var(--persona-mention-menu-radius, 10px);
+  box-shadow: var(--persona-mention-menu-shadow, 0 8px 28px rgba(0, 0, 0, 0.12));
+  font-family: var(--persona-font-family, inherit);
+}
+.persona-mention-list {
+  min-height: 0;
+  overflow-y: auto;
+  padding: 4px;
+}
+.persona-mention-search {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 10px;
+  border-bottom: 1px solid var(--persona-mention-menu-border, var(--persona-border, #e5e7eb));
+}
+.persona-mention-search-icon {
+  display: inline-flex;
+  align-items: center;
+  flex: 0 0 auto;
+  color: var(--persona-mention-group-fg, var(--persona-muted, #6b7280));
+}
+.persona-mention-search-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-family: inherit;
+  /* 16px, not 14px: iOS Safari zooms the page when focusing an input under 16px. */
+  font-size: 16px;
+  line-height: 1.4;
+  color: var(--persona-text, #111827);
+}
+.persona-mention-search-input::placeholder {
+  color: var(--persona-mention-group-fg, var(--persona-muted, #6b7280));
+}
+.persona-mention-group + .persona-mention-group {
+  margin-top: 2px;
+  border-top: 1px solid var(--persona-mention-menu-border, var(--persona-border, #f1f1f1));
+  padding-top: 2px;
+}
+.persona-mention-group-header {
+  padding: 6px 8px 4px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--persona-mention-group-fg, var(--persona-muted, #6b7280));
+}
+.persona-mention-option {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  color: var(--persona-text, #111827);
+}
+.persona-mention-option[data-active="true"] {
+  background: var(--persona-mention-option-active-bg, var(--persona-container, #f1f5f9));
+}
+.persona-mention-option-icon {
+  display: inline-flex;
+  align-items: center;
+  flex: 0 0 auto;
+  opacity: 0.7;
+}
+.persona-mention-option-text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+.persona-mention-option-labelline {
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  min-width: 0;
+}
+.persona-mention-option-label {
+  font-size: 13px;
+  line-height: 1.3;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.persona-mention-option-arghint {
+  flex: 0 0 auto;
+  font-size: 12px;
+  line-height: 1.3;
+  color: var(--persona-muted, #6b7280);
+  opacity: 0.85;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.persona-mention-option-desc {
+  font-size: 11px;
+  line-height: 1.3;
+  color: var(--persona-muted, #6b7280);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.persona-mention-status,
+.persona-mention-empty,
+.persona-mention-hint {
+  padding: 7px 8px;
+  font-size: 12px;
+  color: var(--persona-muted, #6b7280);
+}
+.persona-mention-error {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  color: var(--persona-mention-error, #dc2626);
+}
+.persona-mention-error-text {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.persona-mention-retry {
+  flex: 0 0 auto;
+  padding: 4px 8px;
+  border: 1px solid var(--persona-mention-error, #dc2626);
+  border-radius: 6px;
+  background: transparent;
+  color: var(--persona-mention-error, #dc2626);
+  font: inherit;
+  font-size: 12px;
+  cursor: pointer;
+}
+.persona-mention-retry:hover {
+  background: var(--persona-palette-colors-black-alpha-50, rgba(0, 0, 0, 0.06));
+}
+.persona-mention-hint {
+  font-style: italic;
+  opacity: 0.8;
+}
+@media (pointer: coarse) {
+  .persona-mention-option {
+    min-height: 44px;
+  }
+  .persona-mention-retry {
+    min-height: 36px;
+  }
+}
+`;