@needle-tools/gltf-progressive 3.4.0-rc → 3.5.0-canary.4d42385

package/lib/extension.d.ts

@@ -42,8 +42,31 @@ type TextureLODsMinMaxInfo = {
 export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     /** The name of the extension */
     get name(): string;
+    /**
+     * Get the progressive mesh LOD extension data associated with a geometry.
+     * Returns the extension metadata (available LOD levels, vertex/index counts, densities) if the geometry was registered with progressive LODs, or `null` otherwise.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The mesh LOD extension data, or `null` if no progressive LODs are registered for this geometry.
+     */
     static getMeshLODExtension(geo: BufferGeometry): NEEDLE_ext_progressive_mesh | null;
+    /**
+     * Get the glTF primitive index for a geometry within its parent mesh.
+     * A single glTF mesh node can contain multiple primitives (sub-geometries). This returns which primitive the geometry corresponds to.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The zero-based primitive index, or `-1` if no LOD information is assigned to this geometry.
+     */
     static getPrimitiveIndex(geo: BufferGeometry): number;
+    /**
+     * Compute the minimum and maximum number of texture LOD levels across all textures of a material (or array of materials).
+     * Iterates over all texture slots on the material and collects LOD count ranges and per-level resolution bounds.
+     * Results are cached on the material so subsequent calls are free.
+     *
+     * @param material - A single material or an array of materials to inspect.
+     * @param minmax - Optional accumulator to merge results into (used internally for recursive calls with material arrays).
+     * @returns An object with `min_count` / `max_count` (the range of LOD levels across all textures) and a per-level `lods` array with `min_height` / `max_height`.
+     */
     static getMaterialMinMaxLODsCount(material: Material | Material[], minmax?: TextureLODsMinMaxInfo): TextureLODsMinMaxInfo;
     /** Check if a LOD level is available for a mesh or a texture
      * @param obj the mesh or texture to check
@@ -76,6 +99,12 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     static assignTextureLOD(materialOrTexture: Material, level: number): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
     static assignTextureLOD(materialOrTexture: Mesh, level: number): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
     static assignTextureLOD(materialOrTexture: Texture, level: number): Promise<Texture | null>;
+    /**
+     * Set the maximum number of concurrent loading tasks for LOD resources. This limits how many LOD resources (meshes or textures) can be loaded at the same time to prevent overloading the network or GPU. If the limit is reached, additional loading requests will be queued and processed as previous ones finish.
+     * @default 50 on desktop, 20 on mobile devices
+     */
+    static set maxConcurrentLoadingTasks(value: number);
+    static get maxConcurrentLoadingTasks(): number;
     private static assignTextureLODForSlot;
     private readonly parser;
     private readonly url;
@@ -84,17 +113,36 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     loadMesh: (meshIndex: number) => Promise<any> | null;
     afterRoot(gltf: GLTF): null;
     /**
-     * Register a texture with LOD information
+     * Register a texture with progressive LOD information. This associates the texture with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower resolution versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     *
+     * @param url - The source URL of the glTF file this texture was loaded from.
+     * @param tex - The three.js Texture instance to register.
+     * @param level - The LOD level this texture represents (0 = highest resolution).
+     * @param index - The texture index within the glTF file.
+     * @param ext - The parsed progressive texture extension data containing all available LOD levels and their dimensions.
      */
     static registerTexture: (url: string, tex: Texture, level: number, index: number, ext: NEEDLE_ext_progressive_texture) => void;
     /**
-     * Register a mesh with LOD information
+     * Register a mesh with progressive LOD information. This associates the mesh geometry with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower density versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     * If the mesh is registered at a level > 0 (i.e. not full resolution), a raycast mesh is automatically preserved for accurate picking.
+     *
+     * @param url - The source URL of the glTF file this mesh was loaded from.
+     * @param key - A unique key identifying this mesh's LOD group (typically derived from the extension GUID).
+     * @param mesh - The three.js Mesh instance to register.
+     * @param level - The LOD level this mesh represents (0 = highest resolution / full density).
+     * @param index - The primitive index within the glTF mesh node.
+     * @param ext - The parsed progressive mesh extension data containing all available LOD levels with vertex/index counts and densities.
      */
     static registerMesh: (url: string, key: string, mesh: Mesh, level: number, index: number, ext: NEEDLE_ext_progressive_mesh) => void;
     /**
      * Dispose cached resources to free memory.
      * Call this when a model is removed from the scene to allow garbage collection of its LOD resources.
      * Calls three.js `.dispose()` on cached Textures and BufferGeometries to free GPU memory.
+     * Also clears reference counts for disposed textures.
      * @param guid Optional GUID to dispose resources for a specific model. If omitted, all cached resources are cleared.
      */
     static dispose(guid?: string): void;
@@ -103,20 +151,32 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     /** A map of key = asset uuid and value = LOD information */
     private static readonly lodInfos;
     /** cache of already loaded mesh lods. Uses WeakRef for single resources to allow garbage collection when unused. */
-    private static readonly previouslyLoaded;
+    private static readonly cache;
     /** this contains the geometry/textures that were originally loaded. Uses WeakRef to allow garbage collection when unused. */
     private static readonly lowresCache;
+    /** Reference counting for textures to track usage across multiple materials/objects */
+    private static readonly textureRefCounts;
     /**
      * FinalizationRegistry to automatically clean up `previouslyLoaded` cache entries
      * when their associated three.js resources are garbage collected by the browser.
      * The held value is the cache key string used in `previouslyLoaded`.
      */
     private static readonly _resourceRegistry;
+    /**
+     * Track texture usage by incrementing reference count
+     */
+    private static trackTextureUsage;
+    /**
+     * Untrack texture usage by decrementing reference count.
+     * Automatically disposes the texture when reference count reaches zero.
+     * @returns true if the texture was disposed, false otherwise
+     */
+    private static untrackTextureUsage;
     private static readonly workers;
     private static _workersIndex;
     private static getOrLoadLOD;
-    private static maxConcurrent;
-    private static queue;
+    private static _queue;
+    private static get queue();
     private static assignLODInformation;
     private static getAssignedLODInformation;
     private static copySettings;

package/lib/extension.js

@@ -1,7 +1,7 @@
 import { BufferGeometry, Mesh, Texture, TextureLoader } from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { addDracoAndKTX2Loaders } from "./loaders.js";
-import { getParam, PromiseQueue, resolveUrl } from "./utils.internal.js";
+import { determineTextureMemoryInBytes, getParam, isMobileDevice, PromiseQueue, resolveUrl } from "./utils.internal.js";
 import { getRaycastMesh, registerRaycastMesh } from "./utils.js";
 // All of this has to be removed
 // import { getRaycastMesh, setRaycastMesh } from "../../engine_physics.js";
@@ -11,6 +11,7 @@ import { debug } from "./lods.debug.js";
 import { getWorker } from "./worker/loader.mainthread.js";
 const useWorker = getParam("gltf-progressive-worker");
 const reduceMipmaps = getParam("gltf-progressive-reduce-mipmaps");
+const debugGC = getParam("gltf-progressive-gc");
 const $progressiveTextureExtension = Symbol("needle-progressive-texture");
 export const EXTENSION_NAME = "NEEDLE_progressive";
 // #region EXT
@@ -35,6 +36,13 @@ export class NEEDLE_progressive {
         return EXTENSION_NAME;
     }
     // #region PUBLIC API
+    /**
+     * Get the progressive mesh LOD extension data associated with a geometry.
+     * Returns the extension metadata (available LOD levels, vertex/index counts, densities) if the geometry was registered with progressive LODs, or `null` otherwise.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The mesh LOD extension data, or `null` if no progressive LODs are registered for this geometry.
+     */
     static getMeshLODExtension(geo) {
         const info = this.getAssignedLODInformation(geo);
         if (info?.key) {
@@ -42,12 +50,28 @@ export class NEEDLE_progressive {
         }
         return null;
     }
+    /**
+     * Get the glTF primitive index for a geometry within its parent mesh.
+     * A single glTF mesh node can contain multiple primitives (sub-geometries). This returns which primitive the geometry corresponds to.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The zero-based primitive index, or `-1` if no LOD information is assigned to this geometry.
+     */
     static getPrimitiveIndex(geo) {
         const index = this.getAssignedLODInformation(geo)?.index;
         if (index === undefined || index === null)
             return -1;
         return index;
     }
+    /**
+     * Compute the minimum and maximum number of texture LOD levels across all textures of a material (or array of materials).
+     * Iterates over all texture slots on the material and collects LOD count ranges and per-level resolution bounds.
+     * Results are cached on the material so subsequent calls are free.
+     *
+     * @param material - A single material or an array of materials to inspect.
+     * @param minmax - Optional accumulator to merge results into (used internally for recursive calls with material arrays).
+     * @returns An object with `min_count` / `max_count` (the range of LOD levels across all textures) and a per-level `lods` array with `min_height` / `max_height`.
+     */
     static getMaterialMinMaxLODsCount(material, minmax) {
         const self = this;
         // we can cache this material min max data because it wont change at runtime
@@ -309,6 +333,16 @@ export class NEEDLE_progressive {
         }
         return Promise.resolve(null);
     }
+    /**
+     * Set the maximum number of concurrent loading tasks for LOD resources. This limits how many LOD resources (meshes or textures) can be loaded at the same time to prevent overloading the network or GPU. If the limit is reached, additional loading requests will be queued and processed as previous ones finish.
+     * @default 50 on desktop, 20 on mobile devices
+     */
+    static set maxConcurrentLoadingTasks(value) {
+        NEEDLE_progressive.queue.maxConcurrent = value;
+    }
+    static get maxConcurrentLoadingTasks() {
+        return NEEDLE_progressive.queue.maxConcurrent;
+    }
     // #region INTERNAL
     static assignTextureLODForSlot(current, level, material, slot) {
         if (current?.isTexture !== true) {
@@ -334,29 +368,37 @@ export class NEEDLE_progressive {
                             if (assignedLOD && assignedLOD?.level < level) {
                                 if (debug === "verbose")
                                     console.warn("Assigned texture level is already higher: ", assignedLOD.level, level, material, assigned, tex);
+                                // Dispose the newly loaded texture since we're not using it
+                                // (the assigned texture is higher quality, so we reject the new one)
+                                // Note: We dispose directly here (not via untrackTextureUsage) because this texture
+                                // was never tracked/used - it was rejected immediately upon loading
+                                if (tex && tex !== assigned) {
+                                    if (debug || debugGC) {
+                                        console.log(`[gltf-progressive] Disposing rejected lower-quality texture LOD ${level} (assigned is ${assignedLOD.level})`, tex.uuid);
+                                    }
+                                    tex.dispose();
+                                }
                                 return null;
                             }
                             // assigned.dispose();
                         }
-                        // Since we're switching LOD level for the texture based on distance we can avoid uploading all the mipmaps
-                        if (reduceMipmaps && tex.mipmaps) {
-                            const prevCount = tex.mipmaps.length;
-                            tex.mipmaps.length = Math.min(tex.mipmaps.length, 3);
-                            if (prevCount !== tex.mipmaps.length) {
-                                if (debug)
-                                    console.debug(`Reduced mipmap count from ${prevCount} to ${tex.mipmaps.length} for ${tex.uuid}: ${tex.image?.width}x${tex.image?.height}.`);
+                        // Track reference count for new texture
+                        this.trackTextureUsage(tex);
+                        // Untrack the old texture (may dispose if ref count hits 0)
+                        // This prevents accumulation of GPU VRAM while waiting for garbage collection
+                        if (assigned && assigned !== tex) {
+                            const wasDisposed = this.untrackTextureUsage(assigned);
+                            if (wasDisposed && (debug || debugGC)) {
+                                const assignedLOD = this.getAssignedLODInformation(assigned);
+                                console.log(`[gltf-progressive] Disposed old texture LOD ${assignedLOD?.level ?? '?'} → ${level} for ${material.name || material.type}.${slot}`, assigned.uuid);
                             }
                         }
                         material[slot] = tex;
                     }
-                    // check if the old texture is still used by other objects
-                    // if not we dispose it...
-                    // this could also be handled elsewhere and not be done immediately
-                    // const users = getResourceUserCount(current);
-                    // if (!users) {
-                    //     if (debug) console.log("Progressive: Dispose texture", current.name, current.source.data, current.uuid);
-                    //     current?.dispose();
-                    // }
+                    // Note: We use reference counting above to track texture usage across multiple materials.
+                    // When the reference count hits zero, GPU memory (VRAM) is freed immediately via gl.deleteTexture(),
+                    // not waiting for JavaScript garbage collection which may take seconds/minutes.
+                    // This handles cases where the same texture is shared across multiple materials/objects.
                 }
                 // this.onProgressiveLoadEnd(info);
                 return tex;
@@ -473,7 +515,15 @@ export class NEEDLE_progressive {
         return null;
     }
     /**
-     * Register a texture with LOD information
+     * Register a texture with progressive LOD information. This associates the texture with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower resolution versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     *
+     * @param url - The source URL of the glTF file this texture was loaded from.
+     * @param tex - The three.js Texture instance to register.
+     * @param level - The LOD level this texture represents (0 = highest resolution).
+     * @param index - The texture index within the glTF file.
+     * @param ext - The parsed progressive texture extension data containing all available LOD levels and their dimensions.
      */
     static registerTexture = (url, tex, level, index, ext) => {
         if (!tex) {
@@ -496,7 +546,17 @@ export class NEEDLE_progressive {
         NEEDLE_progressive.lowresCache.set(key, new WeakRef(tex));
     };
     /**
-     * Register a mesh with LOD information
+     * Register a mesh with progressive LOD information. This associates the mesh geometry with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower density versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     * If the mesh is registered at a level > 0 (i.e. not full resolution), a raycast mesh is automatically preserved for accurate picking.
+     *
+     * @param url - The source URL of the glTF file this mesh was loaded from.
+     * @param key - A unique key identifying this mesh's LOD group (typically derived from the extension GUID).
+     * @param mesh - The three.js Mesh instance to register.
+     * @param level - The LOD level this mesh represents (0 = highest resolution / full density).
+     * @param index - The primitive index within the glTF mesh node.
+     * @param ext - The parsed progressive mesh extension data containing all available LOD levels with vertex/index counts and densities.
      */
     static registerMesh = (url, key, mesh, level, index, ext) => {
         const geometry = mesh.geometry;
@@ -531,6 +591,7 @@ export class NEEDLE_progressive {
      * Dispose cached resources to free memory.
      * Call this when a model is removed from the scene to allow garbage collection of its LOD resources.
      * Calls three.js `.dispose()` on cached Textures and BufferGeometries to free GPU memory.
+     * Also clears reference counts for disposed textures.
      * @param guid Optional GUID to dispose resources for a specific model. If omitted, all cached resources are cleared.
      */
     static dispose(guid) {
@@ -542,7 +603,9 @@ export class NEEDLE_progressive {
                 const lowres = lowresRef.deref();
                 if (lowres) {
                     if (lowres.isTexture) {
-                        lowres.dispose();
+                        const tex = lowres;
+                        this.textureRefCounts.delete(tex.uuid); // Clear ref count
+                        tex.dispose();
                     }
                     else if (Array.isArray(lowres)) {
                         for (const geo of lowres)
@@ -552,10 +615,10 @@ export class NEEDLE_progressive {
                 this.lowresCache.delete(guid);
             }
             // Dispose previously loaded LOD entries
-            for (const [key, entry] of this.previouslyLoaded) {
+            for (const [key, entry] of this.cache) {
                 if (key.includes(guid)) {
                     this._disposeCacheEntry(entry);
-                    this.previouslyLoaded.delete(key);
+                    this.cache.delete(key);
                 }
             }
         }
@@ -565,7 +628,9 @@ export class NEEDLE_progressive {
                 const entry = entryRef.deref();
                 if (entry) {
                     if (entry.isTexture) {
-                        entry.dispose();
+                        const tex = entry;
+                        this.textureRefCounts.delete(tex.uuid); // Clear ref count
+                        tex.dispose();
                     }
                     else if (Array.isArray(entry)) {
                         for (const geo of entry)
@@ -574,10 +639,12 @@ export class NEEDLE_progressive {
                 }
             }
             this.lowresCache.clear();
-            for (const [, entry] of this.previouslyLoaded) {
+            for (const [, entry] of this.cache) {
                 this._disposeCacheEntry(entry);
             }
-            this.previouslyLoaded.clear();
+            this.cache.clear();
+            // Clear all texture reference counts when disposing everything
+            this.textureRefCounts.clear();
         }
     }
     /** Dispose a single cache entry's three.js resource(s) to free GPU memory. */
@@ -585,7 +652,13 @@ export class NEEDLE_progressive {
         if (entry instanceof WeakRef) {
             // Single resource — deref and dispose if still alive
             const resource = entry.deref();
-            resource?.dispose();
+            if (resource) {
+                // Clear ref count for textures
+                if (resource.isTexture) {
+                    this.textureRefCounts.delete(resource.uuid);
+                }
+                resource.dispose();
+            }
         }
         else {
             // Promise — may be in-flight or already resolved.
@@ -597,6 +670,10 @@ export class NEEDLE_progressive {
                             geo.dispose();
                     }
                     else {
+                        // Clear ref count for textures
+                        if (resource.isTexture) {
+                            this.textureRefCounts.delete(resource.uuid);
+                        }
                         resource.dispose();
                     }
                 }
@@ -606,27 +683,84 @@ export class NEEDLE_progressive {
     /** A map of key = asset uuid and value = LOD information */
     static lodInfos = new Map();
     /** cache of already loaded mesh lods. Uses WeakRef for single resources to allow garbage collection when unused. */
-    static previouslyLoaded = new Map();
+    static cache = new Map();
     /** this contains the geometry/textures that were originally loaded. Uses WeakRef to allow garbage collection when unused. */
     static lowresCache = new Map();
+    /** Reference counting for textures to track usage across multiple materials/objects */
+    static textureRefCounts = new Map();
     /**
      * FinalizationRegistry to automatically clean up `previouslyLoaded` cache entries
      * when their associated three.js resources are garbage collected by the browser.
      * The held value is the cache key string used in `previouslyLoaded`.
      */
     static _resourceRegistry = new FinalizationRegistry((cacheKey) => {
-        const entry = NEEDLE_progressive.previouslyLoaded.get(cacheKey);
-        console.debug(`[gltf-progressive] FinalizationRegistry cleanup: Resource GC'd for ${cacheKey}.`);
+        const entry = NEEDLE_progressive.cache.get(cacheKey);
+        if (debug || debugGC)
+            console.debug(`[gltf-progressive] Memory: Resource GC'd\n${cacheKey}`);
         // Only delete if the entry is still a WeakRef and the resource is gone
         if (entry instanceof WeakRef) {
             const derefed = entry.deref();
             if (!derefed) {
-                NEEDLE_progressive.previouslyLoaded.delete(cacheKey);
-                if (debug)
-                    console.log(`[gltf-progressive] Cache entry auto-cleaned (GC'd): ${cacheKey}`);
+                NEEDLE_progressive.cache.delete(cacheKey);
+                if (debug || debugGC)
+                    console.log(`[gltf-progressive] ↪ Cache entry deleted (GC)`);
             }
         }
     });
+    /**
+     * Track texture usage by incrementing reference count
+     */
+    static trackTextureUsage(texture) {
+        const uuid = texture.uuid;
+        const count = this.textureRefCounts.get(uuid) || 0;
+        this.textureRefCounts.set(uuid, count + 1);
+        if (debug === "verbose") {
+            console.log(`[gltf-progressive] Track texture ${uuid}, refCount: ${count} → ${count + 1}`);
+        }
+    }
+    /**
+     * Untrack texture usage by decrementing reference count.
+     * Automatically disposes the texture when reference count reaches zero.
+     * @returns true if the texture was disposed, false otherwise
+     */
+    static untrackTextureUsage(texture) {
+        const uuid = texture.uuid;
+        const count = this.textureRefCounts.get(uuid);
+        if (!count) {
+            // Texture wasn't tracked, dispose immediately (safe fallback)
+            if (debug === "verbose" || debugGC) {
+                logDebugInfo(`[gltf-progressive] Memory: Untrack untracked texture (dispose immediately)`, 0);
+            }
+            texture.dispose();
+            return true;
+        }
+        const newCount = count - 1;
+        if (newCount <= 0) {
+            this.textureRefCounts.delete(uuid);
+            if (debug || debugGC) {
+                logDebugInfo(`[gltf-progressive] Memory: Dispose texture`, newCount);
+            }
+            texture.dispose();
+            return true;
+        }
+        else {
+            this.textureRefCounts.set(uuid, newCount);
+            if (debug === "verbose") {
+                logDebugInfo(`[gltf-progressive] Memory: Untrack texture`, newCount);
+            }
+            return false;
+        }
+        function logDebugInfo(prefix, newCount) {
+            let width = texture.image?.width || texture.source?.data?.width || 0;
+            let height = texture.image?.height || texture.source?.data?.height || 0;
+            const textureSize = width && height ? `${width}x${height}` : "N/A";
+            let memorySize = "N/A";
+            if (width && height) {
+                memorySize = `~${(determineTextureMemoryInBytes(texture) / (1024 * 1024)).toFixed(2)} MB`;
+            }
+            console.log(`${prefix} — ${texture.name} ${textureSize} (${memorySize}), refCount: ${count} → ${newCount}\n${uuid}`);
+        }
+    }
     static workers = [];
     static _workersIndex = 0;
     static async getOrLoadLOD(current, level) {
@@ -700,7 +834,7 @@ export class NEEDLE_progressive {
                 const KEY = lod_url + "_" + lodInfo.guid;
                 const slot = await this.queue.slot(lod_url);
                 // check if the requested file is currently being loaded or was previously loaded
-                const existing = this.previouslyLoaded.get(KEY);
+                const existing = this.cache.get(KEY);
                 if (existing !== undefined) {
                     if (debugverbose)
                         console.log(`LOD ${level} was already loading/loaded: ${KEY}`);
@@ -728,7 +862,7 @@ export class NEEDLE_progressive {
                             }
                         }
                         // Resource was garbage collected or disposed — remove stale entry and re-load
-                        this.previouslyLoaded.delete(KEY);
+                        this.cache.delete(KEY);
                         if (debug)
                             console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${KEY}`);
                     }
@@ -751,7 +885,7 @@ export class NEEDLE_progressive {
                             // if it has been disposed we need to load it again
                             else {
                                 resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
+                                this.cache.delete(KEY);
                             }
                         }
                         else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
@@ -760,7 +894,7 @@ export class NEEDLE_progressive {
                             }
                             else {
                                 resouceIsDisposed = true;
-                                this.previouslyLoaded.delete(KEY);
+                                this.cache.delete(KEY);
                             }
                         }
                         if (!resouceIsDisposed) {
@@ -912,30 +1046,32 @@ export class NEEDLE_progressive {
                     // we could not find a texture or mesh with the given guid
                     return resolve(null);
                 });
-                this.previouslyLoaded.set(KEY, request);
+                this.cache.set(KEY, request);
                 slot.use(request);
                 const res = await request;
                 // Optimize cache entry: replace loading promise with lightweight reference.
                 // This releases closure variables captured during the loading function.
                 if (res != null) {
-                    if (Array.isArray(res)) {
+                    if (res instanceof Texture) {
+                        // For Texture resources, use WeakRef to allow garbage collection.
+                        // The FinalizationRegistry will auto-clean this entry when the resource is GC'd.
+                        this.cache.set(KEY, new WeakRef(res));
+                        NEEDLE_progressive._resourceRegistry.register(res, KEY);
+                    }
+                    else if (Array.isArray(res)) {
                         // For BufferGeometry[] (multi-primitive meshes), use a resolved promise.
-                        // WeakRef can't be used here because callers only extract individual elements
-                        // from the array, so the array object itself would be GC'd immediately.
-                        this.previouslyLoaded.set(KEY, Promise.resolve(res));
+                        // This keeps geometries in memory as they should not be GC'd (mesh LODs stay cached).
+                        this.cache.set(KEY, Promise.resolve(res));
                     }
                     else {
-                        // For single resources (Texture or BufferGeometry), use WeakRef to allow
-                        // garbage collection when the resource is no longer referenced by the scene.
-                        // The FinalizationRegistry will auto-clean this entry when the resource is GC'd.
-                        this.previouslyLoaded.set(KEY, new WeakRef(res));
-                        NEEDLE_progressive._resourceRegistry.register(res, KEY);
+                        // For single BufferGeometry, keep in memory (don't use WeakRef)
+                        this.cache.set(KEY, Promise.resolve(res));
                     }
                 }
                 else {
                     // Failed load — replace with clean resolved promise to release loading closure.
                     // Keeping the entry prevents retrying (existing behavior).
-                    this.previouslyLoaded.set(KEY, Promise.resolve(null));
+                    this.cache.set(KEY, Promise.resolve(null));
                 }
                 return res;
             }
@@ -961,8 +1097,8 @@ export class NEEDLE_progressive {
         }
         return null;
     }
-    static maxConcurrent = 50;
-    static queue = new PromiseQueue(NEEDLE_progressive.maxConcurrent, { debug: debug != false });
+    static _queue;
+    static get queue() { return this._queue ??= new PromiseQueue(isMobileDevice() ? 20 : 50, { debug: debug != false }); }
     static assignLODInformation(url, res, key, level, index) {
         if (!res)
             return;

package/lib/lods.manager.d.ts

@@ -98,7 +98,31 @@ export declare class LODsManager {
     private readonly _newPromiseGroups;
     private _promiseGroupIds;
     /**
-     * Call to await LODs loading during the next render cycle.
+     * Returns a promise that resolves once all LOD requests initiated during the next render cycles have finished loading.
+     * This is useful for hiding low-resolution placeholders (e.g. with a loading overlay or CSS blur) until high-quality assets are ready.
+     *
+     * By default, the returned promise captures LOD loading requests for 2 frames and resolves when all of them complete.
+     * Use `waitForFirstCapture` if no LOD requests may happen immediately (e.g. after a scene switch).
+     *
+     * @param opts - Optional configuration for how long to capture and what to wait for. See {@link PromiseGroupOptions}.
+     * @returns A promise that resolves with `{ cancelled, awaited_count, resolved_count }` once all captured LOD loads complete (or the signal aborts).
+     *
+     * @example
+     * ```ts
+     * // Wait for initial LODs to finish loading, then remove a blur overlay
+     * const result = await lodsManager.awaitLoading({
+     *     frames: 5,
+     *     signal: AbortSignal.timeout(10_000),
+     * });
+     * console.log(`Loaded ${result.resolved_count} of ${result.awaited_count} LODs`);
+     * document.querySelector('.blur-overlay')?.remove();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Wait until at least one LOD starts loading before resolving
+     * await lodsManager.awaitLoading({ waitForFirstCapture: true });
+     * ```
      */
     awaitLoading(opts?: PromiseGroupOptions): Promise<{
         cancelled: boolean;
@@ -107,8 +131,29 @@ export declare class LODsManager {
     }>;
     private _postprocessPromiseGroups;
     private readonly _lodchangedlisteners;
-    addEventListener(evt: "changed", listener: LODChangedEventListener): void;
-    removeEventListener(evt: "changed", listener: LODChangedEventListener): void;
+    /**
+     * Register a listener that is called whenever a mesh or texture LOD level has finished loading and has been applied.
+     * The listener receives the type of asset (`"mesh"` or `"texture"`), the new LOD level, and the affected object.
+     *
+     * @param evt - The event type. Currently only `"changed"` is supported.
+     * @param listener - Callback invoked after a LOD swap completes.
+     * @return A function to unregister the listener.
+     *
+     * @example
+     * ```ts
+     * lodsManager.addEventListener("changed", ({ type, level, object }) => {
+     *     console.log(`${type} LOD changed to level ${level}`, object);
+     * });
+     * ```
+     */
+    addEventListener(evt: "changed", listener: LODChangedEventListener): () => void;
+    /**
+     * Remove a previously registered `"changed"` event listener.
+     * @param evt - The event type (`"changed"`).
+     * @param listener - The listener to remove.
+     * @return `true` if the listener was found and removed, `false` otherwise.
+     */
+    removeEventListener(evt: "changed", listener: LODChangedEventListener): boolean;
     private constructor();
     private _fpsBuffer;
     /**
@@ -116,6 +161,21 @@ export declare class LODsManager {
      */
     enable(): void;
     disable(): void;
+    /**
+     * Manually trigger a LOD update for a scene and camera.
+     * Only needed when {@link manual} is set to `true` — otherwise LOD updates happen automatically on each render call.
+     *
+     * @param scene - The scene containing objects with progressive LODs.
+     * @param camera - The camera used to determine screen coverage and LOD levels.
+     *
+     * @example
+     * ```ts
+     * const lodsManager = LODsManager.get(renderer);
+     * lodsManager.manual = true;
+     * // ... later, trigger an update at a specific point:
+     * lodsManager.update(scene, camera);
+     * ```
+     */
     update(scene: Scene, camera: Camera): void;
     private onAfterRender;
     /**