@gjsify/canvas2d-core 0.1.7 → 0.1.9

package/src/canvas-state.spec.ts

@@ -0,0 +1,245 @@
+// Canvas 2D state stack tests — save/restore must round-trip every
+// state field (fillStyle, strokeStyle, globalAlpha, lineWidth, transform,
+// text properties, clip region, imageSmoothingEnabled).
+//
+// Ported from refs/wpt/html/canvas/element/the-canvas-state/
+//   2d.state.saverestore.{fillStyle,strokeStyle,globalAlpha,
+//   globalCompositeOperation,lineWidth,lineCap,lineJoin,miterLimit,
+//   transformation,path,underflow,clip,stackdepth}.html
+// Original: Copyright (c) Web Platform Tests contributors. 3-Clause BSD.
+// Reimplemented for GJS using @gjsify/canvas2d-core + @gjsify/unit.
+
+import { describe, it, expect } from '@gjsify/unit';
+import { CanvasRenderingContext2D } from './canvas-rendering-context-2d.js';
+
+function makeCtx(width = 50, height = 50): CanvasRenderingContext2D {
+    const canvas = { width, height };
+    return new CanvasRenderingContext2D(canvas);
+}
+
+function nearlyEqual(a: number, b: number, eps = 1e-9): boolean {
+    return Math.abs(a - b) < eps;
+}
+
+export default async () => {
+    await describe('CanvasRenderingContext2D — state save/restore', async () => {
+
+        await describe('style properties', async () => {
+            await it('save/restore round-trips fillStyle string colors', async () => {
+                const ctx = makeCtx();
+                ctx.fillStyle = '#ff0000';
+                ctx.save();
+                ctx.fillStyle = '#00ff00';
+                expect(ctx.fillStyle).toBe('#00ff00');
+                ctx.restore();
+                expect(ctx.fillStyle).toBe('#ff0000');
+            });
+
+            await it('save/restore round-trips strokeStyle', async () => {
+                const ctx = makeCtx();
+                ctx.strokeStyle = '#112233';
+                ctx.save();
+                ctx.strokeStyle = '#445566';
+                ctx.restore();
+                expect(ctx.strokeStyle).toBe('#112233');
+            });
+
+            await it('save/restore round-trips globalAlpha', async () => {
+                const ctx = makeCtx();
+                ctx.globalAlpha = 0.3;
+                ctx.save();
+                ctx.globalAlpha = 0.9;
+                ctx.restore();
+                expect(nearlyEqual(ctx.globalAlpha, 0.3)).toBe(true);
+            });
+
+            await it('save/restore round-trips globalCompositeOperation', async () => {
+                const ctx = makeCtx();
+                ctx.globalCompositeOperation = 'source-over';
+                ctx.save();
+                ctx.globalCompositeOperation = 'destination-over';
+                ctx.restore();
+                expect(ctx.globalCompositeOperation).toBe('source-over');
+            });
+        });
+
+        await describe('line properties', async () => {
+            await it('save/restore round-trips lineWidth', async () => {
+                const ctx = makeCtx();
+                ctx.lineWidth = 3;
+                ctx.save();
+                ctx.lineWidth = 10;
+                ctx.restore();
+                expect(ctx.lineWidth).toBe(3);
+            });
+
+            await it('save/restore round-trips lineCap and lineJoin', async () => {
+                const ctx = makeCtx();
+                ctx.lineCap = 'round';
+                ctx.lineJoin = 'bevel';
+                ctx.save();
+                ctx.lineCap = 'square';
+                ctx.lineJoin = 'miter';
+                ctx.restore();
+                expect(ctx.lineCap).toBe('round');
+                expect(ctx.lineJoin).toBe('bevel');
+            });
+
+            await it('save/restore round-trips miterLimit', async () => {
+                const ctx = makeCtx();
+                ctx.miterLimit = 5;
+                ctx.save();
+                ctx.miterLimit = 20;
+                ctx.restore();
+                expect(ctx.miterLimit).toBe(5);
+            });
+
+            await it('save/restore round-trips lineDash and lineDashOffset', async () => {
+                const ctx = makeCtx();
+                ctx.setLineDash([5, 2]);
+                ctx.lineDashOffset = 3;
+                ctx.save();
+                ctx.setLineDash([10, 10]);
+                ctx.lineDashOffset = 7;
+                ctx.restore();
+                const restored = ctx.getLineDash();
+                expect(restored.length).toBe(2);
+                expect(restored[0]).toBe(5);
+                expect(restored[1]).toBe(2);
+                expect(ctx.lineDashOffset).toBe(3);
+            });
+        });
+
+        await describe('text properties', async () => {
+            await it('save/restore round-trips font, textAlign, textBaseline', async () => {
+                const ctx = makeCtx();
+                ctx.font = 'bold 20px sans-serif';
+                ctx.textAlign = 'center';
+                ctx.textBaseline = 'middle';
+                ctx.save();
+                ctx.font = '10px serif';
+                ctx.textAlign = 'left';
+                ctx.textBaseline = 'top';
+                ctx.restore();
+                expect(ctx.font).toBe('bold 20px sans-serif');
+                expect(ctx.textAlign).toBe('center');
+                expect(ctx.textBaseline).toBe('middle');
+            });
+        });
+
+        await describe('shadow properties', async () => {
+            await it('save/restore round-trips shadow state', async () => {
+                const ctx = makeCtx();
+                ctx.shadowColor = '#abcdef';
+                ctx.shadowBlur = 5;
+                ctx.shadowOffsetX = 3;
+                ctx.shadowOffsetY = 7;
+                ctx.save();
+                ctx.shadowColor = '#000000';
+                ctx.shadowBlur = 0;
+                ctx.shadowOffsetX = 0;
+                ctx.shadowOffsetY = 0;
+                ctx.restore();
+                expect(ctx.shadowColor).toBe('#abcdef');
+                expect(ctx.shadowBlur).toBe(5);
+                expect(ctx.shadowOffsetX).toBe(3);
+                expect(ctx.shadowOffsetY).toBe(7);
+            });
+        });
+
+        await describe('imageSmoothing properties — Excalibur pixel-art regression', async () => {
+            // Locks the Phase D imageSmoothingEnabled=false fix. If any
+            // future refactor drops imageSmoothingEnabled from cloneState,
+            // save/restore would silently reset it to the default (true)
+            // and pixel-art sprites would render blurry again.
+            await it('save/restore round-trips imageSmoothingEnabled', async () => {
+                const ctx = makeCtx();
+                ctx.imageSmoothingEnabled = false;
+                ctx.save();
+                ctx.imageSmoothingEnabled = true;
+                ctx.restore();
+                expect(ctx.imageSmoothingEnabled).toBe(false);
+            });
+
+            await it('save/restore round-trips imageSmoothingQuality', async () => {
+                const ctx = makeCtx();
+                ctx.imageSmoothingQuality = 'high';
+                ctx.save();
+                ctx.imageSmoothingQuality = 'low';
+                ctx.restore();
+                expect(ctx.imageSmoothingQuality).toBe('high');
+            });
+        });
+
+        await describe('transform matrix', async () => {
+            await it('save/restore round-trips translation', async () => {
+                const ctx = makeCtx();
+                ctx.translate(10, 20);
+                ctx.save();
+                ctx.translate(50, 50);
+                const inner = ctx.getTransform();
+                expect(nearlyEqual(inner.e, 60)).toBe(true);
+                expect(nearlyEqual(inner.f, 70)).toBe(true);
+                ctx.restore();
+                const outer = ctx.getTransform();
+                expect(nearlyEqual(outer.e, 10)).toBe(true);
+                expect(nearlyEqual(outer.f, 20)).toBe(true);
+            });
+
+            await it('save/restore round-trips scale', async () => {
+                const ctx = makeCtx();
+                ctx.scale(2, 3);
+                ctx.save();
+                ctx.scale(5, 5);
+                ctx.restore();
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 2)).toBe(true);
+                expect(nearlyEqual(m.d, 3)).toBe(true);
+            });
+        });
+
+        await describe('nested save/restore stacks', async () => {
+            await it('triple save + triple restore returns to default', async () => {
+                const ctx = makeCtx();
+                ctx.save();
+                ctx.fillStyle = '#111111';
+                ctx.save();
+                ctx.fillStyle = '#222222';
+                ctx.save();
+                ctx.fillStyle = '#333333';
+                ctx.restore();
+                expect(ctx.fillStyle).toBe('#222222');
+                ctx.restore();
+                expect(ctx.fillStyle).toBe('#111111');
+                ctx.restore();
+                // Default fillStyle per spec is #000000
+                expect(ctx.fillStyle).toBe('#000000');
+            });
+
+            await it('restore() on empty stack is a no-op', async () => {
+                const ctx = makeCtx();
+                // Should not throw — Canvas 2D spec explicitly allows
+                // unbalanced restores.
+                expect(() => {
+                    ctx.restore();
+                    ctx.restore();
+                    ctx.restore();
+                }).not.toThrow();
+            });
+
+            await it('deep stack (50 saves) restores correctly', async () => {
+                const ctx = makeCtx();
+                const fills: string[] = [];
+                for (let i = 0; i < 50; i++) {
+                    ctx.save();
+                    ctx.fillStyle = '#' + (i * 7).toString(16).padStart(6, '0');
+                    fills.push(ctx.fillStyle as string);
+                }
+                for (let i = 49; i >= 0; i--) {
+                    expect(ctx.fillStyle).toBe(fills[i]);
+                    ctx.restore();
+                }
+            });
+        });
+    });
+};

package/src/canvas-transform.spec.ts

@@ -0,0 +1,211 @@
+// Canvas 2D transform tests — verifies Cairo.Context affine matrix
+// decomposition (translate + rotate + scale) and getTransform round-trip
+// via userToDevice. Cairo.Context in GJS does not expose a generic
+// transform(matrix) call, so canvas2d-core decomposes the supplied 2D
+// affine matrix [a,b,c,d,e,f] into primitive translate/rotate/scale calls.
+//
+// These tests lock in the fix made for the excalibur-jelly-jumper showcase,
+// which exercises multiply/transform/setTransform inside its Canvas 2D
+// fallback rendering path.
+
+import { describe, it, expect } from '@gjsify/unit';
+import { CanvasRenderingContext2D } from './canvas-rendering-context-2d.js';
+
+function makeCtx(width = 100, height = 100): CanvasRenderingContext2D {
+    const canvas = { width, height };
+    return new CanvasRenderingContext2D(canvas);
+}
+
+/** Assert two numbers are equal to within an epsilon. */
+function nearlyEqual(actual: number, expected: number, eps = 1e-9): boolean {
+    return Math.abs(actual - expected) < eps;
+}
+
+export default async () => {
+    await describe('CanvasRenderingContext2D — transforms', async () => {
+
+        await describe('getTransform initial state', async () => {
+            await it('returns identity for a fresh context', async () => {
+                const ctx = makeCtx();
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 1)).toBe(true);
+                expect(nearlyEqual(m.b, 0)).toBe(true);
+                expect(nearlyEqual(m.c, 0)).toBe(true);
+                expect(nearlyEqual(m.d, 1)).toBe(true);
+                expect(nearlyEqual(m.e, 0)).toBe(true);
+                expect(nearlyEqual(m.f, 0)).toBe(true);
+            });
+        });
+
+        await describe('translate', async () => {
+            await it('updates e and f in getTransform', async () => {
+                const ctx = makeCtx();
+                ctx.translate(10, 20);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 1)).toBe(true);
+                expect(nearlyEqual(m.d, 1)).toBe(true);
+                expect(nearlyEqual(m.e, 10)).toBe(true);
+                expect(nearlyEqual(m.f, 20)).toBe(true);
+            });
+
+            await it('composes translations cumulatively', async () => {
+                const ctx = makeCtx();
+                ctx.translate(10, 20);
+                ctx.translate(5, 7);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.e, 15)).toBe(true);
+                expect(nearlyEqual(m.f, 27)).toBe(true);
+            });
+        });
+
+        await describe('scale', async () => {
+            await it('updates a and d in getTransform', async () => {
+                const ctx = makeCtx();
+                ctx.scale(2, 3);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 2)).toBe(true);
+                expect(nearlyEqual(m.d, 3)).toBe(true);
+            });
+
+            await it('composes with a prior translate (translate then scale)', async () => {
+                const ctx = makeCtx();
+                ctx.translate(10, 20);
+                ctx.scale(2, 2);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 2)).toBe(true);
+                expect(nearlyEqual(m.d, 2)).toBe(true);
+                expect(nearlyEqual(m.e, 10)).toBe(true);
+                expect(nearlyEqual(m.f, 20)).toBe(true);
+            });
+        });
+
+        await describe('transform (multiply-by-affine)', async () => {
+            await it('pure translate via transform(1,0,0,1,tx,ty)', async () => {
+                const ctx = makeCtx();
+                ctx.transform(1, 0, 0, 1, 15, 25);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 1)).toBe(true);
+                expect(nearlyEqual(m.d, 1)).toBe(true);
+                expect(nearlyEqual(m.e, 15)).toBe(true);
+                expect(nearlyEqual(m.f, 25)).toBe(true);
+            });
+
+            await it('pure scale via transform(sx,0,0,sy,0,0)', async () => {
+                const ctx = makeCtx();
+                ctx.transform(3, 0, 0, 4, 0, 0);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 3)).toBe(true);
+                expect(nearlyEqual(m.d, 4)).toBe(true);
+            });
+
+            await it('ignores NaN / Infinity values without crashing', async () => {
+                const ctx = makeCtx();
+                // Excalibur can emit non-finite matrices during scene
+                // transitions — our Cairo binding must not crash on them.
+                ctx.transform(NaN, 0, 0, 1, 0, 0);
+                ctx.transform(1, 0, 0, 1, Infinity, 0);
+                // Transform was no-op'd, so state is still identity
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 1)).toBe(true);
+            });
+        });
+
+        await describe('setTransform', async () => {
+            await it('resets the matrix then applies the new transform (numeric)', async () => {
+                const ctx = makeCtx();
+                ctx.translate(100, 100);
+                ctx.setTransform(2, 0, 0, 2, 5, 10);
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 2)).toBe(true);
+                expect(nearlyEqual(m.d, 2)).toBe(true);
+                expect(nearlyEqual(m.e, 5)).toBe(true);
+                expect(nearlyEqual(m.f, 10)).toBe(true);
+            });
+
+            await it('accepts a DOMMatrix-like object (a,b,c,d,e,f)', async () => {
+                const ctx = makeCtx();
+                ctx.setTransform({ a: 2, b: 0, c: 0, d: 2, e: 5, f: 10 });
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 2)).toBe(true);
+                expect(nearlyEqual(m.d, 2)).toBe(true);
+                expect(nearlyEqual(m.e, 5)).toBe(true);
+                expect(nearlyEqual(m.f, 10)).toBe(true);
+            });
+
+            await it('no-arg resets to identity', async () => {
+                const ctx = makeCtx();
+                ctx.translate(10, 10);
+                ctx.scale(5, 5);
+                ctx.setTransform();
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 1)).toBe(true);
+                expect(nearlyEqual(m.d, 1)).toBe(true);
+                expect(nearlyEqual(m.e, 0)).toBe(true);
+                expect(nearlyEqual(m.f, 0)).toBe(true);
+            });
+        });
+
+        await describe('save / restore', async () => {
+            await it('restore reverts the matrix set inside a save block', async () => {
+                const ctx = makeCtx();
+                ctx.translate(10, 20);
+                ctx.save();
+                ctx.scale(5, 5);
+                ctx.translate(100, 200);
+                ctx.restore();
+                const m = ctx.getTransform();
+                expect(nearlyEqual(m.a, 1)).toBe(true);
+                expect(nearlyEqual(m.d, 1)).toBe(true);
+                expect(nearlyEqual(m.e, 10)).toBe(true);
+                expect(nearlyEqual(m.f, 20)).toBe(true);
+            });
+        });
+
+        await describe('Excalibur-style multiply pattern', async () => {
+            await it('ctx.setTransform(ctx.getTransform().multiply(other)) round-trips', async () => {
+                // getTransform returns a real DOMMatrix instance only when
+                // globalThis.DOMMatrix is installed (via @gjsify/dom-elements).
+                // Inject a minimal DOMMatrix for this test so the multiply
+                // code path runs end-to-end.
+                if (typeof (globalThis as any).DOMMatrix === 'undefined') {
+                    class TestDOMMatrix {
+                        a = 1; b = 0; c = 0; d = 1; e = 0; f = 0;
+                        constructor(init?: number[]) {
+                            if (Array.isArray(init) && init.length === 6) {
+                                this.a = init[0]; this.b = init[1];
+                                this.c = init[2]; this.d = init[3];
+                                this.e = init[4]; this.f = init[5];
+                            }
+                        }
+                        multiply(o: { a: number; b: number; c: number; d: number; e: number; f: number }) {
+                            const a = this.a * o.a + this.c * o.b;
+                            const b = this.b * o.a + this.d * o.b;
+                            const c = this.a * o.c + this.c * o.d;
+                            const d = this.b * o.c + this.d * o.d;
+                            const e = this.a * o.e + this.c * o.f + this.e;
+                            const f = this.b * o.e + this.d * o.f + this.f;
+                            return new TestDOMMatrix([a, b, c, d, e, f]);
+                        }
+                    }
+                    (globalThis as any).DOMMatrix = TestDOMMatrix;
+                }
+
+                const ctx = makeCtx();
+                ctx.translate(50, 50);
+                // Simulate Excalibur's GraphicsContext2DCanvas.multiply():
+                //     ctx.setTransform(ctx.getTransform().multiply(otherMatrix))
+                const current = ctx.getTransform() as any;
+                expect(typeof current.multiply).toBe('function');
+                const other = { a: 2, b: 0, c: 0, d: 2, e: 0, f: 0 } as any;
+                const composed = current.multiply(other);
+                ctx.setTransform(composed);
+                const final = ctx.getTransform();
+                // translate(50,50) then scale(2,2) → matrix [2,0,0,2,50,50]
+                expect(nearlyEqual(final.a, 2)).toBe(true);
+                expect(nearlyEqual(final.d, 2)).toBe(true);
+                expect(nearlyEqual(final.e, 50)).toBe(true);
+                expect(nearlyEqual(final.f, 50)).toBe(true);
+            });
+        });
+    });
+};

package/src/color.ts

@@ -53,7 +53,11 @@ const NAMED_COLORS: Record<string, string> = {
 
 /**
  * Parse a CSS color string into RGBA components (0-1 range).
- * Supports: #rgb, #rrggbb, #rgba, #rrggbbaa, rgb(), rgba(), named colors, 'transparent'.
+ * Supports: #rgb, #rrggbb, #rgba, #rrggbbaa, rgb(), rgba(), hsl(), hsla(), named colors, 'transparent'.
+ *
+ * Also handles Excalibur's non-standard HSL format where h/s/l are all in 0-1 range (not degrees/%).
+ * Excalibur's Color.toString() returns `hsla(h, s, l, a)` with values in 0-1 normalized form
+ * (e.g. Color.White → "hsla(0, 0, 1, 1)", Color.Black → "hsla(0, 0, 0, 1)").
  */
 export function parseColor(color: string): RGBA | null {
     if (!color || typeof color !== 'string') return null;
@@ -80,6 +84,31 @@ export function parseColor(color: string): RGBA | null {
         };
     }
 
+    // hsl()/hsla() — handles both standard CSS (degrees, %) and Excalibur's 0-1 normalized form.
+    // Heuristic: if s/l have no % and are ≤ 1, treat as 0-1 normalized; if h > 1, treat as degrees.
+    const hslMatch = trimmed.match(
+        /^hsla?\(\s*(\d+(?:\.\d+)?)\s*[,\s]\s*(\d+(?:\.\d+)?)(%)?\s*[,\s]\s*(\d+(?:\.\d+)?)(%)?\s*(?:[,/]\s*(\d+(?:\.\d+)?%?))?\s*\)$/
+    );
+    if (hslMatch) {
+        let h = parseFloat(hslMatch[1]);
+        let s = parseFloat(hslMatch[2]);
+        const sPct = hslMatch[3] === '%';
+        let l = parseFloat(hslMatch[4]);
+        const lPct = hslMatch[5] === '%';
+        const a = hslMatch[6] !== undefined ? parseComponent(hslMatch[6], 1) : 1;
+
+        // Normalize h to 0-1 range: if > 1, it's degrees (0-360)
+        if (h > 1) h /= 360;
+        // Normalize s to 0-1 range
+        if (sPct) s /= 100;
+        else if (s > 1) s /= 100;
+        // Normalize l to 0-1 range
+        if (lPct) l /= 100;
+        else if (l > 1) l /= 100;
+
+        return hslToRGBA(h, s, l, Math.max(0, Math.min(1, a)));
+    }
+
     return null;
 }
 
@@ -119,6 +148,29 @@ function parseComponent(value: string, max: number): number {
     return parseFloat(value);
 }
 
+function hue2rgb(p: number, q: number, t: number): number {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+}
+
+function hslToRGBA(h: number, s: number, l: number, a: number): RGBA {
+    let r: number, g: number, b: number;
+    if (s === 0) {
+        r = g = b = l;
+    } else {
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        const p = 2 * l - q;
+        r = hue2rgb(p, q, h + 1 / 3);
+        g = hue2rgb(p, q, h);
+        b = hue2rgb(p, q, h - 1 / 3);
+    }
+    return { r, g, b, a };
+}
+
 /** Default color: opaque black */
 export const BLACK: RGBA = { r: 0, g: 0, b: 0, a: 1 };
 /** Transparent black */

package/src/test.mts

@@ -2,5 +2,21 @@
 import { run } from '@gjsify/unit';
 
 import canvasTextSuite from './canvas-text.spec.js';
+import canvasTransformSuite from './canvas-transform.spec.js';
+import canvasDrawimageSuite from './canvas-drawimage.spec.js';
+import canvasStateSuite from './canvas-state.spec.js';
+import canvasClearingSuite from './canvas-clearing.spec.js';
+import canvasImagedataSuite from './canvas-imagedata.spec.js';
+import canvasCompositeSuite from './canvas-composite.spec.js';
+import canvasColorSuite from './canvas-color.spec.js';
 
-run({ testSuite: canvasTextSuite });
+run({
+    canvasTextSuite,
+    canvasTransformSuite,
+    canvasDrawimageSuite,
+    canvasStateSuite,
+    canvasClearingSuite,
+    canvasImagedataSuite,
+    canvasCompositeSuite,
+    canvasColorSuite,
+});