@needle-tools/gltf-progressive 4.0.0-alpha.1 → 4.0.0-alpha.2

package/lib/extension.js

@@ -36,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) {
@@ -43,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
@@ -186,7 +209,7 @@ export class NEEDLE_progressive {
      * });
      * ```
      */
-    static assignMeshLOD(mesh, level) {
+    static assignMeshLOD(mesh, level, options) {
         if (!mesh)
             return Promise.resolve(null);
         if (mesh instanceof Mesh || mesh.isMesh === true) {
@@ -200,21 +223,32 @@ export class NEEDLE_progressive {
             }
             // const info = this.onProgressiveLoadStart(context, source, mesh, null);
             mesh["LOD:requested level"] = level;
-            return NEEDLE_progressive.getOrLoadLOD(currentGeometry, level).then(geo => {
+            const shouldLoad = () => mesh["LOD:requested level"] === level || this.shouldApplyStaleMeshLOD(mesh, level);
+            return NEEDLE_progressive.getOrLoadLOD(currentGeometry, level, {
+                isCurrent: shouldLoad,
+            }).then(geo => {
                 if (Array.isArray(geo)) {
                     const index = lodinfo.index || 0;
                     geo = geo[index];
                 }
-                if (mesh["LOD:requested level"] === level) {
-                    delete mesh["LOD:requested level"];
+                const isLatestRequest = mesh["LOD:requested level"] === level;
+                if (isLatestRequest || this.shouldApplyStaleMeshLOD(mesh, level)) {
+                    if (isLatestRequest) {
+                        delete mesh["LOD:requested level"];
+                    }
                     if (geo && currentGeometry != geo) {
                         const isGeometry = geo?.isBufferGeometry;
                         // if (debug == "verbose") console.log("Progressive Mesh " + mesh.name + " loaded", currentGeometry, "→", geo, "\n", mesh)
-                        if (isGeometry) {
-                            mesh.geometry = geo;
+                        if (!isGeometry) {
+                            if (debug) {
+                                console.error("Invalid LOD geometry", geo);
+                            }
                         }
-                        else if (debug) {
-                            console.error("Invalid LOD geometry", geo);
+                        else if (typeof options?.apply === "function") {
+                            options.apply(geo, level, mesh);
+                        }
+                        else if (options?.apply !== false) {
+                            mesh.geometry = geo;
                         }
                     }
                 }
@@ -231,15 +265,16 @@ export class NEEDLE_progressive {
         }
         return Promise.resolve(null);
     }
-    static assignTextureLOD(materialOrTexture, level = 0) {
+    static assignTextureLOD(materialOrTexture, level = 0, options) {
         if (!materialOrTexture)
             return Promise.resolve(null);
+        const force = options?.force === true;
         if (materialOrTexture.isMesh === true) {
             const mesh = materialOrTexture;
             if (Array.isArray(mesh.material)) {
                 const arr = new Array();
                 for (const mat of mesh.material) {
-                    const promise = this.assignTextureLOD(mat, level);
+                    const promise = this.assignTextureLOD(mat, level, options);
                     arr.push(promise);
                 }
                 return Promise.all(arr).then(res => {
@@ -253,13 +288,14 @@ export class NEEDLE_progressive {
                 });
             }
             else {
-                return this.assignTextureLOD(mesh.material, level);
+                return this.assignTextureLOD(mesh.material, level, options);
             }
         }
         if (materialOrTexture.isMaterial === true) {
             const material = materialOrTexture;
             const promises = [];
             const slots = new Array();
+            this.trackCurrentMaterialTextureSlots(material);
             // Handle custom shaders / uniforms progressive textures. This includes support for VRM shaders
             if (material.uniforms && (material.isRawShaderMaterial || material.isShaderMaterial === true)) {
                 // iterate uniforms of custom shaders
@@ -267,7 +303,7 @@ export class NEEDLE_progressive {
                 for (const slot of Object.keys(shaderMaterial.uniforms)) {
                     const val = shaderMaterial.uniforms[slot].value;
                     if (val?.isTexture === true) {
-                        const task = this.assignTextureLODForSlot(val, level, material, slot).then(res => {
+                        const task = this.assignTextureLODForSlot(val, level, material, slot, force).then(res => {
                             if (res && shaderMaterial.uniforms[slot].value != res) {
                                 shaderMaterial.uniforms[slot].value = res;
                                 shaderMaterial.uniformsNeedUpdate = true;
@@ -283,7 +319,7 @@ export class NEEDLE_progressive {
                 for (const slot of Object.keys(material)) {
                     const val = material[slot];
                     if (val?.isTexture === true) {
-                        const task = this.assignTextureLODForSlot(val, level, material, slot);
+                        const task = this.assignTextureLODForSlot(val, level, material, slot, force);
                         promises.push(task);
                         slots.push(slot);
                     }
@@ -306,7 +342,7 @@ export class NEEDLE_progressive {
         }
         if (materialOrTexture instanceof Texture || materialOrTexture.isTexture === true) {
             const texture = materialOrTexture;
-            return this.assignTextureLODForSlot(texture, level, null, null);
+            return this.assignTextureLODForSlot(texture, level, null, null, force);
         }
         return Promise.resolve(null);
     }
@@ -321,14 +357,36 @@ export class NEEDLE_progressive {
         return NEEDLE_progressive.queue.maxConcurrent;
     }
     // #region INTERNAL
-    static assignTextureLODForSlot(current, level, material, slot) {
+    static assignTextureLODForSlot(current, level, material, slot, force) {
         if (current?.isTexture !== true) {
             return Promise.resolve(null);
         }
         if (slot === "glyphMap") {
             return Promise.resolve(current);
         }
-        return NEEDLE_progressive.getOrLoadLOD(current, level).then(tex => {
+        const currentLOD = this.getAssignedLODInformation(current);
+        if (currentLOD) {
+            if (currentLOD.level === level) {
+                return Promise.resolve(current);
+            }
+            if (!force && currentLOD.level < level) {
+                return Promise.resolve(current);
+            }
+        }
+        if (material && slot) {
+            const pending = this.getPendingTextureSlotRequest(material, slot);
+            if (pending && pending.level === level && pending.force === force) {
+                return pending.promise;
+            }
+        }
+        const requestId = material && slot ? this.nextTextureSlotRequestId(material, slot, level, force) : 0;
+        const isCurrentRequest = () => !material || !slot || this.getLatestTextureSlotRequest(material, slot)?.id === requestId;
+        const shouldLoad = () => isCurrentRequest() || this.shouldApplyStaleTextureSlotLOD(material, slot, level, force);
+        const promise = NEEDLE_progressive.getOrLoadLOD(current, level, {
+            isCurrent: shouldLoad,
+        }).then(tex => {
+            if (!isCurrentRequest() && !this.shouldApplyStaleTextureSlotLOD(material, slot, level, force))
+                return null;
             // this can currently not happen
             if (Array.isArray(tex)) {
                 console.warn("Progressive: Got an array of textures for a texture slot, this should not happen...");
@@ -337,40 +395,19 @@ export class NEEDLE_progressive {
             if (tex?.isTexture === true) {
                 if (tex != current) {
                     if (material && slot) {
-                        const assigned = material[slot];
+                        const assigned = this.getMaterialTextureSlot(material, slot) ?? current;
                         // Check if the assigned texture LOD is higher quality than the current LOD
                         // This is necessary for cases where e.g. a texture is updated via an explicit call to assignTextureLOD
-                        if (assigned && !debug) {
+                        if (assigned && !force) {
                             const assignedLOD = this.getAssignedLODInformation(assigned);
                             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();
                         }
-                        // 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;
+                        this.assignTrackedTextureSlot(material, slot, tex);
                     }
                     // 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(),
@@ -390,6 +427,166 @@ export class NEEDLE_progressive {
             console.error("Error loading LOD", current, err);
             return null;
         });
+        if (material && slot) {
+            this.setPendingTextureSlotRequest(material, slot, level, force, requestId, promise);
+        }
+        return promise;
+    }
+    // Track material slots, not just texture objects. A shared fallback texture can be
+    // referenced by many slots and should only be disposed after every slot moved away.
+    static trackedTextureSlots = new WeakMap();
+    static pendingTextureSlotRequests = new WeakMap();
+    static latestTextureSlotRequests = new WeakMap();
+    static textureSlotRequestId = 0;
+    static trackCurrentMaterialTextureSlots(material) {
+        if (material.uniforms && (material.isRawShaderMaterial || material.isShaderMaterial === true)) {
+            const shaderMaterial = material;
+            for (const slot of Object.keys(shaderMaterial.uniforms)) {
+                const value = shaderMaterial.uniforms[slot].value;
+                if (value?.isTexture === true) {
+                    this.ensureTrackedTextureSlot(material, slot, value);
+                }
+            }
+            return;
+        }
+        for (const slot of Object.keys(material)) {
+            const value = material[slot];
+            if (value?.isTexture === true) {
+                this.ensureTrackedTextureSlot(material, slot, value);
+            }
+        }
+    }
+    static getPendingTextureSlotRequest(material, slot) {
+        return this.pendingTextureSlotRequests.get(material)?.get(slot);
+    }
+    static nextTextureSlotRequestId(material, slot, level, force) {
+        let slots = this.latestTextureSlotRequests.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.latestTextureSlotRequests.set(material, slots);
+        }
+        const id = ++this.textureSlotRequestId;
+        slots.set(slot, { id, level, force });
+        return id;
+    }
+    static getLatestTextureSlotRequest(material, slot) {
+        return this.latestTextureSlotRequests.get(material)?.get(slot);
+    }
+    static shouldApplyStaleTextureSlotLOD(material, slot, level, force) {
+        if (!material || !slot)
+            return false;
+        const latest = this.getLatestTextureSlotRequest(material, slot);
+        const assigned = this.getMaterialTextureSlot(material, slot);
+        const assignedLODLevel = this.getAssignedLODInformation(assigned)?.level ?? Infinity;
+        if (level >= assignedLODLevel)
+            return false;
+        if (force) {
+            if (!latest)
+                return false;
+            return level >= latest.level;
+        }
+        return true;
+    }
+    static shouldApplyStaleMeshLOD(mesh, level) {
+        const latestLevel = mesh["LOD:requested level"];
+        if (typeof latestLevel !== "number")
+            return false;
+        const assignedLODLevel = this.getAssignedLODInformation(mesh.geometry)?.level ?? Infinity;
+        return level < assignedLODLevel && level >= latestLevel;
+    }
+    static setPendingTextureSlotRequest(material, slot, level, force, id, promise) {
+        let slots = this.pendingTextureSlotRequests.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.pendingTextureSlotRequests.set(material, slots);
+        }
+        const request = { level, force, id, promise };
+        slots.set(slot, request);
+        promise.finally(() => {
+            const current = slots.get(slot);
+            if (current?.id === id) {
+                slots.delete(slot);
+            }
+        });
+    }
+    static getMaterialTextureSlot(material, slot) {
+        const uniforms = material.uniforms;
+        const uniform = uniforms?.[slot];
+        if (uniform?.value?.isTexture === true) {
+            return uniform.value;
+        }
+        const value = material[slot];
+        if (value?.isTexture === true) {
+            return value;
+        }
+        return null;
+    }
+    static setMaterialTextureSlot(material, slot, texture) {
+        const uniforms = material.uniforms;
+        const uniform = uniforms?.[slot];
+        if (uniform?.value?.isTexture === true) {
+            uniform.value = texture;
+            material.uniformsNeedUpdate = true;
+            return;
+        }
+        material[slot] = texture;
+    }
+    static assignTrackedTextureSlot(material, slot, texture) {
+        let slots = this.trackedTextureSlots.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.trackedTextureSlots.set(material, slots);
+        }
+        const assigned = this.getMaterialTextureSlot(material, slot);
+        let previousTracked = slots.get(slot);
+        if (!previousTracked && assigned) {
+            previousTracked = this.ensureTrackedTextureSlot(material, slot, assigned);
+        }
+        else if (previousTracked && assigned && previousTracked !== assigned) {
+            this.releaseTrackedTextureSlot(material, slot, previousTracked);
+            previousTracked = this.ensureTrackedTextureSlot(material, slot, assigned);
+        }
+        if (previousTracked === texture && assigned === texture) {
+            return;
+        }
+        if (previousTracked && previousTracked !== texture) {
+            this.releaseTrackedTextureSlot(material, slot, previousTracked);
+        }
+        if (previousTracked !== texture) {
+            this.trackTextureUsage(texture);
+            slots.set(slot, texture);
+        }
+        if (assigned !== texture) {
+            this.setMaterialTextureSlot(material, slot, texture);
+        }
+    }
+    static ensureTrackedTextureSlot(material, slot, texture) {
+        let slots = this.trackedTextureSlots.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.trackedTextureSlots.set(material, slots);
+        }
+        const previous = slots.get(slot);
+        if (previous === texture) {
+            return previous;
+        }
+        if (previous) {
+            this.releaseTrackedTextureSlot(material, slot, previous);
+        }
+        this.trackTextureUsage(texture);
+        slots.set(slot, texture);
+        return texture;
+    }
+    static releaseTrackedTextureSlot(material, slot, texture) {
+        const slots = this.trackedTextureSlots.get(material);
+        if (slots?.get(slot) === texture) {
+            slots.delete(slot);
+        }
+        const wasDisposed = this.untrackTextureUsage(texture);
+        if (wasDisposed && (debug || debugGC)) {
+            const assignedLOD = this.getAssignedLODInformation(texture);
+            console.log(`[gltf-progressive] Disposed old texture LOD ${assignedLOD?.level ?? '?'} for ${material.name || material.type}.${slot}`, texture.uuid);
+        }
     }
     parser;
     url;
@@ -492,7 +689,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) {
@@ -514,7 +719,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;
@@ -603,6 +818,10 @@ export class NEEDLE_progressive {
             this.cache.clear();
             // Clear all texture reference counts when disposing everything
             this.textureRefCounts.clear();
+            this.trackedTextureSlots = new WeakMap();
+            this.pendingTextureSlotRequests = new WeakMap();
+            this.latestTextureSlotRequests = new WeakMap();
+            this.textureSlotRequestId = 0;
         }
     }
     /** Dispose a single cache entry's three.js resource(s) to free GPU memory. */
@@ -720,7 +939,7 @@ export class NEEDLE_progressive {
     }
     static workers = [];
     static _workersIndex = 0;
-    static async getOrLoadLOD(current, level) {
+    static async getOrLoadLOD(current, level, options) {
         const debugverbose = debug == "verbose";
         /** this key is used to lookup the LOD information */
         const LOD = this.getAssignedLODInformation(current);
@@ -789,76 +1008,26 @@ export class NEEDLE_progressive {
                 }
                 // check if the requested file has already been loaded
                 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.cache.get(KEY);
-                if (existing !== undefined) {
+                const cached = await this.tryResolveLODCacheEntry(this.cache.get(KEY), KEY, lod_url, current, level, debugverbose);
+                if (cached.found)
+                    return cached.value;
+                if (options?.isCurrent?.() === false) {
                     if (debugverbose)
-                        console.log(`LOD ${level} was already loading/loaded: ${KEY}`);
-                    if (existing instanceof WeakRef) {
-                        // Previously resolved resource — check if still alive in memory
-                        const derefed = existing.deref();
-                        if (derefed) {
-                            let res = derefed;
-                            let resourceIsDisposed = false;
-                            if (res instanceof Texture && current instanceof Texture) {
-                                if (hasPixelData(res.image) || getSourceData(res)) {
-                                    res = this.copySettings(current, res);
-                                }
-                                else {
-                                    resourceIsDisposed = true;
-                                }
-                            }
-                            else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                                if (!res.attributes.position?.array) {
-                                    resourceIsDisposed = true;
-                                }
-                            }
-                            if (!resourceIsDisposed) {
-                                return res;
-                            }
-                        }
-                        // Resource was garbage collected or disposed — remove stale entry and re-load
-                        this.cache.delete(KEY);
-                        if (debug)
-                            console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${KEY}`);
-                    }
-                    else {
-                        // Promise — loading in progress or previously completed
-                        let res = await existing.catch(err => {
-                            console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
-                            return null;
-                        });
-                        let resouceIsDisposed = false;
-                        if (res == null) {
-                            // if the resource is null the last loading result didnt succeed (maybe because the url doesnt exist)
-                            // in which case we don't attempt to load it again
-                        }
-                        else if (res instanceof Texture && current instanceof Texture) {
-                            // check if the texture has been disposed or not
-                            if (hasPixelData(res.image) || getSourceData(res)) {
-                                res = this.copySettings(current, res);
-                            }
-                            // if it has been disposed we need to load it again
-                            else {
-                                resouceIsDisposed = true;
-                                this.cache.delete(KEY);
-                            }
-                        }
-                        else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                            if (res.attributes.position?.array) {
-                                // the geometry is OK
-                            }
-                            else {
-                                resouceIsDisposed = true;
-                                this.cache.delete(KEY);
-                            }
-                        }
-                        if (!resouceIsDisposed) {
-                            return res;
-                        }
-                    }
+                        console.log(`Skipping stale LOD ${level} request before queue: ${lod_url}`);
+                    return null;
+                }
+                const slot = await this.queue.slot(lod_url);
+                if (options?.isCurrent?.() === false) {
+                    if (debugverbose)
+                        console.log(`Skipping stale LOD ${level} request after queue: ${lod_url}`);
+                    return null;
                 }
+                // Another request can fill the cache while this one waits for a queue slot.
+                // Re-checking here avoids duplicate loads for heavily instanced assets.
+                const cachedAfterQueue = await this.tryResolveLODCacheEntry(this.cache.get(KEY), KEY, lod_url, current, level, debugverbose);
+                if (cachedAfterQueue.found)
+                    return cachedAfterQueue.value;
                 // #region loading
                 if (!slot.use) {
                     if (debug)
@@ -1034,10 +1203,19 @@ export class NEEDLE_progressive {
             }
             else {
                 if (current instanceof Texture) {
+                    if (options?.isCurrent?.() === false) {
+                        if (debugverbose)
+                            console.log(`Skipping stale texture LOD ${level} request: ${lod_url}`);
+                        return null;
+                    }
                     if (debugverbose)
                         console.log("Load texture from uri: " + lod_url);
                     const loader = new TextureLoader();
                     const tex = await loader.loadAsync(lod_url);
+                    if (options?.isCurrent?.() === false) {
+                        tex?.dispose();
+                        return null;
+                    }
                     if (tex) {
                         tex.guid = lodInfo.guid;
                         tex.flipY = false;
@@ -1054,7 +1232,69 @@ export class NEEDLE_progressive {
         }
         return null;
     }
-    static queue = new PromiseQueue(isMobileDevice() ? 20 : 50, { debug: debug != false });
+    static async tryResolveLODCacheEntry(existing, key, lodUrl, current, level, debugverbose) {
+        if (existing === undefined) {
+            return { found: false };
+        }
+        if (debugverbose)
+            console.log(`LOD ${level} was already loading/loaded: ${key}`);
+        if (existing instanceof WeakRef) {
+            const derefed = existing.deref();
+            if (derefed) {
+                let res = derefed;
+                let resourceIsDisposed = false;
+                if (res instanceof Texture && current instanceof Texture) {
+                    if (hasPixelData(res.image) || getSourceData(res)) {
+                        res = this.copySettings(current, res);
+                    }
+                    else {
+                        resourceIsDisposed = true;
+                    }
+                }
+                else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
+                    if (!res.attributes.position?.array) {
+                        resourceIsDisposed = true;
+                    }
+                }
+                if (!resourceIsDisposed) {
+                    return { found: true, value: res };
+                }
+            }
+            this.cache.delete(key);
+            if (debug)
+                console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${key}`);
+            return { found: false };
+        }
+        let res = await existing.catch(err => {
+            console.error(`Error loading LOD ${level} from ${lodUrl}\n`, err);
+            return null;
+        });
+        let resourceIsDisposed = false;
+        if (res == null) {
+            // Failed loads stay cached as null so we don't retry the same missing resource forever.
+        }
+        else if (res instanceof Texture && current instanceof Texture) {
+            if (hasPixelData(res.image) || getSourceData(res)) {
+                res = this.copySettings(current, res);
+            }
+            else {
+                resourceIsDisposed = true;
+                this.cache.delete(key);
+            }
+        }
+        else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
+            if (!res.attributes.position?.array) {
+                resourceIsDisposed = true;
+                this.cache.delete(key);
+            }
+        }
+        if (resourceIsDisposed) {
+            return { found: false };
+        }
+        return { found: true, value: res };
+    }
+    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/index.d.ts

@@ -1,7 +1,7 @@
 export { version as VERSION } from "./version.js";
 export * from "./extension.js";
 export * from "./plugins/index.js";
-export { LODsManager, type LOD_Results } from "./lods.manager.js";
+export { LODsManager, calculateMeshLODLevel, getLODColor, lodDebugColors, type LOD_Results, type MeshLODSelectionOptions, type MeshLODSelectionResult } from "./lods.manager.js";
 export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
 export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
 import { WebGLRenderer } from "three";

package/lib/index.js

@@ -1,7 +1,7 @@
 export { version as VERSION } from "./version.js";
 export * from "./extension.js";
 export * from "./plugins/index.js";
-export { LODsManager } from "./lods.manager.js";
+export { LODsManager, calculateMeshLODLevel, getLODColor, lodDebugColors } from "./lods.manager.js";
 export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
 export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
 import { addDracoAndKTX2Loaders, configureLoader, createLoaders } from "./loaders.js";