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

package/package.json

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

package/src/babylonjs-animation-controller.js

@@ -6,22 +6,32 @@ import OpeningAnimation from "./babylonjs-animation-opening.js";
  * BabylonJSAnimationController - Manages animation playback, highlighting, and interactive controls for animated nodes in Babylon.js scenes.
  *
  * Summary:
- *  This class detects, groups, and manages opening/closing animations for scene nodes, provides interactive highlighting of animated nodes and their meshes, and displays a menu for animation control. It is designed for integration with product configurators and interactive 3D applications using Babylon.js.
+ *  This class detects and groups opening/closing animations, manages hover highlighting for animated nodes,
+ *  exposes whether interactive animations are available, and coordinates the contextual animation menu.
  *
  * Key features:
  *  - Detects and groups opening/closing animations in the scene.
  *  - Tracks animated transformation nodes and their relationships to meshes.
+ *  - Exposes animation availability through `hasAnimations()`.
  *  - Highlights animated nodes and their child meshes on pointer hover.
+ *  - Avoids redundant highlight rebuilds using cached mesh/node IDs and order-insensitive node-id comparison.
+ *  - Reports highlight-state deltas from `highlightMeshes()` so callers can react efficiently.
  *  - Displays and disposes the animation control menu for animated nodes.
- *  - Provides public API for highlighting, showing the animation menu, and disposing resources.
+ *  - Provides public API for availability checks, highlighting, showing the animation menu, and disposing resources.
  *  - Cleans up all resources and observers to prevent memory leaks.
  *
  * Public Methods:
  *  - dispose(): Disposes all resources managed by the animation controller.
- *  - highlightMeshes(pickingInfo): Highlights meshes that are children of an animated node when hovered.
+ *  - hasAnimations(): Returns whether opening/closing animations are available.
+ *  - highlightMeshes(pickingInfo): Updates hover highlighting and returns `{ changed, highlighted }`.
  *  - hideMenu(): Hides and disposes the animation control menu if it exists.
  *  - showMenu(pickingInfo): Displays the animation control menu for the animated node under the pointer.
  *
+ * Private Methods (high level):
+ *  - #haveSameNodeIds(arr1, arr2): Compares hovered animated node sets ignoring order.
+ *  - #addHighlight(nodeIds): Applies highlighting with HighlightLayer or overlay meshes.
+ *  - #removeHighlight(): Clears current highlights and cached hover state.
+ *
  * @class
  */
 export default class BabylonJSAnimationController {
@@ -37,6 +47,7 @@ export default class BabylonJSAnimationController {
     #overlayLayer = null;
     #useHighlightLayer = false; // Set to true to use HighlightLayer (better performance) and false to use overlay meshes (UtilityLayerRenderer - always on top)
     #lastHighlightedMeshId = null; // Cache to avoid redundant highlight updates
+    #lastHighlightedNodeIds = []; // Cache to avoid redundant highlight updates
 
     /**
      * Creates a new BabylonJSAnimationController for a Babylon.js scene.
@@ -126,15 +137,18 @@ export default class BabylonJSAnimationController {
      * @returns {Array<string>} Array of animated node IDs associated with the mesh.
      */
     #getNodesAnimatedByMesh(mesh) {
-        let nodeId = [];
+        let nodeIds = [];
+        if (!mesh || !mesh.id) {
+            return nodeIds;
+        }
         let node = mesh;
         while (node.parent !== null) {
             node = node.parent;
-            if (this.#animatedNodes.includes(node.id) && !nodeId.includes(node.id)) {
-                nodeId.push(node.id);
+            if (this.#animatedNodes.includes(node.id) && !nodeIds.includes(node.id)) {
+                nodeIds.push(node.id);
             }
         }
-        return nodeId;
+        return nodeIds;
     }
 
     /**
@@ -308,62 +322,60 @@ export default class BabylonJSAnimationController {
     }
 
     /**
-     * ---------------------------
-     * Public methods
-     * ---------------------------
+     * Compares two node ID arrays and checks whether they contain the same values,
+     * regardless of element order.
+     * @private
+     * @param {string[]} arr1 - First node ID array.
+     * @param {string[]} arr2 - Second node ID array.
+     * @returns {boolean} True when both arrays contain the same node IDs; otherwise false.
      */
+    #haveSameNodeIds(arr1, arr2) {
+        if (arr1.length !== arr2.length) {
+            return false;
+        }
+        const sortedArr1 = [...arr1].sort();
+        const sortedArr2 = [...arr2].sort();
+        return sortedArr1.every((value, index) => value === sortedArr2[index]);
+    }
 
     /**
-     * Disposes all resources managed by the animation controller.
-     * Cleans up the highlight layer, animation menu, and internal animation/node lists.
-     * Should be called when the controller is no longer needed to prevent memory leaks.
-     * @public
+     * Clears the current highlight state from either HighlightLayer or overlay meshes.
+     * Also resets cached mesh/node tracking used to avoid redundant highlight updates.
+     * @private
+     * @returns {void}
      */
-    dispose() {
-        if (this.#highlightLayer) {
-            this.#highlightLayer.removeAllMeshes();
-            this.#highlightLayer.dispose();
-            this.#highlightLayer = null;
-        }
-        if (this.#overlayLayer) {
-            this.#overlayLayer.dispose();
-            this.#overlayLayer = null;
+    #removeHighlight() {
+        if (this.#useHighlightLayer) {
+            if (this.#highlightLayer) {
+                this.#highlightLayer.removeAllMeshes();
+            }
+        } else {
+            if (this.#overlayLayer) {
+                this.#overlayLayer.dispose();
+                this.#overlayLayer = null;
+            }
         }
-        this.hideMenu();
-        this.#animatedNodes = [];
-        this.#openingAnimations.forEach((openingAnimation) => openingAnimation.dispose());
-        this.#openingAnimations = [];
+        this.#lastHighlightedMeshId = null;
+        this.#lastHighlightedNodeIds = [];
     }
 
     /**
-     * Highlights meshes that are children of an animated node when hovered.
-     * @public
-     * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
+     * Applies highlighting for all meshes belonging to the provided animated node IDs.
+     * Depending on configuration, it uses Babylon's HighlightLayer or overlay meshes rendered
+     * in a utility layer for always-on-top outlines/fills.
+     * @private
+     * @param {string[]} nodeIds - Animated node IDs whose child meshes should be highlighted.
+     * @returns {void}
      */
-    highlightMeshes(pickingInfo) {
-        // Check if we're hovering the same mesh to avoid recreating overlays/highlights
-        const pickedMeshId = pickingInfo?.pickedMesh?.id;
-        if (this.#lastHighlightedMeshId === pickedMeshId) {
-            return; // No need to update if hovering the same mesh
+    #addHighlight(nodeIds) {
+        this.#removeHighlight();
+        if (!nodeIds.length) {
+            return;
         }
-        this.#lastHighlightedMeshId = pickedMeshId;
-
         if (this.#useHighlightLayer) {
             if (!this.#highlightLayer) {
                 this.#highlightLayer = new HighlightLayer("hl_animations", this.#scene);
             }
-
-            this.#highlightLayer.removeAllMeshes();
-
-            if (!pickingInfo?.hit || !pickingInfo?.pickedMesh) {
-                return;
-            }
-
-            const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
-            if (!nodeIds.length) {
-                return;
-            }
-
             const transformNodes = [];
             nodeIds.forEach((nodeId) => {
                 const transformNode = this.#scene.getTransformNodeByID(nodeId);
@@ -383,20 +395,6 @@ export default class BabylonJSAnimationController {
                 }
             });
         } else {
-            if (this.#overlayLayer) {
-                this.#overlayLayer.dispose();
-                this.#overlayLayer = null;
-            }
-
-            if (!pickingInfo?.hit || !pickingInfo?.pickedMesh) {
-                return;
-            }
-
-            const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
-            if (!nodeIds.length) {
-                return;
-            }
-
             const meshes = [];
             nodeIds.forEach((nodeId) => {
                 const transformNode = this.#scene.getTransformNodeByID(nodeId);
@@ -408,6 +406,99 @@ export default class BabylonJSAnimationController {
 
             this.#overlayLayer = this.#addGroupOutlineOverlayForInstances(meshes);
         }
+        this.#lastHighlightedNodeIds = nodeIds;
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Disposes all resources managed by the animation controller.
+     * Cleans up the highlight layer, animation menu, and internal animation/node lists.
+     * Should be called when the controller is no longer needed to prevent memory leaks.
+     * @public
+     */
+    dispose() {
+        if (this.#highlightLayer) {
+            this.#highlightLayer.removeAllMeshes();
+            this.#highlightLayer.dispose();
+            this.#highlightLayer = null;
+        }
+        if (this.#overlayLayer) {
+            this.#overlayLayer.dispose();
+            this.#overlayLayer = null;
+        }
+        this.hideMenu();
+        this.#animatedNodes = [];
+        this.#openingAnimations.forEach((openingAnimation) => openingAnimation.dispose());
+        this.#openingAnimations = [];
+    }
+
+    /**
+     * Indicates whether the current asset container exposes at least one opening/closing animation pair.
+     * @public
+     * @returns {boolean} True when interactive opening animations are available; otherwise false.
+     */
+    hasAnimations() {
+        return this.#openingAnimations.length > 0;
+    }
+
+    /**
+     * Updates hover highlighting for meshes under animated nodes.
+     * Uses cached mesh/node state to avoid rebuilding highlight layers when the effective
+     * highlighted node set has not changed.
+     * @public
+     * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
+     * @returns {{changed:boolean, highlighted:boolean}}
+     * Returns whether highlight visuals changed in this call and whether any mesh remains highlighted.
+     */
+    highlightMeshes(pickingInfo) {
+        let changed = false;
+        let highlighted = false;
+
+        // Check if we're hovering the same mesh to avoid recreating overlays/highlights
+        const pickedMeshId = !pickingInfo?.hit || !pickingInfo?.pickedMesh?.id ? null : pickingInfo.pickedMesh.id;
+        const pickedMesh = pickingInfo?.pickedMesh ? pickingInfo.pickedMesh : null;
+        
+        if (this.#lastHighlightedMeshId === pickedMeshId) {
+            // No need to update if hovering the same mesh
+            if (this.#lastHighlightedMeshId !== null) {
+                changed = false;
+                highlighted = true;
+            } else {
+                changed = false;
+                highlighted = false;
+            }
+        } else {
+            const nodeIds = this.#getNodesAnimatedByMesh(pickedMesh);
+            if (!nodeIds.length) {
+                if (this.#lastHighlightedMeshId !== null) {
+                    this.#removeHighlight();
+                    changed = true;
+                    highlighted = false;
+                } else {
+                    changed = false;
+                    highlighted = false;
+                }
+            } else  {
+                if (this.#haveSameNodeIds(nodeIds, this.#lastHighlightedNodeIds)) {
+                    // No need to update if hovering a mesh under the same animated nodes
+                    changed = false;
+                    highlighted = true;
+                } else {
+                    // Hovering a different mesh or same mesh under different animated nodes - update highlight
+                    this.#addHighlight(nodeIds);
+                    changed = true;
+                    highlighted = true;
+                }
+                this.#lastHighlightedMeshId = pickedMeshId;
+            }
+        }
+
+        return { changed: changed, highlighted: highlighted };
     }
 
     /**

package/src/babylonjs-animation-opening.js

@@ -8,6 +8,7 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - Tracks animation state (paused, closed, opened, opening, closing).
  *  - Synchronizes animation progress and UI controls.
  *  - Handles loop mode and progress threshold logic.
+ *  - Dispatches `prefviewer-animation-update` events with animation state snapshots.
  *  - Provides methods for play, pause, go to opened/closed, and progress control.
  *  - Manages the animation control menu (OpeningAnimationMenu) and its callbacks.
  *
@@ -36,9 +37,11 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - #getCurrentFrame(): Gets the current frame based on state.
  *  - #getFrameFromProgress(progress): Calculates frame from progress value.
  *  - #getProgress(): Calculates progress (0-1) from current frame.
+ *  - #getPrefViewer3DComponent(): Resolves and caches the nearest `pref-viewer-3d` host element.
  *  - #checkProgress(progress): Applies threshold logic to progress.
+ *  - #notifyStateChange(): Emits `prefviewer-animation-update` with state/progress/loop metadata.
  *  - #updateControlsSlider(): Updates the slider in the control menu.
- *  - #updateControls(): Updates all controls in the menu.
+ *  - #updateControls(): Emits state updates and syncs controls when the menu is visible.
  */
 export default class OpeningAnimation {
     static states = {
@@ -54,6 +57,7 @@ export default class OpeningAnimation {
     #closeAnimation = null;
     #nodes = [];
     #menu = null;
+    #prefViewer3D = undefined; // Reference to parent custom elements for event dispatching
 
     #state = OpeningAnimation.states.closed;
     #lastPausedFrame = 0;
@@ -271,6 +275,29 @@ export default class OpeningAnimation {
         return progress;
     }
 
+    /**
+     * Resolves and caches the closest `pref-viewer-3d` host associated with the animation canvas.
+     * @private
+     * @returns {void}
+     */
+    #getPrefViewer3DComponent() {
+        if (this.#prefViewer3D !== undefined) {
+            return;
+        }
+        
+        const scene = this.#openAnimation?.getScene?.();
+        const engine = scene?.getEngine?.();
+        const canvas = engine?.getRenderingCanvas?.();
+
+        let prefViewer3D = canvas?.closest?.("pref-viewer-3d") || null;
+        if (!prefViewer3D) {
+            const host = canvas?.getRootNode?.()?.host;
+            prefViewer3D = host?.nodeName === "PREF-VIEWER-3D" ? host : null;
+        }
+
+        this.#prefViewer3D = prefViewer3D;
+    }
+
     /**
      * Applies threshold logic to the progress value to snap to 0 or 1 if near the ends.
      * Prevents floating point errors from leaving the animation in an in-between state.
@@ -287,6 +314,33 @@ export default class OpeningAnimation {
         return progress;
     }
 
+    /**
+     * Dispatches a `prefviewer-animation-update` CustomEvent from the nearest `pref-viewer-3d` host.
+     * The event bubbles and crosses shadow DOM boundaries, exposing the current animation snapshot
+     * (`name`, `state`, `progress`, and `loop`) in `event.detail`.
+     * @private
+     * @returns {boolean} True when the event was dispatched, false when no `pref-viewer-3d` host is available.
+     */
+    #notifyStateChange() {
+        this.#getPrefViewer3DComponent();
+        if (!this.#prefViewer3D) {
+            return false;
+        }
+
+        const customEventOptions = {
+            bubbles: true,
+            composed: true,
+            detail: {
+                name: this.name,
+                state: this.#state,
+                progress: this.#getProgress(),
+                loop: this.#loop,
+            },
+        };
+        this.#prefViewer3D.dispatchEvent(new CustomEvent("prefviewer-animation-changed", customEventOptions));
+        return true;
+    }
+
     /**
      * Updates the slider value in the animation control menu to match the current progress.
      * @private
@@ -299,10 +353,12 @@ export default class OpeningAnimation {
     }
 
     /**
-     * Updates all controls in the animation menu (buttons, slider) to reflect the current state and progress.
+     * Broadcasts the latest animation state and, when the menu is visible, syncs its controls
+     * (buttons and progress slider) with the current state/progress values.
      * @private
      */
     #updateControls() {
+        this.#notifyStateChange();
         if (!this.isControlsVisible()) {
             return;
         }

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";
 
 /**
@@ -63,7 +64,6 @@ import { translate } from "./localization/i18n.js";
  *    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
@@ -75,7 +75,7 @@ export default class BabylonJSController {
         iblEnabled: true,
         shadowsEnabled: false,
     };
-    
+
     // Canvas HTML element
     #canvas = null;
 
@@ -93,11 +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
 
@@ -110,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.
@@ -147,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);
     }
 
@@ -271,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;
+        }
     }
 
     /**
@@ -417,24 +599,20 @@ export default class BabylonJSController {
                 this.#scene.environmentTexture = null;
                 lightsChanged = true;
             }
-            if (this.#hdrTexture) {
-                this.#hdrTexture.dispose();
-                this.#hdrTexture = null;
-            }
 
             // Add a hemispheric light for basic ambient illumination
             if (!this.#hemiLight) {
                 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);
@@ -459,7 +637,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
@@ -499,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;
@@ -523,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;
@@ -533,7 +711,7 @@ export default class BabylonJSController {
                 ssaoPipeline._combinePostProcess.autoClear = false;
                 ssaoPipeline._combinePostProcess.samples = 1;
             }
-            
+
             this.#renderPipelines.ssao = ssaoPipeline;
             pipelineManager.update();
             return true;
@@ -559,7 +737,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
@@ -600,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
@@ -716,7 +894,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
@@ -751,13 +929,13 @@ export default class BabylonJSController {
      * @private
      * @returns {Promise<void|boolean>} Returns false if no environment texture is set; otherwise void.
      */
-    async #initializeIBLShadows() {      
+    async #initializeIBLShadows() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
-        
+
         if (!this.#scene || !this.#scene?.activeCamera || !this.#scene?.environmentTexture || !pipelineManager) {
             return false;
         }
-        
+
         if (!this.#scene.environmentTexture.isReady()) {
             const self = this;
             this.#scene.environmentTexture.onLoadObservable.addOnce(() => {
@@ -771,11 +949,11 @@ export default class BabylonJSController {
             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;
             }
@@ -793,7 +971,7 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (!supportedPipelines) {
             return false;
         }
@@ -816,7 +994,7 @@ export default class BabylonJSController {
         if (!iblShadowsPipeline) {
             return false;
         }
-       
+
         if (iblShadowsPipeline.isSupported) {
             // Disable all debug passes for performance
             const pipelineProps = {
@@ -835,7 +1013,7 @@ export default class BabylonJSController {
 
             meshesForCastingShadows.forEach((mesh) => iblShadowsPipeline.addShadowCastingMesh(mesh));
             materialsForReceivingShadows.forEach((material) => iblShadowsPipeline.addShadowReceivingMaterial(material));
-                 
+
             iblShadowsPipeline.updateSceneBounds();
             iblShadowsPipeline.toggleShadow(true);
             iblShadowsPipeline.updateVoxelization();
@@ -1002,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
@@ -1031,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);
+        }
     }
 
     /**
@@ -1045,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();
     }
 
     /**
@@ -1105,6 +1276,75 @@ export default class BabylonJSController {
         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
@@ -1132,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;
@@ -1149,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();
     }
 
     /**
@@ -1178,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 });
     }
 
     /**
@@ -1222,7 +1508,7 @@ export default class BabylonJSController {
                 .forEach((mesh) => {
                     mesh.material = material;
                     someSetted = true;
-                })
+                }),
         );
 
         if (someSetted) {
@@ -1336,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;
     }
 
     /**
@@ -1512,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();
     }
     /**
@@ -1523,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 });
     }
 
     /**
@@ -1545,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];
         }
@@ -1606,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 ?? {}) };
@@ -1662,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;
@@ -1921,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;
@@ -1941,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);
     }
 
     /**
@@ -1956,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();
     }