Skip to content

Commit 70a7729

Browse files
committed
feat(transport): support deferred target in PostMessageTransport for srcdoc iframes
When hosts load View HTML dynamically via srcdoc, iframe.contentWindow is not available until the iframe loads. The current PostMessageTransport requires contentWindow at construction, creating a race condition where the View sends ui/initialize before the host's transport is listening. This adds deferred target support to PostMessageTransport: - eventTarget and eventSource now accept null - New setTarget() method sets the target and flushes queued messages - send() queues messages when target is null - close() clears the queue Fully backward compatible — existing constructor usage is unchanged. Fixes modelcontextprotocol#542 Made-with: Cursor
1 parent 2b0d11e commit 70a7729

3 files changed

Lines changed: 240 additions & 12 deletions

File tree

‎src/message-transport.examples.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,51 @@ function PostMessageTransport_constructor_host() {
5656
);
5757
//#endregion PostMessageTransport_constructor_host
5858
}
59+
60+
/**
61+
* Example: Host with deferred target for srcdoc iframes.
62+
*
63+
* When loading View HTML via `srcdoc`, `contentWindow` is not available until
64+
* the iframe loads. Create the transport with `null` target, connect the bridge
65+
* (which starts listening for messages), set `srcdoc`, then call `setTarget()`
66+
* after the iframe loads to flush queued outgoing messages.
67+
*/
68+
async function PostMessageTransport_deferred(
69+
bridge: AppBridge,
70+
htmlContent: string,
71+
) {
72+
//#region PostMessageTransport_deferred
73+
const iframe = document.createElement("iframe");
74+
iframe.sandbox.add("allow-scripts");
75+
document.body.appendChild(iframe);
76+
77+
const transport = new PostMessageTransport(null, null);
78+
await bridge.connect(transport);
79+
80+
iframe.srcdoc = htmlContent;
81+
iframe.onload = () => {
82+
transport.setTarget(iframe.contentWindow!);
83+
};
84+
//#endregion PostMessageTransport_deferred
85+
}
86+
87+
/**
88+
* Example: Creating deferred transport (constructor only).
89+
*/
90+
function PostMessageTransport_constructor_deferred() {
91+
//#region PostMessageTransport_constructor_deferred
92+
const transport = new PostMessageTransport(null, null);
93+
//#endregion PostMessageTransport_constructor_deferred
94+
}
95+
96+
/**
97+
* Example: Setting the target after iframe loads.
98+
*/
99+
function PostMessageTransport_setTarget(transport: PostMessageTransport) {
100+
//#region PostMessageTransport_setTarget
101+
const iframe = document.getElementById("app-iframe") as HTMLIFrameElement;
102+
iframe.onload = () => {
103+
transport.setTarget(iframe.contentWindow!);
104+
};
105+
//#endregion PostMessageTransport_setTarget
106+
}

‎src/message-transport.test.ts‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
import { describe, it, expect, beforeEach, afterEach } from "bun:test";
2+
import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
3+
4+
import { PostMessageTransport } from "./message-transport";
5+
6+
const makeMessage = (id: number): JSONRPCMessage => ({
7+
jsonrpc: "2.0",
8+
id,
9+
method: "test",
10+
params: {},
11+
});
12+
13+
type MessageHandler = (ev: MessageEvent) => void;
14+
15+
let messageListeners: Set<MessageHandler>;
16+
17+
const mockWindow = {
18+
addEventListener: (type: string, listener: MessageHandler) => {
19+
if (type === "message") messageListeners.add(listener);
20+
},
21+
removeEventListener: (type: string, listener: MessageHandler) => {
22+
if (type === "message") messageListeners.delete(listener);
23+
},
24+
} as unknown as Window & typeof globalThis;
25+
26+
function dispatchMessage(data: unknown, source?: MessageEventSource | null) {
27+
const event = { data, source, origin: "null" } as MessageEvent;
28+
for (const listener of messageListeners) {
29+
listener(event);
30+
}
31+
}
32+
33+
describe("PostMessageTransport", () => {
34+
let savedWindow: typeof globalThis.window;
35+
36+
beforeEach(() => {
37+
messageListeners = new Set();
38+
savedWindow = globalThis.window;
39+
(globalThis as any).window = mockWindow;
40+
});
41+
42+
afterEach(() => {
43+
(globalThis as any).window = savedWindow;
44+
});
45+
46+
it("queues messages when target is null and flushes on setTarget", async () => {
47+
// Arrange
48+
const transport = new PostMessageTransport(null, null);
49+
await transport.start();
50+
const posted: unknown[] = [];
51+
const fakeTarget = {
52+
postMessage: (data: unknown, _origin: string) => posted.push(data),
53+
} as unknown as Window;
54+
55+
// Act
56+
await transport.send(makeMessage(1));
57+
await transport.send(makeMessage(2));
58+
transport.setTarget(fakeTarget);
59+
60+
// Assert
61+
expect(posted).toEqual([makeMessage(1), makeMessage(2)]);
62+
expect((transport as any)._sendQueue).toHaveLength(0);
63+
});
64+
65+
it("receives messages with null eventSource before setTarget", async () => {
66+
// Arrange
67+
const transport = new PostMessageTransport(null, null);
68+
const received: JSONRPCMessage[] = [];
69+
transport.onmessage = (msg) => received.push(msg);
70+
await transport.start();
71+
72+
// Act
73+
dispatchMessage(makeMessage(1));
74+
75+
// Assert
76+
expect(received).toHaveLength(1);
77+
});
78+
79+
it("sends directly when target is provided (backward compat)", async () => {
80+
// Arrange
81+
const posted: unknown[] = [];
82+
const fakeTarget = {
83+
postMessage: (data: unknown, _origin: string) => posted.push(data),
84+
} as unknown as Window;
85+
const transport = new PostMessageTransport(fakeTarget, fakeTarget);
86+
await transport.start();
87+
88+
// Act
89+
await transport.send(makeMessage(1));
90+
91+
// Assert
92+
expect(posted).toEqual([makeMessage(1)]);
93+
expect((transport as any)._sendQueue).toHaveLength(0);
94+
});
95+
96+
it("clears the send queue on close", async () => {
97+
// Arrange
98+
const transport = new PostMessageTransport(null, null);
99+
await transport.start();
100+
await transport.send(makeMessage(1));
101+
102+
// Act
103+
await transport.close();
104+
105+
// Assert
106+
expect((transport as any)._sendQueue).toHaveLength(0);
107+
});
108+
});

‎src/message-transport.ts‎

Lines changed: 84 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,31 @@ import {
1717
*
1818
* ## Security
1919
*
20-
* The `eventSource` parameter is required and validates the message source window
21-
* by checking `event.source`. For views, pass `window.parent`.
20+
* The `eventSource` parameter validates the message source window by checking
21+
* `event.source`. For views, pass `window.parent`.
2222
* For hosts, pass `iframe.contentWindow` to validate the iframe source.
23+
* When `null`, all sources are accepted (useful when the iframe hasn't loaded yet).
24+
*
25+
* ## Deferred Target (srcdoc iframes)
26+
*
27+
* When the host creates an iframe dynamically (e.g., via `srcdoc`), `contentWindow`
28+
* is not available until the iframe loads. Pass `null` as `eventTarget` and call
29+
* {@link setTarget `setTarget`} after the iframe loads. Outgoing messages are queued
30+
* until the target is set.
31+
*
32+
* ```ts source="./message-transport.examples.ts#PostMessageTransport_deferred"
33+
* const iframe = document.createElement("iframe");
34+
* iframe.sandbox.add("allow-scripts");
35+
* document.body.appendChild(iframe);
36+
*
37+
* const transport = new PostMessageTransport(null, null);
38+
* await bridge.connect(transport);
39+
*
40+
* iframe.srcdoc = htmlContent;
41+
* iframe.onload = () => {
42+
* transport.setTarget(iframe.contentWindow!);
43+
* };
44+
* ```
2345
*
2446
* ## Usage
2547
*
@@ -43,6 +65,9 @@ import {
4365
* @see {@link app-bridge!AppBridge.connect `AppBridge.connect`} for Host usage
4466
*/
4567
export class PostMessageTransport implements Transport {
68+
private _eventTarget: Window | null;
69+
private _eventSource: MessageEventSource | null;
70+
private _sendQueue: JSONRPCMessage[] = [];
4671
private messageListener: (
4772
this: Window,
4873
ev: WindowEventMap["message"],
@@ -51,9 +76,12 @@ export class PostMessageTransport implements Transport {
5176
/**
5277
* Create a new PostMessageTransport.
5378
*
54-
* @param eventTarget - Target window to send messages to (default: `window.parent`)
79+
* @param eventTarget - Target window to send messages to. Pass `null` to defer
80+
* — outgoing messages will be queued until {@link setTarget `setTarget`} is called.
81+
* Defaults to `window.parent` for View usage.
5582
* @param eventSource - Source window for message validation. For views, pass
56-
* `window.parent`. For hosts, pass `iframe.contentWindow`.
83+
* `window.parent`. For hosts, pass `iframe.contentWindow`. Pass `null` to
84+
* accept messages from any source (useful for deferred/srcdoc iframes).
5785
*
5886
* @example View connecting to parent
5987
* ```ts source="./message-transport.examples.ts#PostMessageTransport_constructor_view"
@@ -68,13 +96,20 @@ export class PostMessageTransport implements Transport {
6896
* iframe.contentWindow!,
6997
* );
7098
* ```
99+
*
100+
* @example Host with deferred target (srcdoc)
101+
* ```ts source="./message-transport.examples.ts#PostMessageTransport_constructor_deferred"
102+
* const transport = new PostMessageTransport(null, null);
103+
* ```
71104
*/
72105
constructor(
73-
private eventTarget: Window = window.parent,
74-
private eventSource: MessageEventSource,
106+
eventTarget: Window | null = window.parent,
107+
eventSource: MessageEventSource | null,
75108
) {
109+
this._eventTarget = eventTarget;
110+
this._eventSource = eventSource;
76111
this.messageListener = (event) => {
77-
if (eventSource && event.source !== this.eventSource) {
112+
if (this._eventSource && event.source !== this._eventSource) {
78113
console.debug("Ignoring message from unknown source", event);
79114
return;
80115
}
@@ -103,6 +138,35 @@ export class PostMessageTransport implements Transport {
103138
};
104139
}
105140

141+
/**
142+
* Set or update the target window for outgoing messages.
143+
*
144+
* When the transport was created with a `null` target (deferred mode), call
145+
* this method after the iframe loads to provide `contentWindow` and flush
146+
* any queued messages. Also updates the event source for incoming message
147+
* validation.
148+
*
149+
* @param target - The iframe's `contentWindow` to send messages to
150+
* @param eventSource - Optional new event source for message validation.
151+
* Defaults to `target`, which is correct for most iframe setups.
152+
*
153+
* @example
154+
* ```ts source="./message-transport.examples.ts#PostMessageTransport_setTarget"
155+
* const iframe = document.getElementById("app-iframe") as HTMLIFrameElement;
156+
* iframe.onload = () => {
157+
* transport.setTarget(iframe.contentWindow!);
158+
* };
159+
* ```
160+
*/
161+
setTarget(target: Window, eventSource?: MessageEventSource): void {
162+
this._eventTarget = target;
163+
this._eventSource = eventSource ?? target;
164+
for (const message of this._sendQueue) {
165+
this._eventTarget.postMessage(message, "*");
166+
}
167+
this._sendQueue = [];
168+
}
169+
106170
/**
107171
* Begin listening for messages from the event source.
108172
*
@@ -116,24 +180,32 @@ export class PostMessageTransport implements Transport {
116180
/**
117181
* Send a JSON-RPC message to the target window.
118182
*
119-
* Messages are sent using `postMessage` with `"*"` origin, meaning they are visible
120-
* to all frames. The receiver should validate the message source for security.
183+
* When the target is set, messages are sent immediately using `postMessage`
184+
* with `"*"` origin. When the target is `null` (deferred mode), messages are
185+
* queued and flushed when {@link setTarget `setTarget`} is called.
121186
*
122187
* @param message - JSON-RPC message to send
123188
* @param options - Optional send options (currently unused)
124189
*/
125190
async send(message: JSONRPCMessage, options?: TransportSendOptions) {
126-
console.debug("Sending message", message);
127-
this.eventTarget.postMessage(message, "*");
191+
if (this._eventTarget) {
192+
console.debug("Sending message", message);
193+
this._eventTarget.postMessage(message, "*");
194+
} else {
195+
console.debug("Queuing message (target not set)", message);
196+
this._sendQueue.push(message);
197+
}
128198
}
129199

130200
/**
131201
* Stop listening for messages and cleanup.
132202
*
133-
* Removes the message event listener and calls the {@link onclose `onclose`} callback if set.
203+
* Removes the message event listener, clears any queued messages, and calls
204+
* the {@link onclose `onclose`} callback if set.
134205
*/
135206
async close() {
136207
window.removeEventListener("message", this.messageListener);
208+
this._sendQueue = [];
137209
this.onclose?.();
138210
}
139211

0 commit comments

Comments
 (0)