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

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -8,6 +8,9 @@ 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 BabylonJSViewCubeController from "./babylonjs-view-cube-controller.js";
+import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
+import BabylonJSCameraZoomController from "./babylonjs-camera-zoom-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 import { translate } from "./localization/i18n.js";
 import { PrefViewerStyleVariables } from "./styles.js";
@@ -34,11 +37,12 @@ export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlass
  *  - 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.
+ *  - Lazily owns the ViewCube overlay and binds a model-only orbital zoom guard independently of cube visibility.
  *  - 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)`.
+ *  1. Instantiate with `new BabylonJSController(canvas, containers, options, viewCubeConfig?)`.
  *  2. Call `enable()` to configure Draco, spin up the engine/scene, and attach interaction + XR hooks. The render loop
  *     does not start here; it starts automatically after the first `load()` completes.
  *  3. When PrefViewer marks containers/options pending, invoke `load()` (or `reloadWithCurrentSettings()`) so the controller
@@ -52,7 +56,8 @@ export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlass
  *     shared GLTF resolver, which closes its internal IndexedDB handle.
  *
  * Public API Highlights
- *  - constructor(canvas, containers, options)
+ *  - constructor(canvas, containers, options, viewCubeConfig?)
+ *  - setViewCubeEnabled(enabled) / refreshViewCube()
  *  - enable() / disable()
  *  - load(force?) / reloadWithCurrentSettings()
  *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
@@ -78,8 +83,9 @@ export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlass
  *  - 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
+ *    input avoids interaction picks; post-input orbital zoom protection separately probes only model meshes.
+ *    Right-click POINTERUP performs an on-demand interaction pick for context-menu targeting.
+ *  - Runtime bookkeeping is split into mutable `#state` and shared tuning settings under `BabylonJSController.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.
@@ -87,25 +93,6 @@ export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlass
  *    during XR exit and engine disposal.
  */
 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,
-        // Animation menu and highlight settings
-        showAnimationMenu: true,
-        highlightEnabled: true,
-        highlightColor: PrefViewerStyleVariables.colorPrimary,
-        // Lighting time of day (0=midnight, 0.5=noon, 1=midnight)
-        showLightingTimeOfDay: true,
-        lightingTimeOfDay: 0.5,
-    };
-
     // Canvas HTML element
     #canvas = null;
 
@@ -128,6 +115,13 @@ export default class BabylonJSController {
     #hdrTexture = null; // Reusable in-memory HDR source cloned into scene.environmentTexture across reloads
 
     #containers = {};
+
+    #viewCube = null;
+    #cameraZoom = null;
+    #viewCubeConfig = {};
+    #viewCubeEnabled = true;
+    #viewCubeSuspended = true;
+
     #options = {};
 
     #gltfResolver = null; // GLTFResolver instance
@@ -147,7 +141,7 @@ export default class BabylonJSController {
         renderLoop: null,
     };
 
-    #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
+    #renderSettings = { ...BabylonJSController.config.render.defaultSettings };
 
     // Runtime mutable state (changes while the app is running).
     #state = {
@@ -175,38 +169,22 @@ export default class BabylonJSController {
         },
     };
 
-    // 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 / 8, // Reduced from 15 FPS to 8 FPS for idle - reduces GPU/CPU load
-            idleThresholdMs: 3000, // Time before going to true idle (no renders)
-        },
-        resize: {
-            throttleMs: 50, // Cap resize work to ~20 Hz while dragging/resizing containers
-        },
-        defaultCameraFraming: {
-            margin: 1.25,          // Breathing room so the model doesn't touch the viewport edges
-            minRadiusFactor: 0.25, // Zoom in on detail
+    /**
+     * Shared runtime tuning settings accessible to cooperating controller classes.
+     * All instances use this object, including the quality preset updated by hardware detection.
+     * render.defaultSettings supplies defaults for each instance's persisted render settings snapshot.
+     * Per-instance render and interaction bookkeeping remains in #state.
+     * @public
+     * @static
+     * @type {object}
+     */
+    static config = {
+        camera: {
+            wheelDeltaPercentage: 0.015,
+            fitMarginFactor: 0.15, // Total free viewport fraction: 0.15 leaves 85% for the model
             maxRadiusFactor: 4,    // Pull back past the whole model
-        },
-        // Hardware-adaptive quality settings (applied based on GPU capabilities)
-        quality: {
-            // Settings for different hardware tiers: 'low', 'medium', 'high'
-            // Applied automatically based on GPU detected capabilities
-            tier: 'medium',          // Default, will be updated after hardware detection
-            shadowMapSize: 1024,     // Standard shadow generator resolution
-            iblShadowResolution: 1,  // IBL shadow resolution exponent (0=1024, 1=2048, 2=4096)
-            iblSampleDirections: 4,  // IBL shadow quality
-            shadowBlurKernel: 16,    // Shadow blur amount
-            ssaoEnabled: true,       // Screen Space Ambient Occlusion
+            minRadiusFactor: 0.25, // ViewCube minimum radius relative to transition distance
+            transitionDuration: 350, // ViewCube camera transition duration in milliseconds
         },
         look: {
             showroom: {
@@ -238,6 +216,47 @@ export default class BabylonJSController {
                 backgroundDay: [1.424, 1.424, 1.424],
             },
         },
+        pointerPicking: {
+            movePickIntervalMs: 50, // Cap expensive scene.pick calls to ~20 Hz while moving the pointer
+            movePickMinDistancePx: 2, // Skip picks for sub-pixel jitter
+        },
+        // Hardware-adaptive quality settings (applied based on GPU capabilities)
+        quality: {
+            // Settings for different hardware tiers: 'low', 'medium', 'high'
+            // Applied automatically based on GPU detected capabilities
+            tier: 'medium',          // Default, will be updated after hardware detection
+            shadowMapSize: 1024,     // Standard shadow generator resolution
+            iblShadowResolution: 1,  // IBL shadow resolution exponent (0=1024, 1=2048, 2=4096)
+            iblSampleDirections: 4,  // IBL shadow quality
+            shadowBlurKernel: 16,    // Shadow blur amount
+            ssaoEnabled: true,       // Screen Space Ambient Occlusion
+        },
+        render: {
+            // Default render settings. Add new persisted render toggles here and update their translation labels.
+            defaultSettings: {
+                antiAliasingEnabled: true,
+                ambientOcclusionEnabled: true,
+                iblEnabled: true,
+                shadowsEnabled: false,
+                // Animation menu and highlight settings
+                showAnimationMenu: true,
+                highlightEnabled: true,
+                highlightColor: PrefViewerStyleVariables.colorPrimary,
+                // Lighting time of day (0=midnight, 0.5=noon, 1=midnight)
+                showLightingTimeOfDay: true,
+                lightingTimeOfDay: 0.5,
+            },
+            burstFramesBase: 2,
+            burstFramesEnhanced: 32, // When AA/SSAO/IBL is enabled, more frames are needed to reach stable output
+            interactionMs: 250,
+            animationMs: 200,
+            idleThrottleMs: 1000 / 8, // Reduced from 15 FPS to 8 FPS for idle - reduces GPU/CPU load
+            idleThresholdMs: 3000, // Time before going to true idle (no renders)
+        },
+        resize: {
+            throttleMs: 50, // Cap resize work to ~20 Hz while dragging/resizing containers
+        },
+        storageKey: "pref-viewer/render-settings",
     };
 
     /**
@@ -474,7 +493,7 @@ export default class BabylonJSController {
         const preset = presetMap[tier] || qualityPresets.medium;
 
         // Apply preset to config
-        this.#config.quality = {
+        BabylonJSController.config.quality = {
             tier,
             ...preset,
             // Legacy compatibility
@@ -498,14 +517,20 @@ export default class BabylonJSController {
      * @param {HTMLCanvasElement|null} canvas - The canvas element to render the scene on.
      * @param {object} containers - An object containing container states for model, environment, materials, etc.
      * @param {object} options - Configuration options for the Babylon.js scene and assets.
+     * @param {object} [viewCubeConfig={}] - Internal overlay integration options.
+     * @param {boolean} [viewCubeConfig.enabled=true] - Desired activation; creation waits for a live scene and camera.
+     * @param {function(): string} [viewCubeConfig.getCulture] - Current UI culture for cube labels.
+     * @param {function(number, number): void} [viewCubeConfig.onLayout] - Measured cube SVG height and scene viewport height in CSS pixels; (0, 0) on disposal.
      * @returns {BabylonJSController}
      * @description
      *   - Assigns the provided canvas to the controller.
      *   - Initializes each container with its state and sets assetContainer to null.
      *   - Stores the provided options for later use in scene setup and asset loading.
      */
-    constructor(canvas = null, containers = {}, options = {}) {
+    constructor(canvas = null, containers = {}, options = {}, viewCubeConfig = {}) {
         this.#canvas = canvas;
+        this.#viewCubeConfig = viewCubeConfig;
+        this.#viewCubeEnabled = viewCubeConfig.enabled !== false;
         Object.keys(containers).forEach((key) => {
             this.#containers[key] = {
                 assetContainer: null,
@@ -563,18 +588,18 @@ export default class BabylonJSController {
         let changed = false;
         Object.keys(settings).forEach((key) => {
             // Handle boolean settings
-            if (typeof settings[key] === "boolean" && this.#settings[key] !== settings[key]) {
-                this.#settings[key] = settings[key];
+            if (typeof settings[key] === "boolean" && this.#renderSettings[key] !== settings[key]) {
+                this.#renderSettings[key] = settings[key];
                 changed = true;
             }
             // Handle string settings (like illuminationColor)
-            if (typeof settings[key] === "string" && this.#settings[key] !== settings[key]) {
-                this.#settings[key] = settings[key];
+            if (typeof settings[key] === "string" && this.#renderSettings[key] !== settings[key]) {
+                this.#renderSettings[key] = settings[key];
                 changed = true;
             }
             // Handle numeric settings such as lightingTimeOfDay
-            if (typeof settings[key] === "number" && Number.isFinite(settings[key]) && this.#settings[key] !== settings[key]) {
-                this.#settings[key] = settings[key];
+            if (typeof settings[key] === "number" && Number.isFinite(settings[key]) && this.#renderSettings[key] !== settings[key]) {
+                this.#renderSettings[key] = settings[key];
                 changed = true;
             }
         });
@@ -597,23 +622,23 @@ export default class BabylonJSController {
             return;
         }
         try {
-            const serialized = window.localStorage.getItem(this.#RENDER_SETTINGS_STORAGE_KEY);
+            const serialized = window.localStorage.getItem(BabylonJSController.config.storageKey);
             if (!serialized) {
                 return;
             }
             const parsed = JSON.parse(serialized);
-            Object.keys(BabylonJSController.DEFAULT_RENDER_SETTINGS).forEach((key) => {
+            Object.keys(BabylonJSController.config.render.defaultSettings).forEach((key) => {
                 // Handle boolean settings
                 if (typeof parsed?.[key] === "boolean") {
-                    this.#settings[key] = parsed[key];
+                    this.#renderSettings[key] = parsed[key];
                 }
                 // Handle string settings (like illuminationColor)
                 if (typeof parsed?.[key] === "string") {
-                    this.#settings[key] = parsed[key];
+                    this.#renderSettings[key] = parsed[key];
                 }
                 // Handle numeric settings such as lightingTimeOfDay
                 if (typeof parsed?.[key] === "number" && Number.isFinite(parsed[key])) {
-                    this.#settings[key] = parsed[key];
+                    this.#renderSettings[key] = parsed[key];
                 }
             });
         } catch (error) {
@@ -632,7 +657,7 @@ export default class BabylonJSController {
             return;
         }
         try {
-            window.localStorage.setItem(this.#RENDER_SETTINGS_STORAGE_KEY, JSON.stringify(this.#settings));
+            window.localStorage.setItem(BabylonJSController.config.storageKey, JSON.stringify(this.#renderSettings));
         } catch (error) {
             console.warn("PrefViewer: unable to store render settings", error);
         }
@@ -687,7 +712,7 @@ export default class BabylonJSController {
 
         const timeoutMs = 2000;
         const startedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-        this.#requestRender({ frames: this.#config.render.burstFramesEnhanced, continuousMs: timeoutMs });
+        this.#requestRender({ frames: BabylonJSController.config.render.burstFramesEnhanced, continuousMs: timeoutMs });
 
         try {
             await new Promise((resolve) => {
@@ -844,7 +869,7 @@ export default class BabylonJSController {
 
     /**
      * Evaluates whether the renderer should stay in continuous mode.
-     * XR always forces continuous rendering; animation/camera motion also extends the
+     * Pending ViewCube transitions and active XR force continuous rendering; animation/camera motion extends the
      * continuous deadline window to avoid abrupt stop-start behavior.
      * OPTIMIZATION: Added true idle mode - stops rendering completely after idleThresholdMs of inactivity.
      * @private
@@ -852,6 +877,9 @@ export default class BabylonJSController {
      * @returns {boolean} True when continuous rendering should remain active.
      */
     #shouldRenderContinuously(now) {
+        if (this.#viewCube?.isAnimating) {
+            return true;
+        }
         const inXR = this.#XRExperience?.baseExperience?.state === WebXRState.IN_XR;
         if (inXR) {
             this.#state.render.isIdle = false;
@@ -863,19 +891,19 @@ export default class BabylonJSController {
         const cameraInMotion = this.#isCameraInMotion();
 
         if (animationRunning) {
-            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.animationMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + BabylonJSController.config.render.animationMs);
             this.#state.render.isIdle = false;
             this.#state.render.lastActivityAt = now;
         }
         if (cameraInMotion) {
-            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.interactionMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + BabylonJSController.config.render.interactionMs);
             this.#state.render.isIdle = false;
             this.#state.render.lastActivityAt = now;
         }
 
         // OPTIMIZATION: True idle mode - if no activity for idleThresholdMs, stop rendering completely
         const timeSinceActivity = now - this.#state.render.lastActivityAt;
-        if (timeSinceActivity > this.#config.render.idleThresholdMs) {
+        if (timeSinceActivity > BabylonJSController.config.render.idleThresholdMs) {
             this.#state.render.isIdle = true;
         }
 
@@ -891,7 +919,8 @@ export default class BabylonJSController {
 
     /**
      * Render loop callback for Babylon.js.
-     * Runs only while scene state is dirty, interactive motion is active, animations are running, or XR is active.
+     * Runs while scene state is dirty, interactive motion/animations are active, or XR/ViewCube navigation requires it.
+     * Suspends dynamic zoom constraints during cube framing, advances its transition, renders and synchronizes its indicator.
      * It self-stops when the scene becomes idle (true idle mode - no renders at all).
      * OPTIMIZATION: Added true idle mode that completely stops rendering after idleThresholdMs.
      * @private
@@ -918,11 +947,16 @@ export default class BabylonJSController {
             return;
         }
 
-        if (!continuous && this.#state.render.lastRenderAt > 0 && now - this.#state.render.lastRenderAt < this.#config.render.idleThrottleMs) {
+        if (!continuous && this.#state.render.lastRenderAt > 0 && now - this.#state.render.lastRenderAt < BabylonJSController.config.render.idleThrottleMs) {
             return;
         }
 
+        if (this.#viewCube?.isAnimating) {
+            this.#cameraZoom?.update();
+        }
+        this.#viewCube?.tick(now);
         this.#scene.render();
+        this.#viewCube?.sync();
         this.#state.render.lastRenderAt = now;
 
         if (this.#state.render.dirtyFrames > 0) {
@@ -1005,15 +1039,20 @@ export default class BabylonJSController {
     }
 
     /**
-     * Creates and configures the main ArcRotateCamera for the Babylon.js scene.
+     * Creates the default ArcRotateCamera with unrestricted beta, upright orbit and proportional native wheel zoom.
+     * Starts at the exact Inner orientation (+Z, alpha/beta pi/2), matching the ViewCube before loading.
+     * Starts without a fixed lower radius; the independent model zoom guard supplies the dynamic floor.
+     * Imported-camera configuration is applied separately and is not reset here.
      * @private
      * @returns {void}
      */
     #createCamera() {
-        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;
+        this.#camera = new ArcRotateCamera("defaultCamera", Math.PI / 2, Math.PI / 2, 10, Vector3.Zero(), this.#scene);
+        this.#camera.upperBetaLimit = null;
+        this.#camera.lowerBetaLimit = null;
+        this.#camera.allowUpsideDown = false;
+        this.#camera.wheelDeltaPercentage = BabylonJSController.config.camera.wheelDeltaPercentage;
+        this.#camera.lowerRadiusLimit = null;
         this.#camera.upperRadiusLimit = 20;
         this.#camera.metadata = { locked: false };
         this.#applyShowroomCameraFraming(this.#camera);
@@ -1040,7 +1079,7 @@ export default class BabylonJSController {
 
         let lightsChanged = false;
 
-        const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
+        const iblEnabled = this.#renderSettings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
 
         if (iblEnabled) {
             lightsChanged = await this.#initializeEnvironmentTexture();
@@ -1120,7 +1159,7 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#settings.ambientOcclusionEnabled) {
+        if (!this.#renderSettings.ambientOcclusionEnabled) {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
@@ -1221,7 +1260,7 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#settings.antiAliasingEnabled) {
+        if (!this.#renderSettings.antiAliasingEnabled) {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
@@ -1283,7 +1322,7 @@ export default class BabylonJSController {
         let hdrTexture = null;
         if (this.#options.ibl?.cachedUrl) {
             const hdrTextureURI = this.#options.ibl.cachedUrl;
-            const envTextureSize = this.#config.quality.environmentTextureSize || 1024;
+            const envTextureSize = BabylonJSController.config.quality.environmentTextureSize || 1024;
             hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, envTextureSize, false, false, false, true, undefined, undefined, false, true, true);
         } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
             hdrTexture = this.#hdrTexture.clone();
@@ -1411,8 +1450,8 @@ export default class BabylonJSController {
 
         // Use hardware-adaptive quality settings
         const pipelineOptions = {
-            resolutionExp: this.#config.quality.iblShadowResolution, // Adaptive: 0=1024, 1=2048, 2=4096
-            sampleDirections: this.#config.quality.iblSampleDirections, // Adaptive: 2=fast, 4=quality
+            resolutionExp: BabylonJSController.config.quality.iblShadowResolution, // Adaptive: 0=1024, 1=2048, 2=4096
+            sampleDirections: BabylonJSController.config.quality.iblSampleDirections, // Adaptive: 2=fast, 4=quality
             ssShadowsEnabled: true,
             shadowRemanence: 0.85,
             triPlanarVoxelization: true,
@@ -1493,11 +1532,11 @@ export default class BabylonJSController {
         }
         this.#dirLight.autoUpdateExtends = false;
         // Use quality-adaptive shadow map size
-        const shadowMapSize = this.#config.quality.shadowMapSize;
+        const shadowMapSize = BabylonJSController.config.quality.shadowMapSize;
         const shadowGenerator = new ShadowGenerator(shadowMapSize, this.#dirLight);
         shadowGenerator.useBlurExponentialShadowMap = true;
         // Use quality-adaptive blur kernel
-        shadowGenerator.blurKernel = this.#config.quality.shadowBlurKernel;
+        shadowGenerator.blurKernel = BabylonJSController.config.quality.shadowBlurKernel;
         shadowGenerator.darkness = 0.5;
         shadowGenerator.bias = 0.0005;
         shadowGenerator.normalBias = 0.02;
@@ -1579,13 +1618,13 @@ export default class BabylonJSController {
      * Otherwise, sets up shadow casting and receiving for all relevant meshes using the shadow generator.
      */
     async #initializeShadows() {
-        if (!this.#settings.shadowsEnabled) {
+        if (!this.#renderSettings.shadowsEnabled) {
             return false;
         }
 
         this.#ensureMeshesReceiveShadows();
 
-        const iblEnabled = this.#settings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
+        const iblEnabled = this.#renderSettings.iblEnabled && (this.#options.ibl?.valid === true || !!this.#options.ibl?.cachedUrl);
         const iblShadowsEnabled = iblEnabled && this.#options.ibl.shadows;
 
         if (iblShadowsEnabled) {
@@ -1603,7 +1642,9 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #setMaxSimultaneousLights() {
-        if (!this.#scene) return;
+        if (!this.#scene) {
+            return;
+        }
         let lightsNumber = 1; // At least one light coming from the environment texture contribution
         this.#scene.lights.forEach((light) => {
             if (light.isEnabled()) {
@@ -1657,10 +1698,10 @@ export default class BabylonJSController {
             return;
         }
 
-        const showroom = this.#config.look?.showroom || {};
+        const showroom = BabylonJSController.config.look?.showroom || {};
         const imageProcessing = this.#scene.imageProcessingConfiguration;
 
-        const bg = showroom.backgroundDay ?? this.#config.look.showroom.backgroundDay;
+        const bg = showroom.backgroundDay ?? BabylonJSController.config.look.showroom.backgroundDay;
         this.#scene.clearColor = new Color4(bg[0], bg[1], bg[2], 1);
         imageProcessing.exposure = showroom.exposure ?? 0.95;
         imageProcessing.contrast = showroom.contrast ?? 1.08;
@@ -1684,8 +1725,8 @@ export default class BabylonJSController {
             return false;
         }
 
-        const showroom = this.#config.look?.showroom || {};
-        const timeOfDay = clamp01(this.#settings.lightingTimeOfDay ? this.#settings.lightingTimeOfDay ?? 0.5 : 0.5);
+        const showroom = BabylonJSController.config.look?.showroom || {};
+        const timeOfDay = clamp01(this.#renderSettings.lightingTimeOfDay ? this.#renderSettings.lightingTimeOfDay ?? 0.5 : 0.5);
         const profile = getLightingCycleProfile(timeOfDay);
         const daylight = profile.dayFactor;
         const peakLight = daylight > 0 ? Math.pow(daylight, 0.72) : 0;
@@ -1703,7 +1744,7 @@ export default class BabylonJSController {
 
         // Night end stays in low linear values (a dark blue sky); the day end is the calibrated
         // HDR off-white. Both are linear already, so no toLinearSpace() on either.
-        const bgDay = showroom.backgroundDay ?? this.#config.look.showroom.backgroundDay;
+        const bgDay = showroom.backgroundDay ?? BabylonJSController.config.look.showroom.backgroundDay;
         this.#scene.clearColor = new Color4(
             lerp(0.000627, bgDay[0], daylight),
             lerp(0.001089, bgDay[1], daylight),
@@ -1760,7 +1801,7 @@ export default class BabylonJSController {
         }
 
         this.#scene.markAllMaterialsAsDirty?.(Material.LightDirtyFlag ?? Material.TextureDirtyFlag);
-        this.#requestRender({ frames: 2, continuousMs: this.#config.render.interactionMs });
+        this.#requestRender({ frames: 2, continuousMs: BabylonJSController.config.render.interactionMs });
         return true;
     }
 
@@ -1776,81 +1817,62 @@ export default class BabylonJSController {
         }
 
         const pixelRatio = typeof window !== "undefined" ? window.devicePixelRatio : 1;
-        const baseScaling = this.#config.quality.hardwareScaling || 1;
+        const baseScaling = BabylonJSController.config.quality.hardwareScaling || 1;
         const scalingLevel = getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
         this.#engine.setHardwareScalingLevel(scalingLevel);
     }
 
     /**
-     * World-space bounds of the loaded model's renderable geometry.
+     * Frames the default camera using the shared model-framing calculation.
+     * Preserves its current orientation and projection; excludes environment geometry.
+     * Applies the destination immediately, without a ViewCube transition.
+     * The default camera has no parent; imported cameras retain their authored framing.
      * @private
-     * @returns {{center: Vector3, radius: number}|null} Centre and bounding-sphere radius, or null when nothing renderable is loaded.
-     */
-    #getModelBounds() {
-        const meshes = (this.#containers?.model?.assetContainer?.meshes ?? []).filter((mesh) => (mesh?.getTotalVertices?.() ?? 0) > 0);
-        if (meshes.length === 0) {
-            return null;
-        }
-
-        let min = null;
-        let max = null;
-        meshes.forEach((mesh) => {
-            mesh.computeWorldMatrix(true);
-            const box = mesh.getBoundingInfo?.()?.boundingBox;
-            if (!box) {
-                return;
-            }
-            min = min ? Vector3.Minimize(min, box.minimumWorld) : box.minimumWorld.clone();
-            max = max ? Vector3.Maximize(max, box.maximumWorld) : box.maximumWorld.clone();
-        });
-
-        if (!min || !max) {
-            return null;
-        }
-
-        const radius = Vector3.Distance(min, max) / 2;
-        if (!Number.isFinite(radius) || radius <= 0) {
-            return null;
-        }
-
-        return { center: Vector3.Center(min, max), radius };
-    }
-
-    /**
-     * Frames the default camera on the loaded model: aims it at the model's centre and pulls it
-     * back far enough for the whole model to fit the viewport.
-     *
-     * Only ever applied to the viewer's own camera — a camera authored in the model or the scene
-     * is a composition choice and is left untouched. Orbit angles are preserved so a model reload
-     * (an option or dimension change) re-centres without snapping the user's viewpoint back.
-     * @private
-     * @param {Camera|null|undefined} camera - The camera about to become active.
+     * @param {Camera|null|undefined} camera - Camera about to become active.
      * @returns {void}
      */
     #fitDefaultCameraToModel(camera) {
         if (camera !== this.#camera || !(camera instanceof ArcRotateCamera)) {
             return;
         }
-
-        const bounds = this.#getModelBounds();
+        const bounds = BabylonJSCameraFraming.getModelBounds(this.#containers.model?.assetContainer);
         if (!bounds) {
             return;
         }
-
-        // fovMode is FOVMODE_HORIZONTAL_FIXED (see #applyShowroomCameraFraming), so camera.fov is
-        // the horizontal angle and the vertical one follows the aspect ratio. Fitting to the
-        // horizontal angle alone clips the model top and bottom on any viewport wider than tall.
-        const aspect = this.#engine?.getAspectRatio?.(camera) || 1;
-        const horizontalFov = camera.fov;
-        const verticalFov = 2 * Math.atan(Math.tan(horizontalFov / 2) / aspect);
-        const limitingFov = Math.min(horizontalFov, verticalFov);
-        const distance = (bounds.radius / Math.sin(limitingFov / 2)) * this.#config.defaultCameraFraming.margin;
-
-        camera.setTarget(bounds.center);
-        camera.radius = distance;
-        // The 5-20 m defaults were sized for a room; left in place they clamp the fit itself.
-        camera.lowerRadiusLimit = distance * this.#config.defaultCameraFraming.minRadiusFactor;
-        camera.upperRadiusLimit = distance * this.#config.defaultCameraFraming.maxRadiusFactor;
+        camera.getViewMatrix(true);
+        const direction = camera.globalPosition.subtract(camera.getTarget());
+        if (direction.lengthSquared() <= 1e-12) {
+            return;
+        }
+        direction.normalize();
+        const fit = BabylonJSCameraFraming.calculateCameraFit(camera, bounds, direction, {
+            width: this.#canvas.clientWidth,
+            height: this.#canvas.clientHeight,
+        });
+        if (!fit) {
+            return;
+        }
+        // Geometry protection supplies the minimum zoom radius.
+        camera.lowerRadiusLimit = null;
+        camera.upperRadiusLimit = fit.distance * BabylonJSController.config.camera.maxRadiusFactor;
+        camera.upVector = Vector3.Up();
+        camera.setTarget(fit.target);
+        // Match ViewCube's destination orientation, including its small pole correction.
+        const rotationMatrix = Matrix.Identity();
+        fit.rotation.toRotationMatrix(rotationMatrix);
+        const forward = Vector3.TransformNormal(
+            new Vector3(0, 0, camera.getScene().useRightHandedSystem ? -1 : 1),
+            rotationMatrix
+        );
+        camera.setPosition(fit.target.subtract(forward.scale(fit.distance)));
+        if (camera.mode === Camera.ORTHOGRAPHIC_CAMERA) {
+            camera.orthoLeft = -fit.halfWidth;
+            camera.orthoRight = fit.halfWidth;
+            camera.orthoBottom = -fit.halfHeight;
+            camera.orthoTop = fit.halfHeight;
+        }
+        camera.minZ = Math.min(camera.minZ > 0 ? camera.minZ : Infinity, Math.max(fit.radius * 0.001, 0.00001));
+        camera.maxZ = Math.max(camera.maxZ, fit.distance + fit.radius * 2);
     }
 
     /**
@@ -1896,7 +1918,7 @@ export default class BabylonJSController {
         const x = this.#scene.pointerX;
         const y = this.#scene.pointerY;
         const state = this.#state.pointerPicking;
-        const config = this.#config.pointerPicking;
+        const config = BabylonJSController.config.pointerPicking;
 
         if (!Number.isFinite(state.lastMovePickX) || !Number.isFinite(state.lastMovePickY)) {
             state.lastMovePickX = x;
@@ -2065,7 +2087,7 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onAnimationGroupPlay() {
-        this.#requestRender({ frames: 1, continuousMs: this.#config.render.animationMs });
+        this.#requestRender({ frames: 1, continuousMs: BabylonJSController.config.render.animationMs });
     }
 
     /**
@@ -2074,11 +2096,11 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onAnimationGroupStop() {
-        if (this.#settings.iblEnabled && this.#renderPipelines.iblShadows) {
+        if (this.#renderSettings.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;
+        const frames = this.#renderSettings.antiAliasingEnabled || this.#renderSettings.ambientOcclusionEnabled || this.#renderSettings.iblEnabled ? BabylonJSController.config.render.burstFramesEnhanced : BabylonJSController.config.render.burstFramesBase;
         this.#requestRender({ frames: frames });
     }
 
@@ -2131,7 +2153,8 @@ export default class BabylonJSController {
     }
 
     /**
-     * Handles mouse wheel events on the Babylon.js canvas for zooming the camera.
+     * Wakes rendering for native orbital wheel zoom and handles wheel movement for target cameras.
+     * ArcRotateCamera owns proportional wheel zoom; do not add a second radius offset here.
      * OPTIMIZATION: Tracks activity for idle mode.
      * @private
      * @param {WheelEvent} event - The mouse wheel event.
@@ -2151,10 +2174,7 @@ export default class BabylonJSController {
             return false;
         }
         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) {
+            if (camera instanceof FreeCamera || camera instanceof UniversalCamera) {
                 camera.wheelPrecision = camera.wheelPrecision || 3.0;
                 const zoomSpeed = -event.deltaY * camera.wheelPrecision * 0.001;
 
@@ -2163,7 +2183,7 @@ export default class BabylonJSController {
                 const movementVector = direction.scale(zoomSpeed);
                 camera.position = camera.position.add(movementVector);
             }
-            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
+            this.#requestRender({ frames: 1, continuousMs: BabylonJSController.config.render.interactionMs });
         }
     }
 
@@ -2208,14 +2228,14 @@ export default class BabylonJSController {
 
         const camera = this.#scene?.activeCamera;
         if (camera && !camera.metadata?.locked) {
-            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
+            this.#requestRender({ frames: 1, continuousMs: BabylonJSController.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 });
+                    this.#requestRender({ frames: 1, continuousMs: BabylonJSController.config.render.interactionMs });
                 }
             }
         }
@@ -2272,12 +2292,12 @@ export default class BabylonJSController {
             console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
             this.#applyShowroomCameraFraming();
             this.#engine.resize();
-            const needsEnhancedBurst = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled || this.#settings.shadowsEnabled;
-            const frames = needsEnhancedBurst ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
-            this.#requestRender({ frames, continuousMs: this.#config.render.interactionMs });
+            const needsEnhancedBurst = this.#renderSettings.antiAliasingEnabled || this.#renderSettings.ambientOcclusionEnabled || this.#renderSettings.iblEnabled || this.#renderSettings.shadowsEnabled;
+            const frames = needsEnhancedBurst ? BabylonJSController.config.render.burstFramesEnhanced : BabylonJSController.config.render.burstFramesBase;
+            this.#requestRender({ frames, continuousMs: BabylonJSController.config.render.interactionMs });
         };
 
-        if (elapsed >= this.#config.resize.throttleMs) {
+        if (elapsed >= BabylonJSController.config.resize.throttleMs) {
             applyResize();
             return;
         }
@@ -2287,7 +2307,7 @@ export default class BabylonJSController {
         }
 
         this.#state.resize.isScheduled = true;
-        const waitMs = Math.max(0, this.#config.resize.throttleMs - elapsed);
+        const waitMs = Math.max(0, BabylonJSController.config.resize.throttleMs - elapsed);
         this.#state.resize.timeoutId = setTimeout(() => {
             applyResize();
         }, waitMs);
@@ -2373,11 +2393,14 @@ export default class BabylonJSController {
     }
 
     /**
-     * Applies camera options from the configuration to the active camera.
+     * Cancels pending cube navigation and applies configured camera selection and locking.
+     * Configures unlocked orbital cameras for proportional native wheel input, rebinds the model zoom guard
+     * and synchronizes the cube after selecting the active camera.
      * @private
      * @returns {boolean} True if camera options were set successfully, false otherwise.
      */
     #setOptions_Camera() {
+        this.#viewCube?.cancel();
         const cameraState = this.#options.camera;
         const modelContainer = this.#containers.model;
         const environmentContainer = this.#containers.environment;
@@ -2431,9 +2454,14 @@ export default class BabylonJSController {
         this.#scene.activeCamera?.detachControl();
         camera.detachControl();
         if (!cameraState.locked) {
+            if (camera instanceof ArcRotateCamera) {
+                camera.wheelDeltaPercentage = BabylonJSController.config.camera.wheelDeltaPercentage;
+            }
             camera.attachControl(this.#canvas, true);
         }
         this.#scene.activeCamera = camera;
+        this.#cameraZoom?.setCamera(camera);
+        this.#viewCube?.sync();
         return true;
     }
 
@@ -2628,8 +2656,12 @@ export default class BabylonJSController {
      */
     #assetContainer_simplifyTransmissiveMaterials(assetContainer) {
         assetContainer.materials?.forEach((mat) => {
-            if (!(mat instanceof PBRMaterial)) return;
-            if (!mat.subSurface?.isRefractionEnabled && !mat.subSurface?.isTranslucencyEnabled) return;
+            if (!(mat instanceof PBRMaterial)) {
+                return;
+            }
+            if (!mat.subSurface?.isRefractionEnabled && !mat.subSurface?.isTranslucencyEnabled) {
+                return;
+            }
             this.#simplifyTransmissiveMaterial(mat);
         });
     }
@@ -2700,11 +2732,13 @@ export default class BabylonJSController {
      * @returns {Promise<void>}
      */
     async #startRender() {
-        if (!this.#scene) return;
+        if (!this.#scene) {
+            return;
+        }
         await this.#loadCameraDependentEffects();
         await this.#scene.whenReadyAsync();
-        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 });
+        const frames = this.#renderSettings.antiAliasingEnabled || this.#renderSettings.ambientOcclusionEnabled || this.#renderSettings.iblEnabled ? BabylonJSController.config.render.burstFramesEnhanced : BabylonJSController.config.render.burstFramesBase;
+        this.#requestRender({ frames: frames, continuousMs: BabylonJSController.config.render.interactionMs });
     }
 
     /**
@@ -2776,15 +2810,18 @@ export default class BabylonJSController {
     }
 
     /**
-     * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
+     * Cancels pending cube navigation, loads asset containers and adds replacements to the scene.
+     * Current model selection is resolved by the zoom guard on subsequent input updates.
      * @private
+     * @param {boolean} [force=false] - Whether to bypass existing asset cache metadata.
      * @returns {Promise<{success: boolean, error: any}>} Resolves to an object indicating if loading succeeded and any error encountered.
      * @description
      * Waits for all containers to load in parallel, then replaces or adds them to the scene as needed.
-     * Applies material and camera options, sets wall/floor visibility, and initializes lights and shadows.
+     * Applies material options and wall/floor visibility before camera fitting, then initializes lights and shadows.
      * Returns an object with success status and error details.
      */
     async #loadContainers(force = false) {
+        this.#viewCube?.cancel();
         this.#detachAnimationChangedListener();
         await this.#stopRender();
 
@@ -2837,9 +2874,10 @@ export default class BabylonJSController {
                 });
 
                 this.#setOptions_Materials();
+                // Apply effective geometry visibility before calculating the camera fit.
+                this.#setVisibilityOfWallAndFloorInModel();
                 this.#setOptions_Camera();
                 await this.#setOptions_IBL();
-                this.#setVisibilityOfWallAndFloorInModel();
                 detail.success = true;
             })
             .catch((error) => {
@@ -2865,12 +2903,12 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #syncAnimationControllerAfterModelLoad() {
-        if (this.#settings.showAnimationMenu && this.#containers.model.assetContainer) {
+        if (this.#renderSettings.showAnimationMenu && this.#containers.model.assetContainer) {
             this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
             // Apply stored highlight settings so fresh page loads respect persisted state
             this.#setHighlightConfig({
-                enabled: this.#settings.highlightEnabled,
-                color: this.#settings.highlightColor,
+                enabled: this.#renderSettings.highlightEnabled,
+                color: this.#renderSettings.highlightColor,
             });
             if (this.#babylonJSAnimationController?.hasAnimations?.()) {
                 this.#attachAnimationChangedListener();
@@ -3122,10 +3160,34 @@ export default class BabylonJSController {
      * ---------------------------
      */
 
+    /**
+     * Creates the enabled cube once a live scene/camera exists and teardown is not in progress.
+     * Resolves camera/model state through callbacks; does not reload assets or camera options.
+     * @private
+     * @returns {void}
+     */
+    #initializeViewCube() {
+        if (!this.#viewCubeEnabled || this.#viewCubeSuspended || this.#viewCube || !this.#engine || !this.#scene?.activeCamera) {
+            return;
+        }
+        this.#viewCube = new BabylonJSViewCubeController({
+            canvas: this.#canvas,
+            getCamera: () => this.#scene?.activeCamera,
+            isLocked: (camera) => !camera || camera.metadata?.locked === true || this.#XRExperience?.baseExperience?.state === WebXRState.IN_XR,
+            getBounds: () => BabylonJSCameraFraming.getModelBounds(this.#containers.model?.assetContainer),
+            getViewport: () => ({ width: this.#canvas.clientWidth, height: this.#canvas.clientHeight }),
+            getCulture: this.#viewCubeConfig.getCulture,
+            onLayout: this.#viewCubeConfig.onLayout,
+            requestRender: () => this.#requestRender({ frames: 2 }),
+        });
+    }
+
     /**
      * Initializes the Babylon.js engine, scene, camera, lights, and interaction handlers.
-     * Configures Draco compression, sets up XR experience, and starts the render loop.
-     * Observes canvas resize events to update the engine.
+     * Configures Draco compression and sets up XR; rendering starts through the existing load/request scheduler.
+     * Observes canvas resize events, binds model-only orbital zoom protection and adaptive default-camera near clipping,
+     * and lazily creates the requested cube. Imported camera clipping is preserved by the host policy.
+     * Aborts remaining initialization if the scene was replaced/disposed during texture readiness.
      * @public
      * @returns {Promise<void>}
      */
@@ -3161,20 +3223,39 @@ export default class BabylonJSController {
         this.#scene.skipPointerUpPicking = true;
 
         this.#createCamera();
+        this.#cameraZoom = new BabylonJSCameraZoomController(
+            () => this.#containers.model?.state?.isVisible ? this.#containers.model.assetContainer : null,
+            (camera) => camera.metadata?.locked === true || this.#XRExperience?.baseExperience?.state === WebXRState.IN_XR,
+            () => this.#viewCube?.isAnimating === true,
+            (camera) => camera === this.#camera,
+        );
+        this.#cameraZoom.setCamera(this.#camera);
+        this.#viewCubeSuspended = false;
+        this.#initializeViewCube();
+        const enabledScene = this.#scene;
         await this.#ensureEnvironmentBRDFTextureReady();
+        if (!this.#engine || this.#scene !== enabledScene) {
+            return;
+        }
         this.#enableInteraction();
         await this.#createXRExperience();
     }
 
     /**
      * Disposes the Babylon.js engine and disconnects the canvas resize observer.
-     * Cleans up all scene, camera, light, XR, and GLTF resolver resources.
+     * Releases the zoom observer and cube overlay before scene teardown, restoring the zoom camera
+     * floor and suspending cube creation until the next enable. Cleans up light, XR and 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 {Promise<void>}
      */
     async disable() {
+        this.#cameraZoom?.dispose();
+        this.#cameraZoom = null;
+        this.#viewCubeSuspended = true;
+        this.#viewCube?.dispose();
+        this.#viewCube = null;
         if (this.#disablingPromises.general) {
             return await this.#disablingPromises.general;
         }
@@ -3205,6 +3286,32 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Lazily creates the cube when enabled and releases all cube resources when disabled.
+     * Stores activation until a live scene is available; never reloads assets or camera options.
+     * @public
+     * @param {boolean} enabled - Whether the visible 3D viewer should own a ViewCube.
+     * @returns {void}
+     */
+    setViewCubeEnabled(enabled) {
+        this.#viewCubeEnabled = Boolean(enabled);
+        if (this.#viewCubeEnabled) {
+            this.#initializeViewCube();
+        } else {
+            this.#viewCube?.dispose();
+            this.#viewCube = null;
+        }
+    }
+
+    /**
+     * Synchronizes the existing cube after culture or camera-state changes without creating an inactive cube.
+     * @public
+     * @returns {void}
+     */
+    refreshViewCube() {
+        this.#viewCube?.sync();
+    }
+
     /**
      * Downloads the current scene, model, or environment as a GLB file.
      * @public
@@ -3314,7 +3421,7 @@ export default class BabylonJSController {
      * @returns {{antiAliasingEnabled:boolean, ambientOcclusionEnabled:boolean, iblEnabled:boolean, shadowsEnabled:boolean}}
      */
     getRenderSettings() {
-        return { ...this.#settings };
+        return { ...this.#renderSettings };
     }
 
     /**
@@ -3484,7 +3591,7 @@ export default class BabylonJSController {
                 max: vectorToJSON(modelBounds.max),
             } : null,
             render: { ...this.#state.render },
-            settings: { ...this.#settings },
+            settings: { ...this.#renderSettings },
             pipelines: {
                 default: Boolean(this.#renderPipelines.default),
                 ssao: Boolean(this.#renderPipelines.ssao),
@@ -3548,7 +3655,7 @@ export default class BabylonJSController {
      * Applies animation-menu, highlight, and time-of-day lighting configuration without forcing a full scene reload.
      * Values are merged into the persisted render settings snapshot unless `config.persist === false`.
      * When `showLightingTimeOfDay` is set to false and no explicit `lightingTimeOfDay` is supplied,
-     * the active lighting time is reset to `DEFAULT_RENDER_SETTINGS.lightingTimeOfDay` (0.5).
+     * the active lighting time is reset to `BabylonJSController.config.render.defaultSettings.lightingTimeOfDay` (0.5).
      * @public
      * @param {object} config - Immediate render/illumination configuration.
      * @param {boolean|string} [config.showAnimationMenu] - Enables/disables the animation controls when animations are available.
@@ -3566,16 +3673,16 @@ export default class BabylonJSController {
             const showLighting = typeof config.showLightingTimeOfDay === "string"
                 ? config.showLightingTimeOfDay.toLowerCase() !== "false"
                 : Boolean(config.showLightingTimeOfDay);
-            if (this.#settings.showLightingTimeOfDay !== showLighting) {
+            if (this.#renderSettings.showLightingTimeOfDay !== showLighting) {
                 shouldApplyLighting = true;
             }
-            this.#settings.showLightingTimeOfDay = showLighting;
+            this.#renderSettings.showLightingTimeOfDay = showLighting;
 
             const hasExplicitLightingTime = typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay);
             if (!showLighting && !hasExplicitLightingTime) {
-                const defaultTime = BabylonJSController.DEFAULT_RENDER_SETTINGS.lightingTimeOfDay;
-                if (this.#settings.lightingTimeOfDay !== defaultTime) {
-                    this.#settings.lightingTimeOfDay = defaultTime;
+                const defaultTime = BabylonJSController.config.render.defaultSettings.lightingTimeOfDay;
+                if (this.#renderSettings.lightingTimeOfDay !== defaultTime) {
+                    this.#renderSettings.lightingTimeOfDay = defaultTime;
                     shouldApplyLighting = true;
                 }
             }
@@ -3583,8 +3690,8 @@ export default class BabylonJSController {
 
         if (typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay)) {
             const normalizedTime = clamp01(config.lightingTimeOfDay);
-            if (this.#settings.lightingTimeOfDay !== normalizedTime) {
-                this.#settings.lightingTimeOfDay = normalizedTime;
+            if (this.#renderSettings.lightingTimeOfDay !== normalizedTime) {
+                this.#renderSettings.lightingTimeOfDay = normalizedTime;
                 shouldApplyLighting = true;
             }
         }
@@ -3593,7 +3700,7 @@ export default class BabylonJSController {
             const showMenu = typeof config.showAnimationMenu === "string"
                 ? config.showAnimationMenu.toLowerCase() !== "false"
                 : Boolean(config.showAnimationMenu);
-            this.#settings.showAnimationMenu = showMenu;
+            this.#renderSettings.showAnimationMenu = showMenu;
             this.#syncAnimationControllerAfterModelLoad();
         }
 
@@ -3606,12 +3713,12 @@ export default class BabylonJSController {
             } else if (enabled === null) {
                 enabled = undefined;
             }
-            // Keep #settings in sync so getRenderSettings() always reflects the real state
+            // Keep #renderSettings in sync so getRenderSettings() always reflects the real state
             if (enabled !== undefined) {
-                this.#settings.highlightEnabled = enabled;
+                this.#renderSettings.highlightEnabled = enabled;
             }
             if (config.highlightColor !== undefined && config.highlightColor !== null) {
-                this.#settings.highlightColor = config.highlightColor;
+                this.#renderSettings.highlightColor = config.highlightColor;
             }
             this.#setHighlightConfig({
                 color: config.highlightColor ?? undefined,