@preference-sl/pref-viewer 2.12.0 → 2.13.0-beta.1

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, Camera, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, LoadAssetContainerAsync, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Tools, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState } from "@babylonjs/core";
+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 { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -8,99 +8,71 @@ 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 { translate } from "./localization/i18n.js";
 
 /**
- * BabylonJSController - Main controller for managing Babylon.js 3D scenes, assets, rendering, and user interactions in PrefViewer.
+ * 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.
  *
- * Summary:
- *  Provides a high-level API for initializing, loading, displaying, and exporting 3D models and environments using Babylon.js.
- *  Manages advanced rendering features, AR integration, asset containers, and user interaction logic.
+ * 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.
+ *  - 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.
  *
- * Key Responsibilities:
- *  - Initializes and manages the Babylon.js engine, scene, camera, lights, and asset containers.
- *  - Handles loading, replacing, and disposing of 3D models, environments, and materials.
- *  - Configures advanced rendering features such as Draco mesh compression, shadows, and image-based lighting (IBL).
- *  - Integrates Babylon.js WebXR experience for augmented reality (AR) support.
- *  - Provides methods for downloading models and scenes in GLB, glTF (ZIP), and USDZ formats.
- *  - Manages camera and material options, container visibility, and user interactions.
- *  - Observes canvas resize events and updates the engine accordingly.
- *  - Applies metadata-driven scene adjustments (e.g., inner floor translation) after asset reloads.
- *  - Designed for integration with PrefViewer and GLTFResolver.
- *  - All resource management and rendering operations are performed asynchronously for performance.
+ * 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.
  *
- * Usage:
- *  - Instantiate: const controller = new BabylonJSController(canvas, containers, options);
- *  - Enable rendering: await controller.enable();
- *  - Load assets: await controller.load();
- *  - Set camera/material options: controller.setCameraOptions(), controller.setMaterialOptions();
- *  - Control visibility: controller.setContainerVisibility(name, show);
- *  - Download assets: controller.downloadGLB(), controller.downloadGLTF(), controller.downloadUSDZ();
- *  - Disable rendering: controller.disable();
+ * Public API Highlights
+ *  - constructor(canvas, containers, options)
+ *  - enable() / disable()
+ *  - load()
+ *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
+ *  - getRenderSettings() / applyRenderSettings(partial)
+ *  - setRenderSettings(settings) [via PrefViewer menu integration]
  *
- * Public Methods:
- *  - constructor(canvas, containers, options): Creates the controller, wires container state, and stores runtime options.
- *  - enable(): Boots the Babylon.js engine, scene, camera, baseline lights, XR support, and the render loop.
- *  - disable(): Stops rendering and disposes the engine, lights, XR experience, and observers.
- *  - load(): Reloads every pending asset container, re-applies options, and resolves with the loading summary { success, error }.
- *  - setCameraOptions(): Applies the pending camera selection, reinstalls dependent pipelines, and restarts rendering safely.
- *  - setMaterialOptions(): Re-applies all configured material overrides across visible containers and restarts rendering.
- *  - setIBLOptions(): Pushes pending HDR/IBL updates, refreshes dependent effects, and resumes the render loop.
- *  - setContainerVisibility(name, show): Toggles model/environment containers, syncing wall/floor helpers and component attributes.
- *  - downloadGLB(content): Exports the selected scope (scene/model/environment) into a time-stamped GLB and triggers the download.
- *  - downloadGLTF(content): Generates a glTF + BIN + textures ZIP for the requested scope, adding metadata comments for traceability.
- *  - downloadUSDZ(content): Builds an Apple USDZ archive for the requested scope and downloads it via blob streaming.
+ * 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.
  *
- * Private Methods (using ECMAScript private fields):
- *  - #bindHandlers(): Pre-binds reusable event handlers to preserve stable references.
- *  - #configureDracoCompression(): Sets up Draco mesh compression.
- *  - #renderLoop(): Babylon.js render loop callback.
- *  - #addStylesToARButton(): Styles AR button.
- *  - #createXRExperience(): Initializes WebXR AR experience.
- *  - #createCamera(): Creates and configures the main camera.
- *  - #createLights(): Creates and configures scene lights and shadows.
- *  - #initializeAmbientOcclussion(): Rebuilds the SSAO pipeline for the active camera.
- *  - #initializeVisualImprovements(): Reinstalls the default rendering pipeline (MSAA/FXAA/grain).
- *  - #initializeEnvironmentTexture(): Loads and sets the HDR environment texture.
- *  - #initializeIBLShadows(): Sets up IBL shadow pipeline and assigns meshes/materials.
- *  - #initializeShadows(): Sets up standard or IBL shadows for meshes.
- *  - #initializeDefaultLightShadows(): Configures soft shadows when no HDR environment exists.
- *  - #initializeEnvironmentShadows(): Rebuilds environment-provided shadow generators.
- *  - #setMaxSimultaneousLights(): Updates max simultaneous lights for all materials.
- *  - #onPointerObservable(info): Handles pointer events and dispatches to pointer/mouse handlers.
- *  - #onPointerUp(event, pickInfo): Handles pointer up events (e.g., right-click for animation menu).
- *  - #onPointerMove(event, pickInfo): Handles pointer move events (e.g., mesh highlighting).
- *  - #onMouseWheel(event, pickInfo): Handles mouse wheel events for camera zoom.
- *  - #onKeyUp(event): Handles keyup events for download dialog and shortcuts.
- *  - #enableInteraction(): Adds canvas and scene interaction event listeners.
- *  - #disableInteraction(): Removes canvas and scene interaction event listeners.
- *  - #disposeAnimationController(): Disposes the animation controller if it exists.
- *  - #disposeXRExperience(): Disposes the Babylon.js WebXR experience if it exists.
- *  - #disposeEngine(): Disposes engine and releases all resources.
- *  - #setOptionsMaterial(optionMaterial): Applies a material option to relevant meshes.
- *  - #setOptions_Materials(): Applies all material options from configuration.
- *  - #setOptions_Camera(): Applies camera options from configuration.
- *  - #setOptions_IBL(): Applies pending HDR/IBL option updates and refreshes lights.
- *  - #findContainerByName(name): Finds a container by its name.
- *  - #addContainer(container, updateVisibility): Adds a container to the scene and updates visibility.
- *  - #removeContainer(container, updateVisibility): Removes a container from the scene and updates visibility.
- *  - #replaceContainer(container, newAssetContainer): Replaces a container in the scene.
- *  - #getPrefViewer3DComponent(): Caches and retrieves the parent PREF-VIEWER-3D element.
- *  - #getPrefViewerComponent(): Caches and retrieves the parent PREF-VIEWER element.
- *  - #updateVisibilityAttributeInComponents(name, isVisible): Updates parent visibility attributes.
- *  - #setVisibilityOfWallAndFloorInModel(show): Controls wall/floor mesh visibility.
- *  - #stopRender(): Stops the Babylon.js render loop.
- *  - #startRender(): Starts the Babylon.js render loop.
- *  - #loadAssetContainer(container): Loads an asset container asynchronously.
- *  - #loadContainers(): Loads all asset containers and adds them to the scene.
- *  - #loadCameraDepentEffects(): Re-initializes camera-bound post-processes after reloads or option changes.
- *  - #checkModelMetadata(oldMetadata, newMetadata): Processes metadata changes after loading.
- *  - #checkInnerFloorTranslation(oldMetadata, newMetadata): Applies inner floor Y translations from metadata.
- *  - #translateNodeY(name, deltaY): Adjusts the Y position of a scene node.
- *  - #addDateToName(name): Appends the current date/time to a name string.
- *  - #downloadZip(files, name, comment, addDateInName): Generates and downloads a ZIP file.
- *  - #openDownloadDialog(): Opens the modal download dialog.
+ * 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.
  */
 export default class BabylonJSController {
+
+    #RENDER_SETTINGS_STORAGE_KEY = "pref-viewer/render-settings";
+
+    // Default render settings
+    // Add here new render toggles that require persistence here, and remember to update the matching labels
+    // under translations.prefViewer.menu3d.switches in ./localization/translations.js.
+    static DEFAULT_RENDER_SETTINGS = {
+        antiAliasingEnabled: true,
+        ambientOcclusionEnabled: true,
+        iblEnabled: true,
+        shadowsEnabled: false,
+    };
+    
     // Canvas HTML element
     #canvas = null;
 
@@ -131,12 +103,7 @@ export default class BabylonJSController {
         renderLoop: null,
     };
     
-    #settings = {
-        antiAliasingEnabled: true,
-        ambientOcclusionEnabled: true,
-        iblEnabled: true,
-        shadowsEnabled: false,
-    };
+    #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
 
     /**
      * Constructs a new BabylonJSController instance.
@@ -160,6 +127,7 @@ export default class BabylonJSController {
             };
         });
         this.#options = options;
+        this.#loadStoredRenderSettings();
         this.#bindHandlers();
     }
 
@@ -192,6 +160,114 @@ export default class BabylonJSController {
         };
     }
 
+    /**
+     * Merges boolean render toggles into the current configuration, clearing the environment texture when IBL turns off
+     * and persisting the updated state when at least one flag changed.
+     * @private
+     * @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 = {}) {
+        if (!settings) {
+            return false;
+        }
+
+        let changed = false;
+        Object.keys(settings).forEach((key) => {
+            if (typeof settings[key] === "boolean" && this.#settings[key] !== settings[key]) {
+                this.#settings[key] = settings[key];
+                changed = true;
+            }
+        });
+
+        if (changed && settings.iblEnabled === false && this.#scene) {
+            this.#scene.environmentTexture = null;
+        }
+
+        if (changed) {
+            this.#saveRenderSettings();
+        }
+
+        return changed;
+    }
+
+    /**
+     * Restores previously persisted render toggles from localStorage, falling back to defaults when parsing fails or
+     * the browser environment is unavailable.
+     * @private
+     * @returns {void}
+     */
+    #loadStoredRenderSettings() {
+        if (typeof window === "undefined" || !window?.localStorage) {
+            return;
+        }
+        try {
+            const serialized = window.localStorage.getItem(this.#RENDER_SETTINGS_STORAGE_KEY);
+            if (!serialized) {
+                return;
+            }
+            const parsed = JSON.parse(serialized);
+            Object.keys(BabylonJSController.DEFAULT_RENDER_SETTINGS).forEach((key) => {
+                if (typeof parsed?.[key] === "boolean") {
+                    this.#settings[key] = parsed[key];
+                }
+            });
+        } catch (error) {
+            console.warn("PrefViewer: unable to load render settings", error);
+        }
+    }
+
+    /**
+     * Serializes the current render toggle object to localStorage, ignoring non-browser contexts and logging warnings
+     * if persistence fails.
+     * @private
+     * @returns {void}
+     */
+    #saveRenderSettings() {
+        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);
+        }
+    }
+
+    /**
+     * Walks every container state and marks it as pending using `setPendingWithCurrentStorage` so asset sources are
+     * re-requested on the next load cycle.
+     * @private
+     * @returns {boolean} True when at least one container flipped to pending.
+     */
+    #markContainersForReload() {
+        let marked = false;
+        Object.values(this.#containers).forEach((container) => {
+            if (container?.state?.setPendingWithCurrentStorage && container.state.setPendingWithCurrentStorage()) {
+                marked = true;
+            }
+        });
+        return marked;
+    }
+
+    /**
+     * Re-schedules option-driven resources (camera, materials, IBL) for application by calling their respective
+     * `setPendingWithCurrent`/`setPending` helpers when available.
+     * @private
+     * @returns {void}
+     */
+    #markOptionsForReload() {
+        if (this.#options?.camera?.setPendingWithCurrent) {
+            this.#options.camera.setPendingWithCurrent();
+        }
+        if (this.#options?.materials) {
+            Object.values(this.#options.materials).forEach((material) => material?.setPendingWithCurrent?.());
+        }
+        if (this.#options?.ibl?.setPending) {
+            this.#options.ibl.setPending();
+        }
+    }
+
     /**
      * Render loop callback for Babylon.js.
      * @private
@@ -284,7 +360,7 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #createCamera() {
-        this.#camera = new ArcRotateCamera("camera", (3 * Math.PI) / 2, Math.PI * 0.47, 10, Vector3.Zero(), this.#scene);
+        this.#camera = new ArcRotateCamera("defaultCamera", (3 * Math.PI) / 2, Math.PI * 0.47, 10, Vector3.Zero(), this.#scene);
         this.#camera.upperBetaLimit = Math.PI * 0.48;
         this.#camera.lowerBetaLimit = Math.PI * 0.25;
         this.#camera.lowerRadiusLimit = 5;
@@ -564,13 +640,18 @@ export default class BabylonJSController {
 
             this.#scene.meshes.forEach((mesh) => {
                 const isRootMesh = mesh.id.startsWith("__root__");
-                const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
-                if (isRootMesh || isHDRIMesh) {
+                if (isRootMesh) {
                     return false;
                 }
-                iblShadowsRenderPipeline.addShadowCastingMesh(mesh);
-                iblShadowsRenderPipeline.updateSceneBounds();
-                mesh.receiveShadows = true; // Not necessary for IBL shadows, but yes for standard shadows
+                
+                const isHDRIMesh = mesh.name?.toLowerCase() === "hdri";
+                const extrasCastShadows = mesh.metadata?.gltf?.extras?.castShadows;
+                const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
+
+                if (meshGenerateShadows) {
+                    iblShadowsRenderPipeline.addShadowCastingMesh(mesh);
+                    iblShadowsRenderPipeline.updateSceneBounds();
+                }
             });
 
             this.#scene.materials.forEach((material) => {
@@ -590,6 +671,29 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Adds the mesh to the provided shadow generator when it is eligible to cast shadows.
+     * Skips hidden Babylon root nodes, ignores HDRI domes, and honors the `castShadows` GLTF extra flag.
+     * @private
+     * @param {ShadowGenerator} shadowGenerator - Target generator that should receive the mesh.
+     * @param {AbstractMesh} mesh - Mesh to evaluate for shadow casting.
+     * @returns {boolean} True when the mesh is registered as a caster, otherwise false.
+     */
+    #addMeshToShadowGenerator(shadowGenerator, 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) {
+            shadowGenerator.addShadowCaster(mesh, true);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Configures soft shadows for the built-in directional light used when no HDR environment is present.
      * @private
@@ -608,15 +712,7 @@ export default class BabylonJSController {
         shadowGenerator.bias = 0.0005;
         shadowGenerator.normalBias = 0.02;
         shadowGenerator.getShadowMap().refreshRate = RenderTargetTexture.REFRESHRATE_RENDER_ONCE;
-        this.#scene.meshes.forEach((mesh) => {
-            if (mesh.id.startsWith("__root__")) {
-                return false;
-            }
-            if (mesh.name?.toLowerCase() !== "hdri") {
-                shadowGenerator.addShadowCaster(mesh, true);
-            }
-            mesh.receiveShadows = true;
-        });
+        this.#scene.meshes.forEach((mesh) => this.#addMeshToShadowGenerator(shadowGenerator, mesh));
         this.#shadowGen.push(shadowGenerator);
     }
 
@@ -648,18 +744,28 @@ export default class BabylonJSController {
             shadowGenerator.bias = 0.0005;
             shadowGenerator.normalBias = 0.02;
             shadowGenerator.getShadowMap().refreshRate = RenderTargetTexture.REFRESHRATE_RENDER_ONCE;
-            this.#scene.meshes.forEach((mesh) => {
-                if (mesh.id.startsWith("__root__")) {
-                    return false;
-                }
-                if (mesh.name?.toLowerCase() !== "hdri") {
-                    shadowGenerator.addShadowCaster(mesh, true);
-                }
-            });
+            this.#scene.meshes.forEach((mesh) => this.#addMeshToShadowGenerator(shadowGenerator, mesh));
             this.#shadowGen.push(shadowGenerator);
         });
     }
 
+    /**
+     * Marks every non-root mesh as shadow receiving, unless GLTF metadata explicitly disables it.
+     * Ensures standard shadow generators work even when extras are missing, while still honoring `receiveShadows` overrides.
+     * @private
+     * @returns {void}
+     */
+    #ensureMeshesReceiveShadows() {
+        this.#scene.meshes.forEach((mesh) => {
+            const isRootMesh = mesh.id.startsWith("__root__");
+            if (isRootMesh) {
+                return false;
+            }
+            const extrasReceiveShadows = mesh.metadata?.gltf?.extras?.receiveShadows;
+            mesh.receiveShadows = typeof extrasReceiveShadows === "boolean" ? extrasReceiveShadows : true; // Not necessary for IBL shadows, but yes for standard shadows
+        });
+    }
+
     /**
      * Initializes shadows for the Babylon.js scene.
      * @private
@@ -672,6 +778,9 @@ export default class BabylonJSController {
         if (!this.#settings.shadowsEnabled) {
             return false;
         }
+
+        this.#ensureMeshesReceiveShadows();
+
         if (this.#scene.environmentTexture) {
             if (this.#options.ibl.shadows) {
                 if (this.#scene.environmentTexture.isReady()) {
@@ -834,12 +943,23 @@ export default class BabylonJSController {
      * @returns {void|false} Returns false if there is no active camera; otherwise, void.
      */
     #onMouseWheel(event, pickInfo) {
-        if (!this.#scene?.activeCamera) {
+        const camera = this.#scene?.activeCamera;
+        if (!camera) {
             return false;
         }
-        //this.#scene.activeCamera.target = pickInfo.hit ? pickInfo.pickedPoint.clone() : this.#scene.activeCamera.target;
-        if (!this.#scene.activeCamera.metadata?.locked) {
-            this.#scene.activeCamera.inertialRadiusOffset -= event.deltaY * this.#scene.activeCamera.wheelPrecision * 0.001;
+        if (!camera.metadata?.locked) {            
+            if (camera instanceof ArcRotateCamera) {
+                camera.wheelPrecision = camera.wheelPrecision || 3.0;
+                camera.inertialRadiusOffset -= event.deltaY * camera.wheelPrecision * 0.001;
+            } else if (camera instanceof FreeCamera || camera instanceof UniversalCamera) {
+                camera.wheelPrecision = camera.wheelPrecision || 3.0;
+                const zoomSpeed = -event.deltaY * camera.wheelPrecision * 0.001;
+
+                const target = camera.target || Vector3.Zero();
+                const direction = target.subtract(camera.position).normalize();
+                const movementVector = direction.scale(zoomSpeed);
+                camera.position = camera.position.add(movementVector);
+            }
         }
         event.preventDefault();
     }
@@ -995,7 +1115,8 @@ export default class BabylonJSController {
             }
         }
         this.#scene.activeCamera?.detachControl();
-        if (!cameraState.locked && cameraState.value !== null) {
+        camera.detachControl();
+        if (!cameraState.locked) {
             camera.attachControl(this.#canvas, true);
         }
         this.#scene.activeCamera = camera;
@@ -1210,6 +1331,9 @@ export default class BabylonJSController {
                     compileMaterials: true,
                     loadAllMaterials: true,
                     loadOnlyMaterials: container.state.name === "materials",
+                    extensionOptions: {
+                        ExtrasAsMetadata: { enabled: true },
+                    },
                 },
             },
         };
@@ -1288,7 +1412,6 @@ export default class BabylonJSController {
                 this.#setMaxSimultaneousLights();
                 this.#loadCameraDepentEffects();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
-                this.#forceReflectionsInModelGlasses();
                 this.#startRender();
             });
         return detail;
@@ -1382,28 +1505,6 @@ export default class BabylonJSController {
         }
     }
 
-    /**
-     * Configures realistic glass material properties for all materials whose names include "Glass".
-     * @private
-     * @param {AssetContainer} [assetContainer] - The asset container with materials to process. If undefined, uses the model container.
-     * @returns {void}
-     * @note This method assumes that glass materials are named with the substring "Glass".
-     */
-    #forceReflectionsInModelGlasses(assetContainer) {
-        if (assetContainer === undefined) {
-            assetContainer = this.#containers.model.assetContainer;
-        }
-        if (!this.#scene || !assetContainer) {
-            return;
-        }
-        assetContainer.materials?.forEach(material => {
-            if (material && material.name && material.name.includes("Glass")) {
-                material.metallic = 0.25;
-                material.environmentIntensity = 1.0;
-            }
-        });
-    }
-
     /**
      * Translates a node along the scene's vertical (Y) axis by the provided value.
      * @private
@@ -1485,16 +1586,18 @@ export default class BabylonJSController {
             return;
         }
 
-        const header = "Download 3D Scene";
+        const locale = this.#prefViewer.culture;
+        const texts = translate("prefViewer.downloadDialog", locale ? { locale } : undefined) || {};
+        const header = texts.title || "Download 3D Scene";
         const content = `
             <form slot="content" id="download-dialog-form" style="display:flex;flex-direction:column;gap:16px;">
-                <h4>Content</h4>
+                <h4>${texts.sections?.content || "Content"}</h4>
                 <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
-                    <label><input type="radio" name="content" value="1"> Model</label>
-                    <label><input type="radio" name="content" value="2"> Scene</label>
-                    <label><input type="radio" name="content" value="0" checked> Both</label>
+                    <label><input type="radio" name="content" value="1"> ${texts.options?.model || "Model"}</label>
+                    <label><input type="radio" name="content" value="2"> ${texts.options?.scene || "Scene"}</label>
+                    <label><input type="radio" name="content" value="0" checked> ${texts.options?.both || "Both"}</label>
                 </div>
-                <h4>Format</h4>
+                <h4>${texts.sections?.format || "Format"}</h4>
                 <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
                 <label><input type="radio" name="format" value="gltf" checked> glTF (ZIP)</label>
                     <label><input type="radio" name="format" value="glb"> GLB</label>
@@ -1502,8 +1605,8 @@ export default class BabylonJSController {
                 </div>
             </form>`;
         const footer = `
-            <button type="button" class="primary" id="download-dialog-download">Download</button>
-            <button type="button" id="download-dialog-cancel">Cancel</button>`;
+            <button type="button" class="primary" id="download-dialog-download">${texts.buttons?.download || "Download"}</button>
+            <button type="button" id="download-dialog-cancel">${texts.buttons?.cancel || "Cancel"}</button>`;
 
         const dialog = this.#prefViewer.openDialog(header, content, footer);
 
@@ -1590,81 +1693,6 @@ export default class BabylonJSController {
         this.#disposeEngine();
     }
 
-    /**
-     * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
-     * Applies material and camera options, sets visibility, and initializes lights and shadows.
-     * @public
-     * @returns {Promise<boolean>} Resolves to true if loading succeeds, false otherwise.
-     */
-    async load() {
-        return await this.#loadContainers();
-    }
-
-    /**
-     * Applies camera options from the configuration to the active camera.
-     * Stops and restarts the render loop to apply changes.
-     * @public
-     * @returns {boolean} True if camera options were set successfully, false otherwise.
-     */
-    setCameraOptions() {
-        this.#stopRender();
-        const cameraOptionsSetted = this.#setOptions_Camera();
-        this.#loadCameraDepentEffects();
-        this.#startRender();
-        return cameraOptionsSetted;
-    }
-
-    /**
-     * Applies material options from the configuration to the relevant meshes.
-     * Stops and restarts the render loop to apply changes.
-     * @public
-     * @returns {boolean} True if material options were set successfully, false otherwise.
-     */
-    setMaterialOptions() {
-        this.#stopRender();
-        const materialsOptionsSetted = this.#setOptions_Materials();
-        this.#startRender();
-        return materialsOptionsSetted;
-    }
-
-    /**
-     * 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}
-     */
-    setIBLOptions() {
-        this.#stopRender();
-        const IBLOptionsSetted = this.#setOptions_IBL();
-        this.#loadCameraDepentEffects();
-        this.#startRender();
-        return IBLOptionsSetted;
-    }
-
-    /**
-     * Sets the visibility of a container (model, environment, etc.) by name.
-     * Adds or removes the container from the scene and updates wall/floor visibility.
-     * Restarts the render loop to apply changes.
-     * @public
-     * @param {string} name - The name of the container to show or hide.
-     * @param {boolean} show - True to show the container, false to hide it.
-     * @returns {void}
-     */
-    setContainerVisibility(name, show) {
-        const container = this.#findContainerByName(name);
-        if (!container) {
-            return;
-        }
-        if (container.state.show === show && container.state.visible === show) {
-            return;
-        }
-        container.state.show = show;
-        this.#stopRender();
-        show ? this.#addContainer(container) : this.#removeContainer(container);
-        this.#setVisibilityOfWallAndFloorInModel();
-        this.#startRender();
-    }
-
     /**
      * Downloads the current scene, model, or environment as a GLB file.
      * @public
@@ -1767,4 +1795,118 @@ export default class BabylonJSController {
             }
         });
     }
+
+    /**
+     * Returns a shallow copy of the current render settings so callers can read the active state without mutating the controller internals.
+     * @public
+     * @returns {{antiAliasingEnabled:boolean, ambientOcclusionEnabled:boolean, iblEnabled:boolean, shadowsEnabled:boolean}}
+     */
+    getRenderSettings() {
+        return { ...this.#settings };
+    }
+
+    /**
+     * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
+     * Applies material and camera options, sets visibility, and initializes lights and shadows.
+     * @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() };
+    }
+
+    /**
+     * Applies camera options from the configuration to the active camera.
+     * Stops and restarts the render loop to apply changes.
+     * @public
+     * @returns {boolean} True if camera options were set successfully, false otherwise.
+     */
+    setCameraOptions() {
+        this.#stopRender();
+        const cameraOptionsSetted = this.#setOptions_Camera();
+        this.#loadCameraDepentEffects();
+        this.#startRender();
+        return cameraOptionsSetted;
+    }
+
+    /**
+     * Applies material options from the configuration to the relevant meshes.
+     * Stops and restarts the render loop to apply changes.
+     * @public
+     * @returns {boolean} True if material options were set successfully, false otherwise.
+     */
+    setMaterialOptions() {
+        this.#stopRender();
+        const materialsOptionsSetted = this.#setOptions_Materials();
+        this.#startRender();
+        return materialsOptionsSetted;
+    }
+
+    /**
+     * 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}
+     */
+    setIBLOptions() {
+        this.#stopRender();
+        const IBLOptionsSetted = this.#setOptions_IBL();
+        this.#loadCameraDepentEffects();
+        this.#startRender();
+        return IBLOptionsSetted;
+    }
+
+    /**
+     * Sets the visibility of a container (model, environment, etc.) by name.
+     * Adds or removes the container from the scene and updates wall/floor visibility.
+     * Restarts the render loop to apply changes.
+     * @public
+     * @param {string} name - The name of the container to show or hide.
+     * @param {boolean} show - True to show the container, false to hide it.
+     * @returns {void}
+     */
+    setContainerVisibility(name, show) {
+        const container = this.#findContainerByName(name);
+        if (!container) {
+            return;
+        }
+        if (container.state.show === show && container.state.visible === show) {
+            return;
+        }
+        container.state.show = show;
+        this.#stopRender();
+        show ? this.#addContainer(container) : this.#removeContainer(container);
+        this.#setVisibilityOfWallAndFloorInModel();
+        this.#startRender();
+    }
+
+    /**
+     * Reloads every asset container using the latest staged render settings.
+     * Intended to be called after `scheduleRenderSettingsReload()` marks data as pending.
+     * @public
+     * @returns {Promise<{success:boolean,error:any}>} Resolves with the same status object returned by `load()`.
+     */
+    async reloadWithCurrentSettings() {
+        return await this.#loadContainers();
+    }
 }