@runtypelabs/persona 4.8.0 → 4.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.8.0",
+  "version": "4.10.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/artifact-pane.test.ts

@@ -436,6 +436,37 @@ describe("artifact-pane expand toggle", () => {
     expect(btn.title).toBe("Expand artifacts panel");
     expect(btn.querySelector("svg")).toBeTruthy();
   });
+
+  it("resets content scroll after expanded-state transitions only", () => {
+    const frames: Array<(time: number) => void> = [];
+    vi.stubGlobal("requestAnimationFrame", (callback: (time: number) => void) => {
+      frames.push(callback);
+      return frames.length;
+    });
+    try {
+      const pane = createArtifactPane(makeExpandConfig(), { onSelect: () => {} });
+      pane.update({ artifacts: [fileRecord()], selectedId: "a1" });
+      const content = contentEl(pane);
+
+      content.scrollLeft = 80;
+      pane.setExpanded(true);
+      expect(frames).toHaveLength(1);
+      frames.shift()?.(0);
+      expect(content.scrollLeft).toBe(0);
+
+      content.scrollLeft = 80;
+      pane.setExpanded(true);
+      expect(frames).toHaveLength(0);
+      expect(content.scrollLeft).toBe(80);
+
+      pane.setExpanded(false);
+      expect(frames).toHaveLength(1);
+      frames.shift()?.(0);
+      expect(content.scrollLeft).toBe(0);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
 });
 
 const makeCopyButtonConfig = (): AgentWidgetConfig =>
@@ -698,6 +729,22 @@ describe("artifact-pane tabs", () => {
       Element.prototype.scrollIntoView = orig;
     }
   });
+
+  it("resets content scroll only when the selected artifact changes", () => {
+    const pane = createArtifactPane(makeConfig(), { onSelect: () => {} });
+    const [a1, a2] = twoFileRecords();
+
+    pane.update({ artifacts: [a1], selectedId: "a1" });
+    const content = contentEl(pane);
+    content.scrollLeft = 80;
+
+    pane.update({ artifacts: [a1, a2], selectedId: "a2" });
+    expect(content.scrollLeft).toBe(0);
+
+    content.scrollLeft = 80;
+    pane.update({ artifacts: [a1, a2], selectedId: "a2" });
+    expect(content.scrollLeft).toBe(80);
+  });
 });
 
 const listIn = (pane: ReturnType<typeof createArtifactPane>): HTMLElement =>

package/src/components/artifact-pane.ts

@@ -421,6 +421,21 @@ export function createArtifactPane(
     "div",
     "persona-artifact-content persona-flex-1 persona-min-h-0 persona-overflow-y-auto persona-p-3"
   );
+  const resetContentInlineScroll = () => {
+    // The shared body survives artifact and layout changes. Always return it to
+    // inline start at those lifecycle boundaries so a wide previous preview
+    // cannot leave the next one clipped by a stale horizontal offset.
+    content.scrollLeft = 0;
+  };
+  const scheduleContentInlineScrollReset = () => {
+    // ui.ts applies the expanded root class immediately before setExpanded().
+    // Wait one frame so the new pane width has taken effect before resetting.
+    if (typeof requestAnimationFrame === "function") {
+      requestAnimationFrame(resetContentInlineScroll);
+    } else {
+      setTimeout(resetContentInlineScroll, 0);
+    }
+  };
   if (panePadding) {
     for (const el of [list, customBarMount]) {
       el.style.paddingLeft = panePadding;
@@ -437,6 +452,7 @@ export function createArtifactPane(
   let records: PersonaArtifactRecord[] = [];
   let selectedId: string | null = null;
   let mobileOpen = false;
+  let expandedState = false;
   // Lazy-render gate. `visible` reflects the host's explicit setVisible() signal
   // (never inferred from layout/offsetParent, so class-hiding + jsdom behave the
   // same). It defaults to true so the pane renders eagerly when constructed
@@ -682,11 +698,13 @@ export function createArtifactPane(
     element: shell,
     backdrop,
     update(state: { artifacts: PersonaArtifactRecord[]; selectedId: string | null }) {
-      records = state.artifacts;
-      selectedId =
+      const nextSelectedId =
         state.selectedId ??
         state.artifacts[state.artifacts.length - 1]?.id ??
         null;
+      const selectionChanged = nextSelectedId !== selectedId;
+      records = state.artifacts;
+      selectedId = nextSelectedId;
       if (records.length > 0) {
         mobileOpen = true;
       }
@@ -696,6 +714,7 @@ export function createArtifactPane(
       // executing artifact scripts twice. Defer the whole render() to reveal.
       dirty = true;
       if (visible) flush();
+      if (selectionChanged) resetContentInlineScroll();
     },
     setMobileOpen(open: boolean) {
       mobileOpen = open;
@@ -707,6 +726,10 @@ export function createArtifactPane(
       }
     },
     setExpanded(expanded: boolean) {
+      if (expanded !== expandedState) {
+        expandedState = expanded;
+        scheduleContentInlineScrollReset();
+      }
       // Swap the icon (the state signal) and update the accessible label. We
       // deliberately avoid aria-pressed here: the icon-btn [aria-pressed] CSS
       // would add unwanted active styling.

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