@preference-sl/pref-viewer 2.13.0-beta.11 → 2.13.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.13.0-beta.11",
+    "version": "2.13.0-beta.13",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-controller.js

@@ -18,14 +18,15 @@ import { translate } from "./localization/i18n.js";
  * turns it into a deterministic scene lifecycle with exports.
  *
  * Overview
- *  - Creates the Babylon.js engine/scene/camera stack, configures Draco decoders, wires resize + render loops, and
- *    exposes download/xR helpers.
+ *  - Creates the Babylon.js engine/scene/camera stack, configures Draco decoders, wires render loops plus a throttled
+ *    ResizeObserver, and exposes download/XR helpers.
  *  - Resolves GLTF/GLB sources via GLTFResolver, loads them into `AssetContainer`s, and toggles visibility by
  *    mutating container state plus `show-model/show-scene` attributes.
  *  - Applies/persists AA, SSAO, IBL, and shadow flags; when they change it stops the render loop, tears down pipelines,
  *    reloads containers, and reinstalls effects after environment textures finish loading.
  *  - Manages keyboard/pointer/wheel handlers, animation menus, and WebXR so PrefViewer menus and DOM attributes stay
- *    synchronized with Babylon state, using sampled pointer picking to reduce raycast cost on dense scenes.
+ *    synchronized with Babylon state, using sampled pointer picking and last-picked tracking to reduce raycast/highlight
+ *    cost on dense scenes.
  *  - Generates GLB, glTF+ZIP, or USDZ exports with timestamped names and localized dialog copy.
  *  - Translates metadata (inner floor offsets, cast/receive shadows, camera locks) into scene adjustments after reloads.
  *
@@ -39,7 +40,8 @@ import { translate } from "./localization/i18n.js";
  *  5. Use `setContainerVisibility`, `setMaterialOptions`, `setCameraOptions`, or `setIBLOptions` for targeted updates; these
  *     helpers stop/restart the render loop while they rebuild camera-dependent resources.
  *  6. Invoke `disable()` when the element disconnects to tear down scenes, XR sessions, observers, and handlers.
- *     The controller also disposes the shared GLTF resolver, which closes its internal IndexedDB handle.
+ *     `disable()` is asynchronous; it waits for XR/session shutdown before engine disposal and also disposes the
+ *     shared GLTF resolver, which closes its internal IndexedDB handle.
  *
  * Public API Highlights
  *  - constructor(canvas, containers, options)
@@ -65,6 +67,12 @@ import { translate } from "./localization/i18n.js";
  *    in SSR/Node contexts (though functionality activates only in browsers).
  *  - Pointer-pick lifecycle: hover/highlight raycasts are sampled on POINTERMOVE (time + distance thresholds), wheel
  *    input avoids picks entirely, and right-click POINTERUP performs an on-demand pick for context-menu targeting.
+ *  - Runtime bookkeeping is split into mutable `#state` and tuning constants under `#config` to keep behavior changes
+ *    explicit and reduce cross-field drift.
+ *  - Resize lifecycle: canvas resize notifications are throttled (with trailing execution) before calling `engine.resize()`
+ *    and any queued resize callback is canceled during teardown.
+ *  - Teardown lifecycle: concurrent `disable()` calls are coalesced into a single in-flight promise to avoid races
+ *    during XR exit and engine disposal.
  */
 export default class BabylonJSController {
     #RENDER_SETTINGS_STORAGE_KEY = "pref-viewer/render-settings";
@@ -96,9 +104,8 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
-
+    
     #hdrTexture = null; // reusable in-memory HDR source cloned into scene.environmentTexture across reloads
-    #lastPickedMeshId = null;
 
     #containers = {};
     #options = {};
@@ -113,39 +120,61 @@ export default class BabylonJSController {
     };
 
     #handlers = {
+        onAnimationGroupChanged: null,
         onKeyUp: null,
         onPointerObservable: null,
-        onAnimationGroupChanged: null,
         onResize: null,
         renderLoop: null,
     };
 
     #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
 
-    // State and config for render loop management to balance performance with responsiveness; uses a dirty frame counter plus continuous render windows triggered by interactions, animations, or XR sessions.
-    #renderState = {
-        isLoopRunning: false,
-        dirtyFrames: 0,
-        continuousUntil: 0,
-        lastRenderAt: 0,
-    };
-    #renderConfig = {
-        burstFramesBase: 2,
-        burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
-        interactionMs: 250,
-        animationMs: 200,
-        idleThrottleMs: 1000 / 15,
+    // Runtime mutable state (changes while the app is running).
+    #state = {
+        // Pointer-picking sampling state avoids expensive scene.pick on every move.
+        pointerPicking: {
+            lastMovePickAt: 0,
+            lastMovePickX: NaN,
+            lastMovePickY: NaN,
+            lastPickedMeshId: null,
+        },
+        // Render loop state balances performance with responsiveness.
+        render: {
+            isLoopRunning: false,
+            dirtyFrames: 0,
+            continuousUntil: 0,
+            lastRenderAt: 0,
+        },
+        // Resize state batches frequent ResizeObserver notifications.
+        resize: {
+            isScheduled: false,
+            timeoutId: null,
+            lastAppliedAt: 0,
+        },
     };
 
-    // State and config for pointer-picking sampling to avoid expensive scene.pick calls on every mouse move; uses time + distance heuristics to balance responsiveness with performance.
-    #pointerPickingState = {
-        lastMovePickAt: 0,
-        lastMovePickX: NaN,
-        lastMovePickY: NaN,
+    // Runtime configuration constants (tuning knobs, not per-frame state).
+    #config = {
+        pointerPicking: {
+            movePickIntervalMs: 50, // cap expensive scene.pick calls to ~20 Hz while moving the pointer
+            movePickMinDistancePx: 2, // skip picks for sub-pixel jitter
+        },
+        render: {
+            burstFramesBase: 2,
+            burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
+            interactionMs: 250,
+            animationMs: 200,
+            idleThrottleMs: 1000 / 15,
+        },
+        resize: {
+            throttleMs: 50, // cap resize work to ~20 Hz while dragging/resizing containers
+        },
     };
-    #pointerPickingConfig = {
-        movePickIntervalMs: 50, // cap expensive scene.pick calls to ~20 Hz while moving the pointer
-        movePickMinDistancePx: 2, // skip picks for sub-pixel jitter
+
+    // Promises to track async disable() lifecycle when XR and general teardown may run concurrently; ensures idempotent disable calls are safe and callers can await full teardown completion.
+    #disablingPromises = {
+        xr: null,
+        general: null,
     };
 
     /**
@@ -312,11 +341,11 @@ export default class BabylonJSController {
      * @returns {boolean} True when the loop was started, false when no engine is available or it was already running.
      */
     #startEngineRenderLoop() {
-        if (!this.#engine || this.#renderState.isLoopRunning) {
+        if (!this.#engine || this.#state.render.isLoopRunning) {
             return false;
         }
         this.#engine.runRenderLoop(this.#handlers.renderLoop);
-        this.#renderState.isLoopRunning = true;
+        this.#state.render.isLoopRunning = true;
         return true;
     }
 
@@ -326,13 +355,25 @@ export default class BabylonJSController {
      * @returns {boolean} True when the loop was stopped, false when no engine is available or it was already stopped.
      */
     #stopEngineRenderLoop() {
-        if (!this.#engine || !this.#renderState.isLoopRunning) {
+        if (!this.#engine || !this.#state.render.isLoopRunning) {
             return false;
         }
         this.#engine.stopRenderLoop(this.#handlers.renderLoop);
-        this.#renderState.isLoopRunning = false;
+        this.#state.render.isLoopRunning = false;
         return true;
     }
+    
+    /**
+     * Resets transient render-loop bookkeeping so the next render request starts from a clean baseline.
+     * Clears queued burst frames, ends any active continuous-render window, and drops the idle-throttle timestamp.
+     * @private
+     * @returns {void}
+     */
+    #resetRenderState() {
+        this.#state.render.dirtyFrames = 0;
+        this.#state.render.continuousUntil = 0;
+        this.#state.render.lastRenderAt = 0;
+    }
 
     /**
      * Marks the scene as dirty and optionally extends a short continuous-render window.
@@ -349,9 +390,9 @@ export default class BabylonJSController {
         }
 
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-        this.#renderState.dirtyFrames = Math.max(this.#renderState.dirtyFrames, Math.max(1, frames));
+        this.#state.render.dirtyFrames = Math.max(this.#state.render.dirtyFrames, Math.max(1, frames));
         if (continuousMs > 0) {
-            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + continuousMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + continuousMs);
         }
         this.#startEngineRenderLoop();
         return true;
@@ -436,13 +477,13 @@ export default class BabylonJSController {
         const cameraInMotion = this.#isCameraInMotion();
 
         if (animationRunning) {
-            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + this.#renderConfig.animationMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.animationMs);
         }
         if (cameraInMotion) {
-            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + this.#renderConfig.interactionMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.interactionMs);
         }
 
-        return animationRunning || cameraInMotion || this.#renderState.continuousUntil > now;
+        return animationRunning || cameraInMotion || this.#state.render.continuousUntil > now;
     }
 
     /**
@@ -460,22 +501,22 @@ export default class BabylonJSController {
 
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         const continuous = this.#shouldRenderContinuously(now);
-        const needsRender = continuous || this.#renderState.dirtyFrames > 0;
+        const needsRender = continuous || this.#state.render.dirtyFrames > 0;
 
         if (!needsRender) {
             this.#stopEngineRenderLoop();
             return;
         }
 
-        if (!continuous && this.#renderState.lastRenderAt > 0 && now - this.#renderState.lastRenderAt < this.#renderConfig.idleThrottleMs) {
+        if (!continuous && this.#state.render.lastRenderAt > 0 && now - this.#state.render.lastRenderAt < this.#config.render.idleThrottleMs) {
             return;
         }
-
+        
         this.#scene.render();
-        this.#renderState.lastRenderAt = now;
+        this.#state.render.lastRenderAt = now;
 
-        if (this.#renderState.dirtyFrames > 0) {
-            this.#renderState.dirtyFrames -= 1;
+        if (this.#state.render.dirtyFrames > 0) {
+            this.#state.render.dirtyFrames -= 1;
         }
     }
 
@@ -1200,10 +1241,10 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #resetPointerPickingState() {
-        this.#pointerPickingState.lastMovePickAt = 0;
-        this.#pointerPickingState.lastMovePickX = NaN;
-        this.#pointerPickingState.lastMovePickY = NaN;
-        this.#lastPickedMeshId = null;
+        this.#state.pointerPicking.lastMovePickAt = 0;
+        this.#state.pointerPicking.lastMovePickX = NaN;
+        this.#state.pointerPicking.lastMovePickY = NaN;
+        this.#state.pointerPicking.lastPickedMeshId = null;
     }
 
     /**
@@ -1220,8 +1261,8 @@ export default class BabylonJSController {
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         const x = this.#scene.pointerX;
         const y = this.#scene.pointerY;
-        const state = this.#pointerPickingState;
-        const config = this.#pointerPickingConfig;
+        const state = this.#state.pointerPicking;
+        const config = this.#config.pointerPicking;
 
         if (!Number.isFinite(state.lastMovePickX) || !Number.isFinite(state.lastMovePickY)) {
             state.lastMovePickX = x;
@@ -1256,10 +1297,7 @@ export default class BabylonJSController {
             this.#scene.onPointerObservable.add(this.#handlers.onPointerObservable);
         }
         if (this.#engine) {
-            this.#canvasResizeObserver = new ResizeObserver(() => {
-                this.#engine.resize();
-                this.#requestRender({ frames: this.#renderConfig.burstFramesBase, continuousMs: this.#renderConfig.interactionMs });
-            });
+            this.#canvasResizeObserver = new ResizeObserver(this.#handlers.onResize);
             this.#canvasResizeObserver.observe(this.#canvas);
         }
     }
@@ -1276,6 +1314,7 @@ export default class BabylonJSController {
         if (this.#scene !== null) {
             this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
         }
+        this.#cancelScheduledResize();
         this.#canvasResizeObserver?.disconnect();
         this.#canvasResizeObserver = null;
         this.#detachAnimationChangedListener();
@@ -1308,30 +1347,43 @@ export default class BabylonJSController {
 
     /**
      * Disposes the Babylon.js WebXR experience if it exists.
+     * If XR is currently active, waits for `exitXRAsync()` before disposing to avoid
+     * tearing down the engine while the XR session is still shutting down.
+     * Concurrent calls share the same in-flight promise so disposal runs only once.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
-    #disposeXRExperience() {
-        if (!this.#XRExperience) {
+    async #disposeXRExperience() {
+        if (this.#disablingPromises.xr) {
+            return await this.#disablingPromises.xr;
+        }
+
+        const xrExperience = this.#XRExperience;
+        if (!xrExperience) {
             return;
         }
 
-        if (this.#XRExperience.baseExperience.state === WebXRState.IN_XR) {
-            this.#XRExperience.baseExperience
-                .exitXRAsync()
-                .then(() => {
-                    this.#XRExperience.dispose();
-                    this.#XRExperience = null;
-                })
-                .catch((error) => {
-                    console.warn("Error exiting XR experience:", error);
-                    this.#XRExperience.dispose();
+        this.#disablingPromises.xr = (async () => {
+            try {
+                if (xrExperience.baseExperience?.state === WebXRState.IN_XR) {
+                    await xrExperience.baseExperience.exitXRAsync();
+                }
+            } catch (error) {
+                console.warn("PrefViewer: Error exiting XR experience:", error);
+            } finally {
+                try {
+                    xrExperience.dispose();
+                } catch (error) {
+                    console.warn("PrefViewer: Error disposing XR experience:", error);
+                }
+                if (this.#XRExperience === xrExperience) {
                     this.#XRExperience = null;
-                });
-        } else {
-            this.#XRExperience.dispose();
-            this.#XRExperience = null;
-        }
+                }
+                this.#disablingPromises.xr = null;
+            }
+        })();
+
+        await this.#disablingPromises.xr;
     }
 
     /**
@@ -1379,7 +1431,7 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onAnimationGroupPlay() {
-        this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.animationMs });
+        this.#requestRender({ frames: 1, continuousMs: this.#config.render.animationMs });
     }
 
     /**
@@ -1388,7 +1440,12 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onAnimationGroupStop() {
-        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#renderConfig.burstFramesEnhanced : this.#renderConfig.burstFramesBase;
+        debugger;
+        if (this.#settings.iblEnabled && this.#renderPipelines.iblShadows) {
+            this.#renderPipelines.iblShadows.updateVoxelization();
+            this.#scene?.postProcessRenderPipelineManager?.update();
+        }
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
         this.#requestRender({ frames: frames });
     }
 
@@ -1466,7 +1523,7 @@ export default class BabylonJSController {
                 const movementVector = direction.scale(zoomSpeed);
                 camera.position = camera.position.add(movementVector);
             }
-            this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
         }
     }
 
@@ -1499,14 +1556,14 @@ export default class BabylonJSController {
     #onPointerMove(event, pickInfo) {
         const camera = this.#scene?.activeCamera;
         if (camera && !camera.metadata?.locked) {
-            this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
         }
         if (this.#babylonJSAnimationController && pickInfo) {
             const pickedMeshId = pickInfo?.pickedMesh?.id || null;
-            if (this.#lastPickedMeshId !== pickedMeshId) {
+            if (this.#state.pointerPicking.lastPickedMeshId !== pickedMeshId) {
                 const highlightResult = this.#babylonJSAnimationController.highlightMeshes(pickInfo);
                 if (highlightResult.changed) {
-                    this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+                    this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
                 }
             }
         }
@@ -1528,11 +1585,11 @@ export default class BabylonJSController {
                 lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
             }
             this.#onPointerMove(info.event, pickInfo);
-            this.#lastPickedMeshId = lastPickedMeshId;
+            this.#state.pointerPicking.lastPickedMeshId = lastPickedMeshId;
         } else if (info.type === PointerEventTypes.POINTERUP) {
             const pickInfo = info.event?.button === 2 ? this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY) : null;
             if (pickInfo) {
-                this.#lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
+                this.#state.pointerPicking.lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
             }
             this.#onPointerUp(info.event, pickInfo);
         } else if (info.type === PointerEventTypes.POINTERWHEEL) {
@@ -1551,8 +1608,47 @@ export default class BabylonJSController {
         if (!this.#engine) {
             return;
         }
-        this.#engine.resize();
-        this.#requestRender({ frames: this.#renderConfig.burstFramesBase, continuousMs: this.#renderConfig.interactionMs });
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const elapsed = now - this.#state.resize.lastAppliedAt;
+        const applyResize = () => {
+            this.#state.resize.timeoutId = null;
+            this.#state.resize.isScheduled = false;
+            if (!this.#engine) {
+                return;
+            }
+            this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+            console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
+            this.#engine.resize();
+            this.#requestRender({ frames: this.#config.render.burstFramesBase, continuousMs: this.#config.render.interactionMs });
+        };
+
+        if (elapsed >= this.#config.resize.throttleMs) {
+            applyResize();
+            return;
+        }
+
+        if (this.#state.resize.isScheduled) {
+            return;
+        }
+
+        this.#state.resize.isScheduled = true;
+        const waitMs = Math.max(0, this.#config.resize.throttleMs - elapsed);
+        this.#state.resize.timeoutId = setTimeout(() => {
+            applyResize();
+        }, waitMs);
+    }
+
+    /**
+     * Clears any queued throttled resize callback.
+     * @private
+     * @returns {void}
+     */
+    #cancelScheduledResize() {
+        if (this.#state.resize.timeoutId !== null) {
+            clearTimeout(this.#state.resize.timeoutId);
+        }
+        this.#state.resize.timeoutId = null;
+        this.#state.resize.isScheduled = false;
     }
 
     /**
@@ -1898,11 +1994,10 @@ export default class BabylonJSController {
      */
     async #stopRender() {
         this.#stopEngineRenderLoop();
-        this.#renderState.dirtyFrames = 0;
-        this.#renderState.continuousUntil = 0;
-        this.#renderState.lastRenderAt = 0;
+        this.#resetRenderState();
         await this.#unloadCameraDependentEffects();
     }
+
     /**
      * Starts the Babylon.js render loop for the current scene.
      * Waits until the scene is ready before beginning continuous rendering.
@@ -1912,8 +2007,8 @@ export default class BabylonJSController {
     async #startRender() {
         await this.#loadCameraDependentEffects();
         await this.#scene.whenReadyAsync();
-        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#renderConfig.burstFramesEnhanced : this.#renderConfig.burstFramesBase;
-        this.#requestRender({ frames: frames, continuousMs: this.#renderConfig.interactionMs });
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
+        this.#requestRender({ frames: frames, continuousMs: this.#config.render.interactionMs });
     }
 
     /**
@@ -2345,17 +2440,40 @@ export default class BabylonJSController {
     /**
      * Disposes the Babylon.js engine and disconnects the canvas resize observer.
      * Cleans up all scene, camera, light, XR, and GLTF resolver resources.
+     * The teardown is asynchronous: it waits for XR/session-dependent shutdown work
+     * before disposing the engine, and coalesces concurrent calls into one in-flight promise.
      * @public
-     * @returns {void}
+     * @returns {Promise<void>}
      */
-    disable() {
-        this.#disableInteraction();
-        this.#disposeAnimationController();
-        this.#disposeGLTFResolver();
-        this.#disposeXRExperience();
-        this.#unloadCameraDependentEffects();
-        this.#stopEngineRenderLoop();
-        this.#disposeEngine();
+    async disable() {
+        if (this.#disablingPromises.general) {
+            return await this.#disablingPromises.general;
+        }
+
+        this.#disablingPromises.general = (async () => {
+            this.#disableInteraction();
+            this.#disposeAnimationController();
+            this.#disposeGLTFResolver();
+            try {
+                await this.#disposeXRExperience();
+            } catch (error) {
+                console.warn("PrefViewer: Error while disposing XR experience:", error);
+            }
+            try {
+                await this.#unloadCameraDependentEffects();
+            } catch (error) {
+                console.warn("PrefViewer: Error while unloading camera-dependent effects:", error);
+            } finally {
+                this.#stopEngineRenderLoop();
+                this.#disposeEngine();
+            }
+        })();
+
+        try {
+            await this.#disablingPromises.general;
+        } finally {
+            this.#disablingPromises.general = null;
+        }
     }
 
     /**

package/src/localization/i18n.js

@@ -40,7 +40,7 @@ export const setLocale = (localeId) => {
         try {
             listener(currentLocale);
         } catch (error) {
-            console.warn("PrefViewer i18n listener failed", error);
+            console.warn("PrefViewer: i18n listener failed", error);
         }
     });
     return currentLocale;

package/src/pref-viewer-3d.js

@@ -162,7 +162,7 @@ export default class PrefViewer3D extends HTMLElement {
      */
     disconnectedCallback() {
         if (this.#babylonJSController) {
-            this.#babylonJSController.disable();
+            void this.#babylonJSController.disable();
         }
     }