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

package/package.json

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

package/src/babylonjs-animation-controller.js

@@ -1,5 +1,5 @@
 import { AssetContainer, Color3, HighlightLayer, InstancedMesh, Mesh, PickingInfo, Quaternion, Scene, UtilityLayerRenderer, Vector3 } from "@babylonjs/core";
-import { PrefViewerColors } from "./styles.js";
+import { PrefViewerStyleVariables } from "./styles.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 
 /**
@@ -32,7 +32,7 @@ export default class BabylonJSAnimationController {
     #animatedNodes = [];
     #openingAnimations = [];
 
-    #highlightColor = Color3.FromHexString(PrefViewerColors.primary);
+    #highlightColor = Color3.FromHexString(PrefViewerStyleVariables.colorPrimary);
     #highlightLayer = null;
     #overlayLayer = null;
     #useHighlightLayer = false; // Set to true to use HighlightLayer (better performance) and false to use overlay meshes (UtilityLayerRenderer - always on top)

package/src/babylonjs-controller.js

@@ -8,101 +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, resumes the render loop, and reports whether anything changed.
- *  - 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.
- *  - #addMeshToShadowGenerator(shadowGenerator, mesh): Adds eligible meshes to the provided shadow generator while honoring GLTF metadata.
- *  - #initializeShadows(): Sets up standard or IBL shadows for meshes.
- *  - #initializeDefaultLightShadows(): Configures soft shadows when no HDR environment exists.
- *  - #initializeEnvironmentShadows(): Rebuilds environment-provided shadow generators.
- *  - #ensureMeshesReceiveShadows(): Ensures every non-root mesh receives shadows unless metadata opts out.
- *  - #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;
 
@@ -133,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.
@@ -162,6 +127,7 @@ export default class BabylonJSController {
             };
         });
         this.#options = options;
+        this.#loadStoredRenderSettings();
         this.#bindHandlers();
     }
 
@@ -194,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
@@ -1512,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>
@@ -1529,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);
 
@@ -1617,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
@@ -1794,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();
+    }
 }

package/src/index.js

@@ -3,11 +3,13 @@ import PrefViewer from "./pref-viewer.js";
 import PrefViewer2D from "./pref-viewer-2d.js";
 import PrefViewer3D from "./pref-viewer-3d.js";
 import PrefViewerDialog from "./pref-viewer-dialog.js";
+import PrefViewerMenu3D from "./pref-viewer-menu-3d.js";
 
 // Defines custom elements for use as HTML tags in the application.
 customElements.define("pref-viewer-2d", PrefViewer2D);
 customElements.define("pref-viewer-3d", PrefViewer3D);
 customElements.define("pref-viewer-dialog", PrefViewerDialog);
+customElements.define("pref-viewer-menu-3d", PrefViewerMenu3D);
 customElements.define("pref-viewer", PrefViewer);
 
 // Exposes selected PrefViewer classes globally for external JavaScript use.