@gjsify/webgl 0.36.0 → 0.38.0

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;