@gjsify/dom-elements 0.35.0 → 0.37.0

package/globals.mjs

@@ -1,11 +1,7 @@
 /**
- * Re-exports native DOM Element globals for browser builds.
- *
- * On any browser these classes are part of the global DOM platform. The
- * resolver routes `@gjsify/dom-elements` here on `--app browser` because
- * `package.json#gjsify.runtimes.browser === "native"`.
- *
- * NOT used on Node (`runtimes.node` is `"none"` — Node has no DOM).
+ * Native DOM globals for browser builds: the resolver routes `@gjsify/dom-elements` here on
+ * `--app browser` because `package.json#gjsify.runtimes.browser` is `"native"`. There is no Node
+ * counterpart — `runtimes.node` is `"none"`, Node having no DOM.
  */
 
 export const Node = globalThis.Node;

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

@@ -15,13 +15,10 @@ export declare class FontFace {
     load(): Promise<FontFace>;
 }
 /**
- * FontFaceSet — tracks loaded FontFace objects and exposes them to consumers.
+ * 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.
+ * Does not extend EventTarget: the event methods are no-ops, so a consumer listening for
+ * 'loadingdone' silently receives nothing.
  */
 export declare class FontFaceSet {
     status: 'loading' | 'loaded';

package/lib/types/gst-time.d.ts

@@ -1,13 +1,8 @@
-/**
- * Convert seconds (number) to GStreamer nanoseconds (bigint).
- * Rounds to the nearest nanosecond to avoid floating-point drift over
- * repeated back-and-forth conversions.
- */
+/** Seconds to GStreamer nanoseconds, rounded to avoid drift over repeated round-trips. */
 export declare function secondsToGstTime(seconds: number): bigint;
 /**
- * Convert GStreamer nanoseconds to seconds (number).
- * Accepts both `bigint` (the runtime type from GStreamer queries) and `number`
- * (what the `@girs/gst-1.0` typings currently declare — a known GIR bug for
- * `gint64` return values in `query_position` / `query_duration`).
+ * GStreamer nanoseconds to seconds. Accepts `number` as well as `bigint` because the
+ * `@girs/gst-1.0` typings declare `gint64` returns as `number` (`query_position` /
+ * `query_duration`), while the runtime hands back a `bigint`.
  */
 export declare function gstTimeToSeconds(nanoseconds: bigint | number): number;

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

@@ -1,40 +1,30 @@
 import { HTMLElement } from './html-element.js';
 /**
- * HTMLCanvasElement base class.
- *
- * This is a DOM-spec-compliant stub. The GTK-backed implementation lives in
- * `@gjsify/webgl` and extends this class, overriding `getContext()`.
+ * A DOM-spec-compliant canvas with no rendering of its own. `@gjsify/webgl` extends it with a
+ * `Gtk.GLArea`-backed `getContext()` override.
  *
  * Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement
  */
 export declare class HTMLCanvasElement extends HTMLElement {
     private static _contextFactories;
-    /**
-     * Register a rendering context factory for a given context type.
-     * Called by packages like @gjsify/canvas2d and @gjsify/webgl to plug in their implementations.
-     */
     static registerContextFactory(contextId: string, factory: (canvas: HTMLCanvasElement, options?: unknown) => unknown): void;
     oncontextlost: ((ev: Event) => unknown) | null;
     oncontextrestored: ((ev: Event) => unknown) | null;
     onwebglcontextcreationerror: ((ev: Event) => unknown) | null;
     onwebglcontextlost: ((ev: Event) => unknown) | null;
     onwebglcontextrestored: ((ev: Event) => unknown) | null;
-    /** Returns the width of the canvas element. Default: 300. */
+    /** Defaults to 300 when the attribute is absent, per spec. */
     get width(): number;
     set width(value: number);
-    /** Returns the height of the canvas element. Default: 150. */
+    /** Defaults to 150 when the attribute is absent, per spec. */
     get height(): number;
     set height(value: number);
-    /**
-     * Returns a rendering context.
-     * Checks the static context factory registry for a matching factory.
-     * Subclasses (e.g. @gjsify/webgl) may override and fall through via super.getContext().
-     */
+    /** `null` for any context type with no registered factory. */
     getContext(contextId: string, options?: unknown): unknown;
-    /** Returns a data URL representing the canvas image. Delegates to the active 2D context if available. */
+    /** Empty string unless a 2D context is active — the pixels live in that context's surface. */
     toDataURL(type?: string, quality?: unknown): string;
-    /** Converts the canvas to a Blob and passes it to the callback. Delegates to the active 2D context if available. */
+    /** Calls back with `null` when there is no 2D context to read pixels from. */
     toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: unknown): void;
-    /** Returns a MediaStream capturing the canvas. Stub — returns empty object. */
+    /** Stub: the returned object is not a usable MediaStream. */
     captureStream(_frameRequestRate?: number): Record<string, never>;
 }

package/lib/types/image.d.ts

@@ -1,17 +1,10 @@
 import { HTMLImageElement } from './html-image-element.js';
 /**
- * Image as constructor.
+ * The `Image` constructor form of HTMLImageElement.
  *
- * Reference:
- * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image.
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image
  */
 export default class Image extends HTMLImageElement {
-    /**
-     * Constructor.
-     *
-     * @param [width] Width.
-     * @param [height] Height.
-     */
     constructor(width?: number | null, height?: number | null);
 }
 export { HTMLImageElement, Image };

package/lib/types/intersection-observer.d.ts

@@ -1,7 +1,7 @@
 import type { Element } from './element.js';
 /**
- * IntersectionObserver stub.
- * Many libraries check for IntersectionObserver existence; this prevents crashes.
+ * Tracks no intersections. It exists because many libraries check for `IntersectionObserver` and
+ * crash without it.
  *
  * Reference: https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver
  */

package/lib/types/mutation-observer.d.ts

@@ -9,9 +9,8 @@ interface MutationObserverOptions {
     attributeFilter?: string[];
 }
 /**
- * MutationObserver stub.
- * Many libraries check for MutationObserver existence; this prevents crashes.
- * Does not actually observe DOM mutations (no layout engine).
+ * Observes nothing — there is no layout engine to observe. It exists because many libraries check
+ * for `MutationObserver` and crash without it.
  *
  * Reference: https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver
  */

package/lib/types/notify-resize.d.ts

@@ -1,11 +1,6 @@
 import { Element } from './element.js';
 /**
- * Notify every `ResizeObserver` subscribed to `target` — or to any
- * ancestor of `target` — that the backing widget's allocation just
- * changed. Called from framework bridges' GTK `resize` signal handlers.
- *
- * @param target  the polyfill DOM element paired with the resized widget
- * @param width   the widget's new allocated width (CSS pixels)
- * @param height  the widget's new allocated height (CSS pixels)
+ * Notify every `ResizeObserver` subscribed to `target` — or to any ancestor of `target` —
+ * that the backing widget's allocation just changed. Dimensions are CSS pixels.
  */
 export declare function notifyElementResize(target: Element, width: number, height: number): void;

package/lib/types/register/window-event-bus.d.ts

@@ -7,29 +7,18 @@ export interface WindowEventBusHost {
     dispatchEvent?: (event: unknown) => boolean;
 }
 /**
- * Install the gjsify window-scope event bus (`__gjsify_globalEventTarget`) on
- * `host` and route `addEventListener` / `removeEventListener` /
- * `dispatchEvent` through it.
+ * Install the gjsify window-scope event bus (`__gjsify_globalEventTarget`) on `host` and route
+ * `addEventListener` / `removeEventListener` / `dispatchEvent` through it.
  *
- * UNCONDITIONAL BY DESIGN (idempotent via the singleton check): loading this
- * register declares a GTK-hosted DOM environment, so the window-scope bus MUST
- * be the same object the GTK→DOM event-bridge dispatches on
- * (`@gjsify/event-bridge` `attachEventControllers()` → `getGlobalEventTarget()`),
- * or window-level input is lost. Bun and Deno ship a NATIVE
- * `globalThis.addEventListener` (GJS and Node do not) — the previous
- * "only install when missing" guard therefore SPLIT the bus on those runtimes:
- * app listeners (e.g. Excalibur `Keyboard.init`'s 'keydown'/'keyup'/'blur')
- * registered on the native runtime EventTarget while the event-bridge
- * dispatched into the never-installed gjsify bus — keyboard input silently
- * dead on bun/deno while the identical bundle worked on gjs/node (measured on
- * showcases/dom/excalibur-jelly-jumper: focus + controller attachment healthy,
- * `__gjsify_globalEventTarget` undefined, Excalibur received no keys).
+ * Installs unconditionally, because the bus must be the same object the GTK→DOM bridge dispatches
+ * on (`@gjsify/event-bridge` `attachEventControllers()` → `getGlobalEventTarget()`) or window-level
+ * input is lost. Bun and Deno ship a native `globalThis.addEventListener` where GJS and Node do
+ * not, so an install-only-when-missing guard split the bus there: Excalibur's `Keyboard.init`
+ * listeners sat on the native EventTarget while the bridge dispatched into a never-installed gjsify
+ * bus, leaving keyboard input dead on bun/deno with the identical bundle working on gjs/node.
  *
- * A pre-existing native surface is not discarded: registrations are ALSO
- * forwarded to it, so genuinely native runtime events (Deno's 'unload' /
- * 'beforeunload', bun's 'error') still reach listeners registered through the
- * window surface. Dispatches go to the gjsify bus only — each event type fires
- * from exactly one side (the runtime never fires DOM input events globally),
- * so nothing double-fires.
+ * A pre-existing native surface is not discarded — registrations are forwarded to it too, so
+ * genuinely native events (Deno's 'unload', bun's 'error') still arrive. Dispatch goes to the
+ * gjsify bus only; the runtime never fires DOM input events globally, so nothing double-fires.
  */
 export declare function installWindowEventBus(host: WindowEventBusHost): OurEventTarget;

package/lib/types/resize-observer.d.ts

@@ -28,22 +28,9 @@ export interface ResizeObserverOptions {
     box?: 'content-box' | 'border-box' | 'device-pixel-content-box';
 }
 /**
- * `ResizeObserver` polyfill. Subscribes to bridge-reported GTK widget
- * resizes via `Element._onResize()` (see `./element.ts`). The bridge calls
- * `notifyElementResize()` from `./notify-resize.ts` which fires the
- * subscribers on the resized element and every ancestor.
- *
- * @example
- * ```ts
- * const observer = new ResizeObserver((entries) => {
- *   for (const entry of entries) {
- *     console.log(entry.target, entry.contentRect.width, entry.contentRect.height);
- *   }
- * });
- * observer.observe(canvas);  // canvas paired with a Gtk.GLArea by WebGLBridge
- * // resize the GTK widget → callback fires with the new dimensions
- * observer.disconnect();
- * ```
+ * `ResizeObserver` polyfill. Subscribes to bridge-reported GTK widget resizes through
+ * `Element._onResize()`; `notifyElementResize()` fires those subscribers on the resized element and
+ * every ancestor.
  */
 export declare class ResizeObserver {
     private readonly _callback;
@@ -51,14 +38,10 @@ export declare class ResizeObserver {
     private _pending;
     constructor(callback: ResizeObserverCallback);
     /**
-     * Start observing `target`. Per spec, the first observation reports
-     * the target's current size — we honour this on a microtask so
-     * consumers that observe inside an initialisation routine receive
-     * the first measurement after their setup completes.
-     *
-     * `opts.box` is accepted for spec compatibility but does not change
-     * behaviour here — content-box, border-box, and device-pixel-content-box
-     * all map to the same single allocation reported by GTK.
+     * Start observing `target`. The spec's mandatory first observation of the current size is
+     * deferred to a microtask, so a consumer observing inside an init routine gets that measurement
+     * after its setup completes. `opts.box` is accepted for compatibility but changes nothing: all
+     * three box modes map to the single allocation GTK reports.
      */
     observe(target: Element, _opts?: ResizeObserverOptions): void;
     unobserve(target: Element): void;

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

@@ -2,8 +2,7 @@ import type { HTMLElement } from '@gjsify/dom-elements';
 /**
  * HTML Image Element.
  *
- * Reference:
- * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement.
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement
  */
 export interface IHTMLImageElement extends HTMLElement {
     alt: string;
@@ -24,18 +23,8 @@ export interface IHTMLImageElement extends HTMLElement {
     width: number;
     readonly x: number;
     readonly y: number;
-    /**
-     * The decode() method of the HTMLImageElement interface returns a Promise that resolves when the image is decoded and it is safe to append the image to the DOM.
-     *
-     * @returns Promise.
-     */
+    /** Resolves once the image is decoded and safe to append to the DOM. */
     decode(): Promise<void>;
-    /**
-     * Clones a node.
-     *
-     * @override
-     * @param [deep=false] "true" to clone deep.
-     * @returns Cloned node.
-     */
+    /** @override */
     cloneNode(deep?: boolean): IHTMLImageElement;
 }

package/lib/types/types/image-data.d.ts

@@ -1,11 +1,11 @@
 import type { PredefinedColorSpace } from './predefined-color-space.js';
-/** The underlying pixel data of an area of a <canvas> element. It is created using the ImageData() constructor or creator methods on the CanvasRenderingContext2D object associated with a canvas: createImageData() and getImageData(). It can also be used to set a part of the canvas by using putImageData(). */
+/** The pixel data of an area of a `<canvas>`. */
 export interface ImageData {
     readonly colorSpace: PredefinedColorSpace;
-    /** Returns the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255. */
+    /** One-dimensional, RGBA order, integers 0-255. */
     readonly data: Uint8ClampedArray<ArrayBuffer>;
-    /** Returns the actual dimensions of the data in the ImageData object, in pixels. */
+    /** Pixels, not CSS units. */
     readonly height: number;
-    /** Returns the actual dimensions of the data in the ImageData object, in pixels. */
+    /** Pixels, not CSS units. */
     readonly width: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/dom-elements",
-    "version": "0.35.0",
+    "version": "0.37.0",
     "description": "DOM element hierarchy (Node, Element, HTMLElement, HTMLImageElement) for GJS",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -71,15 +71,15 @@
         "@girs/gdkpixbuf-2.0": "^4.1.0",
         "@girs/gjs": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
-        "@gjsify/abort-controller": "^0.35.0",
-        "@gjsify/canvas2d-core": "^0.35.0",
-        "@gjsify/dom-events": "^0.35.0",
-        "@gjsify/fetch": "^0.35.0"
+        "@gjsify/abort-controller": "^0.37.0",
+        "@gjsify/canvas2d-core": "^0.37.0",
+        "@gjsify/dom-events": "^0.37.0",
+        "@gjsify/fetch": "^0.37.0"
     },
     "devDependencies": {
         "@girs/gst-1.0": "^4.1.0",
-        "@gjsify/cli": "^0.35.0",
-        "@gjsify/unit": "^0.35.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },