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

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,74 +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,
-    };
-}
-
-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,
@@ -100,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
@@ -114,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.
@@ -153,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
@@ -165,8 +112,6 @@ export default class BabylonJSController {
     // References to parent custom elements
     #prefViewer3D = undefined;
     #prefViewer = undefined;
-    #modelFirstPaintedEmitted = false;
-    #modelFirstPaintedLoadToken = 0;
 
     // Babylon.js core objects
     #engine = null;
@@ -176,23 +121,17 @@ export default class BabylonJSController {
     #dirLight = null;
     #moonLight = null;
     #cameraLight = null;
-    #debugCameraFrameInfo = null;
     #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 = {};
 
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
-    #loadingInProgress = false; // blocks #requestRender while assets are loading to prevent WebGL errors from rendering with disposed shaders
-    #isLoadingModelIndependent = false;       // guards against concurrent independent model loads
-    #isLoadingEnvironmentIndependent = false; // guards against concurrent independent environment loads
-    #isLoadingMaterialsIndependent = false;   // guards against concurrent independent materials loads
-    #startRenderInProgress = false; // true while #startRender() is running (after #loadingInProgress clears)
 
     #renderPipelines = {
         default: null,
@@ -239,30 +178,30 @@ 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
         },
         // 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: {
@@ -287,18 +226,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) {
@@ -317,7 +256,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) {
@@ -344,15 +283,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)) {
@@ -360,7 +299,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;
     }
@@ -376,48 +315,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) {
@@ -429,7 +368,7 @@ export default class BabylonJSController {
             const match = userAgent.match(/Android.*;.*(.+?)\)/);
             deviceName = match ? match[1].trim() : 'Android';
         }
-        
+
         return {
             isMobile: isMobilePhone && !isDesktopLike,
             isTablet: isTablet && !isDesktopLike,
@@ -454,13 +393,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
@@ -478,7 +417,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,
@@ -490,9 +429,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
@@ -510,10 +449,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,
@@ -707,6 +646,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
@@ -734,7 +722,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.
@@ -756,8 +744,8 @@ export default class BabylonJSController {
      * @param {number} [options.continuousMs=0] - Milliseconds to keep continuous rendering active.
      * @returns {boolean} True when the request was accepted, false when scene/engine are unavailable.
      */
-    #requestRender({ frames = 1, continuousMs = 0, force = false } = {}) {
-        if (!this.#scene || !this.#engine || (this.#loadingInProgress && !force)) {
+    #requestRender({ frames = 1, continuousMs = 0 } = {}) {
+        if (!this.#scene || !this.#engine) {
             return false;
         }
 
@@ -869,12 +857,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;
     }
 
@@ -910,7 +898,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;
 
@@ -1120,11 +1108,6 @@ export default class BabylonJSController {
 
         const pipelineName = "PrefViewerSSAORenderingPipeline";
 
-        // Skip recreation if already alive — same reason as DefaultRenderingPipeline guard
-        if (this.#renderPipelines.ssao && supportedPipelines.find((p) => p.name === pipelineName)) {
-            return true;
-        }
-
         const ssaoRatio = {
             ssaoRatio: 0.5,
             combineRatio: 1.0,
@@ -1226,21 +1209,6 @@ export default class BabylonJSController {
 
         const pipelineName = "PrefViewerDefaultRenderingPipeline";
 
-        // Skip recreation if the pipeline is already alive — creating a new DefaultRenderingPipeline
-        // while one exists disposes the underlying GeometryBufferRenderer, deleting GL programs that
-        // subMeshes still reference, causing useProgram:deleted errors on the next render frame.
-        if (this.#renderPipelines.default && supportedPipelines.find((p) => p.name === pipelineName)) {
-            return true;
-        }
-
-        // Purge stale effect cache before creating a new pipeline. pipeline.dispose() calls
-        // gl.deleteProgram() per post-process but leaves entries in Engine._compiledEffects.
-        // A new DefaultRenderingPipeline with the same shader key gets a cache hit and receives
-        // the deleted program → useProgram:deleted on the first render frame.
-        // Safe here because #startRender always stops the loop before reaching this point.
-        this.#scene.getEngine().releaseEffects?.();
-        this.#scene.getEngine().releaseComputeEffects?.();
-
         let defaultPipeline = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
 
         if (!defaultPipeline) {
@@ -1418,11 +1386,6 @@ export default class BabylonJSController {
 
         const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
-        // Skip recreation if already alive — same reason as DefaultRenderingPipeline guard
-        if (this.#renderPipelines.iblShadows && supportedPipelines.find((p) => p.name === pipelineName)) {
-            return true;
-        }
-
         // Use hardware-adaptive quality settings
         const pipelineOptions = {
             resolutionExp: this.#config.quality.iblShadowResolution, // Adaptive: 0=1024, 1=2048, 2=4096
@@ -1674,7 +1637,7 @@ export default class BabylonJSController {
         const showroom = this.#config.look?.showroom || {};
         const imageProcessing = this.#scene.imageProcessingConfiguration;
 
-        this.#scene.clearColor = new Color4(1, 1, 1, 1).toLinearSpace();
+        this.#scene.clearColor = new Color4(0.98, 0.98, 0.98, 1).toLinearSpace();
         imageProcessing.exposure = showroom.exposure ?? 0.95;
         imageProcessing.contrast = showroom.contrast ?? 1.08;
         imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
@@ -1698,7 +1661,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;
@@ -1714,7 +1677,12 @@ export default class BabylonJSController {
             imageProcessing.colorCurvesEnabled = false;
         }
 
-        this.#scene.clearColor = new Color4(1, 1, 1, 1).toLinearSpace();
+        this.#scene.clearColor = new Color4(
+            lerp(0.035, 0.98, daylight),
+            lerp(0.045, 0.98, daylight),
+            lerp(0.085, 0.98, daylight),
+            1,
+        ).toLinearSpace();
 
         if ("environmentIntensity" in this.#scene) {
             this.#scene.environmentIntensity = lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
@@ -2016,7 +1984,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.
@@ -2027,12 +1995,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.
      */
@@ -2040,7 +2008,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;
     }
 
@@ -2073,12 +2041,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;
@@ -2113,7 +2081,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();
@@ -2138,7 +2106,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 });
@@ -2203,10 +2171,6 @@ export default class BabylonJSController {
             }
             this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
             console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
-            // Stop the loop before resize: engine.resize() rebuilds DefaultRenderingPipeline
-            // via onResizeObservable, which disposes GL programs. If the loop is running,
-            // the next frame would call useProgram on a deleted program → INVALID_OPERATION.
-            this.#stopEngineRenderLoop();
             this.#applyShowroomCameraFraming();
             this.#engine.resize();
             const needsEnhancedBurst = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled || this.#settings.shadowsEnabled;
@@ -2249,7 +2213,7 @@ export default class BabylonJSController {
      * @param {MaterialData} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
      * @returns {boolean} True if any mesh material was set, false otherwise.
      */
-    #setOptionsMaterial(optionMaterial, force = false) {
+    #setOptionsMaterial(optionMaterial) {
         if (!optionMaterial || !(optionMaterial.value || (optionMaterial.isPending && optionMaterial.update.value)) || !(optionMaterial.nodePrefixes.length || optionMaterial.nodeNames.length)) {
             return false;
         }
@@ -2267,7 +2231,7 @@ export default class BabylonJSController {
             if (container.state.name === "materials") {
                 return;
             }
-            if (container.assetContainer && (force || container.state.isPending || materialContainer.state.isPending || optionMaterial.isPending)) {
+            if (container.assetContainer && (container.state.isPending || materialContainer.state.isPending || optionMaterial.isPending)) {
                 assetContainersToProcess.push(container.assetContainer);
             }
         });
@@ -2278,7 +2242,7 @@ export default class BabylonJSController {
         let someSetted = false;
         assetContainersToProcess.forEach((assetContainer) =>
             assetContainer.meshes
-                .filter((meshToFilter) => optionMaterial.nodePrefixes.some((prefix) => meshToFilter.name.startsWith(prefix)) || optionMaterial.nodeNames.includes(meshToFilter.name))
+                .filter((meshToFilter) => optionMaterial.nodePrefixes.some((prefix) => meshToFilter.name.toLowerCase().startsWith(prefix.toLowerCase())) || optionMaterial.nodeNames.some((n) => n.toLowerCase() === meshToFilter.name.toLowerCase()))
                 .forEach((mesh) => {
                     mesh.material = material;
                     someSetted = true;
@@ -2300,10 +2264,10 @@ export default class BabylonJSController {
      * @private
      * @returns {boolean} True if any material option was set, false otherwise.
      */
-    #setOptions_Materials(force = false) {
+    #setOptions_Materials() {
         let someSetted = false;
         Object.values(this.#options.materials).forEach((material) => {
-            let settedMaterial = this.#setOptionsMaterial(material, force);
+            let settedMaterial = this.#setOptionsMaterial(material);
             someSetted = someSetted || settedMaterial;
         });
         return someSetted;
@@ -2412,9 +2376,7 @@ export default class BabylonJSController {
             prefViewer3D = host?.nodeName === "PREF-VIEWER-3D" ? host : undefined;
         }
 
-        if (prefViewer3D) {
-            this.#prefViewer3D = prefViewer3D;
-        }
+        this.#prefViewer3D = prefViewer3D;
     }
 
     /**
@@ -2429,6 +2391,7 @@ export default class BabylonJSController {
 
         this.#getPrefViewer3DComponent();
         if (this.#prefViewer3D === undefined) {
+            this.#prefViewer = undefined;
             return;
         }
 
@@ -2438,9 +2401,7 @@ export default class BabylonJSController {
             prefViewer = host?.nodeName === "PREF-VIEWER" ? host : undefined;
         }
 
-        if (prefViewer) {
-            this.#prefViewer = prefViewer;
-        }
+        this.#prefViewer = prefViewer;
     }
 
     /**
@@ -2454,94 +2415,13 @@ export default class BabylonJSController {
         // Cache references to parent custom elements
         this.#getPrefViewer3DComponent();
         this.#getPrefViewerComponent();
-        const syncVisibility = (component, fallbackAttr) => {
-            if (!component) {
-                return;
-            }
-            if (typeof component.syncVisibility === "function") {
-                component.syncVisibility(name, isVisible);
-                return;
-            }
-            component.setAttribute(fallbackAttr, isVisible ? "true" : "false");
-        };
         if (name === "model") {
-            syncVisibility(this.#prefViewer3D, "show-model");
-            syncVisibility(this.#prefViewer, "show-model");
+            this.#prefViewer3D?.setAttribute("show-model", isVisible ? "true" : "false");
+            this.#prefViewer?.setAttribute("show-model", isVisible ? "true" : "false");
         } else if (name === "environment") {
-            syncVisibility(this.#prefViewer3D, "show-scene");
-            syncVisibility(this.#prefViewer, "show-scene");
-        }
-    }
-
-    /**
-     * Dispatches a "model-first-painted" event once the model-only preview has had a chance to render a frame.
-     * @private
-     * @param {object} [detail] - Optional metadata describing the paint gate.
-     * @returns {void}
-     */
-    #emitModelFirstPainted(detail = {}) {
-        this.#getPrefViewer3DComponent();
-        this.#getPrefViewerComponent();
-        const target = this.#prefViewer || this.#prefViewer3D || this.#canvas;
-        if (!target) {
-            return;
-        }
-
-        const customEventOptions = {
-            bubbles: true,
-            cancelable: false,
-            composed: true,
-            detail,
-        };
-        target.dispatchEvent(new CustomEvent("model-first-painted", customEventOptions));
-    }
-
-    /**
-     * Dispatches a granular 3D load phase event so the ecommerce trace UI can measure tail phases.
-     * @private
-     * @param {string} phase - Phase event name.
-     * @param {object} [detail] - Optional phase metadata.
-     * @returns {void}
-     */
-    #emitSceneLoadPhase(phase, detail = {}) {
-        this.#getPrefViewer3DComponent();
-        this.#getPrefViewerComponent();
-        const target = this.#prefViewer || this.#prefViewer3D || this.#canvas;
-        if (!target) {
-            return;
+            this.#prefViewer3D?.setAttribute("show-scene", isVisible ? "true" : "false");
+            this.#prefViewer?.setAttribute("show-scene", isVisible ? "true" : "false");
         }
-
-        const customEventOptions = {
-            bubbles: true,
-            cancelable: false,
-            composed: true,
-            detail,
-        };
-        target.dispatchEvent(new CustomEvent(phase, customEventOptions));
-    }
-
-    /**
-     * Waits for one or more animation frames so the browser can paint the current model-only state.
-     * @private
-     * @param {number} [frameCount=2] - Number of animation frames to wait.
-     * @returns {Promise<void>}
-     */
-    async #waitForPaint(frameCount = 2) {
-        if (typeof requestAnimationFrame !== "function") {
-            return;
-        }
-
-        const totalFrames = Math.max(1, frameCount);
-        await new Promise((resolve) => {
-            const step = (remaining) => {
-                if (remaining <= 0) {
-                    resolve();
-                    return;
-                }
-                requestAnimationFrame(() => step(remaining - 1));
-            };
-            requestAnimationFrame(() => step(totalFrames - 1));
-        });
     }
 
     /**
@@ -2589,7 +2469,7 @@ export default class BabylonJSController {
      * @param {AssetContainer} newAssetContainer - The new asset container to add to the scene.
      * @returns {boolean} True if the container was replaced and added, false otherwise.
      */
-    #replaceContainer(container, newAssetContainer, { releaseEffects = true } = {}) {
+    #replaceContainer(container, newAssetContainer) {
         if (container.assetContainer) {
             this.#removeContainer(container, false);
             container.assetContainer.dispose();
@@ -2601,13 +2481,8 @@ export default class BabylonJSController {
             newAssetContainer?.dispose();
             return false;
         }
-        // Skip releaseEffects when the render loop is active: deleting GL programs while frames
-        // are being produced causes useProgram:deleted errors. Also skipped when the caller
-        // explicitly passes releaseEffects:false (e.g. loadContainerIndependent).
-        if (releaseEffects && !this.#state.render.isLoopRunning) {
-            this.#scene.getEngine().releaseEffects();
-            this.#scene.getEngine().releaseComputeEffects();
-        }
+        this.#scene.getEngine().releaseEffects();
+        this.#scene.getEngine().releaseComputeEffects();
 
         container.assetContainer = newAssetContainer;
         return this.#addContainer(container, false);
@@ -2643,6 +2518,40 @@ export default class BabylonJSController {
         assetContainer.lights = [];
     }
 
+    /**
+     * Strips KHR_materials_transmission, KHR_materials_ior and KHR_materials_volume from
+     * environment-container (scene) materials, converting them to simple alpha blending.
+     * Babylon.js cannot render two physical-transmission materials (from separate GLTF
+     * containers) through each other: the scene decorative glass (lamp cups, etc.) is
+     * simplified so the model's physical glass keeps full correct transmission.
+     * @private
+     * @param {AssetContainer} assetContainer
+     * @returns {void}
+     */
+    #assetContainer_simplifyTransmissiveMaterials(assetContainer) {
+        assetContainer.materials?.forEach((mat) => {
+            if (!(mat instanceof PBRMaterial)) return;
+            if (!mat.subSurface?.isRefractionEnabled && !mat.subSurface?.isTranslucencyEnabled) return;
+            this.#simplifyTransmissiveMaterial(mat);
+        });
+    }
+
+    /**
+     * Converts a single PBRMaterial from physical KHR_materials_transmission to simple alpha
+     * blending. Shared helper used by both the at-load simplification and the post-swap pass.
+     * @private
+     * @param {PBRMaterial} mat
+     * @returns {void}
+     */
+    #simplifyTransmissiveMaterial(mat) {
+        const intensity = mat.subSurface.refractionIntensity ?? 1.0;
+        mat.subSurface.isRefractionEnabled = false;
+        mat.subSurface.isTranslucencyEnabled = false;
+        mat.alpha = Math.max(0.28, 1.0 - intensity * 0.65);
+        mat.transparencyMode = PBRMaterial.PBRMATERIAL_ALPHABLEND;
+        markPrefViewerSimplifiedTransmissionMaterial(mat);
+    }
+
     /**
      * Assigns unique ids to every imported camera so Babylon.js does not reuse stale SSAO effects between reloads.
      * @private
@@ -2669,207 +2578,10 @@ export default class BabylonJSController {
         if (!this.#containers.model.assetContainer || !this.#containers.model.state.isVisible) {
             return false;
         }
-        // In model-only previews, or while the environment is still loading, keep wall/floor meshes visible.
-        // Only defer to the environment's visibility after it has fully loaded.
-        show = show !== undefined
-            ? show
-            : (this.#containers.environment.state.isSuccess
-                ? this.#containers.environment.state.isVisible
-                : true);
+        show = show !== undefined ? show : this.#containers.environment.state.isVisible;
         const nodePrefixes = Object.values(this.#options.materials).flatMap((material) => material.nodePrefixes);
         const nodeNames = Object.values(this.#options.materials).flatMap((material) => material.nodeNames);
-        this.#containers.model.assetContainer.meshes.filter((meshToFilter) => nodePrefixes.some((prefix) => meshToFilter.name.startsWith(prefix)) || nodeNames.includes(meshToFilter.name)).forEach((mesh) => mesh.setEnabled(show));
-    }
-
-    /**
-     * Frames the active ArcRotateCamera around the visible model when no environment scene is loaded.
-     * @private
-     * @returns {boolean} True if the camera was adjusted, otherwise false.
-     */
-    #frameCameraToModel({ allowWhenEnvironmentVisible = false } = {}) {
-        const camera = this.#scene?.activeCamera instanceof ArcRotateCamera
-            ? this.#scene.activeCamera
-            : this.#camera;
-        const modelContainer = this.#containers.model;
-        const inspect = {
-            cameraType: camera?.getClassName?.() ?? camera?.constructor?.name ?? null,
-            hasModelContainer: !!modelContainer.assetContainer,
-            modelVisible: modelContainer.state.isVisible,
-            envHasContainer: !!this.#containers.environment.assetContainer,
-            envVisible: this.#containers.environment.state.isVisible,
-            meshCount: modelContainer.assetContainer?.meshes?.length ?? 0,
-        };
-        this.#debugCameraFrameInfo = { phase: "inspect", ...inspect };
-        console.log("[viewer] frameCameraToModel inspect", inspect);
-        if (!(camera instanceof ArcRotateCamera) || !modelContainer.assetContainer || !modelContainer.state.isVisible) {
-            this.#debugCameraFrameInfo = {
-                phase: "skipped",
-                reason: !(camera instanceof ArcRotateCamera)
-                    ? "no-arcrotate-camera"
-                    : !modelContainer.assetContainer
-                        ? "no-model"
-                        : !modelContainer.state.isVisible
-                            ? "model-hidden"
-                            : "unknown",
-                ...inspect,
-            };
-            return false;
-        }
-        if (!allowWhenEnvironmentVisible && this.#containers.environment.assetContainer && this.#containers.environment.state.isVisible) {
-            this.#debugCameraFrameInfo = {
-                phase: "skipped",
-                reason: "environment-visible",
-                ...inspect,
-            };
-            return false;
-        }
-
-        let min = null;
-        let max = null;
-        modelContainer.assetContainer.meshes.forEach((mesh) => {
-            if (!mesh?.getTotalVertices?.() || mesh.getTotalVertices() <= 0) {
-                return;
-            }
-            mesh.computeWorldMatrix?.(true);
-            const boundingBox = mesh.getBoundingInfo?.()?.boundingBox;
-            if (!boundingBox) {
-                return;
-            }
-            const minimum = boundingBox.minimumWorld;
-            const maximum = boundingBox.maximumWorld;
-            if (!minimum || !maximum) {
-                return;
-            }
-            min = min
-                ? new Vector3(Math.min(min.x, minimum.x), Math.min(min.y, minimum.y), Math.min(min.z, minimum.z))
-                : minimum.clone();
-            max = max
-                ? new Vector3(Math.max(max.x, maximum.x), Math.max(max.y, maximum.y), Math.max(max.z, maximum.z))
-                : maximum.clone();
-        });
-
-        if (!min || !max) {
-            const skipped = {
-                hasCamera: camera instanceof ArcRotateCamera,
-                hasModel: !!modelContainer.assetContainer,
-                modelVisible: modelContainer.state.isVisible,
-                environmentVisible: this.#containers.environment.state.isVisible,
-            };
-            this.#debugCameraFrameInfo = {
-                phase: "skipped",
-                reason: "no-bounds",
-                ...inspect,
-                ...skipped,
-            };
-            console.log("[viewer] frameCameraToModel skipped (no bounds)", skipped);
-            return false;
-        }
-
-        const size = max.subtract(min);
-        const largestDimension = Math.max(size.x, size.y, size.z);
-        if (!Number.isFinite(largestDimension) || largestDimension <= 0) {
-            return false;
-        }
-
-        const center = min.add(max).scale(0.5);
-        camera.setTarget(center);
-        const radiusMultiplier = allowWhenEnvironmentVisible ? 1.7 : 1.4;
-        camera.radius = Math.min(
-            Math.max(largestDimension * radiusMultiplier, camera.lowerRadiusLimit ?? largestDimension * radiusMultiplier),
-            camera.upperRadiusLimit ?? largestDimension * radiusMultiplier,
-        );
-        // Keep the initial model-only view aligned to the showroom's frontal composition.
-        // This preserves the user's camera intent once the scene becomes visible, but gives
-        // the standalone model a consistent front-facing presentation.
-        // Rotate the front-facing composition 180° while keeping the same framing/radius.
-        camera.alpha = Math.PI;
-        camera.beta = Math.PI * 0.47;
-        console.log("[viewer] frameCameraToModel applied", {
-            center,
-            size,
-            radius: camera.radius,
-        });
-        this.#debugCameraFrameInfo = {
-            phase: "applied",
-            ...inspect,
-            center: { x: center.x, y: center.y, z: center.z },
-            size: { x: size.x, y: size.y, z: size.z },
-            radius: camera.radius,
-            cameraTarget: camera.target ? { x: camera.target.x, y: camera.target.y, z: camera.target.z } : null,
-            cameraPosition: camera.position ? { x: camera.position.x, y: camera.position.y, z: camera.position.z } : null,
-            cameraLocked: !!camera.metadata?.locked,
-        };
-        return true;
-    }
-
-    /**
-     * Public wrapper to force the active camera to frame the visible model.
-     * @public
-     * @returns {boolean}
-     */
-    focusModel() {
-        return this.#frameCameraToModel();
-    }
-
-    /**
-     * Returns a compact snapshot of the current debug-relevant 3D state.
-     * @public
-     * @returns {object}
-     */
-    getDebugState() {
-        const activeCamera = this.#scene?.activeCamera ?? this.#camera ?? null;
-        const modelMeshes = this.#containers.model?.assetContainer?.meshes ?? [];
-        let boundsMin = null;
-        let boundsMax = null;
-        for (const mesh of modelMeshes) {
-            if (!mesh?.getTotalVertices?.() || mesh.getTotalVertices() <= 0) continue;
-            mesh.computeWorldMatrix?.(true);
-            const boundingBox = mesh.getBoundingInfo?.()?.boundingBox;
-            if (!boundingBox?.minimumWorld || !boundingBox?.maximumWorld) continue;
-            const minimum = boundingBox.minimumWorld;
-            const maximum = boundingBox.maximumWorld;
-            boundsMin = boundsMin
-                ? { x: Math.min(boundsMin.x, minimum.x), y: Math.min(boundsMin.y, minimum.y), z: Math.min(boundsMin.z, minimum.z) }
-                : { x: minimum.x, y: minimum.y, z: minimum.z };
-            boundsMax = boundsMax
-                ? { x: Math.max(boundsMax.x, maximum.x), y: Math.max(boundsMax.y, maximum.y), z: Math.max(boundsMax.z, maximum.z) }
-                : { x: maximum.x, y: maximum.y, z: maximum.z };
-        }
-        const modelBounds = boundsMin && boundsMax ? {
-            min: boundsMin,
-            max: boundsMax,
-            center: {
-                x: (boundsMin.x + boundsMax.x) / 2,
-                y: (boundsMin.y + boundsMax.y) / 2,
-                z: (boundsMin.z + boundsMax.z) / 2,
-            },
-            size: {
-                x: boundsMax.x - boundsMin.x,
-                y: boundsMax.y - boundsMin.y,
-                z: boundsMax.z - boundsMin.z,
-            },
-        } : null;
-        return {
-            camera: activeCamera ? {
-                className: activeCamera.getClassName?.() ?? activeCamera.constructor?.name ?? null,
-                position: activeCamera.position ? { x: activeCamera.position.x, y: activeCamera.position.y, z: activeCamera.position.z } : null,
-                target: activeCamera.target ? { x: activeCamera.target.x, y: activeCamera.target.y, z: activeCamera.target.z } : null,
-                radius: typeof activeCamera.radius === "number" ? activeCamera.radius : null,
-                locked: !!activeCamera.metadata?.locked,
-            } : null,
-            model: {
-                visible: !!this.#containers.model?.state?.isVisible,
-                hasContainer: !!this.#containers.model?.assetContainer,
-                meshCount: this.#containers.model?.assetContainer?.meshes?.length ?? 0,
-                bounds: modelBounds,
-            },
-            environment: {
-                visible: !!this.#containers.environment?.state?.isVisible,
-                hasContainer: !!this.#containers.environment?.assetContainer,
-            },
-            lastCameraFrame: this.#debugCameraFrameInfo,
-            renderLoopRunning: !!this.#state?.render?.isLoopRunning,
-        };
+        this.#containers.model.assetContainer.meshes.filter((meshToFilter) => nodePrefixes.some((prefix) => meshToFilter.name.toLowerCase().startsWith(prefix.toLowerCase())) || nodeNames.some((n) => n.toLowerCase() === meshToFilter.name.toLowerCase())).forEach((mesh) => mesh.setEnabled(show));
     }
 
     /**
@@ -2889,25 +2601,12 @@ export default class BabylonJSController {
      * @private
      * @returns {Promise<void>}
      */
-    async #startRender({ skipWhenReady = false, forceRender = false, skipCameraDependentEffects = false } = {}) {
+    async #startRender() {
         if (!this.#scene) return;
-        this.#startRenderInProgress = true;
-        try {
-            if (!skipCameraDependentEffects) {
-                await this.#loadCameraDependentEffects();
-            }
-            // skipWhenReady: model materials already compiled via compileMaterials:true.
-            // Skips scene-wide whenReadyAsync so the model appears immediately (~1s).
-            if (!skipWhenReady) {
-                await this.#scene.whenReadyAsync();
-            }
-            const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
-            // forceRender: bypasses #loadingInProgress gate so loadContainerIndependent
-            // can show the model preview while #loadContainers is still loading scene/materials.
-            this.#requestRender({ frames: frames, continuousMs: this.#config.render.interactionMs, force: forceRender });
-        } finally {
-            this.#startRenderInProgress = false;
-        }
+        await this.#loadCameraDependentEffects();
+        await this.#scene.whenReadyAsync();
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
+        this.#requestRender({ frames: frames, continuousMs: this.#config.render.interactionMs });
     }
 
     /**
@@ -2926,7 +2625,7 @@ export default class BabylonJSController {
      * 3. Builds the Babylon plugin options so extras are surfaced as metadata, then imports the container with
      *    `LoadAssetContainerAsync`, returning the tuple so the caller can decide how to attach it to the scene.
      */
-    async #loadAssetContainer(container, force = false, { isIndependent = false } = {}) {
+    async #loadAssetContainer(container, force = false) {
         if (container?.state?.update?.storage === undefined || container?.state?.size === undefined || container?.state?.timeStamp === undefined) {
             return [container, false];
         }
@@ -2942,30 +2641,12 @@ export default class BabylonJSController {
         const currentSize = force ? 0 : container.state.size;
         const currentTimeStamp = force ? null : container.state.timeStamp;
 
-        const storageType = container.state.update.storage?.db ? "idb" : container.state.update.storage?.url ? "url" : "?";
-        const storageId = container.state.update.storage?.id ?? container.state.update.storage?.url ?? "?";
-        const tResolve = performance.now();
         let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, currentSize, currentTimeStamp);
-        console.log(`[perf][${container.state.name}] getSource(${storageType}:${storageId}) ${Math.round(performance.now() - tResolve)}ms → ${sourceData ? `${sourceData.extension} ${sourceData.objectURLs?.length ?? 0} assets` : "skipped"}`);
 
         if (!sourceData) {
             return [container, false];
         }
 
-        // Abort if loadContainerIndependent claimed this container while getSource was in flight.
-        // isIndependent=true means THIS call IS the independent load — don't abort yourself.
-        // Returns null (not false) so #loadContainers skips setSuccess(false) for this container.
-        const isClaimedIndependently =
-            (container.state.name === "model" && this.#isLoadingModelIndependent) ||
-            (container.state.name === "environment" && this.#isLoadingEnvironmentIndependent) ||
-            (container.state.name === "materials" && this.#isLoadingMaterialsIndependent);
-        if (isClaimedIndependently && !isIndependent) {
-            if (sourceData.objectURLs?.length) {
-                this.#gltfResolver.revokeObjectURLs(sourceData.objectURLs);
-            }
-            return [container, null];
-        }
-
         container.state.setPendingCacheData(sourceData.size, sourceData.timeStamp, sourceData.metadata);
 
         // https://doc.babylonjs.com/typedoc/interfaces/BABYLON.LoadAssetContainerOptions
@@ -2984,14 +2665,12 @@ export default class BabylonJSController {
         };
 
         let assetContainer = null;
-        const t0 = performance.now();
 
         try {
             assetContainer = await LoadAssetContainerAsync(sourceData.source, this.#scene, options);
-            const elapsed = Math.round(performance.now() - t0);
-            console.log(`[perf][${container.state.name}] LoadAssetContainerAsync ${elapsed}ms`);
             return [container, assetContainer];
         } catch (error) {
+            console.error(`[PrefViewer] LoadAssetContainerAsync failed for [${container.state.name}]`, error);
             return [container, assetContainer];
         } finally {
             this.#gltfResolver.revokeObjectURLs(sourceData.objectURLs);
@@ -3009,29 +2688,7 @@ export default class BabylonJSController {
      */
     async #loadContainers(force = false) {
         this.#detachAnimationChangedListener();
-        this.#loadingInProgress = true;
-
-        // When only the model is pending (scene/environment already rendered), skip
-        // unloading camera-dependent effects (DefaultRenderingPipeline, SSAO, shadows).
-        // Disposing those pipelines while the render loop was recently active deletes GL
-        // programs that are still referenced, causing WebGL INVALID_OPERATION errors.
-        const isModelOnlyLoad =
-            this.#containers.model?.state?.isPending === true &&
-            this.#containers.environment?.state?.isPending !== true &&
-            this.#containers.materials?.state?.isPending !== true;
-
-        if (isModelOnlyLoad) {
-            this.#stopEngineRenderLoop();
-            this.#resetRenderState();
-            // Replacing an already-visible model can leave Babylon post-process chains attached to
-            // a camera that is about to be discarded or re-bound. Tear them down here so the next
-            // startRender() rebuilds a clean pipeline instead of tripping over stale null entries.
-            if (this.#containers.model?.assetContainer) {
-                await this.#unloadCameraDependentEffects();
-            }
-        } else {
-            await this.#stopRender();
-        }
+        await this.#stopRender();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
@@ -3046,12 +2703,8 @@ export default class BabylonJSController {
             error: null,
         };
 
-        const tSceneStart = performance.now();
-        let tAfterLoad, tAfterMerge;
-
         await Promise.allSettled(promiseArray)
             .then(async (values) => {
-                tAfterLoad = performance.now();
                 // Scene may have been disposed (disconnectedCallback) while async loading was in
                 // progress.  Abort cleanly: #replaceContainer already guards the GPU calls, but
                 // we skip the post-load option/visibility calls too to avoid further null-derefs.
@@ -3060,12 +2713,6 @@ export default class BabylonJSController {
                     return;
                 }
                 this.#disposeAnimationController();
-                this.#emitSceneLoadPhase("scene-load-assets-complete", {
-                    path: "full",
-                    containerCount: values.filter((result) => result.status === "fulfilled" && result.value?.[1]).length,
-                    tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
-                    tSceneStart: Math.round(tSceneStart),
-                });
                 values.forEach((result) => {
                     const container = result.value ? result.value[0] : null;
                     const assetContainer = result.value ? result.value[1] : null;
@@ -3078,32 +2725,23 @@ export default class BabylonJSController {
                         if (container.state.name === "model" || container.state.name === "environment") {
                             this.#assetContainer_retagCameras(assetContainer);
                         }
+                        if (container.state.name === "environment") {
+                            this.#assetContainer_simplifyTransmissiveMaterials(assetContainer);
+                        }
                         this.#replaceContainer(container, assetContainer);
                         container.state.setSuccess(true);
                     } else {
-                        // null sentinel = claimed by loadContainerIndependent — already merged independently.
-                        // false = normal skip (no data change) or error. Only mark failure for the latter.
-                        if (assetContainer !== null) {
-                            if (container.assetContainer && container.state.mustBeShown !== container.state.isVisible && container.state.name === "materials") {
-                                container.state.mustBeShown ? this.#addContainer(container) : this.#removeContainer(container);
-                            }
-                            container.state.setSuccess(false);
+                        if (container.assetContainer && container.state.mustBeShown !== container.state.isVisible && container.state.name === "materials") {
+                            container.state.mustBeShown ? this.#addContainer(container) : this.#removeContainer(container);
                         }
+                        container.state.setSuccess(false);
                     }
                 });
 
-                this.#setOptions_Materials(true);
+                this.#setOptions_Materials();
                 this.#setOptions_Camera();
                 await this.#setOptions_IBL();
                 this.#setVisibilityOfWallAndFloorInModel();
-                this.#frameCameraToModel();
-                tAfterMerge = performance.now();
-                this.#emitSceneLoadPhase("scene-load-merge-complete", {
-                    path: "full",
-                    tAfterMerge: tAfterMerge != null ? Math.round(tAfterMerge) : null,
-                    tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
-                    tSceneStart: Math.round(tSceneStart),
-                });
                 detail.success = true;
             })
             .catch((error) => {
@@ -3116,39 +2754,34 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#enhanceTextureQuality();
-                if (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();
-                }
-                this.#loadingInProgress = false;
-                // If loadContainerIndependent already merged a container and started the render
-                // loop while this scene load was in flight, #startRender was already called.
-                // Calling it again is safe (pipeline guards skip recreation) but redundant only
-                // when the loop is already running AND scene/shaders are ready; whenReadyAsync
-                // will settle quickly for the newly added containers.
+                this.#syncAnimationControllerAfterModelLoad();
+
                 await this.#startRender();
-                this.#frameCameraToModel({ allowWhenEnvironmentVisible: true });
-                this.#emitSceneLoadPhase("scene-load-shaders-complete", {
-                    path: "full",
-                    tAfterShaders: Math.round(performance.now()),
-                    tAfterMerge: tAfterMerge != null ? Math.round(tAfterMerge) : null,
-                });
-                const tLoad = tAfterLoad ? Math.round(tAfterLoad - tSceneStart) : null;
-                const tMerge = tAfterLoad && tAfterMerge ? Math.round(tAfterMerge - tAfterLoad) : null;
-                const tShaders = tAfterMerge ? Math.round(performance.now() - tAfterMerge) : null;
-                const tTotal = Math.round(performance.now() - tSceneStart);
-                console.log(`[perf][scene] load=${tLoad}ms merge=${tMerge}ms shaders=${tShaders}ms total=${tTotal}ms`);
             });
         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.
@@ -3260,7 +2893,7 @@ export default class BabylonJSController {
         if (!this.#scene) {
             return false;
         }
-        const node = this.#scene.getNodeByName(name);
+        const node = this.#scene.getNodeByName(name) ?? this.#scene.getNodes().find((n) => n.name.toLowerCase() === name.toLowerCase());
         if (!node || !node.position) {
             return false;
         }
@@ -3402,14 +3035,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,
@@ -3430,6 +3063,7 @@ export default class BabylonJSController {
         this.#scene.skipPointerUpPicking = true;
 
         this.#createCamera();
+        await this.#ensureEnvironmentBRDFTextureReady();
         this.#enableInteraction();
         await this.#createXRExperience();
     }
@@ -3585,6 +3219,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.
@@ -3595,296 +3405,6 @@ export default class BabylonJSController {
         return await this.#loadContainers(force);
     }
 
-    /**
-     * Loads a single named container in the background while the render loop keeps running,
-     * then merges it into the scene atomically (only the merge momentarily pauses the loop).
-     * Camera-dependent effects (post-processing, SSAO, shadows) are preserved across the merge.
-     * If a full #loadContainers is in progress, waits for it to finish before merging.
-     * @public
-     * @param {string} containerName - Name of the container to load ("model", "environment", "materials").
-     * @param {Function} [onReady] - Optional callback invoked after any concurrent scene load finishes
-     *   and before the asset is fetched. Use this to mark the container pending (e.g. via
-     *   #checkNeedToUpdateContainers) so that the concurrent #loadContainers doesn't consume it first.
-     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
-     */
-    async loadContainerIndependent(containerName, onReady, options = {}) {
-        const loadSessionId = containerName === "model" ? (options?.loadSessionId ?? null) : null;
-        if (containerName === "model" && this.#isLoadingModelIndependent) {
-            return { success: false, error: "Already loading model independently", loadedContainers: [], loadSessionId };
-        }
-        if (containerName === "environment" && this.#isLoadingEnvironmentIndependent) {
-            return { success: false, error: "Already loading environment independently", loadedContainers: [], loadSessionId };
-        }
-        if (containerName === "materials" && this.#isLoadingMaterialsIndependent) {
-            return { success: false, error: "Already loading materials independently", loadedContainers: [], loadSessionId };
-        }
-
-        if (containerName === "model") this.#isLoadingModelIndependent = true;
-        else if (containerName === "environment") this.#isLoadingEnvironmentIndependent = true;
-        else if (containerName === "materials") this.#isLoadingMaterialsIndependent = true;
-
-        // Only reset model-first-painted tracking for model loads — resetting it for
-        // environment/materials would stale any in-flight model-first-painted gate.
-        if (containerName === "model") {
-            this.#modelFirstPaintedEmitted = false;
-        }
-        const modelFirstPaintedLoadToken = containerName === "model"
-            ? ++this.#modelFirstPaintedLoadToken
-            : this.#modelFirstPaintedLoadToken;
-        let assetContainer = null;
-        const tIndepStart = performance.now();
-        // Whether the container was already pending inside a running #loadContainers batch.
-        // If so, we fall back to the sequential path (wait → onReady → load) to avoid a
-        // double-load conflict. Otherwise, load the GLTF in parallel with the scene load
-        // and only wait for the atomic merge window.
-        const isAlreadyHandled =
-            this.#containers[containerName]?.state?.isPending === true && this.#loadingInProgress;
-        const path = isAlreadyHandled ? "claimed" : "par";
-        let container;
-        let tAfterLoad, tAfterWait;
-        try {
-            if (!isAlreadyHandled) {
-                // Optimistic path: prepare state and load GLTF NOW, in parallel with any running
-                // #loadContainers. The merge waits for the scene, but the download does not.
-                if (!this.#scene) {
-                    return { success: false, error: "No scene available", loadedContainers: [], loadSessionId };
-                }
-                onReady?.();
-                container = this.#containers[containerName];
-                if (!container) {
-                    return { success: false, error: `Container "${containerName}" not found`, loadedContainers: [], loadSessionId };
-                }
-                // Phase 1 (parallel): load GLTF while scene may still be loading.
-                // No wait — merge happens immediately after load. #replaceContainer skips
-                // releaseEffects when the loop is running, so no WebGL programs are deleted.
-                const [, loaded] = await this.#loadAssetContainer(container, false, { isIndependent: true });
-                assetContainer = loaded || null;
-                tAfterLoad = performance.now();
-                tAfterWait = tAfterLoad; // no wait phase in optimistic path
-            } else {
-                // Parallel claim path: container was already submitted to a running #loadContainers
-                // batch. #isLoadingModelIndependent (set at the top of this method) signals
-                // #loadAssetContainer to abort the in-flight batch load and return a null sentinel,
-                // so #loadContainers skips merging this container. We load it here in parallel —
-                // no waiting for scene/materials to finish.
-                if (!this.#scene) {
-                    return { success: false, error: "No scene available", loadedContainers: [], loadSessionId };
-                }
-                // Call onReady() to ensure the container state carries this load's payload,
-                // which may differ from what #loadContainers was given if the caller swapped the model.
-                onReady?.();
-                container = this.#containers[containerName];
-                if (!container) {
-                    return { success: false, error: `Container "${containerName}" not found`, loadedContainers: [], loadSessionId };
-                }
-                const [, loaded] = await this.#loadAssetContainer(container, false, { isIndependent: true });
-                assetContainer = loaded || null;
-                tAfterLoad = performance.now();
-                tAfterWait = tIndepStart; // no wait phase — measure load from start
-            }
-
-            if (!assetContainer) {
-                return { success: false, error: "Failed to load asset container", loadedContainers: [], loadSessionId };
-            }
-            if (!this.#scene) {
-                assetContainer.dispose();
-                return { success: false, error: "Scene was disposed", loadedContainers: [], loadSessionId };
-            }
-
-            this.#emitSceneLoadPhase("scene-load-assets-complete", {
-                containerName,
-                path,
-                tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
-                tIndepStart: Math.round(tIndepStart),
-            });
-
-            // Phase 3: atomic merge — briefly stop the loop for the merge only
-            this.#stopEngineRenderLoop();
-
-            const oldModelMetadata = containerName === "model"
-                ? { ...(this.#containers.model?.state?.metadata ?? {}) }
-                : {};
-
-            this.#disposeAnimationController();
-
-            if (containerName === "model") {
-                this.#assetContainer_deleteLights(assetContainer);
-                this.#assetContainer_stopAnimations(assetContainer);
-            }
-            if (containerName === "model" || containerName === "environment") {
-                this.#assetContainer_retagCameras(assetContainer);
-            }
-
-            this.#replaceContainer(container, assetContainer, { releaseEffects: false });
-            container.state.setSuccess(true);
-
-            // Progressive independent loads may bring model/materials/environment in any order.
-            // Force material rebinding after each merge so already-visible model meshes pick up
-            // the latest material definitions instead of waiting for pending flags that may
-            // already have been cleared.
-            this.#setOptions_Materials(true);
-            this.#setOptions_Camera();
-            // For model: IBL not yet loaded (scene still in flight) — create only ambient/directional
-            // lights. #loadContainers will call #createLights() again with full IBL once scene merges.
-            // For environment: IBL state was pre-marked pending by loadSceneIndependent before calling
-            // here, so #setOptions_IBL() picks it up and applies it immediately after lights are ready.
-            await this.#createLights();
-            if (containerName === "environment") {
-                await this.#setOptions_IBL();
-            }
-
-            if (containerName === "model") {
-                const newModelMetadata = { ...(container.state.update?.metadata ?? {}) };
-                this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
-            }
-
-            if (this.#containers.model.assetContainer) {
-                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
-            }
-            const tAfterMerge = performance.now();
-            this.#emitSceneLoadPhase("scene-load-merge-complete", {
-                containerName,
-                path,
-                tAfterMerge: Math.round(tAfterMerge),
-                tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
-                tIndepStart: Math.round(tIndepStart),
-            });
-
-            // Use #startRender() so the next frame is scheduled after the atomic merge.
-            // In progressive loads, rebuilding camera-dependent effects (DefaultRenderingPipeline,
-            // SSAO, shadows) while the model is already visible can delete GL programs that are
-            // still referenced by the current frame, which leaves the canvas gray until a later
-            // full reload. Keep the existing pipeline alive for independent model/environment/
-            // materials appends; the full load path still rebuilds everything when needed.
-            await this.#startRender({ skipWhenReady: true, forceRender: true, skipCameraDependentEffects: true });
-            const tAfterShaders = performance.now();
-
-            this.#setHighlightConfig({
-                enabled: this.#settings.highlightEnabled,
-                color: this.#settings.highlightColor,
-            });
-            this.#setMaxSimultaneousLights();
-            this.#enhanceTextureQuality();
-            this.#setVisibilityOfWallAndFloorInModel();
-
-            if (this.#babylonJSAnimationController?.hasAnimations?.()) {
-                this.#attachAnimationChangedListener();
-            }
-
-            this.#requestRender({ frames: 3, continuousMs: this.#config.render.interactionMs });
-            if (containerName === "model" && !this.#modelFirstPaintedEmitted) {
-                try {
-                    performance.mark(`viewer:model-first-painted:scheduled:${modelFirstPaintedLoadToken}`);
-                } catch {
-                    // ignore
-                }
-                console.log("[viewer] model-first-painted gate scheduled", {
-                    containerName,
-                    path: isAlreadyHandled ? "claimed" : "par",
-                    loadToken: modelFirstPaintedLoadToken,
-                    renderLoopRunning: this.#state.render.isLoopRunning,
-                    loopRequested: true,
-                });
-                void (async () => {
-                    await this.#waitForPaint(2);
-                    try {
-                        performance.mark(`viewer:model-first-painted:after-wait:${modelFirstPaintedLoadToken}`);
-                    } catch {
-                        // ignore
-                    }
-                    console.log("[viewer] model-first-painted gate after paint wait", {
-                        containerName,
-                        path: isAlreadyHandled ? "claimed" : "par",
-                        loadToken: modelFirstPaintedLoadToken,
-                        currentToken: this.#modelFirstPaintedLoadToken,
-                        alreadyEmitted: this.#modelFirstPaintedEmitted,
-                        renderLoopRunning: this.#state.render.isLoopRunning,
-                    });
-                    if (modelFirstPaintedLoadToken !== this.#modelFirstPaintedLoadToken) {
-                        try {
-                            performance.mark(`viewer:model-first-painted:stale:${modelFirstPaintedLoadToken}`);
-                        } catch {
-                            // ignore
-                        }
-                        console.log("[viewer] model-first-painted gate skipped (stale load token)", {
-                            containerName,
-                            path: isAlreadyHandled ? "claimed" : "par",
-                            loadToken: modelFirstPaintedLoadToken,
-                            currentToken: this.#modelFirstPaintedLoadToken,
-                        });
-                        return;
-                    }
-                    const paintTarget = this.#prefViewer || this.#prefViewer3D || this.#canvas;
-                    if (!this.#modelFirstPaintedEmitted && paintTarget) {
-                        this.#modelFirstPaintedEmitted = true;
-                        try {
-                            performance.mark(`viewer:model-first-painted:emitted:${modelFirstPaintedLoadToken}`);
-                        } catch {
-                            // ignore
-                        }
-                        console.log("[viewer] model-first-painted ✅ emitted", {
-                            containerName,
-                            path: isAlreadyHandled ? "claimed" : "par",
-                            loadToken: modelFirstPaintedLoadToken,
-                            tAfterPaint: Math.round(performance.now()),
-                        });
-                        this.#emitModelFirstPainted({
-                            containerName,
-                            path: isAlreadyHandled ? "claimed" : "par",
-                            tIndepStart: Math.round(tIndepStart),
-                            tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
-                            tAfterWait: tAfterWait != null ? Math.round(tAfterWait) : null,
-                            tAfterMerge: Math.round(tAfterMerge),
-                            tAfterPaint: Math.round(performance.now()),
-                        });
-                    }
-                })();
-            }
-
-            // In the optimistic path: load runs first, then wait. In the sequential path: wait
-            // runs first, then load. Compute each phase relative to its actual start point.
-            const tLoad = isAlreadyHandled
-                ? Math.round(tAfterLoad - tAfterWait)
-                : Math.round(tAfterLoad - tIndepStart);
-            const tWait = isAlreadyHandled
-                ? Math.round(tAfterWait - tIndepStart)
-                : Math.round(tAfterWait - tAfterLoad);
-            // Merge starts after the wait in both paths (optimistic: load→wait→merge; sequential: wait→load→merge)
-            const tMerge = Math.round(tAfterMerge - (isAlreadyHandled ? tAfterLoad : tAfterWait));
-            const tShaders = Math.round(tAfterShaders - tAfterMerge);
-            const tTotal = Math.round(tAfterShaders - tIndepStart);
-            this.#emitSceneLoadPhase("scene-load-shaders-complete", {
-                containerName,
-                path,
-                tAfterShaders: Math.round(tAfterShaders),
-                tAfterMerge: Math.round(tAfterMerge),
-                tTotal,
-            });
-            this.#emitSceneLoadPhase("scene-load-container-complete", {
-                containerName,
-                path,
-                tLoad,
-                tWait,
-                tMerge,
-                tShaders,
-                tTotal,
-            });
-            console.log(`[perf][${containerName}:indep:${path}] load=${tLoad}ms wait=${tWait}ms merge=${tMerge}ms shaders=${tShaders}ms total=${tTotal}ms`);
-
-            return { success: true, error: null, loadedContainers: [containerName], loadSessionId };
-        } catch (error) {
-            assetContainer?.dispose();
-            if (!this.#state.render.isLoopRunning && this.#scene && this.#engine) {
-                this.#startEngineRenderLoop();
-            }
-            return { success: false, error, loadedContainers: [], loadSessionId };
-        } finally {
-            if (containerName === "model") this.#isLoadingModelIndependent = false;
-            else if (containerName === "environment") this.#isLoadingEnvironmentIndependent = false;
-            else if (containerName === "materials") this.#isLoadingMaterialsIndependent = false;
-        }
-    }
-
     /**
      * Applies camera options from the configuration to the active camera.
      * Stops and restarts the render loop to apply changes.
@@ -3927,14 +3447,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) {
@@ -3944,8 +3492,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
@@ -3966,7 +3517,7 @@ export default class BabylonJSController {
             }
             this.#setHighlightConfig({
                 color: config.highlightColor ?? undefined,
-                enabled,
+                enabled: enabled,
             });
         }
 
@@ -4005,11 +3556,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.
@@ -4089,4 +3642,3 @@ export default class BabylonJSController {
         }
     }
 }
-