@gjsify/dom-elements 0.1.8 → 0.1.9

package/lib/types/dom-matrix.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal DOMMatrix implementation — supports 2D and 3D construction, plus
+ * 2D multiply/inverse/translate/scale operations used by Canvas 2D libraries
+ * like Excalibur. Full 3D math (4x4 multiply, inverse) is NOT implemented.
+ */
+export declare class DOMMatrix {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+    m11: number;
+    m12: number;
+    m13: number;
+    m14: number;
+    m21: number;
+    m22: number;
+    m23: number;
+    m24: number;
+    m31: number;
+    m32: number;
+    m33: number;
+    m34: number;
+    m41: number;
+    m42: number;
+    m43: number;
+    m44: number;
+    is2D: boolean;
+    isIdentity: boolean;
+    constructor(init?: number[] | string);
+    /**
+     * Multiply this 2D matrix by another 2D matrix and return a new matrix.
+     * [a c e] [a' c' e']   [a*a'+c*b'  a*c'+c*d'  a*e'+c*f'+e]
+     * [b d f] [b' d' f'] = [b*a'+d*b'  b*c'+d*d'  b*e'+d*f'+f]
+     * [0 0 1] [0  0  1 ]   [0          0          1           ]
+     */
+    multiply(other: {
+        a: number;
+        b: number;
+        c: number;
+        d: number;
+        e: number;
+        f: number;
+    }): DOMMatrix;
+    /** In-place multiply; returns this. */
+    multiplySelf(other: {
+        a: number;
+        b: number;
+        c: number;
+        d: number;
+        e: number;
+        f: number;
+    }): DOMMatrix;
+    /** 2D inverse. Throws if non-invertible (det === 0). */
+    inverse(): DOMMatrix;
+    translate(tx?: number, ty?: number): DOMMatrix;
+    scale(sx?: number, sy?: number): DOMMatrix;
+}
+/**
+ * DOMMatrixReadOnly alias — MDN specifies this as the immutable base class.
+ * We expose the same impl since consumers (Excalibur, three.js) rarely care.
+ */
+export declare const DOMMatrixReadOnly: typeof DOMMatrix;

package/lib/types/font-face.d.ts

@@ -0,0 +1,45 @@
+export declare class FontFace {
+    readonly family: string;
+    readonly source: string;
+    status: 'unloaded' | 'loading' | 'loaded' | 'error';
+    loaded: Promise<FontFace>;
+    display: string;
+    style: string;
+    weight: string;
+    stretch: string;
+    unicodeRange: string;
+    variant: string;
+    featureSettings: string;
+    constructor(family: string, source: string | ArrayBuffer | ArrayBufferView, _descriptors?: Record<string, string>);
+    private _extractFilePath;
+    load(): Promise<FontFace>;
+}
+/**
+ * FontFaceSet — tracks loaded FontFace objects and exposes them to consumers.
+ *
+ * Intentionally does NOT extend EventTarget. The dom-elements /register module
+ * runs before dom-events/register in the inject order, so EventTarget may not
+ * yet exist when this class is defined at module load time. All event methods
+ * are provided as no-ops; consumers that call addEventListener('loadingdone')
+ * etc. will silently receive nothing.
+ */
+export declare class FontFaceSet {
+    status: 'loading' | 'loaded';
+    ready: Promise<FontFaceSet>;
+    private _faces;
+    addEventListener(_type: string, _listener: unknown): void;
+    removeEventListener(_type: string, _listener: unknown): void;
+    dispatchEvent(_event: unknown): boolean;
+    add(face: FontFace): FontFaceSet;
+    delete(face: FontFace): boolean;
+    clear(): void;
+    has(face: FontFace): boolean;
+    check(_font: string, _text?: string): boolean;
+    load(_font: string, _text?: string): Promise<FontFace[]>;
+    forEach(callback: (value: FontFace, key: FontFace, parent: FontFaceSet) => void): void;
+    values(): IterableIterator<FontFace>;
+    keys(): IterableIterator<FontFace>;
+    entries(): IterableIterator<[FontFace, FontFace]>;
+    [Symbol.iterator](): Iterator<FontFace>;
+    get size(): number;
+}

package/lib/types/html-element.d.ts

@@ -7,7 +7,15 @@ import { Element } from './element.js';
  */
 export declare class CSSStyleDeclaration {
     [key: string]: unknown;
-    cssText: string;
+    private _cssText;
+    /** Setting cssText parses individual declarations and stores them as camelCase properties,
+     *  matching browser behavior for feature-detection checks like Excalibur's rgbaSupport. */
+    get cssText(): string;
+    set cssText(value: string);
+    setProperty(property: string, value: string, _priority?: string): void;
+    getPropertyValue(property: string): string;
+    removeProperty(property: string): string;
+    getPropertyPriority(_property: string): string;
 }
 /**
  * HTML Element base class.
@@ -16,6 +24,7 @@ export declare class CSSStyleDeclaration {
  */
 export declare class HTMLElement extends Element {
     readonly style: CSSStyleDeclaration;
+    get dataset(): Record<string, string>;
     get title(): string;
     set title(value: string);
     get lang(): string;

package/lib/types/html-image-element.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -19,3 +19,7 @@ export { IntersectionObserver } from './intersection-observer.js';
 export { NodeType } from './node-type.js';
 export { NamespaceURI } from './namespace-uri.js';
 export * as PropertySymbol from './property-symbol.js';
+export { FontFace, FontFaceSet } from './font-face.js';
+export { MediaQueryList, matchMedia } from './match-media.js';
+export { location } from './location-stub.js';
+export { DOMMatrix, DOMMatrixReadOnly } from './dom-matrix.js';

package/lib/types/location-stub.d.ts

@@ -0,0 +1,21 @@
+export declare const location: {
+    href: string;
+    origin: string;
+    protocol: string;
+    host: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    search: string;
+    hash: string;
+    assign(_url: string): void;
+    replace(_url: string): void;
+    reload(): void;
+    toString(): string;
+    ancestorOrigins: {
+        length: number;
+        item: () => null;
+        contains: () => boolean;
+        [Symbol.iterator]: () => Generator<string>;
+    };
+};

package/lib/types/match-media.d.ts

@@ -0,0 +1,12 @@
+import { EventTarget } from '@gjsify/dom-events';
+export declare class MediaQueryList extends EventTarget {
+    readonly media: string;
+    readonly matches: boolean;
+    onchange: ((this: MediaQueryList, ev: unknown) => unknown) | null;
+    constructor(query: string);
+    /** @deprecated Use addEventListener('change', ...) */
+    addListener(_listener: unknown): void;
+    /** @deprecated Use removeEventListener('change', ...) */
+    removeListener(_listener: unknown): void;
+}
+export declare function matchMedia(query: string): MediaQueryList;

package/lib/types/register/canvas.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/document.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/font-face.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/helpers.d.ts

@@ -0,0 +1,4 @@
+/** Unconditionally expose a DOM class on `globalThis` (writable + configurable). */
+export declare function defineGlobal(name: string, value: unknown): void;
+/** Only set the global if it hasn't already been defined. */
+export declare function defineGlobalIfMissing(name: string, value: unknown): void;

package/lib/types/register/image.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/location.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/match-media.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/navigator.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register/observers.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register.d.ts

@@ -1 +1,8 @@
-export {};
+import './register/document.js';
+import './register/canvas.js';
+import './register/image.js';
+import './register/observers.js';
+import './register/font-face.js';
+import './register/match-media.js';
+import './register/location.js';
+import './register/navigator.js';

package/lib/types/register.spec.d.ts

@@ -0,0 +1,3 @@
+import '@gjsify/dom-elements/register';
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/stubs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/dom-elements",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "DOM element hierarchy (Node, Element, HTMLElement, HTMLImageElement) for GJS",
   "type": "module",
   "module": "lib/esm/index.js",
@@ -13,10 +13,35 @@
     "./register": {
       "types": "./lib/types/register.d.ts",
       "default": "./lib/esm/register.js"
+    },
+    "./register/document": {
+      "default": "./lib/esm/register/document.js"
+    },
+    "./register/canvas": {
+      "default": "./lib/esm/register/canvas.js"
+    },
+    "./register/image": {
+      "default": "./lib/esm/register/image.js"
+    },
+    "./register/observers": {
+      "default": "./lib/esm/register/observers.js"
+    },
+    "./register/font-face": {
+      "default": "./lib/esm/register/font-face.js"
+    },
+    "./register/match-media": {
+      "default": "./lib/esm/register/match-media.js"
+    },
+    "./register/location": {
+      "default": "./lib/esm/register/location.js"
+    },
+    "./register/navigator": {
+      "default": "./lib/esm/register/navigator.js"
     }
   },
   "sideEffects": [
-    "./lib/esm/register.js"
+    "./lib/esm/register.js",
+    "./lib/esm/register/*.js"
   ],
   "scripts": {
     "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs test.node.mjs || exit 0",
@@ -36,18 +61,18 @@
     "node"
   ],
   "dependencies": {
-    "@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",
-    "@gjsify/abort-controller": "^0.1.8",
-    "@gjsify/canvas2d-core": "^0.1.8",
-    "@gjsify/dom-events": "^0.1.8",
-    "@gjsify/fetch": "^0.1.8"
+    "@girs/gdkpixbuf-2.0": "^2.0.0-4.0.0-rc.2",
+    "@girs/gjs": "^4.0.0-rc.2",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-rc.2",
+    "@gjsify/abort-controller": "^0.1.9",
+    "@gjsify/canvas2d-core": "^0.1.9",
+    "@gjsify/dom-events": "^0.1.9",
+    "@gjsify/fetch": "^0.1.9"
   },
   "devDependencies": {
-    "@gjsify/cli": "^0.1.8",
-    "@gjsify/unit": "^0.1.8",
-    "@types/node": "^25.5.2",
+    "@gjsify/cli": "^0.1.9",
+    "@gjsify/unit": "^0.1.9",
+    "@types/node": "^25.6.0",
     "typescript": "^6.0.2"
   }
 }

package/src/dom-matrix.ts

@@ -0,0 +1,109 @@
+// DOMMatrix stub for GJS — minimal 2D/3D transformation matrix.
+// Libraries like Excalibur construct `new DOMMatrix([a,b,c,d,e,f])` and pass
+// the result to `ctx.setTransform(matrix)` — we store the 6 2D components
+// plus 16 3D components. Our Canvas 2D context's setTransform() accepts
+// either a DOMMatrix or six numbers, so this works transparently.
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrix
+
+/**
+ * Minimal DOMMatrix implementation — supports 2D and 3D construction, plus
+ * 2D multiply/inverse/translate/scale operations used by Canvas 2D libraries
+ * like Excalibur. Full 3D math (4x4 multiply, inverse) is NOT implemented.
+ */
+export class DOMMatrix {
+    // 2D components
+    a = 1; b = 0; c = 0; d = 1; e = 0; f = 0;
+    // 3D components (column-major)
+    m11 = 1; m12 = 0; m13 = 0; m14 = 0;
+    m21 = 0; m22 = 1; m23 = 0; m24 = 0;
+    m31 = 0; m32 = 0; m33 = 1; m34 = 0;
+    m41 = 0; m42 = 0; m43 = 0; m44 = 1;
+    is2D = true;
+    isIdentity = true;
+
+    constructor(init?: number[] | string) {
+        if (Array.isArray(init)) {
+            if (init.length === 6) {
+                // 2D affine: [a, b, c, d, e, f]
+                this.a = this.m11 = init[0];
+                this.b = this.m12 = init[1];
+                this.c = this.m21 = init[2];
+                this.d = this.m22 = init[3];
+                this.e = this.m41 = init[4];
+                this.f = this.m42 = init[5];
+                this.is2D = true;
+            } else if (init.length === 16) {
+                // 3D: column-major 4x4
+                this.m11 = init[0];  this.m12 = init[1];  this.m13 = init[2];  this.m14 = init[3];
+                this.m21 = init[4];  this.m22 = init[5];  this.m23 = init[6];  this.m24 = init[7];
+                this.m31 = init[8];  this.m32 = init[9];  this.m33 = init[10]; this.m34 = init[11];
+                this.m41 = init[12]; this.m42 = init[13]; this.m43 = init[14]; this.m44 = init[15];
+                this.a = this.m11; this.b = this.m12;
+                this.c = this.m21; this.d = this.m22;
+                this.e = this.m41; this.f = this.m42;
+                this.is2D = false;
+            }
+            this.isIdentity =
+                this.a === 1 && this.b === 0 && this.c === 0 &&
+                this.d === 1 && this.e === 0 && this.f === 0;
+        }
+    }
+
+    /**
+     * Multiply this 2D matrix by another 2D matrix and return a new matrix.
+     * [a c e] [a' c' e']   [a*a'+c*b'  a*c'+c*d'  a*e'+c*f'+e]
+     * [b d f] [b' d' f'] = [b*a'+d*b'  b*c'+d*d'  b*e'+d*f'+f]
+     * [0 0 1] [0  0  1 ]   [0          0          1           ]
+     */
+    multiply(other: { a: number; b: number; c: number; d: number; e: number; f: number }): DOMMatrix {
+        const a = this.a * other.a + this.c * other.b;
+        const b = this.b * other.a + this.d * other.b;
+        const c = this.a * other.c + this.c * other.d;
+        const d = this.b * other.c + this.d * other.d;
+        const e = this.a * other.e + this.c * other.f + this.e;
+        const f = this.b * other.e + this.d * other.f + this.f;
+        return new DOMMatrix([a, b, c, d, e, f]);
+    }
+
+    /** In-place multiply; returns this. */
+    multiplySelf(other: { a: number; b: number; c: number; d: number; e: number; f: number }): DOMMatrix {
+        const result = this.multiply(other);
+        this.a = result.a; this.b = result.b;
+        this.c = result.c; this.d = result.d;
+        this.e = result.e; this.f = result.f;
+        this.m11 = this.a; this.m12 = this.b;
+        this.m21 = this.c; this.m22 = this.d;
+        this.m41 = this.e; this.m42 = this.f;
+        this.isIdentity = false;
+        return this;
+    }
+
+    /** 2D inverse. Throws if non-invertible (det === 0). */
+    inverse(): DOMMatrix {
+        const det = this.a * this.d - this.b * this.c;
+        if (det === 0) return new DOMMatrix([1, 0, 0, 1, 0, 0]);
+        const invDet = 1 / det;
+        return new DOMMatrix([
+            this.d * invDet,
+            -this.b * invDet,
+            -this.c * invDet,
+            this.a * invDet,
+            (this.c * this.f - this.d * this.e) * invDet,
+            (this.b * this.e - this.a * this.f) * invDet,
+        ]);
+    }
+
+    translate(tx = 0, ty = 0): DOMMatrix {
+        return this.multiply({ a: 1, b: 0, c: 0, d: 1, e: tx, f: ty });
+    }
+
+    scale(sx = 1, sy: number = sx): DOMMatrix {
+        return this.multiply({ a: sx, b: 0, c: 0, d: sy, e: 0, f: 0 });
+    }
+}
+
+/**
+ * DOMMatrixReadOnly alias — MDN specifies this as the immutable base class.
+ * We expose the same impl since consumers (Excalibur, three.js) rarely care.
+ */
+export const DOMMatrixReadOnly = DOMMatrix;

package/src/font-face.ts

@@ -0,0 +1,97 @@
+// FontFace implementation for GJS — registers custom TTF fonts in PangoCairo
+// so that Canvas2D fillText uses the correct font family.
+//
+// Flow (Excalibur): XHR(blob) → /tmp/gjsify-blob-N.ttf → createObjectURL →
+//   new FontFace(family, 'url(file:///tmp/gjsify-blob-N.ttf)') → face.load()
+// The file is already on disk when load() is called; we just tell PangoCairo
+// about it via font_map_get_default().add_font_file(path).
+//
+// Node.js: dynamic gi:// import fails gracefully → status='loaded' still set.
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/FontFace
+
+export class FontFace {
+    readonly family: string;
+    readonly source: string;
+    status: 'unloaded' | 'loading' | 'loaded' | 'error' = 'unloaded';
+    loaded: Promise<FontFace>;
+    display = 'auto';
+    style = 'normal';
+    weight = 'normal';
+    stretch = 'normal';
+    unicodeRange = 'U+0-10FFFF';
+    variant = 'normal';
+    featureSettings = 'normal';
+
+    constructor(family: string, source: string | ArrayBuffer | ArrayBufferView, _descriptors?: Record<string, string>) {
+        this.family = family;
+        this.source = typeof source === 'string' ? source : '[binary]';
+        this.loaded = Promise.resolve(this);
+    }
+
+    // Parses: url(file:///path), url("file:///path"), url('file:///path')
+    private _extractFilePath(): string | null {
+        const m = this.source.match(/url\s*\(\s*["']?(file:\/\/\/[^"')]+)["']?\s*\)/i);
+        if (!m) return null;
+        // Strip file:// prefix → /path/to/file.ttf
+        return m[1].replace(/^file:\/\//, '');
+    }
+
+    async load(): Promise<FontFace> {
+        this.status = 'loading';
+        const filePath = this._extractFilePath();
+        if (filePath) {
+            try {
+                // gi:// only available in GJS — fails gracefully on Node.js
+                // @ts-ignore
+                const { default: PangoCairo } = await import('gi://PangoCairo?version=1.0');
+                PangoCairo.font_map_get_default().add_font_file(filePath);
+            } catch {
+                // Not in GJS, or font file not found — fall through to loaded
+                // Canvas fillText will use system font fallback (acceptable)
+            }
+        }
+        this.status = 'loaded';
+        return this;
+    }
+}
+
+/**
+ * FontFaceSet — tracks loaded FontFace objects and exposes them to consumers.
+ *
+ * Intentionally does NOT extend EventTarget. The dom-elements /register module
+ * runs before dom-events/register in the inject order, so EventTarget may not
+ * yet exist when this class is defined at module load time. All event methods
+ * are provided as no-ops; consumers that call addEventListener('loadingdone')
+ * etc. will silently receive nothing.
+ */
+export class FontFaceSet {
+    status: 'loading' | 'loaded' = 'loaded';
+    ready: Promise<FontFaceSet> = Promise.resolve(this);
+
+    private _faces = new Set<FontFace>();
+
+    addEventListener(_type: string, _listener: unknown): void {}
+    removeEventListener(_type: string, _listener: unknown): void {}
+    dispatchEvent(_event: unknown): boolean { return true; }
+
+    add(face: FontFace): FontFaceSet {
+        this._faces.add(face);
+        return this;
+    }
+    delete(face: FontFace): boolean { return this._faces.delete(face); }
+    clear(): void { this._faces.clear(); }
+    has(face: FontFace): boolean { return this._faces.has(face); }
+    check(_font: string, _text?: string): boolean { return false; }
+    load(_font: string, _text?: string): Promise<FontFace[]> { return Promise.resolve([]); }
+    forEach(callback: (value: FontFace, key: FontFace, parent: FontFaceSet) => void): void {
+        this._faces.forEach(f => callback(f, f, this));
+    }
+    values(): IterableIterator<FontFace> { return this._faces.values(); }
+    keys(): IterableIterator<FontFace> { return this._faces.values(); }
+    entries(): IterableIterator<[FontFace, FontFace]> {
+        const faces = Array.from(this._faces);
+        return faces.map(f => [f, f] as [FontFace, FontFace])[Symbol.iterator]() as IterableIterator<[FontFace, FontFace]>;
+    }
+    [Symbol.iterator](): Iterator<FontFace> { return this._faces[Symbol.iterator](); }
+    get size(): number { return this._faces.size; }
+}

package/src/html-element.ts

@@ -15,7 +15,37 @@ import * as PS from './property-symbol.js';
  */
 export class CSSStyleDeclaration {
     [key: string]: unknown;
-    cssText = '';
+    private _cssText = '';
+
+    /** Setting cssText parses individual declarations and stores them as camelCase properties,
+     *  matching browser behavior for feature-detection checks like Excalibur's rgbaSupport. */
+    get cssText(): string { return this._cssText; }
+    set cssText(value: string) {
+        this._cssText = value;
+        for (const decl of value.split(';')) {
+            const colon = decl.indexOf(':');
+            if (colon === -1) continue;
+            const prop = decl.slice(0, colon).trim();
+            const val = decl.slice(colon + 1).trim();
+            if (!prop) continue;
+            const camel = prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+            (this as Record<string, unknown>)[camel] = val;
+        }
+    }
+
+    setProperty(property: string, value: string, _priority?: string): void {
+        (this as Record<string, unknown>)[property] = value;
+    }
+    getPropertyValue(property: string): string {
+        const v = (this as Record<string, unknown>)[property];
+        return typeof v === 'string' ? v : '';
+    }
+    removeProperty(property: string): string {
+        const v = (this as Record<string, unknown>)[property];
+        delete (this as Record<string, unknown>)[property];
+        return typeof v === 'string' ? v : '';
+    }
+    getPropertyPriority(_property: string): string { return ''; }
 }
 
 /**
@@ -27,6 +57,39 @@ export class HTMLElement extends Element {
 	// -- Style stub (no layout engine — assignments are no-ops) --
 	readonly style: CSSStyleDeclaration = new CSSStyleDeclaration();
 
+	// -- dataset: Proxy-backed DOMStringMap over data-* attributes --
+	// Converts `data-original-src` ↔ `originalSrc` (camelCase). Used by
+	// Excalibur's ImageSource which sets data-original-src on images for
+	// debugging and TextureLoader.checkImageSizeSupportedAndLog.
+	get dataset(): Record<string, string> {
+		const el = this;
+		return new Proxy({} as Record<string, string>, {
+			get(_target, prop: string): string | undefined {
+				if (typeof prop !== 'string') return undefined;
+				const attr = 'data-' + prop.replace(/[A-Z]/g, c => '-' + c.toLowerCase());
+				const value = el.getAttribute(attr);
+				return value ?? undefined;
+			},
+			set(_target, prop: string, value: string): boolean {
+				if (typeof prop !== 'string') return false;
+				const attr = 'data-' + prop.replace(/[A-Z]/g, c => '-' + c.toLowerCase());
+				el.setAttribute(attr, String(value));
+				return true;
+			},
+			deleteProperty(_target, prop: string): boolean {
+				if (typeof prop !== 'string') return false;
+				const attr = 'data-' + prop.replace(/[A-Z]/g, c => '-' + c.toLowerCase());
+				el.removeAttribute(attr);
+				return true;
+			},
+			has(_target, prop: string): boolean {
+				if (typeof prop !== 'string') return false;
+				const attr = 'data-' + prop.replace(/[A-Z]/g, c => '-' + c.toLowerCase());
+				return el.hasAttribute(attr);
+			},
+		});
+	}
+
 	// -- Attribute-backed string properties --
 
 	get title(): string {