@preference-sl/pref-viewer 2.16.0-beta.9 → 2.16.1

package/src/pref-viewer-3d.js

@@ -10,14 +10,15 @@ import FileStorage from "./file-storage.js";
  *  - Encapsulates a Babylon.js-powered 3D viewer for displaying models, environments, and materials.
  *  - Manages internal state for containers (model, environment, materials) and options (camera, materials, IBL, render toggles).
  *  - Handles asset loading, configuration, and option updates (camera, materials, IBL) through attributes and public methods.
- *  - Exposes getters/setters for render settings so PrefViewerMenu3D or other UIs can persistently toggle AA/SSAO/IBL/shadows.
+ *  - Exposes getters/setters for render settings so PrefViewerMenu3D or other UIs can toggle AA/SSAO/IBL/shadows,
+ *    hover highlight, and time-of-day lighting.
  *  - Provides API for showing/hiding the viewer, model, and environment, and for downloading assets.
  *  - Emits custom events for loading, loaded, option-setting, and render-setting workflows.
  *
  * Usage:
  *  - Use as a custom HTML element: <pref-viewer-3d ...>
  *  - Configure via attributes (config, options, show-model, show-scene, visible).
- *  - Call getRenderSettings()/applyRenderSettings() to synchronize UI toggles with BabylonJSController persistence.
+ *  - Call getRenderSettings()/applyRenderSettings() to synchronize UI controls with BabylonJSController settings.
  *  - Control viewer state and assets via public methods.
  *
  * Observed Attributes:
@@ -30,12 +31,19 @@ import FileStorage from "./file-storage.js";
  *  - hide(): Hides the 3D viewer component.
  *  - load(config): Loads the provided configuration into the viewer.
  *  - setOptions(options): Sets viewer options such as camera, materials, and image-based lighting (IBL).
- *  - getRenderSettings(): Returns the current anti-aliasing, SSAO, IBL, and shadow flags.
- *  - applyRenderSettings(settings): Persists incoming render toggles, reloads if needed, and reports the result.
+ *  - getRenderSettings(): Returns the current render settings snapshot, including highlight and lighting values.
+ *  - applyRenderSettings(settings): Applies render settings, reloading only when a setting requires it.
  *  - showModel(): Shows the 3D model.
  *  - hideModel(): Hides the 3D model.
  *  - showEnvironment(): Shows the 3D environment/scene.
  *  - hideEnvironment(): Hides the 3D environment/scene.
+ *  - isIBLAvailable(): Reports whether a valid IBL environment map is currently available.
+ *  - isAnimationMenuEnabled(): Reports whether the animation control menu is currently enabled.
+ *  - getDebugInfo(): Returns a diagnostic snapshot of the underlying Babylon.js runtime.
+ *  - getAnimations(): Returns a snapshot of all available animations and their current state.
+ *  - playAnimation(name, action): Controls a named animation by applying the specified action.
+ *  - setAnimationProgress(name, progress): Seeks a named animation to a normalized progress position (0–1).
+ *  - setAnimationLoop(name, loop): Enables or disables loop mode for a named animation.
  *  - downloadModelGLB(): Downloads the current 3D model as a GLB file.
  *  - downloadModelGLTF(): Downloads the current 3D model as a glTF ZIP file.
  *  - downloadModelUSDZ(): Downloads the current 3D model as a USDZ file.
@@ -56,14 +64,16 @@ import FileStorage from "./file-storage.js";
  *  - #checkNeedToUpdateCamera(options): Detects camera option changes and marks them pending.
  *  - #checkNeedToUpdateMaterials(options): Resolves material overrides that require updates.
  *  - #checkNeedToUpdateIBL(options): Fetches HDR URLs/timestamps and enqueues IBL updates when needed.
+ *  - #checkNeedToUpdateLighting(options): Resolves time-of-day changes and marks lighting as pending.
  *  - #resetUpdateFlags(): Clears pending/success flags after loads or option-setting flows.
  *  - #onLoading/#onLoaded/#onSettingOptions/#onSetOptions(): Dispatch lifecycle events and synchronize attributes.
  *
  * Events:
- *  - "scene-loading": Dispatched when a loading operation starts.
- *  - "scene-loaded": Dispatched when a loading operation completes.
- *  - "scene-setting-options": Dispatched when viewer options are being set.
- *  - "scene-set-options": Dispatched when viewer options have been set.
+ *  - "pref-viewer-3d-loading": Dispatched when a loading operation starts. Legacy alias: "scene-loading".
+ *  - "pref-viewer-3d-loaded": Dispatched when a loading operation completes. Legacy alias: "scene-loaded".
+ *  - "pref-viewer-3d-options-applying": Dispatched when viewer options are being set. Legacy alias: "scene-setting-options".
+ *  - "pref-viewer-3d-options-applied": Dispatched when viewer options have been set. Legacy alias: "scene-set-options".
+ *  - "pref-viewer-3d-animation-changed": Dispatched by OpeningAnimation instances via the pref-viewer-3d host when an animation state, progress, or loop value changes.
  *
  * Notes:
  *  - Internal state and heavy initialization are handled in connectedCallback.
@@ -97,7 +107,7 @@ export default class PrefViewer3D extends HTMLElement {
      * @returns {string[]} Array of attribute names that trigger attributeChangedCallback.
      */
     static get observedAttributes() {
-        return ["show-model", "show-scene", "visible", "show-animation-menu", "highlight-color", "highlight-enabled"];
+        return ["show-model", "show-scene", "visible"];
     }
 
     /**
@@ -137,18 +147,6 @@ export default class PrefViewer3D extends HTMLElement {
                     this.hide();
                 }
                 break;
-            case "show-animation-menu":
-            case "highlight-color":
-            case "highlight-enabled":
-                // Pass these to BabylonJSController if initialized
-                if (this.#babylonJSController && typeof this.#babylonJSController.setIlluminationConfig === "function") {
-                    this.#babylonJSController.setIlluminationConfig({
-                        showAnimationMenu: this.getAttribute("show-animation-menu"),
-                        highlightColor: this.getAttribute("highlight-color"),
-                        highlightEnabled: this.getAttribute("highlight-enabled"),
-                    });
-                }
-                break;
         }
     }
 
@@ -229,8 +227,10 @@ export default class PrefViewer3D extends HTMLElement {
                     outerFloor: new MaterialData("outerFloor", undefined, undefined, ["outerFloor"]),
                 },
                 ibl: new IBLData(),
-                lighting: {
-                    timeOfDay: 0.5,
+                render: {
+                    showAnimationMenu: false,
+                    lightingTimeOfDay: 0.5,
+                    showLightingTimeOfDay: false,
                 },
             },
         };
@@ -245,15 +245,6 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController = new BabylonJSController(this.#canvas, this.#data.containers, this.#data.options);
         this.#babylonJSController.enable();
 
-        // Apply highlight attributes that were set before the controller was ready
-        const highlightColor = this.getAttribute("highlight-color");
-        const highlightEnabled = this.getAttribute("highlight-enabled");
-        if (highlightColor !== null || highlightEnabled !== null) {
-            this.#babylonJSController.setIlluminationConfig({
-                highlightColor: highlightColor ?? undefined,
-                highlightEnabled: highlightEnabled ?? undefined,
-            });
-        }
     }
 
     /**
@@ -425,29 +416,37 @@ export default class PrefViewer3D extends HTMLElement {
                 iblState.setValues(url, cachedUrl, intensity, shadows, timeStamp);
             }
         }
-        
+
         return needUpdate;
     }
 
     /**
-     * Resolves incoming lighting settings (time-of-day slider) and marks the option as pending when changed.
-     * Supports both nested `options.lighting.timeOfDay` and flat `options.lightingTimeOfDay` payloads so the menu
-     * and external API can share the same controller path.
+     * Checks whether any lighting-related value in `options.render` differs from the cached state.
+     * `options.render.showLightingTimeOfDay` updates slider visibility, while
+     * `options.render.lightingTimeOfDay` updates the normalized 0..1 lighting value.
      * @private
-     * @param {object} options - Options payload containing lighting state.
-     * @returns {boolean} True when lighting differs from the cached state, otherwise false.
+     * @param {object} options - Options payload containing a `render` sub-object.
+     * @param {boolean|string} [options.render.showLightingTimeOfDay] - Whether the time-of-day slider should be visible.
+     * @param {number} [options.render.lightingTimeOfDay] - Desired time-of-day, normalized to 0..1.
+     * @returns {boolean} True when either the visibility flag or the time value differs from the cached state.
      */
     #checkNeedToUpdateLighting(options) {
         if (!options) {
             return false;
         }
 
-        const lightingState = this.#data.options.lighting;
-        const incomingTime = typeof options.lightingTimeOfDay === "number"
-            ? options.lightingTimeOfDay
-            : typeof options.lighting?.timeOfDay === "number"
-                ? options.lighting.timeOfDay
-                : undefined;
+        const incomingTimeEnabled = options.render?.showLightingTimeOfDay;
+        if (incomingTimeEnabled !== undefined) {
+            const dataTimeEnabled = this.#data.options.render.showLightingTimeOfDay;
+            const needUpdate = dataTimeEnabled !== incomingTimeEnabled;
+            this.#data.options.render.showLightingTimeOfDay = incomingTimeEnabled;
+            if (needUpdate) {
+                return true;
+            }
+        }
+
+        const dataTime = this.#data.options.render.lightingTimeOfDay;
+        const incomingTime = typeof options.render?.lightingTimeOfDay === "number" ? options.render.lightingTimeOfDay : undefined;
 
         if (!Number.isFinite(incomingTime)) {
             return false;
@@ -455,9 +454,9 @@ export default class PrefViewer3D extends HTMLElement {
 
         const normalizedTime = Math.min(1, Math.max(0, incomingTime));
         const controllerTime = this.#babylonJSController?.getRenderSettings?.()?.lightingTimeOfDay;
-        const currentTime = Number.isFinite(controllerTime) ? controllerTime : lightingState.timeOfDay;
+        const currentTime = Number.isFinite(controllerTime) ? controllerTime : dataTime;
         const needUpdate = normalizedTime !== currentTime;
-        lightingState.timeOfDay = normalizedTime;
+        this.#data.options.render.lightingTimeOfDay = normalizedTime;
         return needUpdate;
     }
 
@@ -472,8 +471,10 @@ export default class PrefViewer3D extends HTMLElement {
             bubbles: true, // indicates whether the event bubbles up through the DOM tree or not
             cancelable: true, // indicates whether the event can be canceled, and therefore prevented as if the event never happened
             composed: false, // indicates whether or not the event will propagate across the shadow DOM boundary into the standard DOM
+
         };
-        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -521,7 +522,8 @@ export default class PrefViewer3D extends HTMLElement {
             composed: false,
             detail: detail,
         };
-        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -544,7 +546,8 @@ export default class PrefViewer3D extends HTMLElement {
             cancelable: true,
             composed: false,
         };
-        this.dispatchEvent(new CustomEvent("scene-setting-options", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-options-applying", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-setting-options", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -586,7 +589,8 @@ export default class PrefViewer3D extends HTMLElement {
             composed: false,
             detail: detail,
         };
-        this.dispatchEvent(new CustomEvent("scene-set-options", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-options-applied", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-set-options", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -643,10 +647,15 @@ export default class PrefViewer3D extends HTMLElement {
         this.#checkNeedToUpdateContainers(config);
 
         // Options
-        let needUpdateLighting = false;
         const iblOptions = config.scene?.ibl
-            ? { ...(config.options ?? {}), ibl: { ...(config.options?.ibl ?? {}), ...config.scene.ibl } }
-            : config.options;
+        ? { ...(config.options ?? {}), ibl: { ...(config.options?.ibl ?? {}), ...config.scene.ibl } }
+        : config.options;
+
+        if (iblOptions) {
+            await this.#checkNeedToUpdateIBL(iblOptions);
+        }
+
+        let needUpdateLighting = false;
 
         if (config.options) {
             this.#checkNeedToUpdateCamera(config.options);
@@ -654,16 +663,15 @@ export default class PrefViewer3D extends HTMLElement {
             needUpdateLighting = this.#checkNeedToUpdateLighting(config.options);
         }
 
-        if (iblOptions) {
-            await this.#checkNeedToUpdateIBL(iblOptions);
-        }
-
-        const loadDetail = await this.#babylonJSController.load(forceReload);
-
         if (needUpdateLighting && typeof this.#babylonJSController.setIlluminationConfig === "function") {
-            this.#babylonJSController.setIlluminationConfig({
-                lightingTimeOfDay: this.#data.options.lighting.timeOfDay,
-            });
+            const lightingConfig = {};
+            if (config.options?.render?.lightingTimeOfDay !== undefined) {
+                lightingConfig.lightingTimeOfDay = config.options.render.lightingTimeOfDay;
+            }
+            if (config.options?.render?.showLightingTimeOfDay !== undefined) {
+                lightingConfig.showLightingTimeOfDay = config.options.render.showLightingTimeOfDay;
+            }
+            this.#babylonJSController.setIlluminationConfig(lightingConfig);
         }
 
         // Apply initial render settings if provided in options
@@ -671,6 +679,8 @@ export default class PrefViewer3D extends HTMLElement {
             await this.applyRenderSettings(config.options.render);
         }
 
+        const loadDetail = await this.#babylonJSController.load(forceReload);
+
         return { ...loadDetail, load: this.#onLoaded() };
     }
 
@@ -701,17 +711,22 @@ export default class PrefViewer3D extends HTMLElement {
         }
         const needUpdateLighting = this.#checkNeedToUpdateLighting(options);
         if (needUpdateLighting && typeof this.#babylonJSController.setIlluminationConfig === "function") {
-            this.#babylonJSController.setIlluminationConfig({
-                lightingTimeOfDay: this.#data.options.lighting.timeOfDay,
-            });
+            const lightingConfig = {};
+            if (options.render?.lightingTimeOfDay !== undefined) {
+                lightingConfig.lightingTimeOfDay = options.render.lightingTimeOfDay;
+            }
+            if (options.render?.showLightingTimeOfDay !== undefined) {
+                lightingConfig.showLightingTimeOfDay = options.render.showLightingTimeOfDay;
+            }
+            this.#babylonJSController.setIlluminationConfig(lightingConfig);
             someSetted = true;
         }
-        
+
         // Apply render settings if provided
         if (options.render) {
             await this.applyRenderSettings(options.render);
         }
-        
+
         const detail = this.#onSetOptions();
         return { success: someSetted, detail: detail };
     }
@@ -874,8 +889,9 @@ export default class PrefViewer3D extends HTMLElement {
 
     /**
      * Returns the current render settings used by the BabylonJSController.
+     * The snapshot is suitable for hydrating PrefViewerMenu3D controls.
      * @public
-     * @returns {object|null} A shallow copy of the render settings or null if unavailable.
+     * @returns {object|null} A shallow copy of the render settings, including quality toggles, highlight state, and lighting time, or null if unavailable.
      */
     getRenderSettings() {
         if (!this.#babylonJSController) {
@@ -944,40 +960,95 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Applies render settings that require reloading the Babylon.js scene.
+     * Reports whether the animation control menu is currently enabled.
+     * @public
+     * @returns {boolean} True when the animation menu option is active; otherwise false.
+     */
+    isAnimationMenuEnabled() {
+        const renderSettings = this.getRenderSettings?.() ?? null;
+        if (renderSettings?.showAnimationMenu !== undefined) {
+            return renderSettings.showAnimationMenu === true;
+        }
+        return false;
+    }
+
+    /**
+     * Reports whether the lighting time-of-day control should be visible and interactive.
+     * Requires both `showLightingTimeOfDay === true` and a finite `lightingTimeOfDay` value.
+     * @public
+     * @returns {boolean} True when the time-of-day slider is explicitly visible and has a valid value; otherwise false.
+     */
+    isLightingTimeOfDayAvailable() {
+        const renderSettings = this.getRenderSettings?.() ?? null;
+        return renderSettings?.showLightingTimeOfDay === true && Number.isFinite(renderSettings.lightingTimeOfDay);
+    }
+
+    /**
+     * Returns a diagnostic snapshot of the underlying Babylon.js runtime.
      * @public
-     * @param {object} settings - Partial settings for anti-aliasing, SSAO, IBL, and shadows.
-     * @returns {Promise<object>} Resolves with the reload summary.
+     * @returns {object|null} Debug information, or null when the controller is not initialized.
+     */
+    getDebugInfo() {
+        return this.#babylonJSController?.getDebugInfo?.() ?? null;
+    }
+    /**
+     * Applies render settings received from PrefViewerMenu3D or another UI.
+     * Highlight and time-of-day lighting values are pushed directly to BabylonJSController; AA/SSAO/IBL/shadow changes
+     * are scheduled through the render-settings reload path when needed.
+     * @public
+     * @param {object} settings - Partial render settings payload.
+     * @param {boolean} [settings.antiAliasingEnabled] - Enables or disables anti-aliasing.
+     * @param {boolean} [settings.ambientOcclusionEnabled] - Enables or disables SSAO.
+     * @param {boolean} [settings.iblEnabled] - Enables or disables image-based lighting.
+     * @param {boolean} [settings.shadowsEnabled] - Enables or disables scene shadows.
+     * @param {boolean|string} [settings.showAnimationMenu] - Enables/disables the animation controls when animations are available.
+     * @param {boolean|string} [settings.highlightEnabled] - Enables or disables hover highlight; string "false" is normalized to false.
+     * @param {string} [settings.highlightColor] - Hex color used for hover highlight.
+     * @param {boolean|string} [settings.showLightingTimeOfDay] - Shows/hides the lighting time-of-day control.
+     * @param {number} [settings.lightingTimeOfDay] - Normalized 0..1 time-of-day value.
+     * @param {boolean} [settings.persist=true] - False for transient lighting updates such as playback frames.
+     * @returns {Promise<{changed: boolean, success: boolean, detail?: object, controller?: object}>} Resolves with the apply/reload summary.
      */
     async applyRenderSettings(settings) {
         if (!this.#babylonJSController) {
             return { changed: false, success: false };
         }
 
-        // Handle highlight settings separately for immediate effect without reload
-        if (settings.highlightEnabled !== undefined || settings.highlightColor !== undefined) {
-            if (typeof this.#babylonJSController.setIlluminationConfig === "function") {
-                // Convert string "false" to boolean false
-                const highlightEnabled = settings.highlightEnabled === "false" ? false : settings.highlightEnabled;
-                this.#babylonJSController.setIlluminationConfig({
-                    highlightEnabled: highlightEnabled,
-                    highlightColor: settings.highlightColor,
-                });
-            }
+        const illuminationSettings = {};
+        if (settings.showAnimationMenu !== undefined) {
+            illuminationSettings.showAnimationMenu = settings.showAnimationMenu;
         }
-
-        // Exclude highlight settings from the reload — they are handled above without requiring a scene reload
-        if (settings.lightingTimeOfDay !== undefined && typeof this.#babylonJSController.setIlluminationConfig === "function") {
+        if (settings.highlightEnabled !== undefined) {
+            illuminationSettings.highlightEnabled = settings.highlightEnabled;
+        }
+        if (settings.highlightColor !== undefined) {
+            illuminationSettings.highlightColor = settings.highlightColor;
+        }
+        if (settings.showLightingTimeOfDay !== undefined) {
+            illuminationSettings.showLightingTimeOfDay = settings.showLightingTimeOfDay;
+        }
+        if (settings.lightingTimeOfDay !== undefined) {
             const lightingTimeOfDay = Number(settings.lightingTimeOfDay);
             if (Number.isFinite(lightingTimeOfDay)) {
-                this.#babylonJSController.setIlluminationConfig({
-                    lightingTimeOfDay,
-                    persist: settings.persist !== false,
-                });
+                illuminationSettings.lightingTimeOfDay = lightingTimeOfDay;
             }
         }
+        if (settings.persist !== undefined) {
+            illuminationSettings.persist = settings.persist;
+        }
+        if (Object.keys(illuminationSettings).length > 0 && typeof this.#babylonJSController.setIlluminationConfig === "function") {
+            this.#babylonJSController.setIlluminationConfig(illuminationSettings);
+        }
 
-        const { highlightEnabled: _he, highlightColor: _hc, lightingTimeOfDay: _lt, lighting: _lighting, persist: _persist, ...reloadSettings } = settings;
+        const {
+            showAnimationMenu: _sam,
+            highlightEnabled: _he,
+            highlightColor: _hc,
+            showLightingTimeOfDay: _slt,
+            lightingTimeOfDay: _lt,
+            persist: _persist,
+            ...reloadSettings
+        } = settings;
         const scheduled = this.#babylonJSController.scheduleRenderSettingsReload(reloadSettings);
         if (!scheduled.changed) {
             return { changed: false, success: true };