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

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 { determineTextureMemoryInBytes, getParam, isMobileDevice, PromiseQueue, resolveUrl } from "./utils.internal.js";
+import { determineTextureMemoryInBytes, getParam, getSourceData, getTextureDimensions, hasPixelData, 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";
@@ -223,13 +223,19 @@ 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)
@@ -373,7 +379,14 @@ export class NEEDLE_progressive {
                 return pending.promise;
             }
         }
-        const promise = NEEDLE_progressive.getOrLoadLOD(current, level).then(tex => {
+        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...");
@@ -415,7 +428,7 @@ export class NEEDLE_progressive {
             return null;
         });
         if (material && slot) {
-            this.setPendingTextureSlotRequest(material, slot, level, force, promise);
+            this.setPendingTextureSlotRequest(material, slot, level, force, requestId, promise);
         }
         return promise;
     }
@@ -423,6 +436,8 @@ export class NEEDLE_progressive {
     // 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;
@@ -444,17 +459,52 @@ export class NEEDLE_progressive {
     static getPendingTextureSlotRequest(material, slot) {
         return this.pendingTextureSlotRequests.get(material)?.get(slot);
     }
-    static setPendingTextureSlotRequest(material, slot, level, force, promise) {
+    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, promise };
+        const request = { level, force, id, promise };
         slots.set(slot, request);
         promise.finally(() => {
             const current = slots.get(slot);
-            if (current === request) {
+            if (current?.id === id) {
                 slots.delete(slot);
             }
         });
@@ -656,8 +706,7 @@ export class NEEDLE_progressive {
             return;
         }
         if (debug) {
-            const width = tex.image?.width || tex.source?.data?.width || 0;
-            const height = tex.image?.height || tex.source?.data?.height || 0;
+            const { width, height } = getTextureDimensions(tex);
             console.log(`> gltf-progressive: register texture[${index}] "${tex.name || tex.uuid}", Current: ${width}x${height}, Max: ${ext.lods[0]?.width}x${ext.lods[0]?.height}, uuid: ${tex.uuid}`, ext, tex);
         }
         // Put the extension info into the source (seems like tiled textures are cloned and the userdata etc is not properly copied BUT the source of course is not cloned)
@@ -771,6 +820,8 @@ export class NEEDLE_progressive {
             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. */
@@ -877,8 +928,7 @@ export class NEEDLE_progressive {
             return false;
         }
         function logDebugInfo(prefix, newCount) {
-            const width = texture.image?.width || texture.source?.data?.width || 0;
-            const height = texture.image?.height || texture.source?.data?.height || 0;
+            let { width, height } = getTextureDimensions(texture);
             const textureSize = width && height ? `${width}x${height}` : "N/A";
             let memorySize = "N/A";
             if (width && height) {
@@ -889,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);
@@ -962,7 +1012,17 @@ export class NEEDLE_progressive {
                 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(`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);
@@ -1143,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;
@@ -1175,7 +1244,7 @@ export class NEEDLE_progressive {
                 let res = derefed;
                 let resourceIsDisposed = false;
                 if (res instanceof Texture && current instanceof Texture) {
-                    if (res.image?.data || res.source?.data) {
+                    if (hasPixelData(res.image) || getSourceData(res)) {
                         res = this.copySettings(current, res);
                     }
                     else {
@@ -1205,7 +1274,7 @@ export class NEEDLE_progressive {
             // 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 (res.image?.data || res.source?.data) {
+            if (hasPixelData(res.image) || getSourceData(res)) {
                 res = this.copySettings(current, res);
             }
             else {

package/lib/loaders.d.ts

@@ -28,14 +28,7 @@ export declare function setKTX2TranscoderLocation(location: string): void;
 export declare function createLoaders(renderer: WebGLRenderer | null): {
     dracoLoader: DRACOLoader;
     ktx2Loader: KTX2Loader;
-    meshoptDecoder: {
-        supported: boolean;
-        ready: Promise<void>;
-        decodeVertexBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array, filter?: string) => void;
-        decodeIndexBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array) => void;
-        decodeIndexSequence: (target: Uint8Array, count: number, size: number, source: Uint8Array) => void;
-        decodeGltfBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array, mode: string, filter?: string) => void;
-    };
+    meshoptDecoder: any;
 };
 export declare function addDracoAndKTX2Loaders(loader: GLTFLoader): void;
 /**

package/lib/loaders.js

@@ -1,3 +1,4 @@
+// @ts-ignore @types/three re-exports from meshoptimizer which may not resolve in all configs
 import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
@@ -142,8 +143,8 @@ const originalLoadFunction = GLTFLoader.prototype.load;
 function onLoad(...args) {
     const config = gltfLoaderConfigurations.get(this);
     let url_str = args[0];
-    const url = new URL(url_str, window.location.href);
-    if (url.hostname.endsWith("needle.tools")) {
+    const url = tryResolveUrl(url_str);
+    if (url?.hostname.endsWith("needle.tools")) {
         const progressive = config?.progressive !== undefined ? config.progressive : true;
         const usecase = config?.usecase ? config.usecase : "default";
         if (progressive) {
@@ -159,3 +160,15 @@ function onLoad(...args) {
     return res;
 }
 GLTFLoader.prototype.load = onLoad;
+function tryResolveUrl(url) {
+    try {
+        if (url instanceof URL) {
+            return url;
+        }
+        const base = globalThis.location?.href;
+        return base ? new URL(url, base) : new URL(url);
+    }
+    catch {
+        return null;
+    }
+}

package/lib/lods.debug.js

@@ -2,7 +2,7 @@ import { getParam } from "./utils.internal.js";
 export const debug = getParam("debugprogressive");
 let debug_RenderWireframe = undefined;
 export let debug_OverrideLodLevel = -1; // -1 is automatic
-if (debug) {
+if (debug && typeof window !== "undefined") {
     const maxLevel = 6;
     function debugToggleProgressive() {
         debug_OverrideLodLevel += 1;

package/lib/lods.manager.d.ts

@@ -75,6 +75,8 @@ export declare class LODsManager {
     static getObjectLODState(object: Object3D): LOD_state | undefined;
     static addPlugin(plugin: NEEDLE_progressive_plugin): void;
     static removePlugin(plugin: NEEDLE_progressive_plugin): void;
+    /** Read-only snapshot of the currently registered plugins, for inspection. Use {@link addPlugin} / {@link removePlugin} to modify the registry. */
+    static getPlugins(): readonly NEEDLE_progressive_plugin[];
     /**
      * Gets the LODsManager for the given renderer. If the LODsManager does not exist yet, it will be created.
      * @param renderer The renderer to get the LODsManager for.
@@ -207,6 +209,7 @@ export declare class LODsManager {
      * Update LODs in a scene
      */
     private internalUpdate;
+    private getRenderList;
     /** Update the LOD levels for the renderer. */
     private updateLODs;
     /** Load progressive textures for the given material

package/lib/lods.manager.js

@@ -1,4 +1,5 @@
-import { Box3, Clock, Color, Matrix4, Mesh, Sphere, Vector3 } from "three";
+import * as THREE from "three";
+import { Box3, Color, Matrix4, Mesh, Sphere, Vector3 } from "three";
 import { NEEDLE_progressive } from "./extension.js";
 import { createLoaders } from "./loaders.js";
 import { getParam, isDevelopmentServer, isMobileDevice } from "./utils.internal.js";
@@ -12,6 +13,7 @@ const suppressProgressiveLoading = getParam("noprogressive");
 const $lodsManager = Symbol("Needle:LODSManager");
 const $lodstate = Symbol("Needle:LODState");
 const $currentLOD = Symbol("Needle:CurrentLOD");
+const ThreeRuntime = THREE;
 const levels = { mesh_lod: -1, texture_lod: -1 };
 const debugLODColor = new Color();
 export const lodDebugColors = [
@@ -48,6 +50,10 @@ export const lodDebugColors = [
     0x4d908e,
     0x555555,
 ];
+function createLODTimer() {
+    const Timer = ThreeRuntime.Timer || ThreeRuntime.Clock;
+    return new Timer();
+}
 const _meshLODWorldBox = new Box3();
 const _meshLODProjectedBox = new Box3();
 const _meshLODCameraSpaceBox = new Box3();
@@ -82,8 +88,10 @@ export function calculateMeshLODLevel(options) {
     result.screenCoverage = 0;
     result.screenspaceVolume.set(0, 0, 0);
     result.centrality = 1;
-    if (!meshLods?.length)
-        return result;
+    // Note: we intentionally do NOT early-return when there are no mesh LODs.
+    // The screen coverage / screenspace volume computed below is also consumed by
+    // the texture LOD selection, which must keep working for meshes that only have
+    // texture LODs (no mesh LODs). Only the mesh LOD-level selection loop is skipped.
     let boundingBox = options.boundingBox ?? geometry.boundingBox;
     if (!boundingBox) {
         geometry.computeBoundingBox();
@@ -159,16 +167,18 @@ export function calculateMeshLODLevel(options) {
         debugDrawLine(_meshLODCorner1, _meshLODCorner3, 0x0000ff);
         debugDrawLine(_meshLODCorner2, _meshLODCorner3, 0x0000ff);
     }
-    for (let i = 0; i < meshLods.length; i++) {
-        const lod = meshLods[i];
-        const density = lod.densities?.[primitiveIndex] || lod.density || .00001;
-        if (primitiveIndex > 0 && warnMissingPrimitiveDensities && isDevelopmentServer() && !lod.densities && !globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"]) {
-            globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"] = true;
-            console.warn(`[Needle Progressive] Detected usage of mesh without primitive densities. This might cause incorrect LOD level selection: Consider re-optimizing your model by updating your Needle Integration, Needle glTF Pipeline or running optimization again on Needle Cloud.`);
-        }
-        if (density / screenCoverage < desiredDensity) {
-            result.level = i;
-            break;
+    if (meshLods?.length) {
+        for (let i = 0; i < meshLods.length; i++) {
+            const lod = meshLods[i];
+            const density = lod.densities?.[primitiveIndex] || lod.density || .00001;
+            if (primitiveIndex > 0 && warnMissingPrimitiveDensities && isDevelopmentServer() && !lod.densities && !globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"]) {
+                globalThis["NEEDLE:MISSING_LOD_PRIMITIVE_DENSITIES"] = true;
+                console.warn(`[Needle Progressive] Detected usage of mesh without primitive densities. This might cause incorrect LOD level selection: Consider re-optimizing your model by updating your Needle Integration, Needle glTF Pipeline or running optimization again on Needle Cloud.`);
+            }
+            if (density / screenCoverage < desiredDensity) {
+                result.level = i;
+                break;
+            }
         }
     }
     return result;
@@ -219,6 +229,10 @@ export class LODsManager {
         if (index >= 0)
             plugins.splice(index, 1);
     }
+    /** Read-only snapshot of the currently registered plugins, for inspection. Use {@link addPlugin} / {@link removePlugin} to modify the registry. */
+    static getPlugins() {
+        return plugins;
+    }
     /**
      * Gets the LODsManager for the given renderer. If the LODsManager does not exist yet, it will be created.
      * @param renderer The renderer to get the LODsManager for.
@@ -390,11 +404,11 @@ export class LODsManager {
         // })
     }
     #originalRender;
-    #clock = new Clock();
     #frame = 0;
     #delta = 0;
     #time = 0;
     #fps = 0;
+    #clock = createLODTimer();
     _fpsBuffer = [60, 60, 60, 60, 60];
     /**
      * Enable the LODsManager. This will replace the render method of the renderer with a method that updates the LODs.
@@ -416,7 +430,8 @@ export class LODsManager {
             if (renderTarget == null || ("isXRRenderTarget" in renderTarget && renderTarget.isXRRenderTarget)) {
                 stack = 0;
                 self.#frame += 1;
-                self.#delta = self.#clock.getDelta();
+                self.#clock.update?.();
+                self.#delta = Math.max(self.#clock.getDelta(), 1 / 1000);
                 self.#time += self.#delta;
                 self._fpsBuffer.shift();
                 self._fpsBuffer.push(1 / self.#delta);
@@ -457,7 +472,9 @@ export class LODsManager {
     onAfterRender(scene, camera, _stack) {
         if (this.pause)
             return;
-        const renderList = this.renderer.renderLists.get(scene, 0);
+        const renderList = this.getRenderList(scene, camera, _stack);
+        if (!renderList)
+            return;
         const opaque = renderList.opaque;
         let updateLODs = true;
         // check if we're rendering a postprocessing pass
@@ -514,7 +531,9 @@ export class LODsManager {
      * Update LODs in a scene
      */
     internalUpdate(scene, camera) {
-        const renderList = this.renderer.renderLists.get(scene, 0);
+        const renderList = this.getRenderList(scene, camera, 0);
+        if (!renderList)
+            return;
         const opaque = renderList.opaque;
         this.projectionScreenMatrix.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
         const desiredDensity = this.targetTriangleDensity;
@@ -560,6 +579,30 @@ export class LODsManager {
             }
         }
     }
+    getRenderList(scene, camera, stack) {
+        const renderer = this.renderer;
+        let renderList = null;
+        if (renderer.isWebGPURenderer === true) {
+            const renderLists = renderer._renderLists;
+            if (!renderLists)
+                return null;
+            renderList = renderLists.get(scene, camera);
+        }
+        else if (renderer.isWebGLRenderer === true) {
+            const renderLists = renderer.renderLists;
+            if (!renderLists)
+                return null;
+            renderList = renderLists.get(scene, stack);
+        }
+        if (!renderList)
+            return null;
+        return {
+            opaque: renderList.opaque || [],
+            transparent: renderList.transparent || [],
+            transmissive: renderList.transmissive || renderList.transparentDoublePass || [],
+            transparentDoublePass: renderList.transparentDoublePass || [],
+        };
+    }
     /** Update the LOD levels for the renderer. */
     updateLODs(scene, camera, object, desiredDensity) {
         if (!object.userData) {
@@ -820,7 +863,8 @@ export class LODsManager {
                 if (this.context?.engine === "model-viewer") {
                     factor *= 1.5;
                 }
-                const screenSize = canvasHeight / window.devicePixelRatio;
+                const devicePixelRatio = this.renderer.getPixelRatio?.() || globalThis.devicePixelRatio || 1;
+                const screenSize = canvasHeight / devicePixelRatio;
                 const pixelSizeOnScreen = screenSize * factor;
                 let foundLod = false;
                 for (let i = texture_lods_minmax.lods.length - 1; i >= 0; i--) {

package/lib/utils.d.ts

@@ -5,7 +5,7 @@ export declare const isSSR: boolean;
  * @param obj the object to get the raycast mesh from
  * @returns the raycast mesh or null if not set
  */
-export declare function getRaycastMesh(obj: Object3D): BufferGeometry<any> | null;
+export declare function getRaycastMesh(obj: Object3D): BufferGeometry<any, any> | null;
 /**
  * Set the raycast mesh for an object.
  * The raycast mesh is a low poly version of the mesh used for raycasting. It is set when a mesh that has LOD level with more vertices is discovered for the first time

package/lib/utils.internal.d.ts

@@ -1,4 +1,31 @@
 import { Texture } from "three";
+/** Represents the possible shapes of texture image/source data in three.js.
+ * Source.data is typed as `{}` in r183 but at runtime can be ImageBitmap, HTMLImageElement, etc. */
+export type TextureImageData = {
+    width?: number;
+    height?: number;
+    depth?: number;
+    data?: ArrayBufferView | null;
+};
+/** Check if a value has image-like dimensions (width/height) */
+export declare function hasImageDimensions(value: unknown): value is {
+    width: number;
+    height: number;
+};
+/** Check if a value has pixel data (e.g. typed array from a DataTexture) */
+export declare function hasPixelData(value: unknown): value is {
+    data: ArrayBufferView;
+};
+/** Get the source data of a texture, typed for dimension/data access */
+export declare function getSourceData(tex: Texture): TextureImageData | null;
+/** Get the image of a texture, typed for dimension/data access.
+ * In r183, Texture.image is typed as `{}` but at runtime is an ImageBitmap, HTMLImageElement, etc. */
+export declare function getTextureImage(tex: Texture): TextureImageData | null;
+/** Get width/height of a texture from image or source data */
+export declare function getTextureDimensions(tex: Texture): {
+    width: number;
+    height: number;
+};
 export declare function isDebugMode(): string | boolean;
 export declare function getParam(name: string): boolean | string;
 export declare function resolveUrl(source: string | undefined, uri: string): string;

package/lib/utils.internal.js

@@ -1,11 +1,41 @@
+import { RedFormat, RedIntegerFormat, RGFormat, RGIntegerFormat, RGBFormat, RGBAFormat, RGBAIntegerFormat } from "three";
+/** Check if a value has image-like dimensions (width/height) */
+export function hasImageDimensions(value) {
+    return value != null && typeof value.width === 'number' && typeof value.height === 'number';
+}
+/** Check if a value has pixel data (e.g. typed array from a DataTexture) */
+export function hasPixelData(value) {
+    return value != null && value.data != null;
+}
+/** Get the source data of a texture, typed for dimension/data access */
+export function getSourceData(tex) {
+    const data = tex.source?.data;
+    return data != null && typeof data === 'object' ? data : null;
+}
+/** Get the image of a texture, typed for dimension/data access.
+ * In r183, Texture.image is typed as `{}` but at runtime is an ImageBitmap, HTMLImageElement, etc. */
+export function getTextureImage(tex) {
+    const img = tex.image;
+    return img != null && typeof img === 'object' ? img : null;
+}
+/** Get width/height of a texture from image or source data */
+export function getTextureDimensions(tex) {
+    const img = getTextureImage(tex);
+    const src = getSourceData(tex);
+    return {
+        width: img?.width || src?.width || 0,
+        height: img?.height || src?.height || 0,
+    };
+}
 const debug = getParam("debugprogressive");
 export function isDebugMode() {
     return debug;
 }
 export function getParam(name) {
-    if (typeof window === "undefined")
+    const href = globalThis.location?.href;
+    if (!href)
         return false;
-    const url = new URL(window.location.href);
+    const url = new URL(href);
     const param = url.searchParams.get(name);
     if (param == null || param === "0" || param === "false")
         return false;
@@ -44,7 +74,8 @@ export function resolveUrl(source, uri) {
 export function isMobileDevice() {
     if (_ismobile !== undefined)
         return _ismobile;
-    _ismobile = /iPhone|iPad|iPod|Android|IEMobile/i.test(navigator.userAgent);
+    const userAgent = globalThis.navigator?.userAgent || "";
+    _ismobile = /iPhone|iPad|iPod|Android|IEMobile/i.test(userAgent);
     if (getParam("debugprogressive"))
         console.log("[glTF Progressive]: isMobileDevice", _ismobile);
     return _ismobile;
@@ -55,9 +86,10 @@ let _ismobile;
  * @returns `true` if we are running in a development server (localhost or ip address).
  */
 export function isDevelopmentServer() {
-    if (typeof window === "undefined")
+    const href = globalThis.location?.href;
+    if (!href)
         return false;
-    const url = new URL(window.location.href);
+    const url = new URL(href);
     const isLocalhostOrIpAddress = url.hostname === "localhost" || /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(url.hostname);
     const isDevelopment = url.hostname === "127.0.0.1" || isLocalhostOrIpAddress;
     return isDevelopment;
@@ -74,8 +106,14 @@ export class PromiseQueue {
     constructor(maxConcurrent, opts = {}) {
         this.maxConcurrent = maxConcurrent;
         this.debug = opts.debug ?? false;
-        if (typeof window !== "undefined")
-            window.requestAnimationFrame(this.tick);
+        // Dedicated workers can have requestAnimationFrame when they are owned by a window.
+        // Other worker-like scopes do not, so keep the frame-based tick when available and fall back to timers otherwise.
+        if (typeof globalThis.requestAnimationFrame === "function") {
+            globalThis.requestAnimationFrame(this.tick);
+        }
+        else {
+            setTimeout(this.tick, 0);
+        }
     }
     tick = () => {
         this.internalUpdate();
@@ -118,9 +156,10 @@ export class PromiseQueue {
 }
 // #region Texture Memory
 export function determineTextureMemoryInBytes(texture) {
-    const width = texture.image?.width ?? 0;
-    const height = texture.image?.height ?? 0;
-    const depth = texture.image?.depth ?? 1;
+    const img = texture.image;
+    const width = img?.width ?? 0;
+    const height = img?.height ?? 0;
+    const depth = img?.depth ?? 1;
     const mipLevels = Math.floor(Math.log2(Math.max(width, height, depth))) + 1;
     const bytesPerPixel = getBytesPerPixel(texture);
     const totalBytes = (width * height * depth * bytesPerPixel * (1 - Math.pow(0.25, mipLevels))) / (1 - 0.25);
@@ -130,22 +169,22 @@ function getBytesPerPixel(texture) {
     // Determine channel count from format
     let channels = 4; // Default RGBA
     const format = texture.format;
-    if (format === 1024)
-        channels = 1; // RedFormat
-    else if (format === 1025)
-        channels = 1; // RedIntegerFormat
-    else if (format === 1026)
-        channels = 2; // RGFormat
-    else if (format === 1027)
-        channels = 2; // RGIntegerFormat
-    else if (format === 1022)
-        channels = 3; // RGBFormat
+    if (format === RedFormat)
+        channels = 1;
+    else if (format === RedIntegerFormat)
+        channels = 1;
+    else if (format === RGFormat)
+        channels = 2;
+    else if (format === RGIntegerFormat)
+        channels = 2;
+    else if (format === RGBFormat)
+        channels = 3;
     else if (format === 1029)
-        channels = 3; // RGBIntegerFormat
-    else if (format === 1023)
-        channels = 4; // RGBAFormat
-    else if (format === 1033)
-        channels = 4; // RGBAIntegerFormat
+        channels = 3; // RGBIntegerFormat (not exported in r183)
+    else if (format === RGBAFormat)
+        channels = 4;
+    else if (format === RGBAIntegerFormat)
+        channels = 4;
     // Determine bytes per channel from type
     let bytesPerChannel = 1; // UnsignedByteType default
     const type = texture.type;
@@ -177,6 +216,10 @@ export function detectGPUMemory() {
     if (rendererInfo !== undefined) {
         return rendererInfo?.estimatedMemory;
     }
+    if (typeof document === "undefined") {
+        rendererInfo = null;
+        return undefined;
+    }
     const canvas = document.createElement('canvas');
     const powerPreference = "high-performance";
     const gl = canvas.getContext('webgl', { powerPreference }) || canvas.getContext('experimental-webgl', { powerPreference });

package/lib/version.js

@@ -1,4 +1,4 @@
 // replaced at build time
-export const version = "3.6.0-alpha.2";
+export const version = "3.6.0-beta.1";
 globalThis["GLTF_PROGRESSIVE_VERSION"] = version;
 console.debug(`[gltf-progressive] version ${version || "-"}`);