@runtypelabs/persona 4.28.0 → 4.28.1

package/src/webmcp-bridge.test.ts

@@ -8,13 +8,13 @@ import type {
 
 // ---------------------------------------------------------------------------
 // Mock the strict @mcp-b/webmcp-polyfill. The bridge dynamically imports it and
-// calls `initializeWebMCPPolyfill()` (idempotent install of document.modelContext).
+// calls `initializeWebMCPPolyfill()` for the v5 automatic fallback.
 // We stub the install as a no-op and provide `document.modelContext` ourselves,
 // modeling the strict producer-preview surface the bridge consumes:
 //   - getTools(): async; inputSchema in either generation (see
 //     `registry.schemaShape`); annotations only when the tool declared them
-//   - executeTool(info, argsJson, { signal }): async; validates+runs execute(),
-//     returns JSON.stringify(rawResult) or null; honors the abort signal.
+//   - executeTool(info, input, { signal }): async; runs execute(),
+//     returns JSON.stringify(rawResult); honors the abort signal.
 // ---------------------------------------------------------------------------
 
 const polyfillMock = { initThrows: false };
@@ -39,7 +39,7 @@ import {
 } from "./webmcp-bridge";
 import type { ClientToolDefinition } from "./types";
 
-type MockClient = { requestUserInteraction: (cb: () => unknown) => Promise<unknown> };
+type MockClient = { signal: AbortSignal };
 
 type MockTool = {
   name: string;
@@ -85,22 +85,22 @@ const makeModelContext = () => ({
                 : JSON.stringify(t.inputSchema),
           }),
       title: t.title ?? "",
+      window,
+      origin: location.origin,
       ...(t.annotations === undefined ? {} : { annotations: t.annotations }),
     }));
   },
   async executeTool(
     info: { name: string },
-    inputArgsJson: string,
+    input: object,
     options?: { signal?: AbortSignal },
   ): Promise<string | null> {
     if (options?.signal?.aborted) throw new Error("Tool execution was cancelled");
     const tool = registry.tools.find((t) => t.name === info.name);
     if (!tool) throw new Error(`Tool not found: ${info.name}`);
-    const args = inputArgsJson ? JSON.parse(inputArgsJson) : {};
-    // The polyfill owns this client; `requestUserInteraction` is a pass-through.
-    const client: MockClient = {
-      requestUserInteraction: async (cb) => cb(),
-    };
+    if (!input || typeof input !== "object") throw new TypeError("inputObject must be an object");
+    const args = input as Record<string, unknown>;
+    const client: MockClient = { signal: options?.signal ?? new AbortController().signal };
     const execPromise = Promise.resolve(tool.execute(args, client));
     const raced = options?.signal
       ? Promise.race<unknown>([
@@ -118,7 +118,9 @@ const makeModelContext = () => ({
         ])
       : execPromise;
     const raw = await raced;
-    return raw === undefined ? null : JSON.stringify(raw);
+    const json = JSON.stringify(raw);
+    if (json === undefined) throw new Error("Tool execution failed");
+    return json;
   },
 });
 
@@ -137,6 +139,7 @@ beforeEach(() => {
   polyfillMock.initThrows = false;
   registry.tools = [];
   registry.schemaShape = "object";
+  vi.stubGlobal("window", {});
   // location is read by snapshotForDispatch; document.modelContext is the
   // consumer surface. Both are absent in the Node test environment.
   vi.stubGlobal("location", { origin: "https://example.test" });
@@ -183,7 +186,7 @@ describe("WebMcpBridge.snapshotForDispatch", () => {
     expect(bridge.isOperational()).toBe(false);
   });
 
-  it("returns empty when initializeWebMCPPolyfill() throws", async () => {
+  it("returns empty when the fallback initializer throws", async () => {
     // No pre-existing modelContext: otherwise install() short-circuits
     // before importing the polyfill and the throwing init never runs.
     vi.stubGlobal("document", {});
@@ -331,7 +334,7 @@ describe("setWebMcpPolyfillLoader", () => {
     vi.stubGlobal("document", doc);
     registry.tools = [fakeTool({ name: "search" })];
     const loader = vi.fn(async () => ({
-      initializeWebMCPPolyfill: () => {
+      installWebMCP: () => {
         doc.modelContext = makeModelContext();
       },
     }));
@@ -457,7 +460,7 @@ describe("WebMcpBridge.executeToolCall", () => {
   it("warns once and degrades cleanly when document.modelContext is present but incompatible", async () => {
     // A different / older WebMCP polyfill (or divergent native draft) squats
     // document.modelContext without the strict getTools()/executeTool() surface.
-    // @mcp-b's initializeWebMCPPolyfill correctly declines to overwrite it, so
+    // @mcp-b's installWebMCP correctly declines to overwrite it, so
     // Persona must (a) report non-operational, (b) surface an actionable error
     // distinct from "not available", and (c) warn exactly once.
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
@@ -531,32 +534,31 @@ describe("WebMcpBridge.executeToolCall", () => {
     expect(r).toEqual(shaped);
   });
 
-  it("normalizes an undefined return into an empty text block", async () => {
+  it("returns an error for a non-serializable undefined result", async () => {
     registry.tools = [fakeTool({ name: "act", execute: () => undefined })];
     const bridge = new WebMcpBridge({ enabled: true, onConfirm: allowAll });
     const r = await bridge.executeToolCall("webmcp:act", {});
-    expect(r).toEqual({ content: [{ type: "text", text: "" }] });
+    expect(r.isError).toBe(true);
   });
 
-  it("runs a tool's client.requestUserInteraction callback without a second confirm", async () => {
+  it("passes an invocation signal with a single confirmation", async () => {
     const confirmSpy = vi.fn(async () => true);
     registry.tools = [
       fakeTool({
         name: "sensitive",
         execute: async (_args, client) => {
-          const ack = await client.requestUserInteraction(async () => "ok!");
-          return { ack };
+          return { aborted: client.signal.aborted };
         },
       }),
     ];
     const bridge = new WebMcpBridge({ enabled: true, onConfirm: confirmSpy });
     const r = await bridge.executeToolCall("webmcp:sensitive", {});
-    // Only the single outer gate fires: the polyfill owns the in-tool callback.
+    // Only the single outer gate fires; the callback receives a cancellation signal.
     expect(confirmSpy).toHaveBeenCalledTimes(1);
     expect(r.isError).toBeUndefined();
     expect(r.content[0]).toEqual({
       type: "text",
-      text: JSON.stringify({ ack: "ok!" }),
+      text: JSON.stringify({ aborted: false }),
     });
   });
 
@@ -745,3 +747,67 @@ describe("computeClientToolsFingerprint: diff-only / send-once", () => {
     expect(fp.length).toBeLessThanOrEqual(128);
   });
 });
+
+describe("v6 local-document boundary", () => {
+  it("installs via the current lazy-module export", async () => {
+    const context = makeModelContext();
+    registry.tools = [fakeTool({ name: "local" })];
+    vi.stubGlobal("document", {});
+    setWebMcpPolyfillLoader(async () => ({
+      installWebMCP: () => { vi.stubGlobal("document", { modelContext: context }); },
+    }));
+    const snapshot = await new WebMcpBridge({ enabled: true }).snapshotForDispatch();
+    expect(snapshot.map(tool => tool.name)).toEqual(["local"]);
+  });
+
+  it("excludes other frames from snapshots and same-name execution", async () => {
+    const localWindow = {};
+    vi.stubGlobal("window", localWindow);
+    const local = { name: "shared", description: "Local", title: "Local title", origin: location.origin, window: localWindow };
+    const remote = { ...local, description: "Remote", title: "Remote title", window: {} };
+    vi.stubGlobal("document", { modelContext: {
+      getTools: async () => [remote, local, { ...remote, name: "remote_only" }],
+      executeTool: async (info: unknown) => JSON.stringify(info === local ? "local" : "remote"),
+    } });
+    const consumer = new WebMcpBridge({ enabled: true, onConfirm: allowAll });
+    const snapshot = await consumer.snapshotForDispatch();
+    expect(snapshot.map(tool => tool.name)).toEqual(["shared"]);
+    expect(getWebMcpToolDisplayTitle("shared")).toBe("Local title");
+    expect(await consumer.executeToolCall("webmcp:shared", {})).toEqual({ content: [{ type: "text", text: "local" }] });
+    expect((await consumer.executeToolCall("webmcp:remote_only", {})).isError).toBe(true);
+  });
+});
+
+describe("polyfill initializer compatibility", () => {
+  it("accepts the legacy initializer used by the automatic fallback", async () => {
+    vi.stubGlobal("document", {});
+    const initializeWebMCPPolyfill = vi.fn(() => {
+      vi.stubGlobal("document", { modelContext: makeModelContext() });
+    });
+    setWebMcpPolyfillLoader(async () => ({ initializeWebMCPPolyfill }));
+    const bridge = new WebMcpBridge({ enabled: true });
+    await bridge.snapshotForDispatch();
+    expect(initializeWebMCPPolyfill).toHaveBeenCalledTimes(1);
+    expect(bridge.isOperational()).toBe(true);
+  });
+});
+
+describe("native preview argument conversion", () => {
+  it("supports DOMString coercion without relying on polyfill metadata", async () => {
+    const nativeExecute = vi.fn(async (_tool: unknown, input: unknown) => {
+      // WebIDL converts an object to DOMString before the native JSON parser.
+      return JSON.stringify({ received: JSON.parse(String(input)) });
+    });
+    vi.stubGlobal("document", {
+      modelContext: {
+        getTools: async () => [{ name: "native", description: "Native preview tool" }],
+        executeTool: nativeExecute,
+      },
+    });
+    const consumer = new WebMcpBridge({ enabled: true, onConfirm: allowAll });
+    expect(await consumer.executeToolCall("webmcp:native", { count: 2 })).toEqual({
+      content: [{ type: "text", text: '{"received":{"count":2}}' }],
+    });
+    expect(nativeExecute).toHaveBeenCalledTimes(1);
+  });
+});

package/src/webmcp-bridge.ts

@@ -14,26 +14,19 @@
  * enforcement live on the Runtype API; this bridge mirrors those checks
  * client-side as a usability convenience, not a security boundary.
  *
- * About `@mcp-b/webmcp-polyfill`: it polyfills the *strict standard surface*
- * only (`registerTool` / `getTools` / `executeTool` on `document.modelContext`),
- * with no MCP-B-only extensions. The spec standardizes the *producer* side;
- * Persona is an in-page *consumer*, so it reads the registry via the
- * producer-facing preview API:
- *   - `getTools()`: async; returns `{ name, description, inputSchema }` where
- *     `inputSchema` is a JSON *string*. Annotations are not exposed here.
- *   - `executeTool(toolInfo, inputArgsJson, { signal })`: async; validates args
- *     against the tool's schema, runs `execute()`, and returns the raw result as
- *     a JSON *string* (or `null` for `undefined`). Honors `signal` for abort.
+ * Supports v5's JSON-string input and v6's object input with a single call:
+ * the runtime passes a JSON object that also string-coerces to JSON text.
+ * Never infer the execution contract from metadata or retry a failed call.
+ * Only tools owned by this document are exposed: the wire addresses tools by
+ * name, not by frame. Callbacks must validate their own input.
  *
- * The polyfill auto-installs `document.modelContext` at module-evaluation time,
- * so it is imported *dynamically* and only when `config.webmcp.enabled === true`
- *: a static import would install the global for every widget consumer,
- * including those that never opted into WebMCP.
+ * The automatic fallback stays on v5 to preserve its browser requirements and
+ * result semantics. Host pages may install v5 or v6 themselves; Persona does
+ * not replace an existing context. v5's initializeWebMCPPolyfill() and v6's
+ * installWebMCP() are both accepted by custom loaders.
  *
- * Confirm model: every `webmcp:*` call goes through one confirm gate before
- * `execute()` runs, regardless of `annotations.readOnlyHint`. (The polyfill owns
- * the spec's `client.requestUserInteraction` callback internally; Persona cannot
- * inject a nested confirm there, so the single outer gate is the whole story.)
+ * Every call passes one confirm gate before execution, regardless of
+ * annotations.readOnlyHint. v6 callbacks also receive an invocation signal.
  */
 
 import type { ClientToolDefinition } from "./types";
@@ -59,18 +52,20 @@ export interface ModelContextToolInfo {
    * object. `@mcp-b/webmcp-polyfill` made the switch in v5, and Chrome ships it
    * from 154.0.8013 (cross-document tools first) -- but Chrome 149-153, most of
    * the Origin Trial population, and 154's same-document tools still emit the
-   * string. Both are live in the field, so we accept both.
+   * string. Both input execution contracts are supported independently of
+   * schema representation.
    *
    * Absent when the tool registered no schema: v5 omits the member, where v4
    * always emitted a `{"type":"object"}` string.
    */
   inputSchema?: object | string;
+  /** Owning frame and origin, when supplied by the registry. Never sent on the wire. */
+  window?: Window;
+  origin?: 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.
+   * top-level `title` is the display-name channel, not `annotations.title`.
    */
   title?: string;
   /**
@@ -89,7 +84,7 @@ export interface ModelContextCoreLike {
   getTools(): Promise<ModelContextToolInfo[]>;
   executeTool(
     tool: ModelContextToolInfo,
-    inputArgsJson: string,
+    input: object | string,
     options?: { signal?: AbortSignal },
   ): Promise<string | null>;
 }
@@ -132,9 +127,9 @@ export const getWebMcpToolDisplayTitle = (
 ): string | undefined => webMcpToolDisplayTitles.get(stripWebMcpPrefix(toolName));
 
 /** The slice of `@mcp-b/webmcp-polyfill` the bridge consumes on install. */
-export type WebMcpPolyfillModule = {
-  initializeWebMCPPolyfill: () => void;
-};
+export type WebMcpPolyfillModule =
+  | { initializeWebMCPPolyfill: () => void }
+  | { installWebMCP: () => void };
 
 /**
  * Override how the polyfill module is obtained. By default the bridge does

package/src/webmcp-polyfill.integration.test.ts

@@ -0,0 +1,339 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { JSDOM } from "jsdom";
+import { MessageChannel } from "node:worker_threads";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { WebMcpBridge } from "./webmcp-bridge-public";
+import { setWebMcpPolyfillLoader } from "./webmcp-bridge";
+import type { ModelContextCoreLike } from "./webmcp-bridge";
+
+type ToolCallback = (
+  input: unknown,
+  options?: { signal: AbortSignal }
+) => unknown;
+type TestContext = ModelContextCoreLike & {
+  registerTool(
+    tool: {
+      name: string;
+      description: string;
+      title?: string;
+      inputSchema?: object;
+      annotations?: { readOnlyHint: boolean; untrustedContentHint: boolean };
+      execute: ToolCallback;
+    },
+    options?: { signal: AbortSignal }
+  ): Promise<void>;
+};
+
+// Run the actual published distributions, not version-shaped mocks. The v6
+// alias is test-only: Persona's automatic fallback deliberately stays on v5.
+describe.each([
+  { version: "v5", module: "@mcp-b/webmcp-polyfill", legacy: true },
+  { version: "v6", module: "webmcp-polyfill-v6", legacy: false },
+])("WebMcpBridge with published $version", ({ module, legacy }) => {
+  const dom = new JSDOM("<!doctype html><body></body>", {
+    url: "https://example.test",
+    runScripts: "outside-only",
+  });
+  const browser = dom.window;
+  const channels: MessageChannel[] = [];
+  const registrations: AbortController[] = [];
+  let context: TestContext;
+
+  beforeAll(() => {
+    // v5 also runs without the newer browser APIs required by v6. These are
+    // intentionally absent to exercise the compatibility of our fallback.
+    Object.defineProperty(browser, "isSecureContext", { value: true });
+    if (legacy) {
+      Object.defineProperty(browser.Promise, "withResolvers", {
+        value: undefined,
+      });
+      Object.defineProperty(browser.AbortSignal, "any", { value: undefined });
+      Object.defineProperty(browser.URL, "parse", { value: undefined });
+    }
+    Object.defineProperty(browser, "MessageChannel", {
+      value: class extends MessageChannel {
+        constructor() {
+          super();
+          channels.push(this);
+        }
+      },
+    });
+    vi.stubGlobal("AbortController", browser.AbortController);
+    vi.stubGlobal("AbortSignal", browser.AbortSignal);
+    vi.stubGlobal("window", browser);
+    vi.stubGlobal("document", browser.document);
+    vi.stubGlobal("location", browser.location);
+    // A true Window realm is required by v6's native Window.window getter.
+    browser.eval(
+      readFileSync(
+        createRequire(import.meta.url).resolve(`${module}/iife`),
+        "utf8"
+      )
+    );
+    context = (browser.document as unknown as { modelContext: TestContext })
+      .modelContext;
+  });
+  afterEach(() => {
+    for (const registration of registrations.splice(0)) registration.abort();
+    setWebMcpPolyfillLoader(null);
+  });
+  afterAll(() => {
+    for (const channel of channels) {
+      channel.port1.close();
+      channel.port2.close();
+    }
+    browser.close();
+    vi.unstubAllGlobals();
+  });
+
+  const register = async (name: string, execute: ToolCallback) => {
+    const registration = new browser.AbortController();
+    registrations.push(registration);
+    await context.registerTool(
+      {
+        name,
+        description: `Run ${name}`,
+        title: "Local tool",
+        inputSchema: {
+          type: "object",
+          properties: { query: { type: "string" } },
+        },
+        annotations: { readOnlyHint: true, untrustedContentHint: true },
+        execute,
+      },
+      { signal: registration.signal }
+    );
+  };
+  const bridge = (onConfirm = vi.fn(async () => true)) =>
+    new WebMcpBridge({ enabled: true, onConfirm });
+
+  it("discovers tools without replacing the host registry or loading a fallback", async () => {
+    const load = vi.fn(async () => {
+      throw new Error("must preserve the host registry");
+    });
+    setWebMcpPolyfillLoader(load);
+    await register("lookup", (input) => ({ received: input }));
+    expect(await bridge().snapshotForDispatch()).toEqual([
+      expect.objectContaining({
+        name: "lookup",
+        parametersSchema: {
+          type: "object",
+          properties: { query: { type: "string" } },
+        },
+        annotations: { readOnlyHint: true, untrustedContentHint: true },
+        untrustedContentHint: true,
+      }),
+    ]);
+    expect(load).not.toHaveBeenCalled();
+    expect(
+      (browser.document as unknown as { modelContext: TestContext })
+        .modelContext
+    ).toBe(context);
+  });
+
+  it.each(
+    [
+      { query: "shoes" },
+      { nested: { text: 'quotes " and emoji 😀' }, values: [true, null, 2] },
+      { toString: "an ordinary JSON property", valueOf: 7, __proto__: null },
+      ["array", { nested: true }],
+    ].map((args) => ({ args }))
+  )(
+    "executes JSON arguments once without mutating them: $args",
+    async ({ args }) => {
+      const execute = vi.fn((input: unknown) => ({ received: input }));
+      const confirm = vi.fn(async () => true);
+      const before = JSON.stringify(args);
+      await register("lookup", execute);
+      const result = await bridge(confirm).executeToolCall(
+        "webmcp:lookup",
+        args
+      );
+      expect(result).toEqual({
+        content: [{ type: "text", text: JSON.stringify({ received: args }) }],
+      });
+      expect(execute).toHaveBeenCalledTimes(1);
+      expect(execute.mock.calls[0]![0]).toEqual(JSON.parse(before));
+      expect(confirm).toHaveBeenCalledTimes(1);
+      expect(JSON.stringify(args)).toBe(before);
+      expect(Object.getOwnPropertySymbols(args)).toEqual([]);
+    }
+  );
+
+  it.each([undefined, () => "not JSON"])(
+    "defaults absent/non-JSON arguments to an empty object",
+    async (args) => {
+      const execute = vi.fn((input: unknown) => input);
+      await register("empty", execute);
+      expect(await bridge().executeToolCall("webmcp:empty", args)).toEqual({
+        content: [{ type: "text", text: "{}" }],
+      });
+      expect(execute).toHaveBeenCalledTimes(1);
+    }
+  );
+
+  it("keeps the legacy empty-object fallback for circular arguments", async () => {
+    const args: { self?: unknown } = {};
+    args.self = args;
+    await register("empty", (input) => input);
+    expect(await bridge().executeToolCall("webmcp:empty", args)).toEqual({
+      content: [{ type: "text", text: "{}" }],
+    });
+  });
+
+  it.each([
+    ["string", "hello", "hello"],
+    ["null", null, "null"],
+    [
+      "envelope",
+      { isError: true, content: [{ type: "text", text: "invalid input" }] },
+      null,
+    ],
+  ])("preserves a %s result", async (_label, result, text) => {
+    await register("result", () => result);
+    expect(await bridge().executeToolCall("webmcp:result", {})).toEqual(
+      text === null ? result : { content: [{ type: "text", text }] }
+    );
+  });
+
+  const circularResult: { self?: unknown } = {};
+  circularResult.self = circularResult;
+  it.each([
+    { label: "undefined", result: undefined },
+    { label: "circular object", result: circularResult },
+    { label: "function", result: () => "function result" },
+    { label: "BigInt", result: 1n },
+  ])(
+    "preserves the installed runtime's $label-result semantics without retries",
+    async ({ result }) => {
+      const execute = vi.fn(() => result);
+      await register("unserializable_result", execute);
+      const output = await bridge().executeToolCall(
+        "webmcp:unserializable_result",
+        {}
+      );
+      if (legacy) {
+        expect(output).toEqual({
+          content: [{ type: "text", text: String(result) }],
+        });
+      } else {
+        expect(output.isError).toBe(true);
+      }
+      expect(execute).toHaveBeenCalledTimes(1);
+    }
+  );
+
+  it("preserves the installed runtime's empty-string result", async () => {
+    await register("empty_result", () => "");
+    expect(await bridge().executeToolCall("webmcp:empty_result", {})).toEqual({
+      content: [{ type: "text", text: legacy ? "Operation succeeded" : "" }],
+    });
+  });
+
+  it("returns callback failures without retrying a side effect", async () => {
+    const execute = vi.fn(() => {
+      throw new Error("failure after side effect");
+    });
+    await register("failed", execute);
+    expect((await bridge().executeToolCall("webmcp:failed", {})).isError).toBe(
+      true
+    );
+    expect(execute).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not execute when approval is denied", async () => {
+    const execute = vi.fn(() => "unexpected");
+    await register("denied", execute);
+    expect(
+      (
+        await bridge(vi.fn(async () => false)).executeToolCall(
+          "webmcp:denied",
+          {}
+        )
+      ).isError
+    ).toBe(true);
+    expect(execute).not.toHaveBeenCalled();
+  });
+
+  it("cancels the invocation and forwards the signal when the runtime supports it", async () => {
+    let started!: () => void;
+    const ready = new Promise<void>((resolve) => {
+      started = resolve;
+    });
+    let callbackSignal: AbortSignal | undefined;
+    const execute = vi.fn(
+      (_input: unknown, options?: { signal: AbortSignal }) => {
+        callbackSignal = options?.signal;
+        started();
+        return new Promise(() => {});
+      }
+    );
+    await register("wait", execute);
+    const controller = new AbortController();
+    const pending = bridge().executeToolCall(
+      "webmcp:wait",
+      {},
+      controller.signal
+    );
+    await ready;
+    controller.abort();
+    expect((await pending).isError).toBe(true);
+    expect(execute).toHaveBeenCalledTimes(1);
+    if (!legacy)
+      await vi.waitFor(() => expect(callbackSignal?.aborted).toBe(true));
+  });
+
+  it("does not execute a removed registration", async () => {
+    const execute = vi.fn(() => "unexpected");
+    await register("removed", execute);
+    registrations.at(-1)!.abort();
+    expect((await bridge().executeToolCall("webmcp:removed", {})).isError).toBe(
+      true
+    );
+    expect(execute).not.toHaveBeenCalled();
+  });
+
+  it.runIf(legacy)(
+    "lazily installs the real v5 fallback without v6 browser APIs",
+    async () => {
+      const runtime = (
+        browser as unknown as {
+          WebMCPPolyfill: {
+            cleanupWebMCPPolyfill(): void;
+            initializeWebMCPPolyfill(): void;
+          };
+        }
+      ).WebMCPPolyfill;
+      runtime.cleanupWebMCPPolyfill();
+      expect(
+        (browser.document as unknown as { modelContext?: unknown }).modelContext
+      ).toBeUndefined();
+      expect(Reflect.get(browser.Promise, "withResolvers")).toBeUndefined();
+      expect(browser.AbortSignal.any).toBeUndefined();
+      expect(browser.URL.parse).toBeUndefined();
+      const load = vi.fn(async () => runtime);
+      setWebMcpPolyfillLoader(load);
+      const consumer = bridge();
+      expect(await consumer.snapshotForDispatch()).toEqual([]);
+      context = (browser.document as unknown as { modelContext: TestContext })
+        .modelContext;
+      await register("legacy_fallback", () => undefined);
+      expect(
+        await consumer.executeToolCall("webmcp:legacy_fallback", {})
+      ).toEqual({
+        content: [{ type: "text", text: "undefined" }],
+      });
+      expect(load).toHaveBeenCalledTimes(1);
+      expect(consumer.isOperational()).toBe(true);
+    }
+  );
+});

package/src/webmcp-polyfill.ts

@@ -1,10 +1,13 @@
 /**
- * Standalone WebMCP polyfill chunk (`dist/webmcp-polyfill.js`).
+ * Standalone WebMCP v5 fallback chunk (`dist/webmcp-polyfill.js`).
+ * Keep this fallback on v5 so upgrades do not change existing consumers'
+ * browser requirements or callback-result semantics. Host-installed v6 is
+ * supported separately by the bridge's dual-contract argument adapter.
  *
  * 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
+ * polyfill never ships 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`).
  *

package/src/webmcp-runtime-bundle.test.ts

@@ -48,7 +48,7 @@ describe("webmcp-runtime bundle split", () => {
     }
     // No polyfill inlined: `registerTool` / `cfworker` only exist inside
     // @mcp-b/webmcp-polyfill (the class merely CALLS the injected module's
-    // initializeWebMCPPolyfill, so that name legitimately appears here).
+    // initializer, so both initializer names legitimately appear here).
     expect(chunk.includes("registerTool")).toBe(false);
     expect(chunk.includes("cfworker")).toBe(false);
     // A CJS twin exists for require()-based consumers.