@preference-sl/pref-viewer 2.13.0-beta.2 → 2.13.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.13.0-beta.2",
+    "version": "2.13.0-beta.4",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -35,11 +35,11 @@
         "index.d.ts"
     ],
     "dependencies": {
-        "@babylonjs/core": "^8.47.0",
-        "@babylonjs/loaders": "^8.47.0",
-        "@babylonjs/serializers": "^8.47.0",
+        "@babylonjs/core": "^8.50.5",
+        "@babylonjs/loaders": "^8.50.5",
+        "@babylonjs/serializers": "^8.50.5",
         "@panzoom/panzoom": "^4.6.0",
-        "babylonjs-gltf2interface": "^8.47.0",
+        "babylonjs-gltf2interface": "^8.50.5",
         "buffer": "^6.0.3",
         "idb": "^8.0.3",
         "is-svg": "^6.1.0",

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, Camera, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, LoadAssetContainerAsync, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState } from "@babylonjs/core";
+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 { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -11,53 +11,53 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 import { translate } from "./localization/i18n.js";
 
 /**
- * BabylonJSController is the PrefViewer 3D engine coordinator: it bootstraps Babylon.js, manages asset containers,
- * rebuilds post-process pipelines on demand, brokers XR/download interactions, and persists user render toggles so UI
- * components can stay declarative. Higher layers hand over container + option state, while this class turns it into a
- * fully interactive scene with deterministic reloads and exports.
+ * 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
+ * render toggles so the UI can stay declarative. PrefViewer hands over container + option state, while this class
+ * turns it into a deterministic scene lifecycle with exports.
  *
  * Overview
- *  - Spins up the Babylon.js engine/scene/camera stack, configures Draco loaders, and wires resize + render loops.
- *  - Resolves GLTF/GLB sources through GLTFResolver, loads them into `AssetContainer`s, and toggles their visibility.
- *  - Applies render-setting switches (AA, SSAO, IBL, shadows), persists them in localStorage, and rehydrates on startup.
- *  - Rebuilds DefaultRenderingPipeline, SSAO, IBL, and shadow pipelines every time the active camera or assets change.
- *  - Connects keyboard, pointer, wheel, hover, and XR events so menus, animation controllers, and PrefViewer attributes stay in sync.
+ *  - Creates the Babylon.js engine/scene/camera stack, configures Draco decoders, wires resize + render loops, and
+ *    exposes download/xR helpers.
+ *  - Resolves GLTF/GLB sources via GLTFResolver, loads them into `AssetContainer`s, and toggles visibility by
+ *    mutating container state plus `show-model/show-scene` attributes.
+ *  - Applies/persists AA, SSAO, IBL, and shadow flags; when they change it stops the render loop, tears down pipelines,
+ *    reloads containers, and reinstalls effects after environment textures finish loading.
+ *  - Manages keyboard/pointer/wheel handlers, animation menus, and WebXR so PrefViewer menus and DOM attributes stay
+ *    synchronized with Babylon state.
  *  - Generates GLB, glTF+ZIP, or USDZ exports with timestamped names and localized dialog copy.
  *  - Translates metadata (inner floor offsets, cast/receive shadows, camera locks) into scene adjustments after reloads.
  *
  * Runtime Flow
  *  1. Instantiate with `new BabylonJSController(canvas, containers, options)`.
- *  2. Call `enable()` to configure Draco, create the engine/scene, observers, and XR hooks.
- *  3. Whenever PrefViewer marks containers/options pending, invoke `load()` to fetch sources and rebuild pipelines.
- *  4. Use `applyRenderSettings` helpers (via menu events) to merge toggles, persist them, and trigger reloads when needed.
- *  5. Respond to PrefViewer tasks by calling `showModel()/hideModel()` equivalents through container state changes.
- *  6. Surface downloads through `downloadGLB/GLTF/USDZ` or the private `#openDownloadDialog()` triggered by keyboard shortcuts.
- *  7. Invoke `disable()` when the element disconnects to teardown scenes, XR sessions, and listeners.
+ *  2. Call `enable()` to configure Draco, spin up the engine/scene, attach interaction + XR hooks, and start the render loop.
+ *  3. When PrefViewer marks containers/options pending, invoke `load()` (or `reloadWithCurrentSettings()`) so the controller
+ *     fetches sources, rebuilds containers, and reattaches pipelines.
+ *  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
+ *     helpers stop/restart the render loop while they rebuild camera-dependent resources.
+ *  6. Invoke `disable()` when the element disconnects to tear down scenes, XR sessions, observers, and handlers.
  *
  * Public API Highlights
  *  - constructor(canvas, containers, options)
  *  - enable() / disable()
- *  - load()
+ *  - load() / reloadWithCurrentSettings()
  *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
- *  - getRenderSettings() / applyRenderSettings(partial)
- *  - setRenderSettings(settings) [via PrefViewer menu integration]
+ *  - getRenderSettings() / scheduleRenderSettingsReload(settings)
+ *  - setContainerVisibility(name, show)
+ *  - setMaterialOptions() / setCameraOptions() / setIBLOptions()
  *
- * Key Subsystems
- *  - Persistence: #applyRenderSettings, #loadStoredRenderSettings, #saveRenderSettings keep AA/SSAO/IBL/shadow flags synced.
- *  - Loading pipeline: #markContainersForReload, #markOptionsForReload, #loadAssetContainer, #loadContainers orchestrate deterministic reloads.
- *  - Visual setup: #configureDracoCompression, #createCamera, #createLights, #initializeVisualImprovements, #initializeAmbientOcclussion,
- *    #initializeIBLShadows, #initializeDefaultLightShadows, #initializeEnvironmentShadows, #setMaxSimultaneousLights.
- *  - Interaction + XR: #bindHandlers, #enableInteraction, #onPointerObservable, #onMouseWheel, #onKeyUp, #createXRExperience,
- *    #addStylesToARButton, #disposeXRExperience.
- *  - Container helpers: #addContainer, #removeContainer, #replaceContainer, #setOptions_Materials, #setOptions_Camera,
- *    #setOptions_IBL, #setVisibilityOfWallAndFloorInModel, #getPrefViewerComponent.
- *  - Metadata + download utilities: #checkModelMetadata, #checkInnerFloorTranslation, #translateNodeY, #addDateToName,
- *    #downloadZip, #openDownloadDialog.
- *
- * Notes
- *  - Designed to be long-lived per PrefViewer instance; it caches parent components to reflect `show-model/show-scene` attributes.
- *  - All browser-only features guard against SSR/Node usage by checking `window` before touching localStorage or XR APIs.
- *  - Relies on PrefViewerMenu3D events to trigger render-setting updates, ensuring UI and persisted state never drift apart.
+ * 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.
+ *  - 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.
+ *  - IBL shadows require `iblEnabled` plus `options.ibl.shadows` and a loaded HDR texture; otherwise fallback directional
+ *    lights and environment-contributed lights supply classic shadow generators.
+ *  - Browser-only features guard `window`, localStorage, and XR APIs before use so the controller is safe to construct
+ *    in SSR/Node contexts (though functionality activates only in browsers).
  */
 export default class BabylonJSController {
 
@@ -173,7 +173,7 @@ export default class BabylonJSController {
      * @param {object} [settings={}] - Partial map of render settings (AA, SSAO, IBL, shadows, etc.).
      * @returns {boolean} True when any setting changed and was saved.
      */
-    #applyRenderSettings(settings = {}) {
+    #saveRenderSettings(settings = {}) {
         if (!settings) {
             return false;
         }
@@ -186,12 +186,8 @@ export default class BabylonJSController {
             }
         });
 
-        if (changed && settings.iblEnabled === false && this.#scene) {
-            this.#scene.environmentTexture = null;
-        }
-
         if (changed) {
-            this.#saveRenderSettings();
+            this.#storeRenderSettings();
         }
 
         return changed;
@@ -229,14 +225,14 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #saveRenderSettings() {
+    #storeRenderSettings() {
         if (typeof window === "undefined" || !window?.localStorage) {
             return;
         }
         try {
             window.localStorage.setItem(this.#RENDER_SETTINGS_STORAGE_KEY, JSON.stringify(this.#settings));
         } catch (error) {
-            console.warn("PrefViewer: unable to save render settings", error);
+            console.warn("PrefViewer: unable to store render settings", error);
         }
     }
 
@@ -269,9 +265,6 @@ export default class BabylonJSController {
         if (this.#options?.materials) {
             Object.values(this.#options.materials).forEach((material) => material?.setPendingWithCurrent?.());
         }
-        if (this.#options?.ibl?.setPending) {
-            this.#options.ibl.setPending();
-        }
     }
 
     /**
@@ -382,49 +375,71 @@ export default class BabylonJSController {
      * Adds a hemispheric ambient light, a directional light for shadows, a shadow generator, and a camera-attached point light.
      * Sets light intensities and shadow properties for realistic rendering.
      * @private
-     * @returns {void}
+     * @returns {Promise<boolean>} Returns true if lights were changed, false otherwise.
      */
-    #createLights() {
-        if (this.#settings.iblEnabled && this.#options.ibl && this.#options.ibl.url) {
-            this.#hemiLight = this.#dirLight = this.#cameraLight = null;
-            this.#initializeEnvironmentTexture();
-        }
+    async #createLights() {
+        const hemiLightName = "PrefViewerHemiLight";
+        const cameraLightName = "PrefViewerCameraLight";
+        const dirLightName = "PrefViewerDirLight";
 
-        if (this.#scene.environmentTexture) {
-            return true;
-        }
+        const hemiLight = this.#scene.getLightByName(hemiLightName);
+        const cameraLight = this.#scene.getLightByName(cameraLightName);
+        const dirLight = this.#scene.getLightByName(dirLightName);
 
-        // 1) Stronger ambient fill
-        this.#hemiLight = this.#scene.getLightByName("PrefViewerHemiLight");
-        if (!this.#hemiLight) {
-            this.#hemiLight = new HemisphericLight("PrefViewerHemiLight", new Vector3(-10, 10, -10), this.#scene);
-            this.#hemiLight.intensity = 0.6;
-        }
+        let lightsChanged = false;
 
-        // 2) Directional light from the front-right, angled slightly down
-        this.#dirLight = this.#scene.getLightByName("PrefViewerDirLight");
-        if (!this.#dirLight) {
-            this.#dirLight = new DirectionalLight("PrefViewerDirLight", 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;
-        }
+        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl && this.#options.ibl.cachedUrl !== null;
+
+        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
+            if (this.#scene.environmentTexture) {
+                this.#scene.environmentTexture.dispose();
+                this.#scene.environmentTexture = null;
+                lightsChanged = true;
+            }
 
-        // 3) Camera‐attached headlight
-        this.#cameraLight = this.#scene.getLightByName("PrefViewerCameraLight");
-        if (!this.#cameraLight) {
-            this.#cameraLight = new PointLight("PrefViewerCameraLight", this.#camera.position, this.#scene);
-            this.#cameraLight.parent = this.#camera;
-            this.#cameraLight.intensity = 0.3;
+            // 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;
+            }
         }
+        return lightsChanged;
     }
 
     /**
      * Detaches and disposes the SSAO render pipeline from the active camera when it exists.
      * Guards against missing scene resources or absent pipelines, returning false when no cleanup is needed.
      * @private
-     * @returns {boolean} Returns true when the SSAO pipeline was disabled, false otherwise.
+     * @returns {Promise<boolean>} Returns true when the SSAO pipeline was disabled, false otherwise.
      */
-    #disableAmbientOcclusion() {
+    async #disableAmbientOcclusion() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
 
         if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
@@ -437,19 +452,19 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#renderPipelines.ssao) {
+        if (!this.#renderPipelines.ssao || !this.#renderPipelines.ssao?.name) {
             return false;
         }
 
         const pipelineName = this.#renderPipelines.ssao.name;
-        const ssaoPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+        let ssaoPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
 
         if (ssaoPipeline) {
             pipelineManager.detachCamerasFromRenderPipeline(pipelineName, [this.#scene.activeCamera]);
-            ssaoPipeline.dispose();
             pipelineManager.removePipeline(pipelineName);
             pipelineManager.update();
-            this.#renderPipelines.ssao = null;
+            ssaoPipeline.dispose();
+            this.#renderPipelines.ssao = ssaoPipeline = null;
         }
 
         return true;
@@ -460,9 +475,9 @@ export default class BabylonJSController {
      * Disposes previous SSAO pipelines, instantiates a tuned `SSAORenderingPipeline`, and attaches it to the
      * current camera so contact shadows enhance depth perception once assets reload or the camera changes.
      * @private
-     * @returns {boolean} True if the SSAO pipeline is supported and enabled, otherwise false.
+     * @returns {Promise<boolean>} True if the SSAO pipeline is supported and enabled, otherwise false.
      */
-    #initializeAmbientOcclussion() {
+    async #initializeAmbientOcclussion() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
         if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
             return false;
@@ -484,34 +499,35 @@ export default class BabylonJSController {
             combineRatio: 1.0
         };
 
-        this.#renderPipelines.ssao = new SSAORenderingPipeline(pipelineName, this.#scene, ssaoRatio, [this.#scene.activeCamera]);
+        let ssaoPipeline = new SSAORenderingPipeline(pipelineName, this.#scene, ssaoRatio, [this.#scene.activeCamera]);
 
-        if (!this.#renderPipelines.ssao){
+        if (!ssaoPipeline){
             return false;
         }   
 
-        if (this.#renderPipelines.ssao.isSupported) {
-            this.#renderPipelines.ssao.fallOff = 0.000001;
-            this.#renderPipelines.ssao.area = 1;
-            this.#renderPipelines.ssao.radius = 0.0001;
-            this.#renderPipelines.ssao.totalStrength = 1;
-            this.#renderPipelines.ssao.base = 0.6;
+        if (ssaoPipeline.isSupported) {
+            ssaoPipeline.fallOff = 0.000001;
+            ssaoPipeline.area = 1;
+            ssaoPipeline.radius = 0.0001;
+            ssaoPipeline.totalStrength = 1;
+            ssaoPipeline.base = 0.6;
             
             // Configure SSAO to calculate only once instead of every frame for better performance
-            if (this.#renderPipelines.ssao._ssaoPostProcess) {
-                this.#renderPipelines.ssao._ssaoPostProcess.autoClear = false;
-                this.#renderPipelines.ssao._ssaoPostProcess.samples = 1;
+            if (ssaoPipeline._ssaoPostProcess) {
+                ssaoPipeline._ssaoPostProcess.autoClear = false;
+                ssaoPipeline._ssaoPostProcess.samples = 1;
             }
-            if (this.#renderPipelines.ssao._combinePostProcess) {
-                this.#renderPipelines.ssao._combinePostProcess.autoClear = false;
-                this.#renderPipelines.ssao._combinePostProcess.samples = 1;
+            if (ssaoPipeline._combinePostProcess) {
+                ssaoPipeline._combinePostProcess.autoClear = false;
+                ssaoPipeline._combinePostProcess.samples = 1;
             }
             
+            this.#renderPipelines.ssao = ssaoPipeline;
             pipelineManager.update();
             return true;
         } else {
-            this.#renderPipelines.ssao.dispose();
-            this.#renderPipelines.ssao = null;
+            ssaoPipeline.dispose();
+            this.#renderPipelines.ssao = ssaoPipeline = null;
             pipelineManager.update();
             return false;
         }
@@ -521,9 +537,9 @@ export default class BabylonJSController {
      * Tears down the default rendering pipeline (MSAA/FXAA/grain) for the active camera when present.
      * Ensures stale pipelines detach cleanly so a fresh one can be installed on the next load.
      * @private
-     * @returns {boolean} Returns true when the pipeline was removed, false otherwise.
+     * @returns {Promise<boolean>} Returns true when the pipeline was removed, false otherwise.
      */
-    #disableVisualImprovements() {
+    async #disableVisualImprovements() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
 
         if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
@@ -536,19 +552,19 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#renderPipelines.default) {
+        if (!this.#renderPipelines.default || !this.#renderPipelines.default?.name) {
             return false;
         }
 
         const pipelineName = this.#renderPipelines.default.name;
-        const defaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+        let defaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
 
         if (defaultPipeline) {
             pipelineManager.detachCamerasFromRenderPipeline(pipelineName, [this.#scene.activeCamera]);
-            defaultPipeline.dispose();
             pipelineManager.removePipeline(pipelineName);
             pipelineManager.update();
-            this.#renderPipelines.default = null;
+            defaultPipeline.dispose();
+            this.#renderPipelines.default = defaultPipeline = null;
         }
 
         return true;
@@ -559,10 +575,10 @@ export default class BabylonJSController {
      * Disposes any previous pipeline instance to avoid duplicates, then attaches a fresh
      * `DefaultRenderingPipeline` with tuned settings for sharper anti-aliasing and subtle grain.
      * @private
-     * @returns {boolean} True when the pipeline is supported and active, otherwise false.
+     * @returns {Promise<boolean>} True when the pipeline is supported and active, otherwise false.
      * @see {@link https://doc.babylonjs.com/features/featuresDeepDive/postProcesses/defaultRenderingPipeline|Using the Default Rendering Pipeline | Babylon.js Documentation}
      */
-    #initializeVisualImprovements() {
+    async #initializeVisualImprovements() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
         if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
             return false;
@@ -579,49 +595,51 @@ export default class BabylonJSController {
         
         const pipelineName = "PrefViewerDefaultRenderingPipeline";
 
-        this.#renderPipelines.default = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
+        let defaultPipeline = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
 
-        if (!this.#renderPipelines.default){
+        if (!defaultPipeline){
             return false;
         } 
 
-        if (this.#renderPipelines.default.isSupported) {
+        if (defaultPipeline.isSupported) {
             // MSAA - Multisample Anti-Aliasing
             const caps = this.#scene.getEngine()?.getCaps?.() || {};
             const maxSamples = typeof caps.maxMSAASamples === "number" ? caps.maxMSAASamples : 4;
-            this.#renderPipelines.default.samples = Math.max(1, Math.min(8, maxSamples));
+            defaultPipeline.samples = Math.max(1, Math.min(8, maxSamples));
             // FXAA - Fast Approximate Anti-Aliasing
-            this.#renderPipelines.default.fxaaEnabled = true;
-            this.#renderPipelines.default.fxaa.samples = 8;
-            this.#renderPipelines.default.fxaa.adaptScaleToCurrentViewport = true;
-            if (this.#renderPipelines.default.fxaa.edgeThreshold !== undefined) {
-                this.#renderPipelines.default.fxaa.edgeThreshold = 0.125;
+            defaultPipeline.fxaaEnabled = true;
+            defaultPipeline.fxaa.samples = 8;
+            defaultPipeline.fxaa.adaptScaleToCurrentViewport = true;
+            if (defaultPipeline.fxaa.edgeThreshold !== undefined) {
+                defaultPipeline.fxaa.edgeThreshold = 0.125;
             }
-            if (this.#renderPipelines.default.fxaa.edgeThresholdMin !== undefined) {
-                this.#renderPipelines.default.fxaa.edgeThresholdMin = 0.0625;
+            if (defaultPipeline.fxaa.edgeThresholdMin !== undefined) {
+                defaultPipeline.fxaa.edgeThresholdMin = 0.0625;
             }
-            if (this.#renderPipelines.default.fxaa.subPixelQuality !== undefined) {
-                this.#renderPipelines.default.fxaa.subPixelQuality = 0.75;
+            if (defaultPipeline.fxaa.subPixelQuality !== undefined) {
+                defaultPipeline.fxaa.subPixelQuality = 0.75;
             }
 
             // Grain
-            this.#renderPipelines.default.grainEnabled = true;
-            this.#renderPipelines.default.grain.adaptScaleToCurrentViewport = true;
-            this.#renderPipelines.default.grain.animated = false;
-            this.#renderPipelines.default.grain.intensity = 3;
+            defaultPipeline.grainEnabled = true;
+            defaultPipeline.grain.adaptScaleToCurrentViewport = true;
+            defaultPipeline.grain.animated = false;
+            defaultPipeline.grain.intensity = 3;
 
             // Configure post-processes to calculate only once instead of every frame for better performance
-            if (this.#renderPipelines.default.fxaa?._postProcess) {
-                this.#renderPipelines.default.fxaa._postProcess.autoClear = false;
+            if (defaultPipeline.fxaa?._postProcess) {
+                defaultPipeline.fxaa._postProcess.autoClear = false;
             }
-            if (this.#renderPipelines.default.grain?._postProcess) {
-                this.#renderPipelines.default.grain._postProcess.autoClear = false;
+            if (defaultPipeline.grain?._postProcess) {
+                defaultPipeline.grain._postProcess.autoClear = false;
             }
 
+            this.#renderPipelines.default = defaultPipeline;
             pipelineManager.update();
             return true;
         } else {
-            this.#renderPipelines.default.dispose();
+            defaultPipeline.dispose();
+            this.#renderPipelines.default = defaultPipeline = null;
             pipelineManager.update();
             return false;
         }
@@ -632,13 +650,19 @@ export default class BabylonJSController {
      * Loads an HDR texture from a predefined URI and assigns it to the scene's environmentTexture property.
      * Configures gamma space, mipmaps, and intensity level for realistic lighting.
      * @private
-     * @returns {boolean}
+     * @returns {Promise<boolean>} Returns true if the environment texture was changed, false if it was already up to date or failed to load.
      */
-    #initializeEnvironmentTexture() {
-        const hdrTextureURI = this.#options.ibl.url;
-        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 128, false, false, false, true);
+    async #initializeEnvironmentTexture() {
+        if (this.#scene.environmentTexture) {
+            this.#scene.environmentTexture.dispose();
+            this.#scene.environmentTexture = null;
+        }
+        const hdrTextureURI = this.#options.ibl.cachedUrl;
+        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 1024, false, false, false, true, undefined, undefined, false, true, true);
+        await WhenTextureReadyAsync(hdrTexture);
         hdrTexture.level = this.#options.ibl.intensity;
         this.#scene.environmentTexture = hdrTexture;
+        this.#scene.markAllMaterialsAsDirty(Material.TextureDirtyFlag);
         return true;
     }
 
@@ -646,9 +670,9 @@ export default class BabylonJSController {
      * Removes the IBL shadow render pipeline from the active camera when present.
      * Ensures voxelized shadow data is disposed so reloading environments installs a clean pipeline.
      * @private
-     * @returns {boolean} Returns true when the pipeline was removed, false otherwise.
+     * @returns {Promise<boolean>} Returns true when the pipeline was removed, false otherwise.
      */
-    #disableIBLShadows() {
+    async #disableIBLShadows() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
 
         if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
@@ -661,19 +685,23 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#renderPipelines.iblShadows) {
+        if (!this.#renderPipelines.iblShadows || !this.#renderPipelines.iblShadows?.name) {
             return false;
         }
 
         const pipelineName = this.#renderPipelines.iblShadows.name;
-        const defaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+        let iblShadowsPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
 
-        if (defaultPipeline) {
+        if (iblShadowsPipeline) {
+            iblShadowsPipeline.toggleShadow(false);
+            iblShadowsPipeline.clearShadowCastingMeshes();
+            iblShadowsPipeline.clearShadowReceivingMaterials();
+            iblShadowsPipeline.resetAccumulation();
             pipelineManager.detachCamerasFromRenderPipeline(pipelineName, [this.#scene.activeCamera]);
-            defaultPipeline.dispose();
             pipelineManager.removePipeline(pipelineName);
             pipelineManager.update();
-            this.#renderPipelines.iblShadows = null;
+            iblShadowsPipeline.dispose();
+            this.#renderPipelines.iblShadows = iblShadowsPipeline = null;
         }
 
         return true;
@@ -685,24 +713,36 @@ export default class BabylonJSController {
      * Configures pipeline options for resolution, sampling, opacity, and debugging.
      * Only applies if the scene has an environment texture set.
      * @private
-     * @returns {void|false} Returns false if no environment texture is set; otherwise void.
+     * @returns {Promise<void|boolean>} Returns false if no environment texture is set; otherwise void.
      */
-    #initializeIBLShadows() {
+    async #initializeIBLShadows() {
+
+        await this.#scene.whenReadyAsync();
+
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
 
         if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
             return false;
         }
-
+        
         if (!this.#scene.environmentTexture) {
             return false;
         }
+
+        if (!this.#scene.environmentTexture.isReady()) {
+            const self = this;
+            this.#scene.environmentTexture.onLoadObservable.addOnce(() => {
+                self.#initializeIBLShadows();
+            });
+            return false;
+        }
+        
         const supportedPipelines = pipelineManager.supportedPipelines;
         
         if (!supportedPipelines) {
             return false;
         }
-        
+
         const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
         const pipelineOptions = {
@@ -714,13 +754,13 @@ export default class BabylonJSController {
             shadowOpacity: 0.85,
         };
 
-        this.#renderPipelines.iblShadows = new IblShadowsRenderPipeline(pipelineName, this.#scene, pipelineOptions, [this.#scene.activeCamera]);
+        let iblShadowsPipeline = new IblShadowsRenderPipeline(pipelineName, this.#scene, pipelineOptions, [this.#scene.activeCamera]);
 
-        if (!this.#renderPipelines.iblShadows) {
+        if (!iblShadowsPipeline) {
             return false;
         }
        
-        if (this.#renderPipelines.iblShadows.isSupported) {
+        if (iblShadowsPipeline.isSupported) {
             // Disable all debug passes for performance
             const pipelineProps = {
                 allowDebugPasses: false,
@@ -734,13 +774,8 @@ export default class BabylonJSController {
                 accumulationPassDebugEnabled: false,
             };
 
-            Object.assign(this.#renderPipelines.iblShadows, pipelineProps);
-
-            if (this.#renderPipelines.iblShadows._ssaoPostProcess) {
-                this.#renderPipelines.iblShadows._ssaoPostProcess.autoClear = false;
-                this.#renderPipelines.iblShadows._ssaoPostProcess.samples = 1;
-            }
-
+            Object.assign(iblShadowsPipeline, pipelineProps);
+            
             this.#scene.meshes.forEach((mesh) => {
                 const isRootMesh = mesh.id.startsWith("__root__");
                 if (isRootMesh) {
@@ -750,25 +785,28 @@ export default class BabylonJSController {
                 const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
                 const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
                 const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
-
+                
                 if (meshGenerateShadows) {
-                    this.#renderPipelines.iblShadows.addShadowCastingMesh(mesh);
-                    this.#renderPipelines.iblShadows.updateSceneBounds();
+                    iblShadowsPipeline.addShadowCastingMesh(mesh);
+                    iblShadowsPipeline.updateSceneBounds();
                 }
             });
-
+            
             this.#scene.materials.forEach((material) => {
                 if (material instanceof PBRMaterial) {
                     material.enableSpecularAntiAliasing = false;
                 }
-                this.#renderPipelines.iblShadows.addShadowReceivingMaterial(material);
+                iblShadowsPipeline.addShadowReceivingMaterial(material);
             });
-
-            this.#renderPipelines.iblShadows.updateVoxelization();
+            
+            iblShadowsPipeline.toggleShadow(true);
+            iblShadowsPipeline.updateVoxelization();
+            this.#renderPipelines.iblShadows = iblShadowsPipeline;
             pipelineManager.update();
             return true;
         } else {
-            this.#renderPipelines.iblShadows.dispose();
+            iblShadowsPipeline.dispose();
+            this.#renderPipelines.iblShadows = iblShadowsPipeline = null;
             pipelineManager.update();
             return false;
         }
@@ -802,7 +840,7 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #initializeDefaultLightShadows() {
+    async #initializeDefaultLightShadows() {
         if (!this.#dirLight) {
             return;
         }
@@ -825,7 +863,7 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #initializeEnvironmentShadows() {
+    async #initializeEnvironmentShadows() {
         this.#shadowGen = this.#shadowGen.filter((generator) => {
             if (!generator || typeof generator.getLight !== "function") {
                 return false;
@@ -874,12 +912,12 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #disableShadows() {
+    async #disableShadows() {
         this.#shadowGen.forEach((shadowGenerator) => {
             shadowGenerator.dispose();
         });
         this.#shadowGen = [];
-        this.#disableIBLShadows();
+        await this.#disableIBLShadows();
     }
 
     /**
@@ -890,28 +928,22 @@ export default class BabylonJSController {
      * If no environment texture is set, initializes IBL shadows.
      * Otherwise, sets up shadow casting and receiving for all relevant meshes using the shadow generator.
      */
-    #initializeShadows() {
+    async #initializeShadows() {
         if (!this.#settings.shadowsEnabled) {
             return false;
         }
 
         this.#ensureMeshesReceiveShadows();
 
-        if (this.#scene.environmentTexture) {
-            if (this.#options.ibl.shadows) {
-                if (this.#scene.environmentTexture.isReady()) {
-                    this.#initializeIBLShadows();
-                } else {
-                    const self = this;
-                    this.#scene.environmentTexture.onLoadObservable.addOnce(() => {
-                        self.#initializeIBLShadows();
-                    });
-                }
-            }
+        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl && this.#options.ibl.cachedUrl !== null;
+        const iblShadowsEnabled = iblEnabled && this.#options.ibl.shadows;
+
+        if (iblShadowsEnabled) {
+            await this.#initializeIBLShadows();
         } else {
-            this.#initializeDefaultLightShadows();
+            await this.#initializeDefaultLightShadows();
         }
-        this.#initializeEnvironmentShadows();
+        await this.#initializeEnvironmentShadows();
     }
 
     /**
@@ -1244,14 +1276,8 @@ export default class BabylonJSController {
      * @private
      * @returns {boolean} True when lights were refreshed due to pending IBL changes, otherwise false.
      */
-    #setOptions_IBL() {
-        if (this.#options.ibl.isPending && this.#settings.iblEnabled) {
-            this.#options.ibl.setSuccess(true);
-            this.#createLights();
-            return true;
-        }
-        this.#createLights();
-        return false;
+    async #setOptions_IBL() {
+        return await this.#createLights();
     }
 
     /**
@@ -1373,6 +1399,52 @@ export default class BabylonJSController {
         return this.#addContainer(container, false);
     }
 
+    /**
+     * Stops every animation group on the provided asset container to guarantee new loads start from a clean state.
+     * @private
+     * @param {AssetContainer} assetContainer - Container whose animation groups should be halted.
+     */
+    #assetContainer_stopAnimations(assetContainer) {
+        if (!assetContainer.animationGroups || assetContainer.animationGroups.length === 0) {
+            return;
+        }
+        assetContainer.animationGroups.forEach((animationGroup) => {
+            animationGroup.stop();
+        });
+    }
+
+    /**
+     * Disposes every imported light so subsequent reloads avoid duplicating scene illumination.
+     * @private
+     * @param {AssetContainer} assetContainer - Container whose lights should be cleaned up.
+     * @returns {void}
+     */
+    #assetContainer_deleteLights(assetContainer) {
+        if (!assetContainer.lights || assetContainer.lights.length === 0) {
+            return;
+        }
+        assetContainer.lights.forEach((light) => {
+            light.dispose();
+        });
+        assetContainer.lights = [];
+    }
+
+    /**
+     * Assigns unique ids to every imported camera so Babylon.js does not reuse stale SSAO effects between reloads.
+     * @private
+     * @param {AssetContainer} assetContainer - Container whose cameras need deterministic id regeneration.
+     * @returns {void}
+     */
+    #assetContainer_retagCameras(assetContainer) {
+        if (!assetContainer.cameras || assetContainer.cameras.length === 0) {
+            return;
+        }
+        assetContainer.cameras.forEach((camera) => {
+            const sufix = "_" + Date.now();
+            camera.id = `${camera.id || camera.name || "camera"}${sufix}`;
+        });
+    }
+
     /**
      * Sets the visibility of wall and floor meshes in the model container based on the provided value or environment visibility.
      * @private
@@ -1394,9 +1466,9 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #stopRender() {
+    async #stopRender() {
         this.#engine.stopRenderLoop(this.#handlers.renderLoop);
-        this.#unloadCameraDependentEffects();
+        await this.#unloadCameraDependentEffects();
     }
     /**
      * Starts the Babylon.js render loop for the current scene.
@@ -1405,21 +1477,30 @@ export default class BabylonJSController {
      * @returns {Promise<void>}
      */
     async #startRender() {
-        this.#loadCameraDependentEffects();
-        await this.#scene.whenReadyAsync();
-        this.#engine.runRenderLoop(this.#handlers.renderLoop);
+        await this.#loadCameraDependentEffects();
+        this.#scene.executeWhenReady(() => {
+            this.#engine.runRenderLoop(this.#handlers.renderLoop);
+        });
     }
 
     /**
-     * Loads an asset container (model, environment, materials, etc.) using the provided container state.
+     * Loads a single asset container (model, environment, materials, etc.) based on the container state flags.
+     * Skips work when nothing is pending, otherwise resolves the GLTF source, refreshes cache metadata and streams it
+     * into the Babylon.js scene via `LoadAssetContainerAsync`.
      * @private
-     * @param {object} container - The container object containing asset state and metadata.
-     * @returns {Promise<[object, AssetContainer|boolean]>} Resolves to an array with the container and the loaded asset container, or false if loading fails.
+     * @param {object} container - Container descriptor that carries the GLTF storage pointer and current cache info.
+     * @param {boolean} [force=false] - When true, bypasses cached size/timestamp so the resolver re-downloads the asset.
+     * @returns {Promise<[object, AssetContainer|boolean]>} Resolves to `[container, assetContainer]` on success, or
+     * `[container, false]` when loading was skipped or failed.
      * @description
-     * Resolves the asset source using GLTFResolver, prepares plugin options, and loads the asset into the Babylon.js scene.
-     * Updates the container's cache data and returns the container along with the loaded asset container or false if loading fails.
+     * 1. Validates that the container has pending data and initializes the shared `GLTFResolver` if needed.
+     * 2. Requests the source blob (respecting the cached size/timestamp unless `force` is set) and stores the new cache
+     *    metadata via `setPendingCacheData`.
+     * 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) {
+    async #loadAssetContainer(container, force = false) {
+
         if (container?.state?.update?.storage === undefined || container?.state?.size === undefined || container?.state?.timeStamp === undefined) {
             return [container, false];
         }
@@ -1431,9 +1512,12 @@ export default class BabylonJSController {
         if (!this.#gltfResolver) {
             this.#gltfResolver = new GLTFResolver();
         }
-        //let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, container.state.size, container.state.timeStamp);
-        // TEMPORARY: We never pass 'size' or 'timeStamp' to always force a reload and avoid issues with the active camera in reloading assetContainers
-        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, 0, null);
+
+        const currentSize = force ? 0 : container.state.size;
+        const currentTimeStamp = force ? null : container.state.timeStamp;
+
+        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, currentSize, currentTimeStamp);
+
         if (!sourceData) {
             return [container, false];
         }
@@ -1475,7 +1559,7 @@ export default class BabylonJSController {
      * Returns an object with success status and error details.
      */
     async #loadContainers() {
-        this.#stopRender();
+        await this.#stopRender();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
@@ -1491,22 +1575,19 @@ export default class BabylonJSController {
         };
 
         await Promise.allSettled(promiseArray)
-            .then((values) => {
+            .then(async (values) => {
                 this.#disposeAnimationController();
                 values.forEach((result) => {
                     const container = result.value ? result.value[0] : null;
                     const assetContainer = result.value ? result.value[1] : null;
                     if (result.status === "fulfilled" && assetContainer) {
                         if (container.state.name === "model") {
-                            assetContainer.lights = [];
+                            this.#assetContainer_deleteLights(assetContainer);
+                            this.#assetContainer_stopAnimations(assetContainer);
                             newModelMetadata = { ...(container.state.update.metadata ?? {}) };
                         }
                         if (container.state.name === "model" || container.state.name === "environment") {
-                            assetContainer.cameras.forEach((camera) => {
-                                // To avoid conflicts when reloading the model we rename the id because Babylon.js caches the camera's SSAO effect by id.
-                                const sufix = "_" + Date.now();
-                                camera.id = `${camera.id || camera.name || "camera"}${sufix}`;
-                            });
+                            this.#assetContainer_retagCameras(assetContainer);
                         }
                         this.#replaceContainer(container, assetContainer);
                         container.state.setSuccess(true);
@@ -1520,7 +1601,7 @@ export default class BabylonJSController {
 
                 this.#setOptions_Materials();
                 this.#setOptions_Camera();
-                this.#setOptions_IBL();
+                await this.#setOptions_IBL();
                 this.#setVisibilityOfWallAndFloorInModel();
                 detail.success = true;
             })
@@ -1534,7 +1615,7 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
-                this.#startRender();
+                await this.#startRender();
             });
         return detail;
     }
@@ -1545,10 +1626,10 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #loadCameraDependentEffects() {
-        this.#initializeVisualImprovements();
-        this.#initializeAmbientOcclussion();
-        this.#initializeShadows();
+    async #loadCameraDependentEffects() {
+        await this.#initializeVisualImprovements();
+        await this.#initializeAmbientOcclussion();
+        await this.#initializeShadows();
     }
 
     /**
@@ -1557,10 +1638,10 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #unloadCameraDependentEffects() {
-        this.#disableVisualImprovements();
-        this.#disableAmbientOcclusion();
-        this.#disableShadows();
+    async #unloadCameraDependentEffects() {
+        await this.#disableVisualImprovements();
+        await this.#disableAmbientOcclusion();
+        await this.#disableShadows();
     }
 
     /**
@@ -1804,7 +1885,15 @@ export default class BabylonJSController {
             geometryBufferRenderer.generateNormalsInWorldSpace = true;
         }
 
-        this.#scene.clearColor = new Color4(1, 1, 1, 1);
+        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.#createCamera();
         this.#enableInteraction();
         await this.#createXRExperience();
@@ -1950,26 +2039,6 @@ export default class BabylonJSController {
         return await this.#loadContainers();
     }
 
-    /**
-     * Merges incoming render flags with the current configuration, persists them, and marks
-     * all dependent loaders/options as pending when something actually changed.
-     * @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}}}
-     * @description
-     * Callers can inspect the `changed` flag to decide whether to trigger a reload with
-     * `reloadWithCurrentSettings()` or simply reuse the returned snapshot.
-     */
-    scheduleRenderSettingsReload(settings = {}) {
-        const changed = this.#applyRenderSettings(settings);
-        if (!changed) {
-            return { changed: false, settings: this.getRenderSettings() };
-        }
-        this.#markContainersForReload();
-        this.#markOptionsForReload();
-        return { changed: true, settings: this.getRenderSettings() };
-    }
-
     /**
      * Applies camera options from the configuration to the active camera.
      * Stops and restarts the render loop to apply changes.
@@ -2000,7 +2069,7 @@ export default class BabylonJSController {
      * Reapplies image-based lighting configuration (HDR URL, intensity, shadow mode).
      * Stops rendering, pushes pending IBL state into the scene, rebuilds camera-dependent effects, then resumes rendering.
      * @public
-     * @returns {void}
+     * @returns {boolean} True if IBL options were set successfully, false otherwise.
      */
     setIBLOptions() {
         this.#stopRender();
@@ -2033,6 +2102,26 @@ export default class BabylonJSController {
         this.#startRender();
     }
 
+    /**
+     * Merges incoming render flags with the current configuration, persists them, and marks
+     * all dependent loaders/options as pending when something actually changed.
+     * @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}}}
+     * @description
+     * Callers can inspect the `changed` flag to decide whether to trigger a reload with
+     * `reloadWithCurrentSettings()` or simply reuse the returned snapshot.
+     */
+    scheduleRenderSettingsReload(settings = {}) {
+        const changed = this.#saveRenderSettings(settings);
+        if (!changed) {
+            return { changed: false, settings: this.getRenderSettings() };
+        }
+        this.#markContainersForReload();
+        this.#markOptionsForReload();
+        return { changed: true, settings: this.getRenderSettings() };
+    }
+
     /**
      * Reloads every asset container using the latest staged render settings.
      * Intended to be called after `scheduleRenderSettingsReload()` marks data as pending.

package/src/pref-viewer-3d-data.js

@@ -70,9 +70,7 @@ export class ContainerData {
         }
         const targetShow = this.update.show !== null ? this.update.show : this.show;
         this.setPending(storedSource, targetShow);
-        this.update.size = this.size;
-        this.update.timeStamp = this.timeStamp;
-        this.update.metadata = { ...(this.metadata ?? {}) };
+        this.setPendingCacheData(this.size, this.timeStamp, this.metadata);
         return true;
     }
     get isPending() {
@@ -225,38 +223,20 @@ export class CameraData {
  *  - Inspect `isPending`/`isSuccess` to drive UI or re-render logic.
  */
 export class IBLData {
-    constructor(url = null, intensity = 1.0, shadows = false, timeStamp = null) {
+    defaultIntensity = 1.0;
+    defaultShadows = false;
+    constructor(url = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null) {
         this.url = url;
+        this.cachedUrl = null;
         this.intensity = intensity;
         this.shadows = shadows;
         this.timeStamp = timeStamp;
-        this.reset();
-    }
-    reset() {
-        this.pending = false;
-        this.success = false;
-    }
-    setValues(url, intensity, shadows, timeStamp) {
-        this.url = url !== undefined ? url : this.url;
-        this.intensity = intensity !== undefined ? intensity : this.intensity;
-        this.shadows = shadows !== undefined ? shadows : this.shadows;
-        this.timeStamp = timeStamp !== undefined ? timeStamp : this.timeStamp;
-    }
-    setSuccess(success = false) {
-        if (success) {
-            this.success = true;
-        } else {
-            this.success = false;
-        }
     }
-    setPending() {
-        this.pending = true;
-        this.success = false;
-    }
-    get isPending() {
-        return this.pending === true;
-    }
-    get isSuccess() {
-        return this.success === true;
+    setValues(url, cachedUrl = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null) {
+        this.url = url;
+        this.cachedUrl = cachedUrl;
+        this.intensity = intensity;
+        this.shadows = shadows;
+        this.timeStamp = timeStamp;
     }
 }

package/src/pref-viewer-3d.js

@@ -239,7 +239,6 @@ export default class PrefViewer3D extends HTMLElement {
         Object.values(this.#data.containers).forEach((container) => container.reset());
         Object.values(this.#data.options.materials).forEach((material) => material.reset());
         this.#data.options.camera.reset();
-        this.#data.options.ibl.reset();
     }
 
     /**
@@ -335,6 +334,7 @@ export default class PrefViewer3D extends HTMLElement {
         const iblState = this.#data.options.ibl;
 
         let url = undefined;
+        let cachedUrl = undefined;
         let timeStamp = undefined;
         let shadows = undefined;
         let intensity = undefined;
@@ -344,7 +344,7 @@ export default class PrefViewer3D extends HTMLElement {
             const fileStorage = new FileStorage("PrefViewer", "Files");
             const newURL = await fileStorage.getURL(options.ibl.url);
             if (newURL) {
-                url = newURL;
+                cachedUrl = newURL;
                 timeStamp = await fileStorage.getTimeStamp(options.ibl.url);
             }
         }
@@ -358,10 +358,11 @@ export default class PrefViewer3D extends HTMLElement {
         const needUpdate = url !== undefined && url !== iblState.url ||
             timeStamp !== undefined && timeStamp !== iblState.timeStamp ||
             shadows !== undefined && shadows !== iblState.shadows ||
-            intensity !== undefined && intensity !== iblState.intensity;
+            shadows === undefined && iblState.shadows !== iblState.defaultShadows ||
+            intensity !== undefined && intensity !== iblState.intensity ||
+            intensity === undefined && iblState.intensity !== iblState.defaultIntensity;
         if (needUpdate) {
-            iblState.setValues(url, intensity, shadows, timeStamp);
-            iblState.setPending(true);
+            iblState.setValues(url, cachedUrl, intensity, shadows, timeStamp);
         }
         
         return needUpdate;

package/src/pref-viewer-menu-3d.js

@@ -9,7 +9,7 @@ import { DEFAULT_LOCALE, resolveLocale, translate } from "./localization/i18n.js
  *  - Builds an accessible hover/focus-activated panel with switches for AA, SSAO, IBL, and dynamic shadows.
  *  - Caches translated copy in `#texts` and listens for culture changes via the `culture` attribute or `setCulture()`.
  *  - Tracks applied vs. draft render settings so pending diffs, button enablement, and status text stay in sync.
- *  - Emits `pref-viewer-menu-apply` whenever the user confirms toggles, allowing PrefViewer/BabylonJSController to persist.
+ *  - Emits `pref-viewer-menu-3d-apply` whenever the user confirms toggles, allowing PrefViewer/BabylonJSController to persist.
  *  - Shows transient status/error messages and per-switch pending states while operations complete.
  *
  * Public API:
@@ -369,8 +369,15 @@ export default class PrefViewerMenu3D extends HTMLElement {
         if (this.#isApplying || !this.#hasPendingChanges()) {
             return;
         }
+
         const detail = { settings: { ...this.#draftSettings } };
-        this.dispatchEvent(new CustomEvent("pref-viewer-menu-apply", { detail, bubbles: true, composed: true }));
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("pref-viewer-menu-3d-apply", customEventOptions));
     }
 
     /**

package/src/pref-viewer.js

@@ -216,7 +216,7 @@ export default class PrefViewer extends HTMLElement {
             this.#component3D.remove();
         }
         if (this.#menu3D) {
-            this.#menu3D.removeEventListener("pref-viewer-menu-apply", this.#handlers.onMenuApply);
+            this.#menu3D.removeEventListener("pref-viewer-menu-3d-apply", this.#handlers.onMenuApply);
             this.#menu3D.remove();
             this.#menu3D = null;
         }
@@ -264,7 +264,7 @@ export default class PrefViewer extends HTMLElement {
             return;
         }
         if (this.#menu3D) {
-            this.#menu3D.removeEventListener("pref-viewer-menu-apply", this.#handlers.onMenuApply);
+            this.#menu3D.removeEventListener("pref-viewer-menu-3d-apply", this.#handlers.onMenuApply);
             this.#menu3D.remove();
         }
         this.#menu3D = document.createElement("pref-viewer-menu-3d");
@@ -280,7 +280,7 @@ export default class PrefViewer extends HTMLElement {
         this.#handlers.onViewerHoverStart = () => this.#menu3D.setViewerHover(true);
         this.#handlers.onViewerHoverEnd = () => this.#menu3D.setViewerHover(false);
 
-        this.#menu3D.addEventListener("pref-viewer-menu-apply", this.#handlers.onMenuApply);
+        this.#menu3D.addEventListener("pref-viewer-menu-3d-apply", this.#handlers.onMenuApply);
         this.#wrapper.addEventListener("mouseenter", this.#handlers.onViewerHoverStart);
         this.#wrapper.addEventListener("mouseleave", this.#handlers.onViewerHoverEnd);
 
@@ -601,7 +601,7 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Handles the custom "pref-viewer-menu-apply" event emitted by the menu component.
+     * Handles the custom "pref-viewer-menu-3d-apply" event emitted by the menu component.
      * Forwards the requested settings to the render-application pipeline.
      * @private
      * @param {CustomEvent} event - Menu event containing the `settings` payload.