@gjsify/canvas2d-core 0.1.3

package/src/canvas-state.ts

@@ -0,0 +1,77 @@
+// Drawing state for Canvas 2D context save()/restore() stack.
+// Each save() pushes a clone of the current state; restore() pops it.
+
+import type { RGBA } from './color.js';
+import { BLACK } from './color.js';
+
+export interface CanvasState {
+    // Fill & stroke
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    fillColor: RGBA;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    strokeColor: RGBA;
+
+    // Line properties
+    lineWidth: number;
+    lineCap: CanvasLineCap;
+    lineJoin: CanvasLineJoin;
+    miterLimit: number;
+    lineDash: number[];
+    lineDashOffset: number;
+
+    // Compositing
+    globalAlpha: number;
+    globalCompositeOperation: GlobalCompositeOperation;
+
+    // Shadows (Phase 5 — tracked in state for save/restore correctness)
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+
+    // Text (Phase 4)
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    direction: CanvasDirection;
+
+    // Image smoothing
+    imageSmoothingEnabled: boolean;
+    imageSmoothingQuality: ImageSmoothingQuality;
+}
+
+export function createDefaultState(): CanvasState {
+    return {
+        fillStyle: '#000000',
+        fillColor: { ...BLACK },
+        strokeStyle: '#000000',
+        strokeColor: { ...BLACK },
+        lineWidth: 1,
+        lineCap: 'butt',
+        lineJoin: 'miter',
+        miterLimit: 10,
+        lineDash: [],
+        lineDashOffset: 0,
+        globalAlpha: 1,
+        globalCompositeOperation: 'source-over',
+        shadowColor: 'rgba(0, 0, 0, 0)',
+        shadowBlur: 0,
+        shadowOffsetX: 0,
+        shadowOffsetY: 0,
+        font: '10px sans-serif',
+        textAlign: 'start',
+        textBaseline: 'alphabetic',
+        direction: 'ltr',
+        imageSmoothingEnabled: true,
+        imageSmoothingQuality: 'low',
+    };
+}
+
+export function cloneState(state: CanvasState): CanvasState {
+    return {
+        ...state,
+        fillColor: { ...state.fillColor },
+        strokeColor: { ...state.strokeColor },
+        lineDash: [...state.lineDash],
+    };
+}

package/src/canvas-text.spec.ts

@@ -0,0 +1,241 @@
+// Canvas 2D text rendering tests — baseline positioning and alignment
+// Reference: refs/wpt/html/canvas/element/text/2d.text.draw.baseline.*.html
+// Ported from W3C WPT canvas text tests (3-Clause BSD, web-platform-tests contributors)
+// Reimplemented for GJS using PangoCairo (no DOM, no font face loading)
+
+import { describe, it, expect } from '@gjsify/unit';
+import { CanvasRenderingContext2D } from './canvas-rendering-context-2d.js';
+
+// --- Helpers ---
+
+/**
+ * Create a minimal canvas mock + context for testing.
+ * CanvasRenderingContext2D only needs canvas.width / canvas.height.
+ */
+function makeCtx(width: number, height: number): CanvasRenderingContext2D {
+    const canvas = { width, height };
+    return new CanvasRenderingContext2D(canvas);
+}
+
+/**
+ * Find the first and last row (y-coordinate) that contains at least one
+ * "green" pixel (G > 128, R < 64, B < 64) in the given ImageData.
+ * Returns { first: -1, last: -1 } when no green pixel is found.
+ */
+function findGreenRowBounds(data: Uint8ClampedArray, width: number, height: number) {
+    let first = -1;
+    let last = -1;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = (y * width + x) * 4;
+            if (data[i + 1] > 128 && data[i] < 64 && data[i + 2] < 64) {
+                if (first === -1) first = y;
+                last = y;
+                break;
+            }
+        }
+    }
+    return { first, last };
+}
+
+/**
+ * Draw text on a background-filled canvas and return the bounding rows of the
+ * rendered text pixels.
+ *
+ * @param baseline CSS textBaseline value
+ * @param yCoord   The y argument passed to fillText
+ * @param width    Canvas width
+ * @param height   Canvas height
+ */
+function drawAndMeasure(
+    baseline: CanvasTextBaseline,
+    yCoord: number,
+    width = 300,
+    height = 100,
+) {
+    const ctx = makeCtx(width, height);
+
+    // Red background
+    ctx.fillStyle = '#f00';
+    ctx.fillRect(0, 0, width, height);
+
+    // Green text — use a wide string to guarantee pixels across multiple columns
+    ctx.fillStyle = '#0f0';
+    ctx.font = '24px sans-serif';
+    ctx.textBaseline = baseline;
+    ctx.textAlign = 'left';
+    ctx.fillText('XXXXXXX', 0, yCoord);
+
+    const imageData = ctx.getImageData(0, 0, width, height);
+    return findGreenRowBounds(imageData.data, width, height);
+}
+
+// --- Tests ---
+
+export default async () => {
+
+    await describe('CanvasRenderingContext2D.fillText — textBaseline positioning', async () => {
+
+        // textBaseline='top': text top edge is at the provided y coordinate.
+        // With y=5, the first green row must appear near y=5 (within ±8px).
+        await it("textBaseline='top': text starts near y", async () => {
+            const { first, last } = drawAndMeasure('top', 5);
+            expect(first).toBeGreaterThan(-1); // text was rendered
+            expect(first).toBeLessThan(15);    // top edge close to y=5
+            expect(last).toBeGreaterThan(first); // text has height
+        });
+
+        // textBaseline='bottom': text bottom edge is at y. With y=95 on a 100px canvas,
+        // the last green row must appear near y=95 (within ±8px).
+        await it("textBaseline='bottom': text ends near y", async () => {
+            const { first, last } = drawAndMeasure('bottom', 95, 300, 100);
+            expect(last).toBeGreaterThan(-1);  // text was rendered
+            expect(last).toBeGreaterThan(85);  // bottom edge close to y=95
+            expect(first).toBeLessThan(last);  // text has height
+        });
+
+        // textBaseline='middle': the vertical midpoint of the text is at y.
+        // With y=50 on a 100px canvas, text must span across the center:
+        // first green row < 50 AND last green row > 50.
+        await it("textBaseline='middle': text is centered on y", async () => {
+            const { first, last } = drawAndMeasure('middle', 50, 300, 100);
+            expect(first).toBeGreaterThan(-1);
+            expect(first).toBeLessThan(50);    // text extends above center
+            expect(last).toBeGreaterThan(50);  // text extends below center
+        });
+
+        // textBaseline='alphabetic': the baseline (a reference Latin line) is at y.
+        // Ascent extends above y, descent extends below.
+        // With y=50 on a 100px canvas:
+        //   - first green row < 50 (ascent above baseline)
+        //   - last green row > 50  (descent below baseline — use 'g' which has a descender)
+        await it("textBaseline='alphabetic': baseline is at y, ascent above, descent below", async () => {
+            // Use text with descenders (g, p, q, y) so pixels extend below the baseline.
+            const canvas = { width: 300, height: 100 };
+            const ctx = new CanvasRenderingContext2D(canvas);
+            ctx.fillStyle = '#f00';
+            ctx.fillRect(0, 0, 300, 100);
+            ctx.fillStyle = '#0f0';
+            ctx.font = '24px sans-serif';
+            ctx.textBaseline = 'alphabetic';
+            ctx.textAlign = 'left';
+            ctx.fillText('Xgpqy', 0, 50); // descenders ensure pixels below baseline
+            const imageData = ctx.getImageData(0, 0, 300, 100);
+            const { first, last } = findGreenRowBounds(imageData.data, 300, 100);
+            expect(first).toBeGreaterThan(-1);
+            expect(first).toBeLessThan(50);    // text extends above y
+            expect(last).toBeGreaterThan(50);  // descent below y
+        });
+
+        // textBaseline='hanging': the hanging baseline is at y (used for Devanagari etc.).
+        // Approximates the top of the cap height (~0.8 * ascent below the em-square top).
+        // Most of the text should extend BELOW y, with very little above.
+        await it("textBaseline='hanging': text mostly extends below y", async () => {
+            const { first, last } = drawAndMeasure('hanging', 5, 300, 100);
+            expect(first).toBeGreaterThan(-1);
+            // Text should start near y=5; because hanging ≈ 0.2*ascent from top,
+            // first green row should be within 10px of y=5.
+            expect(first).toBeLessThan(20);
+            expect(last).toBeGreaterThan(first);
+        });
+
+        // textBaseline='ideographic': ideographic baseline is at y.
+        // Below the alphabetic baseline; the bulk of text is ABOVE y.
+        await it("textBaseline='ideographic': most text is above y", async () => {
+            const { first, last } = drawAndMeasure('ideographic', 70, 300, 100);
+            expect(first).toBeGreaterThan(-1);
+            expect(first).toBeLessThan(70);  // text extends above y
+            // last may be ≥ 70 (descent below ideographic line) or ≤ 70
+            expect(last).toBeGreaterThan(first);
+        });
+
+        // Regression: 'top' at y=0 should NOT be far below y=0.
+        // Before fix, yOff = +ascent pushed text ~20px too low (wrong).
+        await it("textBaseline='top' regression: first pixel is near y=0, not shifted down by ascent", async () => {
+            const { first } = drawAndMeasure('top', 0, 300, 80);
+            // Before fix: first ≈ 18+ (shifted by ascent). After fix: first ≈ 0-9
+            // (exact value varies with PangoCairo version and font hinting).
+            expect(first).toBeLessThan(12);
+        });
+
+        // Regression: 'alphabetic' at y=40 should put text above AND below y=40.
+        // Before fix, yOff=0 put the layout TOP at y=40, so all text was below y=40.
+        await it("textBaseline='alphabetic' regression: text extends above y, not only below", async () => {
+            const { first } = drawAndMeasure('alphabetic', 40, 300, 80);
+            expect(first).toBeLessThan(40);  // ascent extends above y=40
+        });
+
+        // Regression: 'middle' at y=40 with 24px font → text spans ~28..52
+        // Before fix: yOff = ascent - height/2 ≈ +10, so layout top at ~50, text at 50..74
+        //             → first ≈ 50, which is NOT less than 40.
+        await it("textBaseline='middle' regression: text straddles y, not shifted below y", async () => {
+            const { first } = drawAndMeasure('middle', 40, 300, 80);
+            expect(first).toBeLessThan(40);
+        });
+    });
+
+    await describe('CanvasRenderingContext2D.fillText — textAlign positioning', async () => {
+
+        await it("textAlign='center': text is centered on x", async () => {
+            const width = 200;
+            const height = 60;
+            const ctx = makeCtx(width, height);
+            ctx.fillStyle = '#f00';
+            ctx.fillRect(0, 0, width, height);
+            ctx.fillStyle = '#0f0';
+            ctx.font = '20px sans-serif';
+            ctx.textBaseline = 'top';
+            ctx.textAlign = 'center';
+            ctx.fillText('XX', width / 2, 0);
+
+            const imageData = ctx.getImageData(0, 0, width, height);
+            // Find leftmost and rightmost green column
+            let leftCol = -1, rightCol = -1;
+            for (let x = 0; x < width; x++) {
+                for (let y = 0; y < height; y++) {
+                    const i = (y * width + x) * 4;
+                    if (imageData.data[i + 1] > 128 && imageData.data[i] < 64 && imageData.data[i + 2] < 64) {
+                        if (leftCol === -1) leftCol = x;
+                        rightCol = x;
+                        break;
+                    }
+                }
+            }
+            expect(leftCol).toBeGreaterThan(-1);
+            // Text should be roughly centered: left and right distances from center should be similar
+            const distLeft = width / 2 - leftCol;
+            const distRight = rightCol - width / 2;
+            // Both sides should have roughly equal extent (within 20px)
+            expect(Math.abs(distLeft - distRight)).toBeLessThan(20);
+        });
+
+        await it("textAlign='left': text starts at x", async () => {
+            const width = 200;
+            const height = 60;
+            const ctx = makeCtx(width, height);
+            ctx.fillStyle = '#f00';
+            ctx.fillRect(0, 0, width, height);
+            ctx.fillStyle = '#0f0';
+            ctx.font = '20px sans-serif';
+            ctx.textBaseline = 'top';
+            ctx.textAlign = 'left';
+            ctx.fillText('XX', 20, 0);
+
+            const imageData = ctx.getImageData(0, 0, width, height);
+            let leftCol = -1;
+            outer: for (let x = 0; x < width; x++) {
+                for (let y = 0; y < height; y++) {
+                    const i = (y * width + x) * 4;
+                    if (imageData.data[i + 1] > 128 && imageData.data[i] < 64 && imageData.data[i + 2] < 64) {
+                        leftCol = x;
+                        break outer;
+                    }
+                }
+            }
+            // leftmost green pixel should be near x=20
+            expect(leftCol).toBeGreaterThan(-1);
+            expect(leftCol).toBeGreaterThan(14);
+            expect(leftCol).toBeLessThan(30);
+        });
+    });
+};

package/src/color.ts

@@ -0,0 +1,125 @@
+// CSS color parser for Canvas 2D context
+// Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+
+export interface RGBA {
+    r: number; // 0-1
+    g: number; // 0-1
+    b: number; // 0-1
+    a: number; // 0-1
+}
+
+// CSS named colors (all 148 standard colors)
+const NAMED_COLORS: Record<string, string> = {
+    aliceblue: '#f0f8ff', antiquewhite: '#faebd7', aqua: '#00ffff', aquamarine: '#7fffd4',
+    azure: '#f0ffff', beige: '#f5f5dc', bisque: '#ffe4c4', black: '#000000',
+    blanchedalmond: '#ffebcd', blue: '#0000ff', blueviolet: '#8a2be2', brown: '#a52a2a',
+    burlywood: '#deb887', cadetblue: '#5f9ea0', chartreuse: '#7fff00', chocolate: '#d2691e',
+    coral: '#ff7f50', cornflowerblue: '#6495ed', cornsilk: '#fff8dc', crimson: '#dc143c',
+    cyan: '#00ffff', darkblue: '#00008b', darkcyan: '#008b8b', darkgoldenrod: '#b8860b',
+    darkgray: '#a9a9a9', darkgreen: '#006400', darkgrey: '#a9a9a9', darkkhaki: '#bdb76b',
+    darkmagenta: '#8b008b', darkolivegreen: '#556b2f', darkorange: '#ff8c00', darkorchid: '#9932cc',
+    darkred: '#8b0000', darksalmon: '#e9967a', darkseagreen: '#8fbc8f', darkslateblue: '#483d8b',
+    darkslategray: '#2f4f4f', darkslategrey: '#2f4f4f', darkturquoise: '#00ced1', darkviolet: '#9400d3',
+    deeppink: '#ff1493', deepskyblue: '#00bfff', dimgray: '#696969', dimgrey: '#696969',
+    dodgerblue: '#1e90ff', firebrick: '#b22222', floralwhite: '#fffaf0', forestgreen: '#228b22',
+    fuchsia: '#ff00ff', gainsboro: '#dcdcdc', ghostwhite: '#f8f8ff', gold: '#ffd700',
+    goldenrod: '#daa520', gray: '#808080', green: '#008000', greenyellow: '#adff2f',
+    grey: '#808080', honeydew: '#f0fff0', hotpink: '#ff69b4', indianred: '#cd5c5c',
+    indigo: '#4b0082', ivory: '#fffff0', khaki: '#f0e68c', lavender: '#e6e6fa',
+    lavenderblush: '#fff0f5', lawngreen: '#7cfc00', lemonchiffon: '#fffacd', lightblue: '#add8e6',
+    lightcoral: '#f08080', lightcyan: '#e0ffff', lightgoldenrodyellow: '#fafad2', lightgray: '#d3d3d3',
+    lightgreen: '#90ee90', lightgrey: '#d3d3d3', lightpink: '#ffb6c1', lightsalmon: '#ffa07a',
+    lightseagreen: '#20b2aa', lightskyblue: '#87cefa', lightslategray: '#778899', lightslategrey: '#778899',
+    lightsteelblue: '#b0c4de', lightyellow: '#ffffe0', lime: '#00ff00', limegreen: '#32cd32',
+    linen: '#faf0e6', magenta: '#ff00ff', maroon: '#800000', mediumaquamarine: '#66cdaa',
+    mediumblue: '#0000cd', mediumorchid: '#ba55d3', mediumpurple: '#9370db', mediumseagreen: '#3cb371',
+    mediumslateblue: '#7b68ee', mediumspringgreen: '#00fa9a', mediumturquoise: '#48d1cc',
+    mediumvioletred: '#c71585', midnightblue: '#191970', mintcream: '#f5fffa', mistyrose: '#ffe4e1',
+    moccasin: '#ffe4b5', navajowhite: '#ffdead', navy: '#000080', oldlace: '#fdf5e6',
+    olive: '#808000', olivedrab: '#6b8e23', orange: '#ffa500', orangered: '#ff4500',
+    orchid: '#da70d6', palegoldenrod: '#eee8aa', palegreen: '#98fb98', paleturquoise: '#afeeee',
+    palevioletred: '#db7093', papayawhip: '#ffefd5', peachpuff: '#ffdab9', peru: '#cd853f',
+    pink: '#ffc0cb', plum: '#dda0dd', powderblue: '#b0e0e6', purple: '#800080',
+    rebeccapurple: '#663399', red: '#ff0000', rosybrown: '#bc8f8f', royalblue: '#4169e1',
+    saddlebrown: '#8b4513', salmon: '#fa8072', sandybrown: '#f4a460', seagreen: '#2e8b57',
+    seashell: '#fff5ee', sienna: '#a0522d', silver: '#c0c0c0', skyblue: '#87ceeb',
+    slateblue: '#6a5acd', slategray: '#708090', slategrey: '#708090', snow: '#fffafa',
+    springgreen: '#00ff7f', steelblue: '#4682b4', tan: '#d2b48c', teal: '#008080',
+    thistle: '#d8bfd8', tomato: '#ff6347', turquoise: '#40e0d0', violet: '#ee82ee',
+    wheat: '#f5deb3', white: '#ffffff', whitesmoke: '#f5f5f5', yellow: '#ffff00',
+    yellowgreen: '#9acd32',
+    transparent: '#00000000',
+};
+
+/**
+ * Parse a CSS color string into RGBA components (0-1 range).
+ * Supports: #rgb, #rrggbb, #rgba, #rrggbbaa, rgb(), rgba(), named colors, 'transparent'.
+ */
+export function parseColor(color: string): RGBA | null {
+    if (!color || typeof color !== 'string') return null;
+
+    const trimmed = color.trim().toLowerCase();
+
+    // Named colors
+    const named = NAMED_COLORS[trimmed];
+    if (named) return parseHex(named);
+
+    // Hex formats
+    if (trimmed.startsWith('#')) return parseHex(trimmed);
+
+    // rgb()/rgba()
+    const rgbMatch = trimmed.match(
+        /^rgba?\(\s*(\d+(?:\.\d+)?%?)\s*[,\s]\s*(\d+(?:\.\d+)?%?)\s*[,\s]\s*(\d+(?:\.\d+)?%?)\s*(?:[,/]\s*(\d+(?:\.\d+)?%?))?\s*\)$/
+    );
+    if (rgbMatch) {
+        return {
+            r: parseComponent(rgbMatch[1], 255) / 255,
+            g: parseComponent(rgbMatch[2], 255) / 255,
+            b: parseComponent(rgbMatch[3], 255) / 255,
+            a: rgbMatch[4] !== undefined ? parseComponent(rgbMatch[4], 1) : 1,
+        };
+    }
+
+    return null;
+}
+
+function parseHex(hex: string): RGBA | null {
+    const h = hex.slice(1);
+    let r: number, g: number, b: number, a = 1;
+
+    if (h.length === 3) {
+        r = parseInt(h[0] + h[0], 16) / 255;
+        g = parseInt(h[1] + h[1], 16) / 255;
+        b = parseInt(h[2] + h[2], 16) / 255;
+    } else if (h.length === 4) {
+        r = parseInt(h[0] + h[0], 16) / 255;
+        g = parseInt(h[1] + h[1], 16) / 255;
+        b = parseInt(h[2] + h[2], 16) / 255;
+        a = parseInt(h[3] + h[3], 16) / 255;
+    } else if (h.length === 6) {
+        r = parseInt(h.slice(0, 2), 16) / 255;
+        g = parseInt(h.slice(2, 4), 16) / 255;
+        b = parseInt(h.slice(4, 6), 16) / 255;
+    } else if (h.length === 8) {
+        r = parseInt(h.slice(0, 2), 16) / 255;
+        g = parseInt(h.slice(2, 4), 16) / 255;
+        b = parseInt(h.slice(4, 6), 16) / 255;
+        a = parseInt(h.slice(6, 8), 16) / 255;
+    } else {
+        return null;
+    }
+
+    return { r, g, b, a };
+}
+
+function parseComponent(value: string, max: number): number {
+    if (value.endsWith('%')) {
+        return (parseFloat(value) / 100) * max;
+    }
+    return parseFloat(value);
+}
+
+/** Default color: opaque black */
+export const BLACK: RGBA = { r: 0, g: 0, b: 0, a: 1 };
+/** Transparent black */
+export const TRANSPARENT: RGBA = { r: 0, g: 0, b: 0, a: 0 };

package/src/image-data.ts

@@ -0,0 +1,34 @@
+// ImageData implementation for Canvas 2D context
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/ImageData
+
+/**
+ * ImageData represents the pixel data of a canvas area.
+ * Each pixel is 4 bytes: R, G, B, A (0-255 each).
+ */
+export class OurImageData {
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly colorSpace: PredefinedColorSpace = 'srgb';
+
+    constructor(sw: number, sh: number);
+    constructor(data: Uint8ClampedArray, sw: number, sh?: number);
+    constructor(swOrData: number | Uint8ClampedArray, sh: number, maybeHeight?: number) {
+        if (typeof swOrData === 'number') {
+            // new ImageData(width, height)
+            this.width = swOrData;
+            this.height = sh;
+            this.data = new Uint8ClampedArray(this.width * this.height * 4);
+        } else {
+            // new ImageData(data, width[, height])
+            this.data = swOrData;
+            this.width = sh;
+            this.height = maybeHeight ?? (this.data.length / (4 * this.width));
+            if (this.data.length !== this.width * this.height * 4) {
+                throw new RangeError(
+                    `Source data length ${this.data.length} is not a multiple of (4 * width=${this.width})`
+                );
+            }
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Cairo-backed Canvas 2D core — no @gjsify/dom-elements dependency.
+// Extracted from @gjsify/canvas2d so @gjsify/dom-elements can depend on it
+// without creating a circular dependency.
+//
+// @gjsify/dom-elements imports this package to auto-register the '2d' context
+// factory on HTMLCanvasElement, mirroring browser behavior where
+// canvas.getContext('2d') works without any explicit import.
+
+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';

package/src/test.mts

@@ -0,0 +1,6 @@
+
+import { run } from '@gjsify/unit';
+
+import canvasTextSuite from './canvas-text.spec.js';
+
+run({ testSuite: canvasTextSuite });