@gjsify/iframe 0.1.0

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

@@ -0,0 +1,51 @@
+import { EventTarget } from '@gjsify/dom-events';
+import type { MessageBridge } from './message-bridge.js';
+/**
+ * Lightweight Window-like proxy returned by `HTMLIFrameElement.contentWindow`.
+ *
+ * Supports the subset of the Window API needed for cross-origin iframe communication:
+ * - `postMessage()` for sending messages to the iframe content
+ * - `addEventListener('message', ...)` for receiving messages from the iframe content
+ * - `location` (read-only) reflecting the current URI
+ * - `parent` reference to the host window
+ * - `closed` status
+ *
+ * This is intentionally NOT a full BrowserWindow — just enough for standard
+ * postMessage-based communication patterns.
+ */
+export declare class IFrameWindowProxy extends EventTarget {
+    private _bridge;
+    private _closed;
+    constructor(bridge: MessageBridge);
+    /**
+     * Send a message to the iframe content.
+     *
+     * @param message - Data to send (must be JSON-serializable)
+     * @param targetOrigin - Target origin for the message. Default: '*'
+     */
+    postMessage(message: unknown, targetOrigin?: string): void;
+    /**
+     * Read-only location reflecting the current WebView URI.
+     */
+    get location(): {
+        href: string;
+        origin: string;
+    };
+    /**
+     * Reference to the host (parent) window — in GJS this is globalThis.
+     */
+    get parent(): typeof globalThis;
+    /**
+     * Reference to the top-level window — in GJS this is globalThis.
+     */
+    get top(): typeof globalThis;
+    /**
+     * The window itself (self-reference per spec).
+     */
+    get self(): IFrameWindowProxy;
+    get window(): IFrameWindowProxy;
+    get closed(): boolean;
+    /** @internal Mark as closed when the WebView is destroyed */
+    _close(): void;
+    get [Symbol.toStringTag](): string;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+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';

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

@@ -0,0 +1,47 @@
+import WebKit from 'gi://WebKit?version=6.0';
+import type { IFrameWindowProxy } from './iframe-window-proxy.js';
+/**
+ * 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 declare class MessageBridge {
+    private _webView;
+    private _userContentManager;
+    private _windowProxy;
+    private _currentUri;
+    private _signalId;
+    constructor(webView: WebKit.WebView);
+    /** Connect the IFrameWindowProxy that will receive messages from the WebView */
+    setWindowProxy(proxy: IFrameWindowProxy): void;
+    /** Update current URI (called by IFrameWidget on load-changed) */
+    updateUri(uri: string): void;
+    /** Get current location info for the IFrameWindowProxy */
+    getLocation(): {
+        href: string;
+        origin: string;
+    };
+    /**
+     * 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;
+    /** Clean up signal handlers */
+    destroy(): void;
+    /**
+     * Set up the receiver for messages coming from the WebView.
+     * Registers a script message handler and connects to the signal.
+     */
+    private _setupReceiver;
+    /**
+     * Inject the bootstrap script into the WebView so that
+     * window.parent.postMessage() bridges back to GJS.
+     */
+    private _injectBootstrapScript;
+}

package/lib/types/property-symbol.d.ts

@@ -0,0 +1,3 @@
+export declare const iframeWidget: unique symbol;
+export declare const windowProxy: unique symbol;
+export declare const loaded: unique symbol;

package/lib/types/types/index.d.ts

@@ -0,0 +1,15 @@
+/** 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;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@gjsify/iframe",
+  "version": "0.1.0",
+  "description": "HTMLIFrameElement for GJS, backed by WebKit.WebView",
+  "type": "module",
+  "module": "lib/esm/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/esm/index.js"
+    }
+  },
+  "scripts": {
+    "clear": "rm -rf lib tmp tsconfig.tsbuildinfo test.gjs.mjs || exit 0",
+    "check": "tsc --noEmit",
+    "build": "yarn build:gjsify && yarn build:types",
+    "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+    "build:types": "tsc",
+    "build:test": "yarn build:test:gjs",
+    "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+    "test": "yarn build:gjsify && yarn build:test && yarn test:gjs",
+    "test:gjs": "gjs -m test.gjs.mjs"
+  },
+  "keywords": [
+    "gjs",
+    "iframe",
+    "webview",
+    "webkit",
+    "dom"
+  ],
+  "dependencies": {
+    "@girs/gjs": "^4.0.0-beta.42",
+    "@girs/gtk-4.0": "^4.22.1-4.0.0-beta.42",
+    "@girs/javascriptcore-6.0": "2.51.93-4.0.0-beta.42",
+    "@girs/webkit-6.0": "2.51.93-4.0.0-beta.42",
+    "@gjsify/dom-elements": "^0.1.0",
+    "@gjsify/dom-events": "^0.1.0"
+  },
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.0",
+    "@gjsify/unit": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/html-iframe-element.ts

@@ -0,0 +1,177 @@
+// HTMLIFrameElement for GJS — original implementation using WebKit.WebView
+// Reference: refs/happy-dom/packages/happy-dom/src/nodes/html-iframe-element/HTMLIFrameElement.ts
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement
+
+import { HTMLElement, PropertySymbol } from '@gjsify/dom-elements';
+import { Event } from '@gjsify/dom-events';
+import * as PS from './property-symbol.js';
+
+import type { IFrameWindowProxy } from './iframe-window-proxy.js';
+
+const { tagName, localName, namespaceURI } = PropertySymbol;
+
+/**
+ * HTML IFrame Element.
+ *
+ * Backed by WebKit.WebView when connected to an IFrameWidget.
+ * Without a backing widget, behaves as a pure DOM element with attribute storage.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement
+ */
+export class HTMLIFrameElement extends HTMLElement {
+	/** @internal The backing IFrameWidget (set by IFrameWidget when it creates this element) */
+	[PS.iframeWidget]: import('./iframe-widget.js').IFrameWidget | null = null;
+
+	/** @internal The contentWindow proxy */
+	[PS.windowProxy]: IFrameWindowProxy | null = null;
+
+	/** @internal Whether content has been loaded */
+	[PS.loaded]: boolean = false;
+
+	constructor() {
+		super();
+		this[tagName] = 'IFRAME';
+		this[localName] = 'iframe';
+		this[namespaceURI] = 'http://www.w3.org/1999/xhtml';
+	}
+
+	// -- Attribute-backed string properties --
+
+	get src(): string {
+		return this.getAttribute('src') ?? '';
+	}
+
+	set src(value: string) {
+		const old = this.getAttribute('src');
+		this.setAttribute('src', value);
+		if (value !== old && value && this[PS.iframeWidget]) {
+			this[PS.iframeWidget].loadUri(value);
+		}
+	}
+
+	get srcdoc(): string {
+		return this.getAttribute('srcdoc') ?? '';
+	}
+
+	set srcdoc(value: string) {
+		const old = this.getAttribute('srcdoc');
+		this.setAttribute('srcdoc', value);
+		if (value !== old && value && this[PS.iframeWidget]) {
+			this[PS.iframeWidget].loadHtml(value);
+		}
+	}
+
+	get name(): string {
+		return this.getAttribute('name') ?? '';
+	}
+
+	set name(value: string) {
+		this.setAttribute('name', value);
+	}
+
+	get sandbox(): string {
+		return this.getAttribute('sandbox') ?? '';
+	}
+
+	set sandbox(value: string) {
+		this.setAttribute('sandbox', value);
+	}
+
+	get allow(): string {
+		return this.getAttribute('allow') ?? '';
+	}
+
+	set allow(value: string) {
+		this.setAttribute('allow', value);
+	}
+
+	get referrerPolicy(): string {
+		return this.getAttribute('referrerpolicy') ?? '';
+	}
+
+	set referrerPolicy(value: string) {
+		this.setAttribute('referrerpolicy', value);
+	}
+
+	get loading(): string {
+		const value = this.getAttribute('loading');
+		if (value === 'lazy' || value === 'eager') return value;
+		return 'eager';
+	}
+
+	set loading(value: string) {
+		this.setAttribute('loading', value);
+	}
+
+	// -- Attribute-backed string properties (width/height are strings per spec) --
+
+	get width(): string {
+		return this.getAttribute('width') ?? '';
+	}
+
+	set width(value: string) {
+		this.setAttribute('width', value);
+	}
+
+	get height(): string {
+		return this.getAttribute('height') ?? '';
+	}
+
+	set height(value: string) {
+		this.setAttribute('height', value);
+	}
+
+	// -- Content access --
+
+	/**
+	 * Returns the window proxy for the iframe's content.
+	 * Available after the IFrameWidget has loaded content.
+	 */
+	get contentWindow(): IFrameWindowProxy | null {
+		return this[PS.windowProxy];
+	}
+
+	/**
+	 * Always returns null — cross-context boundary.
+	 * The WebView content runs in a separate process; direct document access
+	 * is not feasible. Use postMessage() for communication.
+	 */
+	get contentDocument(): null {
+		return null;
+	}
+
+	// -- Methods --
+
+	/**
+	 * Returns a promise that resolves to the iframe's src URL.
+	 */
+	getSVGDocument(): null {
+		return null;
+	}
+
+	cloneNode(deep = false): HTMLIFrameElement {
+		const clone = super.cloneNode(deep) as HTMLIFrameElement;
+		// Cloned iframes are not connected to any widget
+		clone[PS.iframeWidget] = null;
+		clone[PS.windowProxy] = null;
+		clone[PS.loaded] = false;
+		return clone;
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'HTMLIFrameElement';
+	}
+
+	// -- Internal: called by IFrameWidget --
+
+	/** @internal Fire load event */
+	_onLoad(): void {
+		this[PS.loaded] = true;
+		this.dispatchEvent(new Event('load'));
+	}
+
+	/** @internal Fire error event */
+	_onError(): void {
+		this.dispatchEvent(new Event('error'));
+	}
+}

package/src/iframe-widget.ts

@@ -0,0 +1,158 @@
+// IFrameWidget GTK widget for GJS — original implementation using WebKit.WebView
+// Provides a WebKit.WebView subclass that bundles all iframe bootstrapping.
+// Pattern follows packages/dom/webgl/src/ts/webgl-area.ts (WebGLArea)
+
+import GObject from 'gi://GObject';
+import WebKit from 'gi://WebKit?version=6.0';
+
+import { HTMLIFrameElement } from './html-iframe-element.js';
+import { IFrameWindowProxy } from './iframe-window-proxy.js';
+import { MessageBridge } from './message-bridge.js';
+import * as PS from './property-symbol.js';
+
+import type { IFrameWidgetOptions, IFrameReadyCallback } from './types/index.js';
+
+/**
+ * A `WebKit.WebView` subclass that handles iframe bootstrapping:
+ * - Sets up WebKit settings (JavaScript, developer extras)
+ * - Creates an `HTMLIFrameElement` wrapping this WebView
+ * - Sets up postMessage bridge for GJS ↔ WebView communication
+ * - Fires `onReady()` callbacks with the iframe element once loaded
+ * - `installGlobals()` sets `globalThis.HTMLIFrameElement`
+ *
+ * Usage:
+ * ```ts
+ * const iframeWidget = new IFrameWidget();
+ * iframeWidget.installGlobals();
+ * iframeWidget.onReady((iframe) => {
+ *     iframe.contentWindow?.addEventListener('message', (e) => {
+ *         console.log('Message from iframe:', e.data);
+ *     });
+ * });
+ * iframeWidget.iframeElement.src = 'https://example.com';
+ * window.set_child(iframeWidget);
+ * ```
+ */
+export const IFrameWidget = GObject.registerClass(
+	{ GTypeName: 'GjsifyIFrameWidget' },
+	class IFrameWidget extends WebKit.WebView {
+		_iframe: HTMLIFrameElement;
+		_messageBridge: MessageBridge;
+		_readyCallbacks: IFrameReadyCallback[] = [];
+		_options: IFrameWidgetOptions;
+
+		constructor(options?: IFrameWidgetOptions & Partial<WebKit.WebView.ConstructorProps>) {
+			const { enableDeveloperExtras, enableJavascript, ...webViewProps } = options ?? {};
+
+			const userContentManager = new WebKit.UserContentManager();
+			const settings = new WebKit.Settings();
+			settings.enable_javascript = enableJavascript ?? true;
+			settings.enable_developer_extras = enableDeveloperExtras ?? true;
+
+			super({
+				...webViewProps,
+				user_content_manager: userContentManager,
+				settings,
+			});
+
+			this._options = { enableDeveloperExtras, enableJavascript };
+
+			// Create the DOM element and link it to this widget
+			this._iframe = new HTMLIFrameElement();
+			this._iframe[PS.iframeWidget] = this as unknown as import('./iframe-widget.js').IFrameWidget;
+
+			// Set up the message bridge
+			this._messageBridge = new MessageBridge(this);
+
+			// Create the window proxy and connect it
+			const windowProxy = new IFrameWindowProxy(this._messageBridge);
+			this._iframe[PS.windowProxy] = windowProxy;
+			this._messageBridge.setWindowProxy(windowProxy);
+
+			// Track load state
+			this.connect('load-changed', (_webView: WebKit.WebView, event: WebKit.LoadEvent) => {
+				switch (event) {
+					case WebKit.LoadEvent.COMMITTED: {
+						const uri = this.get_uri();
+						if (uri) this._messageBridge.updateUri(uri);
+						break;
+					}
+					case WebKit.LoadEvent.FINISHED:
+						this._iframe._onLoad();
+						for (const cb of this._readyCallbacks) {
+							cb(this._iframe as unknown as globalThis.HTMLIFrameElement);
+						}
+						this._readyCallbacks = [];
+						break;
+				}
+			});
+
+			this.connect('load-failed', () => {
+				this._iframe._onError();
+				return false;
+			});
+
+			this.connect('unrealize', () => {
+				this._messageBridge.destroy();
+				const proxy = this._iframe[PS.windowProxy];
+				if (proxy) {
+					proxy._close();
+				}
+				this._iframe[PS.iframeWidget] = null;
+				this._iframe[PS.windowProxy] = null;
+			});
+		}
+
+		/** The HTMLIFrameElement wrapping this WebView. */
+		get iframeElement(): HTMLIFrameElement {
+			return this._iframe;
+		}
+
+		/**
+		 * Register a callback to be invoked when content has loaded.
+		 * If content is already loaded, the callback fires on next load.
+		 */
+		onReady(cb: IFrameReadyCallback): void {
+			this._readyCallbacks.push(cb);
+		}
+
+		/**
+		 * Load a URI into the WebView.
+		 * Also updates the iframe element's src attribute.
+		 */
+		loadUri(uri: string): void {
+			this._iframe.setAttribute('src', uri);
+			this.load_uri(uri);
+		}
+
+		/**
+		 * Load inline HTML into the WebView.
+		 * Also updates the iframe element's srcdoc attribute.
+		 */
+		loadHtml(html: string, baseUri?: string): void {
+			this._iframe.setAttribute('srcdoc', html);
+			this.load_html(html, baseUri ?? 'about:srcdoc');
+		}
+
+		/**
+		 * Send a message to the WebView content via the standard postMessage API.
+		 * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
+		 */
+		postMessage(message: unknown, targetOrigin = '*'): void {
+			this._messageBridge.sendToWebView(message, targetOrigin);
+		}
+
+		/**
+		 * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+		 */
+		installGlobals(): void {
+			Object.defineProperty(globalThis, 'HTMLIFrameElement', {
+				value: HTMLIFrameElement,
+				writable: true,
+				configurable: true,
+			});
+		}
+	},
+);
+
+export type IFrameWidget = InstanceType<typeof IFrameWidget>;

package/src/iframe-window-proxy.ts

@@ -0,0 +1,86 @@
+// IFrameWindowProxy for GJS — lightweight Window proxy for iframe contentWindow
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
+// Reference: refs/happy-dom/packages/happy-dom/src/window/CrossOriginBrowserWindow.ts
+
+import { EventTarget } from '@gjsify/dom-events';
+
+import type { MessageBridge } from './message-bridge.js';
+
+/**
+ * Lightweight Window-like proxy returned by `HTMLIFrameElement.contentWindow`.
+ *
+ * Supports the subset of the Window API needed for cross-origin iframe communication:
+ * - `postMessage()` for sending messages to the iframe content
+ * - `addEventListener('message', ...)` for receiving messages from the iframe content
+ * - `location` (read-only) reflecting the current URI
+ * - `parent` reference to the host window
+ * - `closed` status
+ *
+ * This is intentionally NOT a full BrowserWindow — just enough for standard
+ * postMessage-based communication patterns.
+ */
+export class IFrameWindowProxy extends EventTarget {
+	private _bridge: MessageBridge;
+	private _closed = false;
+
+	constructor(bridge: MessageBridge) {
+		super();
+		this._bridge = bridge;
+	}
+
+	/**
+	 * Send a message to the iframe content.
+	 *
+	 * @param message - Data to send (must be JSON-serializable)
+	 * @param targetOrigin - Target origin for the message. Default: '*'
+	 */
+	postMessage(message: unknown, targetOrigin = '*'): void {
+		if (this._closed) return;
+		this._bridge.sendToWebView(message, targetOrigin);
+	}
+
+	/**
+	 * Read-only location reflecting the current WebView URI.
+	 */
+	get location(): { href: string; origin: string } {
+		return this._bridge.getLocation();
+	}
+
+	/**
+	 * Reference to the host (parent) window — in GJS this is globalThis.
+	 */
+	get parent(): typeof globalThis {
+		return globalThis;
+	}
+
+	/**
+	 * Reference to the top-level window — in GJS this is globalThis.
+	 */
+	get top(): typeof globalThis {
+		return globalThis;
+	}
+
+	/**
+	 * The window itself (self-reference per spec).
+	 */
+	get self(): IFrameWindowProxy {
+		return this;
+	}
+
+	get window(): IFrameWindowProxy {
+		return this;
+	}
+
+	get closed(): boolean {
+		return this._closed;
+	}
+
+	/** @internal Mark as closed when the WebView is destroyed */
+	_close(): void {
+		this._closed = true;
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'IFrameWindowProxy';
+	}
+}