@mcp-ts/sdk 1.3.10 → 1.5.0

package/src/client/core/constants.ts

@@ -0,0 +1,30 @@
+/**
+ * Default configuration values for the App Host.
+ *
+ * `SANDBOX_*_READY_METHOD` match `@modelcontextprotocol/ext-apps` (see
+ * https://github.com/modelcontextprotocol/ext-apps/blob/main/src/types.ts ).
+ * Duplicated here because the package root `app.d.ts` often omits these value exports under
+ * `moduleResolution: "NodeNext"`.
+ */
+export const SANDBOX_PROXY_READY_METHOD = 'ui/notifications/sandbox-proxy-ready' as const;
+export const SANDBOX_RESOURCE_READY_METHOD = 'ui/notifications/sandbox-resource-ready' as const;
+
+export const APP_HOST_DEFAULTS = {
+  /** Default timeout for waiting for the sandbox proxy to be ready (ms). */
+  SANDBOX_TIMEOUT_MS: 10000,
+  
+  /** Default host info reported to guest apps. */
+  HOST_INFO: { name: 'mcp-ts-host', version: '1.0.0' },
+
+  /** Supported MCP App URI schemes. */
+  URI_SCHEMES: ['ui://', 'mcp-app://'] as const,
+
+  /** Default theme for the host context. */
+  THEME: 'dark',
+
+  /** Default platform for the host context. */
+  PLATFORM: 'web',
+
+  /** Default max height for the iframe container (px). */
+  MAX_HEIGHT: 6000,
+} as const;

package/src/client/index.ts

@@ -5,7 +5,12 @@
 
 /** SSE client for real-time connections */
 export { SSEClient, type SSEClientOptions } from './core/sse-client';
-export { AppHost } from './core/app-host';
+export { AppHost, DEFAULT_MCP_APP_CSP } from './core/app-host';
+export {
+  APP_HOST_DEFAULTS,
+  SANDBOX_PROXY_READY_METHOD,
+  SANDBOX_RESOURCE_READY_METHOD,
+} from './core/constants.js';
 
 
 

package/src/client/react/index.ts

@@ -12,7 +12,10 @@ export { useAppHost } from './use-app-host.js';
 // Simplified MCP Apps Hook - the main API
 export {
   useMcpApps,
+  McpAppRenderer,
+  getMcpAppMetadata,
   type McpAppRendererProps,
+  type McpAppRendererHandle,
   type McpAppMetadata,
 } from './use-mcp-apps.js';
 

package/src/client/react/use-app-host.ts

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState, useCallback } from 'react';
-import type { SSEClient } from '../core/sse-client';
-import { AppHost } from '../core/app-host';
+import type { AppHostClient } from '../core/types';
+import { AppHost, type AppHostOptions } from '../core/app-host';
 
 /**
  * Hook to host an MCP App in a React component
@@ -16,19 +16,17 @@ import { AppHost } from '../core/app-host';
  * @param options - Optional configuration
  * @returns Object containing the AppHost instance (or null) and error state
  */
+export type UseAppHostOptions = AppHostOptions;
+
 export function useAppHost(
-    client: SSEClient,
+    client: AppHostClient | null,
     iframeRef: React.RefObject<HTMLIFrameElement>,
-    options?: {
-        /** Callback when the App sends a message (e.g. to chat) */
-        onMessage?: (params: { role: string; content: unknown }) => void;
-    }
+    options?: UseAppHostOptions
 ) {
     const [host, setHost] = useState<AppHost | null>(null);
     const [error, setError] = useState<Error | null>(null);
     const initializingRef = useRef(false);
 
-    // Store latest callback in ref to avoid re-initializing AppHost on callback change
     const onMessageRef = useRef(options?.onMessage);
     useEffect(() => {
         onMessageRef.current = options?.onMessage;
@@ -42,13 +40,8 @@ export function useAppHost(
 
         const initHost = async () => {
             try {
-                // Initialize AppHost with security enforcement
-                const appHost = new AppHost(client, iframeRef.current!);
-
-                // Register message handler
-                appHost.onAppMessage = (params) => {
-                    onMessageRef.current?.(params);
-                };
+                // Initialize AppHost with security enforcement and options
+                const appHost = new AppHost(client, iframeRef.current!, options);
 
                 // Set host immediately so launch can be called
                 // (launch will wait for bridge if needed)

package/src/client/react/use-mcp-apps.tsx

@@ -11,10 +11,16 @@ import React, {
   useRef,
   memo,
   useMemo,
+  forwardRef,
+  useImperativeHandle,
   type MutableRefObject,
 } from 'react';
+import type { UseAppHostOptions } from './use-app-host.js';
 import { useAppHost } from './use-app-host.js';
+import { resolveMetaToolProxy } from '../../shared/meta-tools.js';
 import type { SSEClient } from '../core/sse-client.js';
+import { APP_HOST_DEFAULTS } from '../core/constants.js';
+import type { SandboxConfig } from '../core/app-host.js';
 
 export interface McpClient {
   connections: Array<{
@@ -41,14 +47,27 @@ export interface McpAppMetadata {
   sessionId: string;
 }
 
+/**
+ * Imperative handle for {@link useMcpApps}'s `McpAppRenderer` (via `ref`),
+ * aligned with `@mcp-ui/client`'s `AppRendererHandle.teardownResource`.
+ */
+export interface McpAppRendererHandle {
+  teardownResource: (params?: Record<string, unknown>) => void;
+}
+
 /** Props for {@link useMcpApps}'s `McpAppRenderer` (client is supplied via the hook). */
-export interface McpAppRendererProps {
+export interface McpAppRendererProps extends Pick<UseAppHostOptions, 'sandbox' | 'hostContext' | 'onCallTool' | 'onReadResource' | 'onFallbackRequest' | 'onMessage' | 'onOpenLink' | 'onLoggingMessage' | 'onSizeChanged' | 'onError'> {
   name: string;
-  input?: Record<string, unknown>;
+  client?: McpClient | null;
+  toolResourceUri?: string;
+  html?: string;
+  input?: Record<string, unknown> | null;
   result?: unknown;
-  status: 'executing' | 'inProgress' | 'complete' | 'idle';
-  /** Custom CSS class for the container */
+  status?: 'executing' | 'inProgress' | 'complete' | 'idle';
+  toolInputPartial?: any;
+  toolCancelled?: boolean;
   className?: string;
+  loader?: React.ReactNode;
 }
 
 type McpAppViewProps = McpAppRendererProps & {
@@ -60,28 +79,127 @@ type McpAppViewProps = McpAppRendererProps & {
 };
 
 /** Renders one MCP App in a sandboxed iframe; reads the latest client from `clientRef` each render. */
-const McpAppView = memo(function McpAppView({
-  clientRef,
-  name,
-  input,
-  result,
-  status,
-  className,
-}: McpAppViewProps) {
+const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(function McpAppView(
+  {
+    clientRef,
+    name,
+    toolResourceUri,
+    html,
+    input,
+    result,
+    status = 'idle',
+    toolInputPartial,
+    toolCancelled,
+    sandbox,
+    hostContext,
+    onCallTool,
+    onReadResource,
+    onFallbackRequest,
+    onMessage,
+    onOpenLink,
+    onLoggingMessage,
+    onSizeChanged,
+    onError: onHostError,
+    className,
+    loader,
+  },
+  ref,
+) {
+  
   const mcpClient = clientRef.current;
-  const metadata = getMcpAppMetadata(mcpClient, name);
+  const { toolName: resolvedToolName, args: resolvedInput } = resolveMetaToolProxy(name, input);
+  const metadata = getMcpAppMetadata(mcpClient, resolvedToolName, resolvedInput);
   const sseClient = mcpClient?.sseClient ?? null;
-  const resourceUri = metadata?.resourceUri;
+  const resourceUri = toolResourceUri || metadata?.resourceUri;
   const appSessionId = metadata?.sessionId;
 
   const iframeRef = useRef<HTMLIFrameElement>(null);
-  const { host, error: hostError } = useAppHost(sseClient as SSEClient, iframeRef);
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Tracks the last height (px) reported by the guest before/after fullscreen so we
+  // can restore it when the native fullscreen API exits and the guest fires a stale
+  // resize event that would otherwise collapse the iframe to 0.
+  const preFullscreenHeightRef = useRef<number | null>(null);
+  const displayModeRef = useRef<'inline' | 'fullscreen'>('inline');
+  const [displayMode, setDisplayMode] = useState<'inline' | 'fullscreen'>('inline');
+
+  const setDisplayModeWithRef = (mode: 'inline' | 'fullscreen') => {
+    displayModeRef.current = mode;
+    setDisplayMode(mode);
+  };
+
+  const { host, error: hostError } = useAppHost(sseClient as any, iframeRef, {
+    sandbox,
+    hostContext,
+    onCallTool,
+    onReadResource,
+    onFallbackRequest,
+    onMessage,
+    onOpenLink,
+    onLoggingMessage,
+    // Intercept onSizeChanged: when exiting fullscreen, ignore guest resize events
+    // that arrive with the shrunken viewport dimensions, and restore the pre-fullscreen height.
+    onSizeChanged: (params) => {
+      if (displayModeRef.current === 'inline' && preFullscreenHeightRef.current !== null) {
+        // Guest fired a resize right after fullscreen exit – restore the saved height
+        const savedHeight = preFullscreenHeightRef.current;
+        preFullscreenHeightRef.current = null;
+        if (iframeRef.current) {
+          iframeRef.current.style.height = `${savedHeight}px`;
+        }
+        return;
+      }
+      onSizeChanged?.(params);
+    },
+    onError: onHostError,
+    onRequestDisplayMode: async (params) => {
+      if (params.mode === 'fullscreen') {
+        // Snapshot current iframe height so we can restore on exit
+        if (iframeRef.current) {
+          const h = iframeRef.current.getBoundingClientRect().height;
+          if (h > 0) preFullscreenHeightRef.current = h;
+        }
+        try {
+          if (containerRef.current?.requestFullscreen) {
+            await containerRef.current.requestFullscreen();
+          } else if ((containerRef.current as any)?.webkitRequestFullscreen) {
+            await (containerRef.current as any).webkitRequestFullscreen();
+          }
+          setDisplayModeWithRef('fullscreen');
+        } catch (err) {
+          console.warn('[McpAppHost] requestFullscreen failed:', err);
+          preFullscreenHeightRef.current = null;
+          return { mode: 'inline' };
+        }
+      } else if (params.mode === 'inline') {
+        // Eagerly restore height — don't wait for a guest onsizechange that may never arrive
+        restoreHeightAfterFullscreen();
+        try {
+          if (document.fullscreenElement) {
+            await document.exitFullscreen();
+          }
+        } catch (err) {}
+        setDisplayModeWithRef('inline');
+      }
+      return { mode: params.mode };
+    }
+  });
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      teardownResource: (params?: Record<string, unknown>) => {
+        host?.teardownResource(params ?? {});
+      },
+    }),
+    [host],
+  );
+
   const [isLaunched, setIsLaunched] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
   const sentInputRef = useRef(false);
   const sentResultRef = useRef(false);
-  const lastInputRef = useRef(input);
+  const lastInputRef = useRef(resolvedInput);
   const lastResultRef = useRef(result);
   const lastStatusRef = useRef(status);
 
@@ -90,24 +208,49 @@ const McpAppView = memo(function McpAppView({
     setError(null);
   }, [resourceUri, appSessionId]);
 
+  // Eagerly restore the iframe's pre-fullscreen height at every exit point.
+  // The guest app may NOT fire onSizeChanged after exiting fullscreen, so we cannot
+  // rely on the onSizeChanged interceptor to restore the height.
+  const restoreHeightAfterFullscreen = () => {
+    const savedHeight = preFullscreenHeightRef.current;
+    if (savedHeight && iframeRef.current) {
+      iframeRef.current.style.height = `${savedHeight}px`;
+    }
+    preFullscreenHeightRef.current = null;
+  };
+
   useEffect(() => {
-    if (!host || !resourceUri || !appSessionId) return;
+    const onFullscreenChange = () => {
+      const isFullscreen = !!document.fullscreenElement;
+      // Use ref to avoid stale closure (ESC key exit path)
+      if (!isFullscreen && displayModeRef.current === 'fullscreen') {
+        restoreHeightAfterFullscreen();
+        setDisplayModeWithRef('inline');
+      }
+    };
+    document.addEventListener('fullscreenchange', onFullscreenChange);
+    return () => document.removeEventListener('fullscreenchange', onFullscreenChange);
+  }, []); // stable – reads from refs only, no stale closure over state
+
+  useEffect(() => {
+    if (!host || (!resourceUri && !html)) return;
 
     host
-      .launch(resourceUri, appSessionId)
+      .launch({ uri: resourceUri, html }, appSessionId)
       .then(() => setIsLaunched(true))
       .catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
-  }, [host, resourceUri, appSessionId]);
+  }, [host, resourceUri, html, appSessionId]);
 
+  // Send tool inputs
   useEffect(() => {
-    if (!host || !isLaunched || !resourceUri || !appSessionId || !input) return;
+    if (!host || !isLaunched || !resourceUri || !appSessionId || !resolvedInput) return;
 
-    if (!sentInputRef.current || JSON.stringify(input) !== JSON.stringify(lastInputRef.current)) {
+    if (!sentInputRef.current || JSON.stringify(resolvedInput) !== JSON.stringify(lastInputRef.current)) {
       sentInputRef.current = true;
-      lastInputRef.current = input;
-      host.sendToolInput(input);
+      lastInputRef.current = resolvedInput;
+      host.sendToolInput(resolvedInput);
     }
-  }, [host, isLaunched, input, resourceUri, appSessionId, name]);
+  }, [host, isLaunched, resolvedInput, resourceUri, appSessionId, resolvedToolName]);
 
   useEffect(() => {
     if (!host || !isLaunched || !resourceUri || !appSessionId || result === undefined) return;
@@ -122,7 +265,7 @@ const McpAppView = memo(function McpAppView({
           : result;
       host.sendToolResult(formattedResult);
     }
-  }, [host, isLaunched, result, status, resourceUri, appSessionId, name]);
+  }, [host, isLaunched, result, status, resourceUri, appSessionId, resolvedToolName]);
 
   useEffect(() => {
     if (status === 'executing' && lastStatusRef.current !== 'executing') {
@@ -132,7 +275,30 @@ const McpAppView = memo(function McpAppView({
     lastStatusRef.current = status;
   }, [status]);
 
-  if (!metadata || !sseClient) {
+  useEffect(() => {
+    if (!host) return;
+    // Merge user-provided hostContext with our internal displayMode, then notify the guest.
+    // This causes Excalidraw (and other MCP apps) to switch between inline/fullscreen UI mode.
+    const mergedCtx = {
+      theme: APP_HOST_DEFAULTS.THEME,
+      platform: APP_HOST_DEFAULTS.PLATFORM,
+      containerDimensions: { maxHeight: APP_HOST_DEFAULTS.MAX_HEIGHT },
+      availableDisplayModes: ['inline', 'fullscreen'],
+      ...(hostContext || {}),
+      displayMode, // always override with our authoritative state
+    };
+    host.setHostContext(mergedCtx);
+  }, [host, hostContext, displayMode]);
+
+  useEffect(() => {
+    if (host && toolInputPartial) host.sendToolInputPartial(toolInputPartial);
+  }, [host, toolInputPartial]);
+
+  useEffect(() => {
+    if (host && toolCancelled) host.sendToolCancelled("User cancelled");
+  }, [host, toolCancelled]);
+
+  if (!metadata && !html && !toolResourceUri) {
     return null;
   }
 
@@ -145,48 +311,93 @@ const McpAppView = memo(function McpAppView({
     );
   }
 
+  const opacityClass = isLaunched ? 'opacity-100' : 'opacity-0';
+  let containerClass = `w-full border border-gray-700 rounded bg-transparent my-2 relative ${className || ''}`;
+  let iframeClass = `w-full transition-opacity duration-300 ${opacityClass}`;
+
+  // When native fullscreen is active, the container naturally expands via the browser API.
+  // We only need to satisfy flex layout so the iframe fills 100% of the fullscreen viewport.
+  if (displayMode === 'fullscreen') {
+    containerClass = `w-full h-full bg-black m-0 p-0 flex flex-col relative`;
+    iframeClass = `w-full flex-1 transition-opacity duration-300 ${opacityClass}`;
+  }
+
   return (
-    <div className={`w-full border border-gray-700 rounded overflow-hidden bg-white min-h-96 my-2 relative ${className || ''}`}>
+    <div ref={containerRef} className={containerClass}>
+      {displayMode === 'fullscreen' && (
+        <div className="absolute top-0 right-0 p-2 z-[100000] w-full bg-gradient-to-b from-black/80 to-transparent flex justify-end">
+          <button 
+            title="Exit Fullscreen"
+            onClick={() => {
+              // Eagerly restore height before the browser animation completes
+              restoreHeightAfterFullscreen();
+              if (document.fullscreenElement) document.exitFullscreen();
+              setDisplayModeWithRef('inline');
+            }} 
+            className="px-4 py-2 bg-gray-800 hover:bg-gray-700 text-white rounded-md shadow flex items-center gap-2 border border-gray-600 transition-colors"
+          >
+            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M8 3v3a2 2 0 0 1-2 2H3m18 0h-3a2 2 0 0 1-2-2V3m0 18v-3a2 2 0 0 1 2-2h3M3 16h3a2 2 0 0 1 2 2v3"/></svg>
+            <span className="text-sm font-medium">Exit</span>
+          </button>
+        </div>
+      )}
       <iframe
         ref={iframeRef}
         sandbox="allow-scripts allow-same-origin allow-forms allow-modals allow-popups allow-downloads"
-        className="w-full h-full min-h-96"
-        style={{ height: 'auto' }}
+        allow="fullscreen"
+        className={iframeClass}
         title="MCP App"
       />
-      {!isLaunched && (
-        <div className="absolute inset-0 bg-gray-900/50 flex items-center justify-center pointer-events-none">
-          <div className="w-6 h-6 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
+      {!isLaunched && loader && (
+        <div className="absolute inset-0 bg-transparent flex items-center justify-center pointer-events-none z-10">
+          {loader}
         </div>
       )}
     </div>
   );
 });
 
+const McpAppView = memo(McpAppViewInner);
+McpAppView.displayName = 'McpAppView';
+
+/**
+ * Renders an interactive MCP application inside a sandboxed iframe.
+ */
+export const McpAppRenderer = memo(
+  forwardRef<McpAppRendererHandle, McpAppRendererProps>(function McpAppRenderer(
+    { client, ...props },
+    ref
+  ) {
+    const clientRef = useRef(client || null);
+    clientRef.current = client || null;
+
+    return <McpAppView ref={ref} clientRef={clientRef} {...props} />;
+  })
+);
+
 /**
  * Helpers scoped to one `mcpClient`. Pass the client here once; `McpAppRenderer` only needs per-tool props (`name`, `input`, `result`, `status`).
  *
  * @param mcpClient - From `useMcp()` or context (for example `useMcpContext()`).
+ * @deprecated Use the standalone `<McpAppRenderer>` component and `getMcpAppMetadata` utility directly.
  */
 export function useMcpApps(mcpClient: McpClient | null) {
-  // Stable `McpAppRenderer` type: parent re-renders and `connections` updates must not remount the iframe.
-  const clientRef = useRef(mcpClient);
-  clientRef.current = mcpClient;
-
   const getAppMetadata = useCallback(
-    (toolName: string) => getMcpAppMetadata(clientRef.current, toolName),
-    []
+    (toolName: string) => getMcpAppMetadata(mcpClient, toolName),
+    [mcpClient]
   );
 
-  const McpAppRenderer = useMemo(() => {
-    const Renderer = memo(function McpAppRenderer(props: McpAppRendererProps) {
-      return <McpAppView clientRef={clientRef} {...props} />;
-    });
-    Renderer.displayName = 'McpAppRenderer';
-    return Renderer;
-  }, []);
+  const BoundMcpAppRenderer = useMemo(() => {
+    const Renderer = forwardRef<McpAppRendererHandle, Omit<McpAppRendererProps, 'client'>>(
+      function BoundMcpAppRenderer(props, ref) {
+        return <McpAppRenderer ref={ref} client={mcpClient} {...props} />;
+      }
+    );
+    Renderer.displayName = 'BoundMcpAppRenderer';
+    return memo(Renderer);
+  }, [mcpClient]);
 
-  return { getAppMetadata, McpAppRenderer };
+  return { getAppMetadata, McpAppRenderer: BoundMcpAppRenderer };
 }
 
 function extractToolName(fullName: string): string {
@@ -194,13 +405,15 @@ function extractToolName(fullName: string): string {
   return match?.[1] || fullName;
 }
 
-function getMcpAppMetadata(
+export function getMcpAppMetadata(
   mcpClient: McpClient | null,
-  toolName: string
+  toolName: string,
+  input?: Record<string, unknown> | null
 ): McpAppMetadata | undefined {
   if (!mcpClient) return undefined;
 
-  const extractedName = extractToolName(toolName);
+  const { toolName: proxyToolName } = resolveMetaToolProxy(toolName, input);
+  const extractedName = extractToolName(proxyToolName);
 
   for (const conn of mcpClient.connections) {
     for (const tool of conn.tools) {

package/src/client/react/use-mcp.ts

@@ -343,21 +343,32 @@ export function useMcp(options: UseMcpOptions): McpClient {
         }
 
         case 'auth_required': {
-          // Handle OAuth redirect
-          if (event.authUrl) {
-            onLog?.('info', `OAuth required - redirecting to ${event.authUrl}`, { authUrl: event.authUrl });
-
-            // Suppress redirects/popups for auto-restore on page load.
-            if (!suppressAuthRedirectSessionsRef.current.has(event.sessionId)) {
-              if (onRedirect) {
-                onRedirect(event.authUrl);
-              } else if (typeof window !== 'undefined') {
-                window.location.href = event.authUrl;
-              }
+          const url = (event.authUrl || '').trim();
+          if (!url) {
+            onLog?.('error', 'OAuth required but authorization URL is missing', { sessionId: event.sessionId });
+            return prev.map((c: McpConnection) =>
+              c.sessionId === event.sessionId
+                ? {
+                    ...c,
+                    state: 'FAILED',
+                    error: 'OAuth authorization URL not available',
+                    authUrl: undefined,
+                  }
+                : c
+            );
+          }
+          onLog?.('info', `OAuth required - redirecting to ${url}`, { authUrl: url });
+
+          // Suppress redirects/popups for auto-restore on page load.
+          if (!suppressAuthRedirectSessionsRef.current.has(event.sessionId)) {
+            if (onRedirect) {
+              onRedirect(url);
+            } else if (typeof window !== 'undefined') {
+              window.location.href = url;
             }
           }
           return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: event.authUrl } : c
+            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: url } : c
           );
         }
 

package/src/client/utils/app-host-utils.ts

@@ -0,0 +1,62 @@
+import { APP_HOST_DEFAULTS, SANDBOX_PROXY_READY_METHOD } from '../core/constants.js';
+
+const DEFAULT_SANDBOX_TIMEOUT_MS = APP_HOST_DEFAULTS.SANDBOX_TIMEOUT_MS;
+
+export async function setupSandboxProxyIframe(
+  iframe: HTMLIFrameElement,
+  sandboxProxyUrl: URL
+): Promise<{
+  onReady: Promise<void>;
+}> {
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  iframe.style.border = 'none';
+  iframe.style.backgroundColor = 'transparent';
+  iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-modals allow-popups allow-downloads');
+
+  const onReady = new Promise<void>((resolve, reject) => {
+    let settled = false;
+
+    const cleanup = () => {
+      window.removeEventListener('message', messageListener);
+      iframe.removeEventListener('error', errorListener);
+    };
+
+    const timeoutId = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        cleanup();
+        reject(new Error('Timed out waiting for sandbox proxy iframe to be ready'));
+      }
+    }, DEFAULT_SANDBOX_TIMEOUT_MS);
+
+    const messageListener = (event: MessageEvent) => {
+      if (event.source === iframe.contentWindow) {
+        if (event.data?.method === SANDBOX_PROXY_READY_METHOD) {
+          if (!settled) {
+            settled = true;
+            clearTimeout(timeoutId);
+            cleanup();
+            resolve();
+          }
+        }
+      }
+    };
+
+    const errorListener = () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeoutId);
+        cleanup();
+        reject(new Error('Failed to load sandbox proxy iframe'));
+      }
+    };
+
+    window.addEventListener('message', messageListener);
+    iframe.addEventListener('error', errorListener);
+  });
+
+  iframe.src = sandboxProxyUrl.href;
+
+  return { onReady };
+}