@runtypelabs/persona 4.8.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -62,6 +62,16 @@
       "import": "./dist/animations/wipe.js",
       "require": "./dist/animations/wipe.cjs"
     },
+    "./context-mentions": {
+      "types": "./dist/context-mentions.d.ts",
+      "import": "./dist/context-mentions.js",
+      "require": "./dist/context-mentions.cjs"
+    },
+    "./context-mentions-inline": {
+      "types": "./dist/context-mentions-inline.d.ts",
+      "import": "./dist/context-mentions-inline.js",
+      "require": "./dist/context-mentions-inline.cjs"
+    },
     "./widget.css": "./dist/widget.css"
   },
   "files": [
@@ -120,7 +130,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations && pnpm run check:dist-vite8",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:context-mentions && pnpm run build:context-mentions-inline && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations && pnpm run check:dist-vite8",
     "check:dist-vite8": "node scripts/check-dist-no-in-for-init.mjs",
     "build:markdown-parsers": "tsup --config tsup.markdown-parsers.config.ts",
     "build:plugin-kit": "tsup src/plugin-kit.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
@@ -133,8 +143,10 @@
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:codegen": "tsup src/codegen.ts --format esm,cjs --minify --dts",
     "build:styles": "node scripts/build-styles.mjs",
-    "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup --config tsup.global.config.ts && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
+    "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" --external @runtypelabs/persona/context-mentions --external @runtypelabs/persona/context-mentions-inline && tsup --config tsup.global.config.ts && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
     "build:webmcp-polyfill": "tsup --config tsup.webmcp-polyfill.config.ts",
+    "build:context-mentions": "tsup --config tsup.context-mentions.config.ts",
+    "build:context-mentions-inline": "tsup --config tsup.context-mentions-inline.config.ts",
     "build:runtype-tts": "tsup --config tsup.runtype-tts.config.ts",
     "build:installer": "tsup src/install.ts --format iife --global-name SiteAgentInstaller --out-dir dist --minify --sourcemap --no-splitting",
     "build:launcher": "tsup src/launcher-global.ts --format iife --global-name AgentWidgetLauncher --minify --sourcemap --splitting false --out-dir dist && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/launcher-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/launcher'+ext);}\"",

package/src/client.test.ts

@@ -4542,3 +4542,72 @@ describe('AgentWidgetClient - Artifact display modes', () => {
     expect(props.markdown).toBe('# Hello');
   });
 });
+
+describe('AgentWidgetClient - mention context', () => {
+  const agentDone = (controller: ReadableStreamDefaultController, encoder: TextEncoder) => {
+    controller.enqueue(encoder.encode(sseEvent('agent_complete', {
+      executionId: 'exec_1',
+      agentId: 'agent_123',
+      success: true,
+      iterations: 1,
+      completedAt: new Date().toISOString(),
+      seq: 1,
+    })));
+    controller.close();
+  };
+
+  const captureContext = () => {
+    let capturedPayload: any = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
+      capturedPayload = JSON.parse(options.body);
+      const encoder = new TextEncoder();
+      return {
+        ok: true,
+        body: new ReadableStream({ start(c) { agentDone(c, encoder); } }),
+      };
+    });
+    return () => capturedPayload;
+  };
+
+  it('attaches the latest user turn mention context under context.mentions', async () => {
+    const get = captureContext();
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000', agentId: 'agent_123' });
+
+    await client.dispatch({
+      messages: [{
+        id: 'u1', role: 'user', content: 'Summarize this',
+        createdAt: '2025-01-01T00:00:00.000Z',
+        mentionContext: { files: { app: { path: 'App.tsx' } } },
+      } as AgentWidgetMessage],
+    }, () => {});
+
+    expect(get().context).toEqual({ mentions: { files: { app: { path: 'App.tsx' } } } });
+  });
+
+  it('does NOT re-attach an older turn mention context on a later send', async () => {
+    const get = captureContext();
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000', agentId: 'agent_123' });
+
+    await client.dispatch({
+      messages: [
+        {
+          id: 'u1', role: 'user', content: 'Summarize this',
+          createdAt: '2025-01-01T00:00:00.000Z',
+          mentionContext: { files: { app: { path: 'App.tsx' } } },
+        } as AgentWidgetMessage,
+        {
+          id: 'a1', role: 'assistant', content: 'Done',
+          createdAt: '2025-01-01T00:00:01.000Z',
+        } as AgentWidgetMessage,
+        {
+          id: 'u2', role: 'user', content: 'Now a plain follow-up',
+          createdAt: '2025-01-01T00:00:02.000Z',
+        } as AgentWidgetMessage,
+      ],
+    }, () => {});
+
+    // The most recent user turn (u2) carried no mentionContext, so the stale
+    // context from u1 must not leak into this request.
+    expect(get().context).toBeUndefined();
+  });
+});

package/src/client.ts

@@ -1182,6 +1182,66 @@ export class AgentWidgetClient {
     });
   }
 
+  /**
+   * The opt-in structured mention channel: the MOST RECENT user turn's
+   * `mentionContext` (set by `session.applyMentionBundle`) namespaced under
+   * `mentions`. Only the latest user message is consulted — otherwise an older
+   * turn's mentions would re-attach to `context.mentions` on every later send.
+   * Returns null when the latest user turn carried no structured mention context.
+   * The default model-visible path (`llmAppend`) already rode into the message's
+   * `llmContent`/`contentParts`, so it needs nothing here.
+   */
+  private latestMentionContext(
+    messages: AgentWidgetMessage[]
+  ): Record<string, unknown> | null {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = messages[i];
+      if (m.role !== "user") continue;
+      // First user message from the end IS the latest user turn: use its
+      // mention context if any, and never look further back.
+      if (m.mentionContext && Object.keys(m.mentionContext).length > 0) {
+        return { mentions: m.mentionContext };
+      }
+      return null;
+    }
+    return null;
+  }
+
+  /**
+   * Aggregate request `context`: merge every context provider's result with the
+   * opt-in mention context from the latest user turn. Returns null when nothing
+   * contributed, so callers can skip setting `payload.context`. Shared by the
+   * agent and flow payload builders.
+   */
+  private async buildContextAggregate(
+    messages: AgentWidgetMessage[]
+  ): Promise<Record<string, unknown> | null> {
+    const contextAggregate: Record<string, unknown> = {};
+    if (this.contextProviders.length) {
+      await Promise.all(
+        this.contextProviders.map(async (provider) => {
+          try {
+            const result = await provider({
+              messages,
+              config: this.config
+            });
+            if (result && typeof result === "object") {
+              Object.assign(contextAggregate, result);
+            }
+          } catch (error) {
+            if (typeof console !== "undefined") {
+              // eslint-disable-next-line no-console
+              console.warn("[AgentWidget] Context provider failed:", error);
+            }
+          }
+        })
+      );
+    }
+    const mentionContext = this.latestMentionContext(messages);
+    if (mentionContext) Object.assign(contextAggregate, mentionContext);
+    return Object.keys(contextAggregate).length ? contextAggregate : null;
+  }
+
   private async buildAgentPayload(
     messages: AgentWidgetMessage[]
   ): Promise<AgentWidgetAgentRequestPayload> {
@@ -1231,32 +1291,9 @@ export class AgentWidgetClient {
       payload.clientTools = clientTools;
     }
 
-    // Add context from providers
-    if (this.contextProviders.length) {
-      const contextAggregate: Record<string, unknown> = {};
-      await Promise.all(
-        this.contextProviders.map(async (provider) => {
-          try {
-            const result = await provider({
-              messages,
-              config: this.config
-            });
-            if (result && typeof result === "object") {
-              Object.assign(contextAggregate, result);
-            }
-          } catch (error) {
-            if (typeof console !== "undefined") {
-              // eslint-disable-next-line no-console
-              console.warn("[AgentWidget] Context provider failed:", error);
-            }
-          }
-        })
-      );
-
-      if (Object.keys(contextAggregate).length) {
-        payload.context = contextAggregate;
-      }
-    }
+    // Add context from providers + opt-in mention context.
+    const contextAggregate = await this.buildContextAggregate(messages);
+    if (contextAggregate) payload.context = contextAggregate;
 
     return payload;
   }
@@ -1311,31 +1348,8 @@ export class AgentWidgetClient {
       payload.clientTools = clientTools;
     }
 
-    if (this.contextProviders.length) {
-      const contextAggregate: Record<string, unknown> = {};
-      await Promise.all(
-        this.contextProviders.map(async (provider) => {
-          try {
-            const result = await provider({
-              messages,
-              config: this.config
-            });
-            if (result && typeof result === "object") {
-              Object.assign(contextAggregate, result);
-            }
-          } catch (error) {
-            if (typeof console !== "undefined") {
-              // eslint-disable-next-line no-console
-              console.warn("[AgentWidget] Context provider failed:", error);
-            }
-          }
-        })
-      );
-
-      if (Object.keys(contextAggregate).length) {
-        payload.context = contextAggregate;
-      }
-    }
+    const contextAggregate = await this.buildContextAggregate(messages);
+    if (contextAggregate) payload.context = contextAggregate;
 
     if (this.requestMiddleware) {
       try {

package/src/components/composer-parts.ts

@@ -341,27 +341,18 @@ export const createAttachmentControls = (config?: AgentWidgetConfig): Attachment
       "aria-label": attachmentsConfig.buttonTooltipText ?? "Attach file",
     },
     style: {
+      // Appearance is themed from the CSS rule for `.persona-attachment-button`
+      // via the `--persona-button-ghost-*` tokens (components.button.ghost).
+      // Only config-driven sizing is inline.
       width: attachIconSize,
       height: attachIconSize,
       minWidth: attachIconSize,
       minHeight: attachIconSize,
       fontSize: "18px",
       lineHeight: "1",
-      backgroundColor: "transparent",
-      color: "var(--persona-primary, #111827)",
-      border: "none",
-      borderRadius: "6px",
-      transition: "background-color 0.15s ease",
     },
   });
 
-  button.addEventListener("mouseenter", () => {
-    button.style.backgroundColor = "var(--persona-palette-colors-black-alpha-50, rgba(0, 0, 0, 0.05))";
-  });
-  button.addEventListener("mouseleave", () => {
-    button.style.backgroundColor = "transparent";
-  });
-
   const attachIconSvg = renderLucideIcon(attachIconName, attachIconSizeNum, "currentColor", 1.5);
   if (attachIconSvg) {
     button.appendChild(attachIconSvg);

package/src/components/context-mention-button.test.ts

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+
+import { describe, it, expect, vi } from "vitest";
+import { createMentionButton } from "./context-mention-button";
+import { renderLucideIcon } from "../utils/icons";
+import type { AgentWidgetContextMentionConfig } from "../types";
+
+// Icon rendered inside the default 40px button: iconSize = round(40 * 0.6) = 24,
+// strokeWidth 1.5 (see createMentionButton). Compare against the registry's own
+// output so the assertion tracks lucide glyph changes instead of hard-coding SVG.
+const refIcon = (name: string) =>
+  renderLucideIcon(name, 24, "currentColor", 1.5)!.innerHTML;
+
+const config = (
+  overrides: Partial<AgentWidgetContextMentionConfig> = {}
+): AgentWidgetContextMentionConfig => ({ enabled: true, sources: [], ...overrides });
+
+describe("createMentionButton", () => {
+  it("invokes onOpen on click and labels itself from config", () => {
+    const onOpen = vi.fn();
+    const { button, wrapper } = createMentionButton({
+      config: config({ buttonTooltipText: "Add context" }),
+      onOpen,
+    });
+    expect(button.getAttribute("aria-label")).toBe("Add context");
+    expect(wrapper.querySelector(".persona-send-button-tooltip")?.textContent).toBe(
+      "Add context"
+    );
+
+    button.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    expect(onOpen).toHaveBeenCalledTimes(1);
+  });
+
+  it("defaults to a '+' add-context icon, not an '@' glyph", () => {
+    const { button } = createMentionButton({ config: config(), onOpen: vi.fn() });
+    const svg = button.querySelector("svg");
+    expect(svg).not.toBeNull();
+    // "@" reads as power-user; the consumer-recognized affordance is "+".
+    expect(svg!.innerHTML).toBe(refIcon("plus"));
+    expect(svg!.innerHTML).not.toBe(refIcon("at-sign"));
+    expect(button.textContent).not.toContain("@");
+  });
+
+  it("honors a buttonIconName override for power-user surfaces", () => {
+    const { button } = createMentionButton({
+      config: config({ buttonIconName: "at-sign" }),
+      onOpen: vi.fn(),
+    });
+    expect(button.querySelector("svg")!.innerHTML).toBe(refIcon("at-sign"));
+  });
+
+  it("stops the click from bubbling so the composer's focus-textarea handler never runs", () => {
+    const parent = document.createElement("form");
+    const parentClick = vi.fn();
+    parent.addEventListener("click", parentClick);
+    document.body.appendChild(parent);
+
+    const { wrapper } = createMentionButton({ config: config(), onOpen: vi.fn() });
+    parent.appendChild(wrapper);
+
+    wrapper
+      .querySelector("button")!
+      .dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+
+    // The button's handler calls stopPropagation, so the parent (which stands in
+    // for the composer form's "click anywhere → focus textarea" listener) is
+    // never reached — the picker's search field keeps focus.
+    expect(parentClick).not.toHaveBeenCalled();
+  });
+});

package/src/components/context-mention-button.ts

@@ -0,0 +1,82 @@
+import { createElement, createNode } from "../utils/dom";
+import { renderLucideIcon } from "../utils/icons";
+import type { AgentWidgetContextMentionConfig } from "../types";
+
+export interface MentionButtonParts {
+  button: HTMLButtonElement;
+  wrapper: HTMLElement;
+}
+
+/**
+ * The visible composer affordance ("add context") — the discoverable entry
+ * point that opens the mention menu. Lives in the CORE bundle (not the lazy
+ * chunk) so the button paints immediately when `contextMentions.enabled`, before
+ * the heavy menu runtime loads on first interaction.
+ *
+ * Styled to match `createAttachmentControls`' icon button for visual parity.
+ */
+export function createMentionButton(opts: {
+  config: AgentWidgetContextMentionConfig;
+  buttonSize?: string;
+  onOpen: () => void;
+}): MentionButtonParts {
+  const { config, onOpen } = opts;
+  const size = opts.buttonSize ?? "40px";
+  const sizeNum = parseFloat(size) || 40;
+  const iconSize = Math.round(sizeNum * 0.6);
+  // Default to a "+" signifier, not an "@" glyph: no major consumer chat app
+  // (ChatGPT, Claude, Gemini, Perplexity) puts a literal "@" button in the
+  // composer — "@" is a typed power-user accelerator, while "+"/"add context"
+  // is the recognized consumer affordance. Override via `buttonIconName`
+  // (e.g. "at-sign") on a power-user surface.
+  const iconName = config.buttonIconName ?? "plus";
+  const tooltipText = config.buttonTooltipText ?? "Add context";
+
+  const wrapper = createElement("div", "persona-send-button-wrapper");
+  const button = createNode("button", {
+    className:
+      "persona-rounded-button persona-flex persona-items-center persona-justify-center disabled:persona-opacity-50 persona-cursor-pointer persona-mention-button",
+    attrs: {
+      type: "button",
+      "data-persona-composer-mention-button": "",
+      "aria-label": tooltipText,
+      "aria-haspopup": "listbox",
+      // Reflects the picker's open state: the orchestrator flips aria-expanded
+      // and adds aria-controls (the menu's listbox id) via `onPickerOpenChange`
+      // when this button opens/closes the picker. Starts collapsed.
+      "aria-expanded": "false",
+    },
+    style: {
+      // Appearance (bg / fg / border / radius / hover) is themed from the CSS
+      // rule for `.persona-mention-button` via the `--persona-button-ghost-*`
+      // tokens (components.button.ghost). Only config-driven sizing is inline.
+      width: size,
+      height: size,
+      minWidth: size,
+      minHeight: size,
+      fontSize: "18px",
+      lineHeight: "1",
+    },
+  }) as HTMLButtonElement;
+
+  const icon = renderLucideIcon(iconName, iconSize, "currentColor", 1.5);
+  if (icon) button.appendChild(icon);
+  else button.textContent = "+";
+
+  button.addEventListener("click", (e) => {
+    e.preventDefault();
+    // Stop the click from bubbling to the composer form's "click anywhere →
+    // focus textarea" handler, which would otherwise steal focus from the
+    // picker's search field the moment it opens.
+    e.stopPropagation();
+    onOpen();
+  });
+
+  wrapper.appendChild(button);
+
+  const tooltip = createElement("div", "persona-send-button-tooltip");
+  tooltip.textContent = tooltipText;
+  wrapper.appendChild(tooltip);
+
+  return { button, wrapper };
+}

package/src/components/context-mention-chip.ts

@@ -0,0 +1,134 @@
+import { createElement, createNode } from "../utils/dom";
+import { renderLucideIcon } from "../utils/icons";
+import type {
+  AgentWidgetContextMentionConfig,
+  AgentWidgetContextMentionPayload,
+  AgentWidgetContextMentionRef,
+} from "../types";
+
+export type MentionChipStatus = "resolving" | "ready" | "error";
+
+export interface MentionChipParts {
+  el: HTMLElement;
+  /** Update lifecycle state; `payload` is forwarded to `renderMentionChip` once resolved. */
+  setStatus: (
+    status: MentionChipStatus,
+    payload?: AgentWidgetContextMentionPayload
+  ) => void;
+}
+
+/**
+ * A single compact pill chip (icon + label + ×, ~26px) for the composer context
+ * row. Mirrors the attachment chip's remove affordance but is a text pill, not a
+ * 48×48 thumbnail. Honors `config.renderMentionChip` when provided.
+ */
+export function createMentionChip(opts: {
+  ref: AgentWidgetContextMentionRef;
+  config: AgentWidgetContextMentionConfig;
+  onRemove: () => void;
+}): MentionChipParts {
+  const { ref, config, onRemove } = opts;
+
+  if (config.renderMentionChip) {
+    // Mid-level override: the host owns the markup. Status (and the resolved
+    // payload, once available) is reflected by re-invoking the renderer.
+    let status: MentionChipStatus = "resolving";
+    let payload: AgentWidgetContextMentionPayload | undefined;
+    let el = config.renderMentionChip({ ref, status, payload, remove: onRemove });
+    const setStatus = (
+      next: MentionChipStatus,
+      nextPayload?: AgentWidgetContextMentionPayload
+    ) => {
+      if (next === status && nextPayload === payload) return;
+      status = next;
+      payload = nextPayload;
+      const replacement = config.renderMentionChip!({
+        ref,
+        status,
+        payload,
+        remove: onRemove,
+      });
+      el.replaceWith(replacement);
+      el = replacement;
+    };
+    // Getter, not a snapshot: setStatus swaps the node, and the manager's
+    // remove()/clear() must target the live element, not the detached original.
+    return {
+      get el() {
+        return el;
+      },
+      setStatus,
+    };
+  }
+
+  const iconName = ref.iconName ?? config.chipIconName ?? "at-sign";
+
+  const chip = createNode("div", {
+    className: "persona-mention-chip",
+    attrs: {
+      "data-persona-mention-chip": "",
+      "data-status": "resolving",
+      // Full label on hover, since the pill truncates long labels with ellipsis.
+      title: ref.label,
+    },
+  });
+
+  const iconHost = createElement("span", "persona-mention-chip-icon");
+  const setIcon = (name: string) => {
+    iconHost.replaceChildren();
+    const svg = renderLucideIcon(name, 13, "currentColor", 2);
+    if (svg) iconHost.appendChild(svg);
+  };
+  setIcon(iconName);
+
+  // The spinner shown while the mention resolves; swapped for the icon on ready.
+  const spinner = createElement("span", "persona-mention-chip-spinner");
+
+  const label = createNode("span", {
+    className: "persona-mention-chip-label",
+    text: ref.label,
+  });
+
+  const removeBtn = createNode("button", {
+    className: "persona-mention-chip-remove",
+    attrs: {
+      type: "button",
+      "aria-label": `Remove ${ref.label} context`,
+    },
+  }) as HTMLButtonElement;
+  const x = renderLucideIcon("x", 11, "currentColor", 2.5);
+  if (x) removeBtn.appendChild(x);
+  else removeBtn.textContent = "×";
+  removeBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    onRemove();
+  });
+
+  chip.appendChild(spinner);
+  chip.appendChild(label);
+  chip.appendChild(removeBtn);
+
+  const setStatus = (status: MentionChipStatus) => {
+    chip.setAttribute("data-status", status);
+    if (status === "resolving") {
+      if (spinner.parentNode !== chip) chip.insertBefore(spinner, label);
+      if (iconHost.parentNode === chip) iconHost.remove();
+      chip.setAttribute("title", ref.label);
+    } else {
+      if (spinner.parentNode === chip) spinner.remove();
+      if (iconHost.parentNode !== chip) chip.insertBefore(iconHost, label);
+      if (status === "error") {
+        // Error is not color-only: swap to an alert icon and explain in the
+        // hover title (and the aria-label reflects it via the title too).
+        setIcon("triangle-alert");
+        chip.setAttribute("title", `Couldn't add ${ref.label} to context`);
+      } else {
+        setIcon(iconName);
+        chip.setAttribute("title", ref.label);
+      }
+    }
+  };
+
+  return { el: chip, setStatus };
+}