@gjsify/canvas2d 0.1.0

package/lib/types/canvas-rendering-context-2d.d.ts

@@ -0,0 +1,155 @@
+import Cairo from 'cairo';
+import { Path2D } from './canvas-path.js';
+/**
+ * CanvasRenderingContext2D backed by Cairo.ImageSurface.
+ * Implements the Canvas 2D API for GJS.
+ */
+export declare class CanvasRenderingContext2D {
+    readonly canvas: any;
+    private _surface;
+    private _ctx;
+    private _state;
+    private _stateStack;
+    private _surfaceWidth;
+    private _surfaceHeight;
+    constructor(canvas: any, _options?: any);
+    /** Ensure the surface matches the current canvas dimensions. Recreate if resized. */
+    private _ensureSurface;
+    /** Apply the current fill style (color, gradient, or pattern) to the Cairo context. */
+    private _applyFillStyle;
+    /** Apply the current stroke style to the Cairo context. */
+    private _applyStrokeStyle;
+    /** Apply line properties to the Cairo context. */
+    private _applyLineStyle;
+    /** Apply compositing operator. */
+    private _applyCompositing;
+    /** Get the Cairo ImageSurface (used by other contexts like drawImage). */
+    _getSurface(): Cairo.ImageSurface;
+    /** Check if shadow rendering is needed. */
+    private _hasShadow;
+    /**
+     * Render a shadow for the current path by painting to a temp surface,
+     * applying a simple box blur approximation, and compositing back.
+     * This is called before the actual fill/stroke when shadows are active.
+     */
+    private _renderShadow;
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
+    scale(x: number, y: number): void;
+    /**
+     * Multiply the current transformation matrix by the given values.
+     * Matrix: [a c e]
+     *         [b d f]
+     *         [0 0 1]
+     */
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    /**
+     * Reset the transform to identity, then apply the given matrix.
+     */
+    setTransform(matrix?: DOMMatrix2DInit): void;
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    /**
+     * Return the current transformation matrix as a DOMMatrix-like object.
+     */
+    getTransform(): DOMMatrix;
+    resetTransform(): void;
+    get fillStyle(): string | CanvasGradient | CanvasPattern;
+    set fillStyle(value: string | CanvasGradient | CanvasPattern);
+    get strokeStyle(): string | CanvasGradient | CanvasPattern;
+    set strokeStyle(value: string | CanvasGradient | CanvasPattern);
+    get lineWidth(): number;
+    set lineWidth(value: number);
+    get lineCap(): CanvasLineCap;
+    set lineCap(value: CanvasLineCap);
+    get lineJoin(): CanvasLineJoin;
+    set lineJoin(value: CanvasLineJoin);
+    get miterLimit(): number;
+    set miterLimit(value: number);
+    get globalAlpha(): number;
+    set globalAlpha(value: number);
+    get globalCompositeOperation(): GlobalCompositeOperation;
+    set globalCompositeOperation(value: GlobalCompositeOperation);
+    get imageSmoothingEnabled(): boolean;
+    set imageSmoothingEnabled(value: boolean);
+    get imageSmoothingQuality(): ImageSmoothingQuality;
+    set imageSmoothingQuality(value: ImageSmoothingQuality);
+    setLineDash(segments: number[]): void;
+    getLineDash(): number[];
+    get lineDashOffset(): number;
+    set lineDashOffset(value: number);
+    get shadowColor(): string;
+    set shadowColor(value: string);
+    get shadowBlur(): number;
+    set shadowBlur(value: number);
+    get shadowOffsetX(): number;
+    set shadowOffsetX(value: number);
+    get shadowOffsetY(): number;
+    set shadowOffsetY(value: number);
+    get font(): string;
+    set font(value: string);
+    get textAlign(): CanvasTextAlign;
+    set textAlign(value: CanvasTextAlign);
+    get textBaseline(): CanvasTextBaseline;
+    set textBaseline(value: CanvasTextBaseline);
+    get direction(): CanvasDirection;
+    set direction(value: CanvasDirection);
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radii?: number | number[]): void;
+    fill(fillRule?: CanvasFillRule): void;
+    fill(path: Path2D, fillRule?: CanvasFillRule): void;
+    stroke(): void;
+    stroke(path: Path2D): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    clearRect(x: number, y: number, w: number, h: number): void;
+    clip(fillRule?: CanvasFillRule): void;
+    clip(path: Path2D, fillRule?: CanvasFillRule): void;
+    isPointInPath(x: number, y: number, fillRule?: CanvasFillRule): boolean;
+    isPointInPath(path: Path2D, x: number, y: number, fillRule?: CanvasFillRule): boolean;
+    isPointInStroke(x: number, y: number): boolean;
+    isPointInStroke(path: Path2D, x: number, y: number): boolean;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient;
+    createPattern(image: any, repetition: string | null): CanvasPattern | null;
+    createImageData(sw: number, sh: number): ImageData;
+    createImageData(imagedata: ImageData): ImageData;
+    getImageData(sx: number, sy: number, sw: number, sh: number): ImageData;
+    putImageData(imageData: ImageData, dx: number, dy: number, dirtyX?: number, dirtyY?: number, dirtyWidth?: number, dirtyHeight?: number): void;
+    drawImage(image: any, dx: number, dy: number): void;
+    drawImage(image: any, dx: number, dy: number, dw: number, dh: number): void;
+    drawImage(image: any, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    private _getDrawImageSource;
+    /** Create a PangoCairo layout configured with current font/text settings. */
+    private _createTextLayout;
+    /** Parse a CSS font string (e.g. "bold 16px Arial") into a Pango.FontDescription. */
+    private _parseFontToDescription;
+    /**
+     * Compute the x-offset for text alignment relative to the given x coordinate.
+     */
+    private _getTextAlignOffset;
+    /**
+     * Compute the y-offset for text baseline positioning.
+     */
+    private _getTextBaselineOffset;
+    fillText(text: string, x: number, y: number, _maxWidth?: number): void;
+    strokeText(text: string, x: number, y: number, _maxWidth?: number): void;
+    measureText(text: string): TextMetrics;
+    /**
+     * Write the canvas surface to a PNG file and return as data URL.
+     * Used by HTMLCanvasElement.toDataURL() when a '2d' context is active.
+     */
+    _toDataURL(type?: string, _quality?: number): string;
+    /** Release native Cairo resources. Call when the canvas is discarded. */
+    _dispose(): void;
+}

package/lib/types/canvas-state.d.ts

@@ -0,0 +1,27 @@
+import type { RGBA } from './color.js';
+export interface CanvasState {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    fillColor: RGBA;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    strokeColor: RGBA;
+    lineWidth: number;
+    lineCap: CanvasLineCap;
+    lineJoin: CanvasLineJoin;
+    miterLimit: number;
+    lineDash: number[];
+    lineDashOffset: number;
+    globalAlpha: number;
+    globalCompositeOperation: GlobalCompositeOperation;
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    direction: CanvasDirection;
+    imageSmoothingEnabled: boolean;
+    imageSmoothingQuality: ImageSmoothingQuality;
+}
+export declare function createDefaultState(): CanvasState;
+export declare function cloneState(state: CanvasState): CanvasState;

package/lib/types/color.d.ts

@@ -0,0 +1,15 @@
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Parse a CSS color string into RGBA components (0-1 range).
+ * Supports: #rgb, #rrggbb, #rgba, #rrggbbaa, rgb(), rgba(), named colors, 'transparent'.
+ */
+export declare function parseColor(color: string): RGBA | null;
+/** Default color: opaque black */
+export declare const BLACK: RGBA;
+/** Transparent black */
+export declare const TRANSPARENT: RGBA;

package/lib/types/image-data.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ImageData represents the pixel data of a canvas area.
+ * Each pixel is 4 bytes: R, G, B, A (0-255 each).
+ */
+export declare class OurImageData {
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly colorSpace: PredefinedColorSpace;
+    constructor(sw: number, sh: number);
+    constructor(data: Uint8ClampedArray, sw: number, sh?: number);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,7 @@
+export { CanvasRenderingContext2D } from './canvas-rendering-context-2d.js';
+export { CanvasGradient } from './canvas-gradient.js';
+export { CanvasPattern } from './canvas-pattern.js';
+export { Path2D } from './canvas-path.js';
+export { OurImageData as ImageData } from './image-data.js';
+export { parseColor } from './color.js';
+export { Canvas2DWidget } from './canvas-drawing-area.js';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gjsify/canvas2d",
+  "version": "0.1.0",
+  "description": "Canvas 2D rendering context for GJS, backed by Cairo",
+  "type": "module",
+  "module": "lib/esm/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/esm/index.js"
+    }
+  },
+  "scripts": {
+    "clear": "rm -rf lib tmp tsconfig.tsbuildinfo test.gjs.mjs || exit 0",
+    "check": "tsc --noEmit",
+    "build": "yarn build:gjsify && yarn build:types",
+    "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+    "build:types": "tsc",
+    "build:test": "yarn build:test:gjs",
+    "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+    "test": "yarn build:gjsify && yarn build:test && yarn test:gjs",
+    "test:gjs": "gjs -m test.gjs.mjs"
+  },
+  "keywords": [
+    "gjs",
+    "canvas",
+    "canvas2d",
+    "cairo"
+  ],
+  "dependencies": {
+    "@girs/gdk-4.0": "^4.0.0-4.0.0-beta.42",
+    "@girs/gdkpixbuf-2.0": "^2.0.0-4.0.0-beta.42",
+    "@girs/gjs": "^4.0.0-beta.42",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-beta.42",
+    "@girs/gobject-2.0": "^2.88.0-4.0.0-beta.42",
+    "@girs/gtk-4.0": "^4.22.1-4.0.0-beta.42",
+    "@girs/pango-1.0": "^1.57.0-4.0.0-beta.42",
+    "@girs/pangocairo-1.0": "^1.0.0-4.0.0-beta.42",
+    "@gjsify/dom-elements": "^0.1.0",
+    "@gjsify/event-bridge": "^0.1.0",
+    "@gjsify/utils": "^0.1.0"
+  },
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.0",
+    "@gjsify/unit": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/cairo-utils.ts

@@ -0,0 +1,243 @@
+// Cairo utility helpers for Canvas 2D context
+// Handles format conversions and path operations not directly available in Cairo.
+
+import type Cairo from 'cairo';
+
+/**
+ * Convert quadratic Bezier control point to cubic Bezier control points.
+ * Canvas 2D has quadraticCurveTo but Cairo only has cubic curveTo.
+ *
+ * Given current point (cx, cy), quadratic control point (cpx, cpy), and end (x, y):
+ *   cp1 = current + 2/3 * (cp - current)
+ *   cp2 = end + 2/3 * (cp - end)
+ */
+export function quadraticToCubic(
+    cx: number, cy: number,
+    cpx: number, cpy: number,
+    x: number, y: number,
+): { cp1x: number; cp1y: number; cp2x: number; cp2y: number } {
+    return {
+        cp1x: cx + (2 / 3) * (cpx - cx),
+        cp1y: cy + (2 / 3) * (cpy - cy),
+        cp2x: x + (2 / 3) * (cpx - x),
+        cp2y: y + (2 / 3) * (cpy - y),
+    };
+}
+
+/**
+ * Compute arcTo parameters.
+ * Canvas arcTo(x1,y1,x2,y2,radius) draws a line from current point to the tangent point,
+ * then an arc of the given radius tangent to both lines (current→p1 and p1→p2).
+ *
+ * Returns the two tangent points and arc center, or null if degenerate (collinear points).
+ */
+export function computeArcTo(
+    x0: number, y0: number,
+    x1: number, y1: number,
+    x2: number, y2: number,
+    radius: number,
+): { tx0: number; ty0: number; tx1: number; ty1: number; cx: number; cy: number; startAngle: number; endAngle: number; counterclockwise: boolean } | null {
+    // Direction vectors
+    const dx0 = x0 - x1;
+    const dy0 = y0 - y1;
+    const dx1 = x2 - x1;
+    const dy1 = y2 - y1;
+
+    // Lengths
+    const len0 = Math.sqrt(dx0 * dx0 + dy0 * dy0);
+    const len1 = Math.sqrt(dx1 * dx1 + dy1 * dy1);
+
+    if (len0 === 0 || len1 === 0) return null;
+
+    // Normalize
+    const ux0 = dx0 / len0;
+    const uy0 = dy0 / len0;
+    const ux1 = dx1 / len1;
+    const uy1 = dy1 / len1;
+
+    // Cross product to determine direction
+    const cross = ux0 * uy1 - uy0 * ux1;
+    if (Math.abs(cross) < 1e-10) return null; // Collinear
+
+    // Half-angle between the two direction vectors
+    const dot = ux0 * ux1 + uy0 * uy1;
+    const halfAngle = Math.acos(Math.max(-1, Math.min(1, dot))) / 2;
+
+    // Distance from p1 to tangent point
+    const tanDist = radius / Math.tan(halfAngle);
+
+    // Tangent points
+    const tx0 = x1 + ux0 * tanDist;
+    const ty0 = y1 + uy0 * tanDist;
+    const tx1 = x1 + ux1 * tanDist;
+    const ty1 = y1 + uy1 * tanDist;
+
+    // Center of the arc circle: perpendicular to the bisector, distance = radius / sin(halfAngle)
+    const centerDist = radius / Math.sin(halfAngle);
+    const bisectX = (ux0 + ux1) / 2;
+    const bisectY = (uy0 + uy1) / 2;
+    const bisectLen = Math.sqrt(bisectX * bisectX + bisectY * bisectY);
+    const cx = x1 + (bisectX / bisectLen) * centerDist;
+    const cy = y1 + (bisectY / bisectLen) * centerDist;
+
+    // Start and end angles
+    const startAngle = Math.atan2(ty0 - cy, tx0 - cx);
+    const endAngle = Math.atan2(ty1 - cy, tx1 - cx);
+
+    // Counterclockwise if cross product is positive
+    const counterclockwise = cross > 0;
+
+    return { tx0, ty0, tx1, ty1, cx, cy, startAngle, endAngle, counterclockwise };
+}
+
+/**
+ * Apply an arcTo operation to a Cairo context.
+ */
+export function cairoArcTo(
+    ctx: Cairo.Context,
+    x0: number, y0: number,
+    x1: number, y1: number,
+    x2: number, y2: number,
+    radius: number,
+): void {
+    const result = computeArcTo(x0, y0, x1, y1, x2, y2, radius);
+    if (!result) {
+        // Degenerate: just draw a line to (x1, y1)
+        ctx.lineTo(x1, y1);
+        return;
+    }
+
+    const { tx0, ty0, cx, cy, startAngle, endAngle, counterclockwise } = result;
+
+    // Line from current point to first tangent point
+    ctx.lineTo(tx0, ty0);
+
+    // Arc
+    if (counterclockwise) {
+        ctx.arcNegative(cx, cy, radius, startAngle, endAngle);
+    } else {
+        ctx.arc(cx, cy, radius, startAngle, endAngle);
+    }
+}
+
+/**
+ * Draw an ellipse on a Cairo context.
+ * Canvas ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle, counterclockwise)
+ * is implemented via save/translate/rotate/scale/arc/restore.
+ */
+export function cairoEllipse(
+    ctx: Cairo.Context,
+    x: number, y: number,
+    radiusX: number, radiusY: number,
+    rotation: number,
+    startAngle: number, endAngle: number,
+    counterclockwise: boolean,
+): void {
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.rotate(rotation);
+    ctx.scale(radiusX, radiusY);
+
+    if (counterclockwise) {
+        ctx.arcNegative(0, 0, 1, startAngle, endAngle);
+    } else {
+        ctx.arc(0, 0, 1, startAngle, endAngle);
+    }
+
+    ctx.restore();
+}
+
+/**
+ * Draw a rounded rectangle path on a Cairo context.
+ * Implements the Canvas roundRect(x, y, w, h, radii) method.
+ */
+export function cairoRoundRect(
+    ctx: Cairo.Context,
+    x: number, y: number,
+    w: number, h: number,
+    radii: number | number[],
+): void {
+    // Normalize radii to [topLeft, topRight, bottomRight, bottomLeft]
+    let tl: number, tr: number, br: number, bl: number;
+    if (typeof radii === 'number') {
+        tl = tr = br = bl = radii;
+    } else if (radii.length === 1) {
+        tl = tr = br = bl = radii[0];
+    } else if (radii.length === 2) {
+        tl = br = radii[0];
+        tr = bl = radii[1];
+    } else if (radii.length === 3) {
+        tl = radii[0];
+        tr = bl = radii[1];
+        br = radii[2];
+    } else {
+        tl = radii[0];
+        tr = radii[1];
+        br = radii[2];
+        bl = radii[3];
+    }
+
+    // Clamp radii so they don't exceed half the width/height
+    const maxR = Math.min(w / 2, h / 2);
+    tl = Math.min(tl, maxR);
+    tr = Math.min(tr, maxR);
+    br = Math.min(br, maxR);
+    bl = Math.min(bl, maxR);
+
+    const PI_2 = Math.PI / 2;
+
+    ctx.newSubPath();
+    // Top-left corner
+    ctx.arc(x + tl, y + tl, tl, Math.PI, Math.PI + PI_2);
+    // Top-right corner
+    ctx.arc(x + w - tr, y + tr, tr, -PI_2, 0);
+    // Bottom-right corner
+    ctx.arc(x + w - br, y + h - br, br, 0, PI_2);
+    // Bottom-left corner
+    ctx.arc(x + bl, y + h - bl, bl, PI_2, Math.PI);
+    ctx.closePath();
+}
+
+/** Map Canvas globalCompositeOperation to Cairo.Operator values */
+export const COMPOSITE_OP_MAP: Record<string, number> = {
+    'source-over': 2,      // OVER
+    'source-in': 5,        // IN
+    'source-out': 6,       // OUT
+    'source-atop': 7,      // ATOP
+    'destination-over': 8, // DEST_OVER
+    'destination-in': 9,   // DEST_IN
+    'destination-out': 10, // DEST_OUT
+    'destination-atop': 11,// DEST_ATOP
+    'lighter': 12,         // ADD
+    'copy': 1,             // SOURCE
+    'xor': 13,             // XOR
+    'multiply': 14,        // MULTIPLY
+    'screen': 15,          // SCREEN
+    'overlay': 16,         // OVERLAY
+    'darken': 17,          // DARKEN
+    'lighten': 18,         // LIGHTEN
+    'color-dodge': 19,     // COLOR_DODGE
+    'color-burn': 20,      // COLOR_BURN
+    'hard-light': 21,      // HARD_LIGHT
+    'soft-light': 22,      // SOFT_LIGHT
+    'difference': 23,      // DIFFERENCE
+    'exclusion': 24,       // EXCLUSION
+    'hue': 25,             // HSL_HUE
+    'saturation': 26,      // HSL_SATURATION
+    'color': 27,           // HSL_COLOR
+    'luminosity': 28,      // HSL_LUMINOSITY
+};
+
+/** Map Canvas lineCap to Cairo.LineCap values */
+export const LINE_CAP_MAP: Record<string, number> = {
+    'butt': 0,
+    'round': 1,
+    'square': 2,
+};
+
+/** Map Canvas lineJoin to Cairo.LineJoin values */
+export const LINE_JOIN_MAP: Record<string, number> = {
+    'miter': 0,
+    'round': 1,
+    'bevel': 2,
+};

package/src/canvas-drawing-area.ts

@@ -0,0 +1,164 @@
+// Canvas2DWidget GTK widget for GJS — original implementation using Gtk.DrawingArea + Cairo
+// Provides a Gtk.DrawingArea subclass that handles Canvas 2D bootstrapping.
+// Pattern follows packages/dom/iframe/src/iframe-widget.ts (IFrameWidget)
+
+import GObject from 'gi://GObject';
+import Gdk from 'gi://Gdk?version=4.0';
+import GLib from 'gi://GLib?version=2.0';
+import Gtk from 'gi://Gtk?version=4.0';
+import { HTMLCanvasElement as GjsifyHTMLCanvasElement } from '@gjsify/dom-elements';
+import { attachEventControllers } from '@gjsify/event-bridge';
+import { CanvasRenderingContext2D } from './canvas-rendering-context-2d.js';
+
+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`
+ *
+ * Usage:
+ * ```ts
+ * const widget = new Canvas2DWidget();
+ * widget.installGlobals();  // sets globalThis.requestAnimationFrame
+ * widget.onReady((canvas, ctx) => {
+ *     ctx.fillStyle = 'red';
+ *     ctx.fillRect(0, 0, 100, 100);
+ * });
+ * window.set_child(widget);
+ * ```
+ */
+export const Canvas2DWidget = GObject.registerClass(
+    { GTypeName: 'GjsifyCanvas2DWidget' },
+    class Canvas2DWidget extends Gtk.DrawingArea {
+        _canvas: GjsifyHTMLCanvasElement | null = null;
+        _ctx: CanvasRenderingContext2D | null = null;
+        _readyCallbacks: Canvas2DReadyCallback[] = [];
+        _tickCallbackId: number | null = null;
+        _frameCallback: FrameRequestCallback | null = null;
+        // Time origin in microseconds (GLib monotonic clock).
+        // Both requestAnimationFrame timestamps and performance.now() are
+        // relative to this origin, matching the browser DOMHighResTimeStamp spec.
+        _timeOrigin: number = GLib.get_monotonic_time();
+
+        constructor(params?: Partial<Gtk.DrawingArea.ConstructorProps>) {
+            super(params);
+            this.set_draw_func(this._onDraw.bind(this));
+
+            // Bridge GTK events → DOM events on the canvas element
+            attachEventControllers(this, () => this._canvas);
+
+            this.connect('unrealize', () => {
+                if (this._tickCallbackId !== null) {
+                    this.remove_tick_callback(this._tickCallbackId);
+                    this._tickCallbackId = null;
+                }
+                if (this._ctx) {
+                    this._ctx._dispose();
+                }
+                this._canvas = null;
+                this._ctx = null;
+            });
+        }
+
+        /** @internal Draw function called by GTK. Blits the Cairo surface to screen. */
+        _onDraw(_area: Gtk.DrawingArea, cr: any, width: number, height: number): void {
+            // Lazy init: create canvas + 2D context on first draw
+            if (!this._canvas) {
+                this._canvas = new GjsifyHTMLCanvasElement();
+                this._canvas.width = width;
+                this._canvas.height = height;
+                // Import side-effect registers the '2d' factory, so getContext('2d') works
+                this._ctx = this._canvas.getContext('2d') as unknown as CanvasRenderingContext2D;
+                if (this._ctx) {
+                    for (const cb of this._readyCallbacks) {
+                        cb(this._canvas as unknown as globalThis.HTMLCanvasElement, this._ctx);
+                    }
+                    this._readyCallbacks = [];
+                }
+            }
+
+            // Sync dimensions if widget was resized
+            if (this._canvas.width !== width || this._canvas.height !== height) {
+                this._canvas.width = width;
+                this._canvas.height = height;
+            }
+
+            // Blit the Canvas 2D's Cairo.ImageSurface onto the DrawingArea
+            if (this._ctx) {
+                const surface = this._ctx._getSurface();
+                cr.setSourceSurface(surface, 0, 0);
+                cr.paint();
+            }
+        }
+
+        /** The HTMLCanvasElement backing this widget. Available after the first draw. */
+        get canvas(): globalThis.HTMLCanvasElement | null {
+            return this._canvas as unknown as globalThis.HTMLCanvasElement | null;
+        }
+
+        /** Get the 2D rendering context. Available after the first draw. */
+        getContext(_id: '2d'): CanvasRenderingContext2D | null {
+            return this._ctx;
+        }
+
+        /**
+         * Register a callback to be invoked once the Canvas 2D context is ready.
+         * If the context is already available, the callback fires synchronously.
+         */
+        onReady(cb: Canvas2DReadyCallback): void {
+            if (this._canvas && this._ctx) {
+                cb(this._canvas as unknown as globalThis.HTMLCanvasElement, this._ctx);
+                return;
+            }
+            this._readyCallbacks.push(cb);
+        }
+
+        /**
+         * 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).
+         */
+        requestAnimationFrame(cb: FrameRequestCallback): number {
+            this._frameCallback = cb;
+            if (this._tickCallbackId === null) {
+                this._tickCallbackId = this.add_tick_callback((_widget: Gtk.Widget, frameClock: Gdk.FrameClock) => {
+                    this._tickCallbackId = null;
+                    // DOMHighResTimeStamp: ms since time origin, matching performance.now()
+                    const time = (frameClock.get_frame_time() - this._timeOrigin) / 1000;
+                    this._frameCallback?.(time);
+                    this.queue_draw();
+                    return GLib.SOURCE_REMOVE;
+                });
+            }
+            // Ensure GTK schedules a new frame so the tick callback fires.
+            // Without this, requestAnimationFrame called during the paint phase
+            // (e.g. from onReady) may not trigger the frame clock to tick again.
+            this.queue_draw();
+            return 0;
+        }
+
+        /**
+         * Sets browser globals (`requestAnimationFrame`, `performance`) so that
+         * browser-targeted code works unchanged on GJS.
+         */
+        installGlobals(): void {
+            (globalThis as any).requestAnimationFrame = (cb: FrameRequestCallback) =>
+                this.requestAnimationFrame(cb);
+            // Install performance.now() on the same time origin as rAF timestamps.
+            // Always override to ensure consistency — native GJS performance.now()
+            // may use a different time origin than the frame clock.
+            const timeOrigin = this._timeOrigin;
+            (globalThis as any).performance = {
+                now: () => (GLib.get_monotonic_time() - timeOrigin) / 1000,
+                timeOrigin: Date.now(),
+            };
+        }
+    }
+);
+
+// Export the instance type so callers can type-annotate their Canvas2DWidget variables
+export type Canvas2DWidget = InstanceType<typeof Canvas2DWidget>;