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

package/src/babylonjs-controller.js

@@ -11,15 +11,12 @@ 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,
@@ -126,6 +123,7 @@ export default class BabylonJSController {
 
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
+    #selectionController = null;
 
     #renderPipelines = {
         default: null,
@@ -136,6 +134,7 @@ export default class BabylonJSController {
     #handlers = {
         onAnimationGroupChanged: null,
         onKeyUp: null,
+        onPointerCancel: null,
         onPointerObservable: null,
         onResize: null,
         renderLoop: null,
@@ -151,6 +150,7 @@ export default class BabylonJSController {
             lastMovePickX: NaN,
             lastMovePickY: NaN,
             lastPickedMeshId: null,
+            pointerDown: null,
         },
         // Render loop state balances performance with responsiveness.
         render: {
@@ -219,6 +219,12 @@ export default class BabylonJSController {
         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: {
@@ -320,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) {
@@ -429,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 = {
@@ -538,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();
     }
@@ -550,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);
@@ -716,6 +735,11 @@ export default class BabylonJSController {
 
         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);
@@ -1395,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;
@@ -1524,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) {
@@ -1550,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) => {
@@ -1599,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) => {
@@ -1612,10 +1636,10 @@ 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.#renderSettings.shadowsEnabled) {
@@ -1726,16 +1750,16 @@ export default class BabylonJSController {
         }
 
         const showroom = BabylonJSController.config.look?.showroom || {};
-        const timeOfDay = clamp01(this.#renderSettings.lightingTimeOfDay ? this.#renderSettings.lightingTimeOfDay ?? 0.5 : 0.5);
-        const profile = getLightingCycleProfile(timeOfDay);
+        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;
@@ -1746,57 +1770,57 @@ export default class BabylonJSController {
         // HDR off-white. Both are linear already, so no toLinearSpace() on either.
         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),
             );
         }
 
@@ -1818,7 +1842,7 @@ export default class BabylonJSController {
 
         const pixelRatio = typeof window !== "undefined" ? window.devicePixelRatio : 1;
         const baseScaling = BabylonJSController.config.quality.hardwareScaling || 1;
-        const scalingLevel = getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
+        const scalingLevel = RenderMath.getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
         this.#engine.setHardwareScalingLevel(scalingLevel);
     }
 
@@ -1901,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;
     }
 
     /**
@@ -1948,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);
@@ -1966,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);
@@ -2188,13 +2215,13 @@ export default class BabylonJSController {
     }
 
      /**
-     * 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();
@@ -2241,6 +2268,49 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * 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.
@@ -2250,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()) {
@@ -2258,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;
@@ -2269,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
@@ -2282,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.#renderSettings.antiAliasingEnabled || this.#renderSettings.ambientOcclusionEnabled || this.#renderSettings.iblEnabled || this.#renderSettings.shadowsEnabled;
-            const frames = needsEnhancedBurst ? BabylonJSController.config.render.burstFramesEnhanced : BabylonJSController.config.render.burstFramesBase;
-            this.#requestRender({ frames, continuousMs: BabylonJSController.config.render.interactionMs });
-        };
+
 
         if (elapsed >= BabylonJSController.config.resize.throttleMs) {
-            applyResize();
+            this.#applyResize(elapsed);
             return;
         }
 
@@ -2309,7 +2524,7 @@ export default class BabylonJSController {
         this.#state.resize.isScheduled = true;
         const waitMs = Math.max(0, BabylonJSController.config.resize.throttleMs - elapsed);
         this.#state.resize.timeoutId = setTimeout(() => {
-            applyResize();
+            this.#applyResize(elapsed);
         }, waitMs);
     }
 
@@ -2396,6 +2611,7 @@ export default class BabylonJSController {
      * 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.
      */
@@ -2418,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) {
@@ -2469,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)`.
@@ -2618,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) {
@@ -2679,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);
     }
 
     /**
@@ -2717,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();
@@ -2789,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 },
                     },
@@ -2822,6 +3033,7 @@ export default class BabylonJSController {
      */
     async #loadContainers(force = false) {
         this.#viewCube?.cancel();
+        this.#resetPointerPickingState();
         this.#detachAnimationChangedListener();
         await this.#stopRender();
 
@@ -2891,6 +3103,7 @@ export default class BabylonJSController {
                 this.#setMaxSimultaneousLights();
                 this.#enhanceTextureQuality();
                 this.#syncAnimationControllerAfterModelLoad();
+                this.#selectionController?.refresh();
 
                 await this.#startRender();
             });
@@ -2922,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();
@@ -2934,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();
@@ -2975,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:
@@ -3100,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;">
@@ -3262,6 +3469,7 @@ export default class BabylonJSController {
 
         this.#disablingPromises.general = (async () => {
             this.#disableInteraction();
+            this.#selectionController?.dispose();
             this.#disposeAnimationController();
             this.#disposeGLTFResolver();
             try {
@@ -3312,6 +3520,16 @@ export default class BabylonJSController {
         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
@@ -3431,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 ?? [];
@@ -3441,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)
@@ -3510,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: {
@@ -3560,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,
@@ -3582,13 +3736,13 @@ 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.#renderSettings },
@@ -3604,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);
@@ -3640,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();
@@ -3689,7 +3844,7 @@ export default class BabylonJSController {
         }
 
         if (typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay)) {
-            const normalizedTime = clamp01(config.lightingTimeOfDay);
+            const normalizedTime = RenderMath.clamp01(config.lightingTimeOfDay);
             if (this.#renderSettings.lightingTimeOfDay !== normalizedTime) {
                 this.#renderSettings.lightingTimeOfDay = normalizedTime;
                 shouldApplyLighting = true;