@runtypelabs/persona 3.29.1 → 3.31.0

package/src/utils/auto-follow.test.ts

@@ -1,8 +1,11 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  computeAnchorScrollState,
+  computeShrunkSpacerHeight,
   createFollowStateController,
   getScrollBottomOffset,
+  hasSelectionWithin,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
@@ -90,6 +93,94 @@ describe("auto-follow utilities", () => {
     expect(resume.action).toBe("resume");
   });
 
+  it("detects an active selection touching the container", () => {
+    const inside = { name: "inside" } as unknown as Node;
+    const outside = { name: "outside" } as unknown as Node;
+    const container = {
+      contains: (node: Node | null) => node === inside
+    };
+
+    expect(hasSelectionWithin(null, container)).toBe(false);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: true, anchorNode: inside, focusNode: inside },
+        container
+      )
+    ).toBe(false);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: false, anchorNode: outside, focusNode: outside },
+        container
+      )
+    ).toBe(false);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: false, anchorNode: inside, focusNode: outside },
+        container
+      )
+    ).toBe(true);
+    expect(
+      hasSelectionWithin(
+        { isCollapsed: false, anchorNode: outside, focusNode: inside },
+        container
+      )
+    ).toBe(true);
+  });
+
+  it("computes anchor-top scroll geometry", () => {
+    // Anchored message deep in the transcript: spacer fills the shortfall so
+    // the target position is reachable.
+    expect(
+      computeAnchorScrollState({
+        anchorOffsetTop: 700,
+        topOffset: 16,
+        viewportHeight: 400,
+        contentHeight: 1000
+      })
+    ).toEqual({ targetScrollTop: 684, spacerHeight: 84 });
+
+    // Message near the top of the transcript: target clamps to 0.
+    expect(
+      computeAnchorScrollState({
+        anchorOffsetTop: 10,
+        topOffset: 16,
+        viewportHeight: 400,
+        contentHeight: 1000
+      }).targetScrollTop
+    ).toBe(0);
+
+    // Already enough content below: no spacer needed.
+    expect(
+      computeAnchorScrollState({
+        anchorOffsetTop: 500,
+        topOffset: 16,
+        viewportHeight: 400,
+        contentHeight: 2000
+      }).spacerHeight
+    ).toBe(0);
+  });
+
+  it("shrinks the anchor spacer as content grows, never below zero or above initial", () => {
+    const base = {
+      initialSpacerHeight: 100,
+      contentHeightAtAnchor: 1000
+    };
+
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 1000 })
+    ).toBe(100);
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 1040 })
+    ).toBe(60);
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 1500 })
+    ).toBe(0);
+    // Content shrank (e.g. a collapsed tool row): spacer never grows back.
+    expect(
+      computeShrunkSpacerHeight({ ...base, currentContentHeight: 900 })
+    ).toBe(100);
+  });
+
   it("resolves wheel intent for pause and resume", () => {
     expect(
       resolveFollowStateFromWheel({

package/src/utils/auto-follow.ts

@@ -110,3 +110,71 @@ export function resolveFollowStateFromWheel(
 
   return "none";
 }
+
+export type SelectionLike = Pick<Selection, "isCollapsed"> & {
+  anchorNode: Node | null;
+  focusNode: Node | null;
+};
+
+/**
+ * True when the user has a non-collapsed text selection that touches the
+ * given container. Used to pause auto-follow while the user is selecting
+ * transcript text, so the streaming scroll doesn't drag content out from
+ * under an in-progress drag-selection.
+ */
+export function hasSelectionWithin(
+  selection: SelectionLike | null,
+  container: Pick<Node, "contains">
+): boolean {
+  if (!selection || selection.isCollapsed) return false;
+  return (
+    container.contains(selection.anchorNode) ||
+    container.contains(selection.focusNode)
+  );
+}
+
+export type AnchorScrollInput = {
+  /** Top of the anchored user message, relative to the scroll content. */
+  anchorOffsetTop: number;
+  /** Desired gap kept between the anchored message and the viewport top. */
+  topOffset: number;
+  /** clientHeight of the scroll container. */
+  viewportHeight: number;
+  /** scrollHeight of the scroll container, excluding any anchor spacer. */
+  contentHeight: number;
+};
+
+/**
+ * Geometry for anchor-top ("pin the sent user message near the viewport
+ * top") scrolling. The spacer height is the extra scrollable room needed so
+ * the target scroll position is reachable before the streamed response has
+ * grown tall enough to provide it naturally.
+ */
+export function computeAnchorScrollState(input: AnchorScrollInput): {
+  targetScrollTop: number;
+  spacerHeight: number;
+} {
+  const targetScrollTop = Math.max(0, input.anchorOffsetTop - input.topOffset);
+  const spacerHeight = Math.max(
+    0,
+    targetScrollTop + input.viewportHeight - input.contentHeight
+  );
+  return { targetScrollTop, spacerHeight };
+}
+
+/**
+ * Shrink-only spacer update: as streamed content grows beneath the anchored
+ * message, the spacer gives back exactly that much room so total scroll
+ * height stays constant and nothing jumps. Never grows after anchoring.
+ */
+export function computeShrunkSpacerHeight(input: {
+  initialSpacerHeight: number;
+  contentHeightAtAnchor: number;
+  currentContentHeight: number;
+}): number {
+  const growth = Math.max(
+    0,
+    input.currentContentHeight - input.contentHeightAtAnchor
+  );
+  return Math.max(0, input.initialSpacerHeight - growth);
+}

package/src/utils/theme.test.ts

@@ -288,7 +288,7 @@ describe('theme utils', () => {
     );
   });
 
-  it('lets config.toolCall.shadow override theme tool bubble shadow on the root element', () => {
+  it('drives --persona-tool-bubble-shadow from the theme token (config.toolCall.shadow is applied inline on the bubble, not the root var)', () => {
     const el = document.createElement('div');
     applyThemeVariables(el, {
       colorScheme: 'light',
@@ -297,8 +297,12 @@ describe('theme utils', () => {
           toolBubble: { shadow: '0 1px 2px rgba(255,0,0,0.5)' },
         },
       },
+      // config.toolCall.shadow no longer rewrites the root variable — the
+      // override is applied inline by createToolBubble (see tool-bubble tests).
       toolCall: { shadow: 'none' },
     });
-    expect(el.style.getPropertyValue('--persona-tool-bubble-shadow').trim()).toBe('none');
+    expect(el.style.getPropertyValue('--persona-tool-bubble-shadow').trim()).toBe(
+      '0 1px 2px rgba(255,0,0,0.5)'
+    );
   });
 });

package/src/utils/theme.ts

@@ -194,14 +194,6 @@ export const applyThemeVariables = (
   for (const [name, value] of Object.entries(cssVars)) {
     element.style.setProperty(name, value);
   }
-
-  const toolCallShadow = (config as AgentWidgetConfig | undefined)?.toolCall?.shadow;
-  if (toolCallShadow !== undefined) {
-    element.style.setProperty(
-      '--persona-tool-bubble-shadow',
-      toolCallShadow.trim() === '' ? 'none' : toolCallShadow
-    );
-  }
 };
 
 export const createThemeObserver = (

package/src/utils/tokens.ts

@@ -333,7 +333,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     shadow: 'palette.shadows.sm',
   },
   composer: {
-    shadow: 'none',
+    shadow: 'palette.shadows.none',
   },
   markdown: {
     inlineCode: {
@@ -389,6 +389,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       background: 'palette.colors.warning.50',
       border: 'palette.colors.warning.200',
       text: 'palette.colors.gray.900',
+      shadow: '0 5px 15px rgba(15, 23, 42, 0.08)',
     },
     approve: {
       background: 'palette.colors.success.500',
@@ -683,6 +684,7 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   cssVars['--persona-approval-bg'] = cssVars['--persona-components-approval-requested-background'] ?? cssVars['--persona-palette-colors-warning-50'];
   cssVars['--persona-approval-border'] = cssVars['--persona-components-approval-requested-border'] ?? cssVars['--persona-palette-colors-warning-200'];
   cssVars['--persona-approval-text'] = cssVars['--persona-components-approval-requested-text'] ?? cssVars['--persona-palette-colors-gray-900'];
+  cssVars['--persona-approval-shadow'] = cssVars['--persona-components-approval-requested-shadow'] ?? '0 5px 15px rgba(15, 23, 42, 0.08)';
   cssVars['--persona-approval-approve-bg'] = cssVars['--persona-components-approval-approve-background'] ?? cssVars['--persona-palette-colors-success-500'];
   cssVars['--persona-approval-deny-bg'] = cssVars['--persona-components-approval-deny-background'] ?? cssVars['--persona-palette-colors-error-500'];
 
@@ -737,6 +739,9 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-panel-shadow'] ??
     cssVars['--persona-palette-shadows-xl'] ??
     '0 25px 50px -12px rgba(0, 0, 0, 0.25)';
+  cssVars['--persona-launcher-shadow'] =
+    cssVars['--persona-components-launcher-shadow'] ??
+    '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)';
   cssVars['--persona-input-radius'] =
     cssVars['--persona-components-input-borderRadius'] ??
     cssVars['--persona-radius-lg'] ??

package/src/webmcp-bridge.test.ts

@@ -27,6 +27,7 @@ vi.mock("@mcp-b/webmcp-polyfill", () => ({
 // Import AFTER vi.mock so the bridge's dynamic import resolves to the mock.
 import {
   WebMcpBridge,
+  getWebMcpToolDisplayTitle,
   isWebMcpToolName,
   stripWebMcpPrefix,
   computeClientToolsFingerprint,
@@ -39,6 +40,7 @@ type MockTool = {
   name: string;
   description?: string;
   inputSchema?: object;
+  title?: string;
   execute: (args: Record<string, unknown>, client: MockClient) => unknown;
 };
 
@@ -47,10 +49,13 @@ const registry: { tools: MockTool[] } = { tools: [] };
 /** A fake `document.modelContext` exposing the strict consumer surface. */
 const makeModelContext = () => ({
   async getTools() {
+    // Mirrors the real polyfill's getRegisteredToolInfos(): `title` is always
+    // present, "" when the tool didn't declare one; annotations are absent.
     return registry.tools.map((t) => ({
       name: t.name,
       description: t.description ?? `mock ${t.name}`,
       inputSchema: JSON.stringify(t.inputSchema ?? { type: "object" }),
+      title: t.title ?? "",
     }));
   },
   async executeTool(
@@ -199,6 +204,67 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
   });
 });
 
+describe("WebMCP display titles", () => {
+  it("records declared titles on snapshot and exposes them via getWebMcpToolDisplayTitle", async () => {
+    registry.tools = [
+      fakeTool({ name: "add_to_cart", title: "Add to Cart" }),
+      fakeTool({ name: "search_products" }),
+    ];
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBe("Add to Cart");
+    expect(getWebMcpToolDisplayTitle("webmcp:add_to_cart")).toBe("Add to Cart");
+    expect(getWebMcpToolDisplayTitle("search_products")).toBeUndefined();
+  });
+
+  it("evicts a stale title when the tool re-registers without one", async () => {
+    registry.tools = [fakeTool({ name: "add_to_cart", title: "Add to Cart" })];
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBe("Add to Cart");
+
+    registry.tools = [fakeTool({ name: "add_to_cart" })];
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBeUndefined();
+  });
+
+  it("evicts the title when the tool is removed from the registry entirely", async () => {
+    registry.tools = [
+      fakeTool({ name: "add_to_cart", title: "Add to Cart" }),
+      fakeTool({ name: "search_products", title: "Search the catalog" }),
+    ];
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBe("Add to Cart");
+
+    registry.tools = [fakeTool({ name: "search_products", title: "Search the catalog" })];
+    await bridge.snapshotForDispatch();
+    expect(getWebMcpToolDisplayTitle("add_to_cart")).toBeUndefined();
+    expect(getWebMcpToolDisplayTitle("search_products")).toBe("Search the catalog");
+  });
+
+  it("passes the declared title to the confirm gate", async () => {
+    registry.tools = [fakeTool({ name: "add_to_cart", title: "Add to Cart" })];
+    const onConfirm = vi.fn(async () => true);
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    const r = await bridge.executeToolCall("webmcp:add_to_cart", {});
+    expect(r.isError).toBeFalsy();
+    expect(onConfirm).toHaveBeenCalledWith(
+      expect.objectContaining({ toolName: "add_to_cart", title: "Add to Cart" })
+    );
+  });
+
+  it("omits title from the confirm gate when the tool didn't declare one", async () => {
+    registry.tools = [fakeTool({ name: "add_to_cart" })];
+    const onConfirm = vi.fn(async () => true);
+    const bridge = new WebMcpBridge({ enabled: true, onConfirm });
+    await bridge.executeToolCall("webmcp:add_to_cart", {});
+    expect(onConfirm).toHaveBeenCalledWith(
+      expect.not.objectContaining({ title: expect.anything() })
+    );
+  });
+});
+
 describe("WebMcpBridge.executeToolCall", () => {
   it("returns isError when WebMCP is not enabled", async () => {
     const bridge = new WebMcpBridge({} as AgentWidgetWebMcpConfig);

package/src/webmcp-bridge.ts

@@ -66,6 +66,14 @@ interface ModelContextToolInfo {
   description: string;
   /** JSON-encoded JSON Schema for the tool's input. */
   inputSchema?: string;
+  /**
+   * Display title declared on the tool (`ToolDescriptor.title` in the WebMCP
+   * spec). The polyfill returns `""` when the tool didn't declare one. Note:
+   * `annotations` (incl. the legacy `annotations.title`) are NOT exposed on
+   * this strict consumer surface — top-level `title` is the only display-name
+   * channel available to us.
+   */
+  title?: string;
 }
 
 interface ModelContextCoreLike {
@@ -77,6 +85,43 @@ interface ModelContextCoreLike {
   ): Promise<string | null>;
 }
 
+/**
+ * Page-global map of bare tool name → declared display title
+ * (`ToolDescriptor.title`). `document.modelContext` is page-global, so a
+ * single map shared across widget/bridge instances is semantically correct.
+ * Refreshed on every registry read (`snapshotForDispatch` / `executeToolCall`)
+ * and consumed by the approval bubble's summary line via
+ * `getWebMcpToolDisplayTitle`.
+ */
+const webMcpToolDisplayTitles = new Map<string, string>();
+
+/**
+ * Record declared display titles from a fresh `getTools()` read. The map is
+ * rebuilt from scratch — callers always pass the FULL registry snapshot — so
+ * a tool that unregistered or dropped its title can't leave a stale label
+ * behind. Exported for tests; production callers are the bridge's registry
+ * reads.
+ */
+export const recordWebMcpToolDisplayTitles = (
+  infos: ModelContextToolInfo[],
+): void => {
+  webMcpToolDisplayTitles.clear();
+  for (const info of infos) {
+    const title = info.title?.trim();
+    if (title) webMcpToolDisplayTitles.set(info.name, title);
+  }
+};
+
+/**
+ * Look up the display title a page tool declared via the WebMCP spec's
+ * `ToolDescriptor.title`. Accepts wire (`webmcp:add_to_cart`) or bare
+ * (`add_to_cart`) names. Returns `undefined` when the tool didn't declare
+ * one (callers fall back to humanizing the tool name).
+ */
+export const getWebMcpToolDisplayTitle = (
+  toolName: string,
+): string | undefined => webMcpToolDisplayTitles.get(stripWebMcpPrefix(toolName));
+
 const log = {
   warn(message: string, ...rest: unknown[]): void {
     if (typeof console !== "undefined" && typeof console.warn === "function") {
@@ -220,6 +265,7 @@ export class WebMcpBridge {
       log.warn("getTools() threw — shipping an empty WebMCP snapshot.", err);
       return [];
     }
+    recordWebMcpToolDisplayTitles(infos);
 
     const pageOrigin = typeof location !== "undefined" ? location.origin : "";
 
@@ -295,6 +341,7 @@ export class WebMcpBridge {
       const message = err instanceof Error ? err.message : String(err);
       return errorResult(`Failed to read WebMCP registry: ${message}`);
     }
+    recordWebMcpToolDisplayTitles(infos);
     const info = infos.find((candidate) => candidate.name === bareName);
 
     if (!info) {
@@ -323,10 +370,12 @@ export class WebMcpBridge {
 
     // Confirm-by-default gate. Every `webmcp:*` call routes through here,
     // regardless of `annotations.readOnlyHint`.
+    const displayTitle = getWebMcpToolDisplayTitle(bareName);
     const gateInfo: WebMcpConfirmInfo = {
       toolName: bareName,
       args,
       description: info.description,
+      ...(displayTitle ? { title: displayTitle } : {}),
       reason: "gate",
     };
     if (!(await this.requestConfirm(gateInfo))) {