@preference-sl/pref-viewer 2.14.0 → 2.15.1

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, Camera, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, LoadAssetContainerAsync, Material, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+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 { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -11,6 +11,74 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 import { translate } from "./localization/i18n.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,
+    };
+}
+
 /**
  * BabylonJSController coordinates the PrefViewer 3D runtime: it bootstraps Babylon.js, manages asset containers,
  * rebuilds camera-dependent pipelines once textures are ready, brokers XR/download interactions, and persists
@@ -85,6 +153,7 @@ export default class BabylonJSController {
         ambientOcclusionEnabled: true,
         iblEnabled: true,
         shadowsEnabled: false,
+        lightingTimeOfDay: 0.5,
         // Highlight settings
         highlightEnabled: true,
         highlightColor: "#ff6700",
@@ -103,6 +172,7 @@ export default class BabylonJSController {
     #camera = null;
     #hemiLight = null;
     #dirLight = null;
+    #moonLight = null;
     #cameraLight = null;
     #shadowGen = [];
     #XRExperience = null;
@@ -186,6 +256,18 @@ export default class BabylonJSController {
             shadowBlurKernel: 16,       // Shadow blur amount
             ssaoEnabled: true,         // Screen Space Ambient Occlusion
         },
+        look: {
+            showroom: {
+                exposure: 0.92,
+                contrast: 1.02,
+                toneMappingEnabled: true,
+                toneMappingType: ImageProcessingConfiguration?.TONEMAPPING_ACES ?? 0,
+                environmentIntensity: 1.08,
+                hemiLightIntensity: 0.52,
+                dirLightIntensity: 0.56,
+                cameraLightIntensity: 0.16,
+            },
+        },
     };
 
     /**
@@ -200,6 +282,7 @@ export default class BabylonJSController {
         
         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
@@ -210,6 +293,10 @@ export default class BabylonJSController {
         
         // If we detect a desktop GPU, go directly to desktop detection
         if (isDesktopGPU && !isMobileGPU) {
+            if (isAngleRenderer) {
+                console.log(`[PrefViewer] ANGLE-backed renderer detected: ${rendererName}`);
+                return this.#detectDesktopTier(gl, rendererName, true);
+            }
             console.log(`[PrefViewer] Desktop GPU detected: ${rendererName}`);
             return this.#detectDesktopTier(gl, rendererName);
         }
@@ -246,7 +333,7 @@ export default class BabylonJSController {
      * @param {string} rendererName - GPU renderer name
      * @returns {string} Hardware tier
      */
-    #detectDesktopTier(gl, rendererName) {
+    #detectDesktopTier(gl, rendererName, conservative = false) {
         // Check WebGL capabilities
         const maxTextureSize = gl?.getParameter(gl.MAX_TEXTURE_SIZE) || 8192;
         
@@ -256,12 +343,14 @@ export default class BabylonJSController {
         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 = 'high'; // Default to high for desktop
+        let tier = conservative ? 'medium' : 'high'; // Default to conservative desktop when ANGLE is in the path
         
         if (isIntelIntegrated || maxTextureSize < 8192) {
             tier = 'medium';
-        } else if (isAppleSilicon || isNvidiaHighEnd || isAmdHighEnd || maxTextureSize >= 16384) {
+        } else if (!conservative && (isAppleSilicon || isNvidiaHighEnd || isAmdHighEnd || maxTextureSize >= 16384)) {
             tier = 'ultra';
+        } else if (conservative && maxTextureSize >= 16384) {
+            tier = 'high';
         }
         
         console.log(`[PrefViewer] Desktop tier: ${tier} (GPU: ${rendererName || 'unknown'}, MaxTexture: ${maxTextureSize})`);
@@ -364,6 +453,7 @@ export default class BabylonJSController {
                 antialiasingEnabled: false,
                 hardwareScaling: 2.5,           // Aggressive downscaling
                 maxModelResolution: 512,          // Low-res model loading
+                environmentTextureSize: 512,
             },
             // Mobile high-end / Tablet / Desktop low
             medium: {
@@ -375,28 +465,31 @@ export default class BabylonJSController {
                 antialiasingEnabled: true,
                 hardwareScaling: 2.0,
                 maxModelResolution: 1024,
+                environmentTextureSize: 1024,
             },
             // Desktop mid-range / High-end mobile
             high: {
                 shadowMapSize: 1024,
                 iblShadowResolution: 0,          // 1024x1024 - good balance
                 iblSampleDirections: 4,           // Quality sampling
-                shadowBlurKernel: 16,             // Smooth shadows
-                ssaoEnabled: true,
+                shadowBlurKernel: 8,              // Sharper shadows for product clarity
+                ssaoEnabled: false,
                 antialiasingEnabled: true,
-                hardwareScaling: 1.5,
+                hardwareScaling: 1.0,
                 maxModelResolution: 2048,
+                environmentTextureSize: 2048,
             },
             // Desktop high-end (RTX, Apple Silicon, etc.)
             ultra: {
                 shadowMapSize: 2048,
                 iblShadowResolution: 1,          // 2048x2048
                 iblSampleDirections: 8,           // Maximum quality
-                shadowBlurKernel: 32,            // Ultra smooth
-                ssaoEnabled: true,
+                shadowBlurKernel: 16,            // Preserve clarity over softness
+                ssaoEnabled: false,
                 antialiasingEnabled: true,
                 hardwareScaling: 1.0,             // Native resolution
                 maxModelResolution: 4096,
+                environmentTextureSize: 4096,
             },
         };
 
@@ -509,6 +602,11 @@ export default class BabylonJSController {
                 this.#settings[key] = settings[key];
                 changed = true;
             }
+            // Handle numeric settings such as lightingTimeOfDay
+            if (typeof settings[key] === "number" && Number.isFinite(settings[key]) && this.#settings[key] !== settings[key]) {
+                this.#settings[key] = settings[key];
+                changed = true;
+            }
         });
 
         if (changed) {
@@ -543,6 +641,10 @@ export default class BabylonJSController {
                 if (typeof parsed?.[key] === "string") {
                     this.#settings[key] = parsed[key];
                 }
+                // Handle numeric settings such as lightingTimeOfDay
+                if (typeof parsed?.[key] === "number" && Number.isFinite(parsed[key])) {
+                    this.#settings[key] = parsed[key];
+                }
             });
         } catch (error) {
             console.warn("PrefViewer: unable to load render settings", error);
@@ -895,6 +997,7 @@ export default class BabylonJSController {
         this.#camera.lowerRadiusLimit = 5;
         this.#camera.upperRadiusLimit = 20;
         this.#camera.metadata = { locked: false };
+        this.#applyShowroomCameraFraming(this.#camera);
         this.#camera.attachControl(this.#canvas, true);
         this.#scene.activeCamera = this.#camera;
     }
@@ -916,25 +1019,11 @@ export default class BabylonJSController {
         const cameraLightName = "PrefViewerCameraLight";
         const dirLightName = "PrefViewerDirLight";
 
-        const hemiLight = this.#scene.getLightByName(hemiLightName);
-        const cameraLight = this.#scene.getLightByName(cameraLightName);
-        const dirLight = this.#scene.getLightByName(dirLightName);
-
         let lightsChanged = false;
 
         const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
 
         if (iblEnabled) {
-            if (hemiLight) {
-                hemiLight.dispose();
-            }
-            if (cameraLight) {
-                cameraLight.dispose();
-            }
-            if (dirLight) {
-                dirLight.dispose();
-            }
-            this.#hemiLight = this.#dirLight = this.#cameraLight = null;
             lightsChanged = await this.#initializeEnvironmentTexture();
         } else {
             // If IBL is disabled but an environment texture exists, dispose it to save resources and ensure it doesn't affect the lighting
@@ -943,27 +1032,22 @@ export default class BabylonJSController {
                 this.#scene.environmentTexture = null;
                 lightsChanged = true;
             }
-
-            // Add a hemispheric light for basic ambient illumination
-            if (!this.#hemiLight) {
-                this.#hemiLight = new HemisphericLight(hemiLightName, new Vector3(-10, 10, -10), this.#scene);
-                this.#hemiLight.intensity = 0.6;
-            }
-
-            // Add a directional light to cast shadows and provide stronger directional illumination
-            if (!this.#dirLight) {
-                this.#dirLight = new DirectionalLight(dirLightName, new Vector3(-10, 10, -10), this.#scene);
-                this.#dirLight.position = new Vector3(5, 4, 5); // light is IN FRONT + ABOVE + to the RIGHT
-                this.#dirLight.intensity = 0.6;
-            }
-
-            // Add a point light that follows the camera to ensure the model is always well-lit from the viewer's perspective
-            if (!this.#cameraLight) {
-                this.#cameraLight = new PointLight(cameraLightName, this.#camera.position, this.#scene);
-                this.#cameraLight.parent = this.#camera;
-                this.#cameraLight.intensity = 0.3;
-            }
         }
+        if (!this.#hemiLight) {
+            this.#hemiLight = new HemisphericLight(hemiLightName, new Vector3(-10, 10, -10), this.#scene);
+        }
+        if (!this.#dirLight) {
+            this.#dirLight = new DirectionalLight(dirLightName, new Vector3(-10, 10, -10), this.#scene);
+            this.#dirLight.position = new Vector3(5, 4, 5);
+        }
+        if (!this.#moonLight) {
+            this.#moonLight = new DirectionalLight("PrefViewerMoonLight", new Vector3(10, -10, 8), this.#scene);
+        }
+        if (!this.#cameraLight) {
+            this.#cameraLight = new PointLight(cameraLightName, this.#camera.position, this.#scene);
+            this.#cameraLight.parent = this.#camera;
+        }
+        lightsChanged = this.#applyLightingConfig() || lightsChanged;
         return lightsChanged;
     }
 
@@ -1140,34 +1224,13 @@ export default class BabylonJSController {
             const caps = this.#scene.getEngine()?.getCaps?.() || {};
             const maxSamples = typeof caps.maxMSAASamples === "number" ? caps.maxMSAASamples : 4;
             defaultPipeline.samples = Math.max(1, Math.min(8, maxSamples));
-            // FXAA - Fast Approximate Anti-Aliasing
-            defaultPipeline.fxaaEnabled = true;
-            defaultPipeline.fxaa.samples = 8;
-            defaultPipeline.fxaa.adaptScaleToCurrentViewport = true;
-            if (defaultPipeline.fxaa.edgeThreshold !== undefined) {
-                defaultPipeline.fxaa.edgeThreshold = 0.125;
-            }
-            if (defaultPipeline.fxaa.edgeThresholdMin !== undefined) {
-                defaultPipeline.fxaa.edgeThresholdMin = 0.0625;
-            }
-            if (defaultPipeline.fxaa.subPixelQuality !== undefined) {
-                defaultPipeline.fxaa.subPixelQuality = 0.75;
-            }
+            // FXAA can soften product surfaces too much; keep MSAA only for crisper materials.
+            defaultPipeline.fxaaEnabled = false;
 
-            // Grain
-            defaultPipeline.grainEnabled = true;
-            defaultPipeline.grain.adaptScaleToCurrentViewport = true;
-            defaultPipeline.grain.animated = false;
-            defaultPipeline.grain.intensity = 3;
+            // Grain is disabled to keep product surfaces clean and avoid visible noise.
+            defaultPipeline.grainEnabled = false;
 
             // Configure post-processes to calculate only once instead of every frame for better performance
-            if (defaultPipeline.fxaa?._postProcess) {
-                defaultPipeline.fxaa._postProcess.autoClear = false;
-            }
-            if (defaultPipeline.grain?._postProcess) {
-                defaultPipeline.grain._postProcess.autoClear = false;
-            }
-
             this.#renderPipelines.default = defaultPipeline;
             pipelineManager.update();
             return true;
@@ -1201,7 +1264,8 @@ export default class BabylonJSController {
         let hdrTexture = null;
         if (this.#options.ibl?.cachedUrl) {
             const hdrTextureURI = this.#options.ibl.cachedUrl;
-            hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 1024, false, false, false, true, undefined, undefined, false, true, true);
+            const envTextureSize = this.#config.quality.environmentTextureSize || 1024;
+            hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, envTextureSize, false, false, false, true, undefined, undefined, false, true, true);
         } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
             hdrTexture = this.#hdrTexture.clone();
         } else {
@@ -1218,8 +1282,10 @@ export default class BabylonJSController {
             this.#options.ibl?.consumeCachedUrl?.(true);
         }
 
-        hdrTexture.level = this.#options.ibl.intensity;
+        hdrTexture.level = this.#options.ibl.intensity ?? 1;
         this.#scene.environmentTexture = hdrTexture;
+        this.#applyShowroomLook();
+        this.#applyLightingConfig();
         this.#scene.markAllMaterialsAsDirty(Material.TextureDirtyFlag);
         return true;
     }
@@ -1305,7 +1371,7 @@ export default class BabylonJSController {
         });
         const materialsForReceivingShadows = this.#scene.materials.filter((material) => {
             if (material instanceof PBRMaterial) {
-                material.enableSpecularAntiAliasing = false;
+                material.enableSpecularAntiAliasing = true;
             }
             return true;
         });
@@ -1530,6 +1596,184 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Improves texture sharpness by enabling trilinear filtering and anisotropy.
+     * @private
+     * @returns {void}
+     */
+    #enhanceTextureQuality() {
+        if (!this.#scene) {
+            return;
+        }
+
+        const caps = this.#scene.getEngine()?.getCaps?.() || {};
+        const maxAnisotropy = Math.max(1, Math.min(16, caps.maxAnisotropy || 1));
+
+        this.#scene.textures?.forEach((texture) => {
+            if (!texture || texture.isDisposed?.()) {
+                return;
+            }
+
+            if ("anisotropicFilteringLevel" in texture) {
+                texture.anisotropicFilteringLevel = maxAnisotropy;
+            }
+
+            if (typeof texture.updateSamplingMode === "function") {
+                try {
+                    texture.updateSamplingMode(Texture.TRILINEAR_SAMPLINGMODE);
+                } catch {
+                    // Ignore texture subclasses that do not support sampling changes.
+                }
+            }
+        });
+    }
+
+    /**
+     * Applies the showroom tonemapping curve and lighting bias used by the 3D viewer.
+     * @private
+     * @returns {void}
+     */
+    #applyShowroomLook() {
+        if (!this.#scene?.imageProcessingConfiguration) {
+            return;
+        }
+
+        const showroom = this.#config.look?.showroom || {};
+        const imageProcessing = this.#scene.imageProcessingConfiguration;
+
+        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;
+        imageProcessing.toneMappingType = showroom.toneMappingType ?? (ImageProcessingConfiguration?.TONEMAPPING_ACES ?? 0);
+        imageProcessing.vignetteEnabled = false;
+        imageProcessing.colorCurvesEnabled = false;
+
+        if ("environmentIntensity" in this.#scene) {
+            this.#scene.environmentIntensity = showroom.environmentIntensity ?? 1.15;
+        }
+    }
+
+    /**
+     * Applies the current time-of-day cycle to the scene lighting, environment intensity, and tonemapping bias.
+     * @private
+     * @returns {boolean} True when a scene existed and was updated.
+     */
+    #applyLightingConfig() {
+        if (!this.#scene) {
+            return false;
+        }
+
+        const showroom = this.#config.look?.showroom || {};
+        const timeOfDay = clamp01(this.#settings.lightingTimeOfDay ?? 0.5);
+        const profile = getLightingCycleProfile(timeOfDay);
+        const daylight = profile.dayFactor;
+        const peakLight = daylight > 0 ? Math.pow(daylight, 0.72) : 0;
+        const twilight = 1 - peakLight;
+
+        if (this.#scene.imageProcessingConfiguration) {
+            const imageProcessing = this.#scene.imageProcessingConfiguration;
+            imageProcessing.exposure = lerp(0.78, showroom.exposure ?? 0.92, peakLight);
+            imageProcessing.contrast = lerp(0.98, showroom.contrast ?? 1.02, peakLight);
+            imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
+            imageProcessing.toneMappingType = showroom.toneMappingType ?? (ImageProcessingConfiguration?.TONEMAPPING_ACES ?? 0);
+            imageProcessing.vignetteEnabled = false;
+            imageProcessing.colorCurvesEnabled = false;
+        }
+
+        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);
+        }
+
+        if (this.#hemiLight) {
+            this.#hemiLight.direction = new Vector3(
+                lerp(-0.45, -0.8, peakLight),
+                lerp(0.45, 0.95, peakLight),
+                lerp(-0.75, -0.35, peakLight),
+            );
+            this.#hemiLight.intensity = lerp(0.18, showroom.hemiLightIntensity ?? 0.52, peakLight);
+            this.#hemiLight.diffuse = new Color3(
+                lerp(0.42, 0.92, peakLight),
+                lerp(0.48, 0.96, peakLight),
+                lerp(0.62, 0.98, peakLight),
+            );
+            this.#hemiLight.groundColor = new Color3(
+                lerp(0.08, 0.3, twilight),
+                lerp(0.08, 0.28, twilight),
+                lerp(0.1, 0.22, twilight),
+            );
+        }
+
+        if (this.#dirLight) {
+            this.#dirLight.direction = new Vector3(profile.sunDirection.x, profile.sunDirection.y, profile.sunDirection.z);
+            this.#dirLight.intensity = lerp(0.02, showroom.dirLightIntensity ?? 0.56, peakLight);
+            this.#dirLight.diffuse = new Color3(
+                lerp(0.28, 1.0, peakLight),
+                lerp(0.3, 0.97, peakLight),
+                lerp(0.34, 0.9, peakLight),
+            );
+        }
+
+        if (this.#moonLight) {
+            this.#moonLight.direction = new Vector3(profile.moonDirection.x, profile.moonDirection.y, profile.moonDirection.z);
+            this.#moonLight.intensity = lerp(0.44, 0.03, peakLight);
+            this.#moonLight.diffuse = new Color3(0.58, 0.7, 1.0);
+        }
+
+        if (this.#cameraLight) {
+            this.#cameraLight.intensity = lerp(0.06, showroom.cameraLightIntensity ?? 0.16, peakLight);
+            this.#cameraLight.diffuse = new Color3(
+                lerp(0.35, 1.0, peakLight),
+                lerp(0.35, 0.97, peakLight),
+                lerp(0.36, 0.92, peakLight),
+            );
+        }
+
+        this.#scene.markAllMaterialsAsDirty?.(Material.LightDirtyFlag ?? Material.TextureDirtyFlag);
+        this.#requestRender({ frames: 2, continuousMs: this.#config.render.interactionMs });
+        return true;
+    }
+
+    /**
+     * Recomputes the effective hardware scaling from the current device pixel ratio.
+     * This keeps the 3D output crisp when the viewport changes or the browser zoom/DPR shifts.
+     * @private
+     * @returns {void}
+     */
+    #applyViewportHardwareScaling() {
+        if (!this.#engine) {
+            return;
+        }
+
+        const pixelRatio = typeof window !== "undefined" ? window.devicePixelRatio : 1;
+        const baseScaling = this.#config.quality.hardwareScaling || 1;
+        const scalingLevel = getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
+        this.#engine.setHardwareScalingLevel(scalingLevel);
+    }
+
+    /**
+     * Keeps the showroom camera framing stable when the viewport aspect ratio changes.
+     * The 3D showroom is meant to feel compositionally stable, so we prefer a horizontal-fixed
+     * field of view on ArcRotate cameras to avoid the background appearing undersized on wide layouts.
+     * @private
+     * @param {Camera|null|undefined} camera - Active camera to adjust.
+     * @returns {void}
+     */
+    #applyShowroomCameraFraming(camera = this.#scene?.activeCamera) {
+        if (!(camera instanceof ArcRotateCamera)) {
+            return;
+        }
+
+        camera.fovMode = Camera?.FOVMODE_HORIZONTAL_FIXED ?? 1;
+    }
+
     /**
      * Resets pointer-picking sampling state.
      * @private
@@ -1696,7 +1940,7 @@ export default class BabylonJSController {
         }
         this.#engine.dispose();
         this.#engine = this.#scene = this.#camera = null;
-        this.#hemiLight = this.#dirLight = this.#cameraLight = null;
+        this.#hemiLight = this.#dirLight = this.#moonLight = this.#cameraLight = null;
     }
 
     /**
@@ -1931,8 +2175,11 @@ 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`);
+            this.#applyShowroomCameraFraming();
             this.#engine.resize();
-            this.#requestRender({ frames: this.#config.render.burstFramesBase, continuousMs: this.#config.render.interactionMs });
+            const needsEnhancedBurst = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled || this.#settings.shadowsEnabled;
+            const frames = needsEnhancedBurst ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
+            this.#requestRender({ frames, continuousMs: this.#config.render.interactionMs });
         };
 
         if (elapsed >= this.#config.resize.throttleMs) {
@@ -2084,6 +2331,7 @@ export default class BabylonJSController {
                 cameraState.setSuccess(true);
             }
         }
+        this.#applyShowroomCameraFraming(camera);
         this.#scene.activeCamera?.detachControl();
         camera.detachControl();
         if (!cameraState.locked) {
@@ -2471,6 +2719,7 @@ export default class BabylonJSController {
             .finally(async () => {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
+                this.#enhanceTextureQuality();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
                 // Apply stored highlight settings so fresh page loads respect persisted state
                 this.#setHighlightConfig({
@@ -2736,19 +2985,13 @@ export default class BabylonJSController {
      */
     async enable() {
         this.#configureDracoCompression();
-        this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false });
+        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: Apply hardware scaling from quality preset
-        const pixelRatio = typeof window !== 'undefined' ? window.devicePixelRatio : 1;
-        const baseScaling = this.#config.quality.hardwareScaling || 1;
-        const scalingLevel = pixelRatio > 1 ? baseScaling * pixelRatio : baseScaling;
-        this.#engine.setHardwareScalingLevel(scalingLevel);
-        
         // OPTIMIZATION: Initialize idle tracking
         this.#state.render.lastActivityAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         
@@ -2764,14 +3007,7 @@ export default class BabylonJSController {
             geometryBufferRenderer.generateNormalsInWorldSpace = true;
         }
 
-        this.#scene.clearColor = new Color4(1, 1, 1, 1).toLinearSpace();
-
-        // Lowered exposure to prevent scenes from looking blown out when the DefaultRenderingPipeline (Antialiasing) is enabled.
-        this.#scene.imageProcessingConfiguration.exposure = 0.75;
-        this.#scene.imageProcessingConfiguration.contrast = 1.0;
-        this.#scene.imageProcessingConfiguration.toneMappingEnabled = false;
-        this.#scene.imageProcessingConfiguration.vignetteEnabled = false;
-        this.#scene.imageProcessingConfiguration.colorCurvesEnabled = false;
+        this.#applyShowroomLook();
 
         // Skip the built-in pointer picking logic since the controller implements its own optimized raycasting for interaction.
         this.#scene.skipPointerMovePicking = true;
@@ -2985,6 +3221,60 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Applies lighting and highlight configuration without forcing a full scene reload.
+     * @public
+     * @param {{lightingTimeOfDay?:number, highlightColor?:string, highlightEnabled?:boolean, showAnimationMenu?:boolean}} config - Lighting/highlight configuration.
+     * @returns {void}
+     */
+    setIlluminationConfig(config = {}) {
+        let shouldApplyLighting = false;
+
+        if (typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay)) {
+            const normalizedTime = clamp01(config.lightingTimeOfDay);
+            if (this.#settings.lightingTimeOfDay !== normalizedTime) {
+                this.#settings.lightingTimeOfDay = normalizedTime;
+                shouldApplyLighting = true;
+            }
+        }
+
+        if (config.showAnimationMenu !== undefined) {
+            // Handle show-animation-menu via the 3D component's parent
+            // This is handled in pref-viewer-3d.js attributeChangedCallback
+        }
+
+        // Handle highlight color for animation hover
+        if (config.highlightColor !== undefined || config.highlightEnabled !== undefined) {
+            // Normalize highlightEnabled: accept boolean, string "true"/"false", or null
+            let enabled = config.highlightEnabled;
+            if (typeof enabled === "string") {
+                enabled = enabled.toLowerCase() !== "false";
+            } else if (enabled === null) {
+                enabled = undefined;
+            }
+            // Keep #settings in sync so getRenderSettings() always reflects the real state
+            if (enabled !== undefined) {
+                this.#settings.highlightEnabled = enabled;
+            }
+            if (config.highlightColor !== undefined && config.highlightColor !== null) {
+                this.#settings.highlightColor = config.highlightColor;
+            }
+            this.#setHighlightConfig({
+                color: config.highlightColor ?? undefined,
+                enabled,
+            });
+        }
+
+        if (shouldApplyLighting && this.#scene) {
+            this.#applyLightingConfig();
+        }
+
+        // Persist settings unless caller explicitly requests a non-persistent update (used by playback animation).
+        if (config.persist !== false) {
+            this.#storeRenderSettings();
+        }
+    }
+
     /**
      * Sets the visibility of a container (model, environment, etc.) by name.
      * Adds or removes the container from the scene and updates wall/floor visibility.
@@ -3039,45 +3329,6 @@ export default class BabylonJSController {
         return await this.#loadContainers();
     }
 
-    /**
-     * Sets highlight configuration for animation hover effects.
-     * @public
-     * @param {{showAnimationMenu?:boolean, highlightColor?:string, highlightEnabled?:boolean}} config - Highlight configuration.
-     * @returns {void}
-     */
-    setIlluminationConfig(config = {}) {
-        
-        if (config.showAnimationMenu !== undefined) {
-            // Handle show-animation-menu via the 3D component's parent
-            // This is handled in pref-viewer-3d.js attributeChangedCallback
-        }
-        
-        // Handle highlight color for animation hover
-        if (config.highlightColor !== undefined || config.highlightEnabled !== undefined) {
-            // Normalize highlightEnabled: accept boolean, string "true"/"false", or null
-            let enabled = config.highlightEnabled;
-            if (typeof enabled === "string") {
-                enabled = enabled.toLowerCase() !== "false";
-            } else if (enabled === null) {
-                enabled = undefined;
-            }
-            // Keep #settings in sync so getRenderSettings() always reflects the real state
-            if (enabled !== undefined) {
-                this.#settings.highlightEnabled = enabled;
-            }
-            if (config.highlightColor !== undefined && config.highlightColor !== null) {
-                this.#settings.highlightColor = config.highlightColor;
-            }
-            this.#setHighlightConfig({
-                color: config.highlightColor ?? undefined,
-                enabled,
-            });
-        }
-
-        // Persist settings
-        this.#storeRenderSettings();
-    }
-
     /**
      * Returns a snapshot of all available animations and their current state.
      * @public