@runtypelabs/persona 3.29.0 → 3.30.0

package/src/ui.approval-plugin.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import type { AgentWidgetPlugin } from "./plugins/types";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const injectApproval = (
+  controller: ReturnType<typeof createAgentExperience>,
+  {
+    id = "appr-1",
+    status = "pending" as "pending" | "approved" | "denied",
+  } = {}
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id: `approval-${id}`,
+      role: "assistant",
+      content: "",
+      createdAt: "2026-04-24T00:00:00.000Z",
+      streaming: false,
+      variant: "approval",
+      approval: {
+        id,
+        status,
+        agentId: "agent_1",
+        executionId: "exec_1",
+        toolName: "Search documentation",
+        description: "Search the docs",
+        parameters: { query: "approval theming" },
+      },
+    },
+  });
+};
+
+const injectNoise = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id = "noise"
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "user",
+      content: "noise",
+      createdAt: "2026-04-26T00:00:00.000Z",
+      streaming: false,
+    },
+  });
+};
+
+describe("renderApproval plugin hook", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("renders a plugin-returned element in place of the built-in bubble", () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "custom-approval",
+      renderApproval: ({ message }) => {
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "custom-approval");
+        root.textContent = message.approval?.toolName ?? "";
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    injectApproval(controller);
+
+    const custom = mount.querySelector('[data-test-id="custom-approval"]');
+    expect(custom).not.toBeNull();
+    expect(custom?.textContent).toBe("Search documentation");
+    // The built-in bubble must NOT also render.
+    expect(mount.querySelector(".persona-approval-bubble")).toBeNull();
+  });
+
+  it("preserves plugin click listeners (e.g. an accordion) across morph re-renders", () => {
+    const toggleSpy = vi.fn();
+    const plugin: AgentWidgetPlugin = {
+      id: "accordion-approval",
+      renderApproval: ({ message }) => {
+        if (message.approval?.status !== "pending") return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "appr-root");
+        const head = document.createElement("button");
+        head.type = "button";
+        head.setAttribute("data-test-id", "appr-head");
+        head.setAttribute("data-action", "toggle");
+        const params = document.createElement("pre");
+        params.setAttribute("data-test-id", "appr-params");
+        // Single delegated listener at the root — the recommended pattern.
+        root.addEventListener("click", (e) => {
+          const target = (e.target as HTMLElement).closest("[data-action]");
+          if (target?.getAttribute("data-action") === "toggle") {
+            params.hidden = !params.hidden;
+            toggleSpy();
+          }
+        });
+        root.append(head, params);
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    injectApproval(controller);
+    // Force a re-render — the scenario where innerHTML morph drops listeners
+    // on a freshly-built plugin element unless it's hydrated post-morph.
+    injectNoise(controller);
+
+    const head = mount.querySelector<HTMLButtonElement>('[data-test-id="appr-head"]');
+    const params = mount.querySelector<HTMLPreElement>('[data-test-id="appr-params"]');
+    expect(head).not.toBeNull();
+    expect(params).not.toBeNull();
+
+    head!.click();
+    expect(toggleSpy).toHaveBeenCalledTimes(1);
+    expect(params!.hidden).toBe(true);
+  });
+
+  it("resolves via the approve callback (with the remember option)", async () => {
+    const onDecision = vi.fn(async () => {});
+    const plugin: AgentWidgetPlugin = {
+      id: "approve-callback",
+      renderApproval: ({ message, approve }) => {
+        if (message.approval?.status !== "pending") return null;
+        const root = document.createElement("div");
+        const btn = document.createElement("button");
+        btn.setAttribute("data-test-id", "always-allow");
+        btn.addEventListener("click", () => approve({ remember: true }));
+        root.appendChild(btn);
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      approval: { onDecision },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    injectApproval(controller);
+    injectNoise(controller);
+
+    const btn = mount.querySelector<HTMLButtonElement>('[data-test-id="always-allow"]');
+    expect(btn).not.toBeNull();
+    btn!.click();
+
+    await Promise.resolve();
+    expect(onDecision).toHaveBeenCalledWith(
+      expect.objectContaining({ toolName: "Search documentation" }),
+      "approved",
+      { remember: true }
+    );
+  });
+
+  it("falls through to the built-in bubble when the plugin returns null (resolved state)", () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "pending-only-approval",
+      renderApproval: ({ message }) => {
+        if (message.approval?.status !== "pending") return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "custom-pending");
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    // Inject directly in the resolved state — plugin opts out, built-in renders.
+    injectApproval(controller, { status: "approved" });
+
+    expect(mount.querySelector('[data-test-id="custom-pending"]')).toBeNull();
+    expect(mount.querySelector(".persona-approval-bubble")).not.toBeNull();
+  });
+});

package/src/ui.ts

@@ -3,6 +3,7 @@ import { resolveSanitizer } from "./utils/sanitize";
 import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
 import {
   AgentWidgetConfig,
+  AgentWidgetApprovalDecisionOptions,
   AgentWidgetMessage,
   AgentWidgetEvent,
   AgentWidgetStorageAdapter,
@@ -85,7 +86,7 @@ import {
   setCurrentAnswer,
 } from "./components/ask-user-question-bubble";
 import { formatElapsedMs } from "./utils/formatting";
-import { createApprovalBubble } from "./components/approval-bubble";
+import { approvalDetailsExpansionState, createApprovalBubble, updateApprovalDetailsUI } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
 import { EventStreamStore } from "./utils/event-stream-store";
@@ -375,8 +376,14 @@ type Controller = {
    * Programmatically resolve a pending approval.
    * @param approvalId - The approval ID to resolve
    * @param decision - "approved" or "denied"
+   * @param options - Optional decision context (e.g. `{ remember: true }`),
+   *   forwarded to `config.approval.onDecision`.
    */
-  resolveApproval: (approvalId: string, decision: 'approved' | 'denied') => Promise<void>;
+  resolveApproval: (
+    approvalId: string,
+    decision: 'approved' | 'denied',
+    options?: AgentWidgetApprovalDecisionOptions
+  ) => Promise<void>;
 };
 
 const buildPostprocessor = (
@@ -1218,7 +1225,7 @@ export const createAgentExperience = (
     if (!headerButton) return;
     
     // Find the parent bubble element
-    const bubble = headerButton.closest('.persona-reasoning-bubble, .persona-tool-bubble') as HTMLElement;
+    const bubble = headerButton.closest('.persona-reasoning-bubble, .persona-tool-bubble, .persona-approval-bubble') as HTMLElement;
     if (!bubble) return;
     
     // Get message ID from bubble
@@ -1242,6 +1249,12 @@ export const createAgentExperience = (
         toolExpansionState.add(messageId);
       }
       updateToolBubbleUI(messageId, bubble, config);
+    } else if (bubbleType === 'approval') {
+      const approvalConfig = config.approval !== false ? config.approval : undefined;
+      const defaultExpanded = (approvalConfig?.detailsDisplay ?? 'collapsed') === 'expanded';
+      const expanded = approvalDetailsExpansionState.get(messageId) ?? defaultExpanded;
+      approvalDetailsExpansionState.set(messageId, !expanded);
+      updateApprovalDetailsUI(messageId, bubble, config);
     }
     // Invalidate cached wrapper so next render rebuilds with current expansion state
     messageCache.delete(messageId);
@@ -2599,6 +2612,13 @@ export const createAgentExperience = (
   // expensive rebuild on fingerprint change so user state inside the rendered
   // component (e.g. partially-filled form inputs) is not wiped on every pass.
   const lastComponentDirectiveFingerprint = new Map<string, string>();
+  // Same idea for plugin-rendered approval bubbles (`renderApproval`). The
+  // custom element is injected into the live DOM post-morph so its event
+  // listeners (Approve/Deny, an expandable parameters accordion, etc.) survive;
+  // this map gates the rebuild on fingerprint change so interactive state (e.g.
+  // a collapsed accordion) is not reset on every pass while the approval is
+  // pending.
+  const lastApprovalBubbleFingerprint = new Map<string, string>();
   let configVersion = 0;
   const autoFollow = createFollowStateController();
   let lastScrollTop = 0;
@@ -2977,10 +2997,26 @@ export const createAgentExperience = (
     const componentDirectiveHydrate: ComponentDirectiveHydrate[] = [];
     const componentStreamingEnabled = config.enableComponentStreaming !== false;
 
+    // Plugin-rendered approval bubbles use the same stub-and-hydrate pattern:
+    // `renderApproval` may attach listeners (the built-in bubble resolves via
+    // delegation on `messagesWrapper`, but a custom element owns its own
+    // interactivity), and idiomorph imports nodes via `document.importNode`,
+    // which strips them. So we build the live element, append a stub during
+    // morph, and inject the live element afterward.
+    const hasApprovalPlugin = plugins.some((p) => p.renderApproval) && config.approval !== false;
+    type ApprovalPluginHydrate = {
+      messageId: string;
+      fingerprint: string;
+      bubble: HTMLElement | null;
+    };
+    const approvalPluginHydrate: ApprovalPluginHydrate[] = [];
+
     messages.forEach((message) => {
       activeMessageIds.add(message.id);
 
       const askWithPlugin = hasAskPlugin && isAskUserQuestionMessage(message);
+      const approvalWithPlugin =
+        hasApprovalPlugin && message.variant === "approval" && !!message.approval;
       const hasDirectiveBubble =
         !askWithPlugin &&
         message.role === "assistant" &&
@@ -2988,6 +3024,14 @@ export const createAgentExperience = (
         componentStreamingEnabled &&
         hasComponentDirective(message);
 
+      // If a message stops being an approval-plugin bubble, strip
+      // `data-preserve-runtime` so the next morph can replace the live wrapper.
+      if (!approvalWithPlugin && lastApprovalBubbleFingerprint.has(message.id)) {
+        const existing = container.querySelector<HTMLElement>(`#wrapper-${message.id}`);
+        existing?.removeAttribute("data-preserve-runtime");
+        lastApprovalBubbleFingerprint.delete(message.id);
+      }
+
       // If a message previously rendered as a directive bubble but no longer
       // does (e.g. content was rewritten), strip `data-preserve-runtime` from
       // the live wrapper so the next morph can replace it.
@@ -3009,7 +3053,7 @@ export const createAgentExperience = (
           }`
         : "";
       const fingerprint = computeMessageFingerprint(message, configVersion) + askMeta;
-      const cachedWrapper = (askWithPlugin || hasDirectiveBubble)
+      const cachedWrapper = (askWithPlugin || approvalWithPlugin || hasDirectiveBubble)
         ? null
         : getCachedWrapper(messageCache, message.id, fingerprint);
       if (cachedWrapper) {
@@ -3043,9 +3087,9 @@ export const createAgentExperience = (
         if (message.variant === "tool" && p.renderToolCall) {
           return true;
         }
-        if (message.variant === "approval" && p.renderApproval) {
-          return true;
-        }
+        // Approval plugins are handled via the stub-and-hydrate path below
+        // (see `approvalWithPlugin`), not this inline morph path, so their
+        // listeners survive — so they are intentionally excluded here.
         if (!message.variant && p.renderMessage) {
           return true;
         }
@@ -3159,6 +3203,74 @@ export const createAgentExperience = (
           }
           return;
         }
+      } else if (approvalWithPlugin) {
+        // Plugin-rendered approval bubble. Build the live element with its
+        // listeners, append a stub for the morph pass, and hydrate the live
+        // element into the morphed wrapper afterward (same trick as
+        // `renderAskUserQuestion` / component directives) so Approve/Deny and
+        // any accordion listeners survive idiomorph's `importNode`. Gate the
+        // rebuild on fingerprint so interactive state (e.g. a collapsed
+        // accordion) is preserved while the approval stays pending.
+        const approvalPlugin = plugins.find((p) => typeof p.renderApproval === "function");
+        const lastFp = lastApprovalBubbleFingerprint.get(message.id);
+        const needsRebuild = lastFp !== fingerprint;
+        let liveBubble: HTMLElement | null = null;
+
+        if (needsRebuild && approvalPlugin?.renderApproval) {
+          // Re-find the live message at decision time so we resolve against
+          // current state, and route WebMCP gate approvals to the local
+          // resolver — mirroring the built-in delegated handler.
+          const approvalMessageId = message.id;
+          const resolveDecision = (
+            decision: "approved" | "denied",
+            options?: AgentWidgetApprovalDecisionOptions
+          ): void => {
+            const live = sessionRef.current
+              ?.getMessages()
+              .find((m) => m.id === approvalMessageId);
+            if (!live?.approval) return;
+            if (live.approval.toolType === "webmcp") {
+              sessionRef.current?.resolveWebMcpApproval(live.id, decision);
+            } else {
+              sessionRef.current?.resolveApproval(live.approval, decision, options);
+            }
+          };
+          liveBubble = approvalPlugin.renderApproval({
+            message,
+            defaultRenderer: () => createApprovalBubble(message, config),
+            config,
+            approve: (options) => resolveDecision("approved", options),
+            deny: (options) => resolveDecision("denied", options)
+          });
+        }
+
+        if (needsRebuild && liveBubble === null) {
+          // Plugin opted out for this state (e.g. a resolved approval, where the
+          // demo plugin defers to the built-in approved/denied bubble). Render
+          // the built-in bubble — it resolves via the delegated `messagesWrapper`
+          // handler and morphs normally — and drop any preserved live wrapper so
+          // morph can replace the now-stale pending bubble.
+          const existing = container.querySelector<HTMLElement>(`#wrapper-${message.id}`);
+          existing?.removeAttribute("data-preserve-runtime");
+          lastApprovalBubbleFingerprint.delete(message.id);
+          bubble = createApprovalBubble(message, config);
+        } else {
+          // A fresh live bubble to hydrate (needsRebuild), or fingerprint
+          // unchanged so we reuse the preserved live wrapper (`bubble: null`).
+          const stub = document.createElement("div");
+          stub.className = "persona-flex";
+          stub.id = `wrapper-${message.id}`;
+          stub.setAttribute("data-wrapper-id", message.id);
+          stub.setAttribute("data-approval-plugin-stub", "true");
+          stub.setAttribute("data-preserve-runtime", "true");
+          tempContainer.appendChild(stub);
+          approvalPluginHydrate.push({
+            messageId: message.id,
+            fingerprint,
+            bubble: liveBubble
+          });
+          return;
+        }
       } else if (matchingPlugin) {
         if (message.variant === "reasoning" && message.reasoning && matchingPlugin.renderReasoning) {
           if (!showReasoning) return;
@@ -3174,13 +3286,6 @@ export const createAgentExperience = (
             defaultRenderer: () => createToolBubble(message, config),
             config
           });
-        } else if (message.variant === "approval" && message.approval && matchingPlugin.renderApproval) {
-          if (config.approval === false) return;
-          bubble = matchingPlugin.renderApproval({
-            message,
-            defaultRenderer: () => createApprovalBubble(message, config),
-            config
-          });
         } else if (matchingPlugin.renderMessage) {
           bubble = matchingPlugin.renderMessage({
             message,
@@ -3663,6 +3768,30 @@ export const createAgentExperience = (
         if (!activeMessageIds.has(id)) lastComponentDirectiveFingerprint.delete(id);
       }
     }
+
+    // Hydrate plugin-rendered approval bubbles into their stub wrappers,
+    // mirroring the ask-question / component-directive hydration above.
+    if (approvalPluginHydrate.length > 0) {
+      for (const { messageId, fingerprint, bubble } of approvalPluginHydrate) {
+        const wrapper = container.querySelector(`#wrapper-${messageId}`);
+        if (!wrapper) continue;
+        if (bubble === null) {
+          // Fingerprint matched the previous pass (or the plugin opted out
+          // after a prior render) — the live wrapper, kept alive by
+          // `data-preserve-runtime`, still holds the listener-bearing bubble.
+          continue;
+        }
+        wrapper.replaceChildren(bubble);
+        wrapper.setAttribute("data-bubble-fp", fingerprint);
+        lastApprovalBubbleFingerprint.set(messageId, fingerprint);
+      }
+    }
+
+    if (lastApprovalBubbleFingerprint.size > 0) {
+      for (const id of lastApprovalBubbleFingerprint.keys()) {
+        if (!activeMessageIds.has(id)) lastApprovalBubbleFingerprint.delete(id);
+      }
+    }
   };
 
   // Alias for clarity - the implementation handles flicker prevention via typing indicator logic
@@ -7258,7 +7387,11 @@ export const createAgentExperience = (
       textarea.focus();
       return true;
     },
-    async resolveApproval(approvalId: string, decision: 'approved' | 'denied'): Promise<void> {
+    async resolveApproval(
+      approvalId: string,
+      decision: 'approved' | 'denied',
+      options?: AgentWidgetApprovalDecisionOptions
+    ): Promise<void> {
       const messages = session.getMessages();
       const approvalMessage = messages.find(
         m => m.variant === "approval" && m.approval?.id === approvalId
@@ -7274,7 +7407,7 @@ export const createAgentExperience = (
         session.resolveWebMcpApproval(approvalMessage.id, decision);
         return;
       }
-      return session.resolveApproval(approvalMessage.approval, decision);
+      return session.resolveApproval(approvalMessage.approval, decision, options);
     },
     getMessages() {
       return session.getMessages();

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);