@gjsify/canvas2d-core 0.1.3

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@gjsify/canvas2d-core",
+  "version": "0.1.3",
+  "description": "Cairo-backed Canvas 2D core (CanvasRenderingContext2D, Path2D, ImageData) — no GTK dependency",
+  "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",
+    "offscreen"
+  ],
+  "dependencies": {
+    "@girs/gdk-4.0": "^4.0.0-4.0.0-rc.1",
+    "@girs/gdkpixbuf-2.0": "^2.0.0-4.0.0-rc.1",
+    "@girs/gjs": "^4.0.0-rc.1",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-rc.1",
+    "@girs/gobject-2.0": "^2.88.0-4.0.0-rc.1",
+    "@girs/pango-1.0": "^1.57.1-4.0.0-rc.1",
+    "@girs/pangocairo-1.0": "^1.0.0-4.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.3",
+    "@gjsify/unit": "^0.1.3",
+    "@types/node": "^25.5.2",
+    "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-gradient.ts

@@ -0,0 +1,36 @@
+// CanvasGradient implementation backed by Cairo gradient patterns
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient
+
+import Cairo from 'cairo';
+import { parseColor } from './color.js';
+
+/**
+ * CanvasGradient wrapping a Cairo LinearGradient or RadialGradient.
+ */
+export class CanvasGradient {
+    private _pattern: Cairo.LinearGradient | Cairo.RadialGradient;
+
+    constructor(
+        type: 'linear' | 'radial',
+        x0: number, y0: number,
+        x1: number, y1: number,
+        r0?: number, r1?: number,
+    ) {
+        if (type === 'radial') {
+            this._pattern = new Cairo.RadialGradient(x0, y0, r0!, x1, y1, r1!);
+        } else {
+            this._pattern = new Cairo.LinearGradient(x0, y0, x1, y1);
+        }
+    }
+
+    addColorStop(offset: number, color: string): void {
+        const parsed = parseColor(color);
+        if (!parsed) return;
+        this._pattern.addColorStopRGBA(offset, parsed.r, parsed.g, parsed.b, parsed.a);
+    }
+
+    /** @internal Get the underlying Cairo pattern for rendering. */
+    _getCairoPattern(): Cairo.LinearGradient | Cairo.RadialGradient {
+        return this._pattern;
+    }
+}

package/src/canvas-path.ts

@@ -0,0 +1,131 @@
+// Path2D implementation for Canvas 2D context
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/Path2D
+// Records path operations and replays them on a Cairo context.
+
+import { quadraticToCubic, cairoRoundRect } from './cairo-utils.js';
+
+/** A recorded path operation. */
+type PathOp =
+    | { type: 'moveTo'; x: number; y: number }
+    | { type: 'lineTo'; x: number; y: number }
+    | { type: 'closePath' }
+    | { type: 'bezierCurveTo'; cp1x: number; cp1y: number; cp2x: number; cp2y: number; x: number; y: number }
+    | { type: 'quadraticCurveTo'; cpx: number; cpy: number; x: number; y: number }
+    | { type: 'arc'; x: number; y: number; radius: number; startAngle: number; endAngle: number; ccw: boolean }
+    | { type: 'ellipse'; x: number; y: number; rx: number; ry: number; rotation: number; startAngle: number; endAngle: number; ccw: boolean }
+    | { type: 'rect'; x: number; y: number; w: number; h: number }
+    | { type: 'roundRect'; x: number; y: number; w: number; h: number; radii: number | number[] };
+
+/**
+ * Path2D records path operations for later replay on a CanvasRenderingContext2D.
+ */
+export class Path2D {
+    /** @internal Recorded operations */
+    _ops: PathOp[] = [];
+
+    constructor(pathOrSvg?: Path2D | string) {
+        if (pathOrSvg instanceof Path2D) {
+            this._ops = [...pathOrSvg._ops];
+        }
+        // SVG path string parsing is not implemented (complex, rarely needed)
+    }
+
+    addPath(path: Path2D): void {
+        this._ops.push(...path._ops);
+    }
+
+    moveTo(x: number, y: number): void {
+        this._ops.push({ type: 'moveTo', x, y });
+    }
+
+    lineTo(x: number, y: number): void {
+        this._ops.push({ type: 'lineTo', x, y });
+    }
+
+    closePath(): void {
+        this._ops.push({ type: 'closePath' });
+    }
+
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void {
+        this._ops.push({ type: 'bezierCurveTo', cp1x, cp1y, cp2x, cp2y, x, y });
+    }
+
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void {
+        this._ops.push({ type: 'quadraticCurveTo', cpx, cpy, x, y });
+    }
+
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise = false): void {
+        this._ops.push({ type: 'arc', x, y, radius, startAngle, endAngle, ccw: counterclockwise });
+    }
+
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise = false): void {
+        if (radiusX < 0 || radiusY < 0) throw new RangeError('The radii provided are negative');
+        this._ops.push({ type: 'ellipse', x, y, rx: radiusX, ry: radiusY, rotation, startAngle, endAngle, ccw: counterclockwise });
+    }
+
+    rect(x: number, y: number, w: number, h: number): void {
+        this._ops.push({ type: 'rect', x, y, w, h });
+    }
+
+    roundRect(x: number, y: number, w: number, h: number, radii: number | number[] = 0): void {
+        this._ops.push({ type: 'roundRect', x, y, w, h, radii });
+    }
+
+    /**
+     * @internal Replay all recorded path operations onto a Cairo context.
+     */
+    _replayOnCairo(ctx: import('cairo').default.Context): void {
+        let lastX = 0, lastY = 0;
+
+        for (const op of this._ops) {
+            switch (op.type) {
+                case 'moveTo':
+                    ctx.moveTo(op.x, op.y);
+                    lastX = op.x; lastY = op.y;
+                    break;
+                case 'lineTo':
+                    ctx.lineTo(op.x, op.y);
+                    lastX = op.x; lastY = op.y;
+                    break;
+                case 'closePath':
+                    ctx.closePath();
+                    break;
+                case 'bezierCurveTo':
+                    ctx.curveTo(op.cp1x, op.cp1y, op.cp2x, op.cp2y, op.x, op.y);
+                    lastX = op.x; lastY = op.y;
+                    break;
+                case 'quadraticCurveTo': {
+                    const { cp1x, cp1y, cp2x, cp2y } = quadraticToCubic(lastX, lastY, op.cpx, op.cpy, op.x, op.y);
+                    ctx.curveTo(cp1x, cp1y, cp2x, cp2y, op.x, op.y);
+                    lastX = op.x; lastY = op.y;
+                    break;
+                }
+                case 'arc':
+                    if (op.ccw) {
+                        ctx.arcNegative(op.x, op.y, op.radius, op.startAngle, op.endAngle);
+                    } else {
+                        ctx.arc(op.x, op.y, op.radius, op.startAngle, op.endAngle);
+                    }
+                    break;
+                case 'ellipse':
+                    ctx.save();
+                    ctx.translate(op.x, op.y);
+                    ctx.rotate(op.rotation);
+                    ctx.scale(op.rx, op.ry);
+                    if (op.ccw) {
+                        ctx.arcNegative(0, 0, 1, op.startAngle, op.endAngle);
+                    } else {
+                        ctx.arc(0, 0, 1, op.startAngle, op.endAngle);
+                    }
+                    ctx.restore();
+                    break;
+                case 'rect':
+                    ctx.rectangle(op.x, op.y, op.w, op.h);
+                    break;
+                case 'roundRect':
+                    cairoRoundRect(ctx, op.x, op.y, op.w, op.h, op.radii);
+                    break;
+            }
+        }
+    }
+}

package/src/canvas-pattern.ts

@@ -0,0 +1,75 @@
+// CanvasPattern implementation backed by Cairo SurfacePattern
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/CanvasPattern
+
+import Cairo from 'cairo';
+import Gdk from 'gi://Gdk?version=4.0';
+
+/**
+ * CanvasPattern wrapping a Cairo SurfacePattern.
+ */
+export class CanvasPattern {
+    private _pattern: Cairo.SurfacePattern;
+
+    private constructor(surface: Cairo.ImageSurface, repetition: string | null) {
+        this._pattern = new Cairo.SurfacePattern(surface);
+
+        // Set extend mode based on repetition
+        // setExtend exists at runtime on SurfacePattern but is missing from GIR types
+        const pat = this._pattern as any;
+        switch (repetition) {
+            case 'repeat':
+            case '':
+            case null:
+                pat.setExtend(Cairo.Extend.REPEAT);
+                break;
+            case 'repeat-x':
+            case 'repeat-y':
+                // Cairo doesn't have separate x/y repeat — use REPEAT as approximation
+                pat.setExtend(Cairo.Extend.REPEAT);
+                break;
+            case 'no-repeat':
+                pat.setExtend(Cairo.Extend.NONE);
+                break;
+        }
+    }
+
+    /** Create a CanvasPattern from a supported image source. Returns null if unsupported. */
+    static create(image: any, repetition: string | null): CanvasPattern | null {
+        // HTMLImageElement (GdkPixbuf-backed)
+        if ('isPixbuf' in image && typeof (image as any).isPixbuf === 'function' && (image as any).isPixbuf()) {
+            const pixbuf = (image as any)._pixbuf as import('@girs/gdkpixbuf-2.0').default.Pixbuf;
+            // Create a Cairo surface from the pixbuf
+            const w = pixbuf.get_width();
+            const h = pixbuf.get_height();
+            const surface = new Cairo.ImageSurface(Cairo.Format.ARGB32, w, h);
+            const ctx = new Cairo.Context(surface);
+            Gdk.cairo_set_source_pixbuf(ctx as any, pixbuf, 0, 0);
+            ctx.paint();
+            ctx.$dispose();
+            return new CanvasPattern(surface, repetition);
+        }
+
+        // HTMLCanvasElement with a 2D context
+        if (typeof image?.getContext === 'function') {
+            const ctx2d = image.getContext('2d');
+            if (ctx2d && typeof ctx2d._getSurface === 'function') {
+                const sourceSurface = ctx2d._getSurface() as Cairo.ImageSurface;
+                const w = sourceSurface.getWidth();
+                const h = sourceSurface.getHeight();
+                const surface = new Cairo.ImageSurface(Cairo.Format.ARGB32, w, h);
+                const ctx = new Cairo.Context(surface);
+                ctx.setSourceSurface(sourceSurface, 0, 0);
+                ctx.paint();
+                ctx.$dispose();
+                return new CanvasPattern(surface, repetition);
+            }
+        }
+
+        return null;
+    }
+
+    /** @internal Get the underlying Cairo pattern for rendering. */
+    _getCairoPattern(): Cairo.SurfacePattern {
+        return this._pattern;
+    }
+}