@preference-sl/pref-viewer 2.13.0-beta.2 → 2.13.0-beta.21

package/Readme.md

@@ -5,4 +5,4 @@ A Web Component for visualizing GLTF models using Babylon.js.
 ## Installation
 
 ```bash
-npm install @preference-sl/pref-viewer
+npm install @preference-sl/pref-viewer

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.13.0-beta.2",
+    "version": "2.13.0-beta.21",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -35,11 +35,11 @@
         "index.d.ts"
     ],
     "dependencies": {
-        "@babylonjs/core": "^8.47.0",
-        "@babylonjs/loaders": "^8.47.0",
-        "@babylonjs/serializers": "^8.47.0",
+        "@babylonjs/core": "^8.50.5",
+        "@babylonjs/loaders": "^8.50.5",
+        "@babylonjs/serializers": "^8.50.5",
         "@panzoom/panzoom": "^4.6.0",
-        "babylonjs-gltf2interface": "^8.47.0",
+        "babylonjs-gltf2interface": "^8.50.5",
         "buffer": "^6.0.3",
         "idb": "^8.0.3",
         "is-svg": "^6.1.0",

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 {
@@ -35,19 +45,18 @@ export default class BabylonJSAnimationController {
     #highlightColor = Color3.FromHexString(PrefViewerStyleVariables.colorPrimary);
     #highlightLayer = null;
     #overlayLayer = null;
-    #useHighlightLayer = false; // Set to true to use HighlightLayer (better performance) and false to use overlay meshes (UtilityLayerRenderer - always on top)
+    #useHighlightLayer = true; // 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.
      * @param {AssetContainer|Scene} assetContainer - The Babylon.js asset container or scene instance.
      */
     constructor(assetContainer) {
-        if (assetContainer instanceof AssetContainer || assetContainer instanceof Scene) {
-            this.#scene = assetContainer.scene ? assetContainer.scene : assetContainer;
-            this.#assetContainer = assetContainer;
-            this.#canvas = this.#scene._engine._renderingCanvas;
-        }
+        this.#scene = assetContainer.scene ? assetContainer.scene : assetContainer;
+        this.#assetContainer = assetContainer;
+        this.#canvas = this.#scene._engine._renderingCanvas;
         this.#initializeAnimations();
     }
 
@@ -128,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;
     }
 
     /**
@@ -163,7 +175,8 @@ export default class BabylonJSAnimationController {
         const RENDERING_GROUP_ID = 0; // MUST be > 0 to render on top of main scene
 
         // Use UtilityLayerRenderer for rendering
-        const uScene = UtilityLayerRenderer.DefaultKeepDepthUtilityLayer.utilityLayerScene;
+        const utilityLayer = new UtilityLayerRenderer(this.#scene, undefined, undefined);
+        const uScene = utilityLayer.utilityLayerScene;
 
         // Cache map: baseMesh -> overlayBaseMesh to reuse for InstancedMeshes
         const baseToOverlayBase = new Map();
@@ -304,67 +317,68 @@ export default class BabylonJSAnimationController {
                 baseToOverlayBase.forEach((overlayBase) => {
                     overlayBase.dispose();
                 });
+
+                // Dispose utility layer scene/resources; without this each rebuild leaks GPU/JS resources.
+                utilityLayer.dispose();
             },
         };
     }
 
     /**
-     * ---------------------------
-     * 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);
@@ -384,20 +398,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);
@@ -409,6 +409,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 };
     }
 
     /**
@@ -423,20 +516,26 @@ export default class BabylonJSAnimationController {
 
     /**
      * Displays the animation control menu for the animated node under the pointer.
+     * Hides the current menu when picking info is invalid or when no animated node is found.
+     * Prefers a currently started animation; otherwise falls back to the first available one.
      * @public
-     * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
+     * @param {PickingInfo|null|undefined} pickingInfo - Raycast info from pointer position.
+     * Can be null/undefined when caller intentionally skips picking.
+     * @returns {void}
      */
     showMenu(pickingInfo) {
-        if (!pickingInfo?.hit && !pickingInfo?.pickedMesh) {
+        const pickedMesh = pickingInfo?.pickedMesh;
+        if (!pickingInfo?.hit || !pickedMesh) {
+            this.hideMenu();
             return;
         }
 
-        this.hideMenu();
-
-        const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
+        const nodeIds = this.#getNodesAnimatedByMesh(pickedMesh);
         if (!nodeIds.length) {
+            this.hideMenu();
             return;
         }
+        
         const openingAnimations = [];
         nodeIds.forEach((nodeId) => {
             const openingAnimation = this.#getOpeningAnimationByNode(nodeId);
@@ -446,7 +545,19 @@ export default class BabylonJSAnimationController {
             openingAnimations.push(openingAnimation);
         });
 
+        if (!openingAnimations.length) {
+            this.hideMenu();
+            return;
+        }
+
         const startedAnimation = openingAnimations.find((animation) => animation.state !== OpeningAnimation.states.closed);
-        startedAnimation ? startedAnimation.showControls(this.#canvas, openingAnimations) : openingAnimations[0].showControls(this.#canvas, openingAnimations);
+        const animationToShow = startedAnimation ? startedAnimation : openingAnimations[0];
+
+        if (animationToShow.isControlsVisible()) {
+            return;
+        }
+
+        this.hideMenu();
+        animationToShow.showControls(this.#canvas, openingAnimations);
     }
 }

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;
         }