@preference-sl/pref-viewer 2.13.0-beta.6 → 2.13.0-beta.8

package/src/babylonjs-controller.js

@@ -8,6 +8,7 @@ import JSZip from "jszip";
 import GLTFResolver from "./gltf-resolver.js";
 import { MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
+import OpeningAnimation from "./babylonjs-animation-opening.js";
 import { translate } from "./localization/i18n.js";
 
 /**
@@ -56,11 +57,13 @@ import { translate } from "./localization/i18n.js";
  *  - `show-model`/`show-scene` DOM attributes reflect container visibility; there are no direct `showModel()/hideModel()` APIs.
  *  - IBL shadows require `iblEnabled` plus `options.ibl.shadows` and a loaded HDR texture; otherwise fallback directional
  *    lights and environment-contributed lights supply classic shadow generators.
+ *  - IBL lifecycle: when `options.ibl.cachedUrl` is present, a new `HDRCubeTexture` is created and cloned into `#hdrTexture`;
+ *    then `options.ibl.consumeCachedUrl(true)` clears/revokes the temporary URL. Subsequent reloads reuse `#hdrTexture.clone()`
+ *    while `options.ibl.valid` remains true.
  *  - Browser-only features guard `window`, localStorage, and XR APIs before use so the controller is safe to construct
  *    in SSR/Node contexts (though functionality activates only in browsers).
  */
 export default class BabylonJSController {
-
     #RENDER_SETTINGS_STORAGE_KEY = "pref-viewer/render-settings";
 
     // Default render settings
@@ -72,7 +75,7 @@ export default class BabylonJSController {
         iblEnabled: true,
         shadowsEnabled: false,
     };
-    
+
     // Canvas HTML element
     #canvas = null;
 
@@ -90,10 +93,13 @@ 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 = {};
-    
+
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
 
@@ -106,11 +112,28 @@ export default class BabylonJSController {
     #handlers = {
         onKeyUp: null,
         onPointerObservable: null,
+        onAnimationGroupChanged: null,
+        onResize: null,
         renderLoop: null,
     };
-    
+
     #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
 
+    #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,
+    };
+
     /**
      * Constructs a new BabylonJSController instance.
      * Initializes the canvas, asset containers, and options for the Babylon.js scene.
@@ -143,8 +166,10 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #bindHandlers() {
+        this.#handlers.onAnimationGroupChanged = this.#onAnimationGroupChanged.bind(this);
         this.#handlers.onKeyUp = this.#onKeyUp.bind(this);
         this.#handlers.onPointerObservable = this.#onPointerObservable.bind(this);
+        this.#handlers.onResize = this.#onResize.bind(this);
         this.#handlers.renderLoop = this.#renderLoop.bind(this);
     }
 
@@ -267,16 +292,177 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Starts Babylon's engine render loop if it is not already running.
+     * @private
+     * @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) {
+            return false;
+        }
+        this.#engine.runRenderLoop(this.#handlers.renderLoop);
+        this.#renderState.isLoopRunning = true;
+        return true;
+    }
+
+    /**
+     * Stops Babylon's engine render loop when it is currently active.
+     * @private
+     * @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) {
+            return false;
+        }
+        this.#engine.stopRenderLoop(this.#handlers.renderLoop);
+        this.#renderState.isLoopRunning = false;
+        return true;
+    }
+
+    /**
+     * Marks the scene as dirty and optionally extends a short continuous-render window.
+     * Ensures the engine loop is running so the requested frames can be produced.
+     * @private
+     * @param {{frames?:number, continuousMs?:number}} [options={}] - Render request options.
+     * @param {number} [options.frames=1] - Minimum number of frames to render.
+     * @param {number} [options.continuousMs=0] - Milliseconds to keep continuous rendering active.
+     * @returns {boolean} True when the request was accepted, false when scene/engine are unavailable.
+     */
+    #requestRender({ frames = 1, continuousMs = 0 } = {}) {
+        if (!this.#scene || !this.#engine) {
+            return false;
+        }
+
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        this.#renderState.dirtyFrames = Math.max(this.#renderState.dirtyFrames, Math.max(1, frames));
+        if (continuousMs > 0) {
+            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + continuousMs);
+        }
+        this.#startEngineRenderLoop();
+        return true;
+    }
+
+    /**
+     * Checks whether an ArcRotateCamera still has non-zero inertial movement.
+     * @private
+     * @param {ArcRotateCamera} camera - Camera to evaluate.
+     * @returns {boolean} True when any inertial offset is still active.
+     */
+    #isArcRotateCameraInMotion(camera) {
+        const EPSILON = 0.00001;
+        return Math.abs(camera?.inertialAlphaOffset || 0) > EPSILON || Math.abs(camera?.inertialBetaOffset || 0) > EPSILON || Math.abs(camera?.inertialRadiusOffset || 0) > EPSILON || Math.abs(camera?.inertialPanningX || 0) > EPSILON || Math.abs(camera?.inertialPanningY || 0) > EPSILON;
+    }
+
+    /**
+     * Checks whether a FreeCamera/UniversalCamera is currently moving or rotating.
+     * @private
+     * @param {FreeCamera|UniversalCamera} camera - Camera to evaluate.
+     * @returns {boolean} True when translation or rotation deltas are active.
+     */
+    #isUniversalOrFreeCameraInMotion(camera) {
+        const EPSILON = 0.00001;
+        const direction = camera?.cameraDirection;
+        const rotation = camera?.cameraRotation;
+        const directionMoving = !!direction && (Math.abs(direction.x) > EPSILON || Math.abs(direction.y) > EPSILON || Math.abs(direction.z) > EPSILON);
+        const rotationMoving = !!rotation && (Math.abs(rotation.x) > EPSILON || Math.abs(rotation.y) > EPSILON || Math.abs(rotation.z) > EPSILON);
+        return directionMoving || rotationMoving;
+    }
+
+    /**
+     * Detects motion for the current active camera based on its concrete camera type.
+     * @private
+     * @returns {boolean} True when the active camera is moving, otherwise false.
+     */
+    #isCameraInMotion() {
+        const camera = this.#scene?.activeCamera;
+        if (!camera) {
+            return false;
+        }
+        if (camera instanceof ArcRotateCamera) {
+            return this.#isArcRotateCameraInMotion(camera);
+        }
+        if (camera instanceof UniversalCamera || camera instanceof FreeCamera) {
+            return this.#isUniversalOrFreeCameraInMotion(camera);
+        }
+        return false;
+    }
+
+    /**
+     * Determines whether scene animations are currently running.
+     * @private
+     * @returns {boolean} True when at least one animation group is playing.
+     */
+    #isAnimationRunning() {
+        if (!this.#scene) {
+            return false;
+        }
+        const hasAnimatables = (this.#scene.animatables?.length || 0) > 0;
+        if (!hasAnimatables) {
+            return false;
+        }
+        return this.#scene.animationGroups?.some((group) => group?.isPlaying) || false;
+    }
+
+    /**
+     * Evaluates whether the renderer should stay in continuous mode.
+     * XR always forces continuous rendering; animation/camera motion also extends the
+     * continuous deadline window to avoid abrupt stop-start behavior.
+     * @private
+     * @param {number} now - Current high-resolution timestamp.
+     * @returns {boolean} True when continuous rendering should remain active.
+     */
+    #shouldRenderContinuously(now) {
+        const inXR = this.#XRExperience?.baseExperience?.state === WebXRState.IN_XR;
+        if (inXR) {
+            return true;
+        }
+
+        const animationRunning = this.#isAnimationRunning();
+        const cameraInMotion = this.#isCameraInMotion();
+
+        if (animationRunning) {
+            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + this.#renderConfig.animationMs);
+        }
+        if (cameraInMotion) {
+            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + this.#renderConfig.interactionMs);
+        }
+
+        return animationRunning || cameraInMotion || this.#renderState.continuousUntil > now;
+    }
+
     /**
      * Render loop callback for Babylon.js.
+     * Runs only while scene state is dirty, interactive motion is active, animations are running, or XR is active.
+     * It self-stops when the scene becomes idle.
      * @private
      * @returns {void}
-     * @description
-     * Continuously renders the current scene if it exists.
-     * Used by the engine's runRenderLoop method to update the view.
      */
     #renderLoop() {
-        this.#scene && this.#scene.render();
+        if (!this.#scene) {
+            this.#stopEngineRenderLoop();
+            return;
+        }
+
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const continuous = this.#shouldRenderContinuously(now);
+        const needsRender = continuous || this.#renderState.dirtyFrames > 0;
+
+        if (!needsRender) {
+            this.#stopEngineRenderLoop();
+            return;
+        }
+
+        if (!continuous && this.#renderState.lastRenderAt > 0 && now - this.#renderState.lastRenderAt < this.#renderConfig.idleThrottleMs) {
+            return;
+        }
+
+        this.#scene.render();
+        this.#renderState.lastRenderAt = now;
+
+        if (this.#renderState.dirtyFrames > 0) {
+            this.#renderState.dirtyFrames -= 1;
+        }
     }
 
     /**
@@ -376,6 +562,10 @@ export default class BabylonJSController {
      * Sets light intensities and shadow properties for realistic rendering.
      * @private
      * @returns {Promise<boolean>} Returns true if lights were changed, false otherwise.
+     * @description
+     * IBL path is considered available when either:
+     *  - `options.ibl.cachedUrl` is present (new pending URL), or
+     *  - `options.ibl.valid === true` (reusable in-memory `#hdrTexture` exists).
      */
     async #createLights() {
         const hemiLightName = "PrefViewerHemiLight";
@@ -388,7 +578,7 @@ export default class BabylonJSController {
 
         let lightsChanged = false;
 
-        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl?.cachedUrl !== null;
+        const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
 
         if (iblEnabled) {
             if (hemiLight) {
@@ -415,14 +605,14 @@ export default class BabylonJSController {
                 this.#hemiLight = new HemisphericLight(hemiLightName, new Vector3(-10, 10, -10), this.#scene);
                 this.#hemiLight.intensity = 0.6;
             }
-    
+
             // Add a directional light to cast shadows and provide stronger directional illumination
             if (!this.#dirLight) {
                 this.#dirLight = new DirectionalLight(dirLightName, new Vector3(-10, 10, -10), this.#scene);
                 this.#dirLight.position = new Vector3(5, 4, 5); // light is IN FRONT + ABOVE + to the RIGHT
                 this.#dirLight.intensity = 0.6;
             }
-    
+
             // Add a point light that follows the camera to ensure the model is always well-lit from the viewer's perspective
             if (!this.#cameraLight) {
                 this.#cameraLight = new PointLight(cameraLightName, this.#camera.position, this.#scene);
@@ -447,7 +637,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
@@ -487,23 +677,23 @@ export default class BabylonJSController {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
-        
+
         const pipelineName = "PrefViewerSSAORenderingPipeline";
 
         const ssaoRatio = {
             ssaoRatio: 0.5,
-            combineRatio: 1.0
+            combineRatio: 1.0,
         };
 
         let ssaoPipeline = new SSAORenderingPipeline(pipelineName, this.#scene, ssaoRatio, [this.#scene.activeCamera]);
 
-        if (!ssaoPipeline){
+        if (!ssaoPipeline) {
             return false;
-        }   
+        }
 
         if (ssaoPipeline.isSupported) {
             ssaoPipeline.fallOff = 0.000001;
@@ -511,7 +701,7 @@ export default class BabylonJSController {
             ssaoPipeline.radius = 0.0001;
             ssaoPipeline.totalStrength = 1;
             ssaoPipeline.base = 0.6;
-            
+
             // Configure SSAO to calculate only once instead of every frame for better performance
             if (ssaoPipeline._ssaoPostProcess) {
                 ssaoPipeline._ssaoPostProcess.autoClear = false;
@@ -521,7 +711,7 @@ export default class BabylonJSController {
                 ssaoPipeline._combinePostProcess.autoClear = false;
                 ssaoPipeline._combinePostProcess.samples = 1;
             }
-            
+
             this.#renderPipelines.ssao = ssaoPipeline;
             pipelineManager.update();
             return true;
@@ -547,7 +737,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
@@ -588,18 +778,18 @@ export default class BabylonJSController {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
-        
+
         const pipelineName = "PrefViewerDefaultRenderingPipeline";
 
         let defaultPipeline = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
 
-        if (!defaultPipeline){
+        if (!defaultPipeline) {
             return false;
-        } 
+        }
 
         if (defaultPipeline.isSupported) {
             // MSAA - Multisample Anti-Aliasing
@@ -647,19 +837,43 @@ export default class BabylonJSController {
 
     /**
      * Initializes the environment texture for the Babylon.js scene.
-     * Loads an HDR texture from a predefined URI and assigns it to the scene's environmentTexture property.
-     * Configures gamma space, mipmaps, and intensity level for realistic lighting.
+     * Resolves the active HDR environment texture using either a fresh `cachedUrl`
+     * or the reusable in-memory clone (`#hdrTexture`), then assigns it to `scene.environmentTexture`.
      * @private
      * @returns {Promise<boolean>} Returns true if the environment texture was changed, false if it was already up to date or failed to load.
+     * @description
+     * Lifecycle implemented here:
+     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it.
+     * 2. Wait for readiness, clone it into `#hdrTexture` for reuse.
+     * 3. Call `options.ibl.consumeCachedUrl(true)` to revoke temporary object URLs and clear `cachedUrl`.
+     * 4. On following reloads, if `options.ibl.valid === true` and no `cachedUrl` is present, use `#hdrTexture.clone()`.
      */
     async #initializeEnvironmentTexture() {
         if (this.#scene.environmentTexture) {
             this.#scene.environmentTexture.dispose();
             this.#scene.environmentTexture = null;
         }
-        const hdrTextureURI = this.#options.ibl.cachedUrl;
-        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 1024, false, false, false, true, undefined, undefined, false, true, true);
+
+        let hdrTexture = null;
+        if (this.#options.ibl?.cachedUrl) {
+            const hdrTextureURI = this.#options.ibl.cachedUrl;
+            hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 1024, false, false, false, true, undefined, undefined, false, true, true);
+        } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
+            hdrTexture = this.#hdrTexture.clone();
+        } else {
+            return false;
+        }
+
         await WhenTextureReadyAsync(hdrTexture);
+
+        if (this.#options.ibl?.cachedUrl) {
+            if (this.#hdrTexture) {
+                this.#hdrTexture.dispose();
+            }
+            this.#hdrTexture = hdrTexture.clone();
+            this.#options.ibl?.consumeCachedUrl?.(true);
+        }
+
         hdrTexture.level = this.#options.ibl.intensity;
         this.#scene.environmentTexture = hdrTexture;
         this.#scene.markAllMaterialsAsDirty(Material.TextureDirtyFlag);
@@ -680,7 +894,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
@@ -716,16 +930,9 @@ export default class BabylonJSController {
      * @returns {Promise<void|boolean>} Returns false if no environment texture is set; otherwise void.
      */
     async #initializeIBLShadows() {
-
-        await this.#scene.whenReadyAsync();
-
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
 
-        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
-            return false;
-        }
-        
-        if (!this.#scene.environmentTexture) {
+        if (!this.#scene || !this.#scene?.activeCamera || !this.#scene?.environmentTexture || !pipelineManager) {
             return false;
         }
 
@@ -736,13 +943,41 @@ export default class BabylonJSController {
             });
             return false;
         }
-        
+
+        const meshesForCastingShadows = this.#scene.meshes.filter((mesh) => {
+            const isRootMesh = mesh.id.startsWith("__root__");
+            if (isRootMesh) {
+                return false;
+            }
+
+            const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
+            const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
+            const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
+
+            if (meshGenerateShadows) {
+                return true;
+            }
+            return false;
+        });
+        const materialsForReceivingShadows = this.#scene.materials.filter((material) => {
+            if (material instanceof PBRMaterial) {
+                material.enableSpecularAntiAliasing = false;
+            }
+            return true;
+        });
+
+        if (meshesForCastingShadows.length === 0 || materialsForReceivingShadows.length === 0) {
+            return false;
+        }
+
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (!supportedPipelines) {
             return false;
         }
 
+        await this.#scene.whenReadyAsync();
+
         const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
         const pipelineOptions = {
@@ -759,7 +994,7 @@ export default class BabylonJSController {
         if (!iblShadowsPipeline) {
             return false;
         }
-       
+
         if (iblShadowsPipeline.isSupported) {
             // Disable all debug passes for performance
             const pipelineProps = {
@@ -775,30 +1010,11 @@ export default class BabylonJSController {
             };
 
             Object.assign(iblShadowsPipeline, pipelineProps);
-            
-            this.#scene.meshes.forEach((mesh) => {
-                const isRootMesh = mesh.id.startsWith("__root__");
-                if (isRootMesh) {
-                    return false;
-                }
-                
-                const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
-                const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
-                const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
-                
-                if (meshGenerateShadows) {
-                    iblShadowsPipeline.addShadowCastingMesh(mesh);
-                    iblShadowsPipeline.updateSceneBounds();
-                }
-            });
-            
-            this.#scene.materials.forEach((material) => {
-                if (material instanceof PBRMaterial) {
-                    material.enableSpecularAntiAliasing = false;
-                }
-                iblShadowsPipeline.addShadowReceivingMaterial(material);
-            });
-            
+
+            meshesForCastingShadows.forEach((mesh) => iblShadowsPipeline.addShadowCastingMesh(mesh));
+            materialsForReceivingShadows.forEach((material) => iblShadowsPipeline.addShadowReceivingMaterial(material));
+
+            iblShadowsPipeline.updateSceneBounds();
             iblShadowsPipeline.toggleShadow(true);
             iblShadowsPipeline.updateVoxelization();
             this.#renderPipelines.iblShadows = iblShadowsPipeline;
@@ -935,7 +1151,7 @@ export default class BabylonJSController {
 
         this.#ensureMeshesReceiveShadows();
 
-        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl?.cachedUrl !== null;
+        const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
         const iblShadowsEnabled = iblEnabled && this.#options.ibl.shadows;
 
         if (iblShadowsEnabled) {
@@ -964,23 +1180,6 @@ export default class BabylonJSController {
         }
     }
 
-    /**
-     * Handles pointer events observed on the Babylon.js scene.
-     * @private
-     * @param {PointerInfo} info - The pointer event information from Babylon.js.
-     * @returns {void}
-     */
-    #onPointerObservable(info) {
-        const pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
-        if (info.type === PointerEventTypes.POINTERUP) {
-            this.#onPointerUp(info.event, pickInfo);
-        } else if (info.type === PointerEventTypes.POINTERMOVE) {
-            this.#onPointerMove(info.event, pickInfo);
-        } else if (info.type === PointerEventTypes.POINTERWHEEL) {
-            this.#onMouseWheel(info.event, pickInfo);
-        }
-    }
-
     /**
      * Sets up interaction handlers for the Babylon.js canvas and scene.
      * @private
@@ -993,6 +1192,13 @@ export default class BabylonJSController {
         if (this.#scene) {
             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.observe(this.#canvas);
+        }
     }
 
     /**
@@ -1007,6 +1213,9 @@ export default class BabylonJSController {
         if (this.#scene !== null) {
             this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
         }
+        this.#canvasResizeObserver?.disconnect();
+        this.#canvasResizeObserver = null;
+        this.#detachAnimationChangedListener();
     }
 
     /**
@@ -1058,11 +1267,84 @@ export default class BabylonJSController {
         if (!this.#engine) {
             return;
         }
+        if (this.#hdrTexture) {
+            this.#hdrTexture.dispose();
+            this.#hdrTexture = null;
+        }
         this.#engine.dispose();
         this.#engine = this.#scene = this.#camera = null;
         this.#hemiLight = this.#dirLight = this.#cameraLight = null;
     }
 
+    /**
+     * Handles animation state events emitted by `OpeningAnimation` instances.
+     * Routes opening/closing states to continuous rendering and all other states
+     * (paused/opened/closed) to a short final render burst.
+     * @private
+     * @param {CustomEvent} event - Event carrying animation state in `event.detail.state`.
+     * @returns {void}
+     */
+    #onAnimationGroupChanged(event) {
+        const state = event?.detail?.state;
+        if (state === undefined) {
+            return;
+        }
+
+        if (state === OpeningAnimation.states.opening || state === OpeningAnimation.states.closing) {
+            this.#onAnimationGroupPlay();
+        } else {
+            this.#onAnimationGroupStop();
+        }
+    }
+
+    /**
+     * Marks animation playback as active and requests short continuous rendering so animated transforms remain smooth while state is changing.
+     * @private
+     * @returns {void}
+     */
+    #onAnimationGroupPlay() {
+        this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.animationMs });
+    }
+
+    /**
+     * Handles animation stop/pause/end transitions by requesting a final render burst.
+     * @private
+     * @returns {void}
+     */
+    #onAnimationGroupStop() {
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#renderConfig.burstFramesEnhanced : this.#renderConfig.burstFramesBase;
+        this.#requestRender({ frames: frames });
+    }
+
+    /**
+     * Attaches the `prefviewer-animation-changed` listener to the nearest `pref-viewer-3d` host.
+     * Removes any previous registration first to avoid duplicate callbacks across reload cycles.
+     * @private
+     * @returns {boolean} True when the listener is attached, false when no host is available.
+     */
+    #attachAnimationChangedListener() {
+        this.#getPrefViewer3DComponent();
+        if (!this.#prefViewer3D) {
+            return false;
+        }
+        this.#detachAnimationChangedListener();
+        this.#prefViewer3D.addEventListener("prefviewer-animation-changed", this.#handlers.onAnimationGroupChanged);
+        return true;
+    }
+
+    /**
+     * Detaches the `prefviewer-animation-changed` listener from the cached `pref-viewer-3d` host.
+     * @private
+     * @returns {boolean} True when a host exists and the listener removal was attempted, false otherwise.
+     */
+    #detachAnimationChangedListener() {
+        if (!this.#prefViewer3D) {
+            return false;
+        }
+        this.#prefViewer3D.removeEventListener("prefviewer-animation-changed", this.#handlers.onAnimationGroupChanged);
+        return true;
+    }
+
     /**
      * Handles keyup events on the Babylon.js canvas for triggering model and scene downloads.
      * @private
@@ -1090,11 +1372,12 @@ export default class BabylonJSController {
      * @returns {void|false} Returns false if there is no active camera; otherwise, void.
      */
     #onMouseWheel(event, pickInfo) {
+        event.preventDefault();
         const camera = this.#scene?.activeCamera;
         if (!camera) {
             return false;
         }
-        if (!camera.metadata?.locked) {            
+        if (!camera.metadata?.locked) {
             if (camera instanceof ArcRotateCamera) {
                 camera.wheelPrecision = camera.wheelPrecision || 3.0;
                 camera.inertialRadiusOffset -= event.deltaY * camera.wheelPrecision * 0.001;
@@ -1107,8 +1390,8 @@ export default class BabylonJSController {
                 const movementVector = direction.scale(zoomSpeed);
                 camera.position = camera.position.add(movementVector);
             }
+            this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
         }
-        event.preventDefault();
     }
 
     /**
@@ -1136,9 +1419,54 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onPointerMove(event, pickInfo) {
+        const camera = this.#scene?.activeCamera;
+        if (camera && !camera.metadata?.locked) {
+            this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+        }
         if (this.#babylonJSAnimationController) {
-            this.#babylonJSAnimationController.highlightMeshes(pickInfo);
+            const pickedMeshId = pickInfo?.pickedMesh?.id || null;
+            if (this.#lastPickedMeshId !== pickedMeshId) {
+                const highlightResult = this.#babylonJSAnimationController.highlightMeshes(pickInfo);
+                if (highlightResult.changed) {
+                    this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+                }
+            }
+        }
+    }
+
+    /**
+     * Handles pointer events observed on the Babylon.js scene.
+     * @private
+     * @param {PointerInfo} info - The pointer event information from Babylon.js.
+     * @returns {void}
+     */
+    #onPointerObservable(info) {
+        const pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
+        const pickedMeshId = pickInfo?.pickedMesh?.id || null;
+
+        if (info.type === PointerEventTypes.POINTERMOVE) {
+            this.#onPointerMove(info.event, pickInfo);
+        } else if (info.type === PointerEventTypes.POINTERUP) {
+            this.#onPointerUp(info.event, pickInfo);
+        } else if (info.type === PointerEventTypes.POINTERWHEEL) {
+            this.#onMouseWheel(info.event, pickInfo);
         }
+        this.#lastPickedMeshId = pickedMeshId;
+    }
+
+    /**
+     * Handles canvas resize notifications.
+     * Resizes the Babylon engine and requests a short on-demand render burst so camera-dependent
+     * buffers and post-process pipelines are redrawn at the new viewport size.
+     * @private
+     * @returns {void}
+     */
+    #onResize() {
+        if (!this.#engine) {
+            return;
+        }
+        this.#engine.resize();
+        this.#requestRender({ frames: this.#renderConfig.burstFramesBase, continuousMs: this.#renderConfig.interactionMs });
     }
 
     /**
@@ -1180,7 +1508,7 @@ export default class BabylonJSController {
                 .forEach((mesh) => {
                     mesh.material = material;
                     someSetted = true;
-                })
+                }),
         );
 
         if (someSetted) {
@@ -1275,6 +1603,9 @@ export default class BabylonJSController {
      * Marks the IBL state as successful, recreates lights so the new environment takes effect, and reports whether anything changed.
      * @private
      * @returns {boolean} True when lights were refreshed due to pending IBL changes, otherwise false.
+     * @description
+     * Delegates to `#createLights()`, which executes the full IBL URL-to-texture lifecycle:
+     * `cachedUrl -> HDRCubeTexture -> #hdrTexture clone -> consumeCachedUrl(true)`.
      */
     async #setOptions_IBL() {
         return await this.#createLights();
@@ -1291,34 +1622,47 @@ export default class BabylonJSController {
     }
 
     /**
-     * Caches and retrieves the parent custom element "PREF-VIEWER-3D" for efficient access.
+     * Resolves and caches the closest `pref-viewer-3d` host associated with the rendering canvas.
      * @private
      * @returns {void}
      */
     #getPrefViewer3DComponent() {
-        if (this.#prefViewer3D === undefined) {
-            const grandParentElement = this.#canvas.parentElement.parentElement;
-            this.#prefViewer3D = grandParentElement && grandParentElement.nodeName === "PREF-VIEWER-3D" ? grandParentElement : null;
+        if (this.#prefViewer3D !== undefined) {
+            return;
+        }
+
+        let prefViewer3D = this.#canvas?.closest?.("pref-viewer-3d") || undefined;
+        if (!prefViewer3D) {
+            const host = this.#canvas?.getRootNode?.()?.host;
+            prefViewer3D = host?.nodeName === "PREF-VIEWER-3D" ? host : undefined;
         }
+
+        this.#prefViewer3D = prefViewer3D;
     }
 
     /**
-     * Caches and retrieves the parent custom element "PREF-VIEWER" for efficient access.
+     * Resolves and caches the closest `pref-viewer` host associated with `#prefViewer3D`.
      * @private
      * @returns {void}
      */
     #getPrefViewerComponent() {
-        if (this.#prefViewer === undefined) {
-            if (this.#prefViewer3D === undefined) {
-                this.#getPrefViewer3DComponent();
-            }
-            if (!this.#prefViewer3D) {
-                this.#prefViewer = null;
-                return;
-            }
-            const rootNode = this.#prefViewer3D ? this.#prefViewer3D.getRootNode().host : null;
-            this.#prefViewer = rootNode && rootNode.nodeName === "PREF-VIEWER" ? rootNode : null;
+        if (this.#prefViewer !== undefined) {
+            return;
         }
+
+        this.#getPrefViewer3DComponent();
+        if (this.#prefViewer3D === undefined) {
+            this.#prefViewer = undefined;
+            return;
+        }
+
+        let prefViewer = this.#prefViewer3D.closest?.("pref-viewer") || undefined;
+        if (!prefViewer) {
+            const host = this.#prefViewer3D.getRootNode?.()?.host;
+            prefViewer = host?.nodeName === "PREF-VIEWER" ? host : undefined;
+        }
+
+        this.#prefViewer = prefViewer;
     }
 
     /**
@@ -1467,7 +1811,10 @@ export default class BabylonJSController {
      * @returns {void}
      */
     async #stopRender() {
-        this.#engine.stopRenderLoop(this.#handlers.renderLoop);
+        this.#stopEngineRenderLoop();
+        this.#renderState.dirtyFrames = 0;
+        this.#renderState.continuousUntil = 0;
+        this.#renderState.lastRenderAt = 0;
         await this.#unloadCameraDependentEffects();
     }
     /**
@@ -1478,9 +1825,9 @@ export default class BabylonJSController {
      */
     async #startRender() {
         await this.#loadCameraDependentEffects();
-        this.#scene.executeWhenReady(() => {
-            this.#engine.runRenderLoop(this.#handlers.renderLoop);
-        });
+        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 });
     }
 
     /**
@@ -1500,7 +1847,6 @@ export default class BabylonJSController {
      *    `LoadAssetContainerAsync`, returning the tuple so the caller can decide how to attach it to the scene.
      */
     async #loadAssetContainer(container, force = false) {
-
         if (container?.state?.update?.storage === undefined || container?.state?.size === undefined || container?.state?.timeStamp === undefined) {
             return [container, false];
         }
@@ -1546,6 +1892,8 @@ export default class BabylonJSController {
             return [container, assetContainer];
         } catch (error) {
             return [container, assetContainer];
+        } finally {
+            this.#gltfResolver.revokeObjectURLs(sourceData.objectURLs);
         }
     }
 
@@ -1559,6 +1907,7 @@ export default class BabylonJSController {
      * Returns an object with success status and error details.
      */
     async #loadContainers() {
+        this.#detachAnimationChangedListener();
         await this.#stopRender();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
@@ -1615,6 +1964,9 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
+                if (this.#babylonJSAnimationController?.hasAnimations?.()) {
+                    this.#attachAnimationChangedListener();
+                }
                 await this.#startRender();
             });
         return detail;
@@ -1874,10 +2226,10 @@ export default class BabylonJSController {
         this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false });
         this.#engine.disableUniformBuffers = true;
         this.#scene = new Scene(this.#engine);
-        
+
         // Activate the rendering of geometry data into a G-buffer, essential for advanced effects like deferred shading,
-        // SSAO, and Velocity-Texture-Animation (VAT), allowing for complex post-processing by separating rendering into 
-        // different buffers (depth, normals, velocity) for later use in shaders. 
+        // SSAO, and Velocity-Texture-Animation (VAT), allowing for complex post-processing by separating rendering into
+        // different buffers (depth, normals, velocity) for later use in shaders.
         const geometryBufferRenderer = this.#scene.enableGeometryBufferRenderer();
         if (geometryBufferRenderer) {
             geometryBufferRenderer.enableScreenspaceDepth = true;
@@ -1894,12 +2246,14 @@ export default class BabylonJSController {
         this.#scene.imageProcessingConfiguration.vignetteEnabled = false;
         this.#scene.imageProcessingConfiguration.colorCurvesEnabled = false;
 
+        // Skip the built-in pointer picking logic since the controller implements its own optimized raycasting for interaction.
+        this.#scene.skipPointerMovePicking = true;
+        this.#scene.skipPointerDownPicking = true;
+        this.#scene.skipPointerUpPicking = true;
+
         this.#createCamera();
         this.#enableInteraction();
         await this.#createXRExperience();
-        this.#startRender();
-        this.#canvasResizeObserver = new ResizeObserver(() => this.#engine && this.#engine.resize());
-        this.#canvasResizeObserver.observe(this.#canvas);
     }
 
     /**
@@ -1909,11 +2263,11 @@ export default class BabylonJSController {
      * @returns {void}
      */
     disable() {
-        this.#canvasResizeObserver.disconnect();
         this.#disableInteraction();
         this.#disposeAnimationController();
         this.#disposeXRExperience();
         this.#unloadCameraDependentEffects();
+        this.#stopEngineRenderLoop();
         this.#disposeEngine();
     }