@preference-sl/pref-viewer 2.16.0 → 2.16.2-beta.0

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, Camera, Color3, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -54,9 +54,10 @@ export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlass
  * Public API Highlights
  *  - constructor(canvas, containers, options)
  *  - enable() / disable()
- *  - load() / reloadWithCurrentSettings()
+ *  - load(force?) / reloadWithCurrentSettings()
  *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
  *  - getRenderSettings() / scheduleRenderSettingsReload(settings)
+ *  - getDebugInfo()
  *  - setContainerVisibility(name, show)
  *  - setMaterialOptions() / setCameraOptions() / setIBLOptions()
  *  - setIlluminationConfig(config)
@@ -96,10 +97,13 @@ export default class BabylonJSController {
         ambientOcclusionEnabled: true,
         iblEnabled: true,
         shadowsEnabled: false,
-        lightingTimeOfDay: 0.5,
-        // Highlight settings
+        // Animation menu and highlight settings
+        showAnimationMenu: true,
         highlightEnabled: true,
         highlightColor: PrefViewerStyleVariables.colorPrimary,
+        // Lighting time of day (0=midnight, 0.5=noon, 1=midnight)
+        showLightingTimeOfDay: true,
+        lightingTimeOfDay: 0.5,
     };
 
     // Canvas HTML element
@@ -120,7 +124,7 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
-    
+
     #hdrTexture = null; // Reusable in-memory HDR source cloned into scene.environmentTexture across reloads
 
     #containers = {};
@@ -188,6 +192,11 @@ export default class BabylonJSController {
         resize: {
             throttleMs: 50, // Cap resize work to ~20 Hz while dragging/resizing containers
         },
+        defaultCameraFraming: {
+            margin: 1.25,          // Breathing room so the model doesn't touch the viewport edges
+            minRadiusFactor: 0.25, // Zoom in on detail
+            maxRadiusFactor: 4,    // Pull back past the whole model
+        },
         // Hardware-adaptive quality settings (applied based on GPU capabilities)
         quality: {
             // Settings for different hardware tiers: 'low', 'medium', 'high'
@@ -209,6 +218,24 @@ export default class BabylonJSController {
                 hemiLightIntensity: 0.52,
                 dirLightIntensity: 0.56,
                 cameraLightIntensity: 0.16,
+                // Daylight background, in the LINEAR domain the tonemapper consumes — NOT sRGB.
+                //
+                // The clear colour goes through the same exposure + ACES + gamma chain as the
+                // render, so the value that reads correctly here is not the value that reaches the
+                // screen. The previous literal was an sRGB 0.98 ("almost white") and it arrived as
+                // #C0C0C0, a mid grey.
+                //
+                // This one is solved against the ACES fit at exposure 0.92 and verified on screen:
+                // a light studio grey, #D9D9D9. Other targets, if this needs revisiting —
+                //   #F4F3F0 warm off-white (matches the host app's 2D/PR surface) -> 4.289 3.991 3.304
+                //   #D9D9D9 light studio                                (current) -> 1.424
+                //   #CCCCCC neutral studio                                        -> 1.112
+                //   #B3B3B3 darker                                                -> 0.688
+                // Note how steeply the required input climbs near white: that is the ACES shoulder,
+                // and it is why a near-white background needs a value well above 1.
+                //
+                // Re-solve these if exposure, contrast or the tonemapping curve change.
+                backgroundDay: [1.424, 1.424, 1.424],
             },
         },
     };
@@ -222,18 +249,18 @@ export default class BabylonJSController {
     #detectHardwareTier() {
         // First, try to get WebGL info to help identify the device
         const gl = this.#engine?.getRenderingCanvas()?.getContext?.('webgl2') || this.#engine?.getRenderingCanvas()?.getContext?.('webgl');
-        
+
         const debugInfo = gl?.getExtension('WEBGL_debug_renderer_info');
         const rendererName = debugInfo ? gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) : '';
         const isAngleRenderer = /^ANGLE\s*\(/i.test(rendererName);
-        
+
         // If we have WebGL renderer info and it looks like a desktop GPU, skip mobile detection
         // Desktop GPUs typically have "NVIDIA", "AMD", "Intel" in the name
         const isDesktopGPU = /NVIDIA|AMD|Intel|Radeon|GeForce|Quadro/i.test(rendererName);
-        
+
         // Also check if it's explicitly a mobile GPU
         const isMobileGPU = /Adreno|Mali|Apple GPU/i.test(rendererName);
-        
+
         // If we detect a desktop GPU, go directly to desktop detection
         if (isDesktopGPU && !isMobileGPU) {
             if (isAngleRenderer) {
@@ -252,7 +279,7 @@ export default class BabylonJSController {
 
         // If no WebGL info or unclear, fall back to user agent detection
         const mobileInfo = this.#detectMobileInfo();
-        
+
         // Only treat as mobile if we have strong mobile indicators
         if (mobileInfo.isMobile && !mobileInfo.isDesktopLike) {
             if (mobileInfo.isHighEnd) {
@@ -279,15 +306,15 @@ export default class BabylonJSController {
     #detectDesktopTier(gl, rendererName, conservative = false) {
         // Check WebGL capabilities
         const maxTextureSize = gl?.getParameter(gl.MAX_TEXTURE_SIZE) || 8192;
-        
+
         // Detect high-end GPUs
         const isAppleSilicon = /Apple|M1|M2|M3|M4/i.test(rendererName);
         const isNvidiaHighEnd = /RTX|GeForce (3|4|5|6|7|8|9|40|50|60|70|80|90)|RTX A[5-9]|RTX Pro|Quadro/i.test(rendererName);
         const isAmdHighEnd = /RX (6|7|8|9)[0-9]{2,}|RX Vega|Radeon Pro|WX [0-9]/i.test(rendererName);
         const isIntelIntegrated = /Intel.*UHD|Intel.*Iris|Mesa|llvmpipe/i.test(rendererName);
-        
+
         let tier = conservative ? 'medium' : 'high'; // Default to conservative desktop when ANGLE is in the path
-        
+
         if (isIntelIntegrated || maxTextureSize < 8192) {
             tier = 'medium';
         } else if (!conservative && (isAppleSilicon || isNvidiaHighEnd || isAmdHighEnd || maxTextureSize >= 16384)) {
@@ -295,7 +322,7 @@ export default class BabylonJSController {
         } else if (conservative && maxTextureSize >= 16384) {
             tier = 'high';
         }
-        
+
         console.log(`[PrefViewer] Desktop tier: ${tier} (GPU: ${rendererName || 'unknown'}, MaxTexture: ${maxTextureSize})`);
         return tier;
     }
@@ -311,13 +338,13 @@ export default class BabylonJSController {
         const screenWidth = window.screen?.width || 0;
         const screenHeight = window.screen?.height || 0;
         const pixelRatio = window.devicePixelRatio || 1;
-        
+
         // Detect device type
         const isIPhone = /iPhone/i.test(userAgent);
         const isIPad = /iPad/i.test(userAgent);
         const isAndroid = /Android/i.test(userAgent);
         const isMobile = /Mobile/i.test(userAgent);
-        
+
         // High-end mobile patterns (recent flagship devices)
         const highEndPatterns = [
             /iPhone (1[4-9]|SE)/i,        // iPhone 14+
@@ -329,7 +356,7 @@ export default class BabylonJSController {
             /Xiaomi (1[2-4]|Mi 1[1-4])/i, // Xiaomi 12+
             /Huawei (P50|Mate 4|)/i,      // Huawei P50+
         ];
-        
+
         // Mid-range patterns
         const midRangePatterns = [
             /iPhone (1[0-3]|SE)/i,        // iPhone 10-13
@@ -339,20 +366,20 @@ export default class BabylonJSController {
             /Pixel [4-6]/i,               // Pixel 4-6
             /Moto G/i,                    // Moto G
         ];
-        
+
         const isHighEnd = highEndPatterns.some(p => p.test(userAgent));
         const isMidRange = midRangePatterns.some(p => p.test(userAgent));
-        
+
         // Detect tablet ONLY if explicitly in user agent (not just screen size)
         // Many desktops have large screens and would incorrectly be detected as tablets
         const isTablet = /iPad|Android.*Tablet|Nexus 9|Nexus 10/i.test(userAgent);
-        
+
         // Detect if mobile (phone form factor) - must have explicit mobile indicators
         const isMobilePhone = /Android.*Mobile|iPhone|iPod/i.test(userAgent);
-        
+
         // Check if it looks like a desktop/laptop (has "Windows", "Mac", "Linux" but no mobile indicators)
         const isDesktopLike = /Windows NT|Macintosh|Linux|X11/i.test(userAgent) && !isMobilePhone && !isTablet;
-        
+
         // Device name for logging
         let deviceName = 'Unknown';
         if (isIPhone) {
@@ -364,7 +391,7 @@ export default class BabylonJSController {
             const match = userAgent.match(/Android.*;.*(.+?)\)/);
             deviceName = match ? match[1].trim() : 'Android';
         }
-        
+
         return {
             isMobile: isMobilePhone && !isDesktopLike,
             isTablet: isTablet && !isDesktopLike,
@@ -445,10 +472,10 @@ export default class BabylonJSController {
         };
 
         const preset = presetMap[tier] || qualityPresets.medium;
-        
+
         // Apply preset to config
-        this.#config.quality = { 
-            tier, 
+        this.#config.quality = {
+            tier,
             ...preset,
             // Legacy compatibility
             shadowMapSize: preset.shadowMapSize,
@@ -642,6 +669,55 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Preloads Babylon's internal BRDF lookup texture required by PBR materials.
+     * In render-on-demand hosts the RGBD expansion can stall unless a few renders are kept alive.
+     * @private
+     * @returns {Promise<boolean>} True when the texture is ready, false when it timed out or is unavailable.
+     */
+    async #ensureEnvironmentBRDFTextureReady() {
+        if (!this.#scene || !this.#engine) {
+            return false;
+        }
+
+        const brdfTexture = BRDFTextureTools.GetEnvironmentBRDFTexture(this.#scene);
+        if (!brdfTexture || brdfTexture.isReady?.()) {
+            return true;
+        }
+
+        const timeoutMs = 2000;
+        const startedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        this.#requestRender({ frames: this.#config.render.burstFramesEnhanced, continuousMs: timeoutMs });
+
+        try {
+            await new Promise((resolve) => {
+                const tick = () => {
+                    if (!this.#scene || !this.#engine || brdfTexture.isDisposed?.()) {
+                        resolve(false);
+                        return;
+                    }
+                    if (brdfTexture.isReady?.()) {
+                        resolve(true);
+                        return;
+                    }
+                    const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+                    if (now - startedAt >= timeoutMs) {
+                        resolve(false);
+                        return;
+                    }
+                    this.#requestRender({ frames: 1, continuousMs: 100 });
+                    setTimeout(tick, 16);
+                };
+                tick();
+            });
+        } catch (error) {
+            console.warn("PrefViewer: Error preparing Babylon BRDF texture:", error);
+        }
+
+        this.#requestRender({ frames: 2 });
+        return brdfTexture.isReady?.() ?? false;
+    }
+
     /**
      * Starts Babylon's engine render loop if it is not already running.
      * @private
@@ -669,7 +745,7 @@ export default class BabylonJSController {
         this.#state.render.isLoopRunning = false;
         return true;
     }
-    
+
     /**
      * Resets transient render-loop bookkeeping so the next render request starts from a clean baseline.
      * Clears queued burst frames, ends any active continuous-render window, and drops the idle-throttle timestamp.
@@ -804,12 +880,12 @@ export default class BabylonJSController {
         }
 
         const shouldRender = animationRunning || cameraInMotion || this.#state.render.continuousUntil > now;
-        
+
         // Reset idle flag if we need to render
         if (shouldRender) {
             this.#state.render.isIdle = false;
         }
-        
+
         return shouldRender;
     }
 
@@ -845,7 +921,7 @@ export default class BabylonJSController {
         if (!continuous && this.#state.render.lastRenderAt > 0 && now - this.#state.render.lastRenderAt < this.#config.render.idleThrottleMs) {
             return;
         }
-        
+
         this.#scene.render();
         this.#state.render.lastRenderAt = now;
 
@@ -1570,7 +1646,7 @@ export default class BabylonJSController {
             }
         });
     }
-  
+
     /**
      * Applies the showroom tonemapping curve and lighting bias used by the 3D viewer.
      * @private
@@ -1584,7 +1660,8 @@ export default class BabylonJSController {
         const showroom = this.#config.look?.showroom || {};
         const imageProcessing = this.#scene.imageProcessingConfiguration;
 
-        this.#scene.clearColor = new Color4(0.98, 0.98, 0.98, 1).toLinearSpace();
+        const bg = showroom.backgroundDay ?? this.#config.look.showroom.backgroundDay;
+        this.#scene.clearColor = new Color4(bg[0], bg[1], bg[2], 1);
         imageProcessing.exposure = showroom.exposure ?? 0.95;
         imageProcessing.contrast = showroom.contrast ?? 1.08;
         imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
@@ -1608,7 +1685,7 @@ export default class BabylonJSController {
         }
 
         const showroom = this.#config.look?.showroom || {};
-        const timeOfDay = clamp01(this.#settings.lightingTimeOfDay ?? 0.5);
+        const timeOfDay = clamp01(this.#settings.lightingTimeOfDay ? this.#settings.lightingTimeOfDay ?? 0.5 : 0.5);
         const profile = getLightingCycleProfile(timeOfDay);
         const daylight = profile.dayFactor;
         const peakLight = daylight > 0 ? Math.pow(daylight, 0.72) : 0;
@@ -1624,12 +1701,15 @@ export default class BabylonJSController {
             imageProcessing.colorCurvesEnabled = false;
         }
 
+        // Night end stays in low linear values (a dark blue sky); the day end is the calibrated
+        // HDR off-white. Both are linear already, so no toLinearSpace() on either.
+        const bgDay = showroom.backgroundDay ?? this.#config.look.showroom.backgroundDay;
         this.#scene.clearColor = new Color4(
-            lerp(0.035, 0.98, daylight),
-            lerp(0.045, 0.98, daylight),
-            lerp(0.085, 0.98, daylight),
+            lerp(0.000627, bgDay[0], daylight),
+            lerp(0.001089, bgDay[1], daylight),
+            lerp(0.004413, bgDay[2], daylight),
             1,
-        ).toLinearSpace();
+        );
 
         if ("environmentIntensity" in this.#scene) {
             this.#scene.environmentIntensity = lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
@@ -1701,6 +1781,78 @@ export default class BabylonJSController {
         this.#engine.setHardwareScalingLevel(scalingLevel);
     }
 
+    /**
+     * World-space bounds of the loaded model's renderable geometry.
+     * @private
+     * @returns {{center: Vector3, radius: number}|null} Centre and bounding-sphere radius, or null when nothing renderable is loaded.
+     */
+    #getModelBounds() {
+        const meshes = (this.#containers?.model?.assetContainer?.meshes ?? []).filter((mesh) => (mesh?.getTotalVertices?.() ?? 0) > 0);
+        if (meshes.length === 0) {
+            return null;
+        }
+
+        let min = null;
+        let max = null;
+        meshes.forEach((mesh) => {
+            mesh.computeWorldMatrix(true);
+            const box = mesh.getBoundingInfo?.()?.boundingBox;
+            if (!box) {
+                return;
+            }
+            min = min ? Vector3.Minimize(min, box.minimumWorld) : box.minimumWorld.clone();
+            max = max ? Vector3.Maximize(max, box.maximumWorld) : box.maximumWorld.clone();
+        });
+
+        if (!min || !max) {
+            return null;
+        }
+
+        const radius = Vector3.Distance(min, max) / 2;
+        if (!Number.isFinite(radius) || radius <= 0) {
+            return null;
+        }
+
+        return { center: Vector3.Center(min, max), radius };
+    }
+
+    /**
+     * Frames the default camera on the loaded model: aims it at the model's centre and pulls it
+     * back far enough for the whole model to fit the viewport.
+     *
+     * Only ever applied to the viewer's own camera — a camera authored in the model or the scene
+     * is a composition choice and is left untouched. Orbit angles are preserved so a model reload
+     * (an option or dimension change) re-centres without snapping the user's viewpoint back.
+     * @private
+     * @param {Camera|null|undefined} camera - The camera about to become active.
+     * @returns {void}
+     */
+    #fitDefaultCameraToModel(camera) {
+        if (camera !== this.#camera || !(camera instanceof ArcRotateCamera)) {
+            return;
+        }
+
+        const bounds = this.#getModelBounds();
+        if (!bounds) {
+            return;
+        }
+
+        // fovMode is FOVMODE_HORIZONTAL_FIXED (see #applyShowroomCameraFraming), so camera.fov is
+        // the horizontal angle and the vertical one follows the aspect ratio. Fitting to the
+        // horizontal angle alone clips the model top and bottom on any viewport wider than tall.
+        const aspect = this.#engine?.getAspectRatio?.(camera) || 1;
+        const horizontalFov = camera.fov;
+        const verticalFov = 2 * Math.atan(Math.tan(horizontalFov / 2) / aspect);
+        const limitingFov = Math.min(horizontalFov, verticalFov);
+        const distance = (bounds.radius / Math.sin(limitingFov / 2)) * this.#config.defaultCameraFraming.margin;
+
+        camera.setTarget(bounds.center);
+        camera.radius = distance;
+        // The 5-20 m defaults were sized for a room; left in place they clamp the fit itself.
+        camera.lowerRadiusLimit = distance * this.#config.defaultCameraFraming.minRadiusFactor;
+        camera.upperRadiusLimit = distance * this.#config.defaultCameraFraming.maxRadiusFactor;
+    }
+
     /**
      * Keeps the showroom camera framing stable when the viewport aspect ratio changes.
      * The 3D showroom is meant to feel compositionally stable, so we prefer a horizontal-fixed
@@ -1931,7 +2083,7 @@ export default class BabylonJSController {
     }
 
     /**
-     * Attaches the `prefviewer-animation-changed` listener to the nearest `pref-viewer-3d` host.
+     * Attaches the `pref-viewer-3d-animation-changed` listener to the nearest `pref-viewer-3d` host.
      * Removes any previous registration first to avoid duplicate callbacks across reload cycles.
      * @private
      * @returns {boolean} True when the listener is attached, false when no host is available.
@@ -1942,12 +2094,12 @@ export default class BabylonJSController {
             return false;
         }
         this.#detachAnimationChangedListener();
-        this.#prefViewer3D.addEventListener("prefviewer-animation-changed", this.#handlers.onAnimationGroupChanged);
+        this.#prefViewer3D.addEventListener("pref-viewer-3d-animation-changed", this.#handlers.onAnimationGroupChanged);
         return true;
     }
 
     /**
-     * Detaches the `prefviewer-animation-changed` listener from the cached `pref-viewer-3d` host.
+     * Detaches the `pref-viewer-3d-animation-changed` listener from the cached `pref-viewer-3d` host.
      * @private
      * @returns {boolean} True when a host exists and the listener removal was attempted, false otherwise.
      */
@@ -1955,7 +2107,7 @@ export default class BabylonJSController {
         if (!this.#prefViewer3D) {
             return false;
         }
-        this.#prefViewer3D.removeEventListener("prefviewer-animation-changed", this.#handlers.onAnimationGroupChanged);
+        this.#prefViewer3D.removeEventListener("pref-viewer-3d-animation-changed", this.#handlers.onAnimationGroupChanged);
         return true;
     }
 
@@ -1988,12 +2140,12 @@ export default class BabylonJSController {
      */
     #onMouseWheel(event, pickInfo) {
         event.preventDefault();
-        
+
         // OPTIMIZATION: Mark activity for idle mode
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         this.#state.render.lastActivityAt = now;
         this.#state.render.isIdle = false;
-        
+
         const camera = this.#scene?.activeCamera;
         if (!camera) {
             return false;
@@ -2028,7 +2180,7 @@ export default class BabylonJSController {
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         this.#state.render.lastActivityAt = now;
         this.#state.render.isIdle = false;
-        
+
         if (this.#babylonJSAnimationController) {
             if (event.button !== 2 || !pickInfo || !pickInfo.pickedMesh) {
                 this.#babylonJSAnimationController.hideMenu();
@@ -2053,7 +2205,7 @@ export default class BabylonJSController {
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         this.#state.render.lastActivityAt = now;
         this.#state.render.isIdle = false;
-        
+
         const camera = this.#scene?.activeCamera;
         if (camera && !camera.metadata?.locked) {
             this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
@@ -2275,6 +2427,7 @@ export default class BabylonJSController {
             }
         }
         this.#applyShowroomCameraFraming(camera);
+        this.#fitDefaultCameraToModel(camera);
         this.#scene.activeCamera?.detachControl();
         camera.detachControl();
         if (!cameraState.locked) {
@@ -2701,20 +2854,34 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#enhanceTextureQuality();
-                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
-                // Apply stored highlight settings so fresh page loads respect persisted state
-                this.#setHighlightConfig({
-                    enabled: this.#settings.highlightEnabled,
-                    color: this.#settings.highlightColor,
-                });
-                if (this.#babylonJSAnimationController?.hasAnimations?.()) {
-                    this.#attachAnimationChangedListener();
-                }
+                this.#syncAnimationControllerAfterModelLoad();
+
                 await this.#startRender();
             });
         return detail;
     }
 
+    /**
+     * Creates or disposes the animation controller after a model load according to current settings.
+     * @private
+     * @returns {void}
+     */
+    #syncAnimationControllerAfterModelLoad() {
+        if (this.#settings.showAnimationMenu && this.#containers.model.assetContainer) {
+            this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
+            // Apply stored highlight settings so fresh page loads respect persisted state
+            this.#setHighlightConfig({
+                enabled: this.#settings.highlightEnabled,
+                color: this.#settings.highlightColor,
+            });
+            if (this.#babylonJSAnimationController?.hasAnimations?.()) {
+                this.#attachAnimationChangedListener();
+            }
+        } else {
+            this.#disposeAnimationController();
+        }
+    }
+
     /**
      * Reinstalls every camera-sensitive post-process (default pipeline, SSAO, shadows) after loads or option changes.
      * Ensures the active camera always owns fresh pipelines so render quality remains consistent across reload cycles.
@@ -2968,14 +3135,14 @@ export default class BabylonJSController {
         this.#configureDracoCompression();
         this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false }, true);
         this.#engine.disableUniformBuffers = true;
-        
+
         // OPTIMIZATION: Detect hardware tier and apply quality settings
         const detectedTier = this.#detectHardwareTier();
         this.#applyQualitySettings(detectedTier);
-        
+
         // OPTIMIZATION: Initialize idle tracking
         this.#state.render.lastActivityAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-        
+
         this.#scene = new Scene(this.#engine);
 
         // Activate the rendering of geometry data into a G-buffer, essential for advanced effects like deferred shading,
@@ -2996,6 +3163,7 @@ export default class BabylonJSController {
         this.#scene.skipPointerUpPicking = true;
 
         this.#createCamera();
+        await this.#ensureEnvironmentBRDFTextureReady();
         this.#enableInteraction();
         await this.#createXRExperience();
     }
@@ -3151,6 +3319,182 @@ export default class BabylonJSController {
         return { ...this.#settings };
     }
 
+    /**
+     * Returns a diagnostic snapshot of the current Babylon.js runtime state.
+     * Intended for integration troubleshooting and should not mutate scene state.
+     * @public
+     * @returns {object} Debug information for canvas, engine, scene, containers, render loop and settings.
+     */
+    getDebugInfo() {
+        const vectorToJSON = (value) => value ? { x: value.x, y: value.y, z: value.z } : null;
+        const rect = this.#canvas?.getBoundingClientRect?.();
+        const camera = this.#scene?.activeCamera ?? null;
+        const sceneMeshes = this.#scene?.meshes ?? [];
+        const sceneMaterials = this.#scene?.materials ?? [];
+        const sceneTextures = this.#scene?.textures ?? [];
+        const activeMeshes = this.#scene?.getActiveMeshes?.();
+        const modelAssetContainer = this.#containers?.model?.assetContainer ?? null;
+        const modelMeshes = modelAssetContainer?.meshes ?? [];
+        const enabledModelMeshes = modelMeshes.filter((mesh) => mesh.isEnabled?.() !== false && mesh.isVisible !== false);
+        const textureToJSON = (texture) => ({
+            name: texture?.name ?? null,
+            url: texture?.url ?? null,
+            isReady: texture?.isReady?.() ?? null,
+            hasTexture: Boolean(texture),
+            className: texture?.getClassName?.() ?? texture?.constructor?.name ?? null,
+        });
+        const summarizeMaterial = (material) => {
+            const relatedMeshes = sceneMeshes.filter((mesh) => mesh.material === material);
+            const sampleMesh = relatedMeshes[0] ?? null;
+            const activeTextures = material?.getActiveTextures?.() ?? [];
+            let isReadyWithoutMesh = null;
+            let isReadyWithMesh = null;
+            try {
+                isReadyWithoutMesh = typeof material?.isReady === "function" ? material.isReady() : null;
+            } catch (error) {
+                isReadyWithoutMesh = `error: ${error?.message ?? error}`;
+            }
+            try {
+                isReadyWithMesh = typeof material?.isReady === "function" && sampleMesh ? material.isReady(sampleMesh) : null;
+            } catch (error) {
+                isReadyWithMesh = `error: ${error?.message ?? error}`;
+            }
+
+            return {
+                name: material?.name ?? null,
+                id: material?.id ?? null,
+                className: material?.getClassName?.() ?? material?.constructor?.name ?? null,
+                isReadyWithoutMesh,
+                isReadyWithMesh,
+                relatedMeshes: relatedMeshes.length,
+                sampleMesh: sampleMesh ? {
+                    name: sampleMesh.name,
+                    id: sampleMesh.id,
+                    enabled: sampleMesh.isEnabled?.() ?? null,
+                    isVisible: sampleMesh.isVisible ?? null,
+                    hasVertices: sampleMesh.getTotalVertices?.() ?? null,
+                    hasIndices: sampleMesh.getTotalIndices?.() ?? null,
+                } : null,
+                textures: activeTextures.map(textureToJSON),
+                notReadyTextures: activeTextures.filter((texture) => texture?.isReady?.() === false).map(textureToJSON),
+                forceDepthWrite: material?.forceDepthWrite ?? null,
+                transparencyMode: material?.transparencyMode ?? null,
+                alpha: material?.alpha ?? null,
+                backFaceCulling: material?.backFaceCulling ?? null,
+                disableLighting: material?.disableLighting ?? null,
+            };
+        };
+        const materialDiagnostics = sceneMaterials.slice(0, 25).map(summarizeMaterial);
+        const notReadyMaterials = materialDiagnostics
+            .filter((material) => material.isReadyWithoutMesh === false || material.isReadyWithMesh === false || material.notReadyTextures.length > 0)
+            .slice(0, 25);
+        const notReadyTextures = sceneTextures
+            .filter((texture) => texture?.isReady?.() === false)
+            .slice(0, 25)
+            .map(textureToJSON);
+        const notReadyMeshes = sceneMeshes
+            .filter((mesh) => typeof mesh.isReady === "function" && !mesh.isReady())
+            .slice(0, 25)
+            .map((mesh) => ({
+                name: mesh.name,
+                id: mesh.id,
+                enabled: mesh.isEnabled?.() ?? null,
+                isVisible: mesh.isVisible ?? null,
+                material: mesh.material?.name ?? null,
+            }));
+        const modelBounds = enabledModelMeshes.length && this.#scene?.getWorldExtends
+            ? this.#scene.getWorldExtends((mesh) => enabledModelMeshes.includes(mesh))
+            : null;
+        const summarizeContainer = (container) => ({
+            show: container?.state?.show ?? null,
+            visible: container?.state?.visible ?? null,
+            mustBeShown: container?.state?.mustBeShown ?? null,
+            isPending: container?.state?.isPending ?? null,
+            isSuccess: container?.state?.isSuccess ?? null,
+            hasAssetContainer: Boolean(container?.assetContainer),
+            meshes: container?.assetContainer?.meshes?.length ?? 0,
+            enabledMeshes: (container?.assetContainer?.meshes ?? []).filter((mesh) => mesh.isEnabled?.() !== false && mesh.isVisible !== false).length,
+            materials: container?.assetContainer?.materials?.length ?? 0,
+            cameras: container?.assetContainer?.cameras?.map((item) => ({
+                name: item.name,
+                id: item.id,
+                className: item.getClassName?.() ?? item.constructor?.name ?? null,
+                position: vectorToJSON(item.position),
+                target: vectorToJSON(item.target),
+            })) ?? [],
+            animationGroups: container?.assetContainer?.animationGroups?.length ?? 0,
+        });
+
+        return {
+            canvas: {
+                clientWidth: this.#canvas?.clientWidth ?? null,
+                clientHeight: this.#canvas?.clientHeight ?? null,
+                width: this.#canvas?.width ?? null,
+                height: this.#canvas?.height ?? null,
+                boundingWidth: rect?.width ?? null,
+                boundingHeight: rect?.height ?? null,
+            },
+            engine: {
+                renderWidth: this.#engine?.getRenderWidth?.() ?? null,
+                renderHeight: this.#engine?.getRenderHeight?.() ?? null,
+                hardwareScalingLevel: this.#engine?.getHardwareScalingLevel?.() ?? null,
+                isPointerLock: this.#engine?.isPointerLock ?? null,
+                isDisposed: this.#engine?.isDisposed ?? null,
+                contextLost: this.#engine?.isContextLost?.() ?? null,
+            },
+            scene: {
+                uid: this.#scene?.uid ?? null,
+                isReady: this.#scene?.isReady?.() ?? null,
+                meshes: sceneMeshes.length,
+                visibleMeshes: activeMeshes?.length ?? activeMeshes?.data?.length ?? null,
+                materials: sceneMaterials.length,
+                textures: sceneTextures.length,
+                lights: this.#scene?.lights?.length ?? 0,
+                animationGroups: this.#scene?.animationGroups?.length ?? 0,
+                activeCamera: camera ? {
+                    name: camera.name,
+                    id: camera.id,
+                    className: camera.getClassName?.() ?? camera.constructor?.name ?? null,
+                    position: vectorToJSON(camera.position),
+                    target: vectorToJSON(camera.target),
+                    radius: camera.radius ?? null,
+                    alpha: camera.alpha ?? null,
+                    beta: camera.beta ?? null,
+                } : null,
+                clearColor: this.#scene?.clearColor ? {
+                    r: this.#scene.clearColor.r,
+                    g: this.#scene.clearColor.g,
+                    b: this.#scene.clearColor.b,
+                    a: this.#scene.clearColor.a,
+                } : null,
+                environmentTexture: this.#scene?.environmentTexture ? {
+                    name: this.#scene.environmentTexture.name,
+                    isReady: this.#scene.environmentTexture.isReady?.() ?? null,
+                } : null,
+                notReadyMaterials,
+                notReadyTextures,
+                materialDiagnostics,
+                notReadyMeshes,
+            },
+            containers: {
+                model: summarizeContainer(this.#containers.model),
+                environment: summarizeContainer(this.#containers.environment),
+                materials: summarizeContainer(this.#containers.materials),
+            },
+            modelBounds: modelBounds ? {
+                min: vectorToJSON(modelBounds.min),
+                max: vectorToJSON(modelBounds.max),
+            } : null,
+            render: { ...this.#state.render },
+            settings: { ...this.#settings },
+            pipelines: {
+                default: Boolean(this.#renderPipelines.default),
+                ssao: Boolean(this.#renderPipelines.ssao),
+                iblShadows: Boolean(this.#renderPipelines.iblShadows),
+            },
+        };
+    }
+
     /**
      * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
      * Applies material and camera options, sets visibility, and initializes lights and shadows.
@@ -3203,14 +3547,42 @@ export default class BabylonJSController {
     }
 
     /**
-     * Applies lighting and highlight configuration without forcing a full scene reload.
+     * Applies animation-menu, highlight, and time-of-day lighting configuration without forcing a full scene reload.
+     * Values are merged into the persisted render settings snapshot unless `config.persist === false`.
+     * When `showLightingTimeOfDay` is set to false and no explicit `lightingTimeOfDay` is supplied,
+     * the active lighting time is reset to `DEFAULT_RENDER_SETTINGS.lightingTimeOfDay` (0.5).
      * @public
-     * @param {{lightingTimeOfDay?:number, highlightColor?:string, highlightEnabled?:boolean, showAnimationMenu?:boolean}} config - Lighting/highlight configuration.
+     * @param {object} config - Immediate render/illumination configuration.
+     * @param {boolean|string} [config.showAnimationMenu] - Enables/disables the animation controls when animations are available.
+     * @param {boolean|string|null} [config.highlightEnabled] - Enables/disables hover highlight; string "false" is normalized to false, null is ignored.
+     * @param {string|null} [config.highlightColor] - Hex color used by hover highlight; null is ignored.
+     * @param {boolean|string} [config.showLightingTimeOfDay] - Shows/hides the time-of-day control and can reset time to the default when hidden.
+     * @param {number} [config.lightingTimeOfDay] - Normalized time of day in the 0..1 range.
+     * @param {boolean} [config.persist=true] - False for transient updates such as lighting playback frames.
      * @returns {void}
      */
     setIlluminationConfig(config = {}) {
         let shouldApplyLighting = false;
 
+        if (config.showLightingTimeOfDay !== undefined) {
+            const showLighting = typeof config.showLightingTimeOfDay === "string"
+                ? config.showLightingTimeOfDay.toLowerCase() !== "false"
+                : Boolean(config.showLightingTimeOfDay);
+            if (this.#settings.showLightingTimeOfDay !== showLighting) {
+                shouldApplyLighting = true;
+            }
+            this.#settings.showLightingTimeOfDay = showLighting;
+
+            const hasExplicitLightingTime = typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay);
+            if (!showLighting && !hasExplicitLightingTime) {
+                const defaultTime = BabylonJSController.DEFAULT_RENDER_SETTINGS.lightingTimeOfDay;
+                if (this.#settings.lightingTimeOfDay !== defaultTime) {
+                    this.#settings.lightingTimeOfDay = defaultTime;
+                    shouldApplyLighting = true;
+                }
+            }
+        }
+
         if (typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay)) {
             const normalizedTime = clamp01(config.lightingTimeOfDay);
             if (this.#settings.lightingTimeOfDay !== normalizedTime) {
@@ -3220,8 +3592,11 @@ export default class BabylonJSController {
         }
 
         if (config.showAnimationMenu !== undefined) {
-            // Handle show-animation-menu via the 3D component's parent
-            // This is handled in pref-viewer-3d.js attributeChangedCallback
+            const showMenu = typeof config.showAnimationMenu === "string"
+                ? config.showAnimationMenu.toLowerCase() !== "false"
+                : Boolean(config.showAnimationMenu);
+            this.#settings.showAnimationMenu = showMenu;
+            this.#syncAnimationControllerAfterModelLoad();
         }
 
         // Handle highlight color for animation hover
@@ -3242,7 +3617,7 @@ export default class BabylonJSController {
             }
             this.#setHighlightConfig({
                 color: config.highlightColor ?? undefined,
-                enabled,
+                enabled: enabled,
             });
         }
 
@@ -3281,11 +3656,13 @@ export default class BabylonJSController {
     }
 
     /**
-     * Merges incoming render flags with the current configuration, persists them, and marks
+     * Merges reload-oriented render flags with the current configuration, persists them, and marks
      * all dependent loaders/options as pending when something actually changed.
+     * Immediate settings such as highlight, animation menu, and time-of-day lighting are handled by
+     * `setIlluminationConfig()` before this method receives the remaining reload settings.
      * @public
-     * @param {{antiAliasingEnabled?:boolean, ambientOcclusionEnabled?:boolean, iblEnabled?:boolean, shadowsEnabled?:boolean}} settings Partial set of render toggles to apply.
-     * @returns {{changed:boolean, settings:{antiAliasingEnabled:boolean, ambientOcclusionEnabled:boolean, iblEnabled:boolean, shadowsEnabled:boolean}}}
+     * @param {{antiAliasingEnabled?:boolean, ambientOcclusionEnabled?:boolean, iblEnabled?:boolean, shadowsEnabled?:boolean}} settings Partial set of reload render toggles to apply.
+     * @returns {{changed:boolean, settings:object}} Current full render settings snapshot and whether a reload is required.
      * @description
      * Callers can inspect the `changed` flag to decide whether to trigger a reload with
      * `reloadWithCurrentSettings()` or simply reuse the returned snapshot.