@preference-sl/pref-viewer 2.16.0-beta.1 → 2.16.0-beta.11

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,15 +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.
- *  - "model-first-painted": Dispatched when the model-only preview has actually painted a frame.
- *  - "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.
@@ -77,7 +86,6 @@ export default class PrefViewer3D extends HTMLElement {
     #isLoaded = false;
     #isVisible = false;
     #lastLoadTimestamp = undefined;
-    #suppressVisibilityAttributeCallback = false;
 
     #wrapper = null;
     #canvas = null;
@@ -99,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"];
     }
 
     /**
@@ -114,9 +122,6 @@ export default class PrefViewer3D extends HTMLElement {
      * - "visible": shows or hides the component according to the attribute value ("true"/"false").
      */
     attributeChangedCallback(name, _old, value) {
-        if (this.#suppressVisibilityAttributeCallback && (name === "show-model" || name === "show-scene")) {
-            return;
-        }
         switch (name) {
             case "show-model":
                 if (_old === value) {
@@ -142,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;
         }
     }
 
@@ -234,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,
                 },
             },
         };
@@ -250,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,
-            });
-        }
     }
 
     /**
@@ -430,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;
@@ -460,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;
     }
 
@@ -477,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", "");
@@ -526,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", "");
@@ -549,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", "");
@@ -591,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", "");
@@ -648,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);
@@ -659,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
@@ -676,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() };
     }
 
@@ -706,77 +711,26 @@ 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 };
     }
 
-    /**
-     * Loads the model container independently in the background while the render loop keeps running.
-     * Merges the model into the scene atomically when ready, without stopping camera-dependent effects.
-     * @public
-     * @param {object} payload - Model payload with storage pointer and optional timestamp.
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadModelIndependent(payload) {
-        if (!this.#babylonJSController) {
-            return { success: false, error: "Controller not initialized", loadedContainers: [] };
-        }
-        // #checkNeedToUpdateContainers passed as callback — called AFTER any in-progress #loadContainers
-        // finishes so the scene load doesn't also pick up and consume the model container.
-        return await this.#babylonJSController.loadContainerIndependent("model", () => {
-            this.#checkNeedToUpdateContainers({ model: payload });
-        }, { loadSessionId: payload?.loadSessionId ?? null });
-    }
-
-    /**
-     * Loads the environment/scene container independently in the background, in parallel with any
-     * ongoing model load. Applies IBL (HDR) if the scene payload includes an ibl property.
-     * Dispatches "scene-loading" and "scene-loaded" (or "scene-error") events directly.
-     * @public
-     * @param {object|string} scene - Scene payload: { storage, ibl?, visible? }
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadSceneIndependent(scene) {
-        if (!this.#babylonJSController) {
-            return { success: false, error: "Controller not initialized", loadedContainers: [] };
-        }
-        // Pre-mark IBL as pending before entering loadContainerIndependent — the onReady callback
-        // is synchronous so async IBL resolution must happen here, not inside it.
-        if (scene?.ibl !== undefined) {
-            await this.#checkNeedToUpdateIBL({ ibl: scene.ibl });
-        }
-        return await this.#babylonJSController.loadContainerIndependent("environment", () => {
-            this.#checkNeedToUpdateContainers({ scene });
-        });
-    }
-
-    /**
-     * Loads the materials container independently in the background, in parallel with any
-     * ongoing model or environment load.
-     * @public
-     * @param {object|string} materials - Materials payload: { storage }
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadMaterialsIndependent(materials) {
-        if (!this.#babylonJSController) {
-            return { success: false, error: "Controller not initialized", loadedContainers: [] };
-        }
-        return await this.#babylonJSController.loadContainerIndependent("materials", () => {
-            this.#checkNeedToUpdateContainers({ materials });
-        });
-    }
-
     /**
      * Shows the 3D model within the viewer.
      * @public
@@ -825,31 +779,6 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("environment", false);
     }
 
-    /**
-     * Reflects the current visibility of a container without re-triggering the command queue.
-     * Used by BabylonJSController when the visibility change originated from the renderer itself.
-     * @public
-     * @param {string} name - Container name ("model" or "environment").
-     * @param {boolean} isVisible - Whether the container should be reflected as visible.
-     * @returns {void}
-     */
-    syncVisibility(name, isVisible) {
-        const attrName = name === "model" ? "show-model" : name === "environment" ? "show-scene" : null;
-        if (!attrName) {
-            return;
-        }
-        const nextValue = isVisible ? "true" : "false";
-        if (this.getAttribute(attrName) === nextValue) {
-            return;
-        }
-        this.#suppressVisibilityAttributeCallback = true;
-        try {
-            this.setAttribute(attrName, nextValue);
-        } finally {
-            this.#suppressVisibilityAttributeCallback = false;
-        }
-    }
-
     /**
      * Downloads the current 3D model as a GLB file.
      * @public
@@ -960,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) {
@@ -1030,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
-     * @param {object} settings - Partial settings for anti-aliasing, SSAO, IBL, and shadows.
-     * @returns {Promise<object>} Resolves with the reload summary.
+     * @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
+     * @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 };
@@ -1101,22 +1086,4 @@ export default class PrefViewer3D extends HTMLElement {
     get isVisible() {
         return this.#isVisible;
     }
-
-    /**
-     * Forces the active camera to frame the visible model.
-     * @public
-     * @returns {boolean}
-     */
-    focusModel() {
-        return this.#babylonJSController?.focusModel?.() ?? false;
-    }
-
-    /**
-     * Returns a debug snapshot of the internal 3D state, including camera data.
-     * @public
-     * @returns {object|null}
-     */
-    getDebugState() {
-        return this.#babylonJSController?.getDebugState?.() ?? null;
-    }
 }