@gjsify/webgl 0.35.0 → 0.37.0

package/README.md

@@ -66,19 +66,38 @@ The `'webgl'` / `'webgl2'` contexts themselves need no register: this package's
 ## Running GJS apps that use this package
 
 This package ships prebuilt native libraries for the platforms listed under
-[Platform coverage](#platform-coverage) — today that is Linux only:
+[Platform coverage](#platform-coverage) — Linux, macOS and Windows. Since
+[ADR 0017](https://github.com/gjsify/gjsify/blob/main/docs/adr/0017-native-package-distribution.md)
+each target lives in its own `optionalDependencies` package, so your package
+manager installs the one that fits and silently skips the rest:
 
 ```
-prebuilds/
-  linux-x64/   libgwebgl.so + Gwebgl-0.1.typelib
-  linux-arm64/  libgwebgl.so + Gwebgl-0.1.typelib
-  linux-ppc64/    libgwebgl.so + Gwebgl-0.1.typelib
-  linux-s390x/    libgwebgl.so + Gwebgl-0.1.typelib
-  linux-riscv64/  libgwebgl.so + Gwebgl-0.1.typelib
+@gjsify/webgl-linux-x64/prebuilds/linux-x64/         libgwebgl.so    + Gwebgl-0.1.typelib
+@gjsify/webgl-linux-arm64/…                          libgwebgl.so    + Gwebgl-0.1.typelib
+@gjsify/webgl-linux-{ppc64,s390x,riscv64}/…          libgwebgl.so    + Gwebgl-0.1.typelib
+@gjsify/webgl-darwin-{arm64,x64}/…                   libgwebgl.dylib + Gwebgl-0.1.typelib
+@gjsify/webgl-win32-x64/prebuilds/win32-x64/         gwebgl.dll      + Gwebgl-0.1.typelib
 ```
 
-There is **no macOS or Windows prebuild**; on those platforms `getContext('webgl')`
-has no native backend.
+**Windows needs two more things than the other platforms**, and neither is
+optional:
+
+- **`@gjsify/gtk-runtime-win32-x64`.** `gwebgl.dll` imports `epoxy-0.dll`, and
+  Windows has no system libepoxy — so unlike the `.so`/`.dylib` artifacts this
+  one is not loadable from the host alone. The epoxy it needs is already in that
+  bundle (GTK4 links it), which every Windows consumer has anyway because it is
+  how [`@gjsify/node-gi`](../../node-gi/node-gi) resolves `gi://` at all. It is
+  deliberately not duplicated here: two libepoxy images in one address space is
+  a worse failure than the one it would solve.
+- **A real OpenGL ICD.** GTK4 rejects the GDI generic OpenGL 1.1 that Windows
+  falls back to, and the GTK bundle ships no GL implementation of its own
+  (`epoxy-0.dll` is the *dispatch* layer — it resolves nothing by itself). On a
+  machine with vendor graphics drivers this is already true; on a GPU-less host
+  (VM, RDP session, CI) install [Mesa for Windows](https://github.com/pal1000/mesa-dist-win)
+  and register it system-wide (`systemwidedeploy.cmd 1`). Without one,
+  `Gdk.Display.create_gl_context()` fails with *"No GL implementation is
+  available"* and the window paints that string instead of your scene — a
+  `Gtk.GLArea` failure, not a `gi://Gwebgl` one.
 
 Use the gjsify CLI to run your app — it automatically sets `LD_LIBRARY_PATH` and
 `GI_TYPELIB_PATH` so GJS can find the native library:
@@ -133,7 +152,7 @@ consumer installs only the artifact that fits its platform.
 | `linux-arm64` | ✅ | native runner |
 | `linux-ppc64`, `linux-s390x`, `linux-riscv64` | ✅ | QEMU emulation |
 | `darwin-arm64` / `darwin-x64` | ✅ `libgwebgl.dylib` + `Gwebgl-0.1.typelib` | native runner — **WebGL2 via a shader-dialect rewrite, see below** |
-| Windows | ❌ | — no Vala/GI bridge in this repo targets Windows |
+| `win32-x64` | ✅ `gwebgl.dll` + `Gwebgl-0.1.typelib` | **two jobs** — valac does not run on Windows, so a Linux runner emits the C + GIR and a `windows-latest` runner compiles them with MSVC against gvsbuild's GTK4. Needs a GL ICD and the GTK bundle at run time, [see above](#running-gjs-apps-that-use-this-package) |
 
 **macOS renders, WebGL1 and WebGL2.** Measured on macOS 15.7.8 / x86_64 with gtk 4.22 and
 libepoxy 1.5.10: `Gtk.GLArea` realizes a `GdkMacosGLContext`, and this bridge draws real
@@ -163,8 +182,14 @@ platform, not from the bridge:
   eleven separately probed edge constructs all compile on GLSL 4.10 with just that
   substitution. Measured end to end on macOS 15.7.9 / GL 4.1 core: compiles, links, draws,
   and `readPixels` returns the shader's colour. `#version 100` is left byte-for-byte alone,
-  and a context that already speaks GLSL ES 3.00 — Mesa's `4.6 (Compatibility Profile)` on
-  win32, GLES anywhere — is not rewritten at all.
+  and a context that already speaks GLSL ES 3.00 — GLES anywhere, or any desktop context
+  with `ARB_ES3_compatibility` — is not rewritten at all.
+
+  **The same rewrite applies on Windows, which is not what this file used to predict.** Mesa
+  on win32 advertises `4.6 (Compatibility Profile)`, so the guess was that win32 would take
+  the untouched path; measured on the win11-gjsify VM it does not, because GDK asks for a
+  CORE profile. `is_legacy` is false there, and the dialect decision goes exactly as it does
+  on macOS.
 
   Of the 219 GL entry points the library references, exactly two are absent from Apple's
   `OpenGL.framework` (`glInvalidateFramebuffer`, `glInvalidateSubFramebuffer`, both GL 4.3);

package/lib/esm/context/drawing.js

@@ -1 +1 @@
-import"../_virtual/_rolldown/runtime.js";import{Uint8ArrayToVariant as e,arrayToUint8Array as t,typeSize as n,vertexCount as r}from"../utils.js";const i={drawArrays(e=0,t=0,n=0){if(t<0||n<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let i=r(this,e,n);if(i<0){this.setError(this.INVALID_ENUM);return}if(!this._framebufferOk()||n===0)return;let a=t;n>0&&(a=n+t-1>>>0),this._checkVertexAttribState(a)&&this._gl.drawArrays(e,t,i)},drawElements(e=0,t=0,n=0,r=0){if(t<0||r<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let i=this._vertexObjectState._elementArrayBufferBinding;if(!i){this.setError(this.INVALID_OPERATION);return}let a=null,o=r;if(n===this.UNSIGNED_SHORT){if(o%2){this.setError(this.INVALID_OPERATION);return}o>>=1,a=new Uint16Array(i._elements.buffer)}else if(this._extensions.oes_element_index_uint&&n===this.UNSIGNED_INT){if(o%4){this.setError(this.INVALID_OPERATION);return}o>>=2,a=new Uint32Array(i._elements.buffer)}else if(n===this.UNSIGNED_BYTE)a=i._elements;else{this.setError(this.INVALID_ENUM);return}let s=t;switch(e){case this.TRIANGLES:t%3&&(s-=t%3);break;case this.LINES:t%2&&(s-=t%2);break;case this.POINTS:break;case this.LINE_LOOP:case this.LINE_STRIP:if(t<2){this.setError(this.INVALID_OPERATION);return}break;case this.TRIANGLE_FAN:case this.TRIANGLE_STRIP:if(t<3){this.setError(this.INVALID_OPERATION);return}break;default:this.setError(this.INVALID_ENUM);return}if(!this._framebufferOk())return;if(t===0){this._checkVertexAttribState(0);return}if(t+o>>>0>a.length){this.setError(this.INVALID_OPERATION);return}let c=-1;for(let e=o;e<o+t;++e)c=Math.max(c,a[e]);if(c<0){this._checkVertexAttribState(0);return}this._checkVertexAttribState(c)&&s>0&&this._gl.drawElements(e,s,n,r)},viewport(e,t,n,r){this._viewport[0]=e|0,this._viewport[1]=t|0,this._viewport[2]=n|0,this._viewport[3]=r|0,this._gl.viewport(e,t,n,r)},scissor(e,t,n,r){this._scissorBox[0]=e|0,this._scissorBox[1]=t|0,this._scissorBox[2]=n|0,this._scissorBox[3]=r|0,this._gl.scissor(e|0,t|0,n|0,r|0)},readPixels(n=0,r=0,i=0,a=0,o=0,s=0,c){if(!c)return;if(!(this._extensions.oes_texture_float&&s===this.FLOAT&&o===this.RGBA)){if(o===this.RGB||o===this.ALPHA||s!==this.UNSIGNED_BYTE){this.setError(this.INVALID_OPERATION);return}else if(o!==this.RGBA){this.setError(this.INVALID_ENUM);return}else if(i<0||a<0||!(c instanceof Uint8Array)){this.setError(this.INVALID_VALUE);return}}if(!this._framebufferOk()){console.error(`framebuffer is not okay!`);return}let l=i*4;l%this._packAlignment!==0&&(l+=this._packAlignment-l%this._packAlignment);let u=l*(a-1)+i*4;if(u<=0)return;if((c.length||c.byteLength||0)<u){this.setError(this.INVALID_VALUE);return}let d=this.drawingBufferWidth,f=this.drawingBufferHeight;this._activeFramebuffer&&(d=this._activeFramebuffer._width,f=this._activeFramebuffer._height);let p=t(c);if(n>=d||n+i<=0||r>=f||r+a<=0)for(let e=0;e<p.length;++e)p[e]=0;else if(n<0||n+i>d||r<0||r+a>f){for(let e=0;e<p.length;++e)p[e]=0;let t=n,c=i;n<0&&(c+=n,t=0),t+i>d&&(c=d-t);let u=r,m=a;r<0&&(m+=r,u=0),u+a>f&&(m=f-u);let h=c*4;if(h%this._packAlignment!==0&&(h+=this._packAlignment-h%this._packAlignment),c>0&&m>0){let i=new Uint8Array(h*m),a=this._gl.readPixels(t,u,c,m,o,s,e(i)),d=a&&a.length>0?a:i,f=4*(t-n)+(u-r)*l;for(let e=0;e<m;++e)for(let t=0;t<c;++t)for(let n=0;n<4;++n)p[f+e*l+4*t+n]=d[e*h+4*t+n]}}else{let t=this._gl.readPixels(n,r,i,a,o,s,e(p));t&&t.length>0&&p.set(t)}},enableVertexAttribArray(e){if(e<0||e>=this._vertexObjectState._attribs.length){this.setError(this.INVALID_VALUE);return}this._gl.enableVertexAttribArray(e),this._vertexObjectState._attribs[e]._isPointer=!0},disableVertexAttribArray(e=0){if(e<0||e>=this._vertexObjectState._attribs.length){this.setError(this.INVALID_VALUE);return}this._gl.disableVertexAttribArray(e),this._vertexObjectState._attribs[e]._isPointer=!1},vertexAttrib1f(e,t){if(e|=0,!this._checkVertexIndex(e))return;let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[1]=n[2]=0,n[0]=t,this._gl.vertexAttrib1f(e|0,+t)},vertexAttrib1fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<1){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[2]=0,n[1]=0,n[0]=t[0],this._gl.vertexAttrib1f(e|0,+t[0])},vertexAttrib2f(e,t,n){if(e|=0,!this._checkVertexIndex(e))return;let r=this._vertexGlobalState._attribs[e]._data;r[3]=1,r[2]=0,r[1]=n,r[0]=t,this._gl.vertexAttrib2f(e|0,+t,+n)},vertexAttrib2fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<2){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[2]=0,n[1]=t[1],n[0]=t[0],this._gl.vertexAttrib2f(e|0,+t[0],+t[1])},vertexAttrib3f(e,t,n,r){if(e|=0,!this._checkVertexIndex(e))return;let i=this._vertexGlobalState._attribs[e]._data;i[3]=1,i[2]=r,i[1]=n,i[0]=t,this._gl.vertexAttrib3f(e|0,+t,+n,+r)},vertexAttrib3fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<3){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[2]=t[2],n[1]=t[1],n[0]=t[0],this._gl.vertexAttrib3f(e|0,+t[0],+t[1],+t[2])},vertexAttrib4f(e=0,t,n,r,i){if(!this._checkVertexIndex(e))return;let a=this._vertexGlobalState._attribs[e]._data;a[3]=i,a[2]=r,a[1]=n,a[0]=t,this._gl.vertexAttrib4f(e|0,+t,+n,+r,+i)},vertexAttrib4fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<4){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=t[3],n[2]=t[2],n[1]=t[1],n[0]=t[0],this._gl.vertexAttrib4f(e|0,+t[0],+t[1],+t[2],+t[3])},vertexAttribPointer(e=0,t=0,r=0,i=!1,a=0,o=0){if(a<0||o<0){this.setError(this.INVALID_VALUE);return}if(a<0||o<0||e<0||e>=this._vertexObjectState._attribs.length||!(t===1||t===2||t===3||t===4)){this.setError(this.INVALID_VALUE);return}if(this._vertexGlobalState._arrayBufferBinding===null){this.setError(this.INVALID_OPERATION);return}let s=n(this,r);if(s===0||r===this.INT||r===this.UNSIGNED_INT){this.setError(this.INVALID_ENUM);return}if(a>255||a<0){this.setError(this.INVALID_VALUE);return}if(a%s!==0||o%s!==0){this.setError(this.INVALID_OPERATION);return}this._gl.vertexAttribPointer(e,t,r,i,a,o),this._vertexObjectState.setVertexAttribPointer(this._vertexGlobalState._arrayBufferBinding,e,t*s,o,a||t*s,r,i,a,t)},getVertexAttrib(e=0,t=0){if(e<0||e>=this._vertexObjectState._attribs.length)return this.setError(this.INVALID_VALUE),null;let n=this._vertexObjectState._attribs[e],r=this._vertexGlobalState._attribs[e]._data,i=this._extensions.angle_instanced_arrays;if(i&&t===i.VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE)return n._divisor;switch(t){case this.VERTEX_ATTRIB_ARRAY_BUFFER_BINDING:return n._pointerBuffer;case this.VERTEX_ATTRIB_ARRAY_ENABLED:return n._isPointer;case this.VERTEX_ATTRIB_ARRAY_SIZE:return n._inputSize;case this.VERTEX_ATTRIB_ARRAY_STRIDE:return n._inputStride;case this.VERTEX_ATTRIB_ARRAY_TYPE:return n._pointerType;case this.VERTEX_ATTRIB_ARRAY_NORMALIZED:return n._pointerNormal;case this.CURRENT_VERTEX_ATTRIB:return new Float32Array(r);default:return this.setError(this.INVALID_ENUM),null}},getVertexAttribOffset(e=0,t=0){return e<0||e>=this._vertexObjectState._attribs.length?(this.setError(this.INVALID_VALUE),-1):t===this.VERTEX_ATTRIB_ARRAY_POINTER?this._vertexObjectState._attribs[e]._pointerOffset:(this.setError(this.INVALID_ENUM),-1)},_checkVertexAttribState(e){let t=this._activeProgram;if(!t)return this.setError(this.INVALID_OPERATION),!1;let n=this._vertexObjectState._attribs;for(let r=0;r<n.length;++r){let i=n[r];if(i._isPointer){let n=i._pointerBuffer;if(!n)return this.setError(this.INVALID_OPERATION),!1;if(t._attributes.indexOf(r)>=0){let t=0;if(t=i._divisor?i._pointerSize+i._pointerOffset:i._pointerStride*e+i._pointerSize+i._pointerOffset,t>n._size)return this.setError(this.INVALID_OPERATION),!1}}}return!0},_checkVertexIndex(e){return e<0||e>=this._vertexObjectState._attribs.length?(this.setError(this.INVALID_VALUE),!1):!0}};function installDrawingMethods(e){Object.assign(e,i)}export{installDrawingMethods};
+import"../_virtual/_rolldown/runtime.js";import{Uint8ArrayToVariant as e,arrayToUint8Array as t,typeSize as n,vertexCount as r}from"../utils.js";const i={drawArrays(e=0,t=0,n=0){if(t<0||n<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let i=r(this,e,n);if(i<0){this.setError(this.INVALID_ENUM);return}if(!this._framebufferOk()||n===0)return;let a=t;n>0&&(a=n+t-1>>>0),this._checkVertexAttribState(a)&&this._gl.drawArrays(e,t,i)},drawElements(e=0,t=0,n=0,r=0){if(t<0||r<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let i=this._vertexObjectState._elementArrayBufferBinding;if(!i){this.setError(this.INVALID_OPERATION);return}let a=null,o=r;if(n===this.UNSIGNED_SHORT){if(o%2){this.setError(this.INVALID_OPERATION);return}o>>=1,a=new Uint16Array(i._elements.buffer)}else if(this._extensions.oes_element_index_uint&&n===this.UNSIGNED_INT){if(o%4){this.setError(this.INVALID_OPERATION);return}o>>=2,a=new Uint32Array(i._elements.buffer)}else if(n===this.UNSIGNED_BYTE)a=i._elements;else{this.setError(this.INVALID_ENUM);return}let s=t;switch(e){case this.TRIANGLES:t%3&&(s-=t%3);break;case this.LINES:t%2&&(s-=t%2);break;case this.POINTS:break;case this.LINE_LOOP:case this.LINE_STRIP:if(t<2){this.setError(this.INVALID_OPERATION);return}break;case this.TRIANGLE_FAN:case this.TRIANGLE_STRIP:if(t<3){this.setError(this.INVALID_OPERATION);return}break;default:this.setError(this.INVALID_ENUM);return}if(!this._framebufferOk())return;if(t===0){this._checkVertexAttribState(0);return}if(t+o>>>0>a.length){this.setError(this.INVALID_OPERATION);return}let c=-1;for(let e=o;e<o+t;++e)c=Math.max(c,a[e]);if(c<0){this._checkVertexAttribState(0);return}this._checkVertexAttribState(c)&&s>0&&this._gl.drawElements(e,s,n,r)},viewport(e,t,n,r){this._viewport[0]=e|0,this._viewport[1]=t|0,this._viewport[2]=n|0,this._viewport[3]=r|0,this._gl.viewport(e,t,n,r)},scissor(e,t,n,r){this._scissorBox[0]=e|0,this._scissorBox[1]=t|0,this._scissorBox[2]=n|0,this._scissorBox[3]=r|0,this._gl.scissor(e|0,t|0,n|0,r|0)},readPixels(n=0,r=0,i=0,a=0,o=0,s=0,c){if(!c)return;if(!(this._extensions.oes_texture_float&&s===this.FLOAT&&o===this.RGBA)){if(o===this.RGB||o===this.ALPHA||s!==this.UNSIGNED_BYTE){this.setError(this.INVALID_OPERATION);return}else if(o!==this.RGBA){this.setError(this.INVALID_ENUM);return}else if(i<0||a<0||!(c instanceof Uint8Array)){this.setError(this.INVALID_VALUE);return}}if(!this._framebufferOk()){console.error(`framebuffer is not okay!`);return}let l=i*4;l%this._packAlignment!==0&&(l+=this._packAlignment-l%this._packAlignment);let u=l*(a-1)+i*4;if(u<=0)return;if((c.length||c.byteLength||0)<u){this.setError(this.INVALID_VALUE);return}let d=this.drawingBufferWidth,f=this.drawingBufferHeight;this._activeFramebuffer&&(d=this._activeFramebuffer._width,f=this._activeFramebuffer._height);let p=t(c);if(n>=d||n+i<=0||r>=f||r+a<=0)for(let e=0;e<p.length;++e)p[e]=0;else if(n<0||n+i>d||r<0||r+a>f){for(let e=0;e<p.length;++e)p[e]=0;let t=n,c=i;n<0&&(c+=n,t=0),t+i>d&&(c=d-t);let u=r,m=a;r<0&&(m+=r,u=0),u+a>f&&(m=f-u);let h=c*4;if(h%this._packAlignment!==0&&(h+=this._packAlignment-h%this._packAlignment),c>0&&m>0){let i=new Uint8Array(h*m),a=this._gl.readPixels(t,u,c,m,o,s,e(i)),d=a&&a.length>0?a:i,f=4*(t-n)+(u-r)*l;for(let e=0;e<m;++e)for(let t=0;t<c;++t)for(let n=0;n<4;++n)p[f+e*l+4*t+n]=d[e*h+4*t+n]}}else{let t=this._gl.readPixels(n,r,i,a,o,s,e(p));t&&t.length>0&&p.set(t)}},enableVertexAttribArray(e){if(e<0||e>=this._vertexObjectState._attribs.length){this.setError(this.INVALID_VALUE);return}this._gl.enableVertexAttribArray(e),this._vertexObjectState._attribs[e]._isPointer=!0},disableVertexAttribArray(e=0){if(e<0||e>=this._vertexObjectState._attribs.length){this.setError(this.INVALID_VALUE);return}this._gl.disableVertexAttribArray(e),this._vertexObjectState._attribs[e]._isPointer=!1},vertexAttrib1f(e,t){if(e|=0,!this._checkVertexIndex(e))return;let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[1]=n[2]=0,n[0]=t,this._gl.vertexAttrib1f(e|0,+t)},vertexAttrib1fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<1){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[2]=0,n[1]=0,n[0]=t[0],this._gl.vertexAttrib1f(e|0,+t[0])},vertexAttrib2f(e,t,n){if(e|=0,!this._checkVertexIndex(e))return;let r=this._vertexGlobalState._attribs[e]._data;r[3]=1,r[2]=0,r[1]=n,r[0]=t,this._gl.vertexAttrib2f(e|0,+t,+n)},vertexAttrib2fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<2){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[2]=0,n[1]=t[1],n[0]=t[0],this._gl.vertexAttrib2f(e|0,+t[0],+t[1])},vertexAttrib3f(e,t,n,r){if(e|=0,!this._checkVertexIndex(e))return;let i=this._vertexGlobalState._attribs[e]._data;i[3]=1,i[2]=r,i[1]=n,i[0]=t,this._gl.vertexAttrib3f(e|0,+t,+n,+r)},vertexAttrib3fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<3){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=1,n[2]=t[2],n[1]=t[1],n[0]=t[0],this._gl.vertexAttrib3f(e|0,+t[0],+t[1],+t[2])},vertexAttrib4f(e=0,t,n,r,i){if(!this._checkVertexIndex(e))return;let a=this._vertexGlobalState._attribs[e]._data;a[3]=i,a[2]=r,a[1]=n,a[0]=t,this._gl.vertexAttrib4f(e|0,+t,+n,+r,+i)},vertexAttrib4fv(e,t){if(e|=0,!this._checkVertexIndex(e))return;if(typeof t!=`object`||!t||t.length<4){this.setError(this.INVALID_OPERATION);return}let n=this._vertexGlobalState._attribs[e]._data;n[3]=t[3],n[2]=t[2],n[1]=t[1],n[0]=t[0],this._gl.vertexAttrib4f(e|0,+t[0],+t[1],+t[2],+t[3])},vertexAttribPointer(e=0,t=0,r=0,i=!1,a=0,o=0){if(a<0||o<0){this.setError(this.INVALID_VALUE);return}if(a<0||o<0||e<0||e>=this._vertexObjectState._attribs.length||!(t===1||t===2||t===3||t===4)){this.setError(this.INVALID_VALUE);return}if(this._vertexGlobalState._arrayBufferBinding===null){this.setError(this.INVALID_OPERATION);return}let s=n(this,r);if(s===0||r===this.INT||r===this.UNSIGNED_INT){this.setError(this.INVALID_ENUM);return}if(a>255||a<0){this.setError(this.INVALID_VALUE);return}if(a%s!==0||o%s!==0){this.setError(this.INVALID_OPERATION);return}this._gl.vertexAttribPointer(e,t,r,i,a,o),this._vertexObjectState.setVertexAttribPointer(this._vertexGlobalState._arrayBufferBinding,e,t*s,o,a||t*s,r,i,a,t)},getVertexAttrib(e=0,t=0){if(e<0||e>=this._vertexObjectState._attribs.length)return this.setError(this.INVALID_VALUE),null;let n=this._vertexObjectState._attribs[e],r=this._vertexGlobalState._attribs[e]._data,i=this._extensions.angle_instanced_arrays;if(i&&t===i.VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE||t===this.VERTEX_ATTRIB_ARRAY_DIVISOR)return n._divisor;switch(t){case this.VERTEX_ATTRIB_ARRAY_BUFFER_BINDING:return n._pointerBuffer;case this.VERTEX_ATTRIB_ARRAY_ENABLED:return n._isPointer;case this.VERTEX_ATTRIB_ARRAY_SIZE:return n._inputSize;case this.VERTEX_ATTRIB_ARRAY_STRIDE:return n._inputStride;case this.VERTEX_ATTRIB_ARRAY_TYPE:return n._pointerType;case this.VERTEX_ATTRIB_ARRAY_NORMALIZED:return n._pointerNormal;case this.CURRENT_VERTEX_ATTRIB:return new Float32Array(r);default:return this.setError(this.INVALID_ENUM),null}},getVertexAttribOffset(e=0,t=0){return e<0||e>=this._vertexObjectState._attribs.length?(this.setError(this.INVALID_VALUE),-1):t===this.VERTEX_ATTRIB_ARRAY_POINTER?this._vertexObjectState._attribs[e]._pointerOffset:(this.setError(this.INVALID_ENUM),-1)},_checkVertexAttribState(e){let t=this._activeProgram;if(!t)return this.setError(this.INVALID_OPERATION),!1;let n=this._vertexObjectState._attribs;for(let r=0;r<n.length;++r){let i=n[r];if(i._isPointer){let n=i._pointerBuffer;if(!n)return this.setError(this.INVALID_OPERATION),!1;if(t._attributes.indexOf(r)>=0){let t=0;if(t=i._divisor?i._pointerSize+i._pointerOffset:i._pointerStride*e+i._pointerSize+i._pointerOffset,t>n._size)return this.setError(this.INVALID_OPERATION),!1}}}return!0},_checkVertexIndex(e){return e<0||e>=this._vertexObjectState._attribs.length?(this.setError(this.INVALID_VALUE),!1):!0}};function installDrawingMethods(e){Object.assign(e,i)}export{installDrawingMethods};

package/lib/esm/webgl2-context/instanced-and-framebuffer-ops.js

@@ -1 +1 @@
-import"../_virtual/_rolldown/runtime.js";import{vertexCount as e}from"../utils.js";function debugGlEnabled(){return globalThis.__GJSIFY_DEBUG_GL===!0}const t={drawArraysInstanced(t,n,r,i){if(n<0||r<0||i<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let a=e(this,t,r);if(a<0){this.setError(this.INVALID_ENUM);return}if(this._framebufferOk()&&!(r===0||i===0)&&this._checkVertexAttribState(r+n-1>>>0)){if(debugGlEnabled()){let e=this,t=e.__drawInstCount=(e.__drawInstCount|0)+1;(t<=5||t%100==0)&&console.log(`[WebGL] drawArraysInstanced #${t} count=${a} instances=${i} fbo=${this._activeFramebuffer?._??`_gtkFbo`}`)}this._native2.drawArraysInstanced(t,n,a,i)}},drawElementsInstanced(e,t,n,r,i){if(t<0||r<0||i<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let a=this._vertexObjectState._elementArrayBufferBinding;if(!a){this.setError(this.INVALID_OPERATION);return}let o=null,s=r;if(n===this.UNSIGNED_SHORT){if(s%2){this.setError(this.INVALID_OPERATION);return}s>>=1,o=new Uint16Array(a._elements.buffer)}else if(n===this.UNSIGNED_INT){if(s%4){this.setError(this.INVALID_OPERATION);return}s>>=2,o=new Uint32Array(a._elements.buffer)}else if(n===this.UNSIGNED_BYTE)o=a._elements;else{this.setError(this.INVALID_ENUM);return}let c=t;switch(e){case this.TRIANGLES:t%3&&(c-=t%3);break;case this.LINES:t%2&&(c-=t%2);break;case this.POINTS:break;case this.LINE_LOOP:case this.LINE_STRIP:if(t<2){this.setError(this.INVALID_OPERATION);return}break;case this.TRIANGLE_FAN:case this.TRIANGLE_STRIP:if(t<3){this.setError(this.INVALID_OPERATION);return}break;default:this.setError(this.INVALID_ENUM);return}if(!this._framebufferOk())return;if(c===0||i===0){this._checkVertexAttribState(0);return}if(c+s>>>0>o.length){this.setError(this.INVALID_OPERATION);return}let l=0;for(let e=s;e<s+c;++e)o[e]>l&&(l=o[e]);this._checkVertexAttribState(l)&&this._native2.drawElementsInstanced(e,c,n,r,i)},vertexAttribDivisor(e,t){this._native2.vertexAttribDivisor(e,t)},vertexAttribIPointer(e,t,n,r,i){this._native2.vertexAttribIPointer(e,t,n,r,i)},drawBuffers(e){let t=!1;for(let n=0;n<e.length;n++)if(e[n]===1029){t=!0;break}if(!t){this._native2.drawBuffers(e);return}this._native2.drawBuffers(e.map(e=>e===1029?this.COLOR_ATTACHMENT0:e))},drawRangeElements(e,t,n,r,i,a){if(r<0||a<0){this.setError(this.INVALID_VALUE);return}if(n<t){this.setError(this.INVALID_VALUE);return}this.drawElements(e,r,i,a)},blitFramebuffer(e,t,n,r,i,a,o,s,c,l){if(debugGlEnabled()){let e=this._gl.getError();e!==0&&console.log(`[WebGL] blitFramebuffer PRE-ERROR 0x${e.toString(16)}`)}if(this._native2.blitFramebuffer(e,t,n,r,i,a,o,s,c,l),debugGlEnabled()){let i=this._gl.getError(),a=this,o=a.__blitCount=(a.__blitCount|0)+1;o<=5&&console.log(`[WebGL] blitFramebuffer #${o} src=(${e},${t},${n},${r}) readFbo=${this._activeReadFramebuffer?._??`_gtkFbo`} err=${i===0?`OK`:`0x`+i.toString(16)}`)}},framebufferTextureLayer(e,t,n,r,i){this._native2.framebufferTextureLayer(e,t,n?n._:0,r,i)},invalidateFramebuffer(e,t){this._native2.invalidateFramebuffer(e,t)},invalidateSubFramebuffer(e,t,n,r,i,a){this._native2.invalidateSubFramebuffer(e,t,n,r,i,a)},readBuffer(e){this._native2.readBuffer(e)},renderbufferStorageMultisample(e,t,n,r,i){if(e!==this.RENDERBUFFER){this.setError(this.INVALID_ENUM);return}let a=this._activeRenderbuffer;if(!a){this.setError(this.INVALID_OPERATION);return}this._saveError(),this._native2.renderbufferStorageMultisample(e,t,n,r,i);let o=this.getError();this._restoreError(o),o===this.NO_ERROR&&(a._width=r,a._height=i,a._format=n)}};function installInstancedAndFramebufferOpsMethods(e){Object.assign(e,t)}export{installInstancedAndFramebufferOpsMethods};
+import"../_virtual/_rolldown/runtime.js";import{vertexCount as e}from"../utils.js";function debugGlEnabled(){return globalThis.__GJSIFY_DEBUG_GL===!0}const t={drawArraysInstanced(t,n,r,i){if(n<0||r<0||i<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let a=e(this,t,r);if(a<0){this.setError(this.INVALID_ENUM);return}if(this._framebufferOk()&&!(r===0||i===0)&&this._checkVertexAttribState(r+n-1>>>0)){if(debugGlEnabled()){let e=this,t=e.__drawInstCount=(e.__drawInstCount|0)+1;(t<=5||t%100==0)&&console.log(`[WebGL] drawArraysInstanced #${t} count=${a} instances=${i} fbo=${this._activeFramebuffer?._??`_gtkFbo`}`)}this._native2.drawArraysInstanced(t,n,a,i)}},drawElementsInstanced(e,t,n,r,i){if(t<0||r<0||i<0){this.setError(this.INVALID_VALUE);return}if(!this._checkStencilState())return;let a=this._vertexObjectState._elementArrayBufferBinding;if(!a){this.setError(this.INVALID_OPERATION);return}let o=null,s=r;if(n===this.UNSIGNED_SHORT){if(s%2){this.setError(this.INVALID_OPERATION);return}s>>=1,o=new Uint16Array(a._elements.buffer)}else if(n===this.UNSIGNED_INT){if(s%4){this.setError(this.INVALID_OPERATION);return}s>>=2,o=new Uint32Array(a._elements.buffer)}else if(n===this.UNSIGNED_BYTE)o=a._elements;else{this.setError(this.INVALID_ENUM);return}let c=t;switch(e){case this.TRIANGLES:t%3&&(c-=t%3);break;case this.LINES:t%2&&(c-=t%2);break;case this.POINTS:break;case this.LINE_LOOP:case this.LINE_STRIP:if(t<2){this.setError(this.INVALID_OPERATION);return}break;case this.TRIANGLE_FAN:case this.TRIANGLE_STRIP:if(t<3){this.setError(this.INVALID_OPERATION);return}break;default:this.setError(this.INVALID_ENUM);return}if(!this._framebufferOk())return;if(c===0||i===0){this._checkVertexAttribState(0);return}if(c+s>>>0>o.length){this.setError(this.INVALID_OPERATION);return}let l=0;for(let e=s;e<s+c;++e)o[e]>l&&(l=o[e]);this._checkVertexAttribState(l)&&this._native2.drawElementsInstanced(e,c,n,r,i)},vertexAttribDivisor(e,t){this._checkVertexIndex(e)&&(this._native2.vertexAttribDivisor(e,t),this._vertexObjectState._attribs[e]._divisor=t)},vertexAttribIPointer(e,t,n,r,i){this._native2.vertexAttribIPointer(e,t,n,r,i)},drawBuffers(e){let t=!1;for(let n=0;n<e.length;n++)if(e[n]===1029){t=!0;break}if(!t){this._native2.drawBuffers(e);return}this._native2.drawBuffers(e.map(e=>e===1029?this.COLOR_ATTACHMENT0:e))},drawRangeElements(e,t,n,r,i,a){if(r<0||a<0){this.setError(this.INVALID_VALUE);return}if(n<t){this.setError(this.INVALID_VALUE);return}this.drawElements(e,r,i,a)},blitFramebuffer(e,t,n,r,i,a,o,s,c,l){if(debugGlEnabled()){let e=this._gl.getError();e!==0&&console.log(`[WebGL] blitFramebuffer PRE-ERROR 0x${e.toString(16)}`)}if(this._native2.blitFramebuffer(e,t,n,r,i,a,o,s,c,l),debugGlEnabled()){let i=this._gl.getError(),a=this,o=a.__blitCount=(a.__blitCount|0)+1;o<=5&&console.log(`[WebGL] blitFramebuffer #${o} src=(${e},${t},${n},${r}) readFbo=${this._activeReadFramebuffer?._??`_gtkFbo`} err=${i===0?`OK`:`0x`+i.toString(16)}`)}},framebufferTextureLayer(e,t,n,r,i){this._native2.framebufferTextureLayer(e,t,n?n._:0,r,i)},invalidateFramebuffer(e,t){this._native2.invalidateFramebuffer(e,t)},invalidateSubFramebuffer(e,t,n,r,i,a){this._native2.invalidateSubFramebuffer(e,t,n,r,i,a)},readBuffer(e){this._native2.readBuffer(e)},renderbufferStorageMultisample(e,t,n,r,i){if(e!==this.RENDERBUFFER){this.setError(this.INVALID_ENUM);return}let a=this._activeRenderbuffer;if(!a){this.setError(this.INVALID_OPERATION);return}this._saveError(),this._native2.renderbufferStorageMultisample(e,t,n,r,i);let o=this.getError();this._restoreError(o),o===this.NO_ERROR&&(a._width=r,a._height=i,a._format=n)}};function installInstancedAndFramebufferOpsMethods(e){Object.assign(e,t)}export{installInstancedAndFramebufferOpsMethods};

package/lib/esm/webgl2.spec.js

@@ -1,4 +1,4 @@
-import{__name as e}from"./_virtual/_rolldown/runtime.js";import{TEXTURE_FS_300 as t,TEXTURE_VS_300 as n,destroyTestFBO as r,drawTriangle as i,makeProgram as a,makeTestFBO as o,makeTestFBOFloat as s,makeTestFBOWithDepthTexture as c,readPixel as l}from"./test-utils.js";import{beforeEach as u,describe as d,expect as f,it as p,on as m}from"@gjsify/unit";import{WebGL2RenderingContext as h,WebGLBridge as g}from"@gjsify/webgl";import _ from"@girs/glib-2.0";import v from"@girs/gtk-4.0";var y=e(async()=>{await m(`Display`,async()=>{v.init();let e,m,y=new _.MainLoop(null,!1),b=new v.Window({});b.set_default_size(200,200),e=new g,e.onReady((e,t)=>{m=e.getContext(`webgl2`),y.quit()}),b.set_child(e),b.present();let x=_.timeout_add(_.PRIORITY_DEFAULT,1e4,()=>(y.quit(),_.SOURCE_REMOVE));if(y.run(),_.source_remove(x),!m){console.warn(`WebGL2 context not available — skipping WebGL2 tests`),b.destroy();return}e.make_current(),await d(`WebGL2 context`,async()=>{u(async()=>{e.make_current()}),await p(`getContext("webgl2") returns a WebGL2RenderingContext`,async()=>{f(m).toBeInstanceOf(h)}),await p(`VERSION is "WebGL 2.0"`,async()=>{f(m.getParameter(m.VERSION)).toBe(`WebGL 2.0`)}),await p(`SHADING_LANGUAGE_VERSION is "WebGL GLSL ES 3.00"`,async()=>{f(m.getParameter(m.SHADING_LANGUAGE_VERSION)).toBe(`WebGL GLSL ES 3.00`)}),await p(`drawingBufferWidth and drawingBufferHeight are positive`,async()=>{f(m.drawingBufferWidth>0).toBeTruthy(),f(m.drawingBufferHeight>0).toBeTruthy()}),await p(`getError() returns NO_ERROR initially`,async()=>{f(m.getError()).toBe(m.NO_ERROR)})}),await d(`GLSL ES 3.00 compilation`,async()=>{u(async()=>{e.make_current()});let t=[`#version 300 es`,`in vec2 position;`,`void main() { gl_Position = vec4(position, 0.0, 1.0); }`].join(`
+import{__name as e}from"./_virtual/_rolldown/runtime.js";import{TEXTURE_FS_300 as t,TEXTURE_VS_300 as n,destroyTestFBO as r,drawTriangle as i,makeProgram as a,makeTestFBO as o,makeTestFBOFloat as s,makeTestFBOWithDepthTexture as c,readPixel as l}from"./test-utils.js";import{beforeEach as u,describe as d,expect as f,it as p,on as m}from"@gjsify/unit";import{WebGL2RenderingContext as h,WebGLBridge as g}from"@gjsify/webgl";import _ from"@girs/glib-2.0";import v from"@girs/gtk-4.0";var y=e(async()=>{await m(`Display`,async()=>{v.init();let e,m,y=new _.MainLoop(null,!1),b=new v.Window({});b.set_default_size(200,200),e=new g,e.onReady((e,t)=>{m=e.getContext(`webgl2`),y.quit()}),b.set_child(e),b.present();let x=_.timeout_add(_.PRIORITY_DEFAULT,1e4,()=>(y.quit(),_.SOURCE_REMOVE));if(y.run(),_.source_remove(x),!m){console.warn(`WebGL2 context not available — skipping WebGL2 tests`),b.destroy();return}e.make_current(),await d(`WebGL2 context`,async()=>{u(async()=>{e.make_current()}),await p(`getContext("webgl2") returns a WebGL2RenderingContext`,async()=>{f(m).toBeInstanceOf(h)}),await p(`VERSION is "WebGL 2.0"`,async()=>{f(m.getParameter(m.VERSION)).toBe(`WebGL 2.0`)}),await p(`SHADING_LANGUAGE_VERSION is "WebGL GLSL ES 3.00"`,async()=>{f(m.getParameter(m.SHADING_LANGUAGE_VERSION)).toBe(`WebGL GLSL ES 3.00`)}),await p(`drawingBufferWidth and drawingBufferHeight are positive`,async()=>{f(m.drawingBufferWidth>0).toBeTruthy(),f(m.drawingBufferHeight>0).toBeTruthy()}),await p(`getError() returns NO_ERROR initially`,async()=>{f(m.getError()).toBe(m.NO_ERROR)}),await p(`exposes every WebGL2 sized internal format constant`,async()=>{let e=`R8.R8_SNORM.R16F.R32F.R8UI.R8I.R16UI.R16I.R32UI.R32I.RG8.RG8_SNORM.RG16F.RG32F.RG8UI.RG8I.RG16UI.RG16I.RG32UI.RG32I.RGB8.SRGB8.RGB565.RGB8_SNORM.R11F_G11F_B10F.RGB9_E5.RGB16F.RGB32F.RGB8UI.RGB8I.RGB16UI.RGB16I.RGB32UI.RGB32I.RGBA8.SRGB8_ALPHA8.RGBA8_SNORM.RGB5_A1.RGBA4.RGB10_A2.RGBA16F.RGBA32F.RGBA8UI.RGBA8I.RGB10_A2UI.RGBA16UI.RGBA16I.RGBA32I.RGBA32UI.DEPTH_COMPONENT16.DEPTH_COMPONENT24.DEPTH_COMPONENT32F.DEPTH24_STENCIL8.DEPTH32F_STENCIL8`.split(`.`),t=m;f(e.filter(e=>typeof t[e]!=`number`).join(`, `)).toBe(``)}),await p(`allocates an RG16F texture with texStorage2D without error`,async()=>{let e=m.createTexture();m.bindTexture(m.TEXTURE_2D,e),m.texStorage2D(m.TEXTURE_2D,1,m.RG16F,16,16),f(m.getError()).toBe(m.NO_ERROR),m.texSubImage2D(m.TEXTURE_2D,0,0,0,16,16,m.RG,m.HALF_FLOAT,new Uint16Array(256*2)),f(m.getError()).toBe(m.NO_ERROR),m.bindTexture(m.TEXTURE_2D,null),m.deleteTexture(e)})}),await d(`GLSL ES 3.00 compilation`,async()=>{u(async()=>{e.make_current()});let t=[`#version 300 es`,`in vec2 position;`,`void main() { gl_Position = vec4(position, 0.0, 1.0); }`].join(`
 `),n=[`#version 300 es`,`precision mediump float;`,`out vec4 fragColor;`,`void main() { fragColor = vec4(0.0, 1.0, 0.0, 1.0); }`].join(`
 `);await p(`#version 300 es vertex shader compiles`,async()=>{let e=m.createShader(m.VERTEX_SHADER);m.shaderSource(e,t),m.compileShader(e),m.getShaderParameter(e,m.COMPILE_STATUS)||console.error(`VS300 log:`,m.getShaderInfoLog(e)),f(m.getShaderParameter(e,m.COMPILE_STATUS)).toBeTruthy(),m.deleteShader(e)}),await p(`#version 300 es fragment shader compiles`,async()=>{let e=m.createShader(m.FRAGMENT_SHADER);m.shaderSource(e,n),m.compileShader(e),m.getShaderParameter(e,m.COMPILE_STATUS)||console.error(`FS300 log:`,m.getShaderInfoLog(e)),f(m.getShaderParameter(e,m.COMPILE_STATUS)).toBeTruthy(),m.deleteShader(e)}),await p(`leaves the source alone on a context that speaks GLSL ES 3.00`,async()=>{let e=m.createShader(m.VERTEX_SHADER);m.shaderSource(e,t);let n=m.getShaderSource(e)??``,r=n.split(`
 `)[0].trim(),i=n.split(`
@@ -26,7 +26,9 @@ void main(){ gl_FragColor = textureCube(uCube, vec3(0.0)); }`]])await p(`treats
 `),t=[`#version 300 es`,`precision mediump float;`,`in vec4 vColor; out vec4 c;`,`void main() { c = vColor; }`].join(`
 `),n=a(m,e,t);f(m.getProgramParameter(n,m.LINK_STATUS)).toBeTruthy();let s=m.getUniformBlockIndex(n,`Params`);f(s).not.toBe(m.INVALID_INDEX),m.uniformBlockBinding(n,s,0),f(m.getError()).toBe(m.NO_ERROR);let c=m.createBuffer();m.bindBuffer(m.UNIFORM_BUFFER,c),m.bufferData(m.UNIFORM_BUFFER,new Float32Array([0,1,0,1]),m.STATIC_DRAW),m.bindBufferBase(m.UNIFORM_BUFFER,0,c);let u=o(m,4,4);m.useProgram(n),m.clearColor(0,0,0,1),m.clear(m.COLOR_BUFFER_BIT),i(m),f(m.getError()).toBe(m.NO_ERROR);let d=l(m,0,0);r(m,u),f(d[1]).toBe(255),m.deleteBuffer(c),m.deleteProgram(n)})}),await d(`instanced drawing`,async()=>{u(async()=>{e.make_current()}),await p(`drawArraysInstanced renders without error`,async()=>{let e=[`#version 300 es`,`in vec2 position;`,`void main() { gl_Position = vec4(position,0.0,1.0); }`].join(`
 `),t=[`#version 300 es`,`precision mediump float;`,`out vec4 c;`,`void main() { c = vec4(0.0,1.0,0.0,1.0); }`].join(`
-`),n=a(m,e,t);m.useProgram(n);let i=o(m,4,4),s=m.createBuffer();m.bindBuffer(m.ARRAY_BUFFER,s),m.bufferData(m.ARRAY_BUFFER,new Float32Array([-2,-2,-2,4,4,-2]),m.STREAM_DRAW),m.enableVertexAttribArray(0),m.vertexAttribPointer(0,2,m.FLOAT,!1,0,0),m.vertexAttribDivisor(0,0),m.clearColor(0,0,0,1),m.clear(m.COLOR_BUFFER_BIT),m.drawArraysInstanced(m.TRIANGLES,0,3,1),f(m.getError()).toBe(m.NO_ERROR);let c=l(m,0,0);r(m,i),f(c[1]).toBe(255),m.disableVertexAttribArray(0),m.deleteBuffer(s),m.deleteProgram(n)})}),await d(`drawBuffers (MRT)`,async()=>{u(async()=>{e.make_current()}),await p(`drawBuffers with 2 COLOR_ATTACHMENTs renders to both`,async()=>{let e=[`#version 300 es`,`in vec2 position;`,`void main() { gl_Position = vec4(position,0.0,1.0); }`].join(`
+`),n=a(m,e,t);m.useProgram(n);let i=o(m,4,4),s=m.createBuffer();m.bindBuffer(m.ARRAY_BUFFER,s),m.bufferData(m.ARRAY_BUFFER,new Float32Array([-2,-2,-2,4,4,-2]),m.STREAM_DRAW),m.enableVertexAttribArray(0),m.vertexAttribPointer(0,2,m.FLOAT,!1,0,0),m.vertexAttribDivisor(0,0),m.clearColor(0,0,0,1),m.clear(m.COLOR_BUFFER_BIT),m.drawArraysInstanced(m.TRIANGLES,0,3,1),f(m.getError()).toBe(m.NO_ERROR);let c=l(m,0,0);r(m,i),f(c[1]).toBe(255),m.disableVertexAttribArray(0),m.deleteBuffer(s),m.deleteProgram(n)}),await p(`records the divisor in the tracked attrib state`,async()=>{let e=m.createBuffer();m.bindBuffer(m.ARRAY_BUFFER,e),m.bufferData(m.ARRAY_BUFFER,new Float32Array(8),m.STATIC_DRAW),m.enableVertexAttribArray(1),m.vertexAttribPointer(1,4,m.FLOAT,!1,16,0),m.vertexAttribDivisor(1,1),f(m.getVertexAttrib(1,m.VERTEX_ATTRIB_ARRAY_DIVISOR)).toBe(1),m.vertexAttribDivisor(1,0),f(m.getVertexAttrib(1,m.VERTEX_ATTRIB_ARRAY_DIVISOR)).toBe(0),m.disableVertexAttribArray(1),m.deleteBuffer(e)}),await p(`draws instanced with an instance-sized mat4 attribute buffer`,async()=>{let e=[`#version 300 es`,`in vec2 position;`,`in vec4 offsetRow;`,`void main() { gl_Position = vec4(position + offsetRow.xy * 0.001, 0.0, 1.0); }`].join(`
+`),t=[`#version 300 es`,`precision mediump float;`,`out vec4 c;`,`void main() { c = vec4(0.0,1.0,0.0,1.0); }`].join(`
+`),n=a(m,e,t);m.useProgram(n);let i=m.getAttribLocation(n,`position`),s=m.getAttribLocation(n,`offsetRow`),c=o(m,4,4),u=m.createBuffer();m.bindBuffer(m.ARRAY_BUFFER,u),m.bufferData(m.ARRAY_BUFFER,new Float32Array([-2,-2,-2,4,4,-2]),m.STATIC_DRAW),m.enableVertexAttribArray(i),m.vertexAttribPointer(i,2,m.FLOAT,!1,0,0),m.vertexAttribDivisor(i,0);let d=m.createBuffer();m.bindBuffer(m.ARRAY_BUFFER,d),m.bufferData(m.ARRAY_BUFFER,new Float32Array(96),m.STATIC_DRAW),m.enableVertexAttribArray(s),m.vertexAttribPointer(s,4,m.FLOAT,!1,64,0),m.vertexAttribDivisor(s,1);let p=m.createBuffer();m.bindBuffer(m.ELEMENT_ARRAY_BUFFER,p),m.bufferData(m.ELEMENT_ARRAY_BUFFER,new Uint16Array([0,1,2]),m.STATIC_DRAW),m.clearColor(0,0,0,1),m.clear(m.COLOR_BUFFER_BIT),m.drawElementsInstanced(m.TRIANGLES,3,m.UNSIGNED_SHORT,0,6),f(m.getError()).toBe(m.NO_ERROR);let h=l(m,0,0);r(m,c),f(h[1]).toBe(255),m.disableVertexAttribArray(i),m.disableVertexAttribArray(s),m.vertexAttribDivisor(s,0),m.deleteBuffer(u),m.deleteBuffer(d),m.deleteBuffer(p),m.deleteProgram(n)})}),await d(`drawBuffers (MRT)`,async()=>{u(async()=>{e.make_current()}),await p(`drawBuffers with 2 COLOR_ATTACHMENTs renders to both`,async()=>{let e=[`#version 300 es`,`in vec2 position;`,`void main() { gl_Position = vec4(position,0.0,1.0); }`].join(`
 `),t=[`#version 300 es`,`precision mediump float;`,`layout(location=0) out vec4 c0;`,`layout(location=1) out vec4 c1;`,`void main() { c0 = vec4(1.0,0.0,0.0,1.0); c1 = vec4(0.0,0.0,1.0,1.0); }`].join(`
 `),n=a(m,e,t);f(m.getProgramParameter(n,m.LINK_STATUS)).toBeTruthy();let r=m.createFramebuffer();m.bindFramebuffer(m.FRAMEBUFFER,r);let o=m.createTexture();m.bindTexture(m.TEXTURE_2D,o),m.texImage2D(m.TEXTURE_2D,0,m.RGBA,4,4,0,m.RGBA,m.UNSIGNED_BYTE,null),m.framebufferTexture2D(m.FRAMEBUFFER,m.COLOR_ATTACHMENT0,m.TEXTURE_2D,o,0);let s=m.createTexture();m.bindTexture(m.TEXTURE_2D,s),m.texImage2D(m.TEXTURE_2D,0,m.RGBA,4,4,0,m.RGBA,m.UNSIGNED_BYTE,null),m.framebufferTexture2D(m.FRAMEBUFFER,m.COLOR_ATTACHMENT1,m.TEXTURE_2D,s,0);let c=m.checkFramebufferStatus(m.FRAMEBUFFER);if(c!==m.FRAMEBUFFER_COMPLETE){console.warn(`MRT framebuffer not complete:`,c),m.bindFramebuffer(m.FRAMEBUFFER,null),m.deleteFramebuffer(r),m.deleteTexture(o),m.deleteTexture(s),m.deleteProgram(n);return}m.drawBuffers([m.COLOR_ATTACHMENT0,m.COLOR_ATTACHMENT1]),m.viewport(0,0,4,4),m.clearColor(0,0,0,1),m.clear(m.COLOR_BUFFER_BIT),m.useProgram(n),i(m),f(m.getError()).toBe(m.NO_ERROR),m.readBuffer(m.COLOR_ATTACHMENT0);let u=l(m,0,0);f(u[0]).toBe(255),f(u[1]).toBe(0),m.readBuffer(m.COLOR_ATTACHMENT1);let d=l(m,0,0);f(d[0]).toBe(0),f(d[2]).toBe(255),m.bindFramebuffer(m.FRAMEBUFFER,null),m.deleteFramebuffer(r),m.deleteTexture(o),m.deleteTexture(s),m.deleteProgram(n)})}),await d(`3D texture`,async()=>{u(async()=>{e.make_current()}),await p(`createTexture + TEXTURE_3D binding works`,async()=>{let e=m.createTexture();f(e).not.toBeNull(),m.bindTexture(m.TEXTURE_3D,e),f(m.getError()).toBe(m.NO_ERROR),m.deleteTexture(e)}),await p(`texImage3D uploads a 2×2×2 RGBA texture without error`,async()=>{let e=m.createTexture();m.bindTexture(m.TEXTURE_3D,e),m.texParameteri(m.TEXTURE_3D,m.TEXTURE_MIN_FILTER,m.NEAREST),m.texParameteri(m.TEXTURE_3D,m.TEXTURE_MAG_FILTER,m.NEAREST),m.texParameteri(m.TEXTURE_3D,m.TEXTURE_WRAP_S,m.CLAMP_TO_EDGE),m.texParameteri(m.TEXTURE_3D,m.TEXTURE_WRAP_T,m.CLAMP_TO_EDGE),m.texParameteri(m.TEXTURE_3D,m.TEXTURE_WRAP_R,m.CLAMP_TO_EDGE);let t=new Uint8Array(32).fill(128);m.texImage3D(m.TEXTURE_3D,0,m.RGBA,2,2,2,0,m.RGBA,m.UNSIGNED_BYTE,t),f(m.getError()).toBe(m.NO_ERROR),m.deleteTexture(e)}),await p(`texStorage3D allocates storage without error`,async()=>{let e=m.createTexture();m.bindTexture(m.TEXTURE_3D,e),m.texStorage3D(m.TEXTURE_3D,1,m.RGBA8,4,4,4),f(m.getError()).toBe(m.NO_ERROR),m.deleteTexture(e)})}),await d(`transform feedback`,async()=>{u(async()=>{e.make_current()}),await p(`captures vertex shader output via transform feedback`,async()=>{let e=[`#version 300 es`,`in float inVal;`,`out float outVal;`,`void main() { outVal = inVal * 2.0; gl_Position = vec4(0.0); }`].join(`
 `),t=[`#version 300 es`,`precision mediump float;`,`out vec4 c;`,`void main() { c = vec4(0.0); }`].join(`

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

@@ -10,21 +10,16 @@ export declare class HTMLCanvasElement extends BaseHTMLCanvasElement {
     /**
      * DRAWING-BUFFER width, in DEVICE pixels (overrides the DOM attr-backed getter).
      *
-     * GtkGLArea's framebuffer is `allocation × scale-factor`, and the GL viewport
-     * is raw device pixels — GTK does NOT apply the surface scale to GL the way
-     * it silently pre-scales a Cairo context for `Gtk.DrawingArea`. So on a
-     * scale-factor-3 display (a phone) a viewport computed from the ALLOCATION
-     * covers the bottom-left ninth of the framebuffer and the rest stays at the
-     * clear colour. Measured on a OnePlus 6T / postmarketOS, GNOME Mobile,
-     * 1080×2340 at scale 3: the three.js teapot and the Excalibur game each
-     * rendered into a 120×218 corner of a 360×655-logical widget.
+     * GtkGLArea's framebuffer is `allocation × scale-factor` and the GL viewport is raw
+     * device pixels: GTK does NOT apply the surface scale to GL the way it silently
+     * pre-scales a Cairo context for `Gtk.DrawingArea`. A viewport computed from the
+     * ALLOCATION therefore covers the bottom-left ninth at scale 3 and the rest stays at
+     * the clear colour — measured on a OnePlus 6T (postmarketOS, 1080×2340 at scale 3),
+     * where the three.js teapot rendered into a 120×218 corner of a 360×655 widget.
      *
-     * Reporting device pixels here is also what the browser contract means by
-     * `canvas.width` — the drawing buffer, which is exactly what
-     * `WebGLRenderingContextBase.drawingBufferWidth` re-exports. CSS layout size
-     * stays logical (`clientWidth`/`offsetWidth` below), so a consumer that
-     * multiplies a layout size by `devicePixelRatio` (`installGlobals()` exposes
-     * the live scale factor) lands on the same number.
+     * Device pixels are also what the browser contract means by `canvas.width` (the
+     * drawing buffer). CSS layout size stays logical in `clientWidth`/`offsetWidth`, so a
+     * consumer multiplying a layout size by `devicePixelRatio` lands on this number.
      */
     get width(): number;
     set width(_width: number);
@@ -32,9 +27,9 @@ export declare class HTMLCanvasElement extends BaseHTMLCanvasElement {
     get height(): number;
     set height(_height: number);
     /**
-     * The widget's surface scale factor (1 on a standard display, 2–3 on HiDPI).
-     * Read live rather than cached: moving a window between monitors changes it,
-     * and GTK re-allocates the widget rather than recreating the canvas.
+     * The widget's surface scale factor. Read live rather than cached: moving a window
+     * between monitors changes it, and GTK re-allocates the widget rather than recreating
+     * the canvas.
      */
     get scaleFactor(): number;
     /** CSS layout width — the GTK allocation, in LOGICAL pixels. */
@@ -50,25 +45,22 @@ export declare class HTMLCanvasElement extends BaseHTMLCanvasElement {
     /**
      * A copy of this canvas is a PLAIN, widget-less one.
      *
-     * There is exactly one `Gtk.GLArea` and it stays with the original, so a
-     * clone cannot be GLArea-backed: the default `new this.constructor()` built
-     * one with `gtkGlArea === undefined`, and the first `width` read threw. That
-     * is not a hypothetical — it is how Excalibur switches renderers
-     * (`canvas.cloneNode(false)` → `replaceChild` → `getContext('2d')`), so the
-     * whole fallback died at the clone rather than degrading (gjsify#1107).
+     * There is one `Gtk.GLArea` and it stays with the original, so a clone cannot be
+     * GLArea-backed: the default `new this.constructor()` produced one with
+     * `gtkGlArea === undefined` and the first `width` read threw. That is how Excalibur
+     * switches renderers (`cloneNode(false)` → `replaceChild` → `getContext('2d')`), so
+     * the whole fallback died at the clone instead of degrading (gjsify#1107).
      *
-     * A detached canvas is also what a browser hands back: same size, blank
-     * bitmap, no context, not presented by anything. Dropping to the DOM base
-     * class gives precisely that, including a writable `width`/`height` — the
-     * overrides above deliberately ignore writes because GTK owns the widget's
+     * A detached canvas is also what a browser hands back: same size, blank bitmap, no
+     * context. The DOM base class gives exactly that, including a WRITABLE
+     * `width`/`height` — the overrides above ignore writes because GTK owns the widget's
      * size, and a clone has no widget to own it.
      */
     protected _createCloneTarget(): BaseHTMLCanvasElement;
     /**
-     * Returns a WebGL rendering context backed by the underlying Gtk.GLArea.
-     * 'webgl' and 'experimental-webgl' return a WebGLRenderingContext (WebGL 1.0).
-     * 'webgl2' returns a WebGL2RenderingContext (WebGL 2.0).
-     * Other context types emit a warning and return null.
+     * A WebGL context backed by the underlying Gtk.GLArea: 'webgl' and
+     * 'experimental-webgl' give WebGL 1.0, 'webgl2' gives WebGL 2.0, anything else falls
+     * through to the base class's context-factory registry.
      */
     getContext(contextId: string, options?: unknown): unknown;
 }

package/lib/types/software-renderer.d.ts

@@ -1,16 +1,11 @@
 /**
- * True when `renderer` names a GL implementation that rasterises on the CPU.
+ * True when the unmasked `RENDERER` string names a GL implementation that rasterises on
+ * the CPU.
  *
- * This is a DIAGNOSTIC, not a capability check, and deliberately so: a software
- * renderer is not by itself a reason to change behaviour. Measured on one
- * GPU-less macOS host, the same `Apple Software Renderer` draws a demand-driven
- * three.js scene and a flat-shaded full-screen quad without trouble (1.2 ms per
- * frame) while a continuously animating, fill-heavy 2D game needs 1.1 s for a
- * single textured full-screen draw. What separates them is the workload, not the
- * driver — so key any fallback on a MEASURED frame budget and use this only to
- * name the cause.
- *
- * @param renderer The unmasked `RENDERER` string, e.g. from
- *   `gl.getParameter(gl.getExtension('WEBGL_debug_renderer_info').UNMASKED_RENDERER_WEBGL)`.
+ * A DIAGNOSTIC, not a capability check: measured on one GPU-less macOS host, the same
+ * `Apple Software Renderer` drew a demand-driven three.js scene at 1.2 ms per frame while
+ * a fill-heavy animating 2D game needed 1.1 s for a single textured full-screen draw.
+ * The workload separates them, not the driver, so key any fallback on a MEASURED frame
+ * budget and use this only to name the cause.
  */
 export declare function isSoftwareRenderer(renderer: string | null | undefined): boolean;

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

@@ -6,22 +6,15 @@ import { HTMLCanvasElement as OurHTMLCanvasElement } from './html-canvas-element
 import { WebGLRenderingContext as OurWebGLRenderingContext } from './webgl-rendering-context.js';
 type WebGLReadyCallback = (canvas: globalThis.HTMLCanvasElement, gl: globalThis.WebGLRenderingContext) => void;
 /**
- * A `Gtk.GLArea` subclass that handles WebGL bootstrapping:
- * - Sets up OpenGL ES 3.2 context, depth buffer, stencil buffer
- * - Creates an `HTMLCanvasElement` wrapping the GLArea on first render
- * - Fires `onReady()` callbacks with (canvas, gl) once the context is available
- * - Provides `requestAnimationFrame()` backed by GTK frame clock (vsync) + render signal
- * - `installGlobals()` sets `globalThis.{requestAnimationFrame, cancelAnimationFrame,
- *   performance, WebGLRenderingContext, WebGL2RenderingContext}`
+ * A `Gtk.GLArea` subclass that negotiates the GL context, wraps it in an
+ * `HTMLCanvasElement` on first render, and drives `requestAnimationFrame` off the GTK
+ * frame clock.
  *
- * Usage:
+ * `installGlobals()` must run BEFORE the app code that expects the browser globals:
  * ```ts
  * const widget = new WebGLBridge();
- * widget.installGlobals();  // sets globalThis.requestAnimationFrame
- * widget.onReady((canvas, gl) => {
- *     gl.clearColor(0, 0, 0, 1);
- *     // requestAnimationFrame is now available globally
- * });
+ * widget.installGlobals();
+ * widget.onReady((canvas, gl) => { … });
  * window.set_child(widget);
  * ```
  */
@@ -46,95 +39,68 @@ export declare const WebGLBridge: {
         /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
         get canvas(): globalThis.HTMLCanvasElement | null;
         /**
-         * The GL implementation GDK negotiated, unmasked — `{vendor, renderer}`
-         * straight from `glGetString`, e.g. `Apple Software Renderer`. `null`
-         * until the context exists (i.e. before the first `onReady`).
+         * The GL implementation GDK negotiated, unmasked, straight from `glGetString`;
+         * `null` until the context exists.
          *
-         * Read it to REPORT what a host provides. It is not a capability check:
-         * a CPU rasteriser draws everything a GPU does, only slower, and how much
-         * slower depends entirely on the workload. Anything that switches
-         * renderers should key on a measured frame budget, not on this string.
+         * For REPORTING, not as a capability check: a CPU rasteriser draws everything a
+         * GPU does, only slower, and by how much depends on the workload. Anything that
+         * switches renderers should key on a measured frame budget, not on this string.
          */
         get rendererInfo(): {
             vendor: string;
             renderer: string;
         } | null;
-        /**
-         * Registers a callback to be called once the WebGL context is ready.
-         * If the context is already available, the callback fires synchronously.
-         */
+        /** Runs `cb` once the WebGL context is ready — synchronously if it already is. */
         onReady(cb: WebGLReadyCallback): void;
         /**
          * @deprecated Use `onReady()` instead.
          */
         onWebGLReady(cb: WebGLReadyCallback): void;
         /**
-         * Records the negotiated GL implementation and, when it rasterises on the
-         * CPU, says so ONCE on stderr.
+         * Records the negotiated GL implementation and, when it rasterises on the CPU,
+         * says so ONCE on stderr.
          *
-         * A GPU-less host is invisible from inside the app: context creation
-         * succeeds, every draw call succeeds, nothing rejects, and the only tell
-         * is a frame budget blown by three orders of magnitude — which presents as
-         * a window that sits there. Naming the renderer at the one place that
-         * knows it turns that into a line anyone can act on, for every consumer,
-         * without any of them asking.
+         * A GPU-less host is otherwise invisible from inside the app: the context is
+         * created, every draw call succeeds, and the only tell is a frame budget blown by
+         * three orders of magnitude, which presents as a window that just sits there.
          *
-         * Diagnostic only: it changes no behaviour, because a software renderer is
-         * fine for plenty of workloads (measured on one GPU-less macOS host: a
-         * demand-driven three.js scene and a flat-shaded full-screen quad both run
-         * comfortably on the same driver that needs 1.1 s for one textured
-         * full-screen draw in a 2D game).
+         * Diagnostic only, and deliberately changes no behaviour: a software renderer is
+         * fine for plenty of workloads. Measured on one GPU-less macOS host, a
+         * demand-driven three.js scene ran comfortably on the same driver that needed
+         * 1.1 s for a single textured full-screen draw in a 2D game.
          */
         _reportRenderer(gl: OurWebGLRenderingContext): void;
         /**
-         * Register a callback invoked whenever the GTK widget is resized.
-         * The callback fires alongside the native 'resize' GObject signal and
-         * after the DOM 'resize' event has been dispatched on the canvas.
-         * Canvas buffer dimensions are NOT automatically updated — consumers
-         * should set `canvas.width`/`canvas.height` themselves if desired.
+         * Runs `cb` on every GTK resize, after the DOM 'resize' event has been dispatched
+         * on the canvas. Canvas buffer dimensions are NOT updated for you: set
+         * `canvas.width`/`canvas.height` yourself if the drawing buffer must follow.
          */
         onResize(cb: (width: number, height: number) => void): void;
         /**
-         * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-         * Backed by a persistent GTK frame clock tick callback (vsync-synced) + a persistent GLArea
-         * render signal handler. Both are installed once at construction / first render respectively,
-         * eliminating per-frame GLib.Source allocation and GObject signal connect/disconnect overhead.
+         * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
          *
-         * Returns a monotonically-increasing handle; pass it to `cancelAnimationFrame(id)` to cancel
-         * the specific pending callback. A second `requestAnimationFrame` call before the first has
-         * fired replaces the pending callback (single-slot model — matching the existing rAF
-         * convention of "queue 1 callback per frame, the latest wins"); the older handle becomes
-         * stale and a `cancelAnimationFrame` with that handle is a no-op.
+         * SINGLE SLOT: a second call before the first has fired REPLACES the pending
+         * callback (latest wins), which makes the older handle stale and a
+         * `cancelAnimationFrame` with it a no-op.
          */
         requestAnimationFrame(cb: FrameRequestCallback): number;
         /**
-         * Cancels a previously-scheduled animation frame callback, matching the browser
-         * `cancelAnimationFrame` API. Only clears the pending callback when `id` matches
-         * the handle returned by the most recent `requestAnimationFrame` call — a stale
-         * handle (from a callback that already fired, or was replaced by a later
-         * `requestAnimationFrame`) is a no-op.
+         * Browser `cancelAnimationFrame`. Clears the pending callback only when `id` is
+         * the handle from the most recent `requestAnimationFrame`; a stale handle is a
+         * no-op.
          *
-         * Per-ID matching is load-bearing: without it any consumer that calls
-         * `cancelAnimationFrame` (e.g. Excalibur's `Engine.stop()`, called from a
-         * transient parent `unmap` in a responsive layout) would clear the loop's
-         * latest pending callback and freeze rendering until the next manual
-         * `requestAnimationFrame`. With it, the cancel only fires for the handle
-         * the caller actually owns.
+         * That matching is load-bearing: without it any stray cancel (Excalibur's
+         * `Engine.stop()`, fired from a transient parent `unmap` in a responsive layout)
+         * kills the loop's current callback and freezes rendering.
          */
         cancelAnimationFrame(id: number): void;
         /**
-         * Sets the browser globals this bridge owns — `requestAnimationFrame`,
-         * `cancelAnimationFrame`, `performance` and the two WebGL context
-         * constructors — so that browser-targeted code (e.g. Three.js) works
-         * unchanged on GJS.
+         * Sets the browser globals this bridge owns, so browser-targeted code (Three.js)
+         * runs unchanged on GJS.
          *
-         * `WebGLRenderingContext` / `WebGL2RenderingContext` are installed
-         * UNCONDITIONALLY here: per ADR 0012 rule 5 a bridge's `installGlobals()`
-         * and its `/register` install the same set, `installGlobals()` being the
-         * explicit imperative path (`@gjsify/webgl/register` keeps the
-         * if-undefined guard instead). They used to reach `globalThis` for free
-         * as a side effect of importing the `@gjsify/webgl` barrel; moving that
-         * write into `register.ts` must not shrink what this method does.
+         * The two context constructors are installed UNCONDITIONALLY: per ADR 0012 rule 5
+         * `installGlobals()` is the explicit imperative path and installs the same set as
+         * `@gjsify/webgl/register`, which keeps the if-undefined guard instead.
          */
         installGlobals(): void;
         get allowed_apis(): Gdk.GLAPI;
@@ -577,95 +543,68 @@ export declare const WebGLBridge: {
             /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
             get canvas(): globalThis.HTMLCanvasElement | null;
             /**
-             * The GL implementation GDK negotiated, unmasked — `{vendor, renderer}`
-             * straight from `glGetString`, e.g. `Apple Software Renderer`. `null`
-             * until the context exists (i.e. before the first `onReady`).
+             * The GL implementation GDK negotiated, unmasked, straight from `glGetString`;
+             * `null` until the context exists.
              *
-             * Read it to REPORT what a host provides. It is not a capability check:
-             * a CPU rasteriser draws everything a GPU does, only slower, and how much
-             * slower depends entirely on the workload. Anything that switches
-             * renderers should key on a measured frame budget, not on this string.
+             * For REPORTING, not as a capability check: a CPU rasteriser draws everything a
+             * GPU does, only slower, and by how much depends on the workload. Anything that
+             * switches renderers should key on a measured frame budget, not on this string.
              */
             get rendererInfo(): {
                 vendor: string;
                 renderer: string;
             } | null;
-            /**
-             * Registers a callback to be called once the WebGL context is ready.
-             * If the context is already available, the callback fires synchronously.
-             */
+            /** Runs `cb` once the WebGL context is ready — synchronously if it already is. */
             onReady(cb: WebGLReadyCallback): void;
             /**
              * @deprecated Use `onReady()` instead.
              */
             onWebGLReady(cb: WebGLReadyCallback): void;
             /**
-             * Records the negotiated GL implementation and, when it rasterises on the
-             * CPU, says so ONCE on stderr.
+             * Records the negotiated GL implementation and, when it rasterises on the CPU,
+             * says so ONCE on stderr.
              *
-             * A GPU-less host is invisible from inside the app: context creation
-             * succeeds, every draw call succeeds, nothing rejects, and the only tell
-             * is a frame budget blown by three orders of magnitude — which presents as
-             * a window that sits there. Naming the renderer at the one place that
-             * knows it turns that into a line anyone can act on, for every consumer,
-             * without any of them asking.
+             * A GPU-less host is otherwise invisible from inside the app: the context is
+             * created, every draw call succeeds, and the only tell is a frame budget blown by
+             * three orders of magnitude, which presents as a window that just sits there.
              *
-             * Diagnostic only: it changes no behaviour, because a software renderer is
-             * fine for plenty of workloads (measured on one GPU-less macOS host: a
-             * demand-driven three.js scene and a flat-shaded full-screen quad both run
-             * comfortably on the same driver that needs 1.1 s for one textured
-             * full-screen draw in a 2D game).
+             * Diagnostic only, and deliberately changes no behaviour: a software renderer is
+             * fine for plenty of workloads. Measured on one GPU-less macOS host, a
+             * demand-driven three.js scene ran comfortably on the same driver that needed
+             * 1.1 s for a single textured full-screen draw in a 2D game.
              */
             _reportRenderer(gl: OurWebGLRenderingContext): void;
             /**
-             * Register a callback invoked whenever the GTK widget is resized.
-             * The callback fires alongside the native 'resize' GObject signal and
-             * after the DOM 'resize' event has been dispatched on the canvas.
-             * Canvas buffer dimensions are NOT automatically updated — consumers
-             * should set `canvas.width`/`canvas.height` themselves if desired.
+             * Runs `cb` on every GTK resize, after the DOM 'resize' event has been dispatched
+             * on the canvas. Canvas buffer dimensions are NOT updated for you: set
+             * `canvas.width`/`canvas.height` yourself if the drawing buffer must follow.
              */
             onResize(cb: (width: number, height: number) => void): void;
             /**
-             * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-             * Backed by a persistent GTK frame clock tick callback (vsync-synced) + a persistent GLArea
-             * render signal handler. Both are installed once at construction / first render respectively,
-             * eliminating per-frame GLib.Source allocation and GObject signal connect/disconnect overhead.
+             * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
              *
-             * Returns a monotonically-increasing handle; pass it to `cancelAnimationFrame(id)` to cancel
-             * the specific pending callback. A second `requestAnimationFrame` call before the first has
-             * fired replaces the pending callback (single-slot model — matching the existing rAF
-             * convention of "queue 1 callback per frame, the latest wins"); the older handle becomes
-             * stale and a `cancelAnimationFrame` with that handle is a no-op.
+             * SINGLE SLOT: a second call before the first has fired REPLACES the pending
+             * callback (latest wins), which makes the older handle stale and a
+             * `cancelAnimationFrame` with it a no-op.
              */
             requestAnimationFrame(cb: FrameRequestCallback): number;
             /**
-             * Cancels a previously-scheduled animation frame callback, matching the browser
-             * `cancelAnimationFrame` API. Only clears the pending callback when `id` matches
-             * the handle returned by the most recent `requestAnimationFrame` call — a stale
-             * handle (from a callback that already fired, or was replaced by a later
-             * `requestAnimationFrame`) is a no-op.
+             * Browser `cancelAnimationFrame`. Clears the pending callback only when `id` is
+             * the handle from the most recent `requestAnimationFrame`; a stale handle is a
+             * no-op.
              *
-             * Per-ID matching is load-bearing: without it any consumer that calls
-             * `cancelAnimationFrame` (e.g. Excalibur's `Engine.stop()`, called from a
-             * transient parent `unmap` in a responsive layout) would clear the loop's
-             * latest pending callback and freeze rendering until the next manual
-             * `requestAnimationFrame`. With it, the cancel only fires for the handle
-             * the caller actually owns.
+             * That matching is load-bearing: without it any stray cancel (Excalibur's
+             * `Engine.stop()`, fired from a transient parent `unmap` in a responsive layout)
+             * kills the loop's current callback and freezes rendering.
              */
             cancelAnimationFrame(id: number): void;
             /**
-             * Sets the browser globals this bridge owns — `requestAnimationFrame`,
-             * `cancelAnimationFrame`, `performance` and the two WebGL context
-             * constructors — so that browser-targeted code (e.g. Three.js) works
-             * unchanged on GJS.
+             * Sets the browser globals this bridge owns, so browser-targeted code (Three.js)
+             * runs unchanged on GJS.
              *
-             * `WebGLRenderingContext` / `WebGL2RenderingContext` are installed
-             * UNCONDITIONALLY here: per ADR 0012 rule 5 a bridge's `installGlobals()`
-             * and its `/register` install the same set, `installGlobals()` being the
-             * explicit imperative path (`@gjsify/webgl/register` keeps the
-             * if-undefined guard instead). They used to reach `globalThis` for free
-             * as a side effect of importing the `@gjsify/webgl` barrel; moving that
-             * write into `register.ts` must not shrink what this method does.
+             * The two context constructors are installed UNCONDITIONALLY: per ADR 0012 rule 5
+             * `installGlobals()` is the explicit imperative path and installs the same set as
+             * `@gjsify/webgl/register`, which keeps the if-undefined guard instead.
              */
             installGlobals(): void;
             get allowed_apis(): Gdk.GLAPI;
@@ -1108,95 +1047,68 @@ export declare const WebGLBridge: {
                 /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
                 get canvas(): globalThis.HTMLCanvasElement | null;
                 /**
-                 * The GL implementation GDK negotiated, unmasked — `{vendor, renderer}`
-                 * straight from `glGetString`, e.g. `Apple Software Renderer`. `null`
-                 * until the context exists (i.e. before the first `onReady`).
+                 * The GL implementation GDK negotiated, unmasked, straight from `glGetString`;
+                 * `null` until the context exists.
                  *
-                 * Read it to REPORT what a host provides. It is not a capability check:
-                 * a CPU rasteriser draws everything a GPU does, only slower, and how much
-                 * slower depends entirely on the workload. Anything that switches
-                 * renderers should key on a measured frame budget, not on this string.
+                 * For REPORTING, not as a capability check: a CPU rasteriser draws everything a
+                 * GPU does, only slower, and by how much depends on the workload. Anything that
+                 * switches renderers should key on a measured frame budget, not on this string.
                  */
                 get rendererInfo(): {
                     vendor: string;
                     renderer: string;
                 } | null;
-                /**
-                 * Registers a callback to be called once the WebGL context is ready.
-                 * If the context is already available, the callback fires synchronously.
-                 */
+                /** Runs `cb` once the WebGL context is ready — synchronously if it already is. */
                 onReady(cb: WebGLReadyCallback): void;
                 /**
                  * @deprecated Use `onReady()` instead.
                  */
                 onWebGLReady(cb: WebGLReadyCallback): void;
                 /**
-                 * Records the negotiated GL implementation and, when it rasterises on the
-                 * CPU, says so ONCE on stderr.
+                 * Records the negotiated GL implementation and, when it rasterises on the CPU,
+                 * says so ONCE on stderr.
                  *
-                 * A GPU-less host is invisible from inside the app: context creation
-                 * succeeds, every draw call succeeds, nothing rejects, and the only tell
-                 * is a frame budget blown by three orders of magnitude — which presents as
-                 * a window that sits there. Naming the renderer at the one place that
-                 * knows it turns that into a line anyone can act on, for every consumer,
-                 * without any of them asking.
+                 * A GPU-less host is otherwise invisible from inside the app: the context is
+                 * created, every draw call succeeds, and the only tell is a frame budget blown by
+                 * three orders of magnitude, which presents as a window that just sits there.
                  *
-                 * Diagnostic only: it changes no behaviour, because a software renderer is
-                 * fine for plenty of workloads (measured on one GPU-less macOS host: a
-                 * demand-driven three.js scene and a flat-shaded full-screen quad both run
-                 * comfortably on the same driver that needs 1.1 s for one textured
-                 * full-screen draw in a 2D game).
+                 * Diagnostic only, and deliberately changes no behaviour: a software renderer is
+                 * fine for plenty of workloads. Measured on one GPU-less macOS host, a
+                 * demand-driven three.js scene ran comfortably on the same driver that needed
+                 * 1.1 s for a single textured full-screen draw in a 2D game.
                  */
                 _reportRenderer(gl: OurWebGLRenderingContext): void;
                 /**
-                 * Register a callback invoked whenever the GTK widget is resized.
-                 * The callback fires alongside the native 'resize' GObject signal and
-                 * after the DOM 'resize' event has been dispatched on the canvas.
-                 * Canvas buffer dimensions are NOT automatically updated — consumers
-                 * should set `canvas.width`/`canvas.height` themselves if desired.
+                 * Runs `cb` on every GTK resize, after the DOM 'resize' event has been dispatched
+                 * on the canvas. Canvas buffer dimensions are NOT updated for you: set
+                 * `canvas.width`/`canvas.height` yourself if the drawing buffer must follow.
                  */
                 onResize(cb: (width: number, height: number) => void): void;
                 /**
-                 * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-                 * Backed by a persistent GTK frame clock tick callback (vsync-synced) + a persistent GLArea
-                 * render signal handler. Both are installed once at construction / first render respectively,
-                 * eliminating per-frame GLib.Source allocation and GObject signal connect/disconnect overhead.
+                 * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
                  *
-                 * Returns a monotonically-increasing handle; pass it to `cancelAnimationFrame(id)` to cancel
-                 * the specific pending callback. A second `requestAnimationFrame` call before the first has
-                 * fired replaces the pending callback (single-slot model — matching the existing rAF
-                 * convention of "queue 1 callback per frame, the latest wins"); the older handle becomes
-                 * stale and a `cancelAnimationFrame` with that handle is a no-op.
+                 * SINGLE SLOT: a second call before the first has fired REPLACES the pending
+                 * callback (latest wins), which makes the older handle stale and a
+                 * `cancelAnimationFrame` with it a no-op.
                  */
                 requestAnimationFrame(cb: FrameRequestCallback): number;
                 /**
-                 * Cancels a previously-scheduled animation frame callback, matching the browser
-                 * `cancelAnimationFrame` API. Only clears the pending callback when `id` matches
-                 * the handle returned by the most recent `requestAnimationFrame` call — a stale
-                 * handle (from a callback that already fired, or was replaced by a later
-                 * `requestAnimationFrame`) is a no-op.
+                 * Browser `cancelAnimationFrame`. Clears the pending callback only when `id` is
+                 * the handle from the most recent `requestAnimationFrame`; a stale handle is a
+                 * no-op.
                  *
-                 * Per-ID matching is load-bearing: without it any consumer that calls
-                 * `cancelAnimationFrame` (e.g. Excalibur's `Engine.stop()`, called from a
-                 * transient parent `unmap` in a responsive layout) would clear the loop's
-                 * latest pending callback and freeze rendering until the next manual
-                 * `requestAnimationFrame`. With it, the cancel only fires for the handle
-                 * the caller actually owns.
+                 * That matching is load-bearing: without it any stray cancel (Excalibur's
+                 * `Engine.stop()`, fired from a transient parent `unmap` in a responsive layout)
+                 * kills the loop's current callback and freezes rendering.
                  */
                 cancelAnimationFrame(id: number): void;
                 /**
-                 * Sets the browser globals this bridge owns — `requestAnimationFrame`,
-                 * `cancelAnimationFrame`, `performance` and the two WebGL context
-                 * constructors — so that browser-targeted code (e.g. Three.js) works
-                 * unchanged on GJS.
+                 * Sets the browser globals this bridge owns, so browser-targeted code (Three.js)
+                 * runs unchanged on GJS.
                  *
-                 * `WebGLRenderingContext` / `WebGL2RenderingContext` are installed
-                 * UNCONDITIONALLY here: per ADR 0012 rule 5 a bridge's `installGlobals()`
-                 * and its `/register` install the same set, `installGlobals()` being the
-                 * explicit imperative path (`@gjsify/webgl/register` keeps the
-                 * if-undefined guard instead). They used to reach `globalThis` for free
-                 * as a side effect of importing the `@gjsify/webgl` barrel; moving that
-                 * write into `register.ts` must not shrink what this method does.
+                 * The two context constructors are installed UNCONDITIONALLY: per ADR 0012 rule 5
+                 * `installGlobals()` is the explicit imperative path and installs the same set as
+                 * `@gjsify/webgl/register`, which keeps the if-undefined guard instead.
                  */
                 installGlobals(): void;
                 get allowed_apis(): Gdk.GLAPI;
@@ -1639,95 +1551,68 @@ export declare const WebGLBridge: {
                 /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
                 get canvas(): globalThis.HTMLCanvasElement | null;
                 /**
-                 * The GL implementation GDK negotiated, unmasked — `{vendor, renderer}`
-                 * straight from `glGetString`, e.g. `Apple Software Renderer`. `null`
-                 * until the context exists (i.e. before the first `onReady`).
+                 * The GL implementation GDK negotiated, unmasked, straight from `glGetString`;
+                 * `null` until the context exists.
                  *
-                 * Read it to REPORT what a host provides. It is not a capability check:
-                 * a CPU rasteriser draws everything a GPU does, only slower, and how much
-                 * slower depends entirely on the workload. Anything that switches
-                 * renderers should key on a measured frame budget, not on this string.
+                 * For REPORTING, not as a capability check: a CPU rasteriser draws everything a
+                 * GPU does, only slower, and by how much depends on the workload. Anything that
+                 * switches renderers should key on a measured frame budget, not on this string.
                  */
                 get rendererInfo(): {
                     vendor: string;
                     renderer: string;
                 } | null;
-                /**
-                 * Registers a callback to be called once the WebGL context is ready.
-                 * If the context is already available, the callback fires synchronously.
-                 */
+                /** Runs `cb` once the WebGL context is ready — synchronously if it already is. */
                 onReady(cb: WebGLReadyCallback): void;
                 /**
                  * @deprecated Use `onReady()` instead.
                  */
                 onWebGLReady(cb: WebGLReadyCallback): void;
                 /**
-                 * Records the negotiated GL implementation and, when it rasterises on the
-                 * CPU, says so ONCE on stderr.
+                 * Records the negotiated GL implementation and, when it rasterises on the CPU,
+                 * says so ONCE on stderr.
                  *
-                 * A GPU-less host is invisible from inside the app: context creation
-                 * succeeds, every draw call succeeds, nothing rejects, and the only tell
-                 * is a frame budget blown by three orders of magnitude — which presents as
-                 * a window that sits there. Naming the renderer at the one place that
-                 * knows it turns that into a line anyone can act on, for every consumer,
-                 * without any of them asking.
+                 * A GPU-less host is otherwise invisible from inside the app: the context is
+                 * created, every draw call succeeds, and the only tell is a frame budget blown by
+                 * three orders of magnitude, which presents as a window that just sits there.
                  *
-                 * Diagnostic only: it changes no behaviour, because a software renderer is
-                 * fine for plenty of workloads (measured on one GPU-less macOS host: a
-                 * demand-driven three.js scene and a flat-shaded full-screen quad both run
-                 * comfortably on the same driver that needs 1.1 s for one textured
-                 * full-screen draw in a 2D game).
+                 * Diagnostic only, and deliberately changes no behaviour: a software renderer is
+                 * fine for plenty of workloads. Measured on one GPU-less macOS host, a
+                 * demand-driven three.js scene ran comfortably on the same driver that needed
+                 * 1.1 s for a single textured full-screen draw in a 2D game.
                  */
                 _reportRenderer(gl: OurWebGLRenderingContext): void;
                 /**
-                 * Register a callback invoked whenever the GTK widget is resized.
-                 * The callback fires alongside the native 'resize' GObject signal and
-                 * after the DOM 'resize' event has been dispatched on the canvas.
-                 * Canvas buffer dimensions are NOT automatically updated — consumers
-                 * should set `canvas.width`/`canvas.height` themselves if desired.
+                 * Runs `cb` on every GTK resize, after the DOM 'resize' event has been dispatched
+                 * on the canvas. Canvas buffer dimensions are NOT updated for you: set
+                 * `canvas.width`/`canvas.height` yourself if the drawing buffer must follow.
                  */
                 onResize(cb: (width: number, height: number) => void): void;
                 /**
-                 * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-                 * Backed by a persistent GTK frame clock tick callback (vsync-synced) + a persistent GLArea
-                 * render signal handler. Both are installed once at construction / first render respectively,
-                 * eliminating per-frame GLib.Source allocation and GObject signal connect/disconnect overhead.
+                 * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
                  *
-                 * Returns a monotonically-increasing handle; pass it to `cancelAnimationFrame(id)` to cancel
-                 * the specific pending callback. A second `requestAnimationFrame` call before the first has
-                 * fired replaces the pending callback (single-slot model — matching the existing rAF
-                 * convention of "queue 1 callback per frame, the latest wins"); the older handle becomes
-                 * stale and a `cancelAnimationFrame` with that handle is a no-op.
+                 * SINGLE SLOT: a second call before the first has fired REPLACES the pending
+                 * callback (latest wins), which makes the older handle stale and a
+                 * `cancelAnimationFrame` with it a no-op.
                  */
                 requestAnimationFrame(cb: FrameRequestCallback): number;
                 /**
-                 * Cancels a previously-scheduled animation frame callback, matching the browser
-                 * `cancelAnimationFrame` API. Only clears the pending callback when `id` matches
-                 * the handle returned by the most recent `requestAnimationFrame` call — a stale
-                 * handle (from a callback that already fired, or was replaced by a later
-                 * `requestAnimationFrame`) is a no-op.
+                 * Browser `cancelAnimationFrame`. Clears the pending callback only when `id` is
+                 * the handle from the most recent `requestAnimationFrame`; a stale handle is a
+                 * no-op.
                  *
-                 * Per-ID matching is load-bearing: without it any consumer that calls
-                 * `cancelAnimationFrame` (e.g. Excalibur's `Engine.stop()`, called from a
-                 * transient parent `unmap` in a responsive layout) would clear the loop's
-                 * latest pending callback and freeze rendering until the next manual
-                 * `requestAnimationFrame`. With it, the cancel only fires for the handle
-                 * the caller actually owns.
+                 * That matching is load-bearing: without it any stray cancel (Excalibur's
+                 * `Engine.stop()`, fired from a transient parent `unmap` in a responsive layout)
+                 * kills the loop's current callback and freezes rendering.
                  */
                 cancelAnimationFrame(id: number): void;
                 /**
-                 * Sets the browser globals this bridge owns — `requestAnimationFrame`,
-                 * `cancelAnimationFrame`, `performance` and the two WebGL context
-                 * constructors — so that browser-targeted code (e.g. Three.js) works
-                 * unchanged on GJS.
+                 * Sets the browser globals this bridge owns, so browser-targeted code (Three.js)
+                 * runs unchanged on GJS.
                  *
-                 * `WebGLRenderingContext` / `WebGL2RenderingContext` are installed
-                 * UNCONDITIONALLY here: per ADR 0012 rule 5 a bridge's `installGlobals()`
-                 * and its `/register` install the same set, `installGlobals()` being the
-                 * explicit imperative path (`@gjsify/webgl/register` keeps the
-                 * if-undefined guard instead). They used to reach `globalThis` for free
-                 * as a side effect of importing the `@gjsify/webgl` barrel; moving that
-                 * write into `register.ts` must not shrink what this method does.
+                 * The two context constructors are installed UNCONDITIONALLY: per ADR 0012 rule 5
+                 * `installGlobals()` is the explicit imperative path and installs the same set as
+                 * `@gjsify/webgl/register`, which keeps the if-undefined guard instead.
                  */
                 installGlobals(): void;
                 get allowed_apis(): Gdk.GLAPI;
@@ -2170,95 +2055,68 @@ export declare const WebGLBridge: {
             /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
             get canvas(): globalThis.HTMLCanvasElement | null;
             /**
-             * The GL implementation GDK negotiated, unmasked — `{vendor, renderer}`
-             * straight from `glGetString`, e.g. `Apple Software Renderer`. `null`
-             * until the context exists (i.e. before the first `onReady`).
+             * The GL implementation GDK negotiated, unmasked, straight from `glGetString`;
+             * `null` until the context exists.
              *
-             * Read it to REPORT what a host provides. It is not a capability check:
-             * a CPU rasteriser draws everything a GPU does, only slower, and how much
-             * slower depends entirely on the workload. Anything that switches
-             * renderers should key on a measured frame budget, not on this string.
+             * For REPORTING, not as a capability check: a CPU rasteriser draws everything a
+             * GPU does, only slower, and by how much depends on the workload. Anything that
+             * switches renderers should key on a measured frame budget, not on this string.
              */
             get rendererInfo(): {
                 vendor: string;
                 renderer: string;
             } | null;
-            /**
-             * Registers a callback to be called once the WebGL context is ready.
-             * If the context is already available, the callback fires synchronously.
-             */
+            /** Runs `cb` once the WebGL context is ready — synchronously if it already is. */
             onReady(cb: WebGLReadyCallback): void;
             /**
              * @deprecated Use `onReady()` instead.
              */
             onWebGLReady(cb: WebGLReadyCallback): void;
             /**
-             * Records the negotiated GL implementation and, when it rasterises on the
-             * CPU, says so ONCE on stderr.
+             * Records the negotiated GL implementation and, when it rasterises on the CPU,
+             * says so ONCE on stderr.
              *
-             * A GPU-less host is invisible from inside the app: context creation
-             * succeeds, every draw call succeeds, nothing rejects, and the only tell
-             * is a frame budget blown by three orders of magnitude — which presents as
-             * a window that sits there. Naming the renderer at the one place that
-             * knows it turns that into a line anyone can act on, for every consumer,
-             * without any of them asking.
+             * A GPU-less host is otherwise invisible from inside the app: the context is
+             * created, every draw call succeeds, and the only tell is a frame budget blown by
+             * three orders of magnitude, which presents as a window that just sits there.
              *
-             * Diagnostic only: it changes no behaviour, because a software renderer is
-             * fine for plenty of workloads (measured on one GPU-less macOS host: a
-             * demand-driven three.js scene and a flat-shaded full-screen quad both run
-             * comfortably on the same driver that needs 1.1 s for one textured
-             * full-screen draw in a 2D game).
+             * Diagnostic only, and deliberately changes no behaviour: a software renderer is
+             * fine for plenty of workloads. Measured on one GPU-less macOS host, a
+             * demand-driven three.js scene ran comfortably on the same driver that needed
+             * 1.1 s for a single textured full-screen draw in a 2D game.
              */
             _reportRenderer(gl: OurWebGLRenderingContext): void;
             /**
-             * Register a callback invoked whenever the GTK widget is resized.
-             * The callback fires alongside the native 'resize' GObject signal and
-             * after the DOM 'resize' event has been dispatched on the canvas.
-             * Canvas buffer dimensions are NOT automatically updated — consumers
-             * should set `canvas.width`/`canvas.height` themselves if desired.
+             * Runs `cb` on every GTK resize, after the DOM 'resize' event has been dispatched
+             * on the canvas. Canvas buffer dimensions are NOT updated for you: set
+             * `canvas.width`/`canvas.height` yourself if the drawing buffer must follow.
              */
             onResize(cb: (width: number, height: number) => void): void;
             /**
-             * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-             * Backed by a persistent GTK frame clock tick callback (vsync-synced) + a persistent GLArea
-             * render signal handler. Both are installed once at construction / first render respectively,
-             * eliminating per-frame GLib.Source allocation and GObject signal connect/disconnect overhead.
+             * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
              *
-             * Returns a monotonically-increasing handle; pass it to `cancelAnimationFrame(id)` to cancel
-             * the specific pending callback. A second `requestAnimationFrame` call before the first has
-             * fired replaces the pending callback (single-slot model — matching the existing rAF
-             * convention of "queue 1 callback per frame, the latest wins"); the older handle becomes
-             * stale and a `cancelAnimationFrame` with that handle is a no-op.
+             * SINGLE SLOT: a second call before the first has fired REPLACES the pending
+             * callback (latest wins), which makes the older handle stale and a
+             * `cancelAnimationFrame` with it a no-op.
              */
             requestAnimationFrame(cb: FrameRequestCallback): number;
             /**
-             * Cancels a previously-scheduled animation frame callback, matching the browser
-             * `cancelAnimationFrame` API. Only clears the pending callback when `id` matches
-             * the handle returned by the most recent `requestAnimationFrame` call — a stale
-             * handle (from a callback that already fired, or was replaced by a later
-             * `requestAnimationFrame`) is a no-op.
+             * Browser `cancelAnimationFrame`. Clears the pending callback only when `id` is
+             * the handle from the most recent `requestAnimationFrame`; a stale handle is a
+             * no-op.
              *
-             * Per-ID matching is load-bearing: without it any consumer that calls
-             * `cancelAnimationFrame` (e.g. Excalibur's `Engine.stop()`, called from a
-             * transient parent `unmap` in a responsive layout) would clear the loop's
-             * latest pending callback and freeze rendering until the next manual
-             * `requestAnimationFrame`. With it, the cancel only fires for the handle
-             * the caller actually owns.
+             * That matching is load-bearing: without it any stray cancel (Excalibur's
+             * `Engine.stop()`, fired from a transient parent `unmap` in a responsive layout)
+             * kills the loop's current callback and freezes rendering.
              */
             cancelAnimationFrame(id: number): void;
             /**
-             * Sets the browser globals this bridge owns — `requestAnimationFrame`,
-             * `cancelAnimationFrame`, `performance` and the two WebGL context
-             * constructors — so that browser-targeted code (e.g. Three.js) works
-             * unchanged on GJS.
+             * Sets the browser globals this bridge owns, so browser-targeted code (Three.js)
+             * runs unchanged on GJS.
              *
-             * `WebGLRenderingContext` / `WebGL2RenderingContext` are installed
-             * UNCONDITIONALLY here: per ADR 0012 rule 5 a bridge's `installGlobals()`
-             * and its `/register` install the same set, `installGlobals()` being the
-             * explicit imperative path (`@gjsify/webgl/register` keeps the
-             * if-undefined guard instead). They used to reach `globalThis` for free
-             * as a side effect of importing the `@gjsify/webgl` barrel; moving that
-             * write into `register.ts` must not shrink what this method does.
+             * The two context constructors are installed UNCONDITIONALLY: per ADR 0012 rule 5
+             * `installGlobals()` is the explicit imperative path and installs the same set as
+             * `@gjsify/webgl/register`, which keeps the if-undefined guard instead.
              */
             installGlobals(): void;
             get allowed_apis(): Gdk.GLAPI;
@@ -2701,95 +2559,68 @@ export declare const WebGLBridge: {
         /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
         get canvas(): globalThis.HTMLCanvasElement | null;
         /**
-         * The GL implementation GDK negotiated, unmasked — `{vendor, renderer}`
-         * straight from `glGetString`, e.g. `Apple Software Renderer`. `null`
-         * until the context exists (i.e. before the first `onReady`).
+         * The GL implementation GDK negotiated, unmasked, straight from `glGetString`;
+         * `null` until the context exists.
          *
-         * Read it to REPORT what a host provides. It is not a capability check:
-         * a CPU rasteriser draws everything a GPU does, only slower, and how much
-         * slower depends entirely on the workload. Anything that switches
-         * renderers should key on a measured frame budget, not on this string.
+         * For REPORTING, not as a capability check: a CPU rasteriser draws everything a
+         * GPU does, only slower, and by how much depends on the workload. Anything that
+         * switches renderers should key on a measured frame budget, not on this string.
          */
         get rendererInfo(): {
             vendor: string;
             renderer: string;
         } | null;
-        /**
-         * Registers a callback to be called once the WebGL context is ready.
-         * If the context is already available, the callback fires synchronously.
-         */
+        /** Runs `cb` once the WebGL context is ready — synchronously if it already is. */
         onReady(cb: WebGLReadyCallback): void;
         /**
          * @deprecated Use `onReady()` instead.
          */
         onWebGLReady(cb: WebGLReadyCallback): void;
         /**
-         * Records the negotiated GL implementation and, when it rasterises on the
-         * CPU, says so ONCE on stderr.
+         * Records the negotiated GL implementation and, when it rasterises on the CPU,
+         * says so ONCE on stderr.
          *
-         * A GPU-less host is invisible from inside the app: context creation
-         * succeeds, every draw call succeeds, nothing rejects, and the only tell
-         * is a frame budget blown by three orders of magnitude — which presents as
-         * a window that sits there. Naming the renderer at the one place that
-         * knows it turns that into a line anyone can act on, for every consumer,
-         * without any of them asking.
+         * A GPU-less host is otherwise invisible from inside the app: the context is
+         * created, every draw call succeeds, and the only tell is a frame budget blown by
+         * three orders of magnitude, which presents as a window that just sits there.
          *
-         * Diagnostic only: it changes no behaviour, because a software renderer is
-         * fine for plenty of workloads (measured on one GPU-less macOS host: a
-         * demand-driven three.js scene and a flat-shaded full-screen quad both run
-         * comfortably on the same driver that needs 1.1 s for one textured
-         * full-screen draw in a 2D game).
+         * Diagnostic only, and deliberately changes no behaviour: a software renderer is
+         * fine for plenty of workloads. Measured on one GPU-less macOS host, a
+         * demand-driven three.js scene ran comfortably on the same driver that needed
+         * 1.1 s for a single textured full-screen draw in a 2D game.
          */
         _reportRenderer(gl: OurWebGLRenderingContext): void;
         /**
-         * Register a callback invoked whenever the GTK widget is resized.
-         * The callback fires alongside the native 'resize' GObject signal and
-         * after the DOM 'resize' event has been dispatched on the canvas.
-         * Canvas buffer dimensions are NOT automatically updated — consumers
-         * should set `canvas.width`/`canvas.height` themselves if desired.
+         * Runs `cb` on every GTK resize, after the DOM 'resize' event has been dispatched
+         * on the canvas. Canvas buffer dimensions are NOT updated for you: set
+         * `canvas.width`/`canvas.height` yourself if the drawing buffer must follow.
          */
         onResize(cb: (width: number, height: number) => void): void;
         /**
-         * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-         * Backed by a persistent GTK frame clock tick callback (vsync-synced) + a persistent GLArea
-         * render signal handler. Both are installed once at construction / first render respectively,
-         * eliminating per-frame GLib.Source allocation and GObject signal connect/disconnect overhead.
+         * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
          *
-         * Returns a monotonically-increasing handle; pass it to `cancelAnimationFrame(id)` to cancel
-         * the specific pending callback. A second `requestAnimationFrame` call before the first has
-         * fired replaces the pending callback (single-slot model — matching the existing rAF
-         * convention of "queue 1 callback per frame, the latest wins"); the older handle becomes
-         * stale and a `cancelAnimationFrame` with that handle is a no-op.
+         * SINGLE SLOT: a second call before the first has fired REPLACES the pending
+         * callback (latest wins), which makes the older handle stale and a
+         * `cancelAnimationFrame` with it a no-op.
          */
         requestAnimationFrame(cb: FrameRequestCallback): number;
         /**
-         * Cancels a previously-scheduled animation frame callback, matching the browser
-         * `cancelAnimationFrame` API. Only clears the pending callback when `id` matches
-         * the handle returned by the most recent `requestAnimationFrame` call — a stale
-         * handle (from a callback that already fired, or was replaced by a later
-         * `requestAnimationFrame`) is a no-op.
+         * Browser `cancelAnimationFrame`. Clears the pending callback only when `id` is
+         * the handle from the most recent `requestAnimationFrame`; a stale handle is a
+         * no-op.
          *
-         * Per-ID matching is load-bearing: without it any consumer that calls
-         * `cancelAnimationFrame` (e.g. Excalibur's `Engine.stop()`, called from a
-         * transient parent `unmap` in a responsive layout) would clear the loop's
-         * latest pending callback and freeze rendering until the next manual
-         * `requestAnimationFrame`. With it, the cancel only fires for the handle
-         * the caller actually owns.
+         * That matching is load-bearing: without it any stray cancel (Excalibur's
+         * `Engine.stop()`, fired from a transient parent `unmap` in a responsive layout)
+         * kills the loop's current callback and freezes rendering.
          */
         cancelAnimationFrame(id: number): void;
         /**
-         * Sets the browser globals this bridge owns — `requestAnimationFrame`,
-         * `cancelAnimationFrame`, `performance` and the two WebGL context
-         * constructors — so that browser-targeted code (e.g. Three.js) works
-         * unchanged on GJS.
+         * Sets the browser globals this bridge owns, so browser-targeted code (Three.js)
+         * runs unchanged on GJS.
          *
-         * `WebGLRenderingContext` / `WebGL2RenderingContext` are installed
-         * UNCONDITIONALLY here: per ADR 0012 rule 5 a bridge's `installGlobals()`
-         * and its `/register` install the same set, `installGlobals()` being the
-         * explicit imperative path (`@gjsify/webgl/register` keeps the
-         * if-undefined guard instead). They used to reach `globalThis` for free
-         * as a side effect of importing the `@gjsify/webgl` barrel; moving that
-         * write into `register.ts` must not shrink what this method does.
+         * The two context constructors are installed UNCONDITIONALLY: per ADR 0012 rule 5
+         * `installGlobals()` is the explicit imperative path and installs the same set as
+         * `@gjsify/webgl/register`, which keeps the if-undefined guard instead.
          */
         installGlobals(): void;
         get allowed_apis(): Gdk.GLAPI;

package/lib/types/webgl-context-base.d.ts

@@ -43,7 +43,6 @@ export declare abstract class WebGLContextBase {
     get drawingBufferWidth(): number;
     DEFAULT_ATTACHMENTS: number[];
     DEFAULT_COLOR_ATTACHMENTS: number[];
-    /** context counter */
     _: number;
     abstract get _gl(): Gwebgl.WebGLRenderingContextBase;
     _contextAttributes: WebGLContextAttributes;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/webgl",
-    "version": "0.35.0",
+    "version": "0.37.0",
     "description": "WebGL module for Gjs",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -29,7 +29,8 @@
             "linux-s390x",
             "linux-riscv64",
             "darwin-arm64",
-            "darwin-x64"
+            "darwin-x64",
+            "win32-x64"
         ],
         "runtimes": {
             "gjs": "polyfill",
@@ -60,8 +61,8 @@
         "WebGL"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.35.0",
-        "@gjsify/unit": "^0.35.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/bit-twiddle": "^1.0.3",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
@@ -71,10 +72,10 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
         "@girs/gwebgl-0.1": "0.1.0-4.0.0-rc.5",
-        "@gjsify/dom-elements": "^0.35.0",
-        "@gjsify/dom-events": "^0.35.0",
-        "@gjsify/event-bridge": "^0.35.0",
-        "@gjsify/utils": "^0.35.0",
+        "@gjsify/dom-elements": "^0.37.0",
+        "@gjsify/dom-events": "^0.37.0",
+        "@gjsify/event-bridge": "^0.37.0",
+        "@gjsify/utils": "^0.37.0",
         "bit-twiddle": "^1.0.2",
         "glsl-tokenizer": "^2.1.5"
     },
@@ -89,12 +90,13 @@
     },
     "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/webgl#readme",
     "optionalDependencies": {
-        "@gjsify/webgl-darwin-arm64": "0.35.0",
-        "@gjsify/webgl-darwin-x64": "0.35.0",
-        "@gjsify/webgl-linux-arm64": "0.35.0",
-        "@gjsify/webgl-linux-ppc64": "0.35.0",
-        "@gjsify/webgl-linux-riscv64": "0.35.0",
-        "@gjsify/webgl-linux-s390x": "0.35.0",
-        "@gjsify/webgl-linux-x64": "0.35.0"
+        "@gjsify/webgl-darwin-arm64": "0.37.0",
+        "@gjsify/webgl-darwin-x64": "0.37.0",
+        "@gjsify/webgl-linux-arm64": "0.37.0",
+        "@gjsify/webgl-linux-ppc64": "0.37.0",
+        "@gjsify/webgl-linux-riscv64": "0.37.0",
+        "@gjsify/webgl-linux-s390x": "0.37.0",
+        "@gjsify/webgl-linux-x64": "0.37.0",
+        "@gjsify/webgl-win32-x64": "0.37.0"
     }
 }