@gjsify/canvas2d 0.36.0 → 0.37.0

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

@@ -9,23 +9,19 @@ import '@gjsify/canvas2d-core/gdk';
 import type { CanvasRenderingContext2D } from '@gjsify/canvas2d-core';
 type Canvas2DReadyCallback = (canvas: globalThis.HTMLCanvasElement, ctx: CanvasRenderingContext2D) => void;
 /**
- * A `Gtk.DrawingArea` subclass that handles Canvas 2D bootstrapping:
- * - Creates an `HTMLCanvasElement` + `CanvasRenderingContext2D` on first draw
- * - Blits the Canvas 2D Cairo.ImageSurface onto the DrawingArea each frame
- * - Fires `onReady()` callbacks with (canvas, ctx) once the context is available
- * - Provides `requestAnimationFrame()` backed by GTK frame clock (vsync)
- * - `installGlobals()` sets `globalThis.requestAnimationFrame` and `globalThis.performance`
+ * A `Gtk.DrawingArea` subclass that creates an `HTMLCanvasElement` +
+ * `CanvasRenderingContext2D` on first draw and blits its Cairo surface each frame.
  *
- * Usage:
+ * `installGlobals()` must run BEFORE the app code that expects the browser globals:
  * ```ts
  * const widget = new Canvas2DBridge();
- * widget.installGlobals();  // sets globalThis.requestAnimationFrame
- * widget.onReady((canvas, ctx) => {
- *     ctx.fillStyle = 'red';
- *     ctx.fillRect(0, 0, 100, 100);
- * });
+ * widget.installGlobals();
+ * widget.onReady((canvas, ctx) => { … });
  * window.set_child(widget);
  * ```
+ *
+ * No custom 'resize' signal: the one inherited from Gtk.Widget has the same shape as
+ * Gtk.GLArea's, so `widget.connect('resize', …)` is one pattern across both bridges.
  */
 export declare const Canvas2DBridge: {
     new (...args: any[]): GObject.RegisteredPrototype<{
@@ -40,23 +36,18 @@ export declare const Canvas2DBridge: {
         _onDraw(_area: Gtk.DrawingArea, cr: Cairo.Context, width: number, height: number): void;
         /** The HTMLCanvasElement backing this widget. Available after the first draw. */
         get canvas(): globalThis.HTMLCanvasElement | null;
-        /** Get the 2D rendering context. Available after the first draw. */
+        /** The 2D rendering context; available after the first draw. */
         getContext(_id: "2d"): CanvasRenderingContext2D | null;
-        /**
-         * Register a callback to be invoked once the Canvas 2D context is ready.
-         * If the context is already available, the callback fires synchronously.
-         */
+        /** Runs `cb` once the 2D context is ready — synchronously if it already is. */
         onReady(cb: Canvas2DReadyCallback): void;
         /**
-         * Register a callback invoked whenever the GTK widget is resized.
-         * Canvas dimensions are already updated when the callback fires.
-         * Call `queue_draw()` after re-rendering to push the new surface to screen.
+         * Runs `cb` on every GTK resize, with the canvas dimensions already updated. Call
+         * `queue_draw()` after re-rendering to push the new surface to screen.
          */
         onResize(cb: (width: number, height: number) => void): void;
         /**
-         * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-         * Backed by GTK frame clock (vsync-synced, typically ~60 FPS).
-         * Returns 0 (handle — cancel not yet implemented).
+         * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
+         * Always returns 0: there is no `cancelAnimationFrame` here to hand a handle to.
          */
         requestAnimationFrame(cb: FrameRequestCallback): number;
         /**
@@ -468,23 +459,18 @@ export declare const Canvas2DBridge: {
             _onDraw(_area: Gtk.DrawingArea, cr: Cairo.Context, width: number, height: number): void;
             /** The HTMLCanvasElement backing this widget. Available after the first draw. */
             get canvas(): globalThis.HTMLCanvasElement | null;
-            /** Get the 2D rendering context. Available after the first draw. */
+            /** The 2D rendering context; available after the first draw. */
             getContext(_id: "2d"): CanvasRenderingContext2D | null;
-            /**
-             * Register a callback to be invoked once the Canvas 2D context is ready.
-             * If the context is already available, the callback fires synchronously.
-             */
+            /** Runs `cb` once the 2D context is ready — synchronously if it already is. */
             onReady(cb: Canvas2DReadyCallback): void;
             /**
-             * Register a callback invoked whenever the GTK widget is resized.
-             * Canvas dimensions are already updated when the callback fires.
-             * Call `queue_draw()` after re-rendering to push the new surface to screen.
+             * Runs `cb` on every GTK resize, with the canvas dimensions already updated. Call
+             * `queue_draw()` after re-rendering to push the new surface to screen.
              */
             onResize(cb: (width: number, height: number) => void): void;
             /**
-             * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-             * Backed by GTK frame clock (vsync-synced, typically ~60 FPS).
-             * Returns 0 (handle — cancel not yet implemented).
+             * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
+             * Always returns 0: there is no `cancelAnimationFrame` here to hand a handle to.
              */
             requestAnimationFrame(cb: FrameRequestCallback): number;
             /**
@@ -896,23 +882,18 @@ export declare const Canvas2DBridge: {
                 _onDraw(_area: Gtk.DrawingArea, cr: Cairo.Context, width: number, height: number): void;
                 /** The HTMLCanvasElement backing this widget. Available after the first draw. */
                 get canvas(): globalThis.HTMLCanvasElement | null;
-                /** Get the 2D rendering context. Available after the first draw. */
+                /** The 2D rendering context; available after the first draw. */
                 getContext(_id: "2d"): CanvasRenderingContext2D | null;
-                /**
-                 * Register a callback to be invoked once the Canvas 2D context is ready.
-                 * If the context is already available, the callback fires synchronously.
-                 */
+                /** Runs `cb` once the 2D context is ready — synchronously if it already is. */
                 onReady(cb: Canvas2DReadyCallback): void;
                 /**
-                 * Register a callback invoked whenever the GTK widget is resized.
-                 * Canvas dimensions are already updated when the callback fires.
-                 * Call `queue_draw()` after re-rendering to push the new surface to screen.
+                 * Runs `cb` on every GTK resize, with the canvas dimensions already updated. Call
+                 * `queue_draw()` after re-rendering to push the new surface to screen.
                  */
                 onResize(cb: (width: number, height: number) => void): void;
                 /**
-                 * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-                 * Backed by GTK frame clock (vsync-synced, typically ~60 FPS).
-                 * Returns 0 (handle — cancel not yet implemented).
+                 * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
+                 * Always returns 0: there is no `cancelAnimationFrame` here to hand a handle to.
                  */
                 requestAnimationFrame(cb: FrameRequestCallback): number;
                 /**
@@ -1324,23 +1305,18 @@ export declare const Canvas2DBridge: {
                 _onDraw(_area: Gtk.DrawingArea, cr: Cairo.Context, width: number, height: number): void;
                 /** The HTMLCanvasElement backing this widget. Available after the first draw. */
                 get canvas(): globalThis.HTMLCanvasElement | null;
-                /** Get the 2D rendering context. Available after the first draw. */
+                /** The 2D rendering context; available after the first draw. */
                 getContext(_id: "2d"): CanvasRenderingContext2D | null;
-                /**
-                 * Register a callback to be invoked once the Canvas 2D context is ready.
-                 * If the context is already available, the callback fires synchronously.
-                 */
+                /** Runs `cb` once the 2D context is ready — synchronously if it already is. */
                 onReady(cb: Canvas2DReadyCallback): void;
                 /**
-                 * Register a callback invoked whenever the GTK widget is resized.
-                 * Canvas dimensions are already updated when the callback fires.
-                 * Call `queue_draw()` after re-rendering to push the new surface to screen.
+                 * Runs `cb` on every GTK resize, with the canvas dimensions already updated. Call
+                 * `queue_draw()` after re-rendering to push the new surface to screen.
                  */
                 onResize(cb: (width: number, height: number) => void): void;
                 /**
-                 * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-                 * Backed by GTK frame clock (vsync-synced, typically ~60 FPS).
-                 * Returns 0 (handle — cancel not yet implemented).
+                 * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
+                 * Always returns 0: there is no `cancelAnimationFrame` here to hand a handle to.
                  */
                 requestAnimationFrame(cb: FrameRequestCallback): number;
                 /**
@@ -1752,23 +1728,18 @@ export declare const Canvas2DBridge: {
             _onDraw(_area: Gtk.DrawingArea, cr: Cairo.Context, width: number, height: number): void;
             /** The HTMLCanvasElement backing this widget. Available after the first draw. */
             get canvas(): globalThis.HTMLCanvasElement | null;
-            /** Get the 2D rendering context. Available after the first draw. */
+            /** The 2D rendering context; available after the first draw. */
             getContext(_id: "2d"): CanvasRenderingContext2D | null;
-            /**
-             * Register a callback to be invoked once the Canvas 2D context is ready.
-             * If the context is already available, the callback fires synchronously.
-             */
+            /** Runs `cb` once the 2D context is ready — synchronously if it already is. */
             onReady(cb: Canvas2DReadyCallback): void;
             /**
-             * Register a callback invoked whenever the GTK widget is resized.
-             * Canvas dimensions are already updated when the callback fires.
-             * Call `queue_draw()` after re-rendering to push the new surface to screen.
+             * Runs `cb` on every GTK resize, with the canvas dimensions already updated. Call
+             * `queue_draw()` after re-rendering to push the new surface to screen.
              */
             onResize(cb: (width: number, height: number) => void): void;
             /**
-             * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-             * Backed by GTK frame clock (vsync-synced, typically ~60 FPS).
-             * Returns 0 (handle — cancel not yet implemented).
+             * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
+             * Always returns 0: there is no `cancelAnimationFrame` here to hand a handle to.
              */
             requestAnimationFrame(cb: FrameRequestCallback): number;
             /**
@@ -2180,23 +2151,18 @@ export declare const Canvas2DBridge: {
         _onDraw(_area: Gtk.DrawingArea, cr: Cairo.Context, width: number, height: number): void;
         /** The HTMLCanvasElement backing this widget. Available after the first draw. */
         get canvas(): globalThis.HTMLCanvasElement | null;
-        /** Get the 2D rendering context. Available after the first draw. */
+        /** The 2D rendering context; available after the first draw. */
         getContext(_id: "2d"): CanvasRenderingContext2D | null;
-        /**
-         * Register a callback to be invoked once the Canvas 2D context is ready.
-         * If the context is already available, the callback fires synchronously.
-         */
+        /** Runs `cb` once the 2D context is ready — synchronously if it already is. */
         onReady(cb: Canvas2DReadyCallback): void;
         /**
-         * Register a callback invoked whenever the GTK widget is resized.
-         * Canvas dimensions are already updated when the callback fires.
-         * Call `queue_draw()` after re-rendering to push the new surface to screen.
+         * Runs `cb` on every GTK resize, with the canvas dimensions already updated. Call
+         * `queue_draw()` after re-rendering to push the new surface to screen.
          */
         onResize(cb: (width: number, height: number) => void): void;
         /**
-         * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
-         * Backed by GTK frame clock (vsync-synced, typically ~60 FPS).
-         * Returns 0 (handle — cancel not yet implemented).
+         * Browser `requestAnimationFrame`, driven by the vsync-synced GTK frame clock.
+         * Always returns 0: there is no `cancelAnimationFrame` here to hand a handle to.
          */
         requestAnimationFrame(cb: FrameRequestCallback): number;
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/canvas2d",
-    "version": "0.36.0",
+    "version": "0.37.0",
     "description": "Canvas 2D rendering context for GJS, backed by Cairo",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -47,15 +47,15 @@
         "@girs/gtk-4.0": "^4.1.0",
         "@girs/pango-1.0": "^4.1.0",
         "@girs/pangocairo-1.0": "^4.1.0",
-        "@gjsify/canvas2d-core": "^0.36.0",
-        "@gjsify/dom-elements": "^0.36.0",
-        "@gjsify/dom-events": "^0.36.0",
-        "@gjsify/event-bridge": "^0.36.0",
-        "@gjsify/utils": "^0.36.0"
+        "@gjsify/canvas2d-core": "^0.37.0",
+        "@gjsify/dom-elements": "^0.37.0",
+        "@gjsify/dom-events": "^0.37.0",
+        "@gjsify/event-bridge": "^0.37.0",
+        "@gjsify/utils": "^0.37.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },