@gjsify/iframe 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @gjsify/iframe
+
+GJS implementation of HTMLIFrameElement using WebKit 6.0. Provides IFrameWidget extending WebKit.WebView with postMessage bridge.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+npm install @gjsify/iframe
+# or
+yarn add @gjsify/iframe
+```
+
+## Usage
+
+```typescript
+import { IFrameWidget } from '@gjsify/iframe';
+
+const widget = new IFrameWidget();
+
+widget.onReady((iframe) => {
+  iframe.contentWindow?.addEventListener('message', (event) => {
+    console.log(event.data);
+  });
+});
+
+widget.iframeElement.srcdoc = '<h1>Hello</h1>';
+window.set_child(widget);
+```
+
+## License
+
+MIT

package/lib/esm/html-iframe-element.js

@@ -0,0 +1,131 @@
+var _a, _b, _c;
+import { HTMLElement, PropertySymbol } from "@gjsify/dom-elements";
+import { Event } from "@gjsify/dom-events";
+import * as PS from "./property-symbol.js";
+const { tagName, localName, namespaceURI } = PropertySymbol;
+class HTMLIFrameElement extends HTMLElement {
+  constructor() {
+    super();
+    /** @internal The backing IFrameWidget (set by IFrameWidget when it creates this element) */
+    this[_c] = null;
+    /** @internal The contentWindow proxy */
+    this[_b] = null;
+    /** @internal Whether content has been loaded */
+    this[_a] = false;
+    this[tagName] = "IFRAME";
+    this[localName] = "iframe";
+    this[namespaceURI] = "http://www.w3.org/1999/xhtml";
+  }
+  // -- Attribute-backed string properties --
+  get src() {
+    return this.getAttribute("src") ?? "";
+  }
+  set src(value) {
+    const old = this.getAttribute("src");
+    this.setAttribute("src", value);
+    if (value !== old && value && this[PS.iframeWidget]) {
+      this[PS.iframeWidget].loadUri(value);
+    }
+  }
+  get srcdoc() {
+    return this.getAttribute("srcdoc") ?? "";
+  }
+  set srcdoc(value) {
+    const old = this.getAttribute("srcdoc");
+    this.setAttribute("srcdoc", value);
+    if (value !== old && value && this[PS.iframeWidget]) {
+      this[PS.iframeWidget].loadHtml(value);
+    }
+  }
+  get name() {
+    return this.getAttribute("name") ?? "";
+  }
+  set name(value) {
+    this.setAttribute("name", value);
+  }
+  get sandbox() {
+    return this.getAttribute("sandbox") ?? "";
+  }
+  set sandbox(value) {
+    this.setAttribute("sandbox", value);
+  }
+  get allow() {
+    return this.getAttribute("allow") ?? "";
+  }
+  set allow(value) {
+    this.setAttribute("allow", value);
+  }
+  get referrerPolicy() {
+    return this.getAttribute("referrerpolicy") ?? "";
+  }
+  set referrerPolicy(value) {
+    this.setAttribute("referrerpolicy", value);
+  }
+  get loading() {
+    const value = this.getAttribute("loading");
+    if (value === "lazy" || value === "eager") return value;
+    return "eager";
+  }
+  set loading(value) {
+    this.setAttribute("loading", value);
+  }
+  // -- Attribute-backed string properties (width/height are strings per spec) --
+  get width() {
+    return this.getAttribute("width") ?? "";
+  }
+  set width(value) {
+    this.setAttribute("width", value);
+  }
+  get height() {
+    return this.getAttribute("height") ?? "";
+  }
+  set height(value) {
+    this.setAttribute("height", value);
+  }
+  // -- Content access --
+  /**
+   * Returns the window proxy for the iframe's content.
+   * Available after the IFrameWidget has loaded content.
+   */
+  get contentWindow() {
+    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() {
+    return null;
+  }
+  // -- Methods --
+  /**
+   * Returns a promise that resolves to the iframe's src URL.
+   */
+  getSVGDocument() {
+    return null;
+  }
+  cloneNode(deep = false) {
+    const clone = super.cloneNode(deep);
+    clone[PS.iframeWidget] = null;
+    clone[PS.windowProxy] = null;
+    clone[PS.loaded] = false;
+    return clone;
+  }
+  get [(_c = PS.iframeWidget, _b = PS.windowProxy, _a = PS.loaded, Symbol.toStringTag)]() {
+    return "HTMLIFrameElement";
+  }
+  // -- Internal: called by IFrameWidget --
+  /** @internal Fire load event */
+  _onLoad() {
+    this[PS.loaded] = true;
+    this.dispatchEvent(new Event("load"));
+  }
+  /** @internal Fire error event */
+  _onError() {
+    this.dispatchEvent(new Event("error"));
+  }
+}
+export {
+  HTMLIFrameElement
+};

package/lib/esm/iframe-widget.js

@@ -0,0 +1,107 @@
+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";
+const IFrameWidget = GObject.registerClass(
+  { GTypeName: "GjsifyIFrameWidget" },
+  class IFrameWidget2 extends WebKit.WebView {
+    constructor(options) {
+      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._readyCallbacks = [];
+      this._options = { enableDeveloperExtras, enableJavascript };
+      this._iframe = new HTMLIFrameElement();
+      this._iframe[PS.iframeWidget] = this;
+      this._messageBridge = new MessageBridge(this);
+      const windowProxy = new IFrameWindowProxy(this._messageBridge);
+      this._iframe[PS.windowProxy] = windowProxy;
+      this._messageBridge.setWindowProxy(windowProxy);
+      this.connect("load-changed", (_webView, event) => {
+        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);
+            }
+            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() {
+      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) {
+      this._readyCallbacks.push(cb);
+    }
+    /**
+     * Load a URI into the WebView.
+     * Also updates the iframe element's src attribute.
+     */
+    loadUri(uri) {
+      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, baseUri) {
+      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, targetOrigin = "*") {
+      this._messageBridge.sendToWebView(message, targetOrigin);
+    }
+    /**
+     * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+     */
+    installGlobals() {
+      Object.defineProperty(globalThis, "HTMLIFrameElement", {
+        value: HTMLIFrameElement,
+        writable: true,
+        configurable: true
+      });
+    }
+  }
+);
+export {
+  IFrameWidget
+};

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

@@ -0,0 +1,58 @@
+import { EventTarget } from "@gjsify/dom-events";
+class IFrameWindowProxy extends EventTarget {
+  constructor(bridge) {
+    super();
+    this._closed = false;
+    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, targetOrigin = "*") {
+    if (this._closed) return;
+    this._bridge.sendToWebView(message, targetOrigin);
+  }
+  /**
+   * Read-only location reflecting the current WebView URI.
+   */
+  get location() {
+    return this._bridge.getLocation();
+  }
+  /**
+   * Reference to the host (parent) window — in GJS this is globalThis.
+   */
+  get parent() {
+    return globalThis;
+  }
+  /**
+   * Reference to the top-level window — in GJS this is globalThis.
+   */
+  get top() {
+    return globalThis;
+  }
+  /**
+   * The window itself (self-reference per spec).
+   */
+  get self() {
+    return this;
+  }
+  get window() {
+    return this;
+  }
+  get closed() {
+    return this._closed;
+  }
+  /** @internal Mark as closed when the WebView is destroyed */
+  _close() {
+    this._closed = true;
+  }
+  get [Symbol.toStringTag]() {
+    return "IFrameWindowProxy";
+  }
+}
+export {
+  IFrameWindowProxy
+};

package/lib/esm/index.js

@@ -0,0 +1,18 @@
+import { HTMLIFrameElement } from "./html-iframe-element.js";
+import { IFrameWidget } from "./iframe-widget.js";
+import { IFrameWindowProxy } from "./iframe-window-proxy.js";
+import { MessageBridge } from "./message-bridge.js";
+import { Document } from "@gjsify/dom-elements";
+import { HTMLIFrameElement as HTMLIFrameElement2 } from "./html-iframe-element.js";
+Document.registerElementFactory("iframe", () => new HTMLIFrameElement2());
+Object.defineProperty(globalThis, "HTMLIFrameElement", {
+  value: HTMLIFrameElement2,
+  writable: true,
+  configurable: true
+});
+export {
+  HTMLIFrameElement,
+  IFrameWidget,
+  IFrameWindowProxy,
+  MessageBridge
+};

package/lib/esm/message-bridge.js

@@ -0,0 +1,129 @@
+import Gio from "gi://Gio?version=2.0";
+import WebKit from "gi://WebKit?version=6.0";
+import { MessageEvent } from "@gjsify/dom-events";
+Gio._promisify(WebKit.WebView.prototype, "evaluate_javascript", "evaluate_javascript_finish");
+const CHANNEL_NAME = "gjsify-iframe";
+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] \u2014 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 };
+})();`;
+class MessageBridge {
+  constructor(webView) {
+    this._windowProxy = null;
+    this._currentUri = "about:blank";
+    this._signalId = null;
+    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) {
+    this._windowProxy = proxy;
+  }
+  /** Update current URI (called by IFrameWidget on load-changed) */
+  updateUri(uri) {
+    this._currentUri = uri;
+  }
+  /** Get current location info for the IFrameWindowProxy */
+  getLocation() {
+    let origin;
+    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, _targetOrigin) {
+    const serialized = JSON.stringify(data);
+    const origin = JSON.stringify("gjsify");
+    const script = `window.dispatchEvent(new MessageEvent('message', { data: JSON.parse(${JSON.stringify(serialized)}), origin: ${origin} }));`;
+    this._webView.evaluate_javascript(
+      script,
+      -1,
+      // length (-1 = null-terminated)
+      null,
+      // world name (null = default)
+      null,
+      // source URI
+      null
+      // cancellable
+    ).catch(() => {
+    });
+  }
+  /** Clean up signal handlers */
+  destroy() {
+    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.
+   */
+  _setupReceiver() {
+    this._userContentManager.register_script_message_handler(CHANNEL_NAME, null);
+    this._signalId = this._userContentManager.connect(
+      `script-message-received::${CHANNEL_NAME}`,
+      (_ucm, jsValue) => {
+        if (!this._windowProxy) return;
+        try {
+          const json = jsValue.to_string();
+          const envelope = JSON.parse(json);
+          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.
+   */
+  _injectBootstrapScript() {
+    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);
+  }
+}
+export {
+  MessageBridge
+};

package/lib/esm/property-symbol.js

@@ -0,0 +1,8 @@
+const iframeWidget = /* @__PURE__ */ Symbol("iframeWidget");
+const windowProxy = /* @__PURE__ */ Symbol("windowProxy");
+const loaded = /* @__PURE__ */ Symbol("loaded");
+export {
+  iframeWidget,
+  loaded,
+  windowProxy
+};

package/lib/types/html-iframe-element.d.ts

@@ -0,0 +1,59 @@
+import { HTMLElement } from '@gjsify/dom-elements';
+import * as PS from './property-symbol.js';
+import type { IFrameWindowProxy } from './iframe-window-proxy.js';
+/**
+ * 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 declare class HTMLIFrameElement extends HTMLElement {
+    /** @internal The backing IFrameWidget (set by IFrameWidget when it creates this element) */
+    [PS.iframeWidget]: import('./iframe-widget.js').IFrameWidget | null;
+    /** @internal The contentWindow proxy */
+    [PS.windowProxy]: IFrameWindowProxy | null;
+    /** @internal Whether content has been loaded */
+    [PS.loaded]: boolean;
+    constructor();
+    get src(): string;
+    set src(value: string);
+    get srcdoc(): string;
+    set srcdoc(value: string);
+    get name(): string;
+    set name(value: string);
+    get sandbox(): string;
+    set sandbox(value: string);
+    get allow(): string;
+    set allow(value: string);
+    get referrerPolicy(): string;
+    set referrerPolicy(value: string);
+    get loading(): string;
+    set loading(value: string);
+    get width(): string;
+    set width(value: string);
+    get height(): string;
+    set height(value: string);
+    /**
+     * Returns the window proxy for the iframe's content.
+     * Available after the IFrameWidget has loaded content.
+     */
+    get contentWindow(): IFrameWindowProxy | null;
+    /**
+     * 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;
+    /**
+     * Returns a promise that resolves to the iframe's src URL.
+     */
+    getSVGDocument(): null;
+    cloneNode(deep?: boolean): HTMLIFrameElement;
+    get [Symbol.toStringTag](): string;
+    /** @internal Fire load event */
+    _onLoad(): void;
+    /** @internal Fire error event */
+    _onError(): void;
+}