@gjsify/iframe 0.1.0

package/src/index.spec.ts

@@ -0,0 +1,323 @@
+// Tests for @gjsify/iframe — HTMLIFrameElement, IFrameWindowProxy, IFrameWidget
+// Reference: refs/happy-dom/packages/happy-dom/test/nodes/html-iframe-element/
+
+import { describe, it, expect } from '@gjsify/unit';
+
+// Import index.ts to trigger side-effect registration (Document.registerElementFactory)
+import { HTMLIFrameElement, IFrameWindowProxy } from './index.js';
+import { Document } from '@gjsify/dom-elements';
+import { HTMLElement, Element, Node } from '@gjsify/dom-elements';
+import { MessageEvent } from '@gjsify/dom-events';
+
+export default async () => {
+	// -- HTMLIFrameElement DOM properties --
+
+	await describe('HTMLIFrameElement', async () => {
+		await it('should be an instance of HTMLElement, Element, and Node', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe instanceof HTMLElement).toBe(true);
+			expect(iframe instanceof Element).toBe(true);
+			expect(iframe instanceof Node).toBe(true);
+		});
+
+		await it('should have correct tagName and localName', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.tagName).toBe('IFRAME');
+			expect(iframe.localName).toBe('iframe');
+		});
+
+		await it('should have correct [Symbol.toStringTag]', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(Object.prototype.toString.call(iframe)).toBe('[object HTMLIFrameElement]');
+		});
+
+		// -- src --
+
+		await it('should get/set src', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.src).toBe('');
+			iframe.setAttribute('src', 'https://example.com');
+			expect(iframe.src).toBe('https://example.com');
+		});
+
+		await it('should reflect src to attribute', async () => {
+			const iframe = new HTMLIFrameElement();
+			iframe.src = 'https://example.com';
+			expect(iframe.getAttribute('src')).toBe('https://example.com');
+		});
+
+		// -- srcdoc --
+
+		await it('should get/set srcdoc', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.srcdoc).toBe('');
+			iframe.setAttribute('srcdoc', '<h1>Hello</h1>');
+			expect(iframe.srcdoc).toBe('<h1>Hello</h1>');
+		});
+
+		await it('should reflect srcdoc to attribute', async () => {
+			const iframe = new HTMLIFrameElement();
+			iframe.srcdoc = '<p>test</p>';
+			expect(iframe.getAttribute('srcdoc')).toBe('<p>test</p>');
+		});
+
+		// -- name --
+
+		await it('should get/set name', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.name).toBe('');
+			iframe.name = 'my-frame';
+			expect(iframe.name).toBe('my-frame');
+			expect(iframe.getAttribute('name')).toBe('my-frame');
+		});
+
+		// -- sandbox --
+
+		await it('should get/set sandbox', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.sandbox).toBe('');
+			iframe.sandbox = 'allow-scripts allow-same-origin';
+			expect(iframe.sandbox).toBe('allow-scripts allow-same-origin');
+			expect(iframe.getAttribute('sandbox')).toBe('allow-scripts allow-same-origin');
+		});
+
+		// -- allow --
+
+		await it('should get/set allow', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.allow).toBe('');
+			iframe.allow = 'fullscreen; autoplay';
+			expect(iframe.allow).toBe('fullscreen; autoplay');
+			expect(iframe.getAttribute('allow')).toBe('fullscreen; autoplay');
+		});
+
+		// -- referrerPolicy --
+
+		await it('should get/set referrerPolicy', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.referrerPolicy).toBe('');
+			iframe.referrerPolicy = 'no-referrer';
+			expect(iframe.referrerPolicy).toBe('no-referrer');
+			expect(iframe.getAttribute('referrerpolicy')).toBe('no-referrer');
+		});
+
+		// -- loading --
+
+		await it('should get/set loading with valid values', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.loading).toBe('eager');
+			iframe.loading = 'lazy';
+			expect(iframe.loading).toBe('lazy');
+			iframe.loading = 'eager';
+			expect(iframe.loading).toBe('eager');
+		});
+
+		await it('should default loading to "eager" for invalid values', async () => {
+			const iframe = new HTMLIFrameElement();
+			iframe.loading = 'invalid';
+			expect(iframe.loading).toBe('eager');
+		});
+
+		// -- width / height --
+
+		await it('should get/set width as string', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.width).toBe('');
+			iframe.width = '300';
+			expect(iframe.width).toBe('300');
+			expect(iframe.getAttribute('width')).toBe('300');
+		});
+
+		await it('should get/set height as string', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.height).toBe('');
+			iframe.height = '200';
+			expect(iframe.height).toBe('200');
+			expect(iframe.getAttribute('height')).toBe('200');
+		});
+
+		// -- contentWindow / contentDocument --
+
+		await it('should return null for contentWindow without backing widget', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.contentWindow).toBeNull();
+		});
+
+		await it('should always return null for contentDocument', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.contentDocument).toBeNull();
+		});
+
+		// -- Events --
+
+		await it('should dispatch load event via _onLoad()', async () => {
+			const iframe = new HTMLIFrameElement();
+			let loaded = false;
+			iframe.addEventListener('load', () => { loaded = true; });
+			iframe._onLoad();
+			expect(loaded).toBe(true);
+		});
+
+		await it('should dispatch error event via _onError()', async () => {
+			const iframe = new HTMLIFrameElement();
+			let errored = false;
+			iframe.addEventListener('error', () => { errored = true; });
+			iframe._onError();
+			expect(errored).toBe(true);
+		});
+
+		await it('should support onload property handler', async () => {
+			const iframe = new HTMLIFrameElement();
+			let called = false;
+			iframe.onload = () => { called = true; };
+			iframe._onLoad();
+			expect(called).toBe(true);
+		});
+
+		await it('should support onerror property handler', async () => {
+			const iframe = new HTMLIFrameElement();
+			let called = false;
+			iframe.onerror = () => { called = true; };
+			iframe._onError();
+			expect(called).toBe(true);
+		});
+
+		// -- Clone --
+
+		await it('should clone without widget reference', async () => {
+			const iframe = new HTMLIFrameElement();
+			iframe.src = 'https://example.com';
+			iframe.name = 'test-frame';
+			const clone = iframe.cloneNode(false);
+			expect(clone instanceof HTMLIFrameElement).toBe(true);
+			expect(clone.getAttribute('src')).toBe('https://example.com');
+			expect(clone.getAttribute('name')).toBe('test-frame');
+			expect(clone.contentWindow).toBeNull();
+		});
+
+		// -- getSVGDocument --
+
+		await it('should return null for getSVGDocument()', async () => {
+			const iframe = new HTMLIFrameElement();
+			expect(iframe.getSVGDocument()).toBeNull();
+		});
+	});
+
+	// -- Document.createElement('iframe') --
+
+	await describe('Document.registerElementFactory', async () => {
+		await it('should create HTMLIFrameElement via document.createElement', async () => {
+			// The factory is registered as a side-effect in index.ts
+			// which is imported by the test runner
+			const doc = new Document();
+			const iframe = doc.createElement('iframe');
+			expect(iframe instanceof HTMLIFrameElement).toBe(true);
+			expect(iframe.tagName).toBe('IFRAME');
+		});
+	});
+
+	// -- IFrameWindowProxy (unit tests without WebView) --
+
+	await describe('IFrameWindowProxy', async () => {
+		await it('should have correct [Symbol.toStringTag]', async () => {
+			// Create a minimal mock bridge for unit testing
+			const mockBridge = {
+				sendToWebView(_data: unknown, _targetOrigin: string) {},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			expect(Object.prototype.toString.call(proxy)).toBe('[object IFrameWindowProxy]');
+		});
+
+		await it('should return globalThis as parent', async () => {
+			const mockBridge = {
+				sendToWebView(_data: unknown, _targetOrigin: string) {},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			expect(proxy.parent).toBe(globalThis);
+		});
+
+		await it('should return globalThis as top', async () => {
+			const mockBridge = {
+				sendToWebView(_data: unknown, _targetOrigin: string) {},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			expect(proxy.top).toBe(globalThis);
+		});
+
+		await it('should return self references', async () => {
+			const mockBridge = {
+				sendToWebView(_data: unknown, _targetOrigin: string) {},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			expect(proxy.self).toBe(proxy);
+			expect(proxy.window).toBe(proxy);
+		});
+
+		await it('should report closed status', async () => {
+			const mockBridge = {
+				sendToWebView(_data: unknown, _targetOrigin: string) {},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			expect(proxy.closed).toBe(false);
+			proxy._close();
+			expect(proxy.closed).toBe(true);
+		});
+
+		await it('should delegate postMessage to bridge', async () => {
+			let sentData: unknown;
+			let sentOrigin: string | undefined;
+			const mockBridge = {
+				sendToWebView(data: unknown, targetOrigin: string) {
+					sentData = data;
+					sentOrigin = targetOrigin;
+				},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			proxy.postMessage({ hello: 'world' }, 'https://example.com');
+			expect((sentData as any).hello).toBe('world');
+			expect(sentOrigin).toBe('https://example.com');
+		});
+
+		await it('should not send message when closed', async () => {
+			let called = false;
+			const mockBridge = {
+				sendToWebView() { called = true; },
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			proxy._close();
+			proxy.postMessage('test');
+			expect(called).toBe(false);
+		});
+
+		await it('should return location from bridge', async () => {
+			const mockBridge = {
+				sendToWebView() {},
+				getLocation() { return { href: 'https://example.com/page', origin: 'https://example.com' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			expect(proxy.location.href).toBe('https://example.com/page');
+			expect(proxy.location.origin).toBe('https://example.com');
+		});
+
+		await it('should support addEventListener for message events', async () => {
+			const mockBridge = {
+				sendToWebView() {},
+				getLocation() { return { href: 'about:blank', origin: 'null' }; },
+			};
+			const proxy = new IFrameWindowProxy(mockBridge as any);
+			let received: unknown;
+			proxy.addEventListener('message', (event: Event) => {
+				received = (event as MessageEvent).data;
+			});
+			proxy.dispatchEvent(new MessageEvent('message', { data: 'hello' }));
+			expect(received).toBe('hello');
+		});
+	});
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+// HTMLIFrameElement for GJS — backed by WebKit.WebView
+// Reference: refs/happy-dom/packages/happy-dom/src/nodes/html-iframe-element/HTMLIFrameElement.ts
+// Reference: refs/map-editor/packages/message-channel-gjs/ (GJS ↔ WebView communication)
+
+export { HTMLIFrameElement } from './html-iframe-element.js';
+export { IFrameWidget } from './iframe-widget.js';
+export { IFrameWindowProxy } from './iframe-window-proxy.js';
+export { MessageBridge } from './message-bridge.js';
+export type { IFrameWidgetOptions, IFrameReadyCallback, IFrameMessageData } from './types/index.js';
+
+// Side-effect: register DOM globals on import.
+// Same pattern as @gjsify/dom-elements and @gjsify/canvas2d.
+import { Document } from '@gjsify/dom-elements';
+import { HTMLIFrameElement } from './html-iframe-element.js';
+
+// Register so that document.createElement('iframe') works
+Document.registerElementFactory('iframe', () => new HTMLIFrameElement());
+
+// Register global constructor
+Object.defineProperty(globalThis, 'HTMLIFrameElement', {
+	value: HTMLIFrameElement,
+	writable: true,
+	configurable: true,
+});

package/src/message-bridge.ts

@@ -0,0 +1,175 @@
+// MessageBridge for GJS — postMessage bridge between GJS and WebKit.WebView
+// Adapted from refs/map-editor/packages/message-channel-gjs/src/rpc-endpoint.ts
+// Copyright (c) PixelRPG contributors. MIT license.
+// Modifications: Simplified to standard postMessage semantics (no JSON-RPC layer)
+
+import Gio from 'gi://Gio?version=2.0';
+import WebKit from 'gi://WebKit?version=6.0';
+import JavaScriptCore from 'gi://JavaScriptCore?version=6.0';
+import { MessageEvent } from '@gjsify/dom-events';
+
+// Promisify evaluate_javascript so it returns a Promise in GJS
+Gio._promisify(WebKit.WebView.prototype, 'evaluate_javascript', 'evaluate_javascript_finish');
+
+import type { IFrameWindowProxy } from './iframe-window-proxy.js';
+import type { IFrameMessageData } from './types/index.js';
+
+const CHANNEL_NAME = 'gjsify-iframe';
+
+/**
+ * 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
+ */
+const BOOTSTRAP_SCRIPT = `(function() {
+    var handler = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers['${CHANNEL_NAME}'];
+    if (!handler) return;
+    function bridgePostMessage(data, targetOrigin) {
+        handler.postMessage(JSON.stringify({
+            data: data,
+            targetOrigin: targetOrigin || '*',
+            origin: location.origin
+        }));
+    }
+    // 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,
+    // calls to window.parent.postMessage() will use our override.
+    var origPostMessage = window.postMessage;
+    window.postMessage = function(data, targetOrigin) {
+        bridgePostMessage(data, targetOrigin);
+    };
+    // Also expose on a safe namespace for explicit use
+    window.__gjsifyBridge = { postMessage: bridgePostMessage, origPostMessage: origPostMessage };
+})();`;
+
+/**
+ * Manages bidirectional postMessage communication between GJS and a WebKit.WebView.
+ *
+ * Direction 1 — GJS → WebView:
+ *   Uses webView.evaluate_javascript() to dispatch a MessageEvent on the WebView's window.
+ *
+ * Direction 2 — WebView → GJS:
+ *   Bootstrap script overrides window.parent.postMessage to call
+ *   webkit.messageHandlers[CHANNEL_NAME].postMessage(), which triggers
+ *   the UserContentManager 'script-message-received' signal in GJS.
+ */
+export class MessageBridge {
+	private _webView: WebKit.WebView;
+	private _userContentManager: WebKit.UserContentManager;
+	private _windowProxy: IFrameWindowProxy | null = null;
+	private _currentUri = 'about:blank';
+	private _signalId: number | null = null;
+
+	constructor(webView: WebKit.WebView) {
+		this._webView = webView;
+		this._userContentManager = webView.get_user_content_manager();
+		this._setupReceiver();
+		this._injectBootstrapScript();
+	}
+
+	/** Connect the IFrameWindowProxy that will receive messages from the WebView */
+	setWindowProxy(proxy: IFrameWindowProxy): void {
+		this._windowProxy = proxy;
+	}
+
+	/** Update current URI (called by IFrameWidget on load-changed) */
+	updateUri(uri: string): void {
+		this._currentUri = uri;
+	}
+
+	/** Get current location info for the IFrameWindowProxy */
+	getLocation(): { href: string; origin: string } {
+		let origin: string;
+		try {
+			const url = new URL(this._currentUri);
+			origin = url.origin;
+		} catch {
+			origin = 'null';
+		}
+		return { href: this._currentUri, origin };
+	}
+
+	/**
+	 * 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 {
+		const serialized = JSON.stringify(data);
+		const origin = JSON.stringify('gjsify');
+		// Note: do not pass `source` — WebKit's MessageEvent constructor throws TypeError
+		// if source is not a valid MessageEventSource (Window/MessagePort/ServiceWorker)
+		const script = `window.dispatchEvent(new MessageEvent('message', { data: JSON.parse(${JSON.stringify(serialized)}), origin: ${origin} }));`;
+
+		// evaluate_javascript is async in WebKit 6.0 — fire and forget
+		this._webView.evaluate_javascript(
+			script,
+			-1,    // length (-1 = null-terminated)
+			null,  // world name (null = default)
+			null,  // source URI
+			null,  // cancellable
+		).catch(() => {
+			// Ignore errors for fire-and-forget message dispatch
+		});
+	}
+
+	/** Clean up signal handlers */
+	destroy(): void {
+		if (this._signalId !== null) {
+			this._userContentManager.disconnect(this._signalId);
+			this._signalId = null;
+		}
+		this._userContentManager.unregister_script_message_handler(CHANNEL_NAME, null);
+		this._windowProxy = null;
+	}
+
+	/**
+	 * Set up the receiver for messages coming from the WebView.
+	 * Registers a script message handler and connects to the signal.
+	 */
+	private _setupReceiver(): void {
+		this._userContentManager.register_script_message_handler(CHANNEL_NAME, null);
+
+		this._signalId = this._userContentManager.connect(
+			`script-message-received::${CHANNEL_NAME}`,
+			(_ucm: WebKit.UserContentManager, jsValue: JavaScriptCore.Value) => {
+				if (!this._windowProxy) return;
+
+				try {
+					// The bootstrap script sends JSON.stringify({data, targetOrigin, origin})
+					// so jsValue is a JSC string. Use to_string() to get the raw JSON.
+					const json = jsValue.to_string();
+					const envelope: IFrameMessageData = JSON.parse(json);
+
+					// Dispatch MessageEvent on the IFrameWindowProxy
+					const event = new MessageEvent('message', {
+						data: envelope.data,
+						origin: envelope.origin,
+					});
+					this._windowProxy.dispatchEvent(event);
+				} catch (error) {
+					console.error('[IFrame MessageBridge] Error processing message:', error);
+				}
+			},
+		);
+	}
+
+	/**
+	 * Inject the bootstrap script into the WebView so that
+	 * window.parent.postMessage() bridges back to GJS.
+	 */
+	private _injectBootstrapScript(): void {
+		const script = new WebKit.UserScript(
+			BOOTSTRAP_SCRIPT,
+			WebKit.UserContentInjectedFrames.ALL_FRAMES,
+			WebKit.UserScriptInjectionTime.START,
+			null,  // allow list (null = all)
+			null,  // block list (null = none)
+		);
+		this._userContentManager.add_script(script);
+	}
+}

package/src/property-symbol.ts

@@ -0,0 +1,11 @@
+// Iframe-specific property symbols
+// Follows pattern from packages/dom/dom-elements/src/property-symbol.ts
+
+// IFrameWidget (GTK WebView backing)
+export const iframeWidget = Symbol('iframeWidget');
+
+// IFrameWindowProxy (contentWindow)
+export const windowProxy = Symbol('windowProxy');
+
+// Loading state
+export const loaded = Symbol('loaded');

package/src/test.mts

@@ -0,0 +1,6 @@
+
+import { run } from '@gjsify/unit';
+
+import testSuite from './index.spec.js';
+
+run({ testSuite });

package/src/types/index.ts

@@ -0,0 +1,19 @@
+// Shared interfaces for @gjsify/iframe
+
+/** Options passed to IFrameWidget constructor */
+export interface IFrameWidgetOptions {
+    /** Enable developer extras (Web Inspector). Default: true */
+    enableDeveloperExtras?: boolean;
+    /** Enable JavaScript execution in the WebView. Default: true */
+    enableJavascript?: boolean;
+}
+
+/** Data structure for messages crossing the GJS/WebView boundary */
+export interface IFrameMessageData {
+    data: unknown;
+    targetOrigin: string;
+    origin: string;
+}
+
+/** Callback for when the IFrameWidget is ready */
+export type IFrameReadyCallback = (iframe: globalThis.HTMLIFrameElement) => void;