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

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,15 +8,15 @@ 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 BabylonJSSelectionController from "./babylonjs-selection-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
-import { translate } from "./localization/i18n.js";
+import I18n from "./localization/i18n.js";
 import { PrefViewerStyleVariables } from "./styles.js";
-import { clamp01, lerp, getAdaptiveHardwareScalingLevel, getLightingCycleProfile } from "./render-math.js";
-import { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlassMaterial, isPrefViewerTransparentRenderOrderMaterial } from "./material-utils.js";
-
-// Re-export so existing consumers (tests, other modules) can keep importing from this file.
-export { getAdaptiveHardwareScalingLevel, getLightingCycleProfile } from "./render-math.js";
-export { markPrefViewerSimplifiedTransmissionMaterial, isPrefViewerPhysicalGlassMaterial, isPrefViewerTransparentRenderOrderMaterial } from "./material-utils.js";
+import RenderMath from "./render-math.js";
+import MaterialUtils from "./material-utils.js";
 
 /**
  * BabylonJSController coordinates the PrefViewer 3D runtime: it bootstraps Babylon.js, manages asset containers,
@@ -34,11 +34,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 +53,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 +80,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 +90,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,10 +112,18 @@ 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
     #babylonJSAnimationController = null; // AnimationController instance
+    #selectionController = null;
 
     #renderPipelines = {
         default: null,
@@ -142,12 +134,13 @@ export default class BabylonJSController {
     #handlers = {
         onAnimationGroupChanged: null,
         onKeyUp: null,
+        onPointerCancel: null,
         onPointerObservable: null,
         onResize: null,
         renderLoop: null,
     };
 
-    #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
+    #renderSettings = { ...BabylonJSController.config.render.defaultSettings };
 
     // Runtime mutable state (changes while the app is running).
     #state = {
@@ -157,6 +150,7 @@ export default class BabylonJSController {
             lastMovePickX: NaN,
             lastMovePickY: NaN,
             lastPickedMeshId: null,
+            pointerDown: null,
         },
         // Render loop state balances performance with responsiveness.
         render: {
@@ -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,53 @@ 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
+            clickMaxDistancePx: 6,
+        },
+        selection: {
+            selectableColor: [1, 1, 0],
+            selectedColor: [1, 0, 0],
+            overlayAlpha: 0.5,
+        },
+        // 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",
     };
 
     /**
@@ -301,6 +326,7 @@ export default class BabylonJSController {
      * @private
      * @param {WebGLRenderingContext} gl - WebGL context
      * @param {string} rendererName - GPU renderer name
+     * @param {boolean} [conservative=false] - Uses a cautious fallback when the GPU renderer is unknown.
      * @returns {string} Hardware tier
      */
     #detectDesktopTier(gl, rendererName, conservative = false) {
@@ -410,6 +436,7 @@ export default class BabylonJSController {
      * Applies quality settings based on detected hardware tier.
      * @private
      * @param {string} tier - Hardware tier: 'low', 'medium', or 'high'
+     * @returns {void}
      */
     #applyQualitySettings(tier) {
         const qualityPresets = {
@@ -474,7 +501,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 +525,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,
@@ -513,6 +546,16 @@ export default class BabylonJSController {
             };
         });
         this.#options = options;
+        const selectionConfig = BabylonJSController.config.selection;
+        this.#selectionController = new BabylonJSSelectionController(
+            () => this.#containers.model?.assetContainer?.meshes ?? [],
+            {
+                selectableColor: new Color3(...selectionConfig.selectableColor),
+                selectedColor: new Color3(...selectionConfig.selectedColor),
+                overlayAlpha: selectionConfig.overlayAlpha,
+                requestRender: () => this.#requestRender({ frames: 1 }),
+            },
+        );
         this.#loadStoredRenderSettings();
         this.#bindHandlers();
     }
@@ -525,6 +568,7 @@ export default class BabylonJSController {
     #bindHandlers() {
         this.#handlers.onAnimationGroupChanged = this.#onAnimationGroupChanged.bind(this);
         this.#handlers.onKeyUp = this.#onKeyUp.bind(this);
+        this.#handlers.onPointerCancel = this.#onPointerCancel.bind(this);
         this.#handlers.onPointerObservable = this.#onPointerObservable.bind(this);
         this.#handlers.onResize = this.#onResize.bind(this);
         this.#handlers.renderLoop = this.#renderLoop.bind(this);
@@ -563,18 +607,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 +641,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 +676,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,10 +731,15 @@ 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) => {
+                /**
+                 * Polls BRDF readiness until ready, disposed or the preparation timeout elapses.
+                 * @private
+                 * @returns {void}
+                 */
                 const tick = () => {
                     if (!this.#scene || !this.#engine || brdfTexture.isDisposed?.()) {
                         resolve(false);
@@ -844,7 +893,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 +901,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 +915,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 +943,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 +971,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 +1063,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 +1103,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 +1183,7 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#settings.ambientOcclusionEnabled) {
+        if (!this.#renderSettings.ambientOcclusionEnabled) {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
@@ -1221,7 +1284,7 @@ export default class BabylonJSController {
             return false;
         }
 
-        if (!this.#settings.antiAliasingEnabled) {
+        if (!this.#renderSettings.antiAliasingEnabled) {
             return false;
         }
         const supportedPipelines = pipelineManager.supportedPipelines;
@@ -1283,7 +1346,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();
@@ -1356,7 +1419,7 @@ export default class BabylonJSController {
      * Configures pipeline options for resolution, sampling, opacity, and debugging.
      * Only applies if the scene has an environment texture set.
      * @private
-     * @returns {Promise<void|boolean>} Returns false if no environment texture is set; otherwise void.
+     * @returns {Promise<boolean>} True when the IBL shadow pipeline is initialized; false when unavailable or setup fails.
      */
     async #initializeIBLShadows() {
         const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
@@ -1411,8 +1474,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,
@@ -1485,7 +1548,7 @@ export default class BabylonJSController {
      * Configures soft shadows for the built-in directional light used when no HDR environment is present.
      * Uses hardware-adaptive quality settings.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #initializeDefaultLightShadows() {
         if (!this.#dirLight) {
@@ -1493,11 +1556,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;
@@ -1511,7 +1574,7 @@ export default class BabylonJSController {
      * Keeps only the generator bound to the built-in `PrefViewerDirLight` so its shadows persist,
      * then adds generators for every directional or spot light coming from the environment asset container.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #initializeEnvironmentShadows() {
         this.#shadowGen = this.#shadowGen.filter((generator) => {
@@ -1560,7 +1623,7 @@ export default class BabylonJSController {
      * Disposes every active shadow generator plus the IBL shadow pipeline to avoid stale casters across reloads.
      * Clears the cached `#shadowGen` array so subsequent loads can rebuild fresh generators.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #disableShadows() {
         this.#shadowGen.forEach((shadowGenerator) => {
@@ -1573,19 +1636,19 @@ export default class BabylonJSController {
     /**
      * Initializes shadows for the Babylon.js scene.
      * @private
-     * @returns {void|true} Returns true if IBL shadows are initialized, otherwise void.
+     * @returns {Promise<void|false>} Resolves after shadow setup, or false when shadows are disabled.
      * @description
-     * If no environment texture is set, initializes IBL shadows.
-     * Otherwise, sets up shadow casting and receiving for all relevant meshes using the shadow generator.
+     * Uses IBL shadows only when IBL is enabled with a valid source and its shadow option is active.
+     * Otherwise initializes default-light shadows, then adds shadow support for environment lights.
      */
     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 +1666,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 +1722,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,17 +1749,17 @@ 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 profile = getLightingCycleProfile(timeOfDay);
+        const showroom = BabylonJSController.config.look?.showroom || {};
+        const timeOfDay = RenderMath.clamp01(this.#renderSettings.lightingTimeOfDay ? this.#renderSettings.lightingTimeOfDay ?? 0.5 : 0.5);
+        const profile = RenderMath.getLightingCycleProfile(timeOfDay);
         const daylight = profile.dayFactor;
         const peakLight = daylight > 0 ? Math.pow(daylight, 0.72) : 0;
         const twilight = 1 - peakLight;
 
         if (this.#scene.imageProcessingConfiguration) {
             const imageProcessing = this.#scene.imageProcessingConfiguration;
-            imageProcessing.exposure = lerp(0.78, showroom.exposure ?? 0.92, peakLight);
-            imageProcessing.contrast = lerp(0.98, showroom.contrast ?? 1.02, peakLight);
+            imageProcessing.exposure = RenderMath.lerp(0.78, showroom.exposure ?? 0.92, peakLight);
+            imageProcessing.contrast = RenderMath.lerp(0.98, showroom.contrast ?? 1.02, peakLight);
             imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
             imageProcessing.toneMappingType = showroom.toneMappingType ?? (ImageProcessingConfiguration?.TONEMAPPING_ACES ?? 0);
             imageProcessing.vignetteEnabled = false;
@@ -1703,64 +1768,64 @@ 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),
-            lerp(0.004413, bgDay[2], daylight),
+            RenderMath.lerp(0.000627, bgDay[0], daylight),
+            RenderMath.lerp(0.001089, bgDay[1], daylight),
+            RenderMath.lerp(0.004413, bgDay[2], daylight),
             1,
         );
 
         if ("environmentIntensity" in this.#scene) {
-            this.#scene.environmentIntensity = lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
+            this.#scene.environmentIntensity = RenderMath.lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
         }
 
         if (this.#hemiLight) {
             this.#hemiLight.direction = new Vector3(
-                lerp(-0.45, -0.8, peakLight),
-                lerp(0.45, 0.95, peakLight),
-                lerp(-0.75, -0.35, peakLight),
+                RenderMath.lerp(-0.45, -0.8, peakLight),
+                RenderMath.lerp(0.45, 0.95, peakLight),
+                RenderMath.lerp(-0.75, -0.35, peakLight),
             );
-            this.#hemiLight.intensity = lerp(0.18, showroom.hemiLightIntensity ?? 0.52, peakLight);
+            this.#hemiLight.intensity = RenderMath.lerp(0.18, showroom.hemiLightIntensity ?? 0.52, peakLight);
             this.#hemiLight.diffuse = new Color3(
-                lerp(0.42, 0.92, peakLight),
-                lerp(0.48, 0.96, peakLight),
-                lerp(0.62, 0.98, peakLight),
+                RenderMath.lerp(0.42, 0.92, peakLight),
+                RenderMath.lerp(0.48, 0.96, peakLight),
+                RenderMath.lerp(0.62, 0.98, peakLight),
             );
             this.#hemiLight.groundColor = new Color3(
-                lerp(0.08, 0.3, twilight),
-                lerp(0.08, 0.28, twilight),
-                lerp(0.1, 0.22, twilight),
+                RenderMath.lerp(0.08, 0.3, twilight),
+                RenderMath.lerp(0.08, 0.28, twilight),
+                RenderMath.lerp(0.1, 0.22, twilight),
             );
         }
 
         if (this.#dirLight) {
             this.#dirLight.direction = new Vector3(profile.sunDirection.x, profile.sunDirection.y, profile.sunDirection.z);
-            this.#dirLight.intensity = lerp(0.02, showroom.dirLightIntensity ?? 0.56, peakLight);
+            this.#dirLight.intensity = RenderMath.lerp(0.02, showroom.dirLightIntensity ?? 0.56, peakLight);
             this.#dirLight.diffuse = new Color3(
-                lerp(0.28, 1.0, peakLight),
-                lerp(0.3, 0.97, peakLight),
-                lerp(0.34, 0.9, peakLight),
+                RenderMath.lerp(0.28, 1.0, peakLight),
+                RenderMath.lerp(0.3, 0.97, peakLight),
+                RenderMath.lerp(0.34, 0.9, peakLight),
             );
         }
 
         if (this.#moonLight) {
             this.#moonLight.direction = new Vector3(profile.moonDirection.x, profile.moonDirection.y, profile.moonDirection.z);
-            this.#moonLight.intensity = lerp(0.44, 0.03, peakLight);
+            this.#moonLight.intensity = RenderMath.lerp(0.44, 0.03, peakLight);
             this.#moonLight.diffuse = new Color3(0.58, 0.7, 1.0);
         }
 
         if (this.#cameraLight) {
-            this.#cameraLight.intensity = lerp(0.06, showroom.cameraLightIntensity ?? 0.16, peakLight);
+            this.#cameraLight.intensity = RenderMath.lerp(0.06, showroom.cameraLightIntensity ?? 0.16, peakLight);
             this.#cameraLight.diffuse = new Color3(
-                lerp(0.35, 1.0, peakLight),
-                lerp(0.35, 0.97, peakLight),
-                lerp(0.36, 0.92, peakLight),
+                RenderMath.lerp(0.35, 1.0, peakLight),
+                RenderMath.lerp(0.35, 0.97, peakLight),
+                RenderMath.lerp(0.36, 0.92, peakLight),
             );
         }
 
         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 +1841,62 @@ export default class BabylonJSController {
         }
 
         const pixelRatio = typeof window !== "undefined" ? window.devicePixelRatio : 1;
-        const baseScaling = this.#config.quality.hardwareScaling || 1;
-        const scalingLevel = getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
+        const baseScaling = BabylonJSController.config.quality.hardwareScaling || 1;
+        const scalingLevel = RenderMath.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);
     }
 
     /**
@@ -1879,6 +1925,7 @@ export default class BabylonJSController {
         this.#state.pointerPicking.lastMovePickX = NaN;
         this.#state.pointerPicking.lastMovePickY = NaN;
         this.#state.pointerPicking.lastPickedMeshId = null;
+        this.#state.pointerPicking.pointerDown = null;
     }
 
     /**
@@ -1896,7 +1943,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;
@@ -1926,6 +1973,7 @@ export default class BabylonJSController {
     #enableInteraction() {
         if (this.#canvas) {
             this.#canvas.addEventListener("keyup", this.#handlers.onKeyUp);
+            this.#canvas.addEventListener("pointercancel", this.#handlers.onPointerCancel);
         }
         if (this.#scene) {
             this.#scene.onPointerObservable.add(this.#handlers.onPointerObservable);
@@ -1944,6 +1992,7 @@ export default class BabylonJSController {
     #disableInteraction() {
         if (this.#canvas) {
             this.#canvas.removeEventListener("keyup", this.#handlers.onKeyUp);
+            this.#canvas.removeEventListener("pointercancel", this.#handlers.onPointerCancel);
         }
         if (this.#scene !== null) {
             this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
@@ -2065,7 +2114,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 +2123,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 +2180,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 +2201,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,18 +2210,18 @@ 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 });
         }
     }
 
      /**
-     * Handles pointer up events on the Babylon.js scene.
-     * OPTIMIZATION: Tracks activity for idle mode.
-     * @private
-     * @param {PointerEvent} event - The pointer up event.
-     * @param {PickInfo} pickInfo - The result of the scene pick operation.
-     * @returns {void}
-     */
+      * Handles pointer up events on the Babylon.js scene.
+      * OPTIMIZATION: Tracks activity for idle mode.
+      * @private
+      * @param {PointerEvent} event - The pointer up event.
+      * @param {PickInfo} pickInfo - The result of the scene pick operation.
+      * @returns {void}
+      */
     #onPointerUp(event, pickInfo) {
         // OPTIMIZATION: Mark activity for idle mode
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
@@ -2208,19 +2255,62 @@ 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 });
                 }
             }
         }
     }
 
+    /**
+     * Invalidates an incomplete click gesture when the browser cancels its pointer.
+     * @private
+     * @returns {void}
+     */
+    #onPointerCancel() {
+        this.#state.pointerPicking.pointerDown = null;
+    }
+
+    /**
+     * Emits the internal 3D click contract for every model mesh crossed by the pointer ray.
+     * @private
+     * @returns {void}
+     */
+    #emitModelMeshClick() {
+        const modelMeshes = this.#containers.model?.assetContainer?.meshes ?? [];
+        const acceptedMeshes = BabylonJSSelectionController.getModelMeshSet(modelMeshes);
+        if (!this.#scene || acceptedMeshes.size === 0) {
+            return;
+        }
+        const ray = this.#scene.createPickingRay(
+            this.#scene.pointerX,
+            this.#scene.pointerY,
+            Matrix.Identity(),
+            this.#scene.activeCamera,
+            false,
+        );
+        const picks = this.#scene.multiPickWithRay(ray, (mesh) => BabylonJSSelectionController.isPickableModelMesh(mesh, acceptedMeshes)) ?? [];
+        const ids = BabylonJSSelectionController.collectPickedMeshIds(picks, modelMeshes);
+        if (ids.length === 0) {
+            return;
+        }
+        this.#getPrefViewer3DComponent();
+        const CustomEventType = this.#prefViewer3D?.ownerDocument?.defaultView?.CustomEvent ?? globalThis.CustomEvent;
+        if (this.#prefViewer3D && CustomEventType) {
+            this.#prefViewer3D.dispatchEvent(new CustomEventType("pref-viewer-3d-element-click", {
+                bubbles: true,
+                composed: true,
+                detail: { ids },
+            }));
+        }
+    }
+
     /**
      * Handles pointer events observed on the Babylon.js scene.
      * Uses pointer-move sampling to avoid running expensive `scene.pick()` on every event.
@@ -2230,6 +2320,11 @@ export default class BabylonJSController {
      */
     #onPointerObservable(info) {
         if (info.type === PointerEventTypes.POINTERMOVE) {
+            const start = this.#state.pointerPicking.pointerDown;
+            if (start && (info.event?.pointerId !== start.pointerId || (info.event?.buttons & 1) === 0
+                || Math.hypot(info.event?.clientX - start.x, info.event?.clientY - start.y) > BabylonJSController.config.pointerPicking.clickMaxDistancePx)) {
+                start.dragged = true;
+            }
             let pickInfo = null;
             let lastPickedMeshId = null;
             if (this.#shouldPickOnPointerMove()) {
@@ -2238,7 +2333,17 @@ export default class BabylonJSController {
             }
             this.#onPointerMove(info.event, pickInfo);
             this.#state.pointerPicking.lastPickedMeshId = lastPickedMeshId;
+        } else if (info.type === PointerEventTypes.POINTERDOWN) {
+            this.#state.pointerPicking.pointerDown = info.event?.button === 0 && !this.#state.pointerPicking.pointerDown
+                ? { x: info.event.clientX, y: info.event.clientY, button: info.event.button, pointerId: info.event.pointerId }
+                : null;
         } else if (info.type === PointerEventTypes.POINTERUP) {
+            const pointerDown = this.#state.pointerPicking.pointerDown;
+            this.#state.pointerPicking.pointerDown = null;
+            const pointerUp = { x: info.event?.clientX, y: info.event?.clientY, button: info.event?.button, pointerId: info.event?.pointerId };
+            if (BabylonJSSelectionController.isPrimaryClickGesture(pointerDown, pointerUp, BabylonJSController.config.pointerPicking.clickMaxDistancePx)) {
+                this.#emitModelMeshClick();
+            }
             const pickInfo = info.event?.button === 2 ? this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY) : null;
             if (pickInfo) {
                 this.#state.pointerPicking.lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
@@ -2249,6 +2354,149 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Applies a pending engine resize, cancels cube navigation and wakes rendering.
+     * @private
+     * @param {number} elapsed - Time since the previous resize, retained for diagnostics.
+     * @returns {void}
+     */
+    #applyResize(elapsed) {
+        this.#state.resize.timeoutId = null;
+        this.#state.resize.isScheduled = false;
+        if (!this.#engine) {
+            return;
+        }
+        this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
+        this.#applyShowroomCameraFraming();
+        this.#engine.resize();
+        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 });
+    }
+
+    /**
+     * Extracts the final segment of a slash-containing metadata path, returning false otherwise.
+     * @private
+     * @static
+     * @param {unknown} data - Metadata path candidate.
+     * @returns {string|false}
+     */
+    static #getNodeName(data) {
+        if (data && typeof data === "string" && data.includes("/")) {
+            data = data.slice(data.lastIndexOf("/") + 1);
+            return data;
+        }
+        return false;
+    }
+
+    /**
+     * Converts a vector to serializable coordinates, returning null for an absent value.
+     * @private
+     * @static
+     * @param {Vector3|null|undefined} value - Vector to summarize.
+     * @returns {{x:number,y:number,z:number}|null}
+     */
+    static #vectorToJSON(value) {
+        return value ? { x: value.x, y: value.y, z: value.z } : null;
+    }
+
+    /**
+     * Summarizes texture identity and readiness without including its contents.
+     * @private
+     * @static
+     * @param {object|null|undefined} texture - Babylon texture to inspect.
+     * @returns {object}
+     */
+    static #textureToJSON(texture) {
+        return {
+            name: texture?.name ?? null,
+            url: texture?.url ?? null,
+            isReady: texture?.isReady?.() ?? null,
+            hasTexture: Boolean(texture),
+            className: texture?.getClassName?.() ?? texture?.constructor?.name ?? null,
+        };
+    }
+
+    /**
+     * Summarizes material readiness, related geometry and texture diagnostics, capturing readiness errors.
+     * @private
+     * @static
+     * @param {Material} material - Material to inspect.
+     * @param {Array<object>} sceneMeshes - Current scene mesh snapshot used to resolve material owners.
+     * @returns {object}
+     */
+    static #summarizeMaterial(material, sceneMeshes) {
+        const relatedMeshes = sceneMeshes.filter((mesh) => mesh.material === material);
+        const sampleMesh = relatedMeshes[0] ?? null;
+        const activeTextures = material?.getActiveTextures?.() ?? [];
+        let isReadyWithoutMesh = null;
+        let isReadyWithMesh = null;
+        try {
+            isReadyWithoutMesh = typeof material?.isReady === "function" ? material.isReady() : null;
+        } catch (error) {
+            isReadyWithoutMesh = `error: ${error?.message ?? error}`;
+        }
+        try {
+            isReadyWithMesh = typeof material?.isReady === "function" && sampleMesh ? material.isReady(sampleMesh) : null;
+        } catch (error) {
+            isReadyWithMesh = `error: ${error?.message ?? error}`;
+        }
+
+        return {
+            name: material?.name ?? null,
+            id: material?.id ?? null,
+            className: material?.getClassName?.() ?? material?.constructor?.name ?? null,
+            isReadyWithoutMesh,
+            isReadyWithMesh,
+            relatedMeshes: relatedMeshes.length,
+            sampleMesh: sampleMesh ? {
+                name: sampleMesh.name,
+                id: sampleMesh.id,
+                enabled: sampleMesh.isEnabled?.() ?? null,
+                isVisible: sampleMesh.isVisible ?? null,
+                hasVertices: sampleMesh.getTotalVertices?.() ?? null,
+                hasIndices: sampleMesh.getTotalIndices?.() ?? null,
+            } : null,
+            textures: activeTextures.map(BabylonJSController.#textureToJSON),
+            notReadyTextures: activeTextures.filter((texture) => texture?.isReady?.() === false).map(BabylonJSController.#textureToJSON),
+            forceDepthWrite: material?.forceDepthWrite ?? null,
+            transparencyMode: material?.transparencyMode ?? null,
+            alpha: material?.alpha ?? null,
+            backFaceCulling: material?.backFaceCulling ?? null,
+            disableLighting: material?.disableLighting ?? null,
+        };
+    }
+
+    /**
+     * Summarizes container state and counts of its assets.
+     * @private
+     * @static
+     * @param {object|null|undefined} container - Viewer container and its state.
+     * @returns {object}
+     */
+    static #summarizeContainer(container) {
+        return {
+            show: container?.state?.show ?? null,
+            visible: container?.state?.visible ?? null,
+            mustBeShown: container?.state?.mustBeShown ?? null,
+            isPending: container?.state?.isPending ?? null,
+            isSuccess: container?.state?.isSuccess ?? null,
+            hasAssetContainer: Boolean(container?.assetContainer),
+            meshes: container?.assetContainer?.meshes?.length ?? 0,
+            enabledMeshes: (container?.assetContainer?.meshes ?? []).filter((mesh) => mesh.isEnabled?.() !== false && mesh.isVisible !== false).length,
+            materials: container?.assetContainer?.materials?.length ?? 0,
+            cameras: container?.assetContainer?.cameras?.map((item) => ({
+                name: item.name,
+                id: item.id,
+                className: item.getClassName?.() ?? item.constructor?.name ?? null,
+                position: BabylonJSController.#vectorToJSON(item.position),
+                target: BabylonJSController.#vectorToJSON(item.target),
+            })) ?? [],
+            animationGroups: container?.assetContainer?.animationGroups?.length ?? 0,
+        };
+    }
+
     /**
      * Handles canvas resize notifications.
      * Resizes the Babylon engine and requests a short on-demand render burst so camera-dependent
@@ -2262,23 +2510,10 @@ export default class BabylonJSController {
         }
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         const elapsed = now - this.#state.resize.lastAppliedAt;
-        const applyResize = () => {
-            this.#state.resize.timeoutId = null;
-            this.#state.resize.isScheduled = false;
-            if (!this.#engine) {
-                return;
-            }
-            this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-            console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
-            this.#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 });
-        };
 
-        if (elapsed >= this.#config.resize.throttleMs) {
-            applyResize();
+
+        if (elapsed >= BabylonJSController.config.resize.throttleMs) {
+            this.#applyResize(elapsed);
             return;
         }
 
@@ -2287,9 +2522,9 @@ 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();
+            this.#applyResize(elapsed);
         }, waitMs);
     }
 
@@ -2373,11 +2608,15 @@ 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.
+     * A missing named camera falls back to the unlocked default camera, rather than retaining an imported view.
      * @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;
@@ -2395,31 +2634,22 @@ export default class BabylonJSController {
         }
 
         if (!camera) {
-            // If a new camera (different from the default) was tried and not found, search for the current one
-            if (cameraState.isPending && cameraState.update.value !== null && cameraState.value !== null && cameraState.update.value !== cameraState.value) {
-                camera = modelContainer.assetContainer?.cameras.find((thisCamera) => thisCamera.name === cameraState.value) || environmentContainer.assetContainer?.cameras.find((thisCamera) => thisCamera.name === cameraState.value) || null;
-            }
-            if (camera) {
-                // If the current camera (different from the default) was found, use it
-                camera.metadata = { locked: cameraState.locked };
-                cameraState.setSuccess(false);
-            } else {
-                // If no camera was found, use the default camera
-                camera = this.#camera;
-                cameraState.value = null;
-                cameraState.locked = this.#camera.metadata.locked;
-                cameraState.setSuccess(false);
-            }
+            camera = this.#camera;
+            camera.metadata = { ...camera.metadata, locked: false };
+            cameraState.value = null;
+            cameraState.locked = false;
+            cameraState.setSuccess(false);
         } else {
             // If the requested camera was found, use it
             if (cameraName !== null) {
                 camera.metadata = { locked: cameraState.isPending ? cameraState.update.locked : cameraState.locked };
             } else {
-                // If it's the default camera, maintain its lock state
+                // Selecting the default camera always restores interactive navigation.
+                camera.metadata = { ...camera.metadata, locked: false };
                 if (cameraState.isPending) {
-                    cameraState.update.locked = this.#camera.metadata.locked;
+                    cameraState.update.locked = false;
                 } else {
-                    cameraState.locked = this.#camera.metadata.locked;
+                    cameraState.locked = false;
                 }
             }
             if (cameraState.isPending) {
@@ -2431,9 +2661,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;
     }
 
@@ -2441,7 +2676,7 @@ export default class BabylonJSController {
      * Applies pending image-based lighting (IBL) option updates.
      * Marks the IBL state as successful, recreates lights so the new environment takes effect, and reports whether anything changed.
      * @private
-     * @returns {boolean} True when lights were refreshed due to pending IBL changes, otherwise false.
+     * @returns {Promise<boolean>} True when lights were refreshed due to pending IBL changes, otherwise false.
      * @description
      * Delegates to `#createLights()`, which executes the full IBL URL-to-texture lifecycle:
      * `cachedUrl -> HDRCubeTexture -> #hdrTexture clone -> consumeCachedUrl(true)`.
@@ -2590,6 +2825,7 @@ export default class BabylonJSController {
      * Stops every animation group on the provided asset container to guarantee new loads start from a clean state.
      * @private
      * @param {AssetContainer} assetContainer - Container whose animation groups should be halted.
+     * @returns {void}
      */
     #assetContainer_stopAnimations(assetContainer) {
         if (!assetContainer.animationGroups || assetContainer.animationGroups.length === 0) {
@@ -2628,8 +2864,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);
         });
     }
@@ -2647,7 +2887,7 @@ export default class BabylonJSController {
         mat.subSurface.isTranslucencyEnabled = false;
         mat.alpha = Math.max(0.28, 1.0 - intensity * 0.65);
         mat.transparencyMode = PBRMaterial.PBRMATERIAL_ALPHABLEND;
-        markPrefViewerSimplifiedTransmissionMaterial(mat);
+        MaterialUtils.markPrefViewerSimplifiedTransmissionMaterial(mat);
     }
 
     /**
@@ -2685,7 +2925,7 @@ export default class BabylonJSController {
     /**
      * Stops the Babylon.js render loop for the current scene.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #stopRender() {
         this.#stopEngineRenderLoop();
@@ -2700,11 +2940,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 });
     }
 
     /**
@@ -2755,6 +2997,9 @@ export default class BabylonJSController {
                     compileMaterials: true,
                     loadAllMaterials: true,
                     loadOnlyMaterials: container.state.name === "materials",
+                    // InstancedMesh overlays render through their source mesh. Regular model
+                    // meshes keep shared materials while allowing independent semantic colors.
+                    createInstances: container.state.name !== "model",
                     extensionOptions: {
                         ExtrasAsMetadata: { enabled: true },
                     },
@@ -2776,15 +3021,19 @@ 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.#resetPointerPickingState();
         this.#detachAnimationChangedListener();
         await this.#stopRender();
 
@@ -2837,9 +3086,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) => {
@@ -2853,6 +3103,7 @@ export default class BabylonJSController {
                 this.#setMaxSimultaneousLights();
                 this.#enhanceTextureQuality();
                 this.#syncAnimationControllerAfterModelLoad();
+                this.#selectionController?.refresh();
 
                 await this.#startRender();
             });
@@ -2865,12 +3116,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();
@@ -2884,7 +3135,7 @@ export default class BabylonJSController {
      * Reinstalls every camera-sensitive post-process (default pipeline, SSAO, shadows) after loads or option changes.
      * Ensures the active camera always owns fresh pipelines so render quality remains consistent across reload cycles.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #loadCameraDependentEffects() {
         await this.#initializeVisualImprovements();
@@ -2896,7 +3147,7 @@ export default class BabylonJSController {
      * Shuts down every post-process tied to the active camera before stopping the render loop.
      * Ensures AA, SSAO, and shadow resources detach cleanly so reloads rebuild from scratch.
      * @private
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #unloadCameraDependentEffects() {
         await this.#disableVisualImprovements();
@@ -2937,19 +3188,13 @@ export default class BabylonJSController {
             return;
         }
 
-        const getNodeName = (data) => {
-            if (data && typeof data === "string" && data.includes("/")) {
-                data = data.slice(data.lastIndexOf("/") + 1);
-                return data;
-            }
-            return false;
-        };
+
 
         let applyNewTranslation = false;
         let applyOldTranslation = false;
         let undoOldTranslation = false;
-        const newTranslationNodeName = getNodeName(newMetadata?.customProperties?.innerFloorPath);
-        const oldTranslationNodeName = getNodeName(oldMetadata?.customProperties?.innerFloorPath);
+        const newTranslationNodeName = BabylonJSController.#getNodeName(newMetadata?.customProperties?.innerFloorPath);
+        const oldTranslationNodeName = BabylonJSController.#getNodeName(oldMetadata?.customProperties?.innerFloorPath);
 
         if (this.#containers.environment.state.isSuccess) {
             // If environment is being reloaded:
@@ -3062,7 +3307,7 @@ export default class BabylonJSController {
         }
 
         const locale = this.#prefViewer.culture;
-        const texts = translate("prefViewer.downloadDialog", locale ? { locale } : undefined) || {};
+        const texts = I18n.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;">
@@ -3122,10 +3367,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,26 +3430,46 @@ 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;
         }
 
         this.#disablingPromises.general = (async () => {
             this.#disableInteraction();
+            this.#selectionController?.dispose();
             this.#disposeAnimationController();
             this.#disposeGLTFResolver();
             try {
@@ -3205,6 +3494,42 @@ 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();
+    }
+
+    /**
+     * Applies the host-owned semantic selection state to the current model meshes.
+     * @public
+     * @param {object} state - Canonical PrefViewer selection snapshot.
+     * @returns {void}
+     */
+    applySelectionState(state = {}) {
+        this.#selectionController?.applySelectionState(state);
+    }
+
     /**
      * Downloads the current scene, model, or environment as a GLB file.
      * @public
@@ -3314,7 +3639,7 @@ export default class BabylonJSController {
      * @returns {{antiAliasingEnabled:boolean, ambientOcclusionEnabled:boolean, iblEnabled:boolean, shadowsEnabled:boolean}}
      */
     getRenderSettings() {
-        return { ...this.#settings };
+        return { ...this.#renderSettings };
     }
 
     /**
@@ -3324,7 +3649,7 @@ export default class BabylonJSController {
      * @returns {object} Debug information for canvas, engine, scene, containers, render loop and settings.
      */
     getDebugInfo() {
-        const vectorToJSON = (value) => value ? { x: value.x, y: value.y, z: value.z } : null;
+
         const rect = this.#canvas?.getBoundingClientRect?.();
         const camera = this.#scene?.activeCamera ?? null;
         const sceneMeshes = this.#scene?.meshes ?? [];
@@ -3334,62 +3659,16 @@ export default class BabylonJSController {
         const modelAssetContainer = this.#containers?.model?.assetContainer ?? null;
         const modelMeshes = modelAssetContainer?.meshes ?? [];
         const enabledModelMeshes = modelMeshes.filter((mesh) => mesh.isEnabled?.() !== false && mesh.isVisible !== false);
-        const textureToJSON = (texture) => ({
-            name: texture?.name ?? null,
-            url: texture?.url ?? null,
-            isReady: texture?.isReady?.() ?? null,
-            hasTexture: Boolean(texture),
-            className: texture?.getClassName?.() ?? texture?.constructor?.name ?? null,
-        });
-        const summarizeMaterial = (material) => {
-            const relatedMeshes = sceneMeshes.filter((mesh) => mesh.material === material);
-            const sampleMesh = relatedMeshes[0] ?? null;
-            const activeTextures = material?.getActiveTextures?.() ?? [];
-            let isReadyWithoutMesh = null;
-            let isReadyWithMesh = null;
-            try {
-                isReadyWithoutMesh = typeof material?.isReady === "function" ? material.isReady() : null;
-            } catch (error) {
-                isReadyWithoutMesh = `error: ${error?.message ?? error}`;
-            }
-            try {
-                isReadyWithMesh = typeof material?.isReady === "function" && sampleMesh ? material.isReady(sampleMesh) : null;
-            } catch (error) {
-                isReadyWithMesh = `error: ${error?.message ?? error}`;
-            }
 
-            return {
-                name: material?.name ?? null,
-                id: material?.id ?? null,
-                className: material?.getClassName?.() ?? material?.constructor?.name ?? null,
-                isReadyWithoutMesh,
-                isReadyWithMesh,
-                relatedMeshes: relatedMeshes.length,
-                sampleMesh: sampleMesh ? {
-                    name: sampleMesh.name,
-                    id: sampleMesh.id,
-                    enabled: sampleMesh.isEnabled?.() ?? null,
-                    isVisible: sampleMesh.isVisible ?? null,
-                    hasVertices: sampleMesh.getTotalVertices?.() ?? null,
-                    hasIndices: sampleMesh.getTotalIndices?.() ?? null,
-                } : null,
-                textures: activeTextures.map(textureToJSON),
-                notReadyTextures: activeTextures.filter((texture) => texture?.isReady?.() === false).map(textureToJSON),
-                forceDepthWrite: material?.forceDepthWrite ?? null,
-                transparencyMode: material?.transparencyMode ?? null,
-                alpha: material?.alpha ?? null,
-                backFaceCulling: material?.backFaceCulling ?? null,
-                disableLighting: material?.disableLighting ?? null,
-            };
-        };
-        const materialDiagnostics = sceneMaterials.slice(0, 25).map(summarizeMaterial);
+
+        const materialDiagnostics = sceneMaterials.slice(0, 25).map((material) => BabylonJSController.#summarizeMaterial(material, sceneMeshes));
         const notReadyMaterials = materialDiagnostics
             .filter((material) => material.isReadyWithoutMesh === false || material.isReadyWithMesh === false || material.notReadyTextures.length > 0)
             .slice(0, 25);
         const notReadyTextures = sceneTextures
             .filter((texture) => texture?.isReady?.() === false)
             .slice(0, 25)
-            .map(textureToJSON);
+            .map(BabylonJSController.#textureToJSON);
         const notReadyMeshes = sceneMeshes
             .filter((mesh) => typeof mesh.isReady === "function" && !mesh.isReady())
             .slice(0, 25)
@@ -3403,25 +3682,7 @@ export default class BabylonJSController {
         const modelBounds = enabledModelMeshes.length && this.#scene?.getWorldExtends
             ? this.#scene.getWorldExtends((mesh) => enabledModelMeshes.includes(mesh))
             : null;
-        const summarizeContainer = (container) => ({
-            show: container?.state?.show ?? null,
-            visible: container?.state?.visible ?? null,
-            mustBeShown: container?.state?.mustBeShown ?? null,
-            isPending: container?.state?.isPending ?? null,
-            isSuccess: container?.state?.isSuccess ?? null,
-            hasAssetContainer: Boolean(container?.assetContainer),
-            meshes: container?.assetContainer?.meshes?.length ?? 0,
-            enabledMeshes: (container?.assetContainer?.meshes ?? []).filter((mesh) => mesh.isEnabled?.() !== false && mesh.isVisible !== false).length,
-            materials: container?.assetContainer?.materials?.length ?? 0,
-            cameras: container?.assetContainer?.cameras?.map((item) => ({
-                name: item.name,
-                id: item.id,
-                className: item.getClassName?.() ?? item.constructor?.name ?? null,
-                position: vectorToJSON(item.position),
-                target: vectorToJSON(item.target),
-            })) ?? [],
-            animationGroups: container?.assetContainer?.animationGroups?.length ?? 0,
-        });
+
 
         return {
             canvas: {
@@ -3453,8 +3714,8 @@ export default class BabylonJSController {
                     name: camera.name,
                     id: camera.id,
                     className: camera.getClassName?.() ?? camera.constructor?.name ?? null,
-                    position: vectorToJSON(camera.position),
-                    target: vectorToJSON(camera.target),
+                    position: BabylonJSController.#vectorToJSON(camera.position),
+                    target: BabylonJSController.#vectorToJSON(camera.target),
                     radius: camera.radius ?? null,
                     alpha: camera.alpha ?? null,
                     beta: camera.beta ?? null,
@@ -3475,16 +3736,16 @@ export default class BabylonJSController {
                 notReadyMeshes,
             },
             containers: {
-                model: summarizeContainer(this.#containers.model),
-                environment: summarizeContainer(this.#containers.environment),
-                materials: summarizeContainer(this.#containers.materials),
+                model: BabylonJSController.#summarizeContainer(this.#containers.model),
+                environment: BabylonJSController.#summarizeContainer(this.#containers.environment),
+                materials: BabylonJSController.#summarizeContainer(this.#containers.materials),
             },
             modelBounds: modelBounds ? {
-                min: vectorToJSON(modelBounds.min),
-                max: vectorToJSON(modelBounds.max),
+                min: BabylonJSController.#vectorToJSON(modelBounds.min),
+                max: BabylonJSController.#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),
@@ -3497,7 +3758,8 @@ export default class BabylonJSController {
      * 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.
+     * @param {boolean} [force=false] - Bypasses asset cache metadata checks when reloading.
+     * @returns {Promise<{success:boolean,error:*}>} Result of loading and preparing the asset containers.
      */
     async load(force = false) {
         return await this.#loadContainers(force);
@@ -3533,7 +3795,7 @@ export default class BabylonJSController {
      * Reapplies image-based lighting configuration (HDR URL, intensity, shadow mode).
      * Stops rendering, pushes pending IBL state into the scene, rebuilds camera-dependent effects, then resumes rendering.
      * @public
-     * @returns {boolean} True if IBL options were set successfully, false otherwise.
+     * @returns {Promise<boolean>} True if IBL options were set successfully, false otherwise.
      */
     async setIBLOptions() {
         await this.#stopRender();
@@ -3548,7 +3810,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,25 +3828,25 @@ 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;
                 }
             }
         }
 
         if (typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay)) {
-            const normalizedTime = clamp01(config.lightingTimeOfDay);
-            if (this.#settings.lightingTimeOfDay !== normalizedTime) {
-                this.#settings.lightingTimeOfDay = normalizedTime;
+            const normalizedTime = RenderMath.clamp01(config.lightingTimeOfDay);
+            if (this.#renderSettings.lightingTimeOfDay !== normalizedTime) {
+                this.#renderSettings.lightingTimeOfDay = normalizedTime;
                 shouldApplyLighting = true;
             }
         }
@@ -3593,7 +3855,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 +3868,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,