@zephyr3d/scene 0.9.2 → 0.9.4

package/dist/asset/assetmanager.js

@@ -24,6 +24,7 @@ import '../material/pbrsg.js';
 import { PBRBluePrintMaterial } from '../material/pbrblueprint.js';
 import '../material/sprite.js';
 import '../material/sprite_std.js';
+import '../material/msdf_text.js';
 import { SpriteBlueprintMaterial } from '../material/spriteblueprint.js';
 import { BoundingBox } from '../utility/bounding_volume.js';
 import { MaterialBlueprintIR } from '../utility/blueprint/material/ir.js';
@@ -32,21 +33,22 @@ import '../render/rendergraph/forward_plus_builder.js';
 import '../render/sky.js';
 import '../render/clipmap.js';
 import '../shaders/atmosphere.js';
+import { FontAsset } from '../text/font/font_asset.js';
 
-/**
- * Centralized asset manager for loading and caching resources.
- *
- * Responsibilities:
- * - Abstracts resource loading via VFS (text/json/binary).
- * - Dispatches texture/model loading to registered loaders by MIME type.
- * - Caches results and uses weak references to allow GPU resources to be GC'd when unused.
- * - Harmonizes cross-backend constraints (e.g., WebGL non-power-of-two rules and sRGB handling).
- * - Provides access to built-in textures with device-restore handlers.
- *
- * Threading/async model:
- * - All I/O is async; repeated calls are coalesced via internal promise caches keyed by URL or hash.
- *
- * @public
+/**
+ * Centralized asset manager for loading and caching resources.
+ *
+ * Responsibilities:
+ * - Abstracts resource loading via VFS (text/json/binary).
+ * - Dispatches texture/model loading to registered loaders by MIME type.
+ * - Caches results and uses weak references to allow GPU resources to be GC'd when unused.
+ * - Harmonizes cross-backend constraints (e.g., WebGL non-power-of-two rules and sRGB handling).
+ * - Provides access to built-in textures with device-restore handlers.
+ *
+ * Threading/async model:
+ * - All I/O is async; repeated calls are coalesced via internal promise caches keyed by URL or hash.
+ *
+ * @public
  */ class AssetManager {
     /** @internal */ static _builtinTextures = {};
     /** @internal */ static _builtinTextureLoaders = {
@@ -64,6 +66,7 @@ import '../shaders/atmosphere.js';
     /** @internal */ _textures;
     /** @internal */ _models;
     /** @internal */ _binaryDatas;
+    /** @internal */ _fontAssets;
     /** @internal */ _textDatas;
     /** @internal */ _bluePrints;
     /** @internal */ _materials;
@@ -71,8 +74,8 @@ import '../shaders/atmosphere.js';
     /** @internal */ _skeletons;
     /** @internal */ _jsonDatas;
     /** @internal */ _resourceManager;
-    /**
-   * Creates an instance of AssetManager
+    /**
+   * Creates an instance of AssetManager
    */ constructor(resourceManager){
         this._resourceManager = resourceManager ?? getEngine().resourceManager;
         this._textures = {};
@@ -82,21 +85,22 @@ import '../shaders/atmosphere.js';
         this._skeletons = {};
         this._bluePrints = {};
         this._binaryDatas = {};
+        this._fontAssets = {};
         this._textDatas = {};
         this._jsonDatas = {};
     }
-    /**
-   * VFS used to read resources (files, URLs, virtual mounts).
+    /**
+   * VFS used to read resources (files, URLs, virtual mounts).
    */ get vfs() {
         return this._resourceManager.VFS;
     }
-    /**
-   * Clear cached references and promises.
-   *
-   * - Disposes any DWeakRef holders maintained by this manager.
-   * - Empties internal maps for textures, models, and raw data (text/json/binary).
-   * - Does not forcibly dispose GPU resources; it only clears references so they can be GC'd
-   *   if no other owners are holding them.
+    /**
+   * Clear cached references and promises.
+   *
+   * - Disposes any DWeakRef holders maintained by this manager.
+   * - Empties internal maps for textures, models, and raw data (text/json/binary).
+   * - Does not forcibly dispose GPU resources; it only clears references so they can be GC'd
+   *   if no other owners are holding them.
    */ clearCache() {
         for(const k in Object.keys(this._textures)){
             const v = this._textures[k];
@@ -133,43 +137,58 @@ import '../shaders/atmosphere.js';
             }
         }
         this._skeletons = {};
+        this._fontAssets = {};
         this._binaryDatas = {};
         this._textDatas = {};
         this._jsonDatas = {};
     }
-    /**
-   * Register a texture loader (highest priority first).
-   *
-   * Note: This is a static registry shared by all AssetManager instances.
-   *
-   * @param loader - A concrete texture loader implementation.
+    /**
+   * Removes a cached font asset entry by URL.
+   *
+   * This only evicts the cache entry. It does not dispose any external references to the FontAsset.
+   *
+   * @param url - Resource URL or VFS path.
+   * @returns `true` if a cache entry existed and was removed.
+   */ releaseFontAsset(url) {
+        if (url in this._fontAssets) {
+            delete this._fontAssets[url];
+            return true;
+        }
+        return false;
+    }
+    /**
+   * Register a texture loader (highest priority first).
+   *
+   * Note: This is a static registry shared by all AssetManager instances.
+   *
+   * @param loader - A concrete texture loader implementation.
    */ static addTextureLoader(loader) {
         if (loader) {
             this._textureLoaders.unshift(loader);
         }
     }
-    /**
-   * Register a model loader (highest priority first).
-   *
-   * Note: This is a static registry shared by all AssetManager instances.
-   *
-   * @param loader - A concrete model loader implementation.
+    /**
+   * Register a model loader (highest priority first).
+   *
+   * Note: This is a static registry shared by all AssetManager instances.
+   *
+   * @param loader - A concrete model loader implementation.
    */ static addModelLoader(loader) {
         if (loader) {
             this._modelLoaders.unshift(loader);
         }
     }
-    /**
-   * Fetch a UTF-8 text resource via VFS.
-   *
-   * - Results are cached per resolved URL (via HttpRequest.urlResolver if provided; otherwise the raw URL).
-   * - If cached, any provided postProcess is ignored for subsequent calls; create a separate AssetManager
-   *   if you need different post-processing of the same URL.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the loaded text.
-   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
-   * @returns A promise that resolves to the loaded (and optionally processed) text.
+    /**
+   * Fetch a UTF-8 text resource via VFS.
+   *
+   * - Results are cached per resolved URL (via HttpRequest.urlResolver if provided; otherwise the raw URL).
+   * - If cached, any provided postProcess is ignored for subsequent calls; create a separate AssetManager
+   *   if you need different post-processing of the same URL.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the loaded text.
+   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
+   * @returns A promise that resolves to the loaded (and optionally processed) text.
    */ async fetchTextData(url, postProcess, httpRequest, VFSs) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._textDatas[hash];
@@ -179,16 +198,16 @@ import '../shaders/atmosphere.js';
         }
         return P;
     }
-    /**
-   * Fetch a JSON resource via VFS.
-   *
-   * - Parses as JSON after text load.
-   * - Cached per resolved URL. Post-process is applied only on the first load for a given cache key.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the parsed JSON object.
-   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
-   * @returns A promise that resolves to the loaded (and optionally processed) JSON value.
+    /**
+   * Fetch a JSON resource via VFS.
+   *
+   * - Parses as JSON after text load.
+   * - Cached per resolved URL. Post-process is applied only on the first load for a given cache key.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the parsed JSON object.
+   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
+   * @returns A promise that resolves to the loaded (and optionally processed) JSON value.
    */ async fetchJsonData(url, postProcess, httpRequest, VFSs) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._jsonDatas[hash];
@@ -198,15 +217,15 @@ import '../shaders/atmosphere.js';
         }
         return P;
     }
-    /**
-   * Fetch a binary resource via VFS.
-   *
-   * - Cached per resolved URL. Post-process is applied only on first load for a given key.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the loaded ArrayBuffer.
-   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
-   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
+    /**
+   * Fetch a binary resource via VFS.
+   *
+   * - Cached per resolved URL. Post-process is applied only on first load for a given key.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the loaded ArrayBuffer.
+   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
+   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
    */ async fetchBinaryData(url, postProcess, httpRequest, VFSs) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._binaryDatas[hash];
@@ -216,6 +235,39 @@ import '../shaders/atmosphere.js';
         }
         return P;
     }
+    /**
+   * Fetch a font asset via VFS.
+   *
+   * - Cached per URL only.
+   * - `options` are applied only when the font is first loaded for that URL.
+   * - If the URL is already cached, later calls ignore `options` and reuse the cached FontAsset.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param options - Optional MSDF atlas settings bound to the loaded FontAsset.
+   * @returns A promise that resolves to the loaded (and optionally processed) font asset.
+   */ async fetchFontAsset(url, options, VFSs) {
+        const hash = url;
+        let P = this._fontAssets[hash];
+        if (!P) {
+            P = new Promise((resolve, reject)=>{
+                this.loadBinaryData(url, null, VFSs).then((data)=>{
+                    resolve(data ? FontAsset.fromBuffer(data, options) : null);
+                }).catch((err)=>{
+                    reject(new Error(`Failed to load font asset from ${url}: ${err instanceof Error ? err.message : err}`));
+                });
+            });
+            this._fontAssets[hash] = P;
+        }
+        return P;
+    }
+    /**
+   * Fetch a font asset via VFS if already cached.
+   * @param url - Resource URL or VFS path.
+   * @returns The cached FontAsset if it exists and is loaded, or null if not cached or still loading.
+   */ getFontAsset(url) {
+        const hash = url;
+        return this._fontAssets[hash] instanceof Promise ? null : this._fontAssets[hash] ?? null;
+    }
     async fetchBluePrint(url, VFSs) {
         const hash = url;
         let P = this._bluePrints[hash];
@@ -225,12 +277,12 @@ import '../shaders/atmosphere.js';
         }
         return P;
     }
-    /**
-   * Fetch a material resource.
-   *
-   * @typeParam T - Expected concrete material type.
-   * @param url - Resource URL or VFS path.
-   * @returns A promise that resolves to the loaded material.
+    /**
+   * Fetch a material resource.
+   *
+   * @typeParam T - Expected concrete material type.
+   * @param url - Resource URL or VFS path.
+   * @returns A promise that resolves to the loaded material.
    */ async fetchMaterial(url, VFSs) {
         const hash = url;
         let P = this._materials[hash];
@@ -246,12 +298,12 @@ import '../shaders/atmosphere.js';
         }
         return material;
     }
-    /**
-   * Fetch a primitive resource.
-   *
-   * @typeParam T - Expected concrete primitive type.
-   * @param url - Resource URL or VFS path.
-   * @returns A promise that resolves to the loaded primitive.
+    /**
+   * Fetch a primitive resource.
+   *
+   * @typeParam T - Expected concrete primitive type.
+   * @param url - Resource URL or VFS path.
+   * @returns A promise that resolves to the loaded primitive.
    */ async fetchPrimitive(url, VFSs) {
         const hash = url;
         let P = this._primitives[hash];
@@ -267,19 +319,19 @@ import '../shaders/atmosphere.js';
         }
         return primitive;
     }
-    /**
-   * Fetch a texture resource via registered loaders.
-   *
-   * - Chooses loader by explicit MIME type or by VFS file extension inference.
-   * - Deduplicates in-flight requests and caches ready textures.
-   * - If `options.texture` is provided, the asset will be uploaded/blitted into that texture.
-   * - On WebGL backends, enforces constraints by repacking non-power-of-two or sRGB textures.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param url - Resource URL or VFS path.
-   * @param options - Texture fetching options (color space, sampler, target texture).
-   * @param httpRequest - Optional HttpRequest (not used for binary read but may supply URL resolver for hashing).
-   * @returns A promise that resolves to the loaded texture.
+    /**
+   * Fetch a texture resource via registered loaders.
+   *
+   * - Chooses loader by explicit MIME type or by VFS file extension inference.
+   * - Deduplicates in-flight requests and caches ready textures.
+   * - If `options.texture` is provided, the asset will be uploaded/blitted into that texture.
+   * - On WebGL backends, enforces constraints by repacking non-power-of-two or sRGB textures.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param url - Resource URL or VFS path.
+   * @param options - Texture fetching options (color space, sampler, target texture).
+   * @param httpRequest - Optional HttpRequest (not used for binary read but may supply URL resolver for hashing).
+   * @returns A promise that resolves to the loaded texture.
    */ async fetchTexture(url, options, VFSs) {
         if (options?.texture) {
             return this.loadTexture(url, options.mimeType ?? null, !options.linearColorSpace, options.samplerOptions, options.texture, VFSs);
@@ -299,16 +351,16 @@ import '../shaders/atmosphere.js';
             return tex;
         }
     }
-    /**
-   * Fetch a model resource via registered model loaders (data only).
-   *
-   * - Returns a SharedModel which can create scene nodes in any Scene.
-   * - Uses DWeakRef to cache and allow model data to be reclaimed if unused.
-   *
-   * @param url - Model URL or VFS path.
-   * @param options - Model loader options (MIME override, Draco, instancing hint, post-process).
-   * @returns A promise that resolves to the SharedModel.
-   * @internal
+    /**
+   * Fetch a model resource via registered model loaders (data only).
+   *
+   * - Returns a SharedModel which can create scene nodes in any Scene.
+   * - Uses DWeakRef to cache and allow model data to be reclaimed if unused.
+   *
+   * @param url - Model URL or VFS path.
+   * @param options - Model loader options (MIME override, Draco, instancing hint, post-process).
+   * @returns A promise that resolves to the SharedModel.
+   * @internal
    */ async fetchModelData(url, options, VFSs) {
         const hash = url;
         let P = this._models[hash];
@@ -324,17 +376,17 @@ import '../shaders/atmosphere.js';
         }
         return sharedModel;
     }
-    /**
-   * Fetch a model resource and instantiate it under a scene.
-   *
-   * - Loads or retrieves a cached SharedModel, then creates a SceneNode hierarchy.
-   * - Returns both the created group node and any associated AnimationSet.
-   *
-   * @param scene - Scene into which the model node will be created.
-   * @param url - Model URL or VFS path.
-   * @param options - Model loader options and instancing hint.
-   * @param httpRequest - Optional HttpRequest (unused for binary read; present for API symmetry).
-   * @returns A promise with the created node group and animation set info.
+    /**
+   * Fetch a model resource and instantiate it under a scene.
+   *
+   * - Loads or retrieves a cached SharedModel, then creates a SceneNode hierarchy.
+   * - Returns both the created group node and any associated AnimationSet.
+   *
+   * @param scene - Scene into which the model node will be created.
+   * @param url - Model URL or VFS path.
+   * @param options - Model loader options and instancing hint.
+   * @param httpRequest - Optional HttpRequest (unused for binary read; present for API symmetry).
+   * @returns A promise with the created node group and animation set info.
    */ async fetchModel(scene, url, options, VFSs) {
         const sharedModel = await this.fetchModelData(url, options, VFSs);
         const node = sharedModel.createSceneNode(scene, !!options?.enableInstancing);
@@ -343,15 +395,15 @@ import '../shaders/atmosphere.js';
             animationSet: node.animationSet
         };
     }
-    /**
-   * Load a text resource via VFS and optionally post-process it.
-   *
-   * - Does not use or modify the internal cache; use fetchTextData for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the text.
-   * @returns A promise that resolves to the loaded (and optionally processed) text.
-   * @internal
+    /**
+   * Load a text resource via VFS and optionally post-process it.
+   *
+   * - Does not use or modify the internal cache; use fetchTextData for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the text.
+   * @returns A promise that resolves to the loaded (and optionally processed) text.
+   * @internal
    */ async loadTextData(url, postProcess, VFSs) {
         let text = await this.readFileFromVFSs(url, {
             encoding: 'utf8'
@@ -365,15 +417,15 @@ import '../shaders/atmosphere.js';
         }
         return text;
     }
-    /**
-   * Load a JSON resource via VFS and optionally post-process it.
-   *
-   * - Does not use or modify the internal cache; use fetchJsonData for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the parsed JSON.
-   * @returns A promise that resolves to the loaded (and optionally processed) JSON.
-   * @internal
+    /**
+   * Load a JSON resource via VFS and optionally post-process it.
+   *
+   * - Does not use or modify the internal cache; use fetchJsonData for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the parsed JSON.
+   * @returns A promise that resolves to the loaded (and optionally processed) JSON.
+   * @internal
    */ async loadJsonData(url, postProcess, VFSs) {
         let json = JSON.parse(await this.readFileFromVFSs(url, {
             encoding: 'utf8'
@@ -387,15 +439,15 @@ import '../shaders/atmosphere.js';
         }
         return json;
     }
-    /**
-   * Load a binary resource via VFS and optionally post-process it.
-   *
-   * - Does not use or modify the internal cache; use fetchBinaryData for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the ArrayBuffer.
-   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
-   * @internal
+    /**
+   * Load a binary resource via VFS and optionally post-process it.
+   *
+   * - Does not use or modify the internal cache; use fetchBinaryData for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the ArrayBuffer.
+   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
+   * @internal
    */ async loadBinaryData(url, postProcess, VFSs) {
         try {
             let data = await this.readFileFromVFSs(url, {
@@ -528,14 +580,14 @@ import '../shaders/atmosphere.js';
             return null;
         }
     }
-    /**
-   * Load a material.
-   *
-   * - Does not use or modify the internal cache; use fetchMaterial for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @returns A promise that resolves to the loaded material.
-   * @internal
+    /**
+   * Load a material.
+   *
+   * - Does not use or modify the internal cache; use fetchMaterial for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @returns A promise that resolves to the loaded material.
+   * @internal
    */ async loadMaterial(url, reload, VFSs) {
         try {
             const data = await this.readFileFromVFSs(url, {
@@ -721,19 +773,19 @@ import '../shaders/atmosphere.js';
             return null;
         }
     }
-    /**
-   * Load a texture directly from an ArrayBuffer or typed array.
-   *
-   * - Chooses an appropriate loader based on the provided MIME type.
-   * - Can upload into an existing texture if `texture` is specified.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param arrayBuffer - Raw texture data buffer.
-   * @param mimeType - MIME type of the texture (must be supported by a registered loader).
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options passed to the loader path.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
+    /**
+   * Load a texture directly from an ArrayBuffer or typed array.
+   *
+   * - Chooses an appropriate loader based on the provided MIME type.
+   * - Can upload into an existing texture if `texture` is specified.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param arrayBuffer - Raw texture data buffer.
+   * @param mimeType - MIME type of the texture (must be supported by a registered loader).
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options passed to the loader path.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
    */ async loadTextureFromBuffer(arrayBuffer, mimeType, srgb, samplerOptions, texture) {
         for (const loader of AssetManager._textureLoaders){
             if (!loader.supportMIMEType(mimeType)) {
@@ -744,20 +796,20 @@ import '../shaders/atmosphere.js';
         }
         throw new Error(`Can not find loader for MIME type '${mimeType}'`);
     }
-    /**
-   * Load a texture via VFS by URL and MIME type.
-   *
-   * - Uses the first loader that supports the inferred or provided MIME type.
-   * - On WebGL, may repack textures (resample to power-of-two, convert formats) to meet backend constraints.
-   * - If `texture` is provided, the source is blitted into it, possibly resizing or changing sampling accordingly.
-   *
-   * @param url - Texture URL or VFS path.
-   * @param mimeType - Optional explicit MIME type; otherwise inferred by VFS.
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options for loader or blit path.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
-   * @internal
+    /**
+   * Load a texture via VFS by URL and MIME type.
+   *
+   * - Uses the first loader that supports the inferred or provided MIME type.
+   * - On WebGL, may repack textures (resample to power-of-two, convert formats) to meet backend constraints.
+   * - If `texture` is provided, the source is blitted into it, possibly resizing or changing sampling accordingly.
+   *
+   * @param url - Texture URL or VFS path.
+   * @param mimeType - Optional explicit MIME type; otherwise inferred by VFS.
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options for loader or blit path.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
+   * @internal
    */ async loadTexture(url, mimeType, srgb, samplerOptions, texture, VFSs) {
         const data = await this.readFileFromVFSs(url, {
             encoding: 'binary'
@@ -775,18 +827,18 @@ import '../shaders/atmosphere.js';
         }
         throw new Error(`Can not find loader for asset ${url}`);
     }
-    /**
-   * Internal routine that executes the texture load using a specific loader and applies
-   * backend-specific compatibility steps (e.g., WebGL NPOT/sRGB rules).
-   *
-   * @param loader - Concrete loader to use for decoding/creation.
-   * @param mimeType - Texture MIME type.
-   * @param data - Raw binary data.
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
-   * @internal
+    /**
+   * Internal routine that executes the texture load using a specific loader and applies
+   * backend-specific compatibility steps (e.g., WebGL NPOT/sRGB rules).
+   *
+   * @param loader - Concrete loader to use for decoding/creation.
+   * @param mimeType - Texture MIME type.
+   * @param data - Raw binary data.
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
+   * @internal
    */ async doLoadTexture(loader, mimeType, data, srgb, samplerOptions, texture) {
         const device = getDevice();
         if (device.type !== 'webgl') {
@@ -837,17 +889,17 @@ import '../shaders/atmosphere.js';
             return tex;
         }
     }
-    /**
-   * Load a model via registered model loaders.
-   *
-   * - Selects loader by MIME type (explicit or inferred).
-   * - Optionally applies a post-process transform to the SharedModel.
-   * - Sets the model's name from the source filename for convenience.
-   *
-   * @param url - Model URL or VFS path.
-   * @param options - Model load options (MIME override, Draco module, post-process hook).
-   * @returns A promise that resolves to the loaded SharedModel.
-   * @internal
+    /**
+   * Load a model via registered model loaders.
+   *
+   * - Selects loader by MIME type (explicit or inferred).
+   * - Optionally applies a post-process transform to the SharedModel.
+   * - Sets the model's name from the source filename for convenience.
+   *
+   * @param url - Model URL or VFS path.
+   * @param options - Model load options (MIME override, Draco module, post-process hook).
+   * @returns A promise that resolves to the loaded SharedModel.
+   * @internal
    */ async loadModel(url, options, VFSs) {
         const arrayBuffer = await this.readFileFromVFSs(url, {
             encoding: 'binary'
@@ -879,17 +931,17 @@ import '../shaders/atmosphere.js';
         }
         throw new Error(`Can not find loader for asset ${url}`);
     }
-    /**
-   * Fetch a built-in texture synchronously by name.
-   *
-   * - If this built-in was not created yet, the registered loader is invoked.
-   * - Registers a device restore handler so the texture can be re-initialized after device loss.
-   * - If an existing texture is provided, the loader uploads into it.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param name - Built-in texture identifier.
-   * @param texture - Optional destination texture to populate.
-   * @returns The built-in texture (created or populated).
+    /**
+   * Fetch a built-in texture synchronously by name.
+   *
+   * - If this built-in was not created yet, the registered loader is invoked.
+   * - Registers a device restore handler so the texture can be re-initialized after device loss.
+   * - If an existing texture is provided, the loader uploads into it.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param name - Built-in texture identifier.
+   * @param texture - Optional destination texture to populate.
+   * @returns The built-in texture (created or populated).
    */ fetchBuiltinTexture(name, texture) {
         const loader = AssetManager._builtinTextureLoaders[name];
         if (!loader) {
@@ -909,14 +961,14 @@ import '../shaders/atmosphere.js';
             return texture;
         }
     }
-    /**
-   * Override or unregister the loader for a named built-in texture.
-   *
-   * - Passing a valid loader function sets/overrides the creation path.
-   * - Passing `undefined` removes the loader mapping for the given name.
-   *
-   * @param name - Built-in texture identifier.
-   * @param loader - Factory that creates the built-in texture using the provided AssetManager.
+    /**
+   * Override or unregister the loader for a named built-in texture.
+   *
+   * - Passing a valid loader function sets/overrides the creation path.
+   * - Passing `undefined` removes the loader mapping for the given name.
+   *
+   * @param name - Built-in texture identifier.
+   * @param loader - Factory that creates the built-in texture using the provided AssetManager.
    */ static setBuiltinTextureLoader(name, loader) {
         if (loader) {
             this._builtinTextureLoaders[name] = loader;
@@ -924,29 +976,29 @@ import '../shaders/atmosphere.js';
             delete this._builtinTextureLoaders[name];
         }
     }
-    /**
-   * Compute a cache key for texture requests.
-   *
-   * Includes texture type tag, URL, and color space choice to avoid cross-color-space cache collisions.
-   *
-   * @typeParam T - Texture type parameter (not used for runtime behavior; helps preserve generic intent).
-   * @param type - Logical texture type tag (e.g., '2d', 'cube').
-   * @param url - Resource URL or VFS path.
-   * @param options - Texture fetch options to incorporate into the key.
-   * @returns A string cache key combining type, URL, and color space choice.
-   * @internal
+    /**
+   * Compute a cache key for texture requests.
+   *
+   * Includes texture type tag, URL, and color space choice to avoid cross-color-space cache collisions.
+   *
+   * @typeParam T - Texture type parameter (not used for runtime behavior; helps preserve generic intent).
+   * @param type - Logical texture type tag (e.g., '2d', 'cube').
+   * @param url - Resource URL or VFS path.
+   * @param options - Texture fetch options to incorporate into the key.
+   * @returns A string cache key combining type, URL, and color space choice.
+   * @internal
    */ getHash(type, url, options) {
         return `${type}:${url}:${!options?.linearColorSpace}`;
     }
-    /**
-   * Try reading from file from a list of VFSs
-   *
-   * @param path - File path
-   * @param options - Read options
-   * @param vfsList - VFS list
-   * @returns File content
-   *
-   * @internal
+    /**
+   * Try reading from file from a list of VFSs
+   *
+   * @param path - File path
+   * @param options - Read options
+   * @param vfsList - VFS list
+   * @returns File content
+   *
+   * @internal
    */ async readFileFromVFSs(path, options, vfsList) {
         vfsList = vfsList ?? [
             this.vfs
@@ -958,13 +1010,13 @@ import '../shaders/atmosphere.js';
         }
         throw new VFSError(`File does not exist: ${path}`, 'ENOENT', path);
     }
-    /**
-   * Write file to a list of VFSs
-   *
-   * @param path - File path
-   * @param data - Data to write
-   * @param options - Write options
-   * @param vfsList - Which VFSs will be written to
+    /**
+   * Write file to a list of VFSs
+   *
+   * @param path - File path
+   * @param data - Data to write
+   * @param options - Write options
+   * @param vfsList - Which VFSs will be written to
    */ async writeFileToVFSs(path, data, options, vfsList) {
         vfsList = vfsList ?? [
             this.vfs