@@ -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 */
4567export 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