@gjsify/iframe 0.21.0 → 0.23.0

package/README.md

@@ -31,6 +31,41 @@ widget.iframeElement.srcdoc = '<h1>Hello</h1>';
 window.set_child(widget);
 ```
 
+## Globals
+
+The package root is a **side-effect-free barrel** — importing it gives you named
+exports and nothing else. The DOM wiring lives in the dedicated `/register`
+subpath:
+
+```typescript
+import '@gjsify/iframe/register';
+```
+
+It does two things:
+
+- installs `globalThis.HTMLIFrameElement` (guarded — a global that already exists wins);
+- registers the `'iframe'` element factory, so `document.createElement('iframe')`
+  returns a WebKit-backed `HTMLIFrameElement`.
+
+You normally never write that import: `gjsify build` defaults to `--globals auto`,
+which detects a free `HTMLIFrameElement` reference in the bundled output and injects
+the subpath for you. Application and example code should rely on that (see the
+tree-shakeable-globals convention in `AGENTS.md`).
+
+`IFrameBridge` itself needs neither — it constructs its `HTMLIFrameElement`
+directly — so `new IFrameBridge()` works with `--globals none`. If you want the
+DOM surface unconditionally (overriding whatever is there), the bridge exposes the
+explicit, imperative counterpart, which installs exactly the same pair:
+
+```typescript
+widget.installGlobals();   // globalThis.HTMLIFrameElement + the 'iframe' element factory
+```
+
+> **Changed after 0.22.0** — up to and including 0.22.0, `import { IFrameBridge } from '@gjsify/iframe'`
+> installed `globalThis.HTMLIFrameElement` and the `'iframe'` element factory as an
+> import side effect. See
+> [ADR 0012](https://github.com/gjsify/gjsify/blob/main/docs/adr/0012-framework-register-ownership.md).
+
 ## License
 
 MIT

package/lib/esm/iframe-bridge.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{buildClickElementExpression as e,buildGetLinksExpression as t,buildQueryDomExpression as n}from"./dom-queries.js";import{buildEvalScript as r,parseEvalResult as i}from"./eval.js";import{iframeWidget as a,windowProxy as o}from"./property-symbol.js";import{HTMLIFrameElement as s}from"./html-iframe-element.js";import{IFrameWindowProxy as c}from"./iframe-window-proxy.js";import"./promisify.js";import{MessageBridge as l}from"./message-bridge.js";import{notifyElementResize as u}from"@gjsify/dom-elements";import d from"gi://GLib?version=2.0";import f from"gi://GObject";import p from"gi://WebKit?version=6.0";const m=f.registerClass({GTypeName:`GjsifyIFrameBridge`},class IFrameBridge extends p.WebView{constructor(e){let{enableDeveloperExtras:t,enableJavascript:n,captureConsole:r,...i}=e??{},u=new p.UserContentManager,d=new p.Settings;d.enable_javascript=n??!0,d.enable_developer_extras=t??!0,super({...i,user_content_manager:u,settings:d}),this._readyCallbacks=[],this._navigationWaiters=[],this._lastLoadError=null,this._loadErrorCallbacks=[],this._options={enableDeveloperExtras:t,enableJavascript:n,captureConsole:r},this._iframe=new s,this._iframe[a]=this,this._messageBridge=new l(this,{captureConsole:r});let f=new c(this._messageBridge);this._iframe[o]=f,this._messageBridge.setWindowProxy(f),this.connect(`load-changed`,(e,t)=>{switch(t){case p.LoadEvent.STARTED:this._lastLoadError=null;break;case p.LoadEvent.COMMITTED:{let e=this.get_uri();e&&this._messageBridge.updateUri(e);break}case p.LoadEvent.FINISHED:this._iframe._onLoad();for(let e of this._readyCallbacks)e(this._iframe);this._readyCallbacks=[],this._settleNavigationWaiters(null);break}}),this.connect(`load-failed`,(e,t,n,r)=>{let i={uri:n,message:r?.message??`load failed`};this._lastLoadError=i;for(let e of this._loadErrorCallbacks)e(i);return this._iframe._onError(),this._settleNavigationWaiters(Error(`load failed for ${n}: ${i.message}`)),!1}),this.connect(`unrealize`,()=>{this._messageBridge.destroy();let e=this._iframe[o];e&&e._close(),this._iframe[a]=null,this._iframe[o]=null})}vfunc_size_allocate(e,t,n){super.vfunc_size_allocate(e,t,n),u(this._iframe,e,t)}get iframeElement(){return this._iframe}onReady(e){this._readyCallbacks.push(e)}loadUri(e){this._iframe.setAttribute(`src`,e),this.load_uri(e)}loadHtml(e,t){this._iframe.setAttribute(`srcdoc`,e),this.load_html(e,t??`about:srcdoc`)}postMessage(e,t=`*`){this._messageBridge.sendToWebView(e,t)}goBack(){this.go_back()}goForward(){this.go_forward()}get canGoBack(){return this.can_go_back()}get canGoForward(){return this.can_go_forward()}get currentUri(){return this.get_uri()??`about:blank`}get pageTitle(){return this.get_title()??``}get lastLoadError(){return this._lastLoadError}onLoadError(e){this._loadErrorCallbacks.push(e)}async evaluateJavaScript(e){return i((await this.evaluate_javascript(r(e),-1,null,null,null))?.to_string()??null)}async takeScreenshot(e=`full`){let t=e===`visible`?p.SnapshotRegion.VISIBLE:p.SnapshotRegion.FULL_DOCUMENT,n=(await this.get_snapshot(t,p.SnapshotOptions.NONE,null)).save_to_png_bytes().get_data();return n?new Uint8Array(n):new Uint8Array}waitForNavigation(e=3e4){return new Promise((t,n)=>{let r={resolve:t,reject:n,sourceId:null};e>0&&(r.sourceId=d.timeout_add(d.PRIORITY_DEFAULT,e,()=>{let t=this._navigationWaiters.indexOf(r);return t!==-1&&this._navigationWaiters.splice(t,1),r.sourceId=null,n(Error(`waitForNavigation: timed out after ${e}ms`)),d.SOURCE_REMOVE})),this._navigationWaiters.push(r)})}_settleNavigationWaiters(e){if(this._navigationWaiters.length===0)return;let t=this._navigationWaiters;this._navigationWaiters=[];for(let n of t)n.sourceId!==null&&(d.source_remove(n.sourceId),n.sourceId=null),e?n.reject(e):n.resolve()}getViewportSize(){return{width:this.get_allocated_width(),height:this.get_allocated_height()}}setViewportSize(e,t){this.set_size_request(e,t)}getConsoleLogs(){return this._messageBridge.getConsoleLogs()}clearConsoleLogs(){this._messageBridge.clearConsoleLogs()}onConsole(e){this._messageBridge.onConsole(e)}async getLinks(){let e=await this.evaluateJavaScript(t());return Array.isArray(e)?e:[]}async queryDom(e,t=200){let r=await this.evaluateJavaScript(n(e,t));return Array.isArray(r)?r:[]}async clickElement(t){return await this.evaluateJavaScript(e(t))===!0}installGlobals(){Object.defineProperty(globalThis,`HTMLIFrameElement`,{value:s,writable:!0,configurable:!0})}});export{m as IFrameBridge};
+import"./_virtual/_rolldown/runtime.js";import{buildClickElementExpression as e,buildGetLinksExpression as t,buildQueryDomExpression as n}from"./dom-queries.js";import{buildEvalScript as r,parseEvalResult as i}from"./eval.js";import{iframeWidget as a,windowProxy as o}from"./property-symbol.js";import{HTMLIFrameElement as s}from"./html-iframe-element.js";import{IFrameWindowProxy as c}from"./iframe-window-proxy.js";import"./promisify.js";import{MessageBridge as l}from"./message-bridge.js";import{Document as u,notifyElementResize as d}from"@gjsify/dom-elements";import f from"gi://GLib?version=2.0";import p from"gi://GObject";import m from"gi://WebKit?version=6.0";const h=p.registerClass({GTypeName:`GjsifyIFrameBridge`},class IFrameBridge extends m.WebView{constructor(e){let{enableDeveloperExtras:t,enableJavascript:n,captureConsole:r,...i}=e??{},u=new m.UserContentManager,d=new m.Settings;d.enable_javascript=n??!0,d.enable_developer_extras=t??!0,super({...i,user_content_manager:u,settings:d}),this._readyCallbacks=[],this._navigationWaiters=[],this._lastLoadError=null,this._loadErrorCallbacks=[],this._options={enableDeveloperExtras:t,enableJavascript:n,captureConsole:r},this._iframe=new s,this._iframe[a]=this,this._messageBridge=new l(this,{captureConsole:r});let f=new c(this._messageBridge);this._iframe[o]=f,this._messageBridge.setWindowProxy(f),this.connect(`load-changed`,(e,t)=>{switch(t){case m.LoadEvent.STARTED:this._lastLoadError=null;break;case m.LoadEvent.COMMITTED:{let e=this.get_uri();e&&this._messageBridge.updateUri(e);break}case m.LoadEvent.FINISHED:this._iframe._onLoad();for(let e of this._readyCallbacks)e(this._iframe);this._readyCallbacks=[],this._settleNavigationWaiters(null);break}}),this.connect(`load-failed`,(e,t,n,r)=>{let i={uri:n,message:r?.message??`load failed`};this._lastLoadError=i;for(let e of this._loadErrorCallbacks)e(i);return this._iframe._onError(),this._settleNavigationWaiters(Error(`load failed for ${n}: ${i.message}`)),!1}),this.connect(`unrealize`,()=>{this._messageBridge.destroy();let e=this._iframe[o];e&&e._close(),this._iframe[a]=null,this._iframe[o]=null})}vfunc_size_allocate(e,t,n){super.vfunc_size_allocate(e,t,n),d(this._iframe,e,t)}get iframeElement(){return this._iframe}onReady(e){this._readyCallbacks.push(e)}loadUri(e){this._iframe.setAttribute(`src`,e),this.load_uri(e)}loadHtml(e,t){this._iframe.setAttribute(`srcdoc`,e),this.load_html(e,t??`about:srcdoc`)}postMessage(e,t=`*`){this._messageBridge.sendToWebView(e,t)}goBack(){this.go_back()}goForward(){this.go_forward()}get canGoBack(){return this.can_go_back()}get canGoForward(){return this.can_go_forward()}get currentUri(){return this.get_uri()??`about:blank`}get pageTitle(){return this.get_title()??``}get lastLoadError(){return this._lastLoadError}onLoadError(e){this._loadErrorCallbacks.push(e)}async evaluateJavaScript(e){return i((await this.evaluate_javascript(r(e),-1,null,null,null))?.to_string()??null)}async takeScreenshot(e=`full`){let t=e===`visible`?m.SnapshotRegion.VISIBLE:m.SnapshotRegion.FULL_DOCUMENT,n=(await this.get_snapshot(t,m.SnapshotOptions.NONE,null)).save_to_png_bytes().get_data();return n?new Uint8Array(n):new Uint8Array}waitForNavigation(e=3e4){return new Promise((t,n)=>{let r={resolve:t,reject:n,sourceId:null};e>0&&(r.sourceId=f.timeout_add(f.PRIORITY_DEFAULT,e,()=>{let t=this._navigationWaiters.indexOf(r);return t!==-1&&this._navigationWaiters.splice(t,1),r.sourceId=null,n(Error(`waitForNavigation: timed out after ${e}ms`)),f.SOURCE_REMOVE})),this._navigationWaiters.push(r)})}_settleNavigationWaiters(e){if(this._navigationWaiters.length===0)return;let t=this._navigationWaiters;this._navigationWaiters=[];for(let n of t)n.sourceId!==null&&(f.source_remove(n.sourceId),n.sourceId=null),e?n.reject(e):n.resolve()}getViewportSize(){return{width:this.get_allocated_width(),height:this.get_allocated_height()}}setViewportSize(e,t){this.set_size_request(e,t)}getConsoleLogs(){return this._messageBridge.getConsoleLogs()}clearConsoleLogs(){this._messageBridge.clearConsoleLogs()}onConsole(e){this._messageBridge.onConsole(e)}async getLinks(){let e=await this.evaluateJavaScript(t());return Array.isArray(e)?e:[]}async queryDom(e,t=200){let r=await this.evaluateJavaScript(n(e,t));return Array.isArray(r)?r:[]}async clickElement(t){return await this.evaluateJavaScript(e(t))===!0}installGlobals(){u.registerElementFactory(`iframe`,()=>new s),Object.defineProperty(globalThis,"HTMLIFrameElement",{value:s,writable:!0,configurable:!0})}});export{h as IFrameBridge};

package/lib/esm/index.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{HTMLIFrameElement as e}from"./html-iframe-element.js";import{IFrameWindowProxy as t}from"./iframe-window-proxy.js";import{IFrameMessageChannel as n,IFrameMessagePort as r,MessageChannel as i,MessagePort as a}from"./iframe-message-channel.js";import{GJS_HOST_ORIGIN as o,MessageBridge as s}from"./message-bridge.js";import{IFrameBridge as c}from"./iframe-bridge.js";import{Document as l}from"@gjsify/dom-elements";l.registerElementFactory(`iframe`,()=>new e),Object.defineProperty(globalThis,`HTMLIFrameElement`,{value:e,writable:!0,configurable:!0});export{o as GJS_HOST_ORIGIN,e as HTMLIFrameElement,c as IFrameBridge,n as IFrameMessageChannel,r as IFrameMessagePort,t as IFrameWindowProxy,s as MessageBridge,i as MessageChannel,a as MessagePort};
+import{HTMLIFrameElement as e}from"./html-iframe-element.js";import{IFrameWindowProxy as t}from"./iframe-window-proxy.js";import{IFrameMessageChannel as n,IFrameMessagePort as r,MessageChannel as i,MessagePort as a}from"./iframe-message-channel.js";import{GJS_HOST_ORIGIN as o,MessageBridge as s}from"./message-bridge.js";import{IFrameBridge as c}from"./iframe-bridge.js";export{o as GJS_HOST_ORIGIN,e as HTMLIFrameElement,c as IFrameBridge,n as IFrameMessageChannel,r as IFrameMessagePort,t as IFrameWindowProxy,s as MessageBridge,i as MessageChannel,a as MessagePort};

package/lib/esm/register.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{HTMLIFrameElement as e}from"./html-iframe-element.js";import{Document as t}from"@gjsify/dom-elements";t.registerElementFactory(`iframe`,()=>new e),globalThis.HTMLIFrameElement===void 0&&Object.defineProperty(globalThis,"HTMLIFrameElement",{value:e,writable:!0,configurable:!0});

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

@@ -180,7 +180,22 @@ export declare const IFrameBridge: {
          */
         clickElement(selectorOrText: string): Promise<boolean>;
         /**
-         * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+         * Install the iframe DOM surface imperatively: sets
+         * `globalThis.HTMLIFrameElement` to the gjsify implementation AND registers
+         * the `'iframe'` element factory so `document.createElement('iframe')`
+         * returns it.
+         *
+         * This is the same pair `@gjsify/iframe/register` installs — the explicit,
+         * unconditional counterpart of the tree-shakeable `/register` subpath (which
+         * `--globals auto` injects when it sees a free `HTMLIFrameElement`). Both are
+         * needed here: the element factory used to come along for free with the
+         * barrel's import side effect, and app code that calls `installGlobals()` and
+         * then `document.createElement('iframe')` must keep working (ADR 0012 moved
+         * the side effect out of `index.ts`; it did not remove the capability).
+         *
+         * Unconditional by design — an explicit call means "make MY implementation
+         * the one `document` and `globalThis` hand out", so it overrides whatever is
+         * already installed.
          */
         installGlobals(): void;
         get automation_presentation_type(): WebKit.AutomationBrowsingContextPresentation;
@@ -882,7 +897,22 @@ export declare const IFrameBridge: {
              */
             clickElement(selectorOrText: string): Promise<boolean>;
             /**
-             * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+             * Install the iframe DOM surface imperatively: sets
+             * `globalThis.HTMLIFrameElement` to the gjsify implementation AND registers
+             * the `'iframe'` element factory so `document.createElement('iframe')`
+             * returns it.
+             *
+             * This is the same pair `@gjsify/iframe/register` installs — the explicit,
+             * unconditional counterpart of the tree-shakeable `/register` subpath (which
+             * `--globals auto` injects when it sees a free `HTMLIFrameElement`). Both are
+             * needed here: the element factory used to come along for free with the
+             * barrel's import side effect, and app code that calls `installGlobals()` and
+             * then `document.createElement('iframe')` must keep working (ADR 0012 moved
+             * the side effect out of `index.ts`; it did not remove the capability).
+             *
+             * Unconditional by design — an explicit call means "make MY implementation
+             * the one `document` and `globalThis` hand out", so it overrides whatever is
+             * already installed.
              */
             installGlobals(): void;
             get automation_presentation_type(): WebKit.AutomationBrowsingContextPresentation;
@@ -1584,7 +1614,22 @@ export declare const IFrameBridge: {
                  */
                 clickElement(selectorOrText: string): Promise<boolean>;
                 /**
-                 * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+                 * Install the iframe DOM surface imperatively: sets
+                 * `globalThis.HTMLIFrameElement` to the gjsify implementation AND registers
+                 * the `'iframe'` element factory so `document.createElement('iframe')`
+                 * returns it.
+                 *
+                 * This is the same pair `@gjsify/iframe/register` installs — the explicit,
+                 * unconditional counterpart of the tree-shakeable `/register` subpath (which
+                 * `--globals auto` injects when it sees a free `HTMLIFrameElement`). Both are
+                 * needed here: the element factory used to come along for free with the
+                 * barrel's import side effect, and app code that calls `installGlobals()` and
+                 * then `document.createElement('iframe')` must keep working (ADR 0012 moved
+                 * the side effect out of `index.ts`; it did not remove the capability).
+                 *
+                 * Unconditional by design — an explicit call means "make MY implementation
+                 * the one `document` and `globalThis` hand out", so it overrides whatever is
+                 * already installed.
                  */
                 installGlobals(): void;
                 get automation_presentation_type(): WebKit.AutomationBrowsingContextPresentation;
@@ -2286,7 +2331,22 @@ export declare const IFrameBridge: {
                  */
                 clickElement(selectorOrText: string): Promise<boolean>;
                 /**
-                 * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+                 * Install the iframe DOM surface imperatively: sets
+                 * `globalThis.HTMLIFrameElement` to the gjsify implementation AND registers
+                 * the `'iframe'` element factory so `document.createElement('iframe')`
+                 * returns it.
+                 *
+                 * This is the same pair `@gjsify/iframe/register` installs — the explicit,
+                 * unconditional counterpart of the tree-shakeable `/register` subpath (which
+                 * `--globals auto` injects when it sees a free `HTMLIFrameElement`). Both are
+                 * needed here: the element factory used to come along for free with the
+                 * barrel's import side effect, and app code that calls `installGlobals()` and
+                 * then `document.createElement('iframe')` must keep working (ADR 0012 moved
+                 * the side effect out of `index.ts`; it did not remove the capability).
+                 *
+                 * Unconditional by design — an explicit call means "make MY implementation
+                 * the one `document` and `globalThis` hand out", so it overrides whatever is
+                 * already installed.
                  */
                 installGlobals(): void;
                 get automation_presentation_type(): WebKit.AutomationBrowsingContextPresentation;
@@ -2988,7 +3048,22 @@ export declare const IFrameBridge: {
              */
             clickElement(selectorOrText: string): Promise<boolean>;
             /**
-             * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+             * Install the iframe DOM surface imperatively: sets
+             * `globalThis.HTMLIFrameElement` to the gjsify implementation AND registers
+             * the `'iframe'` element factory so `document.createElement('iframe')`
+             * returns it.
+             *
+             * This is the same pair `@gjsify/iframe/register` installs — the explicit,
+             * unconditional counterpart of the tree-shakeable `/register` subpath (which
+             * `--globals auto` injects when it sees a free `HTMLIFrameElement`). Both are
+             * needed here: the element factory used to come along for free with the
+             * barrel's import side effect, and app code that calls `installGlobals()` and
+             * then `document.createElement('iframe')` must keep working (ADR 0012 moved
+             * the side effect out of `index.ts`; it did not remove the capability).
+             *
+             * Unconditional by design — an explicit call means "make MY implementation
+             * the one `document` and `globalThis` hand out", so it overrides whatever is
+             * already installed.
              */
             installGlobals(): void;
             get automation_presentation_type(): WebKit.AutomationBrowsingContextPresentation;
@@ -3690,7 +3765,22 @@ export declare const IFrameBridge: {
          */
         clickElement(selectorOrText: string): Promise<boolean>;
         /**
-         * Set `globalThis.HTMLIFrameElement` to the gjsify implementation.
+         * Install the iframe DOM surface imperatively: sets
+         * `globalThis.HTMLIFrameElement` to the gjsify implementation AND registers
+         * the `'iframe'` element factory so `document.createElement('iframe')`
+         * returns it.
+         *
+         * This is the same pair `@gjsify/iframe/register` installs — the explicit,
+         * unconditional counterpart of the tree-shakeable `/register` subpath (which
+         * `--globals auto` injects when it sees a free `HTMLIFrameElement`). Both are
+         * needed here: the element factory used to come along for free with the
+         * barrel's import side effect, and app code that calls `installGlobals()` and
+         * then `document.createElement('iframe')` must keep working (ADR 0012 moved
+         * the side effect out of `index.ts`; it did not remove the capability).
+         *
+         * Unconditional by design — an explicit call means "make MY implementation
+         * the one `document` and `globalThis` hand out", so it overrides whatever is
+         * already installed.
          */
         installGlobals(): void;
         get automation_presentation_type(): WebKit.AutomationBrowsingContextPresentation;

package/lib/types/register.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register.spec.d.ts

@@ -0,0 +1,3 @@
+import '@gjsify/iframe/register';
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/iframe",
-    "version": "0.21.0",
+    "version": "0.23.0",
     "description": "HTMLIFrameElement for GJS, backed by WebKit.WebView",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -9,8 +9,15 @@
         ".": {
             "types": "./lib/types/index.d.ts",
             "default": "./lib/esm/index.js"
+        },
+        "./register": {
+            "types": "./lib/types/register.d.ts",
+            "default": "./lib/esm/register.js"
         }
     },
+    "sideEffects": [
+        "./lib/esm/register.js"
+    ],
     "files": [
         "lib"
     ],
@@ -38,13 +45,13 @@
         "@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.21.0",
-        "@gjsify/dom-events": "^0.21.0",
-        "@gjsify/message-channel": "^0.21.0"
+        "@gjsify/dom-elements": "^0.23.0",
+        "@gjsify/dom-events": "^0.23.0",
+        "@gjsify/message-channel": "^0.23.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.21.0",
-        "@gjsify/unit": "^0.21.0",
+        "@gjsify/cli": "^0.23.0",
+        "@gjsify/unit": "^0.23.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },