@codexo/exojs 0.7.11 → 0.7.13

package/dist/esm/resources/factories/ImageFactory.js

@@ -1,11 +1,30 @@
 import { determineMimeType } from '../utils.js';
 import { AbstractAssetFactory } from '../AbstractAssetFactory.js';
 
+/**
+ * {@link AssetFactory} implementation that loads PNG, JPG, WebP, AVIF, and
+ * other browser-supported raster image formats and produces a decoded
+ * {@link HTMLImageElement}.
+ *
+ * MIME type detection is performed automatically from the buffer's magic bytes;
+ * pass an explicit `mimeType` in options to override.
+ */
 class ImageFactory extends AbstractAssetFactory {
     storageName = 'image';
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for MIME-type
+     * detection and blob construction.
+     */
     async process(response) {
         return await response.arrayBuffer();
     }
+    /**
+     * Decodes image bytes into a fully loaded {@link HTMLImageElement}.
+     *
+     * Creates a temporary object URL from the buffer, assigns it to an
+     * `<img>` element, and revokes the URL once loading completes or fails.
+     * Rejects if the browser reports a load error or the load is aborted.
+     */
     async create(source, options = {}) {
         const blob = new Blob([source], { type: options.mimeType ?? determineMimeType(source) });
         const objectUrl = this.createObjectUrl(blob);

package/dist/esm/resources/factories/ImageFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"ImageFactory.js","sources":["../../../../../src/resources/factories/ImageFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAOM,MAAO,YAAa,SAAQ,oBAAsC,CAAA;IAEpD,WAAW,GAAG,OAAO;IAE9B,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEO,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;QACtE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QACxF,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnC,YAAA,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;AAChC,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,KAAK,CAAC;AAClB,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AACH;;;;"}
+{"version":3,"file":"ImageFactory.js","sources":["../../../../../src/resources/factories/ImageFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAaA;;;;;;;AAOG;AACG,MAAO,YAAa,SAAQ,oBAAsC,CAAA;IAEpD,WAAW,GAAG,OAAO;AAErC;;;AAGG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEA;;;;;;AAMG;AACI,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;QACtE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QACxF,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnC,YAAA,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;AAChC,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,KAAK,CAAC;AAClB,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AACH;;;;"}

package/dist/esm/resources/factories/JsonFactory.d.ts

@@ -1,6 +1,19 @@
 import { AbstractAssetFactory } from '@/resources/AbstractAssetFactory';
+/**
+ * {@link AssetFactory} implementation that parses JSON files and exposes them
+ * as plain JavaScript values.
+ *
+ * The parsed value is typed as `unknown`; callers are expected to narrow or
+ * cast the result to their specific schema type.
+ */
 export declare class JsonFactory extends AbstractAssetFactory<unknown> {
     readonly storageName = "json";
+    /**
+     * Parses the response body as JSON and returns the resulting value.
+     */
     process(response: Response): Promise<unknown>;
+    /**
+     * Returns the already-parsed value unchanged.
+     */
     create(source: unknown): Promise<unknown>;
 }

package/dist/esm/resources/factories/JsonFactory.js

@@ -1,10 +1,23 @@
 import { AbstractAssetFactory } from '../AbstractAssetFactory.js';
 
+/**
+ * {@link AssetFactory} implementation that parses JSON files and exposes them
+ * as plain JavaScript values.
+ *
+ * The parsed value is typed as `unknown`; callers are expected to narrow or
+ * cast the result to their specific schema type.
+ */
 class JsonFactory extends AbstractAssetFactory {
     storageName = 'json';
+    /**
+     * Parses the response body as JSON and returns the resulting value.
+     */
     async process(response) {
         return await response.json();
     }
+    /**
+     * Returns the already-parsed value unchanged.
+     */
     async create(source) {
         return source;
     }

package/dist/esm/resources/factories/JsonFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"JsonFactory.js","sources":["../../../../../src/resources/factories/JsonFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEM,MAAO,WAAY,SAAQ,oBAA6B,CAAA;IAE1C,WAAW,GAAG,MAAM;IAE7B,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE;IAChC;IAEO,MAAM,MAAM,CAAC,MAAe,EAAA;AAC/B,QAAA,OAAO,MAAM;IACjB;AACH;;;;"}
+{"version":3,"file":"JsonFactory.js","sources":["../../../../../src/resources/factories/JsonFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;AAMG;AACG,MAAO,WAAY,SAAQ,oBAA6B,CAAA;IAE1C,WAAW,GAAG,MAAM;AAEpC;;AAEG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE;IAChC;AAEA;;AAEG;IACI,MAAM,MAAM,CAAC,MAAe,EAAA;AAC/B,QAAA,OAAO,MAAM;IACjB;AACH;;;;"}

package/dist/esm/resources/factories/MusicFactory.d.ts

@@ -2,15 +2,51 @@ import type { PlaybackOptions, StreamingLoadEvent } from '@/core/types';
 import { AbstractAssetFactory } from '@/resources/AbstractAssetFactory';
 import { Music } from '@/audio/Music';
 interface MusicFactoryOptions {
+    /**
+     * MIME type for the audio blob. Inferred from magic bytes when omitted.
+     */
     mimeType?: string;
+    /**
+     * The `HTMLAudioElement` event that signals the asset is ready. Defaults
+     * to `'canplaythrough'`. Use `'loadedmetadata'` or `'canplay'` for faster
+     * (but potentially less buffered) readiness.
+     */
     loadEvent?: StreamingLoadEvent;
+    /** Initial playback settings forwarded to the {@link Music} instance. */
     playbackOptions?: Partial<PlaybackOptions>;
 }
+/**
+ * {@link AssetFactory} implementation that loads streaming audio assets
+ * (MP3, OGG, WAV, AAC, and other browser-supported formats) and produces a
+ * {@link Music} instance backed by an `<audio>` element.
+ *
+ * Unlike {@link SoundFactory}, music assets are decoded lazily via the browser's
+ * streaming audio pipeline rather than being fully decoded into an
+ * {@link AudioBuffer} up-front, making them appropriate for long-form
+ * background tracks. The underlying `<audio>` elements are paused and detached
+ * when {@link MusicFactory.destroy} is called.
+ */
 export declare class MusicFactory extends AbstractAssetFactory<Music> {
     readonly storageName = "music";
     private readonly _audioElements;
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for blob
+     * construction.
+     */
     process(response: Response): Promise<ArrayBuffer>;
+    /**
+     * Wraps audio bytes in an `<audio>` element and resolves with a
+     * {@link Music} instance once the configured `loadEvent` fires.
+     *
+     * Rejects if the element emits an `error` or `abort` event before the
+     * load event is received.
+     */
     create(source: ArrayBuffer, options?: MusicFactoryOptions): Promise<Music>;
+    /**
+     * Pauses and resets all `<audio>` elements created by this factory to
+     * release media resources, then delegates to the base
+     * {@link AbstractAssetFactory.destroy} to revoke any object URLs.
+     */
     destroy(): void;
 }
 export {};

package/dist/esm/resources/factories/MusicFactory.js

@@ -3,25 +3,65 @@ import { determineMimeType } from '../utils.js';
 import { Music } from '../../audio/Music.js';
 
 const onceListenerOption = { once: true };
+/**
+ * {@link AssetFactory} implementation that loads streaming audio assets
+ * (MP3, OGG, WAV, AAC, and other browser-supported formats) and produces a
+ * {@link Music} instance backed by an `<audio>` element.
+ *
+ * Unlike {@link SoundFactory}, music assets are decoded lazily via the browser's
+ * streaming audio pipeline rather than being fully decoded into an
+ * {@link AudioBuffer} up-front, making them appropriate for long-form
+ * background tracks. The underlying `<audio>` elements are paused and detached
+ * when {@link MusicFactory.destroy} is called.
+ */
 class MusicFactory extends AbstractAssetFactory {
     storageName = 'music';
     _audioElements = [];
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for blob
+     * construction.
+     */
     async process(response) {
         return await response.arrayBuffer();
     }
+    /**
+     * Wraps audio bytes in an `<audio>` element and resolves with a
+     * {@link Music} instance once the configured `loadEvent` fires.
+     *
+     * Rejects if the element emits an `error` or `abort` event before the
+     * load event is received.
+     */
     async create(source, options = {}) {
         const { mimeType, loadEvent, playbackOptions } = options;
         const blob = new Blob([source], { type: mimeType ?? determineMimeType(source) });
+        const objectUrl = this.createObjectUrl(blob);
         return new Promise((resolve, reject) => {
             const audio = document.createElement('audio');
             this._audioElements.push(audio);
-            audio.addEventListener('error', () => reject(Error('Error loading audio source.')), onceListenerOption);
-            audio.addEventListener('abort', () => reject(Error('Audio loading was canceled.')), onceListenerOption);
-            audio.addEventListener(loadEvent ?? 'canplaythrough', () => resolve(new Music(audio, playbackOptions)), onceListenerOption);
+            const finalize = () => {
+                this.revokeObjectUrl(objectUrl);
+            };
+            audio.addEventListener('error', () => {
+                finalize();
+                reject(Error('Error loading audio source.'));
+            }, onceListenerOption);
+            audio.addEventListener('abort', () => {
+                finalize();
+                reject(Error('Audio loading was canceled.'));
+            }, onceListenerOption);
+            audio.addEventListener(loadEvent ?? 'canplaythrough', () => {
+                finalize();
+                resolve(new Music(audio, playbackOptions));
+            }, onceListenerOption);
             audio.preload = 'auto';
-            audio.src = this.createObjectUrl(blob);
+            audio.src = objectUrl;
         });
     }
+    /**
+     * Pauses and resets all `<audio>` elements created by this factory to
+     * release media resources, then delegates to the base
+     * {@link AbstractAssetFactory.destroy} to revoke any object URLs.
+     */
     destroy() {
         for (const audio of this._audioElements) {
             audio.pause();

package/dist/esm/resources/factories/MusicFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"MusicFactory.js","sources":["../../../../../src/resources/factories/MusicFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA,MAAM,kBAAkB,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE;AAQnC,MAAO,YAAa,SAAQ,oBAA2B,CAAA;IAEzC,WAAW,GAAG,OAAO;IAEpB,cAAc,GAA4B,EAAE;IAEtD,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEO,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;QACtE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,OAAO;QACxD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAEhF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;YACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;AAC7C,YAAA,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;AAE/B,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC,EAAE,kBAAkB,CAAC;AACvG,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC,EAAE,kBAAkB,CAAC;YACvG,KAAK,CAAC,gBAAgB,CAAC,SAAS,IAAI,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,EAAE,kBAAkB,CAAC;AAE3H,YAAA,KAAK,CAAC,OAAO,GAAG,MAAM;YACtB,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;AAC1C,QAAA,CAAC,CAAC;IACN;IAEgB,OAAO,GAAA;AACnB,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE;YACrC,KAAK,CAAC,KAAK,EAAE;AACb,YAAA,KAAK,CAAC,GAAG,GAAG,EAAE;YACd,KAAK,CAAC,IAAI,EAAE;QAChB;AACA,QAAA,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC9B,KAAK,CAAC,OAAO,EAAE;IACnB;AACH;;;;"}
+{"version":3,"file":"MusicFactory.js","sources":["../../../../../src/resources/factories/MusicFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAKA,MAAM,kBAAkB,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE;AAiBzC;;;;;;;;;;AAUG;AACG,MAAO,YAAa,SAAQ,oBAA2B,CAAA;IAEzC,WAAW,GAAG,OAAO;IAEpB,cAAc,GAA4B,EAAE;AAE7D;;;AAGG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEA;;;;;;AAMG;AACI,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;QACtE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,OAAO;QACxD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChF,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;YACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;AAC7C,YAAA,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;YAE/B,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;YAChD,CAAC,EAAE,kBAAkB,CAAC;AACtB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;YAChD,CAAC,EAAE,kBAAkB,CAAC;YACtB,KAAK,CAAC,gBAAgB,CAAC,SAAS,IAAI,gBAAgB,EAAE,MAAK;AACvD,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;YAC9C,CAAC,EAAE,kBAAkB,CAAC;AAEtB,YAAA,KAAK,CAAC,OAAO,GAAG,MAAM;AACtB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AAEA;;;;AAIG;IACa,OAAO,GAAA;AACnB,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE;YACrC,KAAK,CAAC,KAAK,EAAE;AACb,YAAA,KAAK,CAAC,GAAG,GAAG,EAAE;YACd,KAAK,CAAC,IAAI,EAAE;QAChB;AACA,QAAA,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC9B,KAAK,CAAC,OAAO,EAAE;IACnB;AACH;;;;"}

package/dist/esm/resources/factories/SoundFactory.d.ts

@@ -2,13 +2,42 @@ import type { PlaybackOptions } from '@/core/types';
 import { AbstractAssetFactory } from '@/resources/AbstractAssetFactory';
 import { Sound, type AudioSpriteClip } from '@/audio/Sound';
 interface SoundFactoryOptions {
+    /** Initial playback settings forwarded to the {@link Sound} instance. */
     playbackOptions?: Partial<PlaybackOptions>;
+    /**
+     * Number of concurrent voices the {@link Sound} instance pre-allocates.
+     * Higher values allow more simultaneous plays of the same clip. Default
+     * 8 (chosen by {@link Sound} when omitted).
+     */
     poolSize?: number;
+    /**
+     * Named sub-regions of the decoded {@link AudioBuffer} for use as an audio
+     * sprite sheet. Each entry maps a clip name to a {@link AudioSpriteClip}
+     * descriptor.
+     */
     sprites?: Readonly<Record<string, AudioSpriteClip>>;
 }
+/**
+ * {@link AssetFactory} implementation that loads short audio assets
+ * (MP3, OGG, WAV, AAC, and other Web Audio API-supported formats), fully
+ * decodes them into an {@link AudioBuffer}, and produces a {@link Sound}
+ * instance ready for low-latency playback.
+ *
+ * For long-form background music use {@link MusicFactory} instead, which
+ * streams audio without up-front decoding. Supports audio sprite sheets via
+ * the `sprites` option.
+ */
 export declare class SoundFactory extends AbstractAssetFactory<Sound> {
     readonly storageName = "sound";
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for decoding
+     * by the Web Audio API.
+     */
     process(response: Response): Promise<ArrayBuffer>;
+    /**
+     * Fully decodes the audio buffer via the shared `AudioContext` and
+     * constructs a {@link Sound} with the given options.
+     */
     create(source: ArrayBuffer, options?: SoundFactoryOptions): Promise<Sound>;
 }
 export {};

package/dist/esm/resources/factories/SoundFactory.js

@@ -2,11 +2,29 @@ import { AbstractAssetFactory } from '../AbstractAssetFactory.js';
 import { Sound } from '../../audio/Sound.js';
 import { decodeAudioData } from '../../audio/audio-context.js';
 
+/**
+ * {@link AssetFactory} implementation that loads short audio assets
+ * (MP3, OGG, WAV, AAC, and other Web Audio API-supported formats), fully
+ * decodes them into an {@link AudioBuffer}, and produces a {@link Sound}
+ * instance ready for low-latency playback.
+ *
+ * For long-form background music use {@link MusicFactory} instead, which
+ * streams audio without up-front decoding. Supports audio sprite sheets via
+ * the `sprites` option.
+ */
 class SoundFactory extends AbstractAssetFactory {
     storageName = 'sound';
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for decoding
+     * by the Web Audio API.
+     */
     async process(response) {
         return await response.arrayBuffer();
     }
+    /**
+     * Fully decodes the audio buffer via the shared `AudioContext` and
+     * constructs a {@link Sound} with the given options.
+     */
     async create(source, options = {}) {
         const audioBuffer = await decodeAudioData(source);
         const sound = new Sound(audioBuffer, {

package/dist/esm/resources/factories/SoundFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"SoundFactory.js","sources":["../../../../../src/resources/factories/SoundFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAWM,MAAO,YAAa,SAAQ,oBAA2B,CAAA;IAEzC,WAAW,GAAG,OAAO;IAE9B,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEO,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;AACtE,QAAA,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC;AAEjD,QAAA,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,WAAW,EAAE;YACjC,GAAG,OAAO,CAAC,eAAe;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;AAC3B,SAAA,CAAC;AAEF,QAAA,OAAO,KAAK;IAChB;AACH;;;;"}
+{"version":3,"file":"SoundFactory.js","sources":["../../../../../src/resources/factories/SoundFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAsBA;;;;;;;;;AASG;AACG,MAAO,YAAa,SAAQ,oBAA2B,CAAA;IAEzC,WAAW,GAAG,OAAO;AAErC;;;AAGG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEA;;;AAGG;AACI,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;AACtE,QAAA,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC;AAEjD,QAAA,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,WAAW,EAAE;YACjC,GAAG,OAAO,CAAC,eAAe;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;AAC3B,SAAA,CAAC;AAEF,QAAA,OAAO,KAAK;IAChB;AACH;;;;"}

package/dist/esm/resources/factories/SvgFactory.d.ts

@@ -1,6 +1,25 @@
 import { AbstractAssetFactory } from '@/resources/AbstractAssetFactory';
+/**
+ * {@link AssetFactory} implementation that loads SVG markup and produces a
+ * rasterised {@link HTMLImageElement}.
+ *
+ * The SVG source text is wrapped in an `image/svg+xml` blob and decoded by the
+ * browser's image pipeline, which means the result is a bitmap snapshot at the
+ * element's intrinsic size rather than a live, interactive SVG DOM. Use this
+ * when you need an SVG as a static sprite or texture source.
+ */
 export declare class SvgFactory extends AbstractAssetFactory<HTMLImageElement> {
     readonly storageName = "svg";
+    /**
+     * Reads the response body as UTF-8 text containing the raw SVG markup.
+     */
     process(response: Response): Promise<string>;
+    /**
+     * Renders the SVG markup into a fully loaded {@link HTMLImageElement}.
+     *
+     * Creates a temporary `image/svg+xml` object URL, assigns it to an `<img>`
+     * element, and revokes the URL once loading settles. Rejects on load error
+     * or abort.
+     */
     create(source: string): Promise<HTMLImageElement>;
 }

package/dist/esm/resources/factories/SvgFactory.js

@@ -1,10 +1,29 @@
 import { AbstractAssetFactory } from '../AbstractAssetFactory.js';
 
+/**
+ * {@link AssetFactory} implementation that loads SVG markup and produces a
+ * rasterised {@link HTMLImageElement}.
+ *
+ * The SVG source text is wrapped in an `image/svg+xml` blob and decoded by the
+ * browser's image pipeline, which means the result is a bitmap snapshot at the
+ * element's intrinsic size rather than a live, interactive SVG DOM. Use this
+ * when you need an SVG as a static sprite or texture source.
+ */
 class SvgFactory extends AbstractAssetFactory {
     storageName = 'svg';
+    /**
+     * Reads the response body as UTF-8 text containing the raw SVG markup.
+     */
     async process(response) {
         return await response.text();
     }
+    /**
+     * Renders the SVG markup into a fully loaded {@link HTMLImageElement}.
+     *
+     * Creates a temporary `image/svg+xml` object URL, assigns it to an `<img>`
+     * element, and revokes the URL once loading settles. Rejects on load error
+     * or abort.
+     */
     async create(source) {
         const blob = new Blob([source], { type: 'image/svg+xml' });
         const objectUrl = this.createObjectUrl(blob);

package/dist/esm/resources/factories/SvgFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"SvgFactory.js","sources":["../../../../../src/resources/factories/SvgFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEM,MAAO,UAAW,SAAQ,oBAAsC,CAAA;IAElD,WAAW,GAAG,KAAK;IAE5B,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE;IAChC;IAEO,MAAM,MAAM,CAAC,MAAc,EAAA;AAC9B,QAAA,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnC,YAAA,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;AAChC,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,KAAK,CAAC;AAClB,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AACH;;;;"}
+{"version":3,"file":"SvgFactory.js","sources":["../../../../../src/resources/factories/SvgFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;AAQG;AACG,MAAO,UAAW,SAAQ,oBAAsC,CAAA;IAElD,WAAW,GAAG,KAAK;AAEnC;;AAEG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE;IAChC;AAEA;;;;;;AAMG;IACI,MAAM,MAAM,CAAC,MAAc,EAAA;AAC9B,QAAA,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnC,YAAA,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;AAChC,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,KAAK,CAAC;AAClB,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AACH;;;;"}

package/dist/esm/resources/factories/TextFactory.d.ts

@@ -1,6 +1,17 @@
 import { AbstractAssetFactory } from '@/resources/AbstractAssetFactory';
+/**
+ * {@link AssetFactory} implementation that loads plain-text files (TXT, CSV,
+ * GLSL shaders, HTML fragments, and any other UTF-8 text) and exposes them as
+ * JavaScript strings.
+ */
 export declare class TextFactory extends AbstractAssetFactory<string> {
     readonly storageName = "text";
+    /**
+     * Reads the response body as a UTF-8 decoded string.
+     */
     process(response: Response): Promise<string>;
+    /**
+     * Returns the decoded string unchanged.
+     */
     create(source: string): Promise<string>;
 }

package/dist/esm/resources/factories/TextFactory.js

@@ -1,10 +1,21 @@
 import { AbstractAssetFactory } from '../AbstractAssetFactory.js';
 
+/**
+ * {@link AssetFactory} implementation that loads plain-text files (TXT, CSV,
+ * GLSL shaders, HTML fragments, and any other UTF-8 text) and exposes them as
+ * JavaScript strings.
+ */
 class TextFactory extends AbstractAssetFactory {
     storageName = 'text';
+    /**
+     * Reads the response body as a UTF-8 decoded string.
+     */
     async process(response) {
         return await response.text();
     }
+    /**
+     * Returns the decoded string unchanged.
+     */
     async create(source) {
         return source;
     }

package/dist/esm/resources/factories/TextFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextFactory.js","sources":["../../../../../src/resources/factories/TextFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEM,MAAO,WAAY,SAAQ,oBAA4B,CAAA;IAEzC,WAAW,GAAG,MAAM;IAE7B,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE;IAChC;IAEO,MAAM,MAAM,CAAC,MAAc,EAAA;AAC9B,QAAA,OAAO,MAAM;IACjB;AACH;;;;"}
+{"version":3,"file":"TextFactory.js","sources":["../../../../../src/resources/factories/TextFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;AAIG;AACG,MAAO,WAAY,SAAQ,oBAA4B,CAAA;IAEzC,WAAW,GAAG,MAAM;AAEpC;;AAEG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE;IAChC;AAEA;;AAEG;IACI,MAAM,MAAM,CAAC,MAAc,EAAA;AAC9B,QAAA,OAAO,MAAM;IACjB;AACH;;;;"}

package/dist/esm/resources/factories/TextureFactory.d.ts

@@ -1,13 +1,38 @@
 import { Texture } from '@/rendering/texture/Texture';
 import type { SamplerOptions } from '@/rendering/texture/Sampler';
 import { AbstractAssetFactory } from '@/resources/AbstractAssetFactory';
-interface TextureFactoryOptions {
+/** Construction options for {@link TextureFactory.create}. */
+export interface TextureFactoryOptions {
+    /**
+     * MIME type for the intermediate blob. Inferred from magic bytes when
+     * omitted.
+     */
     mimeType?: string;
+    /** Sampler parameters (wrap mode, filter, etc.) forwarded to the {@link Texture} constructor. */
     samplerOptions?: SamplerOptions;
 }
+/**
+ * {@link AssetFactory} implementation that loads PNG, JPG, WebP, AVIF, and
+ * other browser-supported raster image formats and produces a GPU-ready
+ * {@link Texture} instance.
+ *
+ * MIME type detection is performed automatically from the buffer's magic bytes;
+ * pass an explicit `mimeType` to override. Sampler state (wrap, filter, etc.)
+ * can be configured via `samplerOptions`.
+ */
 export declare class TextureFactory extends AbstractAssetFactory<Texture> {
     readonly storageName = "texture";
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for MIME-type
+     * detection and blob construction.
+     */
     process(response: Response): Promise<ArrayBuffer>;
+    /**
+     * Decodes image bytes into a fully loaded {@link HTMLImageElement} and
+     * wraps it in a {@link Texture} with the given sampler options.
+     *
+     * Creates a temporary object URL, resolves when the image's `load` event
+     * fires, and revokes the URL regardless of outcome.
+     */
     create(source: ArrayBuffer, options?: TextureFactoryOptions): Promise<Texture>;
 }
-export {};

package/dist/esm/resources/factories/TextureFactory.js

@@ -2,11 +2,31 @@ import { Texture } from '../../rendering/texture/Texture.js';
 import { AbstractAssetFactory } from '../AbstractAssetFactory.js';
 import { determineMimeType } from '../utils.js';
 
+/**
+ * {@link AssetFactory} implementation that loads PNG, JPG, WebP, AVIF, and
+ * other browser-supported raster image formats and produces a GPU-ready
+ * {@link Texture} instance.
+ *
+ * MIME type detection is performed automatically from the buffer's magic bytes;
+ * pass an explicit `mimeType` to override. Sampler state (wrap, filter, etc.)
+ * can be configured via `samplerOptions`.
+ */
 class TextureFactory extends AbstractAssetFactory {
     storageName = 'texture';
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for MIME-type
+     * detection and blob construction.
+     */
     async process(response) {
         return await response.arrayBuffer();
     }
+    /**
+     * Decodes image bytes into a fully loaded {@link HTMLImageElement} and
+     * wraps it in a {@link Texture} with the given sampler options.
+     *
+     * Creates a temporary object URL, resolves when the image's `load` event
+     * fires, and revokes the URL regardless of outcome.
+     */
     async create(source, options = {}) {
         const { mimeType, samplerOptions } = options;
         const blob = new Blob([source], { type: mimeType ?? determineMimeType(source) });

package/dist/esm/resources/factories/TextureFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextureFactory.js","sources":["../../../../../src/resources/factories/TextureFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAUM,MAAO,cAAe,SAAQ,oBAA6B,CAAA;IAE7C,WAAW,GAAG,SAAS;IAEhC,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEO,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAAiC,EAAE,EAAA;AACxE,QAAA,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO;QAC5C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChF,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnC,YAAA,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;AAChC,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;AAC/C,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AACH;;;;"}
+{"version":3,"file":"TextureFactory.js","sources":["../../../../../src/resources/factories/TextureFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAgBA;;;;;;;;AAQG;AACG,MAAO,cAAe,SAAQ,oBAA6B,CAAA;IAE7C,WAAW,GAAG,SAAS;AAEvC;;;AAGG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEA;;;;;;AAMG;AACI,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAAiC,EAAE,EAAA;AACxE,QAAA,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO;QAC5C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChF,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;AACnC,YAAA,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAK;AAChC,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;AAC/C,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAChD,YAAA,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAElB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AACH;;;;"}

package/dist/esm/resources/factories/VideoFactory.d.ts

@@ -3,16 +3,53 @@ import type { SamplerOptions } from '@/rendering/texture/Sampler';
 import type { PlaybackOptions, StreamingLoadEvent } from '@/core/types';
 import { Video } from '@/rendering/video/Video';
 interface VideoFactoryOptions {
+    /**
+     * MIME type for the video blob. Inferred from magic bytes when omitted.
+     */
     mimeType?: string;
+    /**
+     * The `HTMLVideoElement` event that signals the asset is ready for
+     * playback. Defaults to `'canplaythrough'`. Use `'loadedmetadata'` for
+     * faster (dimensions-only) readiness.
+     */
     loadEvent?: StreamingLoadEvent;
+    /** Initial playback settings forwarded to the {@link Video} instance. */
     playbackOptions?: Partial<PlaybackOptions>;
+    /** Sampler parameters forwarded to the {@link Video} instance's texture. */
     samplerOptions?: Partial<SamplerOptions>;
 }
+/**
+ * {@link AssetFactory} implementation that loads video files (MP4, WebM, OGG,
+ * and other browser-supported container formats) and produces a {@link Video}
+ * instance suitable for use as a dynamic texture source in the rendering
+ * pipeline.
+ *
+ * Video data is buffered via a `<video>` element rather than decoded up-front.
+ * The `'stalled'` event is intentionally not treated as an error because it
+ * fires transiently during normal buffering on slow connections. All `<video>`
+ * elements are paused and detached when {@link VideoFactory.destroy} is called.
+ */
 export declare class VideoFactory extends AbstractAssetFactory<Video> {
     readonly storageName = "video";
     private readonly _videoElements;
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for blob
+     * construction.
+     */
     process(response: Response): Promise<ArrayBuffer>;
+    /**
+     * Wraps video bytes in a `<video>` element and resolves with a
+     * {@link Video} instance once the configured `loadEvent` fires.
+     *
+     * Rejects if the element emits `error`, `abort`, or `emptied` before the
+     * load event is received.
+     */
     create(source: ArrayBuffer, options?: VideoFactoryOptions): Promise<Video>;
+    /**
+     * Pauses and resets all `<video>` elements created by this factory to
+     * release media resources, then delegates to the base
+     * {@link AbstractAssetFactory.destroy} to revoke any object URLs.
+     */
     destroy(): void;
 }
 export {};

package/dist/esm/resources/factories/VideoFactory.js

@@ -3,28 +3,71 @@ import { determineMimeType } from '../utils.js';
 import { Video } from '../../rendering/video/Video.js';
 
 const onceListenerOption = { once: true };
+/**
+ * {@link AssetFactory} implementation that loads video files (MP4, WebM, OGG,
+ * and other browser-supported container formats) and produces a {@link Video}
+ * instance suitable for use as a dynamic texture source in the rendering
+ * pipeline.
+ *
+ * Video data is buffered via a `<video>` element rather than decoded up-front.
+ * The `'stalled'` event is intentionally not treated as an error because it
+ * fires transiently during normal buffering on slow connections. All `<video>`
+ * elements are paused and detached when {@link VideoFactory.destroy} is called.
+ */
 class VideoFactory extends AbstractAssetFactory {
     storageName = 'video';
     _videoElements = [];
+    /**
+     * Reads the full response body as an {@link ArrayBuffer} for blob
+     * construction.
+     */
     async process(response) {
         return await response.arrayBuffer();
     }
+    /**
+     * Wraps video bytes in a `<video>` element and resolves with a
+     * {@link Video} instance once the configured `loadEvent` fires.
+     *
+     * Rejects if the element emits `error`, `abort`, or `emptied` before the
+     * load event is received.
+     */
     async create(source, options = {}) {
         const { mimeType, loadEvent, playbackOptions, samplerOptions } = options;
         const blob = new Blob([source], { type: mimeType ?? determineMimeType(source) });
+        const objectUrl = this.createObjectUrl(blob);
         return new Promise((resolve, reject) => {
             const video = document.createElement('video');
             this._videoElements.push(video);
-            video.addEventListener('error', () => reject(Error('Video loading error.')), onceListenerOption);
-            video.addEventListener('abort', () => reject(Error('Video loading error: cancelled.')), onceListenerOption);
-            video.addEventListener('emptied', () => reject(Error('Video loading error: emptied.')), onceListenerOption);
+            const finalize = () => {
+                this.revokeObjectUrl(objectUrl);
+            };
+            video.addEventListener('error', () => {
+                finalize();
+                reject(Error('Video loading error.'));
+            }, onceListenerOption);
+            video.addEventListener('abort', () => {
+                finalize();
+                reject(Error('Video loading error: cancelled.'));
+            }, onceListenerOption);
+            video.addEventListener('emptied', () => {
+                finalize();
+                reject(Error('Video loading error: emptied.'));
+            }, onceListenerOption);
             // 'stalled' is intentionally omitted: it fires transiently during normal buffering
             // and would cause spurious rejections for large files on slow connections.
-            video.addEventListener(loadEvent ?? 'canplaythrough', () => resolve(new Video(video, playbackOptions, samplerOptions)), onceListenerOption);
+            video.addEventListener(loadEvent ?? 'canplaythrough', () => {
+                finalize();
+                resolve(new Video(video, playbackOptions, samplerOptions));
+            }, onceListenerOption);
             video.preload = 'auto';
-            video.src = this.createObjectUrl(blob);
+            video.src = objectUrl;
         });
     }
+    /**
+     * Pauses and resets all `<video>` elements created by this factory to
+     * release media resources, then delegates to the base
+     * {@link AbstractAssetFactory.destroy} to revoke any object URLs.
+     */
     destroy() {
         for (const video of this._videoElements) {
             video.pause();

package/dist/esm/resources/factories/VideoFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"VideoFactory.js","sources":["../../../../../src/resources/factories/VideoFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA,MAAM,kBAAkB,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE;AASnC,MAAO,YAAa,SAAQ,oBAA2B,CAAA;IAEzC,WAAW,GAAG,OAAO;IAEpB,cAAc,GAA4B,EAAE;IAEtD,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEO,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;QACtE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,GAAG,OAAO;QACxE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAEhF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;YACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;AAC7C,YAAA,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;AAE/B,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,EAAE,kBAAkB,CAAC;AAChG,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC,EAAE,kBAAkB,CAAC;AAC3G,YAAA,KAAK,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC,EAAE,kBAAkB,CAAC;;;YAG3G,KAAK,CAAC,gBAAgB,CAAC,SAAS,IAAI,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC,EAAE,kBAAkB,CAAC;AAE3I,YAAA,KAAK,CAAC,OAAO,GAAG,MAAM;YACtB,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;AAC1C,QAAA,CAAC,CAAC;IACN;IAEgB,OAAO,GAAA;AACnB,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE;YACrC,KAAK,CAAC,KAAK,EAAE;AACb,YAAA,KAAK,CAAC,GAAG,GAAG,EAAE;YACd,KAAK,CAAC,IAAI,EAAE;QAChB;AACA,QAAA,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC9B,KAAK,CAAC,OAAO,EAAE;IACnB;AACH;;;;"}
+{"version":3,"file":"VideoFactory.js","sources":["../../../../../src/resources/factories/VideoFactory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA,MAAM,kBAAkB,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE;AAmBzC;;;;;;;;;;AAUG;AACG,MAAO,YAAa,SAAQ,oBAA2B,CAAA;IAEzC,WAAW,GAAG,OAAO;IAEpB,cAAc,GAA4B,EAAE;AAE7D;;;AAGG;IACI,MAAM,OAAO,CAAC,QAAkB,EAAA;AACnC,QAAA,OAAO,MAAM,QAAQ,CAAC,WAAW,EAAE;IACvC;AAEA;;;;;;AAMG;AACI,IAAA,MAAM,MAAM,CAAC,MAAmB,EAAE,UAA+B,EAAE,EAAA;QACtE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,GAAG,OAAO;QACxE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChF,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;QAE5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,KAAI;YACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;AAC7C,YAAA,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;YAE/B,MAAM,QAAQ,GAAG,MAAW;AACxB,gBAAA,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC;AACnC,YAAA,CAAC;AAED,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;YACzC,CAAC,EAAE,kBAAkB,CAAC;AACtB,YAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAK;AACjC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACpD,CAAC,EAAE,kBAAkB,CAAC;AACtB,YAAA,KAAK,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAK;AACnC,gBAAA,QAAQ,EAAE;AACV,gBAAA,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAClD,CAAC,EAAE,kBAAkB,CAAC;;;YAGtB,KAAK,CAAC,gBAAgB,CAAC,SAAS,IAAI,gBAAgB,EAAE,MAAK;AACvD,gBAAA,QAAQ,EAAE;gBACV,OAAO,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;YAC9D,CAAC,EAAE,kBAAkB,CAAC;AAEtB,YAAA,KAAK,CAAC,OAAO,GAAG,MAAM;AACtB,YAAA,KAAK,CAAC,GAAG,GAAG,SAAS;AACzB,QAAA,CAAC,CAAC;IACN;AAEA;;;;AAIG;IACa,OAAO,GAAA;AACnB,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE;YACrC,KAAK,CAAC,KAAK,EAAE;AACb,YAAA,KAAK,CAAC,GAAG,GAAG,EAAE;YACd,KAAK,CAAC,IAAI,EAAE;QAChB;AACA,QAAA,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC9B,KAAK,CAAC,OAAO,EAAE;IACnB;AACH;;;;"}