@gjsify/iframe 0.36.0 → 0.38.0

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

@@ -2,21 +2,17 @@ import { MessagePort, MessageChannel } from '@gjsify/message-channel';
 import type { MessagePortTransport } from '@gjsify/message-channel';
 import type { MessageBridge } from './message-bridge.js';
 export { MessagePort, MessageChannel };
-/** @deprecated Re-exported alias of `MessagePort` from
- *  `@gjsify/message-channel`. Use the standard name. */
+/** @deprecated Alias of `MessagePort`; use the standard name. */
 export declare const IFrameMessagePort: typeof MessagePort;
 export type IFrameMessagePort = MessagePort;
-/** @deprecated Re-exported alias of `MessageChannel` from
- *  `@gjsify/message-channel`. Use the standard name. */
+/** @deprecated Alias of `MessageChannel`; use the standard name. */
 export declare const IFrameMessageChannel: typeof MessageChannel;
 export type IFrameMessageChannel = MessageChannel;
 /**
- * MessagePortTransport adapter that routes a port's outbound messages
- * through a `MessageBridge` instance. Used internally by the bridge
- * when it picks up `MessagePort` instances from a `postMessage`
- * transferList — the transferred port's partner is attached to a
- * `BridgePortTransport` so its `.postMessage` flows over the WebKit
- * IPC instead of the in-process partner (which has been detached).
+ * Routes a port's outbound messages through a `MessageBridge`. The bridge attaches one to
+ * the PARTNER of every `MessagePort` it takes out of a `postMessage` transferList, so
+ * that partner's `.postMessage` flows over the WebKit IPC instead of to the now-detached
+ * in-process port.
  *
  * @internal
  */

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

@@ -2,57 +2,36 @@ import { EventTarget } from '@gjsify/dom-events';
 import type { MessageBridge } from './message-bridge.js';
 import type { MessagePort } from '@gjsify/message-channel';
 /**
- * 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.
+ * Deliberately NOT a full BrowserWindow: only the subset of the Window API that
+ * postMessage-based iframe communication needs.
  */
 export declare class IFrameWindowProxy extends EventTarget {
     private _bridge;
     private _closed;
     constructor(bridge: MessageBridge);
     /**
-     * Send a message to the iframe content.
+     * Send a message to the iframe content. `message` must be JSON-serialisable, plus the
+     * binary types `@gjsify/iframe/serialize` can base64-encode.
      *
-     * @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 `MessagePort` 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`.
+     * Each port in `transfer` is detached locally and its surviving partner becomes the
+     * GJS-side endpoint of a bidirectional channel routed through the bridge; the WebView
+     * receives proxy ports wherever the originals appeared in `message`.
      */
     postMessage(message: unknown, targetOrigin?: string, transfer?: MessagePort[]): void;
-    /**
-     * Read-only location reflecting the current WebView URI.
-     */
+    /** 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.
-     */
+    /** The host window — `globalThis` on GJS. */
     get parent(): typeof globalThis;
-    /**
-     * Reference to the top-level window — in GJS this is globalThis.
-     */
+    /** The top-level window — `globalThis` on GJS. */
     get top(): typeof globalThis;
-    /**
-     * The window itself (self-reference per spec).
-     */
+    /** Self-reference, per spec. */
     get self(): IFrameWindowProxy;
     get window(): IFrameWindowProxy;
     get closed(): boolean;
-    /** @internal Mark as closed when the WebView is destroyed */
+    /** @internal Called when the WebView is destroyed. */
     _close(): void;
     get [Symbol.toStringTag](): string;
 }

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

@@ -5,60 +5,38 @@ import type { ConsoleCallback, ConsoleLogEntry } from './types/index.js';
 import type { MessagePort } from '@gjsify/message-channel';
 /** Options for {@link MessageBridge}. */
 export interface MessageBridgeOptions {
-    /** Inject the console-capture UserScript so the page's console.* is
-     *  forwarded to the host. Default: false. */
+    /** Forward the page's `console.*` to the host via a UserScript. Default: false. */
     captureConsole?: boolean;
 }
 /**
- * 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).
+ * Synthetic origin on messages travelling FROM the GJS host INTO the WebView, so page
+ * code can filter on it and accept only what its hosting process sent.
  *
- * 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.
+ * `https://` because WHATWG URL parsing yields `null` as the origin of a non-special
+ * scheme like `gjsify://`, which would break the equality comparison the bridge does on
+ * every message. `.local` is RFC 6762's non-routable suffix, so it cannot 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.
+ * `targetOrigin` per the HTML spec for window.postMessage: `'*'` is unrestricted, a URL
+ * must match the destination origin, `'/'` means "the source's own origin" (returned as
+ * `null`), and anything else is a `SyntaxError`.
  */
 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.
+ * @internal Exposed only so a unit test can check that the bootstrap script's
+ * idempotency guard survives a refactor. Not public API.
  */
 export declare const BOOTSTRAP_SCRIPT_FOR_TEST: () => string;
 /**
- * Manages bidirectional postMessage communication between GJS and a WebKit.WebView.
+ * Bidirectional postMessage 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.
+ * GJS → WebView goes through `evaluate_javascript()`, which dispatches a MessageEvent on
+ * the WebView's window. WebView → GJS goes through the bootstrap script's
+ * `window.parent.postMessage` override, which calls
+ * `webkit.messageHandlers[CHANNEL_NAME].postMessage()` and raises the
+ * UserContentManager 'script-message-received' signal.
  */
 export declare class MessageBridge {
     private _webView;
@@ -66,9 +44,8 @@ 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)`. */
+    /** GJS-side endpoints of transferred ports, keyed by per-bridge id: a
+     *  `{__gjsifyPortMessage: id, payload}` envelope routes to `_receive(decoded)`. */
     private _ports;
     private _nextPortId;
     private _transport;
@@ -77,8 +54,7 @@ export declare class MessageBridge {
     private _consoleBuffer;
     private _consoleCallbacks;
     constructor(webView: WebKit.WebView, options?: MessageBridgeOptions);
-    /** Buffered console entries captured from the page (oldest first). Empty
-     *  unless the bridge was created with `captureConsole`. */
+    /** Console entries from the page, oldest first; empty without `captureConsole`. */
     getConsoleLogs(): ConsoleLogEntry[];
     /** Drop all buffered console entries. */
     clearConsoleLogs(): void;
@@ -86,29 +62,25 @@ export declare class MessageBridge {
     onConsole(cb: ConsoleCallback): void;
     /** @internal Record a parsed console entry + fan out to subscribers. */
     private _recordConsole;
-    /** Connect the IFrameWindowProxy that will receive messages from the WebView */
+    /** Connect the IFrameWindowProxy that receives messages from the WebView. */
     setWindowProxy(proxy: IFrameWindowProxy): void;
-    /** Update current URI (called by IFrameBridge on load-changed) */
+    /** Called by IFrameBridge on load-changed. */
     updateUri(uri: string): void;
-    /** Get current location info for the IFrameWindowProxy */
+    /** 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.
-     */
+    /** Dispatches a standard MessageEvent on the WebView's window object. */
     /**
      * Register a port pair for cross-bridge transfer. Called by
      * IFrameWindowProxy.postMessage when it sees a `MessagePort` 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 with a `BridgePortTransport` so the partner's
-     * postMessage routes back over the WebKit bridge instead of the
-     * (now-null) in-process partner.
+     * The transferred port is detached locally and its surviving partner gets a
+     * `BridgePortTransport`, so the partner's postMessage routes over the WebKit bridge
+     * instead of the now-null in-process partner.
      */
     _registerTransferredPort(port: MessagePort): number;
     /** @internal Called by MessagePort.postMessage when its partner

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/iframe",
-    "version": "0.36.0",
+    "version": "0.38.0",
     "description": "HTMLIFrameElement for GJS, backed by WebKit.WebView",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -46,14 +46,14 @@
         "@girs/gtk-4.0": "^4.1.0",
         "@girs/javascriptcore-6.0": "^4.1.0",
         "@girs/webkit-6.0": "^4.1.0",
-        "@gjsify/dom-elements": "^0.36.0",
-        "@gjsify/dom-events": "^0.36.0",
-        "@gjsify/message-channel": "^0.36.0",
-        "@gjsify/webkit-native": "^0.36.0"
+        "@gjsify/dom-elements": "^0.38.0",
+        "@gjsify/dom-events": "^0.38.0",
+        "@gjsify/message-channel": "^0.38.0",
+        "@gjsify/webkit-native": "^0.38.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.38.0",
+        "@gjsify/unit": "^0.38.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },