@gjsify/dom-elements 0.1.7 → 0.1.9

package/src/html-image-element.spec.ts

@@ -0,0 +1,285 @@
+// HTMLImageElement lifecycle tests — verifies the src → onload → pixbuf
+// chain Excalibur relies on, plus the native GJS extensions used by
+// @gjsify/canvas2d-core drawImage.
+//
+// Ported from refs/happy-dom/packages/happy-dom/test/nodes/html-image-element/
+// HTMLImageElement.test.ts (MIT, David Ortner) plus custom cases that
+// lock in compatibility with Excalibur's ImageSource.load pattern:
+//     const image = new Image();
+//     image.onload = () => futureResolve();
+//     image.src = url;
+//     await future;
+// (refs/excalibur/src/engine/graphics/image-source.ts:226-273)
+
+import { describe, it, expect } from '@gjsify/unit';
+import GLib from 'gi://GLib?version=2.0';
+import GdkPixbuf from 'gi://GdkPixbuf?version=2.0';
+
+import { HTMLImageElement, Image } from '@gjsify/dom-elements';
+
+// ── Test fixture setup ────────────────────────────────────────────────────
+//
+// Generates a 2×2 RGBA test PNG in /tmp at module load. Each pixel has a
+// distinct color (red/green/blue/white) so get-pixel tests can verify
+// byte order. Cleaned up by /tmp rotation; no explicit teardown needed.
+
+const FIXTURE_DIR = GLib.get_tmp_dir();
+const FIXTURE_PATH = GLib.build_filenamev([FIXTURE_DIR, 'gjsify-test-2x2.png']);
+const FIXTURE_URI = 'file://' + FIXTURE_PATH;
+
+function writeFixturePng(): void {
+    // 2×2 RGBA raw pixel buffer:
+    //   (0,0) red   (1,0) green
+    //   (0,1) blue  (1,1) white
+    const pixels = new Uint8Array([
+        255, 0, 0, 255,    0, 255, 0, 255,
+        0, 0, 255, 255,  255, 255, 255, 255,
+    ]);
+    // GdkPixbuf.Pixbuf.new_from_bytes expects row-major, w*4 stride for RGBA.
+    const bytes = GLib.Bytes.new(pixels);
+    const pixbuf = GdkPixbuf.Pixbuf.new_from_bytes(
+        bytes,
+        GdkPixbuf.Colorspace.RGB,
+        true,  // has_alpha
+        8,     // bits_per_sample
+        2,     // width
+        2,     // height
+        8,     // rowstride (2 px * 4 bytes)
+    );
+    pixbuf.savev(FIXTURE_PATH, 'png', [], []);
+}
+
+writeFixturePng();
+
+export default async () => {
+    await describe('HTMLImageElement', async () => {
+
+        await describe('constructor + static Image alias', async () => {
+            await it('new HTMLImageElement() creates an empty image', async () => {
+                const img = new HTMLImageElement();
+                expect(img.complete).toBe(false);
+                expect(img.naturalWidth).toBe(0);
+                expect(img.naturalHeight).toBe(0);
+                expect(img.src).toBe('');
+            });
+
+            await it('new Image() yields an HTMLImageElement instance', async () => {
+                const img = new Image();
+                expect(img instanceof HTMLImageElement).toBe(true);
+            });
+        });
+
+        await describe('src setter — file:// loading', async () => {
+            await it('loads a file:// URL synchronously and sets natural dimensions', async () => {
+                const img = new HTMLImageElement();
+                img.src = FIXTURE_URI;
+                expect(img.complete).toBe(true);
+                expect(img.naturalWidth).toBe(2);
+                expect(img.naturalHeight).toBe(2);
+                expect(img.isPixbuf()).toBe(true);
+            });
+
+            await it('fires the load event (sync dispatch)', async () => {
+                const img = new HTMLImageElement();
+                let loaded = false;
+                img.addEventListener('load', () => { loaded = true; });
+                img.src = FIXTURE_URI;
+                expect(loaded).toBe(true);
+            });
+
+            await it('fires the error event for non-existent files', async () => {
+                const img = new HTMLImageElement();
+                let errored = false;
+                img.addEventListener('error', () => { errored = true; });
+                img.src = 'file:///nonexistent/definitely/not/here.png';
+                expect(errored).toBe(true);
+                expect(img.complete).toBe(true);
+                expect(img.isPixbuf()).toBe(false);
+            });
+
+            await it('fires error immediately for http:// URLs (not supported in GJS)', async () => {
+                const img = new HTMLImageElement();
+                let errored = false;
+                img.addEventListener('error', () => { errored = true; });
+                img.src = 'http://example.com/img.png';
+                expect(errored).toBe(true);
+                expect(img.complete).toBe(true);
+            });
+        });
+
+        await describe('Excalibur.ImageSource.load pattern — handler before src', async () => {
+            // This is the canonical pattern Excalibur uses in
+            // refs/excalibur/src/engine/graphics/image-source.ts:247-252.
+            // The handler must be set BEFORE src so the sync dispatch fires
+            // it and the awaited promise resolves correctly.
+            await it('onload-set-then-src-set resolves the future', async () => {
+                const img = new HTMLImageElement();
+                const future = new Promise<void>((resolve) => {
+                    img.onload = () => resolve();
+                });
+                img.src = FIXTURE_URI;
+                // Sync dispatch fires onload before returning from src=.
+                await future;
+                expect(img.complete).toBe(true);
+                expect(img.naturalWidth).toBe(2);
+            });
+
+            await it('onload registered AFTER src is set does NOT fire', async () => {
+                // Matches browser semantics: the load event is a one-shot
+                // dispatch — registering a listener after it fires does not
+                // retroactively invoke it.
+                const img = new HTMLImageElement();
+                img.src = FIXTURE_URI;
+                expect(img.complete).toBe(true);
+                let fired = false;
+                img.onload = () => { fired = true; };
+                // Give microtasks a chance to fire (they won't).
+                await new Promise<void>((r) => r());
+                expect(fired).toBe(false);
+            });
+        });
+
+        await describe('getImageData — RGBA byte order', async () => {
+            await it('extracts correct pixel bytes from the loaded pixbuf', async () => {
+                const img = new HTMLImageElement();
+                img.src = FIXTURE_URI;
+                const data = img.getImageData();
+                expect(data).not.toBeNull();
+                expect(data!.width).toBe(2);
+                expect(data!.height).toBe(2);
+                // Pixel (0,0) — red
+                expect(data!.data[0]).toBe(255);
+                expect(data!.data[1]).toBe(0);
+                expect(data!.data[2]).toBe(0);
+                expect(data!.data[3]).toBe(255);
+                // Pixel (1,0) — green
+                expect(data!.data[4]).toBe(0);
+                expect(data!.data[5]).toBe(255);
+                expect(data!.data[6]).toBe(0);
+                expect(data!.data[7]).toBe(255);
+                // Pixel (0,1) — blue
+                expect(data!.data[8]).toBe(0);
+                expect(data!.data[9]).toBe(0);
+                expect(data!.data[10]).toBe(255);
+                expect(data!.data[11]).toBe(255);
+                // Pixel (1,1) — white
+                expect(data!.data[12]).toBe(255);
+                expect(data!.data[13]).toBe(255);
+                expect(data!.data[14]).toBe(255);
+                expect(data!.data[15]).toBe(255);
+            });
+        });
+
+        await describe('src setter — data: URI loading', async () => {
+            // Excalibur's Loader.onBeforeLoad() sets img.src to a data:image/png;base64,...
+            // URI for the loader logo. If this fires error instead of load, the
+            // _imageLoaded promise never resolves and the loader hangs forever.
+            // Regression test for the GJS fix using GLib.base64_decode + Gio.MemoryInputStream.
+
+            function makeDataUri(): string {
+                // Encode the 2×2 fixture PNG as a data URI using GLib.
+                const [ok, bytes] = GLib.file_get_contents(FIXTURE_PATH);
+                if (!ok) throw new Error('fixture PNG not found');
+                const b64 = GLib.base64_encode(bytes as unknown as Uint8Array);
+                return `data:image/png;base64,${b64}`;
+            }
+
+            await it('loads a base64 PNG data URI and sets natural dimensions', async () => {
+                const img = new HTMLImageElement();
+                const dataUri = makeDataUri();
+                img.src = dataUri;
+                expect(img.complete).toBe(true);
+                expect(img.naturalWidth).toBe(2);
+                expect(img.naturalHeight).toBe(2);
+                expect(img.isPixbuf()).toBe(true);
+            });
+
+            await it('fires load event for a base64 PNG data URI', async () => {
+                const img = new HTMLImageElement();
+                let loaded = false;
+                img.addEventListener('load', () => { loaded = true; });
+                img.src = makeDataUri();
+                expect(loaded).toBe(true);
+            });
+
+            await it('Excalibur pattern: onload-then-src resolves for data URIs', async () => {
+                const img = new HTMLImageElement();
+                const future = new Promise<void>((resolve) => {
+                    img.onload = () => resolve();
+                });
+                img.src = makeDataUri();
+                await future;
+                expect(img.complete).toBe(true);
+                expect(img.naturalWidth).toBe(2);
+            });
+
+            await it('fires error for a malformed data URI (no comma)', async () => {
+                const img = new HTMLImageElement();
+                let errored = false;
+                img.addEventListener('error', () => { errored = true; });
+                img.src = 'data:image/png;base64';
+                expect(errored).toBe(true);
+                expect(img.complete).toBe(true);
+            });
+
+            await it('getImageData returns correct RGBA pixels from data URI', async () => {
+                const img = new HTMLImageElement();
+                img.src = makeDataUri();
+                const data = img.getImageData();
+                expect(data).not.toBeNull();
+                expect(data!.width).toBe(2);
+                expect(data!.height).toBe(2);
+                // Pixel (0,0) — red
+                expect(data!.data[0]).toBe(255);
+                expect(data!.data[1]).toBe(0);
+                expect(data!.data[2]).toBe(0);
+                expect(data!.data[3]).toBe(255);
+            });
+        });
+
+        await describe('dataset proxy — Excalibur data-original-src pattern', async () => {
+            // Excalibur's ImageSource.load does:
+            //   image.setAttribute('data-original-src', this.path);
+            // and TextureLoader.checkImageSizeSupportedAndLog reads
+            //   image.dataset.originalSrc
+            // Our dataset Proxy must perform the kebab→camel case conversion.
+            await it('reads a data-* attribute via camelCase dataset access', async () => {
+                const img = new HTMLImageElement();
+                img.setAttribute('data-original-src', 'sprites/hero.png');
+                expect(img.dataset.originalSrc).toBe('sprites/hero.png');
+            });
+
+            await it('sets a data-* attribute via dataset assignment', async () => {
+                const img = new HTMLImageElement();
+                img.dataset.tileIndex = '42';
+                expect(img.getAttribute('data-tile-index')).toBe('42');
+            });
+
+            await it('delete operator removes the data-* attribute', async () => {
+                const img = new HTMLImageElement();
+                img.setAttribute('data-foo', 'bar');
+                delete img.dataset.foo;
+                expect(img.hasAttribute('data-foo')).toBe(false);
+            });
+
+            await it('returns undefined for unset dataset keys', async () => {
+                const img = new HTMLImageElement();
+                expect(img.dataset.nothing).toBe(undefined);
+            });
+        });
+
+        await describe('attribute-backed properties', async () => {
+            await it('alt, title, crossOrigin round-trip through attributes', async () => {
+                const img = new HTMLImageElement();
+                img.alt = 'hero sprite';
+                img.title = 'A jumping jelly';
+                img.crossOrigin = 'anonymous';
+                expect(img.getAttribute('alt')).toBe('hero sprite');
+                expect(img.getAttribute('title')).toBe('A jumping jelly');
+                expect(img.getAttribute('crossorigin')).toBe('anonymous');
+                expect(img.alt).toBe('hero sprite');
+                expect(img.crossOrigin).toBe('anonymous');
+            });
+        });
+    });
+};

package/src/html-image-element.ts

@@ -2,6 +2,7 @@
 // Reference: refs/happy-dom/packages/happy-dom/src/nodes/html-image-element/HTMLImageElement.ts
 
 import GLib from '@girs/glib-2.0';
+import Gio from '@girs/gio-2.0';
 import GdkPixbuf from '@girs/gdkpixbuf-2.0';
 import { Event } from '@gjsify/dom-events';
 import { HTMLElement } from './html-element.js';
@@ -118,12 +119,49 @@ export class HTMLImageElement extends HTMLElement {
 	set src(src: string) {
 		this.setAttribute('src', src);
 
+		const DEBUG = (globalThis as any).__GJSIFY_DEBUG_IMG === true;
+
+		// Handle data: URIs (e.g. base64 PNG logos from Excalibur's loader)
+		if (src.startsWith('data:')) {
+			const commaIdx = src.indexOf(',');
+			if (commaIdx === -1) {
+				this._complete = true;
+				this.dispatchEvent(new Event('error'));
+				return;
+			}
+			const meta = src.slice(5, commaIdx); // between 'data:' and ','
+			const data = src.slice(commaIdx + 1);
+			const isBase64 = meta.includes(';base64');
+			try {
+				let bytes: Uint8Array;
+				if (isBase64) {
+					// Use GLib.base64_decode — available in all GJS versions, no global needed
+					bytes = GLib.base64_decode(data) as unknown as Uint8Array;
+				} else {
+					bytes = new TextEncoder().encode(decodeURIComponent(data));
+				}
+				const gbytes = GLib.Bytes.new(bytes);
+				const stream = Gio.MemoryInputStream.new_from_bytes(gbytes);
+				this._pixbuf = GdkPixbuf.Pixbuf.new_from_stream(stream, null);
+				this._naturalWidth = this._pixbuf!.get_width();
+				this._naturalHeight = this._pixbuf!.get_height();
+				this._complete = true;
+				if (DEBUG) console.log(`[img] ok data: (${this._naturalWidth}x${this._naturalHeight})`);
+				this.dispatchEvent(new Event('load'));
+			} catch (_error) {
+				if (DEBUG) console.warn(`[img] error data:: ${(_error as any)?.message ?? _error}`);
+				this._complete = true;
+				this.dispatchEvent(new Event('error'));
+			}
+			return;
+		}
+
 		let filename: string;
 		if (src.startsWith('file://')) {
 			// GLib.filename_from_uri returns [localPath, hostname]
 			filename = GLib.filename_from_uri(src)[0];
-		} else if (src.startsWith('http://') || src.startsWith('https://') || src.startsWith('data:')) {
-			// Remote URLs and data URIs are not supported in GJS — fire error
+		} else if (src.startsWith('http://') || src.startsWith('https://')) {
+			// Remote URLs are not supported in GJS — fire error
 			this._complete = true;
 			this.dispatchEvent(new Event('error'));
 			return;
@@ -134,13 +172,16 @@ export class HTMLImageElement extends HTMLElement {
 		}
 
 		try {
+			if (DEBUG) console.log(`[img] load ${filename}`);
 			this._pixbuf = GdkPixbuf.Pixbuf.new_from_file(filename);
 			this._naturalWidth = this._pixbuf.get_width();
 			this._naturalHeight = this._pixbuf.get_height();
 			this._complete = true;
+			if (DEBUG) console.log(`[img] ok ${filename} (${this._naturalWidth}x${this._naturalHeight})`);
 
 			this.dispatchEvent(new Event('load'));
 		} catch (_error) {
+			if (DEBUG) console.warn(`[img] error ${filename}: ${(_error as any)?.message ?? _error}`);
 			this._complete = true;
 			this.dispatchEvent(new Event('error'));
 		}

package/src/index.spec.ts

@@ -4,7 +4,7 @@
 import { describe, it, expect } from '@gjsify/unit';
 
 import {
-	Node, Element, HTMLElement, NodeType, NamespaceURI, Attr, NamedNodeMap,
+	Node, Element, HTMLElement, NodeType, Attr,
 	CharacterData, Text, Comment, DocumentFragment, DOMTokenList,
 } from '@gjsify/dom-elements';
 import { Event } from '@gjsify/dom-events';
@@ -325,7 +325,7 @@ export default async () => {
 		await it('should getElementsByTagName', async () => {
 			const root = new Element();
 			const div = new Element();
-			div[Symbol.for ? Symbol.for('tagName') : 'tagName'] = 'DIV';
+			(div as any)[Symbol.for ? Symbol.for('tagName') : 'tagName'] = 'DIV';
 			// Use internal symbol access via setting attribute approach
 			// Instead, test with the proper API
 			root.appendChild(div);
@@ -336,14 +336,13 @@ export default async () => {
 
 		await it('should dispatch events and call on* handlers', async () => {
 			const el = new Element();
-			let handlerCalled = false;
 			let listenerCalled = false;
 
 			el.addEventListener('click', () => {
 				listenerCalled = true;
 			});
 
-			el[Symbol.for ? Symbol.for('propertyEventListeners') : 'propertyEventListeners'] = new Map();
+			(el as any)[Symbol.for ? Symbol.for('propertyEventListeners') : 'propertyEventListeners'] = new Map();
 			// Use the propertyEventListeners through proper API in HTMLElement
 			// For Element, test addEventListener only
 			el.dispatchEvent(new Event('click'));

package/src/index.ts

@@ -1,5 +1,14 @@
 // DOM element hierarchy for GJS — original implementation adapted from happy-dom
 // Copyright (c) David Ortner (capricorn86). MIT license.
+//
+// Note: This module has no side effects. Importing it gives you the DOM
+// classes as named exports but does NOT register `document`, `Image`,
+// `HTMLCanvasElement` etc. on globalThis, and does NOT wire up the 2d
+// canvas context factory.
+//
+// If you need the globals (or `canvas.getContext('2d')` to work), import
+// `@gjsify/dom-elements/register` explicitly — or let the gjsify esbuild
+// plugin auto-inject it based on references in your code.
 
 export { Attr } from './attr.js';
 export { NamedNodeMap } from './named-node-map.js';
@@ -22,115 +31,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';
-
-// Side-effect: register DOM globals on import.
-// Same pattern as @gjsify/node-globals (packages/node/globals/src/index.ts)
-// and @gjsify/web-globals (packages/web/web-globals/src/index.ts).
-import '@gjsify/abort-controller'; // registers globalThis.AbortController + AbortSignal
-import '@gjsify/fetch'; // registers globalThis.fetch, Request, Response, Headers
-import { Text } from './text.js';
-import { Comment } from './comment.js';
-import { DocumentFragment } from './document-fragment.js';
-import { DOMTokenList } from './dom-token-list.js';
-import { HTMLCanvasElement } from './html-canvas-element.js';
-import { HTMLImageElement } from './html-image-element.js';
-import { Image } from './image.js';
-import { document } from './document.js';
-import { MutationObserver } from './mutation-observer.js';
-import { ResizeObserver } from './resize-observer.js';
-import { IntersectionObserver } from './intersection-observer.js';
-
-Object.defineProperty(globalThis, 'Text', {
-    value: Text,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'Comment', {
-    value: Comment,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'DocumentFragment', {
-    value: DocumentFragment,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'DOMTokenList', {
-    value: DOMTokenList,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'HTMLCanvasElement', {
-    value: HTMLCanvasElement,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'HTMLImageElement', {
-    value: HTMLImageElement,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'Image', {
-    value: Image,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'document', {
-    value: document,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'MutationObserver', {
-    value: MutationObserver,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'ResizeObserver', {
-    value: ResizeObserver,
-    writable: true,
-    configurable: true,
-});
-Object.defineProperty(globalThis, 'IntersectionObserver', {
-    value: IntersectionObserver,
-    writable: true,
-    configurable: true,
-});
-
-// Auto-register the '2d' context factory on HTMLCanvasElement.
-// Mirrors browser behavior: canvas.getContext('2d') works without any explicit import.
-// The factory is idempotent — re-registering from @gjsify/canvas2d has no effect.
-import { CanvasRenderingContext2D } from '@gjsify/canvas2d-core';
-
-const CANVAS2D_KEY = Symbol.for('gjsify_canvas2d_context');
-HTMLCanvasElement.registerContextFactory('2d', (canvas, options) => {
-    const existing = (canvas as any)[CANVAS2D_KEY];
-    if (existing) return existing;
-    const ctx = new CanvasRenderingContext2D(canvas as any, options);
-    (canvas as any)[CANVAS2D_KEY] = ctx;
-    return ctx;
-});
-
-Object.defineProperty(globalThis, 'CanvasRenderingContext2D', {
-    value: CanvasRenderingContext2D,
-    writable: true,
-    configurable: true,
-});
-
-// self — three.js checks `typeof self !== 'undefined'` for animation context
-if (typeof (globalThis as any).self === 'undefined') {
-    Object.defineProperty(globalThis, 'self', { value: globalThis, writable: true, configurable: true });
-}
-
-// devicePixelRatio — defaults to 1 (no HiDPI scaling in GTK GL context)
-if (typeof (globalThis as any).devicePixelRatio === 'undefined') {
-    Object.defineProperty(globalThis, 'devicePixelRatio', { value: 1, writable: true, configurable: true });
-}
-
-// alert — stub redirecting to console.error (GTK dialog version can override via writable)
-if (typeof (globalThis as any).alert === 'undefined') {
-    Object.defineProperty(globalThis, 'alert', {
-        value: (...args: any[]) => console.error('alert:', ...args),
-        writable: true,
-        configurable: true,
-    });
-}
+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/src/location-stub.ts

@@ -0,0 +1,20 @@
+// window.location stub for GJS — provides minimal Location-compatible object.
+// In GJS apps, there is no browser URL — we use file:// as a reasonable default.
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/Location
+
+export const location = {
+    href:     'file://',
+    origin:   'file://',
+    protocol: 'file:',
+    host:     '',
+    hostname: '',
+    port:     '',
+    pathname: '/',
+    search:   '',
+    hash:     '',
+    assign(_url: string): void {},
+    replace(_url: string): void {},
+    reload(): void {},
+    toString(): string { return this.href; },
+    ancestorOrigins: { length: 0, item: () => null, contains: () => false, [Symbol.iterator]: function*(): Generator<string> {} },
+};

package/src/match-media.ts

@@ -0,0 +1,32 @@
+// matchMedia stub for GJS — used by Excalibur and other libraries to monitor
+// devicePixelRatio changes. Returns a minimal MediaQueryList-compatible object.
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia
+//
+// NOTE: imports EventTarget directly from @gjsify/dom-events rather than
+// using the global, because dom-elements/register runs BEFORE
+// dom-events/register in the inject order — so `globalThis.EventTarget` may
+// not yet exist when this class is defined at module load time.
+
+import { EventTarget } from '@gjsify/dom-events';
+
+export class MediaQueryList extends EventTarget {
+    readonly media: string;
+    readonly matches: boolean;
+    onchange: ((this: MediaQueryList, ev: unknown) => unknown) | null = null;
+
+    constructor(query: string) {
+        super();
+        this.media = query;
+        this.matches = false;
+    }
+
+    /** @deprecated Use addEventListener('change', ...) */
+    addListener(_listener: unknown): void {}
+
+    /** @deprecated Use removeEventListener('change', ...) */
+    removeListener(_listener: unknown): void {}
+}
+
+export function matchMedia(query: string): MediaQueryList {
+    return new MediaQueryList(query);
+}

package/src/register/canvas.ts

@@ -0,0 +1,23 @@
+// Registers: HTMLCanvasElement, CanvasRenderingContext2D, DOMMatrix,
+// DOMMatrixReadOnly + the '2d' context factory.
+
+import { CanvasRenderingContext2D } from '@gjsify/canvas2d-core';
+
+import { HTMLCanvasElement } from '../html-canvas-element.js';
+import { DOMMatrix, DOMMatrixReadOnly } from '../dom-matrix.js';
+import { defineGlobal } from './helpers.js';
+
+defineGlobal('HTMLCanvasElement', HTMLCanvasElement);
+defineGlobal('CanvasRenderingContext2D', CanvasRenderingContext2D);
+defineGlobal('DOMMatrix', DOMMatrix);
+defineGlobal('DOMMatrixReadOnly', DOMMatrixReadOnly);
+
+// Register the '2d' context factory on HTMLCanvasElement.
+const CANVAS2D_KEY = Symbol.for('gjsify_canvas2d_context');
+HTMLCanvasElement.registerContextFactory('2d', (canvas, options) => {
+    const existing = (canvas as any)[CANVAS2D_KEY];
+    if (existing) return existing;
+    const ctx = new CanvasRenderingContext2D(canvas as any, options);
+    (canvas as any)[CANVAS2D_KEY] = ctx;
+    return ctx;
+});

package/src/register/document.ts

@@ -0,0 +1,56 @@
+// Registers: document, Text, Comment, DocumentFragment, DOMTokenList
+// + browser environment globals: self, window, Window, focus, blur, top,
+//   alert, devicePixelRatio, addEventListener/removeEventListener/dispatchEvent
+
+import { EventTarget as OurEventTarget } from '@gjsify/dom-events';
+
+import { Comment } from '../comment.js';
+import { document } from '../document.js';
+import { DocumentFragment } from '../document-fragment.js';
+import { DOMTokenList } from '../dom-token-list.js';
+import { Text } from '../text.js';
+import { defineGlobal, defineGlobalIfMissing } from './helpers.js';
+
+defineGlobal('Text', Text);
+defineGlobal('Comment', Comment);
+defineGlobal('DocumentFragment', DocumentFragment);
+defineGlobal('DOMTokenList', DOMTokenList);
+defineGlobal('document', document);
+
+// self — three.js checks `typeof self !== 'undefined'` for animation context
+defineGlobalIfMissing('self', globalThis);
+
+// window + Window — Excalibur's _applyDisplayMode uses `this.parent instanceof Window`
+class Window {}
+defineGlobalIfMissing('Window', Window);
+defineGlobalIfMissing('window', globalThis);
+
+// window.focus() / window.blur() stubs
+defineGlobalIfMissing('focus', () => {});
+defineGlobalIfMissing('blur', () => {});
+
+// globalThis.addEventListener / removeEventListener / dispatchEvent
+if (typeof (globalThis as any).addEventListener !== 'function') {
+    const _globalEventTarget = new OurEventTarget();
+    (globalThis as any).__gjsify_globalEventTarget = _globalEventTarget;
+    (globalThis as any).addEventListener = (type: string, listener: any, options?: any) =>
+        _globalEventTarget.addEventListener(type, listener, options);
+    (globalThis as any).removeEventListener = (type: string, listener: any, options?: any) =>
+        _globalEventTarget.removeEventListener(type, listener, options);
+    (globalThis as any).dispatchEvent = (event: Event) =>
+        _globalEventTarget.dispatchEvent(event as any);
+}
+
+// devicePixelRatio — defaults to 1 (no HiDPI scaling in GTK GL context)
+defineGlobalIfMissing('devicePixelRatio', 1);
+
+// alert — stub redirecting to console.error
+defineGlobalIfMissing('alert', (...args: unknown[]) => console.error('alert:', ...args));
+
+// window.top — prevents Excalibur's iframe detection from crashing
+if (typeof (globalThis as any).top === 'undefined') {
+    Object.defineProperty(globalThis, 'top', {
+        get: () => globalThis,
+        configurable: true,
+    });
+}