@preference-sl/pref-viewer 2.16.2 → 2.17.0-beta.1

package/src/babylonjs-animation-controller.js

@@ -1,6 +1,7 @@
-import { AssetContainer, Color3, HighlightLayer, InstancedMesh, Mesh, PickingInfo, Quaternion, Scene, UtilityLayerRenderer, Vector3 } from "@babylonjs/core";
+import { AssetContainer, Color3, HighlightLayer, Mesh, PickingInfo, Scene } from "@babylonjs/core";
 import { PrefViewerStyleVariables } from "./styles.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
+import BabylonJSAnimationOverlayController from "./babylonjs-animation-overlay-controller.js";
 
 /**
  * BabylonJSAnimationController - Manages animation playback, highlighting, and interactive controls for animated nodes in Babylon.js scenes.
@@ -48,7 +49,7 @@ export default class BabylonJSAnimationController {
     #useHighlightLayer = true;
     #lastHighlightedMeshId = null;
     #lastHighlightedNodeIds = [];
-    
+
     // Static property to store global highlight enabled state
     static #globalHighlightEnabled = true;
     static #instanceId = 0;
@@ -70,6 +71,7 @@ export default class BabylonJSAnimationController {
     /**
      * Detects and stores animatable objects and animated nodes in the scene.
      * @private
+     * @returns {void}
      */
     #initializeAnimations() {
         this.hideMenu(); // Clean up any existing menus
@@ -83,6 +85,7 @@ export default class BabylonJSAnimationController {
     /**
      * Collects the IDs of all nodes targeted by any animation group in the scene.
      * @private
+     * @returns {void}
      */
     #getAnimatedNodes() {
         this.#assetContainer.animationGroups.forEach((animationGroup) => {
@@ -103,6 +106,7 @@ export default class BabylonJSAnimationController {
      * @private
      * @description
      * Uses animation group names with the pattern "animation_open_<name>" and "animation_close_<name>".
+     * @returns {void}
      */
     #getOpeningAnimations() {
         const openings = {};
@@ -131,7 +135,7 @@ export default class BabylonJSAnimationController {
      * Finds the OpeningAnimation instance associated with a given node ID.
      * @private
      * @param {string} nodeId - The node identifier.
-     * @returns {OpeningAnimation|null} The matching OpeningAnimation instance or null.
+     * @returns {OpeningAnimation|undefined} The matching OpeningAnimation instance, or undefined when absent.
      */
     #getOpeningAnimationByNode(nodeId) {
         return this.#openingAnimations.find((openingAnimation) => openingAnimation.isAnimationForNode(nodeId));
@@ -172,163 +176,7 @@ export default class BabylonJSAnimationController {
      * - Removes overlay when mouse moves away from highlighted meshes
      */
     #addGroupOutlineOverlayForInstances(meshes) {
-        // Configuration
-        const OUTLINE_ENABLED = false; // Draw outline on individual meshes
-        const OUTLINE_COLOR = this.#highlightColor;
-        const OUTLINE_WIDTH = 1.5;
-        const OVERLAY_ENABLED = true; // Draw semi-transparent fill
-        const OVERLAY_COLOR = this.#highlightColor;
-        const OVERLAY_ALPHA = 0.25;
-        const RENDERING_GROUP_ID = 0; // MUST be > 0 to render on top of main scene
-
-        // Use UtilityLayerRenderer for rendering
-        const utilityLayer = new UtilityLayerRenderer(this.#scene, undefined, undefined);
-        const uScene = utilityLayer.utilityLayerScene;
-
-        // Cache map: baseMesh -> overlayBaseMesh to reuse for InstancedMeshes
-        const baseToOverlayBase = new Map();
-
-        // Pairs of { original mesh, overlay mesh } for tracking
-        const pairs = [];
-
-        /**
-         * Gets the base mesh from either a regular mesh or an InstancedMesh
-         * @param {Mesh} mesh - The mesh to check
-         * @returns {Mesh} The base mesh or the mesh itself
-         */
-        function getBaseMesh(mesh) {
-            return mesh instanceof InstancedMesh ? mesh.sourceMesh : mesh;
-        }
-
-        /**
-         * Creates or retrieves an overlay base mesh in the utility scene
-         * Reuses the same base for all instances of the same source mesh
-         * @param {Mesh} baseMesh - The base mesh to clone
-         * @returns {Mesh} The overlay base mesh
-         */
-        function ensureOverlayBase(baseMesh) {
-            let overlayBase = baseToOverlayBase.get(baseMesh);
-            if (overlayBase) {
-                return overlayBase;
-            }
-
-            // Clone the source mesh into the utility scene (deep clone materials/geometry)
-            overlayBase = baseMesh.clone(baseMesh.name + "_overlayBase", null, true, false);
-            overlayBase._scene = uScene;
-            overlayBase.isPickable = false;
-            overlayBase.setEnabled(true);
-
-            // Configure visual appearance for the overlay
-            overlayBase.renderOutline = OUTLINE_ENABLED; // Only draw outline if enabled
-            overlayBase.outlineColor = OUTLINE_COLOR;
-            overlayBase.outlineWidth = OUTLINE_WIDTH;
-            
-            // Overlay color and transparency (semi-transparent colored fill)
-            overlayBase.renderOverlay = OVERLAY_ENABLED;
-            overlayBase.overlayColor = OVERLAY_COLOR;
-            overlayBase.overlayAlpha = OVERLAY_ALPHA;
-            
-            overlayBase.visibility = 1;
-
-            // Ensure always-on-top rendering or not
-            overlayBase.renderingGroupId = RENDERING_GROUP_ID;
-
-            baseToOverlayBase.set(baseMesh, overlayBase);
-            return overlayBase;
-        }
-
-        // Create overlay meshes for each input mesh
-        meshes.forEach((mesh) => {
-            // Skip meshes without geometry
-            if (!mesh.geometry && !mesh.getChildMeshes) {
-                return;
-            }
-
-            const baseMesh = getBaseMesh(mesh);
-            const overlayBase = ensureOverlayBase(baseMesh);
-
-            let overlay;
-            if (mesh instanceof InstancedMesh) {
-                // For instances, create a new instance of the overlay base
-                overlay = overlayBase.createInstance(mesh.name + "_overlayInst");
-                overlay._scene = uScene;
-                overlay.isPickable = false;
-            } else {
-                // For regular meshes, use the overlay base directly (avoids double cloning)
-                overlay = overlayBase;
-            }
-
-            // Remove parent to allow independent world matrix control
-            overlay.parent = null;
-            overlay.renderingGroupId = RENDERING_GROUP_ID;
-
-            pairs.push({ original: mesh, overlay });
-        });
-
-        // Sync world matrix transformations
-        const pos = new Vector3();
-        const scl = new Vector3();
-        const rot = new Quaternion();
-
-        // Track all observers for cleanup
-        const observers = [];
-
-        // Subscribe to world matrix update events
-        // This is more efficient than updating every frame
-        pairs.forEach(({ original, overlay }) => {
-            // Skip if mesh has no geometry to sync
-            if (!original.getWorldMatrix) {
-                return;
-            }
-
-            // Initial sync: copy the current world matrix
-            original.computeWorldMatrix(true);
-            original.getWorldMatrix().decompose(scl, rot, pos);
-
-            overlay.position.copyFrom(pos);
-            overlay.scaling.copyFrom(scl);
-            overlay.rotationQuaternion = overlay.rotationQuaternion || new Quaternion();
-            overlay.rotationQuaternion.copyFrom(rot);
-            overlay.computeWorldMatrix(true);
-
-            // Subscribe to world matrix changes
-            // Only updates when the original mesh's transformation actually changes
-            const obs = original.onAfterWorldMatrixUpdateObservable?.add(() => {
-                original.getWorldMatrix().decompose(scl, rot, pos);
-
-                overlay.position.copyFrom(pos);
-                overlay.scaling.copyFrom(scl);
-                overlay.rotationQuaternion.copyFrom(rot);
-                overlay.computeWorldMatrix(true);
-            });
-
-            if (obs) {
-                observers.push({ mesh: original, observer: obs });
-            }
-        });
-
-        // Cleanup API
-        return {
-            dispose() {
-                // Remove world matrix update observers
-                observers.forEach(({ mesh, observer }) => {
-                    mesh.onAfterWorldMatrixUpdateObservable?.remove(observer);
-                });
-
-                // Dispose overlay instances and meshes
-                pairs.forEach(({ original, overlay }) => {
-                    overlay.dispose();
-                });
-
-                // Dispose overlay base meshes
-                baseToOverlayBase.forEach((overlayBase) => {
-                    overlayBase.dispose();
-                });
-
-                // Dispose utility layer scene/resources; without this each rebuild leaks GPU/JS resources.
-                utilityLayer.dispose();
-            },
-        };
+        return new BabylonJSAnimationOverlayController(this.#scene, meshes, this.#highlightColor);
     }
 
     /**
@@ -430,6 +278,7 @@ export default class BabylonJSAnimationController {
      * 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
+     * @returns {void}
      */
     dispose() {
         if (this.#highlightLayer) {
@@ -476,14 +325,14 @@ export default class BabylonJSAnimationController {
             }
             return { changed: false, highlighted: false };
         }
-        
+
         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) {
@@ -651,7 +500,7 @@ export default class BabylonJSAnimationController {
             this.hideMenu();
             return;
         }
-        
+
         const openingAnimations = [];
         nodeIds.forEach((nodeId) => {
             const openingAnimation = this.#getOpeningAnimationByNode(nodeId);

package/src/babylonjs-animation-opening-menu.js

@@ -117,11 +117,12 @@ export default class OpeningAnimationMenu {
      * Sets button appearance and attaches the callback for user interaction.
      * @private
      * @param {string} name - Button identifier.
-     * @param {string} imageURL - SVG image data URL for the button icon.
+     * @param {string} imageSVG - SVG markup for the button icon.
      * @param {boolean} enabled - Whether the button is enabled.
      * @param {boolean} active - Whether the button is visually active.
      * @param {boolean} visible - Whether the button is visible.
      * @param {function} callback - Callback to invoke on button click.
+     * @returns {void}
      */
     #addButton(name, imageSVG, enabled = true, active = false, visible = true, callback) {
         const stateClass = active ? "active" : enabled ? "enabled" : "disabled";
@@ -183,6 +184,7 @@ export default class OpeningAnimationMenu {
     /**
      * Creates all control buttons and sets their initial states.
      * @private
+     * @returns {void}
      */
     #createButtons() {
         const buttonsState = this.#getButtonsState();
@@ -198,6 +200,7 @@ export default class OpeningAnimationMenu {
     /**
      * Creates and configures the animation progress slider.
      * @private
+     * @returns {void}
      */
     #createSlider() {
         this.#slider = document.createElement("input");
@@ -216,6 +219,7 @@ export default class OpeningAnimationMenu {
     /**
      * Initializes and renders the menu UI, including buttons and slider.
      * @private
+     * @returns {void}
      */
     #createMenu() {
         this.#containerMain = document.createElement("div");
@@ -334,6 +338,7 @@ export default class OpeningAnimationMenu {
      * @param {boolean} enabled
      * @param {boolean} active
      * @param {boolean} visible
+     * @returns {void}
      */
     #setButtonState(name, enabled, active, visible = true) {
         const button = this.#getButtonByName(name);
@@ -350,6 +355,7 @@ export default class OpeningAnimationMenu {
     /**
      * Updates all loop control buttons according to current loop mode.
      * @private
+     * @returns {void}
      */
     #setLoopButtonsState() {
         const buttonsState = this.#getLoopButtonsState();
@@ -360,6 +366,7 @@ export default class OpeningAnimationMenu {
     /**
      * Updates all playback control buttons according to current animation state.
      * @private
+     * @returns {void}
      */
     #setPlayerButtonsState() {
         const buttonsState = this.#getPlayerButtonsState();

package/src/babylonjs-animation-opening.js

@@ -108,6 +108,11 @@ export default class OpeningAnimation {
         this.#goToClosed();
     }
 
+    /**
+     * Binds opening and closing completion handlers once for stable subscription and removal.
+     * @private
+     * @returns {void}
+     */
     #bindHandlers() {
         this.#handlers.onOpened = this.#onOpened.bind(this);
         this.#handlers.onClosed = this.#onClosed.bind(this);
@@ -118,6 +123,7 @@ export default class OpeningAnimation {
      * Collects node IDs affected by the opening and closing animation groups.
      * Populates the #nodes array with unique node identifiers.
      * @private
+     * @returns {void}
      */
     #getNodesFromAnimationGroups() {
         [this.#openAnimation, this.#closeAnimation].forEach((animationGroup) => {
@@ -132,6 +138,7 @@ export default class OpeningAnimation {
     /**
      * Handles the end of the opening animation group.
      * @private
+     * @returns {void}
      */
     #onOpened() {
         this.#goToOpened(true);
@@ -140,6 +147,7 @@ export default class OpeningAnimation {
     /**
      * Handles the end of the closing animation group.
      * @private
+     * @returns {void}
      */
     #onClosed() {
         this.#goToClosed(true);
@@ -149,6 +157,7 @@ export default class OpeningAnimation {
      * Moves the animation to the fully opened state, optionally looping to close.
      * @private
      * @param {boolean} useLoop - If true, starts closing animation after opening.
+     * @returns {void}
      */
     #goToOpened(useLoop = false) {
         this.#lastPausedFrame = this.#endFrame;
@@ -178,6 +187,7 @@ export default class OpeningAnimation {
      * Moves the animation to the fully closed state, optionally looping to open.
      * @private
      * @param {boolean} useLoop - If true, starts opening animation after closing.
+     * @returns {void}
      */
     #goToClosed(useLoop = false) {
         this.#lastPausedFrame = this.#startFrame;
@@ -207,6 +217,7 @@ export default class OpeningAnimation {
      * Moves the animation to a specific frame and pauses.
      * @private
      * @param {number} frame - The frame to go to and pause.
+     * @returns {void}
      */
     #goToFrameAndPause(frame) {
         if (!frame) {
@@ -350,6 +361,7 @@ export default class OpeningAnimation {
     /**
      * Updates the slider value in the animation control menu to match the current progress.
      * @private
+     * @returns {void}
      */
     #updateControlsSlider() {
         if (!this.isControlsVisible()) {
@@ -362,6 +374,7 @@ export default class OpeningAnimation {
      * 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
+     * @returns {void}
      */
     #updateControls() {
         this.#notifyStateChange();
@@ -412,6 +425,7 @@ export default class OpeningAnimation {
     /**
      * Starts the opening animation.
      * @public
+     * @returns {void}
      */
     playOpen() {
         if (this.#state === OpeningAnimation.states.opening || this.#state === OpeningAnimation.states.opened) {
@@ -437,6 +451,7 @@ export default class OpeningAnimation {
     /**
      * Starts the closing animation.
      * @public
+     * @returns {void}
      */
     playClose() {
         if (this.#state === OpeningAnimation.states.closing || this.#state === OpeningAnimation.states.closed) {
@@ -462,6 +477,7 @@ export default class OpeningAnimation {
     /**
      * Pauses the current animation.
      * @public
+     * @returns {void}
      */
     pause() {
         if (this.#state === OpeningAnimation.states.opening) {
@@ -479,6 +495,7 @@ export default class OpeningAnimation {
     /**
      * Moves animation to the fully opened state.
      * @public
+     * @returns {void}
      */
     goToOpened() {
         this.#goToOpened(false);
@@ -487,6 +504,7 @@ export default class OpeningAnimation {
     /**
      * Moves animation to the fully closed state.
      * @public
+     * @returns {void}
      */
     goToClosed() {
         this.#goToClosed(false);
@@ -498,6 +516,7 @@ export default class OpeningAnimation {
      * @public
      * @param {HTMLCanvasElement} canvas - The canvas element for rendering.
      * @param {Array<OpeningAnimation>} openingAnimations - Array of OpeningAnimation instances to manage.
+     * @returns {void}
      */
     showControls(canvas, openingAnimations = []) {
         const controlCallbacks = {
@@ -562,6 +581,7 @@ export default class OpeningAnimation {
     /**
      * Hides the animation control menu and removes observers.
      * @public
+     * @returns {void}
      */
     hideControls() {
         if (!this.isControlsVisible()) {
@@ -590,7 +610,7 @@ export default class OpeningAnimation {
     /**
      * Returns the current animation state.
      * @public
-     * @returns {number}
+     * @returns {number} 0 paused, 1 closed, 2 opened, 3 opening or 4 closing.
      */
     get state() {
         return this.#state;

package/src/babylonjs-animation-overlay-controller.js

@@ -0,0 +1,145 @@
+import { InstancedMesh, Mesh, Quaternion, UtilityLayerRenderer, Vector3 } from "@babylonjs/core";
+
+/**
+ * Owns one animated-mesh overlay group, its utility scene and transform observers.
+ * Groups retain independent caches and release only their own rendering resources.
+ * @class BabylonJSAnimationOverlayController
+ */
+export default class BabylonJSAnimationOverlayController {
+    #utilityLayer;
+    #color;
+    #baseToOverlayBase = new Map();
+    #pairs = [];
+    #observers = [];
+    #position = new Vector3();
+    #scale = new Vector3();
+    #rotation = new Quaternion();
+    #disposed = false;
+
+    /**
+     * Creates presentation meshes and follows their original world transforms.
+     * @public
+     * @param {import("@babylonjs/core").Scene} scene - Host scene used by the utility renderer.
+     * @param {Array<import("@babylonjs/core").AbstractMesh>} meshes - Original meshes to highlight.
+     * @param {import("@babylonjs/core").Color3} color - Highlight color for the group.
+     */
+    constructor(scene, meshes, color) {
+        this.#color = color;
+        this.#utilityLayer = new UtilityLayerRenderer(scene, undefined, undefined);
+        for (const mesh of meshes) {
+            this.#createOverlay(mesh);
+        }
+        for (const pair of this.#pairs) {
+            if (!pair.original.getWorldMatrix) {
+                continue;
+            }
+            pair.original.computeWorldMatrix(true);
+            this.#syncPair(pair);
+            const observer = pair.original.onAfterWorldMatrixUpdateObservable?.add(() => this.#syncPair(pair));
+            if (observer) {
+                this.#observers.push({ mesh: pair.original, observer });
+            }
+        }
+    }
+
+    /**
+     * Resolves the source geometry mesh for an instance or returns a regular mesh unchanged.
+     * @private
+     * @static
+     * @param {import("@babylonjs/core").AbstractMesh} mesh - Original mesh.
+     * @returns {import("@babylonjs/core").Mesh} Mesh supplying the overlay geometry.
+     */
+    static #getBaseMesh(mesh) {
+        return mesh instanceof InstancedMesh ? mesh.sourceMesh : mesh;
+    }
+
+    /**
+     * Creates or reuses the group's presentation base for a source mesh.
+     * @private
+     * @param {import("@babylonjs/core").Mesh} baseMesh - Source mesh to clone.
+     * @returns {import("@babylonjs/core").Mesh} Cached overlay base.
+     */
+    #ensureOverlayBase(baseMesh) {
+        let overlayBase = this.#baseToOverlayBase.get(baseMesh);
+        if (overlayBase) {
+            return overlayBase;
+        }
+        // Register the clone in its owning scene from creation; changing _scene later
+        // leaves Babylon's node and root-node registries in the original scene.
+        overlayBase = new Mesh(baseMesh.name + "_overlayBase", this.#utilityLayer.utilityLayerScene, null, baseMesh, true, false);
+        overlayBase.isPickable = false;
+        overlayBase.isVisible = false;
+        overlayBase.setEnabled(true);
+        overlayBase.renderOutline = false;
+        overlayBase.outlineColor = this.#color;
+        overlayBase.outlineWidth = 1.5;
+        overlayBase.renderOverlay = true;
+        overlayBase.overlayColor = this.#color;
+        overlayBase.overlayAlpha = 0.25;
+        overlayBase.visibility = 1;
+        overlayBase.renderingGroupId = 0;
+        this.#baseToOverlayBase.set(baseMesh, overlayBase);
+        return overlayBase;
+    }
+
+    /**
+     * Adds a presentation mesh or an instance of a cached presentation base.
+     * @private
+     * @param {import("@babylonjs/core").AbstractMesh} mesh - Original mesh to present.
+     * @returns {void}
+     */
+    #createOverlay(mesh) {
+        if (!mesh.geometry && !mesh.getChildMeshes) {
+            return;
+        }
+        const baseMesh = BabylonJSAnimationOverlayController.#getBaseMesh(mesh);
+        const overlayBase = this.#ensureOverlayBase(baseMesh);
+        const overlay = mesh instanceof InstancedMesh ? overlayBase.createInstance(mesh.name + "_overlayInst") : overlayBase;
+        if (mesh instanceof InstancedMesh) {
+            overlay.isPickable = false;
+        } else {
+            overlay.isVisible = true;
+        }
+        overlay.parent = null;
+        overlay.renderingGroupId = 0;
+        this.#pairs.push({ original: mesh, overlay });
+    }
+
+    /**
+     * Copies an original world transform to its overlay using reusable group-local scratch vectors.
+     * @private
+     * @param {{original:object,overlay:object}} pair - Original and presentation mesh pair.
+     * @returns {void}
+     */
+    #syncPair(pair) {
+        pair.original.getWorldMatrix().decompose(this.#scale, this.#rotation, this.#position);
+        pair.overlay.position.copyFrom(this.#position);
+        pair.overlay.scaling.copyFrom(this.#scale);
+        pair.overlay.rotationQuaternion = pair.overlay.rotationQuaternion || new Quaternion();
+        pair.overlay.rotationQuaternion.copyFrom(this.#rotation);
+        pair.overlay.computeWorldMatrix(true);
+    }
+
+    /**
+     * Removes transform observers and disposes each owned mesh and the utility renderer once.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        for (const { mesh, observer } of this.#observers) {
+            mesh.onAfterWorldMatrixUpdateObservable?.remove(observer);
+        }
+        const overlays = new Set([...this.#pairs.map(pair => pair.overlay), ...this.#baseToOverlayBase.values()]);
+        for (const overlay of overlays) {
+            overlay.dispose();
+        }
+        this.#utilityLayer.dispose();
+        this.#observers.length = 0;
+        this.#pairs.length = 0;
+        this.#baseToOverlayBase.clear();
+    }
+}