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

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";
@@ -10,104 +10,13 @@ import { MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 import { translate } from "./localization/i18n.js";
+import { PrefViewerStyleVariables } from "./styles.js";
+import { clamp01, lerp, getAdaptiveHardwareScalingLevel, getLightingCycleProfile } from "./render-math.js";
+import { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlassMaterial, isPrefViewerTransparentRenderOrderMaterial } from "./material-utils.js";
 
-export function getAdaptiveHardwareScalingLevel(baseScaling = 1, pixelRatio = 1) {
-    const safeBaseScaling = Number.isFinite(baseScaling) && baseScaling > 0 ? baseScaling : 1;
-    const safePixelRatio = Number.isFinite(pixelRatio) && pixelRatio > 0 ? pixelRatio : 1;
-    return safeBaseScaling / safePixelRatio;
-}
-
-function clamp01(value) {
-    if (!Number.isFinite(value)) {
-        return 0.5;
-    }
-    return Math.min(1, Math.max(0, value));
-}
-
-function lerp(from, to, amount) {
-    const t = clamp01(amount);
-    return from + (to - from) * t;
-}
-
-function smoothstep(edge0, edge1, x) {
-    if (edge0 === edge1) {
-        return x >= edge1 ? 1 : 0;
-    }
-    const t = clamp01((x - edge0) / (edge1 - edge0));
-    return t * t * (3 - 2 * t);
-}
-
-function bellCurve(x) {
-    const clamped = clamp01(x);
-    return Math.sin(clamped * Math.PI);
-}
-
-function normalizeDirection(x, y, z) {
-    const length = Math.hypot(x, y, z) || 1;
-    return {
-        x: x / length,
-        y: y / length,
-        z: z / length,
-    };
-}
-
-const PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY = "prefViewerSimplifiedTransmission";
-
-export function markPrefViewerSimplifiedTransmissionMaterial(mat) {
-    if (!mat) return mat;
-    mat.metadata = {
-        ...(mat.metadata ?? {}),
-        [PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY]: true,
-    };
-    return mat;
-}
-
-export function isPrefViewerTransparentRenderOrderMaterial(mat) {
-    if (!mat) return false;
-    const isTransmissive = isPrefViewerPhysicalGlassMaterial(mat);
-    const isSimplifiedTransmission = mat.metadata?.[PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY] === true;
-    const alpha = typeof mat.alpha === "number" ? mat.alpha : 1;
-    const isAlphaBlended =
-        alpha < 1 ||
-        mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHABLEND ||
-        mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHATESTANDBLEND ||
-        mat.needAlphaBlending?.() === true ||
-        mat.needAlphaTesting?.() === true;
-
-    return Boolean(isTransmissive || isSimplifiedTransmission || isAlphaBlended);
-}
-
-export function isPrefViewerPhysicalGlassMaterial(mat) {
-    return Boolean(mat?.subSurface?.isRefractionEnabled || mat?.subSurface?.isTranslucencyEnabled);
-}
-
-export function getLightingCycleProfile(timeOfDay = 0.5) {
-    const normalizedTime = clamp01(timeOfDay);
-    const timeHours = normalizedTime * 24;
-    const sunriseHour = 6.25;
-    const sunsetHour = 20.25;
-    const daylightProgress = clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
-    const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(bellCurve(daylightProgress), 0.88) : 0;
-    const nightFactor = 1 - dayFactor;
-    const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
-    const solarAzimuth = lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
-    const solarElevation = lerp(-0.18, 1.18, solarArc);
-    const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
-    const sunDirection = normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
-    const moonDirection = normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
-
-    return {
-        timeOfDay: normalizedTime,
-        timeHours,
-        sunPhase,
-        solarAzimuth,
-        solarElevation,
-        dayFactor,
-        nightFactor,
-        sunDirection,
-        moonDirection,
-    };
-}
+// Re-export so existing consumers (tests, other modules) can keep importing from this file.
+export { getAdaptiveHardwareScalingLevel, getLightingCycleProfile } from "./render-math.js";
+export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlassMaterial, isPrefViewerTransparentRenderOrderMaterial } from "./material-utils.js";
 
 /**
  * BabylonJSController coordinates the PrefViewer 3D runtime: it bootstraps Babylon.js, manages asset containers,
@@ -130,9 +39,10 @@ export function getLightingCycleProfile(timeOfDay = 0.5) {
  *
  * Runtime Flow
  *  1. Instantiate with `new BabylonJSController(canvas, containers, options)`.
- *  2. Call `enable()` to configure Draco, spin up the engine/scene, attach interaction + XR hooks, and start the render loop.
+ *  2. Call `enable()` to configure Draco, spin up the engine/scene, and attach interaction + XR hooks. The render loop
+ *     does not start here; it starts automatically after the first `load()` completes.
  *  3. When PrefViewer marks containers/options pending, invoke `load()` (or `reloadWithCurrentSettings()`) so the controller
- *     fetches sources, rebuilds containers, and reattaches pipelines.
+ *     fetches sources, rebuilds containers, reattaches pipelines, and starts the render loop.
  *  4. Use `scheduleRenderSettingsReload()` to merge/persist toggles; when it reports `changed: true`, call
  *     `reloadWithCurrentSettings()` to apply the staged settings.
  *  5. Use `setContainerVisibility`, `setMaterialOptions`, `setCameraOptions`, or `setIBLOptions` for targeted updates; these
@@ -144,15 +54,19 @@ export function getLightingCycleProfile(timeOfDay = 0.5) {
  * 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)
+ *  - getAnimations() / playAnimation(name, action) / setAnimationProgress(name, progress) / setAnimationLoop(name, loop)
  *
  * Key Invariants
- *  - Asset containers must expose `setPendingWithCurrentStorage`/`setPending` before calling load/reload; the controller
- *    reads those flags to resolve fresh sources and avoids touching the DOM until data is ready.
+ *  - Asset containers must expose `setPendingWithCurrentStorage` before calling load/reload; the controller reads that
+ *    flag to resolve fresh sources. Option objects (camera, materials, IBL) expose `setPendingWithCurrent` for the same
+ *    purpose. Neither set of flags touches the DOM — they only gate resolver calls.
  *  - Camera-dependent pipelines (DefaultRenderingPipeline, SSAO, IBL shadows, directional shadow generators) are rebuilt
  *    only after the active camera and environment textures are ready; render-loop restarts gate those transitions.
  *  - `show-model`/`show-scene` DOM attributes reflect container visibility; there are no direct `showModel()/hideModel()` APIs.
@@ -183,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: "#ff6700",
+        highlightColor: PrefViewerStyleVariables.colorPrimary,
+        // Lighting time of day (0=midnight, 0.5=noon, 1=midnight)
+        showLightingTimeOfDay: true,
+        lightingTimeOfDay: 0.5,
     };
 
     // Canvas HTML element
@@ -207,8 +124,8 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
-    
-    #hdrTexture = null; // reusable in-memory HDR source cloned into scene.environmentTexture across reloads
+
+    #hdrTexture = null; // Reusable in-memory HDR source cloned into scene.environmentTexture across reloads
 
     #containers = {};
     #options = {};
@@ -261,30 +178,35 @@ export default class BabylonJSController {
     // Runtime configuration constants (tuning knobs, not per-frame state).
     #config = {
         pointerPicking: {
-            movePickIntervalMs: 50, // cap expensive scene.pick calls to ~20 Hz while moving the pointer
-            movePickMinDistancePx: 2, // skip picks for sub-pixel jitter
+            movePickIntervalMs: 50, // Cap expensive scene.pick calls to ~20 Hz while moving the pointer
+            movePickMinDistancePx: 2, // Skip picks for sub-pixel jitter
         },
         render: {
             burstFramesBase: 2,
-            burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
+            burstFramesEnhanced: 32, // When AA/SSAO/IBL is enabled, more frames are needed to reach stable output
             interactionMs: 250,
             animationMs: 200,
             idleThrottleMs: 1000 / 8, // Reduced from 15 FPS to 8 FPS for idle - reduces GPU/CPU load
             idleThresholdMs: 3000, // Time before going to true idle (no renders)
         },
         resize: {
-            throttleMs: 50, // cap resize work to ~20 Hz while dragging/resizing containers
+            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'
             // Applied automatically based on GPU detected capabilities
-            tier: 'medium', // default, will be updated after hardware detection
-            shadowMapSize: 1024,        // Standard shadow generator resolution
-            iblShadowResolution: 1,     // IBL shadow resolution exponent (0=1024, 1=2048, 2=4096)
-            iblSampleDirections: 4,     // IBL shadow quality
-            shadowBlurKernel: 16,       // Shadow blur amount
-            ssaoEnabled: true,         // Screen Space Ambient Occlusion
+            tier: 'medium',          // Default, will be updated after hardware detection
+            shadowMapSize: 1024,     // Standard shadow generator resolution
+            iblShadowResolution: 1,  // IBL shadow resolution exponent (0=1024, 1=2048, 2=4096)
+            iblSampleDirections: 4,  // IBL shadow quality
+            shadowBlurKernel: 16,    // Shadow blur amount
+            ssaoEnabled: true,       // Screen Space Ambient Occlusion
         },
         look: {
             showroom: {
@@ -296,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],
             },
         },
     };
@@ -309,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) {
@@ -339,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) {
@@ -366,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)) {
@@ -382,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;
     }
@@ -398,48 +338,48 @@ 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+
-            /iPad Pro/i,                   // iPad Pro
-            /SM-S91[0-9]/i,              // Samsung S21+
-            /SM-S9[0-9]/i,               // Samsung S20+
-            /Pixel [7-9]/i,              // Pixel 7+
-            /OnePlus [8-9|10|11]/i,      // OnePlus 8+
+            /iPad Pro/i,                  // iPad Pro
+            /SM-S91[0-9]/i,               // Samsung S21+
+            /SM-S9[0-9]/i,                // Samsung S20+
+            /Pixel [7-9]/i,               // Pixel 7+
+            /OnePlus [8-9|10|11]/i,       // OnePlus 8+
             /Xiaomi (1[2-4]|Mi 1[1-4])/i, // Xiaomi 12+
-            /Huawei (P50|Mate 4|)/i,     // Huawei P50+
+            /Huawei (P50|Mate 4|)/i,      // Huawei P50+
         ];
-        
+
         // Mid-range patterns
         const midRangePatterns = [
-            /iPhone (1[0-3]|SE)/i,       // iPhone 10-13
+            /iPhone (1[0-3]|SE)/i,        // iPhone 10-13
             /iPad Air/i,                  // iPad Air
-            /SM-A[0-9]/i,                // Samsung A series
-            /Redmi Note/i,               // Redmi Note
-            /Pixel [4-6]/i,              // Pixel 4-6
-            /Moto G/i,                   // Moto G
+            /SM-A[0-9]/i,                 // Samsung A series
+            /Redmi Note/i,                // Redmi Note
+            /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) {
@@ -451,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,
@@ -476,13 +416,13 @@ export default class BabylonJSController {
             // Mobile low-end (old phones, budget devices)
             low: {
                 shadowMapSize: 256,              // Very small for speed
-                iblShadowResolution: -1,        // Disable IBL shadows
+                iblShadowResolution: -1,         // Disable IBL shadows
                 iblSampleDirections: 1,          // Minimal sampling
                 shadowBlurKernel: 0,             // No blur
                 ssaoEnabled: false,
                 antialiasingEnabled: false,
-                hardwareScaling: 2.5,           // Aggressive downscaling
-                maxModelResolution: 512,          // Low-res model loading
+                hardwareScaling: 2.5,            // Aggressive downscaling
+                maxModelResolution: 512,         // Low-res model loading
                 environmentTextureSize: 512,
             },
             // Mobile high-end / Tablet / Desktop low
@@ -500,7 +440,7 @@ export default class BabylonJSController {
             // Desktop mid-range / High-end mobile
             high: {
                 shadowMapSize: 1024,
-                iblShadowResolution: 0,          // 1024x1024 - good balance
+                iblShadowResolution: 0,           // 1024x1024 - good balance
                 iblSampleDirections: 4,           // Quality sampling
                 shadowBlurKernel: 8,              // Sharper shadows for product clarity
                 ssaoEnabled: false,
@@ -512,9 +452,9 @@ export default class BabylonJSController {
             // Desktop high-end (RTX, Apple Silicon, etc.)
             ultra: {
                 shadowMapSize: 2048,
-                iblShadowResolution: 1,          // 2048x2048
+                iblShadowResolution: 1,           // 2048x2048
                 iblSampleDirections: 8,           // Maximum quality
-                shadowBlurKernel: 16,            // Preserve clarity over softness
+                shadowBlurKernel: 16,             // Preserve clarity over softness
                 ssaoEnabled: false,
                 antialiasingEnabled: true,
                 hardwareScaling: 1.0,             // Native resolution
@@ -532,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,
@@ -729,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
@@ -756,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.
@@ -891,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;
     }
 
@@ -932,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;
 
@@ -1658,81 +1647,6 @@ export default class BabylonJSController {
         });
     }
 
-    /**
-     * Fixes cross-GLTF transparency ordering. Detects transparent/transmissive meshes
-     * (alpha-blended, alpha-tested, simplified environment transmission, or
-     * KHR_materials_transmission) across all loaded containers and moves them to
-     * renderingGroupId=1 with depth-write disabled.
-     * This ensures opaque scene geometry (e.g. lamp cups behind a model window) is
-     * written to the depth buffer first (group 0) so the glass layer composites on top
-     * without occluding it.
-     * @private
-     * @returns {void}
-     */
-    #applyTransmittanceRenderOrder() {
-        if (!this.#scene) return;
-
-        const envMeshIds = new Set(
-            this.#containers.environment?.assetContainer?.meshes.map((m) => m.uniqueId) ?? []
-        );
-        const modelMeshIds = new Set(
-            this.#containers.model?.assetContainer?.meshes.map((m) => m.uniqueId) ?? []
-        );
-
-        // Map each material to the model meshes using it — needed to detect shared materials
-        // before modifying an env mesh's material (must clone to avoid breaking model glass).
-        const matToModelMeshes = new Map();
-        this.#scene.meshes.forEach((mesh) => {
-            if (!modelMeshIds.has(mesh.uniqueId) || !mesh.material) return;
-            if (!matToModelMeshes.has(mesh.material)) matToModelMeshes.set(mesh.material, new Set());
-            matToModelMeshes.get(mesh.material).add(mesh.uniqueId);
-        });
-
-        this.#scene.meshes.forEach((mesh) => {
-            const mat = mesh.material;
-            if (!mat) return;
-            const isTransmissive = isPrefViewerPhysicalGlassMaterial(mat);
-            const isTransparentLike = isPrefViewerTransparentRenderOrderMaterial(mat);
-            if (!isTransparentLike) return;
-
-            if (envMeshIds.has(mesh.uniqueId)) {
-                // Environment mesh carrying a transmissive material introduced by a material swap
-                // (initial-load materials are pre-simplified in #assetContainer_simplifyTransmissiveMaterials).
-                // Clone if shared with a model mesh so the model's physical glass is not affected.
-                let targetMat = mat;
-                if (matToModelMeshes.has(mat)) {
-                    targetMat = mat.clone(`${mat.name}_env_simplified`);
-                    mesh.material = targetMat;
-                }
-                if (isTransmissive) {
-                    this.#simplifyTransmissiveMaterial(targetMat);
-                }
-                mesh.renderingGroupId = 1;
-                targetMat.disableDepthWrite = true;
-                targetMat.alphaIndex = 0;
-            } else if (modelMeshIds.has(mesh.uniqueId)) {
-                // Model transparent materials render after all group-0 geometry.
-                mesh.renderingGroupId = 1;
-                mat.disableDepthWrite = true;
-
-                // Physical model glass keeps transmission, but strips volume absorption (tintColor)
-                // and roughness because those blur/darken transmitted geometry. Do not apply this
-                // tuning to plain alpha-blended model materials: render-order and physical glass
-                // material tuning are separate concerns.
-                if (isTransmissive && mat.subSurface) {
-                    mat.subSurface.tintColor = Color3.White();
-                    mat.roughness = 0;
-                }
-                mat.alphaIndex = 1;
-            } else {
-                // Unknown container (future-proof safe default).
-                mesh.renderingGroupId = 1;
-                mat.disableDepthWrite = true;
-                mat.alphaIndex = 1;
-            }
-        });
-    }
-
     /**
      * Applies the showroom tonemapping curve and lighting bias used by the 3D viewer.
      * @private
@@ -1746,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;
@@ -1770,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;
@@ -1786,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);
@@ -1863,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
@@ -2093,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.
@@ -2104,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.
      */
@@ -2117,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;
     }
 
@@ -2150,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;
@@ -2190,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();
@@ -2215,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 });
@@ -2437,6 +2427,7 @@ export default class BabylonJSController {
             }
         }
         this.#applyShowroomCameraFraming(camera);
+        this.#fitDefaultCameraToModel(camera);
         this.#scene.activeCamera?.detachControl();
         camera.detachControl();
         if (!cameraState.locked) {
@@ -2863,21 +2854,34 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#enhanceTextureQuality();
-                this.#applyTransmittanceRenderOrder();
-                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.
@@ -3131,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,
@@ -3159,6 +3163,7 @@ export default class BabylonJSController {
         this.#scene.skipPointerUpPicking = true;
 
         this.#createCamera();
+        await this.#ensureEnvironmentBRDFTextureReady();
         this.#enableInteraction();
         await this.#createXRExperience();
     }
@@ -3314,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.
@@ -3346,7 +3527,6 @@ export default class BabylonJSController {
     setMaterialOptions() {
         this.#stopRender();
         const materialsOptionsSetted = this.#setOptions_Materials();
-        this.#applyTransmittanceRenderOrder();
         this.#startRender();
         return materialsOptionsSetted;
     }
@@ -3367,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) {
@@ -3384,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
@@ -3406,7 +3617,7 @@ export default class BabylonJSController {
             }
             this.#setHighlightConfig({
                 color: config.highlightColor ?? undefined,
-                enabled,
+                enabled: enabled,
             });
         }
 
@@ -3445,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.