@agent-native/toolkit 0.209.2 → 0.209.3-nightly-20261016212700

package/src/app/extensions/ExtensionViewer.spec.tsx

@@ -127,6 +127,7 @@ describe("ExtensionViewer MCP embeds", () => {
     act(() => root.unmount());
     queryClient.clear();
     container.remove();
+    vi.restoreAllMocks();
     vi.unstubAllGlobals();
   });
 
@@ -158,6 +159,96 @@ describe("ExtensionViewer MCP embeds", () => {
     );
   });
 
+  it("opens links only for the shell document that announced the binding", async () => {
+    document.body.appendChild(container);
+    const iframe = await renderViewer();
+    const frameWindow = iframe.contentWindow as Window;
+    expect(frameWindow).toBeTruthy();
+    const replies: unknown[] = [];
+    vi.spyOn(frameWindow, "postMessage").mockImplementation((data: unknown) => {
+      replies.push(data);
+    });
+    const open = vi.spyOn(window, "open").mockImplementation(() => null);
+    const post = (data: unknown) =>
+      act(() => {
+        window.dispatchEvent(
+          new MessageEvent("message", { data, source: frameWindow }),
+        );
+      });
+    const token = "a".repeat(32);
+    const url = "https://app.hubspot.com/contacts/1/company/2";
+
+    post({ type: "agent-native-extension-open-url", url, token });
+    expect(open).not.toHaveBeenCalled();
+
+    post({
+      type: "agent-native-extension-binding",
+      binding: { role: "viewer" },
+      openUrlToken: token,
+    });
+    expect(replies).toContainEqual({
+      type: "agent-native-extension-open-url-ready",
+    });
+
+    // A page the iframe navigated to can't re-announce or guess the token.
+    post({
+      type: "agent-native-extension-binding",
+      binding: { role: "owner" },
+      openUrlToken: "b".repeat(32),
+    });
+    post({
+      type: "agent-native-extension-open-url",
+      url,
+      token: "b".repeat(32),
+    });
+    post({ type: "agent-native-extension-open-url", url });
+    post({
+      type: "agent-native-extension-open-url",
+      url: "javascript:alert(1)",
+      token,
+    });
+    expect(open).not.toHaveBeenCalled();
+
+    post({ type: "agent-native-extension-open-url", url, token });
+    expect(open).toHaveBeenCalledTimes(1);
+    expect(open).toHaveBeenCalledWith(url, "_blank", "noopener,noreferrer");
+  });
+
+  it("leaves links native inside MCP chat embeds, where the host can't escape the sandbox either", async () => {
+    embedState.active = true;
+    document.body.appendChild(container);
+    const iframe = await renderViewer();
+    const frameWindow = iframe.contentWindow as Window;
+    const replies: unknown[] = [];
+    vi.spyOn(frameWindow, "postMessage").mockImplementation((data: unknown) => {
+      replies.push(data);
+    });
+    const open = vi.spyOn(window, "open").mockImplementation(() => null);
+    const token = "d".repeat(32);
+    const post = (data: unknown) =>
+      act(() => {
+        window.dispatchEvent(
+          new MessageEvent("message", { data, source: frameWindow }),
+        );
+      });
+
+    post({
+      type: "agent-native-extension-binding",
+      binding: { role: "viewer" },
+      openUrlToken: token,
+    });
+    post({
+      type: "agent-native-extension-open-url",
+      url: "https://example.com/",
+      token,
+    });
+
+    expect(replies).not.toContainEqual({
+      type: "agent-native-extension-open-url-ready",
+    });
+    expect(open).not.toHaveBeenCalled();
+  });
+
   it("uses sandboxed srcdoc inside MCP chat embeds to avoid a blocked nested route frame", async () => {
     embedState.active = true;
     const iframe = await renderViewer();
@@ -215,11 +306,18 @@ describe("ExtensionViewer MCP embeds", () => {
     await act(async () => {
       resolveSources(Response.json(displaySourcesResponse));
     });
+    // The real document gets a fresh iframe element (a new window), so look
+    // it up again rather than reusing the blank frame's.
+    const loadedFrame = () =>
+      container.querySelector("iframe") as HTMLIFrameElement;
     await vi.waitFor(() => {
-      expect(iframe.getAttribute("srcdoc")).toContain("Star history chart");
+      expect(loadedFrame().getAttribute("srcdoc")).toContain(
+        "Star history chart",
+      );
     });
+    expect(spinner()).toBeTruthy();
     await act(async () => {
-      iframe.dispatchEvent(new Event("load"));
+      loadedFrame().dispatchEvent(new Event("load"));
       await new Promise((resolve) => setTimeout(resolve, 200));
     });
     expect(spinner()).toBeNull();

package/src/app/extensions/ExtensionViewer.tsx

@@ -66,6 +66,11 @@ import {
   type ExtensionBridgeRole,
 } from "./iframe-bridge.js";
 import { useExtensionIframeMetaCsp } from "./iframe-display-sources.js";
+import {
+  EXTENSION_OPEN_URL_MESSAGE,
+  useExtensionFrameKey,
+  useOpenUrlLatch,
+} from "./open-extension-link.js";
 import { normalizeAgentNativeExtensionSandbox } from "./portable-extension.js";
 
 const THEME_CSS_VARS = [
@@ -737,6 +742,7 @@ export function ExtensionViewer({
     isAuthor: false,
   });
   const bindingLatchedRef = useRef(false);
+  const openUrl = useOpenUrlLatch();
 
   useEffect(() => {
     setIsDark(document.documentElement.classList.contains("dark"));
@@ -776,6 +782,9 @@ export function ExtensionViewer({
       if (!message) return;
 
       if (message.type === "agent-native-extension-binding") {
+        // Inside an MCP chat embed this page is itself sandboxed, so its
+        // window.open can't escape either; leave links native there.
+        openUrl.latch(message, event.source, !isEmbedMcpChatBridgeActive());
         if (bindingLatchedRef.current) return;
         bindingLatchedRef.current = true;
         const binding = message.binding ?? {};
@@ -812,6 +821,11 @@ export function ExtensionViewer({
         return;
       }
 
+      if (message.type === EXTENSION_OPEN_URL_MESSAGE) {
+        openUrl.open(message);
+        return;
+      }
+
       if (message.type === "agent-native-send-to-chat") {
         const text = serializeChatValue(message.message);
         if (!text?.trim()) return;
@@ -985,7 +999,7 @@ export function ExtensionViewer({
 
     window.addEventListener("message", handleMessage);
     return () => window.removeEventListener("message", handleMessage);
-  }, [extensionId, queryClient]);
+  }, [extensionId, openUrl, queryClient]);
 
   const {
     data: extension,
@@ -1060,6 +1074,10 @@ export function ExtensionViewer({
     if (!extension || !usesSrcDoc || !iframeMetaCsp) return undefined;
     return buildExtensionViewerSrcDoc(extension, isDark, iframeMetaCsp);
   }, [extension, iframeMetaCsp, isDark, usesSrcDoc]);
+
+  const frameKey = useExtensionFrameKey(
+    `${extensionId}|${extension?.updatedAt}|${refreshKey}|${usesSrcDoc ? "" : iframeSrc}|${iframeSrcDoc ?? ""}`,
+  );
   const unavailableStatus = extensionLoadErrorStatus(
     extensionError ?? extensionFailureReason,
   );
@@ -1287,7 +1305,7 @@ export function ExtensionViewer({
           <iframe
             {...{ [SESSION_REPLAY_IFRAME_ATTRIBUTE]: "" }}
             ref={iframeRef}
-            key={`${extension.updatedAt}-${refreshKey}`}
+            key={`${extension.updatedAt}-${refreshKey}-${frameKey}`}
             src={usesSrcDoc ? undefined : iframeSrc}
             srcDoc={iframeSrcDoc}
             className="h-full w-full border-0"

package/src/app/extensions/InlineExtensionFrame.spec.tsx

@@ -43,6 +43,7 @@ describe("InlineExtensionFrame", () => {
   afterEach(() => {
     act(() => root.unmount());
     container.remove();
+    vi.restoreAllMocks();
     vi.unstubAllGlobals();
   });
 
@@ -253,6 +254,141 @@ describe("InlineExtensionFrame", () => {
     });
   });
 
+  it("keeps opening links with the live document's token after a re-render that doesn't reload it", async () => {
+    const open = vi.spyOn(window, "open").mockImplementation(() => null);
+    const extension = {
+      id: "inline-links",
+      mode: "transient" as const,
+      name: "Links",
+      content: '<a href="https://app.hubspot.com/x" target="_blank">x</a>',
+    };
+    await act(async () => {
+      root.render(
+        <InlineExtensionFrame extension={extension} initialHeight={200} />,
+      );
+    });
+    const iframe = container.querySelector("iframe");
+    const frameWindow = iframe?.contentWindow as Window;
+    const post = (data: unknown) =>
+      act(() => {
+        window.dispatchEvent(
+          new MessageEvent("message", { source: frameWindow, data }),
+        );
+      });
+    const token = "c".repeat(32);
+    post({
+      type: "agent-native-extension-binding",
+      binding: { role: "owner", isAuthor: true },
+      openUrlToken: token,
+    });
+
+    // initialHeight resets the binding latch, but the iframe keeps its document.
+    await act(async () => {
+      root.render(
+        <InlineExtensionFrame extension={extension} initialHeight={320} />,
+      );
+    });
+    expect(container.querySelector("iframe")?.contentWindow).toBe(frameWindow);
+
+    post({
+      type: "agent-native-extension-open-url",
+      url: "https://app.hubspot.com/x",
+      token,
+    });
+    expect(open).toHaveBeenCalledWith(
+      "https://app.hubspot.com/x",
+      "_blank",
+      "noopener,noreferrer",
+    );
+  });
+
+  it("binds the open-url token to the document the host loaded, not to re-renders", async () => {
+    const open = vi.spyOn(window, "open").mockImplementation(() => null);
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const extension = {
+      id: "inline-links-doc",
+      mode: "transient" as const,
+      name: "Links",
+      content: '<a href="https://app.hubspot.com/x" target="_blank">x</a>',
+    };
+    const render = async (props: {
+      content?: string;
+      initialHeight?: number;
+    }) =>
+      act(async () => {
+        root.render(
+          <InlineExtensionFrame
+            extension={{
+              ...extension,
+              content: props.content ?? extension.content,
+            }}
+            initialHeight={props.initialHeight ?? 200}
+          />,
+        );
+      });
+    const post = (data: unknown) =>
+      act(() => {
+        window.dispatchEvent(
+          new MessageEvent("message", {
+            source: container.querySelector("iframe")?.contentWindow,
+            data,
+          }),
+        );
+      });
+    const bind = (token: string) =>
+      post({
+        type: "agent-native-extension-binding",
+        binding: { role: "owner", isAuthor: true },
+        openUrlToken: token,
+      });
+    const openWith = (token: string) =>
+      post({
+        type: "agent-native-extension-open-url",
+        url: "https://example.com/",
+        token,
+      });
+
+    await render({});
+    bind("a".repeat(32));
+
+    // The frame navigated to another page, then a host-only re-render reset
+    // the binding latch. That page's binding must not latch a new token.
+    const firstFrame = container.querySelector("iframe");
+    await render({ initialHeight: 320 });
+    expect(container.querySelector("iframe")).toBe(firstFrame);
+    bind("b".repeat(32));
+    openWith("b".repeat(32));
+    expect(open).not.toHaveBeenCalled();
+
+    // New content is a new document from the host, in a fresh iframe element.
+    // A binding still queued from the previous document's window is ignored,
+    // and the new document's token latches.
+    // (Browsers keep one window per iframe element across its documents, so
+    // the element itself must be new; happy-dom swaps windows on srcdoc
+    // changes regardless, which is why this checks the element.)
+    const previousFrame = container.querySelector("iframe");
+    const previousWindow = previousFrame?.contentWindow;
+    await render({ content: "<a href='https://example.com/'>y</a>" });
+    expect(container.querySelector("iframe")).not.toBe(previousFrame);
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          source: previousWindow,
+          data: {
+            type: "agent-native-extension-binding",
+            binding: { role: "owner", isAuthor: true },
+            openUrlToken: "d".repeat(32),
+          },
+        }),
+      );
+    });
+    bind("c".repeat(32));
+    openWith("d".repeat(32));
+    expect(open).not.toHaveBeenCalled();
+    openWith("c".repeat(32));
+    expect(open).toHaveBeenCalledTimes(1);
+  });
+
   it("dispatches passive output events from generated UI", async () => {
     await act(async () => {
       root.render(

package/src/app/extensions/InlineExtensionFrame.tsx

@@ -14,6 +14,11 @@ import {
   type ExtensionBridgeRole,
 } from "./iframe-bridge.js";
 import { useExtensionIframeMetaCsp } from "./iframe-display-sources.js";
+import {
+  EXTENSION_OPEN_URL_MESSAGE,
+  useExtensionFrameKey,
+  useOpenUrlLatch,
+} from "./open-extension-link.js";
 import { normalizeAgentNativeExtensionSandbox } from "./portable-extension.js";
 
 const THEME_CSS_VARS = [
@@ -339,6 +344,7 @@ export function InlineExtensionFrame({
     isAuthor: !!providedExtension?.content,
   });
   const bindingLatchedRef = useRef(false);
+  const openUrl = useOpenUrlLatch();
   const [fetchedExtension, setFetchedExtension] =
     useState<InlineExtensionDefinition | null>(null);
   const [isLoading, setIsLoading] = useState(false);
@@ -412,6 +418,10 @@ export function InlineExtensionFrame({
     );
   }, [extension, iframeMetaCsp, isTransient]);
 
+  const frameKey = useExtensionFrameKey(
+    `${resolvedId}|${extension?.updatedAt ?? "inline"}|${isTransient}|${iframeSrc ?? ""}|${srcDoc ?? ""}`,
+  );
+
   useEffect(() => {
     bridgeContextRef.current = isTransient
       ? { role: "owner", isAuthor: true }
@@ -466,6 +476,7 @@ export function InlineExtensionFrame({
       if (!message || typeof message !== "object") return;
 
       if (message.type === "agent-native-extension-binding") {
+        openUrl.latch(message, event.source);
         if (bindingLatchedRef.current) return;
         bindingLatchedRef.current = true;
         const binding = (message as any).binding ?? {};
@@ -506,6 +517,11 @@ export function InlineExtensionFrame({
         return;
       }
 
+      if (message.type === EXTENSION_OPEN_URL_MESSAGE) {
+        openUrl.open(message);
+        return;
+      }
+
       if (message.type === "agent-native-send-to-chat") {
         const text = serializeChatValue((message as any).message);
         if (!text?.trim()) return;
@@ -655,7 +671,7 @@ export function InlineExtensionFrame({
 
     window.addEventListener("message", handleMessage);
     return () => window.removeEventListener("message", handleMessage);
-  }, [extension, isTransient, resolvedId]);
+  }, [extension, isTransient, openUrl, resolvedId]);
 
   if (!extension) {
     if (!isLoading) return null;
@@ -673,7 +689,7 @@ export function InlineExtensionFrame({
       <iframe
         {...{ [SESSION_REPLAY_IFRAME_ATTRIBUTE]: "" }}
         ref={iframeRef}
-        key={`${resolvedId}-${extension.updatedAt ?? "inline"}-${isTransient ? "transient" : "persisted"}`}
+        key={`${resolvedId}-${extension.updatedAt ?? "inline"}-${isTransient ? "transient" : "persisted"}-${frameKey}`}
         src={iframeSrc}
         srcDoc={srcDoc}
         title={extension.name}

package/src/app/extensions/open-extension-link.spec.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createOpenUrlLatch,
+  openExtensionLink,
+  readOpenUrlToken,
+} from "./open-extension-link.js";
+
+const TOKEN = "0123456789abcdef0123456789abcdef";
+
+describe("openExtensionLink", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("opens web links in a new tab without an opener", () => {
+    const open = vi.fn();
+    vi.stubGlobal("window", { open });
+    const url = "https://app.hubspot.com/contacts/1/company/2";
+
+    expect(openExtensionLink({ url, token: TOKEN }, TOKEN)).toBe(true);
+    expect(open).toHaveBeenCalledWith(url, "_blank", "noopener,noreferrer");
+  });
+
+  it("refuses and warns about requests without the latched token", () => {
+    const open = vi.fn();
+    vi.stubGlobal("window", { open });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const url = "https://example.com/";
+
+    expect(openExtensionLink({ url }, TOKEN)).toBe(false);
+    expect(openExtensionLink({ url, token: "other" }, TOKEN)).toBe(false);
+    expect(openExtensionLink({ url, token: TOKEN }, null)).toBe(false);
+    expect(openExtensionLink(null, TOKEN)).toBe(false);
+    expect(open).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledTimes(4);
+  });
+
+  it("refuses and warns about anything that isn't an http(s) URL", () => {
+    const open = vi.fn();
+    vi.stubGlobal("window", { open });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const urls = [
+      "javascript:alert(1)",
+      "data:text/html,<script>alert(1)</script>",
+      "blob:https://example.com/1",
+      "/relative/path",
+      "",
+      42,
+      undefined,
+    ];
+
+    for (const url of urls) {
+      expect(openExtensionLink({ url, token: TOKEN }, TOKEN)).toBe(false);
+    }
+    expect(open).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledTimes(urls.length);
+  });
+});
+
+describe("readOpenUrlToken", () => {
+  it("only latches a 32-character hex token", () => {
+    expect(readOpenUrlToken({ openUrlToken: TOKEN })).toBe(TOKEN);
+    expect(readOpenUrlToken({ openUrlToken: TOKEN.toUpperCase() })).toBeNull();
+    expect(readOpenUrlToken({ openUrlToken: "short" })).toBeNull();
+    expect(readOpenUrlToken({ openUrlToken: `${TOKEN}0` })).toBeNull();
+    expect(readOpenUrlToken({ openUrlToken: "" })).toBeNull();
+    expect(readOpenUrlToken({ openUrlToken: 42 })).toBeNull();
+    expect(readOpenUrlToken(null)).toBeNull();
+  });
+});
+
+describe("createOpenUrlLatch", () => {
+  const OTHER = "fedcba9876543210fedcba9876543210";
+  const READY = { type: "agent-native-extension-open-url-ready" };
+  const frameWindow = () => ({ postMessage: vi.fn() }) as unknown as Window;
+  const binding = (openUrlToken: string) => ({
+    type: "agent-native-extension-binding",
+    openUrlToken,
+  });
+  const request = (token: string) => ({ url: "https://example.com/", token });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("latches a window's first binding and ignores later ones from it", () => {
+    const open = vi.fn();
+    vi.stubGlobal("window", { open });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const latch = createOpenUrlLatch();
+    const frame = frameWindow();
+
+    latch.latch(binding(TOKEN), frame);
+    // A page the frame navigated to re-announces from the same window.
+    latch.latch(binding(OTHER), frame);
+
+    expect(frame.postMessage).toHaveBeenCalledTimes(1);
+    expect(frame.postMessage).toHaveBeenCalledWith(READY, "*");
+    expect(latch.open(request(OTHER))).toBe(false);
+    expect(latch.open(request(TOKEN))).toBe(true);
+    expect(open).toHaveBeenCalledTimes(1);
+  });
+
+  it("latches afresh for a new iframe window, however it was mounted", () => {
+    const open = vi.fn();
+    vi.stubGlobal("window", { open });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const latch = createOpenUrlLatch();
+    const first = frameWindow();
+    const remounted = frameWindow();
+
+    latch.latch(binding(TOKEN), first);
+    latch.latch(binding(OTHER), remounted);
+
+    expect(remounted.postMessage).toHaveBeenCalledWith(READY, "*");
+    expect(latch.open(request(OTHER))).toBe(true);
+    // The old window's token no longer opens anything.
+    expect(latch.open(request(TOKEN))).toBe(false);
+    expect(open).toHaveBeenCalledTimes(1);
+  });
+
+  it("never opens or offers to when disabled or the binding has no token", () => {
+    const open = vi.fn();
+    vi.stubGlobal("window", { open });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const disabled = createOpenUrlLatch();
+    const frame = frameWindow();
+    disabled.latch(binding(TOKEN), frame, false);
+    const tokenless = createOpenUrlLatch();
+    const other = frameWindow();
+    tokenless.latch({ type: "agent-native-extension-binding" }, other);
+
+    expect(frame.postMessage).not.toHaveBeenCalled();
+    expect(other.postMessage).not.toHaveBeenCalled();
+    expect(disabled.open(request(TOKEN))).toBe(false);
+    expect(open).not.toHaveBeenCalled();
+  });
+});

package/src/app/extensions/open-extension-link.ts

@@ -0,0 +1,94 @@
+import { useMemo } from "react";
+
+export const EXTENSION_OPEN_URL_MESSAGE = "agent-native-extension-open-url";
+export const EXTENSION_OPEN_URL_READY_MESSAGE =
+  "agent-native-extension-open-url-ready";
+
+const OPEN_URL_TOKEN_RE = /^[0-9a-f]{32}$/;
+
+// The extension shell announces a random token with its binding, before any
+// extension code runs. Hosts latch it with the binding and only honor
+// open-url requests that carry it, so a page the iframe navigated to can't
+// use this. A binding without a valid token means the shell can't route
+// links, so the host doesn't offer to.
+export function readOpenUrlToken(message: unknown): string | null {
+  const token = (message as { openUrlToken?: unknown } | null)?.openUrlToken;
+  return typeof token === "string" && OPEN_URL_TOKEN_RE.test(token)
+    ? token
+    : null;
+}
+
+// Tells the shell this host opens links, so it starts routing them here.
+export function announceOpenUrlSupport(source: MessageEventSource | null) {
+  (source as Window | null)?.postMessage?.(
+    { type: EXTENSION_OPEN_URL_READY_MESSAGE },
+    "*",
+  );
+}
+
+// Opens a link on behalf of a sandboxed extension iframe. A tab the iframe
+// opened itself would inherit its sandbox (an opaque origin, so apps like
+// HubSpot render blank); opening from the host gives a normal tab, and
+// noopener keeps that tab from reaching back into the host page.
+export function openExtensionLink(
+  message: unknown,
+  expectedToken: string | null,
+): boolean {
+  const { url, token } = (message ?? {}) as { url?: unknown; token?: unknown };
+  if (!expectedToken || token !== expectedToken) {
+    console.warn(
+      "[extensions] Ignored an open-url request without this frame's token.",
+    );
+    return false;
+  }
+  const parsed =
+    typeof url === "string" && URL.canParse(url) ? new URL(url) : null;
+  if (
+    !parsed ||
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+  ) {
+    console.warn("[extensions] Ignored an open-url request for a non-web URL.");
+    return false;
+  }
+  window.open(parsed.href, "_blank", "noopener,noreferrer");
+  return true;
+}
+
+// Binds link opening to one iframe window: the first binding from a window
+// latches its token, later bindings from that window are ignored (a page the
+// frame navigated to can't latch its own), and open-url requests must carry
+// the latched token. A new iframe element is a new window, so it latches
+// afresh (replacing the token) however it came to be mounted. Hosts must
+// only pass messages whose event.source is their current iframe's window.
+export function createOpenUrlLatch() {
+  let latchedWindow: MessageEventSource | null = null;
+  let token: string | null = null;
+  return {
+    latch(message: unknown, source: MessageEventSource | null, enabled = true) {
+      if (!source || source === latchedWindow) return;
+      latchedWindow = source;
+      token = enabled ? readOpenUrlToken(message) : null;
+      if (token) announceOpenUrlSupport(source);
+    },
+    open(message: unknown) {
+      return openExtensionLink(message, token);
+    },
+  };
+}
+
+export function useOpenUrlLatch() {
+  return useMemo(createOpenUrlLatch, []);
+}
+
+let frameDocuments = 0;
+
+// A key for the iframe's `key` that changes whenever `documentIdentity`
+// (whatever determines the frame's document: its src, srcdoc or key) does.
+// The frame's window outlives its documents, so without a new element a new
+// document would share the window the latch already holds. A new element is
+// a new window, so the new document latches its own token and messages from
+// any earlier document fail the hosts' event.source check.
+export function useExtensionFrameKey(documentIdentity: string): string {
+  // oxlint-disable-next-line react-hooks/exhaustive-deps -- a new document is what makes a new key
+  return useMemo(() => `doc-${++frameDocuments}`, [documentIdentity]);
+}