@gjsify/iframe 0.35.0 → 0.37.0

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

@@ -6,30 +6,20 @@ import { HTMLIFrameElement } from './html-iframe-element.js';
 import { MessageBridge } from './message-bridge.js';
 import './promisify.js';
 import type { ConsoleCallback, ConsoleLogEntry, IFrameBridgeOptions, IFrameReadyCallback, LoadErrorCallback, LoadErrorInfo } from './types/index.js';
-/** A pending {@link IFrameBridge.waitForNavigation} promise. `sourceId` is the
- *  GLib timeout source backing its deadline (null when no timeout). */
+/** A pending {@link IFrameBridge.waitForNavigation}; `sourceId` backs its deadline. */
 interface NavigationWaiter {
     resolve: () => void;
     reject: (error: Error) => void;
     sourceId: number | null;
 }
 /**
- * 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`
+ * A `WebKit.WebView` subclass that wraps itself in an `HTMLIFrameElement` and bridges
+ * postMessage between GJS and the page.
  *
- * Usage:
  * ```ts
  * const iframeWidget = new IFrameBridge();
  * iframeWidget.installGlobals();
- * iframeWidget.onReady((iframe) => {
- *     iframe.contentWindow?.addEventListener('message', (e) => {
- *         console.log('Message from iframe:', e.data);
- *     });
- * });
+ * iframeWidget.onReady((iframe) => { … });
  * iframeWidget.iframeElement.src = 'https://example.com';
  * window.set_child(iframeWidget);
  * ```
@@ -46,107 +36,74 @@ export declare const IFrameBridge: {
         _lastLoadError: LoadErrorInfo | null;
         _loadErrorCallbacks: LoadErrorCallback[];
         /**
-         * GTK4 allocation hook — surfaces WebKit.WebView size changes to any
-         * ResizeObserver watching the paired HTMLIFrameElement (or an ancestor;
-         * see notifyElementResize). GTK4 has no `resize` signal on Gtk.Widget
-         * (only Gtk.DrawingArea/GLArea), so the allocation vfunc is the portable
-         * way to observe the widget's size.
+         * Surfaces size changes to any ResizeObserver watching the paired
+         * HTMLIFrameElement or an ancestor. GTK4 has no `resize` signal on Gtk.Widget
+         * (only Gtk.DrawingArea/GLArea), so this vfunc is the portable way to see them.
          */
         vfunc_size_allocate(width: number, height: number, baseline: number): void;
         /** The HTMLIFrameElement wrapping this WebView. */
         get iframeElement(): HTMLIFrameElement;
-        /**
-         * Register a callback to be invoked when content has loaded.
-         * If content is already loaded, the callback fires on next load.
-         */
+        /** Runs `cb` when content has loaded — on the NEXT load if it already has. */
         onReady(cb: IFrameReadyCallback): void;
-        /**
-         * Load a URI into the WebView.
-         * Also updates the iframe element's src attribute.
-         */
+        /** Load a URI, keeping the iframe element's `src` attribute in step. */
         loadUri(uri: string): void;
-        /**
-         * Load inline HTML into the WebView.
-         * Also updates the iframe element's srcdoc attribute.
-         */
+        /** Load inline HTML, keeping the iframe element's `srcdoc` attribute in step. */
         loadHtml(html: string, baseUri?: string): void;
-        /**
-         * Send a message to the WebView content via the standard postMessage API.
-         * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
-         */
+        /** Equivalent to `iframeElement.contentWindow.postMessage(message, targetOrigin)`. */
         postMessage(message: unknown, targetOrigin?: string): void;
         /**
-         * Navigate the embedded WebView back one entry in its internal
-         * history list. No-op when `canGoBack` is false.
+         * Back one entry in WEBKIT's own history list, independent of any
+         * application-level history. No-op when `canGoBack` is false.
          *
-         * Note: reflects WebKit's own navigation history (independent of
-         * any application-level history the embedder maintains). The
-         * browser `<iframe>` element has no equivalent — cross-origin
-         * iframes cannot be navigated programmatically by the parent. For
-         * cross-variant (browser + GJS) parity, embedders typically track
-         * URLs themselves and call `loadUri(url)`; the methods here exist
-         * for apps that DO want to expose the WebKit-internal back/forward
-         * list directly (e.g. a "WebView with browser-like UX").
+         * The browser `<iframe>` has no equivalent (a parent cannot navigate a
+         * cross-origin iframe), so cross-variant parity means tracking URLs yourself and
+         * calling `loadUri(url)`.
          */
         goBack(): void;
-        /** Navigate forward in the WebView's internal history. No-op when
-         *  `canGoForward` is false. See `goBack()` for caveats. */
+        /** Forward one entry. No-op when `canGoForward` is false; caveats as `goBack()`. */
         goForward(): void;
-        /** True when the WebView has prior entries in its internal history.
-         *  Reflects WebKit's `can-go-back` state, NOT any application-level
-         *  history stack. */
+        /** WebKit's `can-go-back`, NOT any application-level history stack. */
         get canGoBack(): boolean;
-        /** True when the WebView has forward entries in its internal history.
-         *  Reflects WebKit's `can-go-forward` state. */
+        /** WebKit's `can-go-forward`. */
         get canGoForward(): boolean;
-        /** WebKit's ground-truth current URI (`about:blank` before any load).
-         *  Distinct from any application-side history the embedder maintains. */
+        /** WebKit's ground-truth current URI; `about:blank` before any load. */
         get currentUri(): string;
-        /** The loaded document's title (empty string before it is known).
-         *  Reflects WebKit's tracked `<title>`. */
+        /** WebKit's tracked `<title>`; empty before it is known. */
         get pageTitle(): string;
-        /** Detail of the most recent failed load, or null when the current
-         *  page loaded without a main-resource failure. */
+        /** The most recent failed load, or null when the current page had no failure. */
         get lastLoadError(): LoadErrorInfo | null;
         /** Subscribe to load failures (network / main-resource errors). */
         onLoadError(cb: LoadErrorCallback): void;
         /**
          * Evaluate a JavaScript *expression* in the page and return its value.
          *
-         * The value is serialised to JSON in-page and parsed on the GJS host,
-         * so objects/arrays/strings/numbers/booleans/null round-trip. A value
-         * that is not JSON-serialisable (DOM node, function, circular object)
-         * comes back as `undefined`. A thrown page error rejects the promise.
+         * The value round-trips through JSON, so anything not JSON-serialisable (DOM
+         * node, function, circular object) comes back as `undefined`; a thrown page error
+         * rejects the promise.
          *
-         * Pass an expression, not statements — wrap multi-statement logic in an
-         * IIFE that returns a value, e.g.
-         * `evaluateJavaScript('(() => { const a = 1; return a + 1; })()')`.
-         * This mirrors Playwright/Puppeteer `page.evaluate` ergonomics.
+         * An EXPRESSION, not statements: wrap multi-statement logic in an IIFE that
+         * returns a value, as `page.evaluate` requires.
          */
         evaluateJavaScript(expression: string): Promise<unknown>;
         /**
          * Capture the rendered web content as PNG bytes.
          *
-         * `'full'` (default) snapshots the whole scrollable document; `'visible'`
-         * snapshots only the current viewport. This goes through WebKit's own
-         * `get_snapshot` — NOT a GSK widget snapshot — because WebKit composites
-         * its content in a separate process, so a GTK-tree snapshot of the
+         * `'full'` (default) takes the whole scrollable document, `'visible'` the current
+         * viewport. Through WebKit's own `get_snapshot` and NOT a GSK widget snapshot,
+         * because WebKit composites in a separate process, so a GTK-tree snapshot of the
          * WebView can come back blank or stale.
          */
         takeScreenshot(region?: "full" | "visible"): Promise<Uint8Array>;
         /**
          * Resolve on the next load that finishes (`LoadEvent.FINISHED`).
          *
-         * `onReady()` fires only once and is drained per load, so a
-         * page-initiated navigation (link click, JS redirect, form submit,
-         * meta-refresh) never re-triggers it. Register a `waitForNavigation()`
-         * *before* triggering such a navigation. Rejects on a main-resource
-         * load failure, or after `timeoutMs` (0 disables the timeout).
+         * `onReady()` is drained per load, so a page-initiated navigation (link click, JS
+         * redirect, form submit, meta-refresh) never re-triggers it — register this
+         * BEFORE triggering one. Rejects on a main-resource failure, or after `timeoutMs`
+         * (0 disables the timeout).
          */
         waitForNavigation(timeoutMs?: number): Promise<void>;
-        /** Settle (and clear) every pending waitForNavigation() promise,
-         *  removing its timeout source. Resolves them on success; rejects with
-         *  `error` on a load failure. */
+        /** Settle and clear every pending waitForNavigation(), removing its timeout. */
         _settleNavigationWaiters(error: Error | null): void;
         /** Current size of the WebView content region, in widget pixels. */
         getViewportSize(): {
@@ -154,18 +111,16 @@ export declare const IFrameBridge: {
             height: number;
         };
         /**
-         * Request a content-region size (e.g. for responsive testing). This sets
-         * the widget's size request; the actual allocation still depends on the
-         * parent layout, and `getViewportSize()` reflects the realised size.
+         * Request a content-region size, e.g. for responsive testing. Only a size REQUEST:
+         * the allocation still depends on the parent layout, and `getViewportSize()`
+         * reports what was realised.
          */
         setViewportSize(width: number, height: number): void;
-        /** Buffered page `console.*` output. Empty unless the bridge was created
-         *  with `{ captureConsole: true }`. */
+        /** Buffered page `console.*` output; empty without `{ captureConsole: true }`. */
         getConsoleLogs(): ConsoleLogEntry[];
         /** Drop all buffered console entries. */
         clearConsoleLogs(): void;
-        /** Subscribe to captured console entries as they arrive. Requires
-         *  `{ captureConsole: true }` to receive anything. */
+        /** Console entries as they arrive; needs `{ captureConsole: true }`. */
         onConsole(cb: ConsoleCallback): void;
         /** Every `<a href>` on the page (resolved href, trimmed text, title). */
         getLinks(): Promise<LinkInfo[]>;
@@ -763,107 +718,74 @@ export declare const IFrameBridge: {
             _lastLoadError: LoadErrorInfo | null;
             _loadErrorCallbacks: LoadErrorCallback[];
             /**
-             * GTK4 allocation hook — surfaces WebKit.WebView size changes to any
-             * ResizeObserver watching the paired HTMLIFrameElement (or an ancestor;
-             * see notifyElementResize). GTK4 has no `resize` signal on Gtk.Widget
-             * (only Gtk.DrawingArea/GLArea), so the allocation vfunc is the portable
-             * way to observe the widget's size.
+             * Surfaces size changes to any ResizeObserver watching the paired
+             * HTMLIFrameElement or an ancestor. GTK4 has no `resize` signal on Gtk.Widget
+             * (only Gtk.DrawingArea/GLArea), so this vfunc is the portable way to see them.
              */
             vfunc_size_allocate(width: number, height: number, baseline: number): void;
             /** The HTMLIFrameElement wrapping this WebView. */
             get iframeElement(): HTMLIFrameElement;
-            /**
-             * Register a callback to be invoked when content has loaded.
-             * If content is already loaded, the callback fires on next load.
-             */
+            /** Runs `cb` when content has loaded — on the NEXT load if it already has. */
             onReady(cb: IFrameReadyCallback): void;
-            /**
-             * Load a URI into the WebView.
-             * Also updates the iframe element's src attribute.
-             */
+            /** Load a URI, keeping the iframe element's `src` attribute in step. */
             loadUri(uri: string): void;
-            /**
-             * Load inline HTML into the WebView.
-             * Also updates the iframe element's srcdoc attribute.
-             */
+            /** Load inline HTML, keeping the iframe element's `srcdoc` attribute in step. */
             loadHtml(html: string, baseUri?: string): void;
-            /**
-             * Send a message to the WebView content via the standard postMessage API.
-             * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
-             */
+            /** Equivalent to `iframeElement.contentWindow.postMessage(message, targetOrigin)`. */
             postMessage(message: unknown, targetOrigin?: string): void;
             /**
-             * Navigate the embedded WebView back one entry in its internal
-             * history list. No-op when `canGoBack` is false.
+             * Back one entry in WEBKIT's own history list, independent of any
+             * application-level history. No-op when `canGoBack` is false.
              *
-             * Note: reflects WebKit's own navigation history (independent of
-             * any application-level history the embedder maintains). The
-             * browser `<iframe>` element has no equivalent — cross-origin
-             * iframes cannot be navigated programmatically by the parent. For
-             * cross-variant (browser + GJS) parity, embedders typically track
-             * URLs themselves and call `loadUri(url)`; the methods here exist
-             * for apps that DO want to expose the WebKit-internal back/forward
-             * list directly (e.g. a "WebView with browser-like UX").
+             * The browser `<iframe>` has no equivalent (a parent cannot navigate a
+             * cross-origin iframe), so cross-variant parity means tracking URLs yourself and
+             * calling `loadUri(url)`.
              */
             goBack(): void;
-            /** Navigate forward in the WebView's internal history. No-op when
-             *  `canGoForward` is false. See `goBack()` for caveats. */
+            /** Forward one entry. No-op when `canGoForward` is false; caveats as `goBack()`. */
             goForward(): void;
-            /** True when the WebView has prior entries in its internal history.
-             *  Reflects WebKit's `can-go-back` state, NOT any application-level
-             *  history stack. */
+            /** WebKit's `can-go-back`, NOT any application-level history stack. */
             get canGoBack(): boolean;
-            /** True when the WebView has forward entries in its internal history.
-             *  Reflects WebKit's `can-go-forward` state. */
+            /** WebKit's `can-go-forward`. */
             get canGoForward(): boolean;
-            /** WebKit's ground-truth current URI (`about:blank` before any load).
-             *  Distinct from any application-side history the embedder maintains. */
+            /** WebKit's ground-truth current URI; `about:blank` before any load. */
             get currentUri(): string;
-            /** The loaded document's title (empty string before it is known).
-             *  Reflects WebKit's tracked `<title>`. */
+            /** WebKit's tracked `<title>`; empty before it is known. */
             get pageTitle(): string;
-            /** Detail of the most recent failed load, or null when the current
-             *  page loaded without a main-resource failure. */
+            /** The most recent failed load, or null when the current page had no failure. */
             get lastLoadError(): LoadErrorInfo | null;
             /** Subscribe to load failures (network / main-resource errors). */
             onLoadError(cb: LoadErrorCallback): void;
             /**
              * Evaluate a JavaScript *expression* in the page and return its value.
              *
-             * The value is serialised to JSON in-page and parsed on the GJS host,
-             * so objects/arrays/strings/numbers/booleans/null round-trip. A value
-             * that is not JSON-serialisable (DOM node, function, circular object)
-             * comes back as `undefined`. A thrown page error rejects the promise.
+             * The value round-trips through JSON, so anything not JSON-serialisable (DOM
+             * node, function, circular object) comes back as `undefined`; a thrown page error
+             * rejects the promise.
              *
-             * Pass an expression, not statements — wrap multi-statement logic in an
-             * IIFE that returns a value, e.g.
-             * `evaluateJavaScript('(() => { const a = 1; return a + 1; })()')`.
-             * This mirrors Playwright/Puppeteer `page.evaluate` ergonomics.
+             * An EXPRESSION, not statements: wrap multi-statement logic in an IIFE that
+             * returns a value, as `page.evaluate` requires.
              */
             evaluateJavaScript(expression: string): Promise<unknown>;
             /**
              * Capture the rendered web content as PNG bytes.
              *
-             * `'full'` (default) snapshots the whole scrollable document; `'visible'`
-             * snapshots only the current viewport. This goes through WebKit's own
-             * `get_snapshot` — NOT a GSK widget snapshot — because WebKit composites
-             * its content in a separate process, so a GTK-tree snapshot of the
+             * `'full'` (default) takes the whole scrollable document, `'visible'` the current
+             * viewport. Through WebKit's own `get_snapshot` and NOT a GSK widget snapshot,
+             * because WebKit composites in a separate process, so a GTK-tree snapshot of the
              * WebView can come back blank or stale.
              */
             takeScreenshot(region?: "full" | "visible"): Promise<Uint8Array>;
             /**
              * Resolve on the next load that finishes (`LoadEvent.FINISHED`).
              *
-             * `onReady()` fires only once and is drained per load, so a
-             * page-initiated navigation (link click, JS redirect, form submit,
-             * meta-refresh) never re-triggers it. Register a `waitForNavigation()`
-             * *before* triggering such a navigation. Rejects on a main-resource
-             * load failure, or after `timeoutMs` (0 disables the timeout).
+             * `onReady()` is drained per load, so a page-initiated navigation (link click, JS
+             * redirect, form submit, meta-refresh) never re-triggers it — register this
+             * BEFORE triggering one. Rejects on a main-resource failure, or after `timeoutMs`
+             * (0 disables the timeout).
              */
             waitForNavigation(timeoutMs?: number): Promise<void>;
-            /** Settle (and clear) every pending waitForNavigation() promise,
-             *  removing its timeout source. Resolves them on success; rejects with
-             *  `error` on a load failure. */
+            /** Settle and clear every pending waitForNavigation(), removing its timeout. */
             _settleNavigationWaiters(error: Error | null): void;
             /** Current size of the WebView content region, in widget pixels. */
             getViewportSize(): {
@@ -871,18 +793,16 @@ export declare const IFrameBridge: {
                 height: number;
             };
             /**
-             * Request a content-region size (e.g. for responsive testing). This sets
-             * the widget's size request; the actual allocation still depends on the
-             * parent layout, and `getViewportSize()` reflects the realised size.
+             * Request a content-region size, e.g. for responsive testing. Only a size REQUEST:
+             * the allocation still depends on the parent layout, and `getViewportSize()`
+             * reports what was realised.
              */
             setViewportSize(width: number, height: number): void;
-            /** Buffered page `console.*` output. Empty unless the bridge was created
-             *  with `{ captureConsole: true }`. */
+            /** Buffered page `console.*` output; empty without `{ captureConsole: true }`. */
             getConsoleLogs(): ConsoleLogEntry[];
             /** Drop all buffered console entries. */
             clearConsoleLogs(): void;
-            /** Subscribe to captured console entries as they arrive. Requires
-             *  `{ captureConsole: true }` to receive anything. */
+            /** Console entries as they arrive; needs `{ captureConsole: true }`. */
             onConsole(cb: ConsoleCallback): void;
             /** Every `<a href>` on the page (resolved href, trimmed text, title). */
             getLinks(): Promise<LinkInfo[]>;
@@ -1480,107 +1400,74 @@ export declare const IFrameBridge: {
                 _lastLoadError: LoadErrorInfo | null;
                 _loadErrorCallbacks: LoadErrorCallback[];
                 /**
-                 * GTK4 allocation hook — surfaces WebKit.WebView size changes to any
-                 * ResizeObserver watching the paired HTMLIFrameElement (or an ancestor;
-                 * see notifyElementResize). GTK4 has no `resize` signal on Gtk.Widget
-                 * (only Gtk.DrawingArea/GLArea), so the allocation vfunc is the portable
-                 * way to observe the widget's size.
+                 * Surfaces size changes to any ResizeObserver watching the paired
+                 * HTMLIFrameElement or an ancestor. GTK4 has no `resize` signal on Gtk.Widget
+                 * (only Gtk.DrawingArea/GLArea), so this vfunc is the portable way to see them.
                  */
                 vfunc_size_allocate(width: number, height: number, baseline: number): void;
                 /** The HTMLIFrameElement wrapping this WebView. */
                 get iframeElement(): HTMLIFrameElement;
-                /**
-                 * Register a callback to be invoked when content has loaded.
-                 * If content is already loaded, the callback fires on next load.
-                 */
+                /** Runs `cb` when content has loaded — on the NEXT load if it already has. */
                 onReady(cb: IFrameReadyCallback): void;
-                /**
-                 * Load a URI into the WebView.
-                 * Also updates the iframe element's src attribute.
-                 */
+                /** Load a URI, keeping the iframe element's `src` attribute in step. */
                 loadUri(uri: string): void;
-                /**
-                 * Load inline HTML into the WebView.
-                 * Also updates the iframe element's srcdoc attribute.
-                 */
+                /** Load inline HTML, keeping the iframe element's `srcdoc` attribute in step. */
                 loadHtml(html: string, baseUri?: string): void;
-                /**
-                 * Send a message to the WebView content via the standard postMessage API.
-                 * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
-                 */
+                /** Equivalent to `iframeElement.contentWindow.postMessage(message, targetOrigin)`. */
                 postMessage(message: unknown, targetOrigin?: string): void;
                 /**
-                 * Navigate the embedded WebView back one entry in its internal
-                 * history list. No-op when `canGoBack` is false.
+                 * Back one entry in WEBKIT's own history list, independent of any
+                 * application-level history. No-op when `canGoBack` is false.
                  *
-                 * Note: reflects WebKit's own navigation history (independent of
-                 * any application-level history the embedder maintains). The
-                 * browser `<iframe>` element has no equivalent — cross-origin
-                 * iframes cannot be navigated programmatically by the parent. For
-                 * cross-variant (browser + GJS) parity, embedders typically track
-                 * URLs themselves and call `loadUri(url)`; the methods here exist
-                 * for apps that DO want to expose the WebKit-internal back/forward
-                 * list directly (e.g. a "WebView with browser-like UX").
+                 * The browser `<iframe>` has no equivalent (a parent cannot navigate a
+                 * cross-origin iframe), so cross-variant parity means tracking URLs yourself and
+                 * calling `loadUri(url)`.
                  */
                 goBack(): void;
-                /** Navigate forward in the WebView's internal history. No-op when
-                 *  `canGoForward` is false. See `goBack()` for caveats. */
+                /** Forward one entry. No-op when `canGoForward` is false; caveats as `goBack()`. */
                 goForward(): void;
-                /** True when the WebView has prior entries in its internal history.
-                 *  Reflects WebKit's `can-go-back` state, NOT any application-level
-                 *  history stack. */
+                /** WebKit's `can-go-back`, NOT any application-level history stack. */
                 get canGoBack(): boolean;
-                /** True when the WebView has forward entries in its internal history.
-                 *  Reflects WebKit's `can-go-forward` state. */
+                /** WebKit's `can-go-forward`. */
                 get canGoForward(): boolean;
-                /** WebKit's ground-truth current URI (`about:blank` before any load).
-                 *  Distinct from any application-side history the embedder maintains. */
+                /** WebKit's ground-truth current URI; `about:blank` before any load. */
                 get currentUri(): string;
-                /** The loaded document's title (empty string before it is known).
-                 *  Reflects WebKit's tracked `<title>`. */
+                /** WebKit's tracked `<title>`; empty before it is known. */
                 get pageTitle(): string;
-                /** Detail of the most recent failed load, or null when the current
-                 *  page loaded without a main-resource failure. */
+                /** The most recent failed load, or null when the current page had no failure. */
                 get lastLoadError(): LoadErrorInfo | null;
                 /** Subscribe to load failures (network / main-resource errors). */
                 onLoadError(cb: LoadErrorCallback): void;
                 /**
                  * Evaluate a JavaScript *expression* in the page and return its value.
                  *
-                 * The value is serialised to JSON in-page and parsed on the GJS host,
-                 * so objects/arrays/strings/numbers/booleans/null round-trip. A value
-                 * that is not JSON-serialisable (DOM node, function, circular object)
-                 * comes back as `undefined`. A thrown page error rejects the promise.
+                 * The value round-trips through JSON, so anything not JSON-serialisable (DOM
+                 * node, function, circular object) comes back as `undefined`; a thrown page error
+                 * rejects the promise.
                  *
-                 * Pass an expression, not statements — wrap multi-statement logic in an
-                 * IIFE that returns a value, e.g.
-                 * `evaluateJavaScript('(() => { const a = 1; return a + 1; })()')`.
-                 * This mirrors Playwright/Puppeteer `page.evaluate` ergonomics.
+                 * An EXPRESSION, not statements: wrap multi-statement logic in an IIFE that
+                 * returns a value, as `page.evaluate` requires.
                  */
                 evaluateJavaScript(expression: string): Promise<unknown>;
                 /**
                  * Capture the rendered web content as PNG bytes.
                  *
-                 * `'full'` (default) snapshots the whole scrollable document; `'visible'`
-                 * snapshots only the current viewport. This goes through WebKit's own
-                 * `get_snapshot` — NOT a GSK widget snapshot — because WebKit composites
-                 * its content in a separate process, so a GTK-tree snapshot of the
+                 * `'full'` (default) takes the whole scrollable document, `'visible'` the current
+                 * viewport. Through WebKit's own `get_snapshot` and NOT a GSK widget snapshot,
+                 * because WebKit composites in a separate process, so a GTK-tree snapshot of the
                  * WebView can come back blank or stale.
                  */
                 takeScreenshot(region?: "full" | "visible"): Promise<Uint8Array>;
                 /**
                  * Resolve on the next load that finishes (`LoadEvent.FINISHED`).
                  *
-                 * `onReady()` fires only once and is drained per load, so a
-                 * page-initiated navigation (link click, JS redirect, form submit,
-                 * meta-refresh) never re-triggers it. Register a `waitForNavigation()`
-                 * *before* triggering such a navigation. Rejects on a main-resource
-                 * load failure, or after `timeoutMs` (0 disables the timeout).
+                 * `onReady()` is drained per load, so a page-initiated navigation (link click, JS
+                 * redirect, form submit, meta-refresh) never re-triggers it — register this
+                 * BEFORE triggering one. Rejects on a main-resource failure, or after `timeoutMs`
+                 * (0 disables the timeout).
                  */
                 waitForNavigation(timeoutMs?: number): Promise<void>;
-                /** Settle (and clear) every pending waitForNavigation() promise,
-                 *  removing its timeout source. Resolves them on success; rejects with
-                 *  `error` on a load failure. */
+                /** Settle and clear every pending waitForNavigation(), removing its timeout. */
                 _settleNavigationWaiters(error: Error | null): void;
                 /** Current size of the WebView content region, in widget pixels. */
                 getViewportSize(): {
@@ -1588,18 +1475,16 @@ export declare const IFrameBridge: {
                     height: number;
                 };
                 /**
-                 * Request a content-region size (e.g. for responsive testing). This sets
-                 * the widget's size request; the actual allocation still depends on the
-                 * parent layout, and `getViewportSize()` reflects the realised size.
+                 * Request a content-region size, e.g. for responsive testing. Only a size REQUEST:
+                 * the allocation still depends on the parent layout, and `getViewportSize()`
+                 * reports what was realised.
                  */
                 setViewportSize(width: number, height: number): void;
-                /** Buffered page `console.*` output. Empty unless the bridge was created
-                 *  with `{ captureConsole: true }`. */
+                /** Buffered page `console.*` output; empty without `{ captureConsole: true }`. */
                 getConsoleLogs(): ConsoleLogEntry[];
                 /** Drop all buffered console entries. */
                 clearConsoleLogs(): void;
-                /** Subscribe to captured console entries as they arrive. Requires
-                 *  `{ captureConsole: true }` to receive anything. */
+                /** Console entries as they arrive; needs `{ captureConsole: true }`. */
                 onConsole(cb: ConsoleCallback): void;
                 /** Every `<a href>` on the page (resolved href, trimmed text, title). */
                 getLinks(): Promise<LinkInfo[]>;
@@ -2197,107 +2082,74 @@ export declare const IFrameBridge: {
                 _lastLoadError: LoadErrorInfo | null;
                 _loadErrorCallbacks: LoadErrorCallback[];
                 /**
-                 * GTK4 allocation hook — surfaces WebKit.WebView size changes to any
-                 * ResizeObserver watching the paired HTMLIFrameElement (or an ancestor;
-                 * see notifyElementResize). GTK4 has no `resize` signal on Gtk.Widget
-                 * (only Gtk.DrawingArea/GLArea), so the allocation vfunc is the portable
-                 * way to observe the widget's size.
+                 * Surfaces size changes to any ResizeObserver watching the paired
+                 * HTMLIFrameElement or an ancestor. GTK4 has no `resize` signal on Gtk.Widget
+                 * (only Gtk.DrawingArea/GLArea), so this vfunc is the portable way to see them.
                  */
                 vfunc_size_allocate(width: number, height: number, baseline: number): void;
                 /** The HTMLIFrameElement wrapping this WebView. */
                 get iframeElement(): HTMLIFrameElement;
-                /**
-                 * Register a callback to be invoked when content has loaded.
-                 * If content is already loaded, the callback fires on next load.
-                 */
+                /** Runs `cb` when content has loaded — on the NEXT load if it already has. */
                 onReady(cb: IFrameReadyCallback): void;
-                /**
-                 * Load a URI into the WebView.
-                 * Also updates the iframe element's src attribute.
-                 */
+                /** Load a URI, keeping the iframe element's `src` attribute in step. */
                 loadUri(uri: string): void;
-                /**
-                 * Load inline HTML into the WebView.
-                 * Also updates the iframe element's srcdoc attribute.
-                 */
+                /** Load inline HTML, keeping the iframe element's `srcdoc` attribute in step. */
                 loadHtml(html: string, baseUri?: string): void;
-                /**
-                 * Send a message to the WebView content via the standard postMessage API.
-                 * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
-                 */
+                /** Equivalent to `iframeElement.contentWindow.postMessage(message, targetOrigin)`. */
                 postMessage(message: unknown, targetOrigin?: string): void;
                 /**
-                 * Navigate the embedded WebView back one entry in its internal
-                 * history list. No-op when `canGoBack` is false.
+                 * Back one entry in WEBKIT's own history list, independent of any
+                 * application-level history. No-op when `canGoBack` is false.
                  *
-                 * Note: reflects WebKit's own navigation history (independent of
-                 * any application-level history the embedder maintains). The
-                 * browser `<iframe>` element has no equivalent — cross-origin
-                 * iframes cannot be navigated programmatically by the parent. For
-                 * cross-variant (browser + GJS) parity, embedders typically track
-                 * URLs themselves and call `loadUri(url)`; the methods here exist
-                 * for apps that DO want to expose the WebKit-internal back/forward
-                 * list directly (e.g. a "WebView with browser-like UX").
+                 * The browser `<iframe>` has no equivalent (a parent cannot navigate a
+                 * cross-origin iframe), so cross-variant parity means tracking URLs yourself and
+                 * calling `loadUri(url)`.
                  */
                 goBack(): void;
-                /** Navigate forward in the WebView's internal history. No-op when
-                 *  `canGoForward` is false. See `goBack()` for caveats. */
+                /** Forward one entry. No-op when `canGoForward` is false; caveats as `goBack()`. */
                 goForward(): void;
-                /** True when the WebView has prior entries in its internal history.
-                 *  Reflects WebKit's `can-go-back` state, NOT any application-level
-                 *  history stack. */
+                /** WebKit's `can-go-back`, NOT any application-level history stack. */
                 get canGoBack(): boolean;
-                /** True when the WebView has forward entries in its internal history.
-                 *  Reflects WebKit's `can-go-forward` state. */
+                /** WebKit's `can-go-forward`. */
                 get canGoForward(): boolean;
-                /** WebKit's ground-truth current URI (`about:blank` before any load).
-                 *  Distinct from any application-side history the embedder maintains. */
+                /** WebKit's ground-truth current URI; `about:blank` before any load. */
                 get currentUri(): string;
-                /** The loaded document's title (empty string before it is known).
-                 *  Reflects WebKit's tracked `<title>`. */
+                /** WebKit's tracked `<title>`; empty before it is known. */
                 get pageTitle(): string;
-                /** Detail of the most recent failed load, or null when the current
-                 *  page loaded without a main-resource failure. */
+                /** The most recent failed load, or null when the current page had no failure. */
                 get lastLoadError(): LoadErrorInfo | null;
                 /** Subscribe to load failures (network / main-resource errors). */
                 onLoadError(cb: LoadErrorCallback): void;
                 /**
                  * Evaluate a JavaScript *expression* in the page and return its value.
                  *
-                 * The value is serialised to JSON in-page and parsed on the GJS host,
-                 * so objects/arrays/strings/numbers/booleans/null round-trip. A value
-                 * that is not JSON-serialisable (DOM node, function, circular object)
-                 * comes back as `undefined`. A thrown page error rejects the promise.
+                 * The value round-trips through JSON, so anything not JSON-serialisable (DOM
+                 * node, function, circular object) comes back as `undefined`; a thrown page error
+                 * rejects the promise.
                  *
-                 * Pass an expression, not statements — wrap multi-statement logic in an
-                 * IIFE that returns a value, e.g.
-                 * `evaluateJavaScript('(() => { const a = 1; return a + 1; })()')`.
-                 * This mirrors Playwright/Puppeteer `page.evaluate` ergonomics.
+                 * An EXPRESSION, not statements: wrap multi-statement logic in an IIFE that
+                 * returns a value, as `page.evaluate` requires.
                  */
                 evaluateJavaScript(expression: string): Promise<unknown>;
                 /**
                  * Capture the rendered web content as PNG bytes.
                  *
-                 * `'full'` (default) snapshots the whole scrollable document; `'visible'`
-                 * snapshots only the current viewport. This goes through WebKit's own
-                 * `get_snapshot` — NOT a GSK widget snapshot — because WebKit composites
-                 * its content in a separate process, so a GTK-tree snapshot of the
+                 * `'full'` (default) takes the whole scrollable document, `'visible'` the current
+                 * viewport. Through WebKit's own `get_snapshot` and NOT a GSK widget snapshot,
+                 * because WebKit composites in a separate process, so a GTK-tree snapshot of the
                  * WebView can come back blank or stale.
                  */
                 takeScreenshot(region?: "full" | "visible"): Promise<Uint8Array>;
                 /**
                  * Resolve on the next load that finishes (`LoadEvent.FINISHED`).
                  *
-                 * `onReady()` fires only once and is drained per load, so a
-                 * page-initiated navigation (link click, JS redirect, form submit,
-                 * meta-refresh) never re-triggers it. Register a `waitForNavigation()`
-                 * *before* triggering such a navigation. Rejects on a main-resource
-                 * load failure, or after `timeoutMs` (0 disables the timeout).
+                 * `onReady()` is drained per load, so a page-initiated navigation (link click, JS
+                 * redirect, form submit, meta-refresh) never re-triggers it — register this
+                 * BEFORE triggering one. Rejects on a main-resource failure, or after `timeoutMs`
+                 * (0 disables the timeout).
                  */
                 waitForNavigation(timeoutMs?: number): Promise<void>;
-                /** Settle (and clear) every pending waitForNavigation() promise,
-                 *  removing its timeout source. Resolves them on success; rejects with
-                 *  `error` on a load failure. */
+                /** Settle and clear every pending waitForNavigation(), removing its timeout. */
                 _settleNavigationWaiters(error: Error | null): void;
                 /** Current size of the WebView content region, in widget pixels. */
                 getViewportSize(): {
@@ -2305,18 +2157,16 @@ export declare const IFrameBridge: {
                     height: number;
                 };
                 /**
-                 * Request a content-region size (e.g. for responsive testing). This sets
-                 * the widget's size request; the actual allocation still depends on the
-                 * parent layout, and `getViewportSize()` reflects the realised size.
+                 * Request a content-region size, e.g. for responsive testing. Only a size REQUEST:
+                 * the allocation still depends on the parent layout, and `getViewportSize()`
+                 * reports what was realised.
                  */
                 setViewportSize(width: number, height: number): void;
-                /** Buffered page `console.*` output. Empty unless the bridge was created
-                 *  with `{ captureConsole: true }`. */
+                /** Buffered page `console.*` output; empty without `{ captureConsole: true }`. */
                 getConsoleLogs(): ConsoleLogEntry[];
                 /** Drop all buffered console entries. */
                 clearConsoleLogs(): void;
-                /** Subscribe to captured console entries as they arrive. Requires
-                 *  `{ captureConsole: true }` to receive anything. */
+                /** Console entries as they arrive; needs `{ captureConsole: true }`. */
                 onConsole(cb: ConsoleCallback): void;
                 /** Every `<a href>` on the page (resolved href, trimmed text, title). */
                 getLinks(): Promise<LinkInfo[]>;
@@ -2914,107 +2764,74 @@ export declare const IFrameBridge: {
             _lastLoadError: LoadErrorInfo | null;
             _loadErrorCallbacks: LoadErrorCallback[];
             /**
-             * GTK4 allocation hook — surfaces WebKit.WebView size changes to any
-             * ResizeObserver watching the paired HTMLIFrameElement (or an ancestor;
-             * see notifyElementResize). GTK4 has no `resize` signal on Gtk.Widget
-             * (only Gtk.DrawingArea/GLArea), so the allocation vfunc is the portable
-             * way to observe the widget's size.
+             * Surfaces size changes to any ResizeObserver watching the paired
+             * HTMLIFrameElement or an ancestor. GTK4 has no `resize` signal on Gtk.Widget
+             * (only Gtk.DrawingArea/GLArea), so this vfunc is the portable way to see them.
              */
             vfunc_size_allocate(width: number, height: number, baseline: number): void;
             /** The HTMLIFrameElement wrapping this WebView. */
             get iframeElement(): HTMLIFrameElement;
-            /**
-             * Register a callback to be invoked when content has loaded.
-             * If content is already loaded, the callback fires on next load.
-             */
+            /** Runs `cb` when content has loaded — on the NEXT load if it already has. */
             onReady(cb: IFrameReadyCallback): void;
-            /**
-             * Load a URI into the WebView.
-             * Also updates the iframe element's src attribute.
-             */
+            /** Load a URI, keeping the iframe element's `src` attribute in step. */
             loadUri(uri: string): void;
-            /**
-             * Load inline HTML into the WebView.
-             * Also updates the iframe element's srcdoc attribute.
-             */
+            /** Load inline HTML, keeping the iframe element's `srcdoc` attribute in step. */
             loadHtml(html: string, baseUri?: string): void;
-            /**
-             * Send a message to the WebView content via the standard postMessage API.
-             * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
-             */
+            /** Equivalent to `iframeElement.contentWindow.postMessage(message, targetOrigin)`. */
             postMessage(message: unknown, targetOrigin?: string): void;
             /**
-             * Navigate the embedded WebView back one entry in its internal
-             * history list. No-op when `canGoBack` is false.
+             * Back one entry in WEBKIT's own history list, independent of any
+             * application-level history. No-op when `canGoBack` is false.
              *
-             * Note: reflects WebKit's own navigation history (independent of
-             * any application-level history the embedder maintains). The
-             * browser `<iframe>` element has no equivalent — cross-origin
-             * iframes cannot be navigated programmatically by the parent. For
-             * cross-variant (browser + GJS) parity, embedders typically track
-             * URLs themselves and call `loadUri(url)`; the methods here exist
-             * for apps that DO want to expose the WebKit-internal back/forward
-             * list directly (e.g. a "WebView with browser-like UX").
+             * The browser `<iframe>` has no equivalent (a parent cannot navigate a
+             * cross-origin iframe), so cross-variant parity means tracking URLs yourself and
+             * calling `loadUri(url)`.
              */
             goBack(): void;
-            /** Navigate forward in the WebView's internal history. No-op when
-             *  `canGoForward` is false. See `goBack()` for caveats. */
+            /** Forward one entry. No-op when `canGoForward` is false; caveats as `goBack()`. */
             goForward(): void;
-            /** True when the WebView has prior entries in its internal history.
-             *  Reflects WebKit's `can-go-back` state, NOT any application-level
-             *  history stack. */
+            /** WebKit's `can-go-back`, NOT any application-level history stack. */
             get canGoBack(): boolean;
-            /** True when the WebView has forward entries in its internal history.
-             *  Reflects WebKit's `can-go-forward` state. */
+            /** WebKit's `can-go-forward`. */
             get canGoForward(): boolean;
-            /** WebKit's ground-truth current URI (`about:blank` before any load).
-             *  Distinct from any application-side history the embedder maintains. */
+            /** WebKit's ground-truth current URI; `about:blank` before any load. */
             get currentUri(): string;
-            /** The loaded document's title (empty string before it is known).
-             *  Reflects WebKit's tracked `<title>`. */
+            /** WebKit's tracked `<title>`; empty before it is known. */
             get pageTitle(): string;
-            /** Detail of the most recent failed load, or null when the current
-             *  page loaded without a main-resource failure. */
+            /** The most recent failed load, or null when the current page had no failure. */
             get lastLoadError(): LoadErrorInfo | null;
             /** Subscribe to load failures (network / main-resource errors). */
             onLoadError(cb: LoadErrorCallback): void;
             /**
              * Evaluate a JavaScript *expression* in the page and return its value.
              *
-             * The value is serialised to JSON in-page and parsed on the GJS host,
-             * so objects/arrays/strings/numbers/booleans/null round-trip. A value
-             * that is not JSON-serialisable (DOM node, function, circular object)
-             * comes back as `undefined`. A thrown page error rejects the promise.
+             * The value round-trips through JSON, so anything not JSON-serialisable (DOM
+             * node, function, circular object) comes back as `undefined`; a thrown page error
+             * rejects the promise.
              *
-             * Pass an expression, not statements — wrap multi-statement logic in an
-             * IIFE that returns a value, e.g.
-             * `evaluateJavaScript('(() => { const a = 1; return a + 1; })()')`.
-             * This mirrors Playwright/Puppeteer `page.evaluate` ergonomics.
+             * An EXPRESSION, not statements: wrap multi-statement logic in an IIFE that
+             * returns a value, as `page.evaluate` requires.
              */
             evaluateJavaScript(expression: string): Promise<unknown>;
             /**
              * Capture the rendered web content as PNG bytes.
              *
-             * `'full'` (default) snapshots the whole scrollable document; `'visible'`
-             * snapshots only the current viewport. This goes through WebKit's own
-             * `get_snapshot` — NOT a GSK widget snapshot — because WebKit composites
-             * its content in a separate process, so a GTK-tree snapshot of the
+             * `'full'` (default) takes the whole scrollable document, `'visible'` the current
+             * viewport. Through WebKit's own `get_snapshot` and NOT a GSK widget snapshot,
+             * because WebKit composites in a separate process, so a GTK-tree snapshot of the
              * WebView can come back blank or stale.
              */
             takeScreenshot(region?: "full" | "visible"): Promise<Uint8Array>;
             /**
              * Resolve on the next load that finishes (`LoadEvent.FINISHED`).
              *
-             * `onReady()` fires only once and is drained per load, so a
-             * page-initiated navigation (link click, JS redirect, form submit,
-             * meta-refresh) never re-triggers it. Register a `waitForNavigation()`
-             * *before* triggering such a navigation. Rejects on a main-resource
-             * load failure, or after `timeoutMs` (0 disables the timeout).
+             * `onReady()` is drained per load, so a page-initiated navigation (link click, JS
+             * redirect, form submit, meta-refresh) never re-triggers it — register this
+             * BEFORE triggering one. Rejects on a main-resource failure, or after `timeoutMs`
+             * (0 disables the timeout).
              */
             waitForNavigation(timeoutMs?: number): Promise<void>;
-            /** Settle (and clear) every pending waitForNavigation() promise,
-             *  removing its timeout source. Resolves them on success; rejects with
-             *  `error` on a load failure. */
+            /** Settle and clear every pending waitForNavigation(), removing its timeout. */
             _settleNavigationWaiters(error: Error | null): void;
             /** Current size of the WebView content region, in widget pixels. */
             getViewportSize(): {
@@ -3022,18 +2839,16 @@ export declare const IFrameBridge: {
                 height: number;
             };
             /**
-             * Request a content-region size (e.g. for responsive testing). This sets
-             * the widget's size request; the actual allocation still depends on the
-             * parent layout, and `getViewportSize()` reflects the realised size.
+             * Request a content-region size, e.g. for responsive testing. Only a size REQUEST:
+             * the allocation still depends on the parent layout, and `getViewportSize()`
+             * reports what was realised.
              */
             setViewportSize(width: number, height: number): void;
-            /** Buffered page `console.*` output. Empty unless the bridge was created
-             *  with `{ captureConsole: true }`. */
+            /** Buffered page `console.*` output; empty without `{ captureConsole: true }`. */
             getConsoleLogs(): ConsoleLogEntry[];
             /** Drop all buffered console entries. */
             clearConsoleLogs(): void;
-            /** Subscribe to captured console entries as they arrive. Requires
-             *  `{ captureConsole: true }` to receive anything. */
+            /** Console entries as they arrive; needs `{ captureConsole: true }`. */
             onConsole(cb: ConsoleCallback): void;
             /** Every `<a href>` on the page (resolved href, trimmed text, title). */
             getLinks(): Promise<LinkInfo[]>;
@@ -3631,107 +3446,74 @@ export declare const IFrameBridge: {
         _lastLoadError: LoadErrorInfo | null;
         _loadErrorCallbacks: LoadErrorCallback[];
         /**
-         * GTK4 allocation hook — surfaces WebKit.WebView size changes to any
-         * ResizeObserver watching the paired HTMLIFrameElement (or an ancestor;
-         * see notifyElementResize). GTK4 has no `resize` signal on Gtk.Widget
-         * (only Gtk.DrawingArea/GLArea), so the allocation vfunc is the portable
-         * way to observe the widget's size.
+         * Surfaces size changes to any ResizeObserver watching the paired
+         * HTMLIFrameElement or an ancestor. GTK4 has no `resize` signal on Gtk.Widget
+         * (only Gtk.DrawingArea/GLArea), so this vfunc is the portable way to see them.
          */
         vfunc_size_allocate(width: number, height: number, baseline: number): void;
         /** The HTMLIFrameElement wrapping this WebView. */
         get iframeElement(): HTMLIFrameElement;
-        /**
-         * Register a callback to be invoked when content has loaded.
-         * If content is already loaded, the callback fires on next load.
-         */
+        /** Runs `cb` when content has loaded — on the NEXT load if it already has. */
         onReady(cb: IFrameReadyCallback): void;
-        /**
-         * Load a URI into the WebView.
-         * Also updates the iframe element's src attribute.
-         */
+        /** Load a URI, keeping the iframe element's `src` attribute in step. */
         loadUri(uri: string): void;
-        /**
-         * Load inline HTML into the WebView.
-         * Also updates the iframe element's srcdoc attribute.
-         */
+        /** Load inline HTML, keeping the iframe element's `srcdoc` attribute in step. */
         loadHtml(html: string, baseUri?: string): void;
-        /**
-         * Send a message to the WebView content via the standard postMessage API.
-         * Equivalent to `this.iframeElement.contentWindow.postMessage(message, targetOrigin)`.
-         */
+        /** Equivalent to `iframeElement.contentWindow.postMessage(message, targetOrigin)`. */
         postMessage(message: unknown, targetOrigin?: string): void;
         /**
-         * Navigate the embedded WebView back one entry in its internal
-         * history list. No-op when `canGoBack` is false.
+         * Back one entry in WEBKIT's own history list, independent of any
+         * application-level history. No-op when `canGoBack` is false.
          *
-         * Note: reflects WebKit's own navigation history (independent of
-         * any application-level history the embedder maintains). The
-         * browser `<iframe>` element has no equivalent — cross-origin
-         * iframes cannot be navigated programmatically by the parent. For
-         * cross-variant (browser + GJS) parity, embedders typically track
-         * URLs themselves and call `loadUri(url)`; the methods here exist
-         * for apps that DO want to expose the WebKit-internal back/forward
-         * list directly (e.g. a "WebView with browser-like UX").
+         * The browser `<iframe>` has no equivalent (a parent cannot navigate a
+         * cross-origin iframe), so cross-variant parity means tracking URLs yourself and
+         * calling `loadUri(url)`.
          */
         goBack(): void;
-        /** Navigate forward in the WebView's internal history. No-op when
-         *  `canGoForward` is false. See `goBack()` for caveats. */
+        /** Forward one entry. No-op when `canGoForward` is false; caveats as `goBack()`. */
         goForward(): void;
-        /** True when the WebView has prior entries in its internal history.
-         *  Reflects WebKit's `can-go-back` state, NOT any application-level
-         *  history stack. */
+        /** WebKit's `can-go-back`, NOT any application-level history stack. */
         get canGoBack(): boolean;
-        /** True when the WebView has forward entries in its internal history.
-         *  Reflects WebKit's `can-go-forward` state. */
+        /** WebKit's `can-go-forward`. */
         get canGoForward(): boolean;
-        /** WebKit's ground-truth current URI (`about:blank` before any load).
-         *  Distinct from any application-side history the embedder maintains. */
+        /** WebKit's ground-truth current URI; `about:blank` before any load. */
         get currentUri(): string;
-        /** The loaded document's title (empty string before it is known).
-         *  Reflects WebKit's tracked `<title>`. */
+        /** WebKit's tracked `<title>`; empty before it is known. */
         get pageTitle(): string;
-        /** Detail of the most recent failed load, or null when the current
-         *  page loaded without a main-resource failure. */
+        /** The most recent failed load, or null when the current page had no failure. */
         get lastLoadError(): LoadErrorInfo | null;
         /** Subscribe to load failures (network / main-resource errors). */
         onLoadError(cb: LoadErrorCallback): void;
         /**
          * Evaluate a JavaScript *expression* in the page and return its value.
          *
-         * The value is serialised to JSON in-page and parsed on the GJS host,
-         * so objects/arrays/strings/numbers/booleans/null round-trip. A value
-         * that is not JSON-serialisable (DOM node, function, circular object)
-         * comes back as `undefined`. A thrown page error rejects the promise.
+         * The value round-trips through JSON, so anything not JSON-serialisable (DOM
+         * node, function, circular object) comes back as `undefined`; a thrown page error
+         * rejects the promise.
          *
-         * Pass an expression, not statements — wrap multi-statement logic in an
-         * IIFE that returns a value, e.g.
-         * `evaluateJavaScript('(() => { const a = 1; return a + 1; })()')`.
-         * This mirrors Playwright/Puppeteer `page.evaluate` ergonomics.
+         * An EXPRESSION, not statements: wrap multi-statement logic in an IIFE that
+         * returns a value, as `page.evaluate` requires.
          */
         evaluateJavaScript(expression: string): Promise<unknown>;
         /**
          * Capture the rendered web content as PNG bytes.
          *
-         * `'full'` (default) snapshots the whole scrollable document; `'visible'`
-         * snapshots only the current viewport. This goes through WebKit's own
-         * `get_snapshot` — NOT a GSK widget snapshot — because WebKit composites
-         * its content in a separate process, so a GTK-tree snapshot of the
+         * `'full'` (default) takes the whole scrollable document, `'visible'` the current
+         * viewport. Through WebKit's own `get_snapshot` and NOT a GSK widget snapshot,
+         * because WebKit composites in a separate process, so a GTK-tree snapshot of the
          * WebView can come back blank or stale.
          */
         takeScreenshot(region?: "full" | "visible"): Promise<Uint8Array>;
         /**
          * Resolve on the next load that finishes (`LoadEvent.FINISHED`).
          *
-         * `onReady()` fires only once and is drained per load, so a
-         * page-initiated navigation (link click, JS redirect, form submit,
-         * meta-refresh) never re-triggers it. Register a `waitForNavigation()`
-         * *before* triggering such a navigation. Rejects on a main-resource
-         * load failure, or after `timeoutMs` (0 disables the timeout).
+         * `onReady()` is drained per load, so a page-initiated navigation (link click, JS
+         * redirect, form submit, meta-refresh) never re-triggers it — register this
+         * BEFORE triggering one. Rejects on a main-resource failure, or after `timeoutMs`
+         * (0 disables the timeout).
          */
         waitForNavigation(timeoutMs?: number): Promise<void>;
-        /** Settle (and clear) every pending waitForNavigation() promise,
-         *  removing its timeout source. Resolves them on success; rejects with
-         *  `error` on a load failure. */
+        /** Settle and clear every pending waitForNavigation(), removing its timeout. */
         _settleNavigationWaiters(error: Error | null): void;
         /** Current size of the WebView content region, in widget pixels. */
         getViewportSize(): {
@@ -3739,18 +3521,16 @@ export declare const IFrameBridge: {
             height: number;
         };
         /**
-         * Request a content-region size (e.g. for responsive testing). This sets
-         * the widget's size request; the actual allocation still depends on the
-         * parent layout, and `getViewportSize()` reflects the realised size.
+         * Request a content-region size, e.g. for responsive testing. Only a size REQUEST:
+         * the allocation still depends on the parent layout, and `getViewportSize()`
+         * reports what was realised.
          */
         setViewportSize(width: number, height: number): void;
-        /** Buffered page `console.*` output. Empty unless the bridge was created
-         *  with `{ captureConsole: true }`. */
+        /** Buffered page `console.*` output; empty without `{ captureConsole: true }`. */
         getConsoleLogs(): ConsoleLogEntry[];
         /** Drop all buffered console entries. */
         clearConsoleLogs(): void;
-        /** Subscribe to captured console entries as they arrive. Requires
-         *  `{ captureConsole: true }` to receive anything. */
+        /** Console entries as they arrive; needs `{ captureConsole: true }`. */
         onConsole(cb: ConsoleCallback): void;
         /** Every `<a href>` on the page (resolved href, trimmed text, title). */
         getLinks(): Promise<LinkInfo[]>;