feat(studio): fall back to a WebMCP polyfill where the browser has none

WebMCP is an Origin Trial. Chrome 149 and Edge 150 have it behind a flag,
ChatGPT Desktop ships it, and everything else does not. Without a fallback the
tools registered in the previous change are invisible on stable Chrome, which
is exactly where a bridge extension would connect from.

Adds `@mcp-b/global` (MIT) as a DYNAMIC import, so a browser with native
support never fetches it. Verified in the build output rather than asserted:
the bundle keeps a bare `import("@mcp-b/global")` instead of inlining it.

Chosen over the smaller `@mcp-b/webmcp-polyfill` because that one only defines
`document.modelContext`. `@mcp-b/global` also stands up the in-page MCP server
a bridge extension attaches to, and serving that case is the only reason the
fallback exists at all.

The load is guarded by a module-level promise so two mounts racing share one
load, and an import failure is caught and logged rather than thrown: a missing
agent surface must never stop Studio booting. The registration path re-checks
the abort signal after the await, so unmounting mid-import registers nothing.

Two things the type checker forced, both worth keeping:

Installing the package brings its own global `Document.modelContext`
declaration, which collided with the local one. Studio now reads the property
through a type guard instead of augmenting `Document`, so there is only one
declaration of that global and it is the package's.

Studio keeps its own narrow tool types rather than importing the package's.
Theirs overload `registerTool` to infer argument types from a literal
`inputSchema`, which helps when registering one tool inline and fights a
uniform registration loop. The comment in `types.ts` says so, and names the
drift risk that choice accepts.

The polyfill test asserts promise identity rather than counting imports. The
ESM registry dedupes the import either way, so a call count would pass whether
or not the guard existed.

Author: miguel-heygen

bun.lock

@@ -71,6 +71,7 @@
     "@hyperframes/player": "workspace:*",
     "@hyperframes/sdk": "workspace:*",
     "@hyperframes/studio-server": "workspace:*",
+    "@mcp-b/global": "^5.0.1",
     "@phosphor-icons/react": "^2.1.10",
     "@tanstack/react-virtual": "^3.14.6",
     "bpm-detective": "^2.0.5",

packages/studio/package.json

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { loadModelContextPolyfill, resetModelContextPolyfillForTest } from "./polyfill";
+import type { ModelContext } from "./types";
+
+// The real package defines `document.modelContext` as an import side effect.
+// A mock cannot do that, so tests stand the object up themselves to represent
+// the import having happened.
+vi.mock("@mcp-b/global", () => ({}));
+
+function installModelContext(): ModelContext {
+  const modelContext: ModelContext = { registerTool: vi.fn().mockResolvedValue(undefined) };
+  Object.defineProperty(document, "modelContext", {
+    value: modelContext,
+    configurable: true,
+    writable: true,
+  });
+  return modelContext;
+}
+
+beforeEach(() => {
+  resetModelContextPolyfillForTest();
+});
+
+afterEach(() => {
+  Reflect.deleteProperty(document, "modelContext");
+  vi.restoreAllMocks();
+});
+
+describe("loadModelContextPolyfill", () => {
+  it("returns the model context the package defines", async () => {
+    const modelContext = installModelContext();
+
+    await expect(loadModelContextPolyfill()).resolves.toBe(modelContext);
+  });
+
+  it("shares one load between callers that race", async () => {
+    installModelContext();
+
+    // Identity, not a call count: the guard being tested is the module-level
+    // promise, and the ESM registry would dedupe the import either way.
+    const first = loadModelContextPolyfill();
+    const second = loadModelContextPolyfill();
+
+    expect(first).toBe(second);
+    await expect(first).resolves.toBe(await second);
+  });
+
+  it("reuses the settled load rather than starting another", async () => {
+    installModelContext();
+
+    const first = loadModelContextPolyfill();
+    await first;
+
+    expect(loadModelContextPolyfill()).toBe(first);
+  });
+
+  it("returns null when the package loads but defines nothing", async () => {
+    // Studio must still boot. A missing agent surface is not a broken editor.
+    await expect(loadModelContextPolyfill()).resolves.toBeNull();
+  });
+
+  it("starts a fresh load after the test seam resets it", async () => {
+    installModelContext();
+    const first = loadModelContextPolyfill();
+    await first;
+
+    resetModelContextPolyfillForTest();
+
+    expect(loadModelContextPolyfill()).not.toBe(first);
+  });
+});

packages/studio/src/webmcp/polyfill.test.ts

@@ -0,0 +1,50 @@
+/**
+ * The fallback for browsers that have not shipped WebMCP.
+ *
+ * `@mcp-b/global` does two things: it defines `document.modelContext`, and it
+ * stands up an in-page MCP server for a bridge extension to attach to. The
+ * second is the reason this is the chosen package over the bare
+ * `@mcp-b/webmcp-polyfill`: without the server there is nothing for an
+ * out-of-browser agent to connect to, which is the only case the fallback
+ * exists to serve.
+ *
+ * It is a DYNAMIC import so a browser with native support never downloads it,
+ * and so it lands in its own chunk rather than the entry bundle.
+ */
+
+import { makeStudioDebugLogger } from "../utils/studioDebug";
+import { getModelContext, type ModelContext } from "./types";
+
+const log = makeStudioDebugLogger("webmcp");
+
+/**
+ * Module-level, so two mounts racing (React StrictMode, or a remount during
+ * the import) share one load instead of pulling the package twice.
+ */
+let pending: Promise<ModelContext | null> | null = null;
+
+async function importPolyfill(): Promise<ModelContext | null> {
+  try {
+    await import("@mcp-b/global");
+    const modelContext = getModelContext();
+    if (!modelContext) {
+      // The package loaded but did not define what it promises to define.
+      log("polyfill", { loaded: true, modelContext: false });
+    }
+    return modelContext;
+  } catch (error) {
+    // A missing agent surface must never break Studio's boot.
+    log("polyfill", { failed: error instanceof Error ? error.message : String(error) });
+    return null;
+  }
+}
+
+export function loadModelContextPolyfill(): Promise<ModelContext | null> {
+  pending ??= importPolyfill();
+  return pending;
+}
+
+/** Test seam. Nothing in production resets this. */
+export function resetModelContextPolyfillForTest(): void {
+  pending = null;
+}

packages/studio/src/webmcp/polyfill.ts

@@ -1,5 +1,5 @@
 /**
- * Local typings for the WebMCP browser API, which is not in lib.dom yet.
+ * The slice of the WebMCP browser API that Studio uses.
  *
  * Mirrors the WebIDL in the W3C spec (`webmachinelearning/webmcp`, `index.bs`)
  * as of 2026-08-26. Two things worth knowing before editing this file:
@@ -11,8 +11,15 @@
  *   only places that touch the API, so a spec change is a two-file edit. Re-read
  *   `index.bs` rather than trusting this transcription.
  *
- * Only the surface Studio actually uses is declared. `getTools` and
+ * Only the surface Studio registers against is declared. `getTools` and
  * `executeTool` are the consumer side; Studio registers, it does not call.
+ *
+ * These stay hand-written rather than imported from `@mcp-b/webmcp-types`,
+ * which the polyfill pulls in. That package's `registerTool` is overloaded to
+ * infer argument types from a literal `inputSchema`, which is useful when you
+ * register one tool inline and actively hostile when you register a uniform
+ * list of them, as `registerStudioTools` does. Narrower is the safe operation
+ * here. It does mean this file can drift from the spec, hence the note above.
  */
 
 export interface ModelContextToolAnnotations {
@@ -24,9 +31,9 @@ export interface ModelContextToolAnnotations {
 
 export interface ToolExecuteCallbackOptions {
   /**
-   * Aborted when the caller cancels. Note that Studio's commit path is not
-   * cancellable once dispatched, so tools check this BEFORE dispatching and
-   * document that a late abort does not unwind a write.
+   * Aborted when the caller cancels. Studio's commit path is not cancellable
+   * once dispatched, so tools check this BEFORE dispatching and document that a
+   * late abort does not unwind a write.
    */
   signal: AbortSignal;
 }
@@ -65,12 +72,19 @@ export interface ModelContext {
   registerTool(tool: ModelContextTool, options?: ModelContextRegisterToolOptions): Promise<void>;
 }
 
-interface DocumentWithModelContext extends Document {
-  modelContext?: ModelContext;
+function isModelContext(value: unknown): value is ModelContext {
+  if (typeof value !== "object" || value === null) return false;
+  return typeof Reflect.get(value, "registerTool") === "function";
 }
 
-/** The live WebMCP entry point, or null when this browser has not shipped it. */
+/**
+ * The live WebMCP entry point, or null when this browser has not shipped it.
+ *
+ * Reads through a guard rather than augmenting the `Document` interface. The
+ * polyfill's typings already declare `Document.modelContext` globally, and a
+ * second, narrower declaration of the same property is a type error.
+ */
 export function getModelContext(doc: Document = document): ModelContext | null {
-  const candidate = (doc as DocumentWithModelContext).modelContext;
-  return typeof candidate?.registerTool === "function" ? candidate : null;
+  const candidate = Reflect.get(doc, "modelContext");
+  return isModelContext(candidate) ? candidate : null;
 }