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

package/README.md

@@ -274,6 +274,8 @@ Rapid selections retarget the transition from the displayed pose. Canvas pointer
 
 The default orbital camera starts on the **Inner (+Z)** side before the ViewCube is created, so the loading indicator does not first show Outer and then switch to Inner when model framing completes. The initial fit uses the same model bounds and projection-aware calculation as the ViewCube, with the shared framing factor (`BabylonJSController.config.camera.fitMarginFactor`) of 0.15. The resulting fit matches a cube destination for the same orientation, projection and canvas dimensions; the initial orientation is exact Inner, with no elevation, so selecting Inner immediately after loading preserves the view. The initial fit preserves its orbit angles; later model reloads preserve the user's current orientation. Explicitly selected cameras from the model or environment retain their authored view, which may differ from Inner.
 
+Camera selection through `options.camera` uses `null` for the interactive default camera. A named camera such as `"Inner"` is resolved from the model first, then the environment, and is locked by default. If that name is absent from both assets, the viewer activates its default camera with `locked = false` and reconnects canvas controls, even after a previously locked imported camera. A missing name does not retain the previous imported view. Omitting `options.camera` preserves the current selection.
+
 The shared internal setting `BabylonJSController.config.camera.fitMarginFactor` accepts finite values from **0 to 0.5, inclusive**. It reserves a total fraction of the viewport along the limiting axis; the model's projected bounding envelope can occupy `1 - fitMarginFactor` of that axis. It is applied when automatic or ViewCube framing runs, rather than continuously changing the current zoom.
 
 | fitMarginFactor | Space available for the model | Margin at each opposing edge of the limiting axis |
@@ -319,19 +321,19 @@ These are sampled ray checks, not continuous volume collision. Small surfaces be
 | --- | --- |
 | `showModel()` / `hideModel()` | Shows or hides the loaded model. |
 | `showScene()` / `hideScene()` | Shows or hides the loaded scene/environment. |
-| `syncVisibility(name, isVisible)` | Synchronizes `model` or `scene` visibility with the corresponding reflected attribute. |
 | `zoomCenter()` | Centers the 2D drawing view. |
 | `zoomExtentsAll()` | Fits all 2D drawing content in view. |
 | `zoomIn()` / `zoomOut()` | Controls 2D drawing zoom. |
-| `focusModel()` | Moves focus to the current model interaction target when available. |
+
+These zoom methods operate only in 2D mode. In 3D, use canvas navigation and the ViewCube to orient and refit the model. Switching modes retains the semantic selection snapshot.
 
 ### Semantic selection and turnable state
 
 | Method | Description |
 | --- | --- |
-| `setSelectableElements(elements)` | Defines and renders selectable SVG ids in yellow (`#FFFF00`, opacity `0.5`). Accepts strings or objects with `id`/`Id`. |
-| `setSelectedElements(elements)` | Defines and renders selected highlights in red (`#FF0000`, opacity `0.5`). Accepts strings or objects with `id`/`Id` and optional `highlights`/`Highlights`. |
-| `applySelectionState(state)` | Applies selectable and selected state to the semantic snapshot and 2D drawing in one call. Accepts `selectableIds`/`selectables` and `selectedItems`/`selectedIds`/`selected`; state supplied before a drawing is reapplied after load. |
+| `setSelectableElements(elements)` | Defines and renders selectable 2D/3D ids in yellow (`#FFFF00`, opacity `0.5`). Accepts strings or objects with `id`/`Id`. |
+| `setSelectedElements(elements)` | Defines and renders selected 2D/3D highlights in red (`#FF0000`, opacity `0.5`). Accepts strings or objects with `id`/`Id` and optional `highlights`/`Highlights`. |
+| `applySelectionState(state)` | Applies selectable and selected state to the semantic snapshot and both renderers in one call. Accepts `selectableIds`/`selectables` and `selectedItems`/`selectedIds`/`selected`; state supplied before drawing or model load is reapplied after that renderer loads. |
 | `clearSelectedElements()` | Clears selected elements while preserving the selectable set. |
 | `clearSelectableElements()` | Clears selectable elements while preserving the selected set. |
 | `clearSelectionState()` | Clears all semantic selection state. |
@@ -344,16 +346,26 @@ These are sampled ray checks, not continuous volume collision. Small surfaces be
 | `toggleTurnable(options)` | Toggles semantic turnable state. |
 | `getTurnableState()` | Returns `{ running, speed, direction }`. |
 
-Selection colors are rendered through disposable SVG clones; the loaded base SVG and shared definitions are not modified. Selectable clones are inserted before selected clones so red selection remains visible above yellow availability. Reapplying state is idempotent, and replacing the drawing removes dynamic nodes and prior visual layers before the current semantic snapshot is rendered again.
+In 2D, selection colors are rendered through disposable SVG clones; the loaded base SVG and shared definitions are not modified. In 3D, model meshes use Babylon overlays without mutating shared materials; every mesh instance with the semantic id is updated independently. Selected ids and their highlights take red priority over yellow selectable state. Reapplying state is idempotent, and replacing a drawing or model reapplies the current semantic snapshot.
+
+3D model loading disables Babylon's automatic glTF mesh instancing so repeated geometry can have independent overlays while materials remain shared. Environment loading retains instancing. This can increase draw calls for models with many repeated parts. Clearing selection restores the original overlay properties.
+
+3D clicks report eligible crossed ids independently of the selectable set; the host decides which ids to select. Only a final `_primitiveN` suffix is removed, and hits are sorted by distance before duplicate ids are removed.
+
+The 3D click threshold defaults to 6 CSS pixels and is defined by the internal `BabylonJSController.config.pointerPicking.clickMaxDistancePx` setting. Movement beyond the threshold at any point cancels the click, including drags returning to their starting point. Cancelled pointers and multi-pointer gestures emit no click. Hidden, disabled, non-pickable meshes, groups and environment geometry are excluded.
+
+The turnable methods store and publish semantic state for host integration. They do not start a camera rotation or a render-loop animation. Hosts can read the snapshot through `getTurnableState()` or consume it in `pref-viewer-3d-turnable-changed`.
 
 ### Animation controls
 
 | Method | Description |
 | --- | --- |
 | `getAnimations()` | Returns available model animations with state, progress, loop, and affected node ids. |
-| `playAnimation(name, action)` | Controls a named animation. Supported actions are delegated to `BabylonJSAnimationController`. |
-| `setAnimationProgress(name, progress)` | Sets animation progress from `0` to `1`. |
-| `setAnimationLoop(name, loop)` | Enables or disables looping for a named animation. |
+| `playAnimation(name, action)` | Controls a named opening animation with `open`, `close`, `pause`, `goToOpened` or `goToClosed`. Returns whether the animation and action were accepted. |
+| `setAnimationProgress(name, progress)` | Seeks to normalized progress from `0` to `1` and pauses playback. Returns `false` when the animation is absent. |
+| `setAnimationLoop(name, loop)` | Enables or disables ping-pong looping for a named animation. Returns `false` when the animation is absent. |
+
+Opening animations are discovered from paired glTF animation groups named `animation_open_<name>` and `animation_close_<name>`. State values are `0` (paused), `1` (closed), `2` (opened), `3` (opening) and `4` (closing). Enable `options.render.showAnimationMenu` to create the animation controller. Disabling that setting releases the controller: `getAnimations()` returns an empty array and imperative animation actions return `false`. A controller that is enabled can still receive imperative actions while its controls are closed.
 
 ### Dialogs and downloads
 
@@ -398,18 +410,18 @@ These setters are convenience bridges for framework bindings and property-based
 
 ## Events
 
-The component emits custom events so host applications can integrate loading indicators, error states, and viewer controls. Public event payloads do not include `source`. Only root-level events without an explicit 2D/3D scope include `detail.mode`, and that value is always the current `<pref-viewer>` mode (`"2d"` or `"3d"`).
+The component emits custom events so host applications can integrate loading indicators, error states, and viewer controls. Root-dispatched lifecycle, selection-state and viewport events include `detail.timestamp` in Unix milliseconds. Generic root events also include `detail.mode`, which is always the current `<pref-viewer>` mode (`"2d"` or `"3d"`); scoped 2D/3D and legacy `drawing-*`/`scene-*` events omit it. `pref-viewer-element-click` is an exception: its detail remains exactly `{ ids: string[] }`, without mode or timestamp. Renderer events received directly from child components can have different metadata from their root forwarding.
 
 ### General Events
 
 | Event | Emitted by | Legacy alias | Description |
 | --- | --- | --- | --- |
-| `pref-viewer-initialized` | `<pref-viewer>` | None | The root component has been mounted and initialized. |
+| `pref-viewer-initialized` | `<pref-viewer>` | None | The root component is connected and ready to process queued work. Detail includes `isInitialized`, `mode` and `timestamp`; it does not mean assets have finished loading. |
 | `pref-viewer-loading` | `<pref-viewer>` | None | A 2D or 3D load operation has started. Includes `detail.mode` with the current root mode. |
 | `pref-viewer-loaded` | `<pref-viewer>` | None | A 2D or 3D load operation completed. Includes `detail.mode` with the current root mode. |
 | `pref-viewer-error` | `<pref-viewer>` | None | A 2D or 3D operation failed. Includes `detail.mode` with the current root mode. |
-| `pref-viewer-selection-state-changed` | `<pref-viewer>` | None | The semantic selection state changed. |
-| `pref-viewer-element-click` | `<pref-viewer>` | None | A semantic SVG element was clicked or forwarded by the host. Geometry without its own id resolves the nearest id-bearing ancestor inside the drawing. `detail` is exactly `{ ids: string[] }`; clicks are emitted independently of the current selectable set. |
+| `pref-viewer-selection-state-changed` | `<pref-viewer>` | None | The semantic selection state changed. Detail includes `selectableIds`, `selectedIds`, `selectedItems`, `mode` and `timestamp`. |
+| `pref-viewer-element-click` | `<pref-viewer>` | None | A semantic 2D or 3D element was clicked or forwarded by the host. In 2D, geometry without its own id resolves the nearest id-bearing ancestor. In 3D, a primary click that moves no more than 6 CSS pixels reports every crossed visible, enabled, pickable model mesh, nearest first, from `mesh.id`; only a final `_primitiveN` suffix is removed and duplicate ids are omitted. Empty/background clicks do not emit. `detail` is exactly `{ ids: string[] }`, independently of the current selectable set. |
 
 ### 3D Events
 
@@ -421,8 +433,8 @@ The component emits custom events so host applications can integrate loading ind
 | `pref-viewer-3d-options-applying` | `<pref-viewer-3d>` | `scene-setting-options` | 3D viewer options are being applied. |
 | `pref-viewer-3d-options-applied` | `<pref-viewer-3d>` | `scene-set-options` | 3D viewer options were applied. |
 | `pref-viewer-3d-render-settings-change-requested` | `<pref-viewer-menu-3d>` | None | The 3D settings menu requested render-setting changes. |
-| `pref-viewer-3d-animation-changed` | Opening animation controller | None | A model animation state changed. |
-| `pref-viewer-3d-turnable-changed` | `<pref-viewer>` | None | The semantic turnable state changed. |
+| `pref-viewer-3d-animation-changed` | `<pref-viewer-3d>` via its opening animation controller | None | An opening animation state, progress or loop changed. Detail is `{ name, state, progress, loop }`. The event bubbles across the shadow boundary. |
+| `pref-viewer-3d-turnable-changed` | `<pref-viewer>` | None | The semantic turnable state changed. Detail includes `state: { running, speed, direction }` and `timestamp`. |
 
 ### 2D Events
 
@@ -435,7 +447,7 @@ The component emits custom events so host applications can integrate loading ind
 
 ### Internal Listeners
 
-`<pref-viewer>` listens to `pref-viewer-2d-viewport-changed` from `<pref-viewer-2d>`, `pref-viewer-3d-loaded` and `pref-viewer-3d-error` from `<pref-viewer-3d>`, and `pref-viewer-3d-render-settings-change-requested` from `<pref-viewer-menu-3d>`. `BabylonJSController` listens to `pref-viewer-3d-animation-changed` from the nearest `<pref-viewer-3d>` host. The root also conditionally subscribes to the internal, non-bubbling `view-cube-layout` event while the cube is active in 3D. It carries measured layout dimensions for the render menu and is not a new public root event.
+`<pref-viewer>` listens to `pref-viewer-2d-viewport-changed` from `<pref-viewer-2d>`, `pref-viewer-3d-loaded` and `pref-viewer-3d-error` from `<pref-viewer-3d>`, and `pref-viewer-3d-render-settings-change-requested` from `<pref-viewer-menu-3d>`. Internal `pref-viewer-2d-element-click` and `pref-viewer-3d-element-click` events are intercepted and forwarded through the single public `pref-viewer-element-click` contract. `BabylonJSController` listens to `pref-viewer-3d-animation-changed` from the nearest `<pref-viewer-3d>` host. The root also conditionally subscribes to the internal, non-bubbling `view-cube-layout` event while the cube is active in 3D. It carries measured layout dimensions for the render menu and is not a new public root event.
 
 Example:
 
@@ -485,6 +497,8 @@ viewer.setOptions({
 
 Render settings are persisted in `localStorage` under the `pref-viewer/render-settings` key when changed through the runtime settings flow. The menu is always synchronized from the effective controller settings after changes from the menu, `setOptions`, or `loadConfig`.
 
+The showroom daylight background uses a shared linear HDR color calibrated with exposure and ACES tone mapping for the current light studio gray target, `#d9d9d9`, in a scene-less view. Both the static look and time-of-day cycle use this same daylight value; the cycle retains its dark night endpoint. Scene geometry can cover the background. The internal `BabylonJSController.config.look.showroom.backgroundDay` value is not a public background-color option and must be recalibrated if tone mapping or exposure changes.
+
 ## Runtime styles
 
 Runtime styles can be passed through the `styles` attribute, the `styles` property setter, `setStyles(styles)`, or `loadConfig({ styles })`.
@@ -540,6 +554,18 @@ npm start
 
 The playground is available from `playground/index.html` at `http://localhost:8080/` and serves the project through `http-server` after bundling the local source. Use it for manual ViewCube, wheel-zoom and modal checks with representative model/environment assets. The separate ViewCube test HTML/script and its generated fixture bundle have been removed; automated tests remain.
 
+### 3D selection implementation and maintenance
+
+`src/babylonjs-selection-controller.js` encapsulates semantic picking helpers as public static methods of `BabylonJSSelectionController`: `normalizeMeshId`, `isPrimaryClickGesture`, `isPickableModelMesh`, `getModelMeshSet` and `collectPickedMeshIds`. The Babylon controller and tests call these methods through the class. Instance methods retain selection state and manage reversible overlays. These internal implementation helpers do not change the `<pref-viewer>` public API.
+
+JavaScript classes, methods and named helper functions outside tests are documented with JSDoc, including parameters and return values where applicable. This also covers existing helpers and webpack configuration callbacks. Keep those comments and this README aligned with the current implementation. Edited code files use Windows CRLF line endings.
+
+Shared calculations live in the static `RenderMath` and `MaterialUtils` classes. `I18n` owns the shared locale and translation subscribers, with private lookup helpers and public static methods. These modules export their classes only; viewer components and tests call their static methods directly. Former named function/constant exports and utility reexports from `BabylonJSController` have been removed. These helpers are internal modules, not additional package-root API exports. `BabylonJSController` encapsulates resize application, metadata path parsing and debug serialization as private methods, passing scene mesh snapshots explicitly to material diagnostics.
+
+`BabylonJSAnimationOverlayController` owns one opening-highlight group: its utility scene, cached overlay bases, transformed presentation meshes and observers. It creates clones directly in the utility scene, hides geometry bases used only by instances, and releases only its own resources through an idempotent `dispose()`. These animation overlays remain separate from semantic 3D selection overlays. The temporary legacy storage module and opening-control callbacks retain their existing structure.
+
+Focused regressions for this work live in `tests/babylonjs-selection-controller.test.js`, `tests/babylonjs-animation-overlay-controller.test.js`, `tests/encapsulated-utilities.test.js`, `tests/pref-viewer-menu-3d.test.js`, `tests/babylonjs-controller-wheel.test.js` and `tests/pref-viewer.test.js`. They cover picking and repeated model parts, reversible overlays, root state synchronization, animation resource ownership, localization, menu playback and diagnostics. Use `npm test -- --run --maxWorkers=2` for a bounded full-suite run; validate both builds and actual rendering when changing overlays.
+
 ### Camera implementation and maintenance
 
 - `src/babylonjs-view-cube-controller.js`: dedicated `BabylonJSViewCubeController` for SVG regions, orientation/projection feedback, transitions and cleanup. It delegates model bounds and destination-fit calculations to BabylonJSCameraFraming. Cube-only helpers and constants remain private; region generation remains a public static utility. Its constructor JSDoc documents the host object and callbacks.
@@ -572,6 +598,8 @@ The following variables are defined in the root rule of `PrefViewerViewCubeStyle
 
 Both feedback colors default to `var(--pref-viewer-color-primary, ...)`, preserving supported runtime primary-color updates. Text size and spacing apply in the SVG coordinate system and scale with its viewport. Active-view borders remain transparent; hover borders remain fully opaque regardless of fill opacity. Geometry and input behavior remain owned by the controller.
 
+ViewCube listener registration and hover updates are private instance methods. Surface creation, region construction, hit-region lookup, extent interpolation and SVG projection are private static helpers; per-update projection values and interpolation progress are passed explicitly. The render menu also encapsulates hue-channel calculation and lighting playback as private methods. Playback uses one callback bound to the menu instance and cancels its scheduled frame on stop or disconnection.
+
 ## Package scripts
 
 | Script | Description |
@@ -607,11 +635,15 @@ export function ProductViewer() {
 - The component is a Web Component, so it can be used from plain HTML, React, Vue, Angular, or any framework that supports custom elements.
 - Give the element an explicit width and height. Babylon.js needs a measurable canvas container.
 - Use object-based JavaScript APIs for complex payloads. Attributes must be valid JSON strings.
+- Root load/configuration methods enqueue work and return `void` on accepted input, rather than a completion promise. Use the loading/loaded/error events for completion. Malformed JSON strings can throw synchronously.
+- `loadConfig({ forceReload: true })` bypasses 3D asset cache metadata checks. A supplied `timestamp` that differs from the last supplied timestamp also forces the 3D reload; repeating the same value does not. These controls apply to the 3D configuration flow, not SVG cache invalidation.
 - Remote assets must be reachable by the browser and must satisfy the expected CORS policy.
 - glTF files with external resources are resolved and cached by the viewer when possible.
 - Avoid repeatedly replacing large assets if only visibility, camera, lighting, render, or material options changed.
 - Use `pref-viewer-initialized` only as a component-readiness signal. If a host generates model data asynchronously, wait for the host data-ready signal before calling `loadConfig()`.
 - For PrefWeb integration, consume the webpack UMD build (`bundle-umd.js`) and prefer development UMD builds while debugging source maps.
+- Babylon's initial PBR BRDF preparation keeps demand rendering awake and waits at most two seconds, so a missing readiness signal does not indefinitely block a queued model load. `getDebugInfo()` provides camera, rendering and asset-readiness diagnostics.
+- Release versioning and npm publication run in Bitbucket Pipelines: `develop` publishes the `beta` tag and `main` publishes `latest`. Do not run the release scripts locally.
 
 ## License
 

package/index.d.ts

@@ -94,6 +94,7 @@ export interface PrefViewerSelectionInput {
 }
 
 export interface PrefViewerElementClickDetail {
+  /** Semantic 2D ids, or distance-ordered, deduplicated 3D mesh ids with final _primitiveN removed. */
   ids: string[];
 }
 
@@ -271,7 +272,7 @@ export declare class PrefViewer extends HTMLElement {
   zoomIn(): void;
   zoomOut(): void;
 
-  // ── Semantic selection ──
+  // ── Semantic selection synchronized to both 2D and 3D renderers ──
   setSelectableElements(elements?: PrefViewerElementDescriptor[]): PrefViewerSelectionState;
   setSelectedElements(elements?: Array<string | PrefViewerSelectionDescriptor>): PrefViewerSelectionState;
   applySelectionState(state?: PrefViewerSelectionInput): PrefViewerSelectionState;

package/package.json

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

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;