feat: send render data to the iframe (#51)

Author: liady

README.md

@@ -88,6 +88,7 @@ It accepts the following props:
 - **`htmlProps`**: Optional props for the internal `<HTMLResourceRenderer>`
   - **`style`**: Optional custom styles for the iframe
   - **`iframeProps`**: Optional props passed to the iframe element
+  - **`iframeRenderData`**: Optional `Record<string, unknown>` to pass data to the iframe upon rendering. This enables advanced use cases where the parent application needs to provide initial state or configuration to the sandboxed iframe content.
 - **`remoteDomProps`**: Optional props for the internal `<RemoteDOMResourceRenderer>`
   - **`library`**: Optional component library for Remote DOM resources (defaults to `basicComponentLibrary`)
   - **`remoteElements`**: remote element definitions for Remote DOM resources.

docs/src/guide/client/resource-renderer.md

@@ -50,6 +50,7 @@ interface UIResourceRendererProps {
   - **`proxy`**: Optional. A URL to a static "proxy" script for rendering external URLs. See [Using a Proxy for External URLs](./using-a-proxy.md) for details.
   - **`iframeProps`**: Optional props passed to iframe elements (for HTML/URL resources)
     - **`ref`**: Optional React ref to access the underlying iframe element
+  - **`iframeRenderData`**: Optional `Record<string, unknown>` to pass data to the iframe upon rendering. This enables advanced use cases where the parent application needs to provide initial state or configuration to the sandboxed iframe content.
 - **`remoteDomProps`**: Optional props for the `<RemoteDOMResourceRenderer>`
   - **`library`**: Optional component library for Remote DOM resources (defaults to `basicComponentLibrary`)
   - **`remoteElements`**: Optional remote element definitions for Remote DOM resources. REQUIRED for Remote DOM snippets.
@@ -138,6 +139,63 @@ function App({ mcpResource }) {
 />
 ```
 
+### Passing Render-Time Data to Iframes
+
+The `iframeRenderData` prop allows you to send a data payload to an iframe as it renders. This is useful for initializing the iframe with dynamic data from the parent application.
+
+When `iframeRenderData` is provided:
+1. The iframe's URL will automatically include `?waitForRenderData=true`. The iframe's internal script can use this to know it should wait for data instead of immediately rendering.
+2. The data is sent to the iframe via `postMessage` using a dual-mechanism approach to ensure reliable delivery:
+    - **On Load**: A `ui-lifecycle-iframe-render-data` message is sent as soon as the iframe's `onLoad` event fires.
+    - **On Ready**: If the iframe sends a `ui-lifecycle-iframe-ready` message, the parent will respond with the same `ui-lifecycle-iframe-render-data` payload.
+
+This ensures the data is delivered whether the iframe is ready immediately or needs to perform setup work first.
+
+```tsx
+<UIResourceRenderer
+  resource={mcpResource.resource}
+  htmlProps={{
+    iframeRenderData: {
+      theme: 'dark',
+      user: { id: '123', name: 'John Doe' }
+    }
+  }}
+  onUIAction={handleUIAction}
+/>
+```
+
+Inside the iframe, you can listen for this data:
+
+```javascript
+// In the iframe's script
+
+// If the iframe needs to do async work, it can tell the parent when it's ready
+const urlParams = new URLSearchParams(window.location.search);
+if (urlParams.get('waitForRenderData') === 'true') {
+  let customRenderData = null;
+
+  // The parent will send this message on load or when we notify it we're ready
+  window.addEventListener('message', (event) => {
+    // Add origin checks for security
+    if (event.data.type === 'ui-lifecycle-iframe-render-data') {
+      // If the iframe has already received data, we don't need to do anything
+      if(customRenderData) {
+        return;
+      } else {
+        customRenderData = event.data.payload.renderData;
+        // Now you can render the UI with the received data
+        renderUI(renderData);
+      }
+    }
+  });
+  // We can let the parent know we're ready to receive data
+  window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*');
+} else {
+  // If the iframe doesn't need to wait for data, we can render the default UI immediately
+  renderUI();
+}
+```
+
 ### Accessing the Iframe Element
 
 You can pass a ref through `iframeProps` to access the underlying iframe element:

sdks/typescript/client/src/components/HTMLResourceRenderer.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useImperativeHandle, useMemo, useRef } from 'react';
+import React, { useCallback, useEffect, useImperativeHandle, useMemo, useRef } from 'react';
 import type { Resource } from '@modelcontextprotocol/sdk/types.js';
 import { UIActionResult } from '../types';
 import { processHTMLResource } from '../utils/processResource';
@@ -8,6 +8,7 @@ export type HTMLResourceRendererProps = {
   onUIAction?: (result: UIActionResult) => Promise<unknown>;
   style?: React.CSSProperties;
   proxy?: string;
+  iframeRenderData?: Record<string, unknown>;
   iframeProps?: Omit<React.HTMLAttributes<HTMLIFrameElement>, 'src' | 'srcDoc' | 'style'> & {
     ref?: React.RefObject<HTMLIFrameElement>;
   };
@@ -17,13 +18,21 @@ const InternalMessageType = {
   UI_ACTION_RECEIVED: 'ui-action-received',
   UI_ACTION_RESPONSE: 'ui-action-response',
   UI_ACTION_ERROR: 'ui-action-error',
+
+  UI_LIFECYCLE_IFRAME_READY: 'ui-lifecycle-iframe-ready',
+  UI_LIFECYCLE_IFRAME_RENDER_DATA: 'ui-lifecycle-iframe-render-data',
+} as const;
+
+export const ReservedUrlParams = {
+  WAIT_FOR_RENDER_DATA: 'waitForRenderData',
 } as const;
 
 export const HTMLResourceRenderer = ({
   resource,
   onUIAction,
   style,
   proxy,
+  iframeRenderData,
   iframeProps,
 }: HTMLResourceRendererProps) => {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
@@ -34,27 +43,72 @@ export const HTMLResourceRenderer = ({
     [resource, proxy],
   );
 
+  const iframeSrcToRender = useMemo(() => {
+    if (iframeSrc && iframeRenderData) {
+      const iframeUrl = new URL(iframeSrc);
+      iframeUrl.searchParams.set(ReservedUrlParams.WAIT_FOR_RENDER_DATA, 'true');
+      return iframeUrl.toString();
+    }
+    return iframeSrc;
+  }, [iframeSrc, iframeRenderData]);
+
+  const onIframeLoad = useCallback(
+    (event: React.SyntheticEvent<HTMLIFrameElement>) => {
+      if (iframeRenderData) {
+        const iframeWindow = event.currentTarget.contentWindow;
+        const iframeOrigin = iframeSrcToRender ? new URL(iframeSrcToRender).origin : '*';
+        postToFrame(
+          InternalMessageType.UI_LIFECYCLE_IFRAME_RENDER_DATA,
+          iframeWindow,
+          iframeOrigin,
+          undefined,
+          {
+            renderData: iframeRenderData,
+          },
+        );
+      }
+      iframeProps?.onLoad?.(event);
+    },
+    [iframeRenderData, iframeSrcToRender, iframeProps?.onLoad],
+  );
+
   useEffect(() => {
     async function handleMessage(event: MessageEvent) {
+      const { source, origin, data } = event;
       // Only process the message if it came from this specific iframe
-      if (iframeRef.current && event.source === iframeRef.current.contentWindow) {
-        const uiActionResult = event.data as UIActionResult;
+      if (iframeRef.current && source === iframeRef.current.contentWindow) {
+        // if the iframe is ready, send the render data to the iframe
+        if (data?.type === InternalMessageType.UI_LIFECYCLE_IFRAME_READY && iframeRenderData) {
+          postToFrame(
+            InternalMessageType.UI_LIFECYCLE_IFRAME_RENDER_DATA,
+            source,
+            origin,
+            undefined,
+            {
+              renderData: iframeRenderData,
+            },
+          );
+          return;
+        }
+
+        const uiActionResult = data as UIActionResult;
         if (!uiActionResult) {
           return;
         }
 
         // return the "ui-action-received" message only if the onUIAction callback is provided
         // otherwise we cannot know that the message was received by the client
         if (onUIAction) {
-          postToFrame(InternalMessageType.UI_ACTION_RECEIVED, event, uiActionResult);
+          const messageId = uiActionResult.messageId;
+          postToFrame(InternalMessageType.UI_ACTION_RECEIVED, source, origin, messageId);
           try {
             const response = await onUIAction(uiActionResult);
-            postToFrame(InternalMessageType.UI_ACTION_RESPONSE, event, uiActionResult, {
+            postToFrame(InternalMessageType.UI_ACTION_RESPONSE, source, origin, messageId, {
               response,
             });
           } catch (err) {
             console.error('Error handling UI action result in HTMLResourceRenderer:', err);
-            postToFrame(InternalMessageType.UI_ACTION_ERROR, event, uiActionResult, {
+            postToFrame(InternalMessageType.UI_ACTION_ERROR, source, origin, messageId, {
               error: err,
             });
           }
@@ -82,23 +136,26 @@ export const HTMLResourceRenderer = ({
         title="MCP HTML Resource (Embedded Content)"
         {...iframeProps}
         ref={iframeRef}
+        onLoad={onIframeLoad}
       />
     );
   } else if (iframeRenderMode === 'src') {
-    if (iframeSrc === null || iframeSrc === undefined) {
+    if (iframeSrcToRender === null || iframeSrcToRender === undefined) {
       if (!error) {
         return <p className="text-orange-500">No URL provided for HTML resource.</p>;
       }
       return null;
     }
+
     return (
       <iframe
-        src={iframeSrc}
+        src={iframeSrcToRender}
         sandbox="allow-scripts allow-same-origin"
         style={{ width: '100%', minHeight: 200, ...style }}
         title="MCP HTML Resource (URL)"
         {...iframeProps}
         ref={iframeRef}
+        onLoad={onIframeLoad}
       />
     );
   }
@@ -110,21 +167,19 @@ HTMLResourceRenderer.displayName = 'HTMLResourceRenderer';
 
 function postToFrame(
   type: (typeof InternalMessageType)[keyof typeof InternalMessageType],
-  event: MessageEvent,
-  uiActionResult: UIActionResult,
+  source: Window | null,
+  origin: string,
+  originalMessageId?: string,
   payload?: unknown,
 ) {
-  if (uiActionResult.messageId) {
-    event.source?.postMessage(
-      {
-        type,
-        messageId: uiActionResult.messageId,
-        payload,
-      },
-      {
-        // in case the iframe is srcdoc, the origin is null
-        targetOrigin: event.origin && event.origin !== 'null' ? event.origin : '*',
-      },
-    );
-  }
+  // in case the iframe is srcdoc, the origin is null
+  const targetOrigin = origin && origin !== 'null' ? origin : '*';
+  source?.postMessage(
+    {
+      type,
+      messageId: originalMessageId ?? undefined,
+      payload,
+    },
+    targetOrigin,
+  );
 }

sdks/typescript/client/src/components/__tests__/HTMLResourceRenderer.test.tsx

@@ -1,6 +1,10 @@
 import { render, screen, fireEvent, waitFor } from '@testing-library/react';
 import '@testing-library/jest-dom';
-import { HTMLResourceRenderer, HTMLResourceRendererProps } from '../HTMLResourceRenderer';
+import {
+  HTMLResourceRenderer,
+  HTMLResourceRendererProps,
+  ReservedUrlParams,
+} from '../HTMLResourceRenderer';
 import { vi } from 'vitest';
 import type { Resource } from '@modelcontextprotocol/sdk/types.js';
 import { UIActionResult } from '../../types.js';
@@ -322,6 +326,37 @@ describe('HTMLResource iframe communication', () => {
     expect(localMockOnUIAction).not.toHaveBeenCalled();
     expect(mockOnUIAction).not.toHaveBeenCalled(); // also check the describe-scoped one
   });
+
+  it('should hang the proper query params in the iframe src', async () => {
+    const resource = {
+      mimeType: 'text/uri-list',
+      text: 'https://example.com/app',
+    };
+    const iframeRenderData = { foo: 'bar' };
+    const ref = React.createRef<HTMLIFrameElement>();
+    render(
+      <HTMLResourceRenderer
+        resource={resource}
+        iframeProps={{ ref }}
+        iframeRenderData={iframeRenderData}
+      />,
+    );
+    expect(ref.current).toBeInTheDocument();
+    expect(ref.current?.src).toContain(`${ReservedUrlParams.WAIT_FOR_RENDER_DATA}=true`);
+  });
+
+  it('shouldnt hang the query param if there is no render data', async () => {
+    const resource = {
+      mimeType: 'text/uri-list',
+      text: 'https://example.com/app',
+    };
+    const ref = React.createRef<HTMLIFrameElement>();
+    render(
+      <HTMLResourceRenderer resource={resource} iframeProps={{ ref }} iframeRenderData={undefined} />,
+    );
+    expect(ref.current).toBeInTheDocument();
+    expect(ref.current?.src).not.toContain(`${ReservedUrlParams.WAIT_FOR_RENDER_DATA}=true`);
+  });
 });
 
 // Helper to dispatch a message event

sdks/typescript/server/src/index.ts

@@ -139,8 +139,15 @@ export const InternalMessageType = {
   UI_ACTION_RECEIVED: 'ui-action-received',
   UI_ACTION_RESPONSE: 'ui-action-response',
   UI_ACTION_ERROR: 'ui-action-error',
+
+  UI_LIFECYCLE_IFRAME_READY: 'ui-lifecycle-iframe-ready',
+  UI_LIFECYCLE_IFRAME_RENDER_DATA: 'ui-lifecycle-iframe-render-data',
 };
 
+export const ReservedUrlParams = {
+  WAIT_FOR_RENDER_DATA: 'waitForRenderData',
+} as const;
+
 export function uiActionResultToolCall(
   toolName: string,
   params: Record<string, unknown>,