@runtypelabs/persona 3.31.0 → 3.33.0

package/src/types.ts

@@ -231,8 +231,13 @@ export type ClientToolDefinition = {
   description: string;
   /** JSON Schema (per WebMCP spec) — passed through as-is. */
   parametersSchema?: object;
-  /** Set to `'webmcp'` for tools discovered via the polyfill. */
-  origin?: 'webmcp' | 'local';
+  /**
+   * `'webmcp'` for tools discovered via the polyfill (server prepends the
+   * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
+   * bare on the wire). Matches the server's accepted enum — any other value
+   * fails dispatch validation.
+   */
+  origin?: 'webmcp' | 'sdk';
   /** Origin of the page that registered the tool — for server-side audit. */
   pageOrigin?: string;
   /**
@@ -397,6 +402,13 @@ export type AgentMessageMetadata = {
    * paginated stepper. Persists alongside `askUserQuestionAnswers`.
    */
   askUserQuestionIndex?: number;
+  /**
+   * Set to `true` once a `suggest_replies` tool call's fire-and-forget
+   * `/resume` has been accepted by the server. Persisted belt-and-suspenders
+   * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
+   * never re-resume the call.
+   */
+  suggestRepliesResolved?: boolean;
 };
 
 export type AgentWidgetRequestMiddlewareContext = {
@@ -1092,6 +1104,38 @@ export type AgentWidgetFeatureFlags = {
    * pills + optional free-text input.
    */
   askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+  /**
+   * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
+   * the tool, the widget shows the suggestions as tappable chips above the
+   * composer (reusing the suggestion-chips surface) and immediately resumes
+   * the execution — fire-and-forget, no user input awaited.
+   */
+  suggestReplies?: AgentWidgetSuggestRepliesFeature;
+};
+
+/**
+ * Feature config for the built-in `suggest_replies` quick-reply chips.
+ * Chips render in the existing suggestions slot above the composer and are
+ * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
+ * verbatim as the user's next message; chips clear once any user message
+ * follows them.
+ */
+export type AgentWidgetSuggestRepliesFeature = {
+  /**
+   * Enable the feature. Defaults to true. When false, `suggest_replies`
+   * renders as a regular tool bubble and is NOT auto-resumed — only set this
+   * with no server-side `suggest_replies` declaration, or the execution
+   * parks awaiting a resume that never comes.
+   */
+  enabled?: boolean;
+  /**
+   * Advertise the built-in `suggest_replies` tool to the agent on every
+   * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+   * needed. Defaults to `false`: flows that already declare the tool via
+   * `runtimeTools` would otherwise present it to the model twice. Ignored
+   * when `enabled` is `false`.
+   */
+  expose?: boolean;
 };
 
 /**
@@ -1157,6 +1201,19 @@ export type AgentWidgetAskUserQuestionStyles = {
 export type AgentWidgetAskUserQuestionFeature = {
   /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
   enabled?: boolean;
+  /**
+   * Advertise the built-in `ask_user_question` tool to the agent on every
+   * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+   * needed. The tool ships with a model-facing description and JSON schema
+   * matching {@link AskUserQuestionPayload}; when the model calls it, the
+   * existing answer-pill sheet renders and the answer resumes the execution.
+   *
+   * Defaults to `false`: flows that already declare `ask_user_question` via
+   * `runtimeTools` would otherwise present the tool to the model twice.
+   * Ignored when `enabled` is `false` — never offer the agent a question
+   * tool the widget can't render an answer UI for.
+   */
+  expose?: boolean;
   /** Slide-in animation duration in ms. Defaults to 180. */
   slideInMs?: number;
   /** Label for the free-text pill. Defaults to "Other…". */
@@ -1350,6 +1407,26 @@ export type AgentWidgetDockConfig = {
    *   it appears to emerge at full width like a floating widget.
    */
   reveal?: "resize" | "overlay" | "push" | "emerge";
+  /**
+   * Maximum height of the dock panel, applied as a viewport-overflow guard.
+   *
+   * The docked shell sizes itself with `height: 100%`, which only resolves when
+   * an ancestor (usually `html, body { height: 100% }`) provides a definite
+   * height. Without one, the dock column would otherwise grow with the
+   * conversation and scroll off the page. This cap clamps the panel to the
+   * viewport (and keeps the `resize`/`emerge` reveals pinned with
+   * `position: sticky`; `push`/`overlay` get the cap only, since their
+   * transform/absolute contexts defeat sticky) so a missing height chain
+   * degrades gracefully instead of breaking the chat.
+   *
+   * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
+   * - Set `false` to disable the guard entirely (the panel then sizes purely
+   *   from the surrounding layout — make sure your page provides a definite
+   *   height all the way down to the dock target's parent).
+   *
+   * @default "100dvh"
+   */
+  maxHeight?: string | false;
 };
 
 /**

package/src/ui.suggest-replies.test.ts

@@ -0,0 +1,237 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import { SUGGEST_REPLIES_TOOL_NAME } from "./suggest-replies-tool";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const makeController = (config?: Record<string, unknown>) => {
+  const mount = createMount();
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    suggestionChips: [],
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+  return { mount, controller };
+};
+
+const injectUserMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id = "u1",
+  createdAt = "2026-06-10T00:00:00.000Z",
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "user",
+      content: "hello",
+      createdAt,
+      streaming: false,
+    },
+  });
+};
+
+const injectSuggestReplies = (
+  controller: ReturnType<typeof createAgentExperience>,
+  {
+    id = "sr-1",
+    suggestions = ["Tell me more", "Show pricing"],
+  }: { id?: string; suggestions?: string[] } = {},
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "assistant",
+      content: "",
+      createdAt: "2026-06-10T00:00:01.000Z",
+      streaming: false,
+      variant: "tool",
+      toolCall: {
+        id,
+        name: SUGGEST_REPLIES_TOOL_NAME,
+        status: "complete",
+        args: { suggestions },
+        chunks: [],
+      },
+      // No executionId/awaitingLocalTool — rendering is driven purely by the
+      // message list; the auto-resume path is covered in
+      // suggest-replies-tool.test.ts.
+    },
+  });
+};
+
+const chipButtons = (mount: HTMLElement, label: string): HTMLButtonElement[] =>
+  Array.from(mount.querySelectorAll("button")).filter(
+    (btn) => btn.textContent === label,
+  );
+
+describe("suggest_replies chips UI", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("renders agent-pushed chips mid-conversation (after a user message exists)", () => {
+    const { mount, controller } = makeController();
+    injectUserMessage(controller);
+    injectSuggestReplies(controller);
+
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(1);
+    expect(chipButtons(mount, "Show pricing")).toHaveLength(1);
+
+    controller.destroy();
+  });
+
+  it("suppresses the transcript tool bubble for the suggest_replies message", () => {
+    const { mount, controller } = makeController();
+    injectUserMessage(controller);
+    injectSuggestReplies(controller);
+
+    // No tool bubble rendered for the suggest_replies tool message.
+    expect(mount.querySelector('[data-bubble-type="tool"]')).toBeNull();
+    expect(mount.textContent).not.toContain("suggest_replies");
+
+    controller.destroy();
+  });
+
+  it("clears the chips once a user message follows them", () => {
+    const { mount, controller } = makeController();
+    injectUserMessage(controller, "u1");
+    injectSuggestReplies(controller);
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(1);
+
+    injectUserMessage(controller, "u2", "2026-06-10T00:00:02.000Z");
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(0);
+
+    controller.destroy();
+  });
+
+  it("shows only the latest call's chips when a turn carries several", () => {
+    const { mount, controller } = makeController();
+    injectUserMessage(controller);
+    injectSuggestReplies(controller, { id: "sr-1", suggestions: ["Old"] });
+    injectSuggestReplies(controller, { id: "sr-2", suggestions: ["New"] });
+
+    expect(chipButtons(mount, "Old")).toHaveLength(0);
+    expect(chipButtons(mount, "New")).toHaveLength(1);
+
+    controller.destroy();
+  });
+
+  it("sends the chip text verbatim as a user message on click", async () => {
+    global.fetch = vi.fn().mockImplementation(async () => {
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(c) {
+          c.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+          c.close();
+        },
+      });
+      return new Response(stream, {
+        headers: { "Content-Type": "text/event-stream" },
+      });
+    });
+
+    const { mount, controller } = makeController();
+    injectUserMessage(controller);
+    injectSuggestReplies(controller);
+
+    chipButtons(mount, "Tell me more")[0]!.click();
+    await Promise.resolve();
+
+    const sent = controller
+      .getMessages()
+      .filter((m) => m.role === "user")
+      .map((m) => m.content);
+    expect(sent).toContain("Tell me more");
+    // The chip click appended a user message, so the chips cleared.
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(0);
+
+    controller.destroy();
+  });
+
+  it("keeps live agent chips through a config update", () => {
+    const { mount, controller } = makeController();
+    injectUserMessage(controller);
+    injectSuggestReplies(controller);
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(1);
+
+    // A display-only config update (e.g. theme tweak) re-renders the
+    // suggestions row — it must re-apply the agent-chips rule, not fall back
+    // to the static config chips (which are hidden mid-conversation).
+    controller.update({
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      suggestionChips: [],
+      copy: { title: "Updated title" },
+    } as unknown as Parameters<typeof controller.update>[0]);
+
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(1);
+
+    controller.destroy();
+  });
+
+  it("renders no chips and falls back to the tool bubble when disabled", () => {
+    const { mount, controller } = makeController({
+      features: { suggestReplies: { enabled: false } },
+    });
+    injectUserMessage(controller);
+    injectSuggestReplies(controller);
+
+    expect(chipButtons(mount, "Tell me more")).toHaveLength(0);
+    // The generic tool bubble renders instead, keeping the parked call visible.
+    expect(mount.textContent).toContain("suggest_replies");
+
+    controller.destroy();
+  });
+
+  it("dispatches persona:suggestReplies:shown and :selected DOM events", async () => {
+    global.fetch = vi.fn().mockImplementation(async () => {
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(c) {
+          c.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+          c.close();
+        },
+      });
+      return new Response(stream, {
+        headers: { "Content-Type": "text/event-stream" },
+      });
+    });
+
+    const shown: string[][] = [];
+    const selected: string[] = [];
+    document.addEventListener("persona:suggestReplies:shown", (e) => {
+      shown.push((e as CustomEvent).detail.suggestions);
+    });
+    document.addEventListener("persona:suggestReplies:selected", (e) => {
+      selected.push((e as CustomEvent).detail.suggestion);
+    });
+
+    const { mount, controller } = makeController();
+    injectUserMessage(controller);
+    injectSuggestReplies(controller);
+
+    expect(shown).toEqual([["Tell me more", "Show pricing"]]);
+
+    // Re-rendering the same chip set must not re-fire `shown`.
+    injectSuggestReplies(controller, { id: "sr-1" });
+    expect(shown).toHaveLength(1);
+
+    chipButtons(mount, "Show pricing")[0]!.click();
+    await Promise.resolve();
+    expect(selected).toEqual(["Show pricing"]);
+
+    controller.destroy();
+  });
+});

package/src/ui.ts

@@ -88,6 +88,10 @@ import {
   removeAskUserQuestionSheet,
   setCurrentAnswer,
 } from "./components/ask-user-question-bubble";
+import {
+  isSuggestRepliesMessage,
+  latestAgentSuggestions,
+} from "./suggest-replies-tool";
 import { formatElapsedMs } from "./utils/formatting";
 import { approvalDetailsExpansionState, createApprovalBubble, updateApprovalDetailsUI } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
@@ -2625,6 +2629,43 @@ export const createAgentExperience = (
   const suggestionsManager = createSuggestions(suggestions);
   let closeHandler: (() => void) | null = null;
   let session: AgentWidgetSession;
+
+  // Single render rule for the suggestions row, shared by the message-change,
+  // initial-paint, and config-update paths: agent-pushed `suggest_replies`
+  // chips win when the latest-turn rule yields any (last suggest_replies tool
+  // message with no user message after it); otherwise static config chips
+  // keep their before-first-user-message behavior. Config updates MUST route
+  // through here too — re-rendering with only `config.suggestionChips` would
+  // drop a live agent chip row until the next message change.
+  const renderSuggestions = (messages?: AgentWidgetMessage[]) => {
+    if (!session) return;
+    const current = messages ?? session.getMessages();
+    const agentChips =
+      config.features?.suggestReplies?.enabled !== false
+        ? latestAgentSuggestions(current)
+        : null;
+    if (agentChips) {
+      suggestionsManager.render(
+        agentChips,
+        session,
+        textarea,
+        current,
+        config.suggestionChipsConfig,
+        { agentPushed: true }
+      );
+    } else if (current.some((msg) => msg.role === "user")) {
+      // Hide suggestions once a user message exists.
+      suggestionsManager.render([], session, textarea, current);
+    } else {
+      suggestionsManager.render(
+        config.suggestionChips,
+        session,
+        textarea,
+        current,
+        config.suggestionChipsConfig
+      );
+    }
+  };
   let isStreaming = false;
   const messageCache = createMessageCache();
   // Tracks the last fingerprint we rendered a plugin-rendered ask_user_question
@@ -3359,6 +3400,18 @@ export const createAgentExperience = (
         return;
       }
 
+      // suggest_replies renders no transcript bubble — the chips above the
+      // composer are the only UI, and the session auto-resumes the call.
+      // When the feature is disabled the message falls through to the generic
+      // tool bubble (and is never auto-resumed), keeping the parked execution
+      // visible instead of silently swallowed.
+      if (
+        isSuggestRepliesMessage(message) &&
+        config.features?.suggestReplies?.enabled !== false
+      ) {
+        return;
+      }
+
       if (
         isAskUserQuestionMessage(message) &&
         config.features?.askUserQuestion?.enabled !== false
@@ -4758,18 +4811,9 @@ export const createAgentExperience = (
       renderMessagesWithPlugins(messagesWrapper, messages, postprocess);
       // Start elapsed timer if any active tool has a live duration span
       ensureToolElapsedTimer();
-      // Re-render suggestions to hide them after first user message
+      // Re-render suggestions — agent chips vs config chips, one shared rule.
       // Pass messages directly to avoid calling session.getMessages() during construction
-      if (session) {
-        const hasUserMessage = messages.some((msg) => msg.role === "user");
-        if (hasUserMessage) {
-          // Hide suggestions if user message exists
-          suggestionsManager.render([], session, textarea, messages);
-        } else {
-          // Show suggestions if no user message yet
-          suggestionsManager.render(config.suggestionChips, session, textarea, messages, config.suggestionChipsConfig);
-        }
-      }
+      renderSuggestions(messages);
       scheduleAutoScroll(!isStreaming);
       trackMessages(messages);
 
@@ -5698,7 +5742,7 @@ export const createAgentExperience = (
     mount.appendChild(customLauncherElement);
   }
   updateOpenState();
-  suggestionsManager.render(config.suggestionChips, session, textarea, undefined, config.suggestionChipsConfig);
+  renderSuggestions();
   updateCopy();
   setComposerDisabled(session.isStreaming());
   if (getScrollMode() === "follow") {
@@ -6982,7 +7026,7 @@ export const createAgentExperience = (
         session.getMessages(),
         postprocess
       );
-      suggestionsManager.render(config.suggestionChips, session, textarea, undefined, config.suggestionChipsConfig);
+      renderSuggestions();
       updateCopy();
       setComposerDisabled(session.isStreaming());
       

package/src/utils/dock.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isComposerBarMountMode, isDockedMountMode } from "./dock";
+import { isComposerBarMountMode, isDockedMountMode, resolveDockConfig } from "./dock";
 import type { AgentWidgetConfig } from "../types";
 
 describe("isDockedMountMode", () => {
@@ -17,6 +17,28 @@ describe("isDockedMountMode", () => {
   });
 });
 
+describe("resolveDockConfig", () => {
+  it("defaults maxHeight to the viewport guard", () => {
+    const config: AgentWidgetConfig = { apiUrl: "/api", launcher: { mountMode: "docked" } };
+    expect(resolveDockConfig(config).maxHeight).toBe("100dvh");
+  });
+
+  it("passes through a custom maxHeight and the false opt-out", () => {
+    expect(
+      resolveDockConfig({
+        apiUrl: "/api",
+        launcher: { mountMode: "docked", dock: { maxHeight: "600px" } },
+      }).maxHeight
+    ).toBe("600px");
+    expect(
+      resolveDockConfig({
+        apiUrl: "/api",
+        launcher: { mountMode: "docked", dock: { maxHeight: false } },
+      }).maxHeight
+    ).toBe(false);
+  });
+});
+
 describe("isComposerBarMountMode", () => {
   it("returns true for mountMode: 'composer-bar'", () => {
     const config: AgentWidgetConfig = {

package/src/utils/dock.ts

@@ -5,6 +5,7 @@ const DEFAULT_DOCK_CONFIG: Required<AgentWidgetDockConfig> = {
   width: "420px",
   animate: true,
   reveal: "resize",
+  maxHeight: "100dvh",
 };
 
 export const isDockedMountMode = (config?: AgentWidgetConfig): boolean =>
@@ -29,5 +30,6 @@ export const resolveDockConfig = (
     width: dock?.width ?? DEFAULT_DOCK_CONFIG.width,
     animate: dock?.animate ?? DEFAULT_DOCK_CONFIG.animate,
     reveal: dock?.reveal ?? DEFAULT_DOCK_CONFIG.reveal,
+    maxHeight: dock?.maxHeight ?? DEFAULT_DOCK_CONFIG.maxHeight,
   };
 };

package/src/version.ts

@@ -1,7 +1,10 @@
-import packageJson from "../package.json";
+// Named import (not default) so esbuild tree-shakes the JSON module down to
+// the one field we read — a default import inlines the entire package.json
+// (~4.8 kB minified) into every bundle.
+import { version } from "../package.json";
 
 /**
  * The current version of the @runtypelabs/persona package.
  * This is automatically derived from package.json.
  */
-export const VERSION = packageJson.version;
+export const VERSION = version;

package/src/webmcp-bridge.test.ts

@@ -31,6 +31,7 @@ import {
   isWebMcpToolName,
   stripWebMcpPrefix,
   computeClientToolsFingerprint,
+  setWebMcpPolyfillLoader,
 } from "./webmcp-bridge";
 import type { ClientToolDefinition } from "./types";
 
@@ -114,6 +115,9 @@ beforeEach(() => {
 
 afterEach(() => {
   vi.unstubAllGlobals();
+  // The loader is module-global (page-global in production); reset so a test
+  // that registers one can't leak into the default-import tests.
+  setWebMcpPolyfillLoader(null);
 });
 
 describe("stripWebMcpPrefix", () => {
@@ -150,6 +154,9 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
   });
 
   it("returns empty when initializeWebMCPPolyfill() throws", async () => {
+    // No pre-existing modelContext — otherwise install() short-circuits
+    // before importing the polyfill and the throwing init never runs.
+    vi.stubGlobal("document", {});
     polyfillMock.initThrows = true;
     const bridge = new WebMcpBridge({ enabled: true });
     expect(await bridge.snapshotForDispatch()).toEqual([]);
@@ -204,6 +211,59 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
   });
 });
 
+describe("setWebMcpPolyfillLoader", () => {
+  it("uses the registered loader instead of the bare import when no modelContext exists", async () => {
+    // Start with no modelContext so install() actually loads the polyfill;
+    // the loader's init then installs the registry, like the real one would.
+    const doc: { modelContext?: ReturnType<typeof makeModelContext> } = {};
+    vi.stubGlobal("document", doc);
+    registry.tools = [fakeTool({ name: "search" })];
+    const loader = vi.fn(async () => ({
+      initializeWebMCPPolyfill: () => {
+        doc.modelContext = makeModelContext();
+      },
+    }));
+    setWebMcpPolyfillLoader(loader);
+
+    const bridge = new WebMcpBridge({ enabled: true });
+    const snap = await bridge.snapshotForDispatch();
+
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect(snap.map((t) => t.name)).toEqual(["search"]);
+    expect(bridge.isOperational()).toBe(true);
+  });
+
+  it("disables WebMCP (with a warning) when the loader rejects", async () => {
+    vi.stubGlobal("document", {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    setWebMcpPolyfillLoader(() => Promise.reject(new Error("chunk 404")));
+
+    const bridge = new WebMcpBridge({ enabled: true });
+    expect(await bridge.snapshotForDispatch()).toEqual([]);
+    expect(bridge.isOperational()).toBe(false);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to load @mcp-b/webmcp-polyfill"),
+      expect.any(Error),
+    );
+    warn.mockRestore();
+  });
+
+  it("never invokes the loader when a compatible modelContext is already present", async () => {
+    // beforeEach stubs a compatible document.modelContext — the install
+    // short-circuit must win, so a failing loader is irrelevant.
+    registry.tools = [fakeTool({ name: "search" })];
+    const loader = vi.fn(() => Promise.reject(new Error("should not load")));
+    setWebMcpPolyfillLoader(loader);
+
+    const bridge = new WebMcpBridge({ enabled: true });
+    const snap = await bridge.snapshotForDispatch();
+
+    expect(loader).not.toHaveBeenCalled();
+    expect(snap.map((t) => t.name)).toEqual(["search"]);
+    expect(bridge.isOperational()).toBe(true);
+  });
+});
+
 describe("WebMCP display titles", () => {
   it("records declared titles on snapshot and exposes them via getWebMcpToolDisplayTitle", async () => {
     registry.tools = [

package/src/webmcp-bridge.ts

@@ -131,6 +131,28 @@ const log = {
   },
 };
 
+/** The slice of `@mcp-b/webmcp-polyfill` the bridge consumes on install. */
+export type WebMcpPolyfillModule = {
+  initializeWebMCPPolyfill: () => void;
+};
+
+/**
+ * Override how the polyfill module is obtained. By default the bridge does
+ * `import("@mcp-b/webmcp-polyfill")`, which bundlers resolve for npm
+ * consumers. The IIFE/CDN build can't resolve a bare specifier at runtime, so
+ * its entry (`index-global.ts`) registers a loader that imports the
+ * self-contained `webmcp-polyfill.js` chunk from a URL derived from the
+ * widget script's own `src`. Page-global, like `document.modelContext`
+ * itself. Pass `null` to restore the default (used by tests).
+ */
+let polyfillLoader: (() => Promise<WebMcpPolyfillModule>) | null = null;
+
+export const setWebMcpPolyfillLoader = (
+  loader: (() => Promise<WebMcpPolyfillModule>) | null,
+): void => {
+  polyfillLoader = loader;
+};
+
 /**
  * Compute a stable, order-independent fingerprint of a `ClientToolDefinition[]`
  * snapshot, for the diff-only / send-once dispatch path (client-token mode).
@@ -449,7 +471,18 @@ export class WebMcpBridge {
 
   private async install(): Promise<void> {
     try {
-      const mod = await import("@mcp-b/webmcp-polyfill");
+      // A compatible registry is already on the page (the host installed the
+      // polyfill, or a native impl) — initialize would no-op against it, so
+      // skip loading the module entirely. Pages that register tools before
+      // Persona's first dispatch always land here, because registering
+      // requires `document.modelContext` to exist.
+      if (this.getModelContext()) {
+        this.installed = true;
+        return;
+      }
+      const mod = polyfillLoader
+        ? await polyfillLoader()
+        : await import("@mcp-b/webmcp-polyfill");
       // Idempotent: no-ops if `document.modelContext` already exists (native or
       // a prior install by the host page).
       mod.initializeWebMCPPolyfill();

package/src/webmcp-polyfill.ts

@@ -0,0 +1,16 @@
+/**
+ * Standalone WebMCP polyfill chunk (`dist/webmcp-polyfill.js`).
+ *
+ * The IIFE/CDN widget bundle marks `@mcp-b/webmcp-polyfill` external so the
+ * ~35 kB (minified) polyfill + its transitive `@cfworker/json-schema` never
+ * ship to consumers who don't enable WebMCP. When `config.webmcp.enabled` is
+ * true and no `document.modelContext` exists yet, the bridge dynamically
+ * imports this chunk from a URL derived from the widget script's own `src`
+ * (see the loader registered in `index-global.ts`).
+ *
+ * Built self-contained (`--no-external`) — it must work standalone on a CDN
+ * with no module resolution. npm/bundler consumers never load this file;
+ * their bundlers resolve the bare `import("@mcp-b/webmcp-polyfill")` in
+ * `webmcp-bridge.ts` directly.
+ */
+export { initializeWebMCPPolyfill } from "@mcp-b/webmcp-polyfill";