@gjsify/iframe 0.4.10 → 0.4.12

package/lib/esm/iframe-message-channel.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{EventTarget as e,MessageEvent as t}from"@gjsify/dom-events";var IFrameMessagePort=class extends e{constructor(...e){super(...e),this._partner=null,this._transferred=!1,this._bridge=null,this._portId=null,this._started=!1,this._queue=[],this._closed=!1}postMessage(e){if(this._transferred)throw Error(`IFrameMessagePort.postMessage: port has been transferred`);if(!this._closed){if(this._bridge&&this._portId!==null){this._bridge._sendPortMessage(this._portId,e);return}this._partner&&!this._partner._closed&&this._partner._receive(e)}}start(){if(this._started||this._closed)return;this._started=!0;let e=this._queue;this._queue=[];for(let t of e)this._dispatch(t)}close(){this._closed||(this._closed=!0,this._bridge&&this._portId!==null&&(this._bridge._closePort(this._portId),this._bridge=null,this._portId=null),this._partner=null,this._queue=[])}_receive(e){if(!this._closed){if(!this._started){this._queue.push(e);return}this._dispatch(e)}}_dispatch(e){Promise.resolve().then(()=>{this._closed||this.dispatchEvent(new t(`message`,{data:e}))})}addEventListener(e,t,n){super.addEventListener(e,t,n),e===`message`&&this.start()}get[Symbol.toStringTag](){return`MessagePort`}},IFrameMessageChannel=class{constructor(){this.port1=new IFrameMessagePort,this.port2=new IFrameMessagePort,this.port1._partner=this.port2,this.port2._partner=this.port1}get[Symbol.toStringTag](){return`MessageChannel`}};export{IFrameMessageChannel,IFrameMessagePort};

package/lib/esm/iframe-window-proxy.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{EventTarget as e}from"@gjsify/dom-events";var IFrameWindowProxy=class extends e{constructor(e){super(),this._closed=!1,this._bridge=e}postMessage(e,t=`*`){this._closed||this._bridge.sendToWebView(e,t)}get location(){return this._bridge.getLocation()}get parent(){return globalThis}get top(){return globalThis}get self(){return this}get window(){return this}get closed(){return this._closed}_close(){this._closed=!0}get[Symbol.toStringTag](){return`IFrameWindowProxy`}};export{IFrameWindowProxy};
+import"./_virtual/_rolldown/runtime.js";import{EventTarget as e}from"@gjsify/dom-events";var IFrameWindowProxy=class extends e{constructor(e){super(),this._closed=!1,this._bridge=e}postMessage(e,t=`*`,n){this._closed||this._bridge.sendToWebView(e,t,n)}get location(){return this._bridge.getLocation()}get parent(){return globalThis}get top(){return globalThis}get self(){return this}get window(){return this}get closed(){return this._closed}_close(){this._closed=!0}get[Symbol.toStringTag](){return`IFrameWindowProxy`}};export{IFrameWindowProxy};

package/lib/esm/index.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{HTMLIFrameElement as e}from"./html-iframe-element.js";import{IFrameWindowProxy as t}from"./iframe-window-proxy.js";import{MessageBridge as n}from"./message-bridge.js";import{IFrameBridge as r}from"./iframe-bridge.js";import{Document as i}from"@gjsify/dom-elements";i.registerElementFactory(`iframe`,()=>new e),Object.defineProperty(globalThis,`HTMLIFrameElement`,{value:e,writable:!0,configurable:!0});export{e as HTMLIFrameElement,r as IFrameBridge,t as IFrameWindowProxy,n as MessageBridge};
+import"./_virtual/_rolldown/runtime.js";import{HTMLIFrameElement as e}from"./html-iframe-element.js";import{IFrameWindowProxy as t}from"./iframe-window-proxy.js";import{GJS_HOST_ORIGIN as n,MessageBridge as r}from"./message-bridge.js";import{IFrameBridge as i}from"./iframe-bridge.js";import{IFrameMessageChannel as a,IFrameMessagePort as o}from"./iframe-message-channel.js";import{Document as s}from"@gjsify/dom-elements";s.registerElementFactory(`iframe`,()=>new e),Object.defineProperty(globalThis,`HTMLIFrameElement`,{value:e,writable:!0,configurable:!0});export{n as GJS_HOST_ORIGIN,e as HTMLIFrameElement,i as IFrameBridge,a as IFrameMessageChannel,o as IFrameMessagePort,t as IFrameWindowProxy,r as MessageBridge};

package/lib/esm/message-bridge.js

@@ -1,13 +1,123 @@
-import"./_virtual/_rolldown/runtime.js";import{MessageEvent as e}from"@gjsify/dom-events";import t from"gi://WebKit?version=6.0";import n from"gi://Gio?version=2.0";n._promisify(t.WebView.prototype,`evaluate_javascript`,`evaluate_javascript_finish`);const r=`gjsify-iframe`,i=`(function() {
-    var handler = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers['${r}'];
+import"./_virtual/_rolldown/runtime.js";import{BINARY_SERIALIZER_INJECTED_SRC as e,decodeBinariesFromJson as t,encodeBinariesForJson as n}from"./serialize.js";import{MessageEvent as r}from"@gjsify/dom-events";import i from"gi://WebKit?version=6.0";import a from"gi://Gio?version=2.0";a._promisify(i.WebView.prototype,`evaluate_javascript`,`evaluate_javascript_finish`);const o=`gjsify-iframe`,s=`https://gjsify.local`;function normaliseTargetOrigin(e){if(e===`*`)return`*`;if(e===`/`)return null;try{return new URL(e).origin}catch{let t=Error(`Invalid target origin '${e}'`);throw t.name=`SyntaxError`,t}}const BOOTSTRAP_SCRIPT_FOR_TEST=()=>c,c=`(function() {
+    var handler = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers['${o}'];
     if (!handler) return;
+
+    // Idempotency guard: WebKit auto-injects this script at INJECTION_TIME.START
+    // for every page load. On rapid reload, srcdoc remount, or
+    // history.replaceState shenanigans, the script may run twice in the
+    // same window without an intervening real navigation. If we
+    // overwrite our previous override blindly we'd capture OUR override
+    // as origPostMessage, losing the real one — and any consumer using
+    // __gjsifyBridge.origPostMessage would loop forever.
+    if (window.__gjsifyBridge && window.__gjsifyBridge.__bridgeVersion === 1) return;
+
+    var GJS_HOST_ORIGIN = '${s}';
+
+    ${e}
+
+    // Per-WebView registry of proxy ports created during GJS → WebView
+    // postMessage. Keyed by the GJS-allocated portId. Each entry has a
+    // .deliver(payload) hook the GJS host can invoke via evaluate_javascript
+    // to dispatch a 'message' event on the proxy port.
+    var __gjsifyPorts = {};
+
+    function __makeProxyPort(portId) {
+        var listeners = [];
+        var started = false;
+        var queued = [];
+        function dispatch(d) {
+            var ev = { data: d, type: 'message' };
+            for (var i = 0; i < listeners.length; i++) {
+                try { listeners[i].call(undefined, ev); } catch (_) {}
+            }
+        }
+        function drain() {
+            while (queued.length > 0) dispatch(queued.shift());
+        }
+        var port = {
+            postMessage: function(d) {
+                handler.postMessage(JSON.stringify({
+                    __gjsifyPortMessage: portId,
+                    payload: __encodeBin(d)
+                }));
+            },
+            addEventListener: function(type, fn) {
+                if (type !== 'message' || typeof fn !== 'function') return;
+                listeners.push(fn);
+                if (!started) { started = true; drain(); }
+            },
+            removeEventListener: function(type, fn) {
+                if (type !== 'message') return;
+                var i = listeners.indexOf(fn);
+                if (i !== -1) listeners.splice(i, 1);
+            },
+            start: function() { if (!started) { started = true; drain(); } },
+            close: function() {
+                handler.postMessage(JSON.stringify({ __gjsifyPortClose: portId }));
+                listeners = [];
+                queued = [];
+                delete __gjsifyPorts[portId];
+            },
+        };
+        Object.defineProperty(port, 'onmessage', {
+            get: function() { return port.__onmessage || null; },
+            set: function(fn) {
+                if (port.__onmessage) port.removeEventListener('message', port.__onmessage);
+                port.__onmessage = fn;
+                if (typeof fn === 'function') port.addEventListener('message', fn);
+            },
+        });
+        __gjsifyPorts[portId] = {
+            deliver: function(d) {
+                if (started) dispatch(d); else queued.push(d);
+            },
+        };
+        return port;
+    }
+
+    // Walk an incoming GJS → WebView payload for {__gjsifyPort: id}
+    // placeholders and replace each with a proxy port instance.
+    function __substitutePorts(v) {
+        if (v === null || typeof v !== 'object') return v;
+        if (typeof v.__gjsifyPort === 'number') return __makeProxyPort(v.__gjsifyPort);
+        if (Array.isArray(v)) { for (var i=0;i<v.length;i++) v[i]=__substitutePorts(v[i]); return v; }
+        if (__classOf(v) === 'Object') {
+            for (var k in v) if (Object.prototype.hasOwnProperty.call(v,k)) v[k]=__substitutePorts(v[k]);
+            return v;
+        }
+        return v;
+    }
+    window.__gjsifyPortRegistry = __gjsifyPorts;
+    window.__gjsifySubstitutePorts = __substitutePorts;
+
+    function normaliseOrigin(t) {
+        if (t === '*') return '*';
+        if (t === '/') return location.origin;       // source own-origin shortcut
+        try { return new URL(t).origin; }
+        catch (_) {
+            var err = new SyntaxError("Invalid target origin '" + t + "'");
+            throw err;
+        }
+    }
+
     function bridgePostMessage(data, targetOrigin) {
+        var t = targetOrigin || '*';
+        var resolved = normaliseOrigin(t);
+        // Drop silently if the targetOrigin doesn't match GJS host origin.
+        // '*' matches anything; otherwise must equal GJS_HOST_ORIGIN.
+        if (resolved !== '*' && resolved !== GJS_HOST_ORIGIN) return;
         handler.postMessage(JSON.stringify({
-            data: data,
-            targetOrigin: targetOrigin || '*',
+            data: __encodeBin(data),
+            targetOrigin: resolved,
             origin: location.origin
         }));
     }
+
+    // GJS → WebView messages come in via window.dispatchEvent(new MessageEvent(...))
+    // injected by evaluate_javascript. We can't intercept that path, so the
+    // injection itself decodes placeholders before constructing MessageEvent —
+    // see MessageBridge.sendToWebView in message-bridge.ts.
+
     // In a WebKit.WebView loaded via srcdoc, window.parent === window (no real iframe nesting).
     // window.parent is [LegacyUnforgeable] — cannot be redefined with defineProperty.
     // Instead, override window.postMessage directly. Since window.parent === window,
@@ -16,6 +126,11 @@ import"./_virtual/_rolldown/runtime.js";import{MessageEvent as e}from"@gjsify/do
     window.postMessage = function(data, targetOrigin) {
         bridgePostMessage(data, targetOrigin);
     };
-    // Also expose on a safe namespace for explicit use
-    window.__gjsifyBridge = { postMessage: bridgePostMessage, origPostMessage: origPostMessage };
-})();`;var MessageBridge=class{constructor(e){this._windowProxy=null,this._currentUri=`about:blank`,this._signalId=null,this._webView=e,this._userContentManager=e.get_user_content_manager(),this._setupReceiver(),this._injectBootstrapScript()}setWindowProxy(e){this._windowProxy=e}updateUri(e){this._currentUri=e}getLocation(){let e;try{e=new URL(this._currentUri).origin}catch{e=`null`}return{href:this._currentUri,origin:e}}sendToWebView(e,t){let n=JSON.stringify(e),r=JSON.stringify(`gjsify`),i=`window.dispatchEvent(new MessageEvent('message', { data: JSON.parse(${JSON.stringify(n)}), origin: ${r} }));`;this._webView.evaluate_javascript(i,-1,null,null,null).catch(()=>{})}destroy(){this._signalId!==null&&(this._userContentManager.disconnect(this._signalId),this._signalId=null),this._userContentManager.unregister_script_message_handler(r,null),this._windowProxy=null}_setupReceiver(){this._userContentManager.register_script_message_handler(r,null),this._signalId=this._userContentManager.connect(`script-message-received::${r}`,(t,n)=>{if(this._windowProxy)try{let t=n.to_string(),r=JSON.parse(t),i=new e(`message`,{data:r.data,origin:r.origin});this._windowProxy.dispatchEvent(i)}catch(e){console.error(`[IFrame MessageBridge] Error processing message:`,e)}})}_injectBootstrapScript(){let e=new t.UserScript(i,t.UserContentInjectedFrames.ALL_FRAMES,t.UserScriptInjectionTime.START,null,null);this._userContentManager.add_script(e)}};export{MessageBridge};
+    // Also expose on a safe namespace for explicit use. Version-tag
+    // the bridge so the idempotency guard above can detect a re-run.
+    window.__gjsifyBridge = {
+        __bridgeVersion: 1,
+        postMessage: bridgePostMessage,
+        origPostMessage: origPostMessage,
+    };
+})();`;var MessageBridge=class{constructor(e){this._windowProxy=null,this._currentUri=`about:blank`,this._signalId=null,this._ports=new Map,this._nextPortId=1,this._webView=e,this._userContentManager=e.get_user_content_manager(),this._setupReceiver(),this._injectBootstrapScript()}setWindowProxy(e){this._windowProxy=e}updateUri(e){this._currentUri=e}getLocation(){let e;try{e=new URL(this._currentUri).origin}catch{e=`null`}return{href:this._currentUri,origin:e}}_registerTransferredPort(e){if(e._transferred)throw Error(`IFrameMessagePort: already transferred`);let t=e._partner;if(!t)throw Error(`IFrameMessagePort: partner missing — port already transferred or closed`);let n=this._nextPortId++;return e._transferred=!0,e._partner=null,t._partner=null,t._bridge=this,t._portId=n,this._ports.set(n,t),n}_sendPortMessage(t,r){let i=n(r),a=JSON.stringify(i),o=`(function(){${e}var p = window.__gjsifyPortRegistry && window.__gjsifyPortRegistry[${t}]; if (p) p.deliver(__decodeBin(JSON.parse(${JSON.stringify(a)})));})();`;this._webView.evaluate_javascript(o,-1,null,null,null).catch(()=>{})}_closePort(e){this._ports.delete(e);let t=`(function(){ if (window.__gjsifyPortRegistry) delete window.__gjsifyPortRegistry[${e}]; })();`;this._webView.evaluate_javascript(t,-1,null,null,null).catch(()=>{})}sendToWebView(t,r,i){let a=normaliseTargetOrigin(r);if(a!==`*`){let e=this.getLocation().origin;if((a??`https://gjsify.local`)!==e)return}let o=t;if(i&&i.length>0){let e=new Map;for(let t of i){let n=this._registerTransferredPort(t);e.set(t,n)}o=substitutePorts(t,e)}let c=n(o),l=JSON.stringify(c),u=JSON.stringify(s),d=`(function(){${e}var d = __decodeBin(JSON.parse(${JSON.stringify(l)})); if (window.__gjsifySubstitutePorts) d = window.__gjsifySubstitutePorts(d); window.dispatchEvent(new MessageEvent('message', { data: d, origin: ${u} }));})();`;this._webView.evaluate_javascript(d,-1,null,null,null).catch(()=>{})}destroy(){this._signalId!==null&&(this._userContentManager.disconnect(this._signalId),this._signalId=null),this._userContentManager.unregister_script_message_handler(o,null),this._windowProxy=null}_setupReceiver(){this._userContentManager.register_script_message_handler(o,null),this._signalId=this._userContentManager.connect(`script-message-received::${o}`,(e,n)=>{if(this._windowProxy)try{let e=n.to_string(),i=JSON.parse(e);if(typeof i.__gjsifyPortMessage==`number`){let e=i,n=this._ports.get(e.__gjsifyPortMessage);n&&n._receive(t(e.payload));return}if(typeof i.__gjsifyPortClose==`number`){let e=i,t=this._ports.get(e.__gjsifyPortClose);t&&t.close(),this._ports.delete(e.__gjsifyPortClose);return}let a=i,o=a.targetOrigin;if(o!==`*`&&o!==`https://gjsify.local`)return;let s=new r(`message`,{data:t(a.data),origin:a.origin});this._windowProxy.dispatchEvent(s)}catch(e){console.error(`[IFrame MessageBridge] Error processing message:`,e)}})}_injectBootstrapScript(){let e=new i.UserScript(c,i.UserContentInjectedFrames.ALL_FRAMES,i.UserScriptInjectionTime.START,null,null);this._userContentManager.add_script(e)}};function substitutePorts(e,t){let n=new WeakMap;function walk(e){if(typeof e!=`object`||!e)return e;if(e[Symbol.toStringTag]===`MessagePort`&&t.has(e))return{__gjsifyPort:t.get(e)};if(n.has(e))return n.get(e);if(Array.isArray(e)){let t=[];n.set(e,t);for(let n=0;n<e.length;n++)t[n]=walk(e[n]);return t}if(Object.prototype.toString.call(e).slice(8,-1)===`Object`){let t={};n.set(e,t);for(let n of Object.keys(e))t[n]=walk(e[n]);return t}return e}return walk(e)}export{BOOTSTRAP_SCRIPT_FOR_TEST,s as GJS_HOST_ORIGIN,MessageBridge,normaliseTargetOrigin};

package/lib/esm/serialize.js

@@ -0,0 +1,58 @@
+import"./_virtual/_rolldown/runtime.js";const e=[`ArrayBuffer`,`Uint8Array`,`Uint8ClampedArray`,`Int8Array`,`Uint16Array`,`Int16Array`,`Uint32Array`,`Int32Array`,`BigUint64Array`,`BigInt64Array`,`Float32Array`,`Float64Array`,`DataView`];function classOf(e){return Object.prototype.toString.call(e).slice(8,-1)}function isBinaryType(t){return e.includes(t)}function bytesToBase64(e){let t=e;if(typeof t.toBase64==`function`)return t.toBase64();let n=``;for(let t=0;t<e.length;t++)n+=String.fromCharCode(e[t]);return globalThis.btoa(n)}function base64ToBytes(e){let t=Uint8Array;if(typeof t.fromBase64==`function`)return t.fromBase64(e);let n=globalThis.atob(e),r=new Uint8Array(n.length);for(let e=0;e<n.length;e++)r[e]=n.charCodeAt(e);return r}function makePlaceholder(e){let t=classOf(e);if(e instanceof ArrayBuffer)return{__gjsifyBin:`b64`,type:t,data:bytesToBase64(new Uint8Array(e))};if(e instanceof DataView)return{__gjsifyBin:`b64`,type:`DataView`,data:bytesToBase64(new Uint8Array(e.buffer,e.byteOffset,e.byteLength))};let n=e;return{__gjsifyBin:`b64`,type:t,data:bytesToBase64(new Uint8Array(n.buffer,n.byteOffset,n.byteLength)),length:n.length}}function reconstructFromPlaceholder(e){let t=base64ToBytes(e.data);switch(e.type){case`ArrayBuffer`:return t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength);case`DataView`:return new DataView(t.buffer,t.byteOffset,t.byteLength);case`Uint8Array`:return t;case`Uint8ClampedArray`:return new Uint8ClampedArray(t.buffer,t.byteOffset,t.byteLength);case`Int8Array`:return new Int8Array(t.buffer,t.byteOffset,t.byteLength);case`Uint16Array`:return new Uint16Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`Int16Array`:return new Int16Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`Uint32Array`:return new Uint32Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`Int32Array`:return new Int32Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`BigUint64Array`:return new BigUint64Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`BigInt64Array`:return new BigInt64Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`Float32Array`:return new Float32Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength));case`Float64Array`:return new Float64Array(t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength))}}function isPlaceholder(e){return typeof e==`object`&&!!e&&e.__gjsifyBin===`b64`&&typeof e.type==`string`&&typeof e.data==`string`}function encodeBinariesForJson(e){let t=new WeakMap;function walk(e){if(typeof e!=`object`||!e)return e;let n=classOf(e);if(isBinaryType(n))return makePlaceholder(e);if(t.has(e))return t.get(e);if(Array.isArray(e)){let n=[];t.set(e,n);for(let t=0;t<e.length;t++)n[t]=walk(e[t]);return n}if(n===`Object`){let n={};t.set(e,n);for(let t of Object.keys(e))n[t]=walk(e[t]);return n}return e}return walk(e)}function decodeBinariesFromJson(e){let t=new WeakSet;function walk(e){if(typeof e!=`object`||!e)return e;if(isPlaceholder(e))return reconstructFromPlaceholder(e);if(t.has(e))return e;if(t.add(e),Array.isArray(e)){for(let t=0;t<e.length;t++)e[t]=walk(e[t]);return e}if(classOf(e)===`Object`){for(let t of Object.keys(e))e[t]=walk(e[t]);return e}return e}return walk(e)}const t=`
+  var __binKey = '__gjsifyBin';
+  var __binVal = 'b64';
+  var __binCtors = ${JSON.stringify(e)};
+  function __classOf(v){ return Object.prototype.toString.call(v).slice(8,-1); }
+  function __isBin(n){ return __binCtors.indexOf(n) !== -1; }
+  function __b64enc(bytes){
+    if (typeof bytes.toBase64 === 'function') return bytes.toBase64();
+    var s=''; for (var i=0;i<bytes.length;i++) s+=String.fromCharCode(bytes[i]);
+    return btoa(s);
+  }
+  function __b64dec(s){
+    if (typeof Uint8Array.fromBase64 === 'function') return Uint8Array.fromBase64(s);
+    var bin = atob(s); var u = new Uint8Array(bin.length);
+    for (var i=0;i<bin.length;i++) u[i] = bin.charCodeAt(i);
+    return u;
+  }
+  function __mkPlaceholder(v){
+    var t = __classOf(v);
+    if (v instanceof ArrayBuffer) return {__gjsifyBin:__binVal, type:t, data:__b64enc(new Uint8Array(v))};
+    if (v instanceof DataView)    return {__gjsifyBin:__binVal, type:'DataView', data:__b64enc(new Uint8Array(v.buffer, v.byteOffset, v.byteLength))};
+    var ta = v; return {__gjsifyBin:__binVal, type:t, data:__b64enc(new Uint8Array(ta.buffer, ta.byteOffset, ta.byteLength)), length:ta.length};
+  }
+  function __reconstruct(p){
+    var bytes = __b64dec(p.data);
+    switch (p.type) {
+      case 'ArrayBuffer': return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+      case 'DataView':    return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+      case 'Uint8Array':  return bytes;
+      case 'Uint8ClampedArray': return new Uint8ClampedArray(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+      case 'Int8Array':   return new Int8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+      case 'Uint16Array': return new Uint16Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'Int16Array':  return new Int16Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'Uint32Array': return new Uint32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'Int32Array':  return new Int32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'BigUint64Array': return new BigUint64Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'BigInt64Array':  return new BigInt64Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'Float32Array': return new Float32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+      case 'Float64Array': return new Float64Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+    }
+  }
+  function __isPlaceholder(v){ return v && typeof v==='object' && v[__binKey]===__binVal && typeof v.type==='string' && typeof v.data==='string'; }
+  function __encodeBin(v){
+    if (v === null || typeof v !== 'object') return v;
+    var c = __classOf(v);
+    if (__isBin(c)) return __mkPlaceholder(v);
+    if (Array.isArray(v)) { var o=[]; for (var i=0;i<v.length;i++) o[i]=__encodeBin(v[i]); return o; }
+    if (c==='Object') { var o={}; for (var k in v) if (Object.prototype.hasOwnProperty.call(v,k)) o[k]=__encodeBin(v[k]); return o; }
+    return v;
+  }
+  function __decodeBin(v){
+    if (v === null || typeof v !== 'object') return v;
+    if (__isPlaceholder(v)) return __reconstruct(v);
+    if (Array.isArray(v)) { for (var i=0;i<v.length;i++) v[i]=__decodeBin(v[i]); return v; }
+    if (__classOf(v)==='Object') { for (var k in v) if (Object.prototype.hasOwnProperty.call(v,k)) v[k]=__decodeBin(v[k]); return v; }
+    return v;
+  }
+`;export{t as BINARY_SERIALIZER_INJECTED_SRC,decodeBinariesFromJson,encodeBinariesForJson};

package/lib/types/iframe-message-channel.d.ts

@@ -0,0 +1,38 @@
+import { EventTarget } from '@gjsify/dom-events';
+import type { MessageBridge } from './message-bridge.js';
+export declare class IFrameMessagePort extends EventTarget {
+    /** @internal In-process partner; null when this port has been transferred. */
+    _partner: IFrameMessagePort | null;
+    /** @internal Set once this port has been passed in a transferList — can no longer post locally. */
+    _transferred: boolean;
+    /** @internal Set when the partner of this port has been transferred — this port now routes via the bridge. */
+    _bridge: MessageBridge | null;
+    /** @internal Bridge-side identifier when this port is wired to a remote endpoint. */
+    _portId: number | null;
+    /** @internal W3C: dispatching is gated until .start() (or first addEventListener('message')). */
+    _started: boolean;
+    /** @internal Messages received before .start() */
+    _queue: unknown[];
+    /** @internal Closed by close() */
+    _closed: boolean;
+    postMessage(data: unknown): void;
+    /**
+     * W3C: enables dispatching of queued messages. Explicit `start()`
+     * is optional — adding a 'message' listener via addEventListener
+     * auto-starts. This method exists for explicit control + .onmessage
+     * setter compatibility (not implemented yet).
+     */
+    start(): void;
+    close(): void;
+    /** @internal Called by the bridge or the in-process partner. */
+    _receive(data: unknown): void;
+    private _dispatch;
+    addEventListener(type: string, listener: any, options?: any): void;
+    get [Symbol.toStringTag](): string;
+}
+export declare class IFrameMessageChannel {
+    readonly port1: IFrameMessagePort;
+    readonly port2: IFrameMessagePort;
+    constructor();
+    get [Symbol.toStringTag](): string;
+}

package/lib/types/iframe-message-channel.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/iframe-window-proxy.d.ts

@@ -1,5 +1,6 @@
 import { EventTarget } from '@gjsify/dom-events';
 import type { MessageBridge } from './message-bridge.js';
+import type { IFrameMessagePort } from './iframe-message-channel.js';
 /**
  * Lightweight Window-like proxy returned by `HTMLIFrameElement.contentWindow`.
  *
@@ -20,10 +21,16 @@ export declare class IFrameWindowProxy extends EventTarget {
     /**
      * Send a message to the iframe content.
      *
-     * @param message - Data to send (must be JSON-serializable)
-     * @param targetOrigin - Target origin for the message. Default: '*'
+     * @param message - Data to send (must be JSON-serializable + base64-encodable
+     *   binaries — see @gjsify/iframe/serialize for supported binary types).
+     * @param targetOrigin - Target origin for the message. Default: '*'.
+     * @param transfer - Optional list of `IFrameMessagePort` instances to
+     *   transfer. Each transferred port is detached locally; its surviving
+     *   partner becomes the GJS-side endpoint of a bidirectional channel
+     *   routed through the bridge. The WebView receives proxy ports under
+     *   `MessageEvent.data` wherever the original ports appeared in `message`.
      */
-    postMessage(message: unknown, targetOrigin?: string): void;
+    postMessage(message: unknown, targetOrigin?: string, transfer?: IFrameMessagePort[]): void;
     /**
      * Read-only location reflecting the current WebView URI.
      */

package/lib/types/index.d.ts

@@ -1,5 +1,6 @@
 export { HTMLIFrameElement } from './html-iframe-element.js';
 export { IFrameBridge } from './iframe-bridge.js';
 export { IFrameWindowProxy } from './iframe-window-proxy.js';
-export { MessageBridge } from './message-bridge.js';
+export { MessageBridge, GJS_HOST_ORIGIN } from './message-bridge.js';
+export { IFrameMessageChannel, IFrameMessagePort } from './iframe-message-channel.js';
 export type { IFrameBridgeOptions, IFrameReadyCallback, IFrameMessageData } from './types/index.js';

package/lib/types/message-bridge.d.ts

@@ -1,5 +1,46 @@
 import WebKit from 'gi://WebKit?version=6.0';
 import type { IFrameWindowProxy } from './iframe-window-proxy.js';
+import type { IFrameMessagePort } from './iframe-message-channel.js';
+/**
+ * Synthetic origin attached to messages travelling FROM the GJS host
+ * INTO the WebView. The WebView can use this in a targetOrigin filter to
+ * accept messages only when they originate from its hosting GJS process
+ * (vs. any other code that might inject script via developer tools).
+ *
+ * Uses the `https://` scheme so WHATWG URL parsing gives a real origin
+ * string (non-special schemes like `gjsify://` return `null` as origin
+ * per the URL spec, which would break the equality comparison the
+ * bridge does on every message). `.local` is the standard RFC 6762
+ * suffix for non-routable mDNS names, so it can't collide with a real
+ * site.
+ */
+export declare const GJS_HOST_ORIGIN = "https://gjsify.local";
+/**
+ * Per HTML spec for window.postMessage:
+ *   - '*'         → no origin restriction
+ *   - URL string  → only deliver if destination origin matches URL.origin
+ *   - '/'         → only deliver if destination origin matches source origin
+ *   - other       → throw SyntaxError
+ *
+ * Returns the canonical origin string (e.g. 'https://example.com'),
+ * `'*'`, or `null` if the input is `'/'`. Throws `SyntaxError` for
+ * malformed input.
+ */
+export declare function normaliseTargetOrigin(targetOrigin: string): string | null;
+/**
+ * Bootstrap script injected into every WebView page at document start.
+ * Provides the `window.parent.postMessage()` bridge from WebView content back to GJS.
+ *
+ * The script:
+ * 1. Gets the WebKit message handler registered under CHANNEL_NAME
+ * 2. Creates a parent proxy with a postMessage() that sends via the WebKit handler
+ * 3. Overrides window.parent to point to the proxy
+ */
+/**
+ * @internal Exposed only for unit testing — verifies the bootstrap
+ * idempotency guard survives refactors. Not part of the public API.
+ */
+export declare const BOOTSTRAP_SCRIPT_FOR_TEST: () => string;
 /**
  * Manages bidirectional postMessage communication between GJS and a WebKit.WebView.
  *
@@ -17,6 +58,11 @@ export declare class MessageBridge {
     private _windowProxy;
     private _currentUri;
     private _signalId;
+    /** GJS-side endpoints of transferred ports, keyed by per-bridge id.
+     *  When the WebView sends a `{__gjsifyPortMessage: id, payload}` envelope,
+     *  we route the payload to `_ports.get(id)._receive(decoded)`. */
+    private _ports;
+    private _nextPortId;
     constructor(webView: WebKit.WebView);
     /** Connect the IFrameWindowProxy that will receive messages from the WebView */
     setWindowProxy(proxy: IFrameWindowProxy): void;
@@ -31,7 +77,26 @@ export declare class MessageBridge {
      * Send a message from GJS to the WebView content.
      * Dispatches a standard MessageEvent on the WebView's window object.
      */
-    sendToWebView(data: unknown, _targetOrigin: string): void;
+    /**
+     * Register a port pair for cross-bridge transfer. Called by
+     * IFrameWindowProxy.postMessage when it sees an IFrameMessagePort
+     * in the transferList. Returns the port-id placeholder that should
+     * be substituted into the outgoing payload.
+     *
+     * Marks the transferred port as detached locally and wires its
+     * surviving partner so the partner's postMessage routes back over
+     * the bridge.
+     */
+    _registerTransferredPort(port: IFrameMessagePort): number;
+    /** @internal Called by IFrameMessagePort.postMessage when its partner
+     *  was transferred to the WebView. Dispatches the data onto the
+     *  WebView-side proxy port via evaluate_javascript. */
+    _sendPortMessage(portId: number, data: unknown): void;
+    /** @internal Called by IFrameMessagePort.close to tear down the
+     *  bridge-side registration. The WebView side keeps its proxy port
+     *  alive in user-script land but subsequent .deliver calls go nowhere. */
+    _closePort(portId: number): void;
+    sendToWebView(data: unknown, targetOrigin: string, transfer?: IFrameMessagePort[]): void;
     /** Clean up signal handlers */
     destroy(): void;
     /**
@@ -39,6 +104,12 @@ export declare class MessageBridge {
      * Registers a script message handler and connects to the signal.
      */
     private _setupReceiver;
+    /**
+     * Walk the user payload and replace each IFrameMessagePort instance
+     * (transferred via the transferList) with a {__gjsifyPort: id}
+     * placeholder. Non-transferred ports are passed through untouched —
+     * matches W3C semantics where only ports in transferList are detached.
+     */
     /**
      * Inject the bootstrap script into the WebView so that
      * window.parent.postMessage() bridges back to GJS.

package/lib/types/serialize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Walk `value`, substituting any binary buffer/view with a base64
+ * placeholder. Returns the substituted tree (copy-on-write — input
+ * untouched). Cycles produce cycle-preserving output.
+ */
+export declare function encodeBinariesForJson(value: unknown): unknown;
+/**
+ * Reverse of `encodeBinariesForJson`. Walks the tree in place and
+ * replaces every placeholder with a reconstructed binary view. Returns
+ * the same tree reference (for parity with the encoder's contract).
+ */
+export declare function decodeBinariesFromJson(value: unknown): unknown;
+/**
+ * Inlined twin of the encode/decode pair as a string. Injected into the
+ * WebView bootstrap so the WebKit-side window.postMessage override can
+ * encode binaries before handing the JSON to GJS, and decode incoming
+ * GJS-originated placeholders back into typed arrays before dispatching
+ * MessageEvent.
+ *
+ * Kept in sync with the TS source above by manual review — small enough
+ * to audit at a glance, and the alternative (build-time string template)
+ * would tangle the bridge build pipeline for marginal gain.
+ */
+export declare const BINARY_SERIALIZER_INJECTED_SRC: string;

package/lib/types/serialize.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/iframe",
-    "version": "0.4.10",
+    "version": "0.4.12",
     "description": "HTMLIFrameElement for GJS, backed by WebKit.WebView",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -37,12 +37,12 @@
         "@girs/gtk-4.0": "4.23.0-4.0.0-rc.15",
         "@girs/javascriptcore-6.0": "2.52.1-4.0.0-rc.15",
         "@girs/webkit-6.0": "2.52.1-4.0.0-rc.15",
-        "@gjsify/dom-elements": "^0.4.10",
-        "@gjsify/dom-events": "^0.4.10"
+        "@gjsify/dom-elements": "^0.4.12",
+        "@gjsify/dom-events": "^0.4.12"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.4.10",
-        "@gjsify/unit": "^0.4.10",
+        "@gjsify/cli": "^0.4.12",
+        "@gjsify/unit": "^0.4.12",
         "@types/node": "^25.6.2",
         "typescript": "^6.0.3"
     }