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

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";
@@ -8,59 +8,73 @@ import JSZip from "jszip";
 import GLTFResolver from "./gltf-resolver.js";
 import { MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
+import OpeningAnimation from "./babylonjs-animation-opening.js";
 import { translate } from "./localization/i18n.js";
 
 /**
- * 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 render loops plus a throttled
+ *    ResizeObserver, 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, using sampled pointer picking and last-picked tracking to reduce raycast/highlight
+ *    cost on dense scenes.
  *  - 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.
+ *     `disable()` is asynchronous; it waits for XR/session shutdown before engine disposal and also disposes the
+ *     shared GLTF resolver, which closes its internal IndexedDB handle.
  *
  * 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.
+ *  - IBL lifecycle: when `options.ibl.cachedUrl` is present, a new `HDRCubeTexture` is created and cloned into `#hdrTexture`;
+ *    then `options.ibl.consumeCachedUrl(true)` clears/revokes the temporary URL. Subsequent reloads reuse `#hdrTexture.clone()`
+ *    while `options.ibl.valid` remains true.
+ *  - 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).
+ *  - Pointer-pick lifecycle: hover/highlight raycasts are sampled on POINTERMOVE (time + distance thresholds), wheel
+ *    input avoids picks entirely, and right-click POINTERUP performs an on-demand pick for context-menu targeting.
+ *  - Runtime bookkeeping is split into mutable `#state` and tuning constants under `#config` to keep behavior changes
+ *    explicit and reduce cross-field drift.
+ *  - Resize lifecycle: canvas resize notifications are throttled (with trailing execution) before calling `engine.resize()`
+ *    and any queued resize callback is canceled during teardown.
+ *  - Teardown lifecycle: concurrent `disable()` calls are coalesced into a single in-flight promise to avoid races
+ *    during XR exit and engine disposal.
  */
 export default class BabylonJSController {
-
     #RENDER_SETTINGS_STORAGE_KEY = "pref-viewer/render-settings";
 
     // Default render settings
@@ -72,7 +86,7 @@ export default class BabylonJSController {
         iblEnabled: true,
         shadowsEnabled: false,
     };
-    
+
     // Canvas HTML element
     #canvas = null;
 
@@ -91,9 +105,11 @@ export default class BabylonJSController {
     #XRExperience = null;
     #canvasResizeObserver = null;
     
+    #hdrTexture = null; // reusable in-memory HDR source cloned into scene.environmentTexture across reloads
+
     #containers = {};
     #options = {};
-    
+
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
 
@@ -104,13 +120,63 @@ export default class BabylonJSController {
     };
 
     #handlers = {
+        onAnimationGroupChanged: null,
         onKeyUp: null,
         onPointerObservable: null,
+        onResize: null,
         renderLoop: null,
     };
-    
+
     #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
 
+    // Runtime mutable state (changes while the app is running).
+    #state = {
+        // Pointer-picking sampling state avoids expensive scene.pick on every move.
+        pointerPicking: {
+            lastMovePickAt: 0,
+            lastMovePickX: NaN,
+            lastMovePickY: NaN,
+            lastPickedMeshId: null,
+        },
+        // Render loop state balances performance with responsiveness.
+        render: {
+            isLoopRunning: false,
+            dirtyFrames: 0,
+            continuousUntil: 0,
+            lastRenderAt: 0,
+        },
+        // Resize state batches frequent ResizeObserver notifications.
+        resize: {
+            isScheduled: false,
+            timeoutId: null,
+            lastAppliedAt: 0,
+        },
+    };
+
+    // Runtime configuration constants (tuning knobs, not per-frame state).
+    #config = {
+        pointerPicking: {
+            movePickIntervalMs: 50, // cap expensive scene.pick calls to ~20 Hz while moving the pointer
+            movePickMinDistancePx: 2, // skip picks for sub-pixel jitter
+        },
+        render: {
+            burstFramesBase: 2,
+            burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
+            interactionMs: 250,
+            animationMs: 200,
+            idleThrottleMs: 1000 / 15,
+        },
+        resize: {
+            throttleMs: 50, // cap resize work to ~20 Hz while dragging/resizing containers
+        },
+    };
+
+    // Promises to track async disable() lifecycle when XR and general teardown may run concurrently; ensures idempotent disable calls are safe and callers can await full teardown completion.
+    #disablingPromises = {
+        xr: null,
+        general: null,
+    };
+
     /**
      * Constructs a new BabylonJSController instance.
      * Initializes the canvas, asset containers, and options for the Babylon.js scene.
@@ -143,8 +209,10 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #bindHandlers() {
+        this.#handlers.onAnimationGroupChanged = this.#onAnimationGroupChanged.bind(this);
         this.#handlers.onKeyUp = this.#onKeyUp.bind(this);
         this.#handlers.onPointerObservable = this.#onPointerObservable.bind(this);
+        this.#handlers.onResize = this.#onResize.bind(this);
         this.#handlers.renderLoop = this.#renderLoop.bind(this);
     }
 
@@ -173,7 +241,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 +254,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 +293,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,21 +333,191 @@ 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();
+    }
+
+    /**
+     * Starts Babylon's engine render loop if it is not already running.
+     * @private
+     * @returns {boolean} True when the loop was started, false when no engine is available or it was already running.
+     */
+    #startEngineRenderLoop() {
+        if (!this.#engine || this.#state.render.isLoopRunning) {
+            return false;
+        }
+        this.#engine.runRenderLoop(this.#handlers.renderLoop);
+        this.#state.render.isLoopRunning = true;
+        return true;
+    }
+
+    /**
+     * Stops Babylon's engine render loop when it is currently active.
+     * @private
+     * @returns {boolean} True when the loop was stopped, false when no engine is available or it was already stopped.
+     */
+    #stopEngineRenderLoop() {
+        if (!this.#engine || !this.#state.render.isLoopRunning) {
+            return false;
+        }
+        this.#engine.stopRenderLoop(this.#handlers.renderLoop);
+        this.#state.render.isLoopRunning = false;
+        return true;
+    }
+    
+    /**
+     * Resets transient render-loop bookkeeping so the next render request starts from a clean baseline.
+     * Clears queued burst frames, ends any active continuous-render window, and drops the idle-throttle timestamp.
+     * @private
+     * @returns {void}
+     */
+    #resetRenderState() {
+        this.#state.render.dirtyFrames = 0;
+        this.#state.render.continuousUntil = 0;
+        this.#state.render.lastRenderAt = 0;
+    }
+
+    /**
+     * Marks the scene as dirty and optionally extends a short continuous-render window.
+     * Ensures the engine loop is running so the requested frames can be produced.
+     * @private
+     * @param {{frames?:number, continuousMs?:number}} [options={}] - Render request options.
+     * @param {number} [options.frames=1] - Minimum number of frames to render.
+     * @param {number} [options.continuousMs=0] - Milliseconds to keep continuous rendering active.
+     * @returns {boolean} True when the request was accepted, false when scene/engine are unavailable.
+     */
+    #requestRender({ frames = 1, continuousMs = 0 } = {}) {
+        if (!this.#scene || !this.#engine) {
+            return false;
+        }
+
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        this.#state.render.dirtyFrames = Math.max(this.#state.render.dirtyFrames, Math.max(1, frames));
+        if (continuousMs > 0) {
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + continuousMs);
+        }
+        this.#startEngineRenderLoop();
+        return true;
+    }
+
+    /**
+     * Checks whether an ArcRotateCamera still has non-zero inertial movement.
+     * @private
+     * @param {ArcRotateCamera} camera - Camera to evaluate.
+     * @returns {boolean} True when any inertial offset is still active.
+     */
+    #isArcRotateCameraInMotion(camera) {
+        const EPSILON = 0.00001;
+        return Math.abs(camera?.inertialAlphaOffset || 0) > EPSILON || Math.abs(camera?.inertialBetaOffset || 0) > EPSILON || Math.abs(camera?.inertialRadiusOffset || 0) > EPSILON || Math.abs(camera?.inertialPanningX || 0) > EPSILON || Math.abs(camera?.inertialPanningY || 0) > EPSILON;
+    }
+
+    /**
+     * Checks whether a FreeCamera/UniversalCamera is currently moving or rotating.
+     * @private
+     * @param {FreeCamera|UniversalCamera} camera - Camera to evaluate.
+     * @returns {boolean} True when translation or rotation deltas are active.
+     */
+    #isUniversalOrFreeCameraInMotion(camera) {
+        const EPSILON = 0.00001;
+        const direction = camera?.cameraDirection;
+        const rotation = camera?.cameraRotation;
+        const directionMoving = !!direction && (Math.abs(direction.x) > EPSILON || Math.abs(direction.y) > EPSILON || Math.abs(direction.z) > EPSILON);
+        const rotationMoving = !!rotation && (Math.abs(rotation.x) > EPSILON || Math.abs(rotation.y) > EPSILON || Math.abs(rotation.z) > EPSILON);
+        return directionMoving || rotationMoving;
+    }
+
+    /**
+     * Detects motion for the current active camera based on its concrete camera type.
+     * @private
+     * @returns {boolean} True when the active camera is moving, otherwise false.
+     */
+    #isCameraInMotion() {
+        const camera = this.#scene?.activeCamera;
+        if (!camera) {
+            return false;
+        }
+        if (camera instanceof ArcRotateCamera) {
+            return this.#isArcRotateCameraInMotion(camera);
+        }
+        if (camera instanceof UniversalCamera || camera instanceof FreeCamera) {
+            return this.#isUniversalOrFreeCameraInMotion(camera);
+        }
+        return false;
+    }
+
+    /**
+     * Determines whether scene animations are currently running.
+     * @private
+     * @returns {boolean} True when at least one animation group is playing.
+     */
+    #isAnimationRunning() {
+        if (!this.#scene) {
+            return false;
+        }
+        const hasAnimatables = (this.#scene.animatables?.length || 0) > 0;
+        if (!hasAnimatables) {
+            return false;
+        }
+        return this.#scene.animationGroups?.some((group) => group?.isPlaying) || false;
+    }
+
+    /**
+     * Evaluates whether the renderer should stay in continuous mode.
+     * XR always forces continuous rendering; animation/camera motion also extends the
+     * continuous deadline window to avoid abrupt stop-start behavior.
+     * @private
+     * @param {number} now - Current high-resolution timestamp.
+     * @returns {boolean} True when continuous rendering should remain active.
+     */
+    #shouldRenderContinuously(now) {
+        const inXR = this.#XRExperience?.baseExperience?.state === WebXRState.IN_XR;
+        if (inXR) {
+            return true;
+        }
+
+        const animationRunning = this.#isAnimationRunning();
+        const cameraInMotion = this.#isCameraInMotion();
+
+        if (animationRunning) {
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.animationMs);
         }
+        if (cameraInMotion) {
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.interactionMs);
+        }
+
+        return animationRunning || cameraInMotion || this.#state.render.continuousUntil > now;
     }
 
     /**
      * Render loop callback for Babylon.js.
+     * Runs only while scene state is dirty, interactive motion is active, animations are running, or XR is active.
+     * It self-stops when the scene becomes idle.
      * @private
      * @returns {void}
-     * @description
-     * Continuously renders the current scene if it exists.
-     * Used by the engine's runRenderLoop method to update the view.
      */
     #renderLoop() {
-        this.#scene && this.#scene.render();
+        if (!this.#scene) {
+            this.#stopEngineRenderLoop();
+            return;
+        }
+
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const continuous = this.#shouldRenderContinuously(now);
+        const needsRender = continuous || this.#state.render.dirtyFrames > 0;
+
+        if (!needsRender) {
+            this.#stopEngineRenderLoop();
+            return;
+        }
+
+        if (!continuous && this.#state.render.lastRenderAt > 0 && now - this.#state.render.lastRenderAt < this.#config.render.idleThrottleMs) {
+            return;
+        }
+        
+        this.#scene.render();
+        this.#state.render.lastRenderAt = now;
+
+        if (this.#state.render.dirtyFrames > 0) {
+            this.#state.render.dirtyFrames -= 1;
+        }
     }
 
     /**
@@ -382,49 +616,75 @@ 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.
+     * @description
+     * IBL path is considered available when either:
+     *  - `options.ibl.cachedUrl` is present (new pending URL), or
+     *  - `options.ibl.valid === true` (reusable in-memory `#hdrTexture` exists).
      */
-    #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?.valid === true || !!this.#options.ibl?.cachedUrl);
 
-        // 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;
+        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;
+            }
+
+            // 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) {
@@ -432,24 +692,24 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             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 +720,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;
@@ -472,46 +732,47 @@ export default class BabylonJSController {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
-        
+
         const pipelineName = "PrefViewerSSAORenderingPipeline";
 
         const ssaoRatio = {
             ssaoRatio: 0.5,
-            combineRatio: 1.0
+            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 +782,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) {
@@ -531,24 +792,24 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             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 +820,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;
@@ -572,56 +833,58 @@ export default class BabylonJSController {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             return false;
         }
-        
+
         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;
         }
@@ -629,16 +892,46 @@ export default class BabylonJSController {
 
     /**
      * Initializes the environment texture for the Babylon.js scene.
-     * 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.
+     * Resolves the active HDR environment texture using either a fresh `cachedUrl`
+     * or the reusable in-memory clone (`#hdrTexture`), then assigns it to `scene.environmentTexture`.
      * @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.
+     * @description
+     * Lifecycle implemented here:
+     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it.
+     * 2. Wait for readiness, clone it into `#hdrTexture` for reuse.
+     * 3. Call `options.ibl.consumeCachedUrl(true)` to revoke temporary object URLs and clear `cachedUrl`.
+     * 4. On following reloads, if `options.ibl.valid === true` and no `cachedUrl` is present, use `#hdrTexture.clone()`.
      */
-    #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;
+        }
+
+        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);
+        } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
+            hdrTexture = this.#hdrTexture.clone();
+        } else {
+            return false;
+        }
+
+        await WhenTextureReadyAsync(hdrTexture);
+
+        if (this.#options.ibl?.cachedUrl) {
+            if (this.#hdrTexture) {
+                this.#hdrTexture.dispose();
+            }
+            this.#hdrTexture = hdrTexture.clone();
+            this.#options.ibl?.consumeCachedUrl?.(true);
+        }
+
         hdrTexture.level = this.#options.ibl.intensity;
         this.#scene.environmentTexture = hdrTexture;
+        this.#scene.markAllMaterialsAsDirty(Material.TextureDirtyFlag);
         return true;
     }
 
@@ -646,9 +939,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) {
@@ -656,24 +949,28 @@ export default class BabylonJSController {
         }
 
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (supportedPipelines === undefined) {
             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 +982,57 @@ 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() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
 
-        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
+        if (!this.#scene || !this.#scene?.activeCamera || !this.#scene?.environmentTexture || !pipelineManager) {
+            return false;
+        }
+
+        if (!this.#scene.environmentTexture.isReady()) {
+            const self = this;
+            this.#scene.environmentTexture.onLoadObservable.addOnce(() => {
+                self.#initializeIBLShadows();
+            });
             return false;
         }
 
-        if (!this.#scene.environmentTexture) {
+        const meshesForCastingShadows = this.#scene.meshes.filter((mesh) => {
+            const isRootMesh = mesh.id.startsWith("__root__");
+            if (isRootMesh) {
+                return false;
+            }
+
+            const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
+            const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
+            const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
+
+            if (meshGenerateShadows) {
+                return true;
+            }
+            return false;
+        });
+        const materialsForReceivingShadows = this.#scene.materials.filter((material) => {
+            if (material instanceof PBRMaterial) {
+                material.enableSpecularAntiAliasing = false;
+            }
+            return true;
+        });
+
+        if (meshesForCastingShadows.length === 0 || materialsForReceivingShadows.length === 0) {
             return false;
         }
+
         const supportedPipelines = pipelineManager.supportedPipelines;
-        
+
         if (!supportedPipelines) {
             return false;
         }
-        
+
+        await this.#scene.whenReadyAsync();
+
         const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
         const pipelineOptions = {
@@ -714,13 +1044,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,41 +1064,20 @@ 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;
-            }
-
-            this.#scene.meshes.forEach((mesh) => {
-                const isRootMesh = mesh.id.startsWith("__root__");
-                if (isRootMesh) {
-                    return false;
-                }
-                
-                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();
-                }
-            });
+            Object.assign(iblShadowsPipeline, pipelineProps);
 
-            this.#scene.materials.forEach((material) => {
-                if (material instanceof PBRMaterial) {
-                    material.enableSpecularAntiAliasing = false;
-                }
-                this.#renderPipelines.iblShadows.addShadowReceivingMaterial(material);
-            });
+            meshesForCastingShadows.forEach((mesh) => iblShadowsPipeline.addShadowCastingMesh(mesh));
+            materialsForReceivingShadows.forEach((material) => iblShadowsPipeline.addShadowReceivingMaterial(material));
 
-            this.#renderPipelines.iblShadows.updateVoxelization();
+            iblShadowsPipeline.updateSceneBounds();
+            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 +1111,7 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #initializeDefaultLightShadows() {
+    async #initializeDefaultLightShadows() {
         if (!this.#dirLight) {
             return;
         }
@@ -825,7 +1134,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 +1183,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 +1199,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?.valid === true || !!this.#options.ibl?.cachedUrl);
+        const iblShadowsEnabled = iblEnabled && this.#options.ibl.shadows;
+
+        if (iblShadowsEnabled) {
+            await this.#initializeIBLShadows();
         } else {
-            this.#initializeDefaultLightShadows();
+            await this.#initializeDefaultLightShadows();
         }
-        this.#initializeEnvironmentShadows();
+        await this.#initializeEnvironmentShadows();
     }
 
     /**
@@ -933,20 +1236,52 @@ export default class BabylonJSController {
     }
 
     /**
-     * Handles pointer events observed on the Babylon.js scene.
+     * Resets pointer-picking sampling state.
      * @private
-     * @param {PointerInfo} info - The pointer event information from Babylon.js.
      * @returns {void}
      */
-    #onPointerObservable(info) {
-        const pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
-        if (info.type === PointerEventTypes.POINTERUP) {
-            this.#onPointerUp(info.event, pickInfo);
-        } else if (info.type === PointerEventTypes.POINTERMOVE) {
-            this.#onPointerMove(info.event, pickInfo);
-        } else if (info.type === PointerEventTypes.POINTERWHEEL) {
-            this.#onMouseWheel(info.event, pickInfo);
+    #resetPointerPickingState() {
+        this.#state.pointerPicking.lastMovePickAt = 0;
+        this.#state.pointerPicking.lastMovePickX = NaN;
+        this.#state.pointerPicking.lastMovePickY = NaN;
+        this.#state.pointerPicking.lastPickedMeshId = null;
+    }
+
+    /**
+     * Decides whether a POINTERMOVE event should trigger a scene raycast.
+     * Uses time + distance sampling to avoid expensive pick calls on every mouse move.
+     * @private
+     * @returns {boolean}
+     */
+    #shouldPickOnPointerMove() {
+        if (!this.#scene || !this.#babylonJSAnimationController) {
+            return false;
+        }
+
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const x = this.#scene.pointerX;
+        const y = this.#scene.pointerY;
+        const state = this.#state.pointerPicking;
+        const config = this.#config.pointerPicking;
+
+        if (!Number.isFinite(state.lastMovePickX) || !Number.isFinite(state.lastMovePickY)) {
+            state.lastMovePickX = x;
+            state.lastMovePickY = y;
+            state.lastMovePickAt = now;
+            return true;
+        }
+
+        const elapsed = now - state.lastMovePickAt >= config.movePickIntervalMs;
+        const moved = Math.abs(x - state.lastMovePickX) >= config.movePickMinDistancePx || Math.abs(y - state.lastMovePickY) >= config.movePickMinDistancePx;
+
+        if (!elapsed || !moved) {
+            return false;
         }
+
+        state.lastMovePickX = x;
+        state.lastMovePickY = y;
+        state.lastMovePickAt = now;
+        return true;
     }
 
     /**
@@ -961,6 +1296,10 @@ export default class BabylonJSController {
         if (this.#scene) {
             this.#scene.onPointerObservable.add(this.#handlers.onPointerObservable);
         }
+        if (this.#engine) {
+            this.#canvasResizeObserver = new ResizeObserver(this.#handlers.onResize);
+            this.#canvasResizeObserver.observe(this.#canvas);
+        }
     }
 
     /**
@@ -975,6 +1314,11 @@ export default class BabylonJSController {
         if (this.#scene !== null) {
             this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
         }
+        this.#cancelScheduledResize();
+        this.#canvasResizeObserver?.disconnect();
+        this.#canvasResizeObserver = null;
+        this.#detachAnimationChangedListener();
+        this.#resetPointerPickingState();
     }
 
     /**
@@ -990,31 +1334,56 @@ export default class BabylonJSController {
     }
 
     /**
-     * Disposes the Babylon.js WebXR experience if it exists.
+     * Disposes the shared GLTFResolver instance and closes its underlying storage handle.
      * @private
      * @returns {void}
      */
-    #disposeXRExperience() {
-        if (!this.#XRExperience) {
+    #disposeGLTFResolver() {
+        if (this.#gltfResolver) {
+            this.#gltfResolver.dispose();
+            this.#gltfResolver = null;
+        }
+    }
+
+    /**
+     * Disposes the Babylon.js WebXR experience if it exists.
+     * If XR is currently active, waits for `exitXRAsync()` before disposing to avoid
+     * tearing down the engine while the XR session is still shutting down.
+     * Concurrent calls share the same in-flight promise so disposal runs only once.
+     * @private
+     * @returns {Promise<void>}
+     */
+    async #disposeXRExperience() {
+        if (this.#disablingPromises.xr) {
+            return await this.#disablingPromises.xr;
+        }
+
+        const xrExperience = this.#XRExperience;
+        if (!xrExperience) {
             return;
         }
 
-        if (this.#XRExperience.baseExperience.state === WebXRState.IN_XR) {
-            this.#XRExperience.baseExperience
-                .exitXRAsync()
-                .then(() => {
-                    this.#XRExperience.dispose();
-                    this.#XRExperience = null;
-                })
-                .catch((error) => {
-                    console.warn("Error exiting XR experience:", error);
-                    this.#XRExperience.dispose();
+        this.#disablingPromises.xr = (async () => {
+            try {
+                if (xrExperience.baseExperience?.state === WebXRState.IN_XR) {
+                    await xrExperience.baseExperience.exitXRAsync();
+                }
+            } catch (error) {
+                console.warn("PrefViewer: Error exiting XR experience:", error);
+            } finally {
+                try {
+                    xrExperience.dispose();
+                } catch (error) {
+                    console.warn("PrefViewer: Error disposing XR experience:", error);
+                }
+                if (this.#XRExperience === xrExperience) {
                     this.#XRExperience = null;
-                });
-        } else {
-            this.#XRExperience.dispose();
-            this.#XRExperience = null;
-        }
+                }
+                this.#disablingPromises.xr = null;
+            }
+        })();
+
+        await this.#disablingPromises.xr;
     }
 
     /**
@@ -1026,11 +1395,88 @@ export default class BabylonJSController {
         if (!this.#engine) {
             return;
         }
+        if (this.#hdrTexture) {
+            this.#hdrTexture.dispose();
+            this.#hdrTexture = null;
+        }
         this.#engine.dispose();
         this.#engine = this.#scene = this.#camera = null;
         this.#hemiLight = this.#dirLight = this.#cameraLight = null;
     }
 
+    /**
+     * Handles animation state events emitted by `OpeningAnimation` instances.
+     * Routes opening/closing states to continuous rendering and all other states
+     * (paused/opened/closed) to a short final render burst.
+     * @private
+     * @param {CustomEvent} event - Event carrying animation state in `event.detail.state`.
+     * @returns {void}
+     */
+    #onAnimationGroupChanged(event) {
+        const state = event?.detail?.state;
+        if (state === undefined) {
+            return;
+        }
+
+        if (state === OpeningAnimation.states.opening || state === OpeningAnimation.states.closing) {
+            this.#onAnimationGroupPlay();
+        } else {
+            this.#onAnimationGroupStop();
+        }
+    }
+
+    /**
+     * Marks animation playback as active and requests short continuous rendering so animated transforms remain smooth while state is changing.
+     * @private
+     * @returns {void}
+     */
+    #onAnimationGroupPlay() {
+        this.#requestRender({ frames: 1, continuousMs: this.#config.render.animationMs });
+    }
+
+    /**
+     * Handles animation stop/pause/end transitions by requesting a final render burst.
+     * @private
+     * @returns {void}
+     */
+    #onAnimationGroupStop() {
+        if (this.#settings.iblEnabled && this.#renderPipelines.iblShadows) {
+            this.#renderPipelines.iblShadows.updateVoxelization();
+            this.#scene?.postProcessRenderPipelineManager?.update();
+        }
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
+        this.#requestRender({ frames: frames });
+    }
+
+    /**
+     * Attaches the `prefviewer-animation-changed` listener to the nearest `pref-viewer-3d` host.
+     * Removes any previous registration first to avoid duplicate callbacks across reload cycles.
+     * @private
+     * @returns {boolean} True when the listener is attached, false when no host is available.
+     */
+    #attachAnimationChangedListener() {
+        this.#getPrefViewer3DComponent();
+        if (!this.#prefViewer3D) {
+            return false;
+        }
+        this.#detachAnimationChangedListener();
+        this.#prefViewer3D.addEventListener("prefviewer-animation-changed", this.#handlers.onAnimationGroupChanged);
+        return true;
+    }
+
+    /**
+     * Detaches the `prefviewer-animation-changed` listener from the cached `pref-viewer-3d` host.
+     * @private
+     * @returns {boolean} True when a host exists and the listener removal was attempted, false otherwise.
+     */
+    #detachAnimationChangedListener() {
+        if (!this.#prefViewer3D) {
+            return false;
+        }
+        this.#prefViewer3D.removeEventListener("prefviewer-animation-changed", this.#handlers.onAnimationGroupChanged);
+        return true;
+    }
+
     /**
      * Handles keyup events on the Babylon.js canvas for triggering model and scene downloads.
      * @private
@@ -1038,10 +1484,10 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onKeyUp(event) {
-        // CTRL + ALT + letter
-        if (event.ctrlKey && event.altKey && event.key !== undefined) {
-            switch (event.key.toLowerCase()) {
-                case "d":
+        // CTRL + ALT + letter (uses event.code for physical key, layout-independent — fixes Mac Option+D producing "∂" instead of "d")
+        if (event.ctrlKey && event.altKey && event.code !== undefined) {
+            switch (event.code) {
+                case "KeyD":
                     this.#openDownloadDialog();
                     break;
                 default:
@@ -1058,11 +1504,12 @@ export default class BabylonJSController {
      * @returns {void|false} Returns false if there is no active camera; otherwise, void.
      */
     #onMouseWheel(event, pickInfo) {
+        event.preventDefault();
         const camera = this.#scene?.activeCamera;
         if (!camera) {
             return false;
         }
-        if (!camera.metadata?.locked) {            
+        if (!camera.metadata?.locked) {
             if (camera instanceof ArcRotateCamera) {
                 camera.wheelPrecision = camera.wheelPrecision || 3.0;
                 camera.inertialRadiusOffset -= event.deltaY * camera.wheelPrecision * 0.001;
@@ -1075,8 +1522,8 @@ export default class BabylonJSController {
                 const movementVector = direction.scale(zoomSpeed);
                 camera.position = camera.position.add(movementVector);
             }
+            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
         }
-        event.preventDefault();
     }
 
     /**
@@ -1088,7 +1535,9 @@ export default class BabylonJSController {
      */
     #onPointerUp(event, pickInfo) {
         if (this.#babylonJSAnimationController) {
-            this.#babylonJSAnimationController.hideMenu();
+            if (event.button !== 2 || !pickInfo || !pickInfo.pickedMesh) {
+                this.#babylonJSAnimationController.hideMenu();
+            }
             // Right click for showing animation menu
             if (event.button === 2) {
                 this.#babylonJSAnimationController.showMenu(pickInfo);
@@ -1100,13 +1549,105 @@ export default class BabylonJSController {
      * Handles pointer move events on the Babylon.js scene.
      * @private
      * @param {PointerEvent} event - The pointer move event.
-     * @param {PickInfo} pickInfo - The result of the scene pick operation.
+     * @param {PickInfo|null} pickInfo - The sampled result of the scene pick operation (may be null when sampling skips a raycast).
      * @returns {void}
      */
     #onPointerMove(event, pickInfo) {
-        if (this.#babylonJSAnimationController) {
-            this.#babylonJSAnimationController.highlightMeshes(pickInfo);
+        const camera = this.#scene?.activeCamera;
+        if (camera && !camera.metadata?.locked) {
+            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
+        }
+        if (this.#babylonJSAnimationController && pickInfo) {
+            const pickedMeshId = pickInfo?.pickedMesh?.id || null;
+            if (this.#state.pointerPicking.lastPickedMeshId !== pickedMeshId) {
+                const highlightResult = this.#babylonJSAnimationController.highlightMeshes(pickInfo);
+                if (highlightResult.changed) {
+                    this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
+                }
+            }
+        }
+    }
+
+    /**
+     * Handles pointer events observed on the Babylon.js scene.
+     * Uses pointer-move sampling to avoid running expensive `scene.pick()` on every event.
+     * @private
+     * @param {PointerInfo} info - The pointer event information from Babylon.js.
+     * @returns {void}
+     */
+    #onPointerObservable(info) {
+        if (info.type === PointerEventTypes.POINTERMOVE) {
+            let pickInfo = null;
+            let lastPickedMeshId = null;
+            if (this.#shouldPickOnPointerMove()) {
+                pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
+                lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
+            }
+            this.#onPointerMove(info.event, pickInfo);
+            this.#state.pointerPicking.lastPickedMeshId = lastPickedMeshId;
+        } else if (info.type === PointerEventTypes.POINTERUP) {
+            const pickInfo = info.event?.button === 2 ? this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY) : null;
+            if (pickInfo) {
+                this.#state.pointerPicking.lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
+            }
+            this.#onPointerUp(info.event, pickInfo);
+        } else if (info.type === PointerEventTypes.POINTERWHEEL) {
+            this.#onMouseWheel(info.event, null);
+        }
+    }
+
+    /**
+     * Handles canvas resize notifications.
+     * Resizes the Babylon engine and requests a short on-demand render burst so camera-dependent
+     * buffers and post-process pipelines are redrawn at the new viewport size.
+     * @private
+     * @returns {void}
+     */
+    #onResize() {
+        if (!this.#engine) {
+            return;
+        }
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const elapsed = now - this.#state.resize.lastAppliedAt;
+        const applyResize = () => {
+            this.#state.resize.timeoutId = null;
+            this.#state.resize.isScheduled = false;
+            if (!this.#engine) {
+                return;
+            }
+            this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+            console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
+            this.#engine.resize();
+            this.#requestRender({ frames: this.#config.render.burstFramesBase, continuousMs: this.#config.render.interactionMs });
+        };
+
+        if (elapsed >= this.#config.resize.throttleMs) {
+            applyResize();
+            return;
+        }
+
+        if (this.#state.resize.isScheduled) {
+            return;
+        }
+
+        this.#state.resize.isScheduled = true;
+        const waitMs = Math.max(0, this.#config.resize.throttleMs - elapsed);
+        this.#state.resize.timeoutId = setTimeout(() => {
+            applyResize();
+        }, waitMs);
+    }
+
+    /**
+     * Clears any queued throttled resize callback.
+     * @private
+     * @returns {void}
+     */
+    #cancelScheduledResize() {
+        if (this.#state.resize.timeoutId !== null) {
+            clearTimeout(this.#state.resize.timeoutId);
         }
+        this.#state.resize.timeoutId = null;
+        this.#state.resize.isScheduled = false;
     }
 
     /**
@@ -1148,7 +1689,7 @@ export default class BabylonJSController {
                 .forEach((mesh) => {
                     mesh.material = material;
                     someSetted = true;
-                })
+                }),
         );
 
         if (someSetted) {
@@ -1243,15 +1784,12 @@ export default class BabylonJSController {
      * Marks the IBL state as successful, recreates lights so the new environment takes effect, and reports whether anything changed.
      * @private
      * @returns {boolean} True when lights were refreshed due to pending IBL changes, otherwise false.
+     * @description
+     * Delegates to `#createLights()`, which executes the full IBL URL-to-texture lifecycle:
+     * `cachedUrl -> HDRCubeTexture -> #hdrTexture clone -> consumeCachedUrl(true)`.
      */
-    #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();
     }
 
     /**
@@ -1265,34 +1803,47 @@ export default class BabylonJSController {
     }
 
     /**
-     * Caches and retrieves the parent custom element "PREF-VIEWER-3D" for efficient access.
+     * Resolves and caches the closest `pref-viewer-3d` host associated with the rendering canvas.
      * @private
      * @returns {void}
      */
     #getPrefViewer3DComponent() {
-        if (this.#prefViewer3D === undefined) {
-            const grandParentElement = this.#canvas.parentElement.parentElement;
-            this.#prefViewer3D = grandParentElement && grandParentElement.nodeName === "PREF-VIEWER-3D" ? grandParentElement : null;
+        if (this.#prefViewer3D !== undefined) {
+            return;
         }
+
+        let prefViewer3D = this.#canvas?.closest?.("pref-viewer-3d") || undefined;
+        if (!prefViewer3D) {
+            const host = this.#canvas?.getRootNode?.()?.host;
+            prefViewer3D = host?.nodeName === "PREF-VIEWER-3D" ? host : undefined;
+        }
+
+        this.#prefViewer3D = prefViewer3D;
     }
 
     /**
-     * Caches and retrieves the parent custom element "PREF-VIEWER" for efficient access.
+     * Resolves and caches the closest `pref-viewer` host associated with `#prefViewer3D`.
      * @private
      * @returns {void}
      */
     #getPrefViewerComponent() {
-        if (this.#prefViewer === undefined) {
-            if (this.#prefViewer3D === undefined) {
-                this.#getPrefViewer3DComponent();
-            }
-            if (!this.#prefViewer3D) {
-                this.#prefViewer = null;
-                return;
-            }
-            const rootNode = this.#prefViewer3D ? this.#prefViewer3D.getRootNode().host : null;
-            this.#prefViewer = rootNode && rootNode.nodeName === "PREF-VIEWER" ? rootNode : null;
+        if (this.#prefViewer !== undefined) {
+            return;
         }
+
+        this.#getPrefViewer3DComponent();
+        if (this.#prefViewer3D === undefined) {
+            this.#prefViewer = undefined;
+            return;
+        }
+
+        let prefViewer = this.#prefViewer3D.closest?.("pref-viewer") || undefined;
+        if (!prefViewer) {
+            const host = this.#prefViewer3D.getRootNode?.()?.host;
+            prefViewer = host?.nodeName === "PREF-VIEWER" ? host : undefined;
+        }
+
+        this.#prefViewer = prefViewer;
     }
 
     /**
@@ -1373,6 +1924,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,10 +1991,12 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #stopRender() {
-        this.#engine.stopRenderLoop(this.#handlers.renderLoop);
-        this.#unloadCameraDependentEffects();
+    async #stopRender() {
+        this.#stopEngineRenderLoop();
+        this.#resetRenderState();
+        await this.#unloadCameraDependentEffects();
     }
+
     /**
      * Starts the Babylon.js render loop for the current scene.
      * Waits until the scene is ready before beginning continuous rendering.
@@ -1405,21 +2004,29 @@ export default class BabylonJSController {
      * @returns {Promise<void>}
      */
     async #startRender() {
-        this.#loadCameraDependentEffects();
+        await this.#loadCameraDependentEffects();
         await this.#scene.whenReadyAsync();
-        this.#engine.runRenderLoop(this.#handlers.renderLoop);
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
+        this.#requestRender({ frames: frames, continuousMs: this.#config.render.interactionMs });
     }
 
     /**
-     * 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 +2038,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];
         }
@@ -1462,6 +2072,8 @@ export default class BabylonJSController {
             return [container, assetContainer];
         } catch (error) {
             return [container, assetContainer];
+        } finally {
+            this.#gltfResolver.revokeObjectURLs(sourceData.objectURLs);
         }
     }
 
@@ -1474,15 +2086,16 @@ export default class BabylonJSController {
      * Applies material and camera options, sets wall/floor visibility, and initializes lights and shadows.
      * Returns an object with success status and error details.
      */
-    async #loadContainers() {
-        this.#stopRender();
+    async #loadContainers(force = false) {
+        this.#detachAnimationChangedListener();
+        await this.#stopRender();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
 
         const promiseArray = [];
         Object.values(this.#containers).forEach((container) => {
-            promiseArray.push(this.#loadAssetContainer(container));
+            promiseArray.push(this.#loadAssetContainer(container, force));
         });
 
         let detail = {
@@ -1491,22 +2104,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 +2130,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 +2144,10 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
-                this.#startRender();
+                if (this.#babylonJSAnimationController?.hasAnimations?.()) {
+                    this.#attachAnimationChangedListener();
+                }
+                await this.#startRender();
             });
         return detail;
     }
@@ -1545,10 +2158,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 +2170,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();
     }
 
     /**
@@ -1793,10 +2406,10 @@ export default class BabylonJSController {
         this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false });
         this.#engine.disableUniformBuffers = true;
         this.#scene = new Scene(this.#engine);
-        
+
         // Activate the rendering of geometry data into a G-buffer, essential for advanced effects like deferred shading,
-        // SSAO, and Velocity-Texture-Animation (VAT), allowing for complex post-processing by separating rendering into 
-        // different buffers (depth, normals, velocity) for later use in shaders. 
+        // SSAO, and Velocity-Texture-Animation (VAT), allowing for complex post-processing by separating rendering into
+        // different buffers (depth, normals, velocity) for later use in shaders.
         const geometryBufferRenderer = this.#scene.enableGeometryBufferRenderer();
         if (geometryBufferRenderer) {
             geometryBufferRenderer.enableScreenspaceDepth = true;
@@ -1804,28 +2417,62 @@ 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;
+
+        // Skip the built-in pointer picking logic since the controller implements its own optimized raycasting for interaction.
+        this.#scene.skipPointerMovePicking = true;
+        this.#scene.skipPointerDownPicking = true;
+        this.#scene.skipPointerUpPicking = true;
+
         this.#createCamera();
         this.#enableInteraction();
         await this.#createXRExperience();
-        this.#startRender();
-        this.#canvasResizeObserver = new ResizeObserver(() => this.#engine && this.#engine.resize());
-        this.#canvasResizeObserver.observe(this.#canvas);
     }
 
     /**
      * Disposes the Babylon.js engine and disconnects the canvas resize observer.
-     * Cleans up all scene, camera, light, and XR resources.
+     * Cleans up all scene, camera, light, XR, and GLTF resolver resources.
+     * The teardown is asynchronous: it waits for XR/session-dependent shutdown work
+     * before disposing the engine, and coalesces concurrent calls into one in-flight promise.
      * @public
-     * @returns {void}
+     * @returns {Promise<void>}
      */
-    disable() {
-        this.#canvasResizeObserver.disconnect();
-        this.#disableInteraction();
-        this.#disposeAnimationController();
-        this.#disposeXRExperience();
-        this.#unloadCameraDependentEffects();
-        this.#disposeEngine();
+    async disable() {
+        if (this.#disablingPromises.general) {
+            return await this.#disablingPromises.general;
+        }
+
+        this.#disablingPromises.general = (async () => {
+            this.#disableInteraction();
+            this.#disposeAnimationController();
+            this.#disposeGLTFResolver();
+            try {
+                await this.#disposeXRExperience();
+            } catch (error) {
+                console.warn("PrefViewer: Error while disposing XR experience:", error);
+            }
+            try {
+                await this.#unloadCameraDependentEffects();
+            } catch (error) {
+                console.warn("PrefViewer: Error while unloading camera-dependent effects:", error);
+            } finally {
+                this.#stopEngineRenderLoop();
+                this.#disposeEngine();
+            }
+        })();
+
+        try {
+            await this.#disablingPromises.general;
+        } finally {
+            this.#disablingPromises.general = null;
+        }
     }
 
     /**
@@ -1946,28 +2593,8 @@ export default class BabylonJSController {
      * @public
      * @returns {Promise<boolean>} Resolves to true if loading succeeds, false otherwise.
      */
-    async load() {
-        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() };
+    async load(force = false) {
+        return await this.#loadContainers(force);
     }
 
     /**
@@ -2000,13 +2627,15 @@ 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();
-        const IBLOptionsSetted = this.#setOptions_IBL();
-        this.#startRender();
-        return IBLOptionsSetted;
+    async setIBLOptions() {
+        await this.#stopRender();
+        try {
+            return await this.#setOptions_IBL();
+        } finally {
+            await this.#startRender();
+        }
     }
 
     /**
@@ -2033,6 +2662,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.