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

package/src/babylonjs-controller.js

@@ -165,6 +165,8 @@ export default class BabylonJSController {
     // References to parent custom elements
     #prefViewer3D = undefined;
     #prefViewer = undefined;
+    #modelFirstPaintedEmitted = false;
+    #modelFirstPaintedLoadToken = 0;
 
     // Babylon.js core objects
     #engine = null;
@@ -174,6 +176,7 @@ export default class BabylonJSController {
     #dirLight = null;
     #moonLight = null;
     #cameraLight = null;
+    #debugCameraFrameInfo = null;
     #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
@@ -185,6 +188,11 @@ export default class BabylonJSController {
 
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
+    #loadingInProgress = false; // blocks #requestRender while assets are loading to prevent WebGL errors from rendering with disposed shaders
+    #isLoadingModelIndependent = false;       // guards against concurrent independent model loads
+    #isLoadingEnvironmentIndependent = false; // guards against concurrent independent environment loads
+    #isLoadingMaterialsIndependent = false;   // guards against concurrent independent materials loads
+    #startRenderInProgress = false; // true while #startRender() is running (after #loadingInProgress clears)
 
     #renderPipelines = {
         default: null,
@@ -748,8 +756,8 @@ export default class BabylonJSController {
      * @param {number} [options.continuousMs=0] - Milliseconds to keep continuous rendering active.
      * @returns {boolean} True when the request was accepted, false when scene/engine are unavailable.
      */
-    #requestRender({ frames = 1, continuousMs = 0 } = {}) {
-        if (!this.#scene || !this.#engine) {
+    #requestRender({ frames = 1, continuousMs = 0, force = false } = {}) {
+        if (!this.#scene || !this.#engine || (this.#loadingInProgress && !force)) {
             return false;
         }
 
@@ -1112,6 +1120,11 @@ export default class BabylonJSController {
 
         const pipelineName = "PrefViewerSSAORenderingPipeline";
 
+        // Skip recreation if already alive — same reason as DefaultRenderingPipeline guard
+        if (this.#renderPipelines.ssao && supportedPipelines.find((p) => p.name === pipelineName)) {
+            return true;
+        }
+
         const ssaoRatio = {
             ssaoRatio: 0.5,
             combineRatio: 1.0,
@@ -1213,6 +1226,21 @@ export default class BabylonJSController {
 
         const pipelineName = "PrefViewerDefaultRenderingPipeline";
 
+        // Skip recreation if the pipeline is already alive — creating a new DefaultRenderingPipeline
+        // while one exists disposes the underlying GeometryBufferRenderer, deleting GL programs that
+        // subMeshes still reference, causing useProgram:deleted errors on the next render frame.
+        if (this.#renderPipelines.default && supportedPipelines.find((p) => p.name === pipelineName)) {
+            return true;
+        }
+
+        // Purge stale effect cache before creating a new pipeline. pipeline.dispose() calls
+        // gl.deleteProgram() per post-process but leaves entries in Engine._compiledEffects.
+        // A new DefaultRenderingPipeline with the same shader key gets a cache hit and receives
+        // the deleted program → useProgram:deleted on the first render frame.
+        // Safe here because #startRender always stops the loop before reaching this point.
+        this.#scene.getEngine().releaseEffects?.();
+        this.#scene.getEngine().releaseComputeEffects?.();
+
         let defaultPipeline = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
 
         if (!defaultPipeline) {
@@ -1390,6 +1418,11 @@ export default class BabylonJSController {
 
         const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
+        // Skip recreation if already alive — same reason as DefaultRenderingPipeline guard
+        if (this.#renderPipelines.iblShadows && supportedPipelines.find((p) => p.name === pipelineName)) {
+            return true;
+        }
+
         // Use hardware-adaptive quality settings
         const pipelineOptions = {
             resolutionExp: this.#config.quality.iblShadowResolution, // Adaptive: 0=1024, 1=2048, 2=4096
@@ -1641,7 +1674,7 @@ export default class BabylonJSController {
         const showroom = this.#config.look?.showroom || {};
         const imageProcessing = this.#scene.imageProcessingConfiguration;
 
-        this.#scene.clearColor = new Color4(0.98, 0.98, 0.98, 1).toLinearSpace();
+        this.#scene.clearColor = new Color4(1, 1, 1, 1).toLinearSpace();
         imageProcessing.exposure = showroom.exposure ?? 0.95;
         imageProcessing.contrast = showroom.contrast ?? 1.08;
         imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
@@ -1681,12 +1714,7 @@ export default class BabylonJSController {
             imageProcessing.colorCurvesEnabled = false;
         }
 
-        this.#scene.clearColor = new Color4(
-            lerp(0.035, 0.98, daylight),
-            lerp(0.045, 0.98, daylight),
-            lerp(0.085, 0.98, daylight),
-            1,
-        ).toLinearSpace();
+        this.#scene.clearColor = new Color4(1, 1, 1, 1).toLinearSpace();
 
         if ("environmentIntensity" in this.#scene) {
             this.#scene.environmentIntensity = lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
@@ -2175,6 +2203,10 @@ export default class BabylonJSController {
             }
             this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
             console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
+            // Stop the loop before resize: engine.resize() rebuilds DefaultRenderingPipeline
+            // via onResizeObservable, which disposes GL programs. If the loop is running,
+            // the next frame would call useProgram on a deleted program → INVALID_OPERATION.
+            this.#stopEngineRenderLoop();
             this.#applyShowroomCameraFraming();
             this.#engine.resize();
             const needsEnhancedBurst = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled || this.#settings.shadowsEnabled;
@@ -2217,7 +2249,7 @@ export default class BabylonJSController {
      * @param {MaterialData} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
      * @returns {boolean} True if any mesh material was set, false otherwise.
      */
-    #setOptionsMaterial(optionMaterial) {
+    #setOptionsMaterial(optionMaterial, force = false) {
         if (!optionMaterial || !(optionMaterial.value || (optionMaterial.isPending && optionMaterial.update.value)) || !(optionMaterial.nodePrefixes.length || optionMaterial.nodeNames.length)) {
             return false;
         }
@@ -2235,7 +2267,7 @@ export default class BabylonJSController {
             if (container.state.name === "materials") {
                 return;
             }
-            if (container.assetContainer && (container.state.isPending || materialContainer.state.isPending || optionMaterial.isPending)) {
+            if (container.assetContainer && (force || container.state.isPending || materialContainer.state.isPending || optionMaterial.isPending)) {
                 assetContainersToProcess.push(container.assetContainer);
             }
         });
@@ -2268,10 +2300,10 @@ export default class BabylonJSController {
      * @private
      * @returns {boolean} True if any material option was set, false otherwise.
      */
-    #setOptions_Materials() {
+    #setOptions_Materials(force = false) {
         let someSetted = false;
         Object.values(this.#options.materials).forEach((material) => {
-            let settedMaterial = this.#setOptionsMaterial(material);
+            let settedMaterial = this.#setOptionsMaterial(material, force);
             someSetted = someSetted || settedMaterial;
         });
         return someSetted;
@@ -2380,7 +2412,9 @@ export default class BabylonJSController {
             prefViewer3D = host?.nodeName === "PREF-VIEWER-3D" ? host : undefined;
         }
 
-        this.#prefViewer3D = prefViewer3D;
+        if (prefViewer3D) {
+            this.#prefViewer3D = prefViewer3D;
+        }
     }
 
     /**
@@ -2395,7 +2429,6 @@ export default class BabylonJSController {
 
         this.#getPrefViewer3DComponent();
         if (this.#prefViewer3D === undefined) {
-            this.#prefViewer = undefined;
             return;
         }
 
@@ -2405,7 +2438,9 @@ export default class BabylonJSController {
             prefViewer = host?.nodeName === "PREF-VIEWER" ? host : undefined;
         }
 
-        this.#prefViewer = prefViewer;
+        if (prefViewer) {
+            this.#prefViewer = prefViewer;
+        }
     }
 
     /**
@@ -2419,13 +2454,94 @@ export default class BabylonJSController {
         // Cache references to parent custom elements
         this.#getPrefViewer3DComponent();
         this.#getPrefViewerComponent();
+        const syncVisibility = (component, fallbackAttr) => {
+            if (!component) {
+                return;
+            }
+            if (typeof component.syncVisibility === "function") {
+                component.syncVisibility(name, isVisible);
+                return;
+            }
+            component.setAttribute(fallbackAttr, isVisible ? "true" : "false");
+        };
         if (name === "model") {
-            this.#prefViewer3D?.setAttribute("show-model", isVisible ? "true" : "false");
-            this.#prefViewer?.setAttribute("show-model", isVisible ? "true" : "false");
+            syncVisibility(this.#prefViewer3D, "show-model");
+            syncVisibility(this.#prefViewer, "show-model");
         } else if (name === "environment") {
-            this.#prefViewer3D?.setAttribute("show-scene", isVisible ? "true" : "false");
-            this.#prefViewer?.setAttribute("show-scene", isVisible ? "true" : "false");
+            syncVisibility(this.#prefViewer3D, "show-scene");
+            syncVisibility(this.#prefViewer, "show-scene");
+        }
+    }
+
+    /**
+     * Dispatches a "model-first-painted" event once the model-only preview has had a chance to render a frame.
+     * @private
+     * @param {object} [detail] - Optional metadata describing the paint gate.
+     * @returns {void}
+     */
+    #emitModelFirstPainted(detail = {}) {
+        this.#getPrefViewer3DComponent();
+        this.#getPrefViewerComponent();
+        const target = this.#prefViewer || this.#prefViewer3D || this.#canvas;
+        if (!target) {
+            return;
         }
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail,
+        };
+        target.dispatchEvent(new CustomEvent("model-first-painted", customEventOptions));
+    }
+
+    /**
+     * Dispatches a granular 3D load phase event so the ecommerce trace UI can measure tail phases.
+     * @private
+     * @param {string} phase - Phase event name.
+     * @param {object} [detail] - Optional phase metadata.
+     * @returns {void}
+     */
+    #emitSceneLoadPhase(phase, detail = {}) {
+        this.#getPrefViewer3DComponent();
+        this.#getPrefViewerComponent();
+        const target = this.#prefViewer || this.#prefViewer3D || this.#canvas;
+        if (!target) {
+            return;
+        }
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail,
+        };
+        target.dispatchEvent(new CustomEvent(phase, customEventOptions));
+    }
+
+    /**
+     * Waits for one or more animation frames so the browser can paint the current model-only state.
+     * @private
+     * @param {number} [frameCount=2] - Number of animation frames to wait.
+     * @returns {Promise<void>}
+     */
+    async #waitForPaint(frameCount = 2) {
+        if (typeof requestAnimationFrame !== "function") {
+            return;
+        }
+
+        const totalFrames = Math.max(1, frameCount);
+        await new Promise((resolve) => {
+            const step = (remaining) => {
+                if (remaining <= 0) {
+                    resolve();
+                    return;
+                }
+                requestAnimationFrame(() => step(remaining - 1));
+            };
+            requestAnimationFrame(() => step(totalFrames - 1));
+        });
     }
 
     /**
@@ -2473,7 +2589,7 @@ export default class BabylonJSController {
      * @param {AssetContainer} newAssetContainer - The new asset container to add to the scene.
      * @returns {boolean} True if the container was replaced and added, false otherwise.
      */
-    #replaceContainer(container, newAssetContainer) {
+    #replaceContainer(container, newAssetContainer, { releaseEffects = true } = {}) {
         if (container.assetContainer) {
             this.#removeContainer(container, false);
             container.assetContainer.dispose();
@@ -2485,8 +2601,13 @@ export default class BabylonJSController {
             newAssetContainer?.dispose();
             return false;
         }
-        this.#scene.getEngine().releaseEffects();
-        this.#scene.getEngine().releaseComputeEffects();
+        // Skip releaseEffects when the render loop is active: deleting GL programs while frames
+        // are being produced causes useProgram:deleted errors. Also skipped when the caller
+        // explicitly passes releaseEffects:false (e.g. loadContainerIndependent).
+        if (releaseEffects && !this.#state.render.isLoopRunning) {
+            this.#scene.getEngine().releaseEffects();
+            this.#scene.getEngine().releaseComputeEffects();
+        }
 
         container.assetContainer = newAssetContainer;
         return this.#addContainer(container, false);
@@ -2548,12 +2669,209 @@ export default class BabylonJSController {
         if (!this.#containers.model.assetContainer || !this.#containers.model.state.isVisible) {
             return false;
         }
-        show = show !== undefined ? show : this.#containers.environment.state.isVisible;
+        // In model-only previews, or while the environment is still loading, keep wall/floor meshes visible.
+        // Only defer to the environment's visibility after it has fully loaded.
+        show = show !== undefined
+            ? show
+            : (this.#containers.environment.state.isSuccess
+                ? this.#containers.environment.state.isVisible
+                : true);
         const nodePrefixes = Object.values(this.#options.materials).flatMap((material) => material.nodePrefixes);
         const nodeNames = Object.values(this.#options.materials).flatMap((material) => material.nodeNames);
         this.#containers.model.assetContainer.meshes.filter((meshToFilter) => nodePrefixes.some((prefix) => meshToFilter.name.startsWith(prefix)) || nodeNames.includes(meshToFilter.name)).forEach((mesh) => mesh.setEnabled(show));
     }
 
+    /**
+     * Frames the active ArcRotateCamera around the visible model when no environment scene is loaded.
+     * @private
+     * @returns {boolean} True if the camera was adjusted, otherwise false.
+     */
+    #frameCameraToModel({ allowWhenEnvironmentVisible = false } = {}) {
+        const camera = this.#scene?.activeCamera instanceof ArcRotateCamera
+            ? this.#scene.activeCamera
+            : this.#camera;
+        const modelContainer = this.#containers.model;
+        const inspect = {
+            cameraType: camera?.getClassName?.() ?? camera?.constructor?.name ?? null,
+            hasModelContainer: !!modelContainer.assetContainer,
+            modelVisible: modelContainer.state.isVisible,
+            envHasContainer: !!this.#containers.environment.assetContainer,
+            envVisible: this.#containers.environment.state.isVisible,
+            meshCount: modelContainer.assetContainer?.meshes?.length ?? 0,
+        };
+        this.#debugCameraFrameInfo = { phase: "inspect", ...inspect };
+        console.log("[viewer] frameCameraToModel inspect", inspect);
+        if (!(camera instanceof ArcRotateCamera) || !modelContainer.assetContainer || !modelContainer.state.isVisible) {
+            this.#debugCameraFrameInfo = {
+                phase: "skipped",
+                reason: !(camera instanceof ArcRotateCamera)
+                    ? "no-arcrotate-camera"
+                    : !modelContainer.assetContainer
+                        ? "no-model"
+                        : !modelContainer.state.isVisible
+                            ? "model-hidden"
+                            : "unknown",
+                ...inspect,
+            };
+            return false;
+        }
+        if (!allowWhenEnvironmentVisible && this.#containers.environment.assetContainer && this.#containers.environment.state.isVisible) {
+            this.#debugCameraFrameInfo = {
+                phase: "skipped",
+                reason: "environment-visible",
+                ...inspect,
+            };
+            return false;
+        }
+
+        let min = null;
+        let max = null;
+        modelContainer.assetContainer.meshes.forEach((mesh) => {
+            if (!mesh?.getTotalVertices?.() || mesh.getTotalVertices() <= 0) {
+                return;
+            }
+            mesh.computeWorldMatrix?.(true);
+            const boundingBox = mesh.getBoundingInfo?.()?.boundingBox;
+            if (!boundingBox) {
+                return;
+            }
+            const minimum = boundingBox.minimumWorld;
+            const maximum = boundingBox.maximumWorld;
+            if (!minimum || !maximum) {
+                return;
+            }
+            min = min
+                ? new Vector3(Math.min(min.x, minimum.x), Math.min(min.y, minimum.y), Math.min(min.z, minimum.z))
+                : minimum.clone();
+            max = max
+                ? new Vector3(Math.max(max.x, maximum.x), Math.max(max.y, maximum.y), Math.max(max.z, maximum.z))
+                : maximum.clone();
+        });
+
+        if (!min || !max) {
+            const skipped = {
+                hasCamera: camera instanceof ArcRotateCamera,
+                hasModel: !!modelContainer.assetContainer,
+                modelVisible: modelContainer.state.isVisible,
+                environmentVisible: this.#containers.environment.state.isVisible,
+            };
+            this.#debugCameraFrameInfo = {
+                phase: "skipped",
+                reason: "no-bounds",
+                ...inspect,
+                ...skipped,
+            };
+            console.log("[viewer] frameCameraToModel skipped (no bounds)", skipped);
+            return false;
+        }
+
+        const size = max.subtract(min);
+        const largestDimension = Math.max(size.x, size.y, size.z);
+        if (!Number.isFinite(largestDimension) || largestDimension <= 0) {
+            return false;
+        }
+
+        const center = min.add(max).scale(0.5);
+        camera.setTarget(center);
+        const radiusMultiplier = allowWhenEnvironmentVisible ? 1.7 : 1.4;
+        camera.radius = Math.min(
+            Math.max(largestDimension * radiusMultiplier, camera.lowerRadiusLimit ?? largestDimension * radiusMultiplier),
+            camera.upperRadiusLimit ?? largestDimension * radiusMultiplier,
+        );
+        // Keep the initial model-only view aligned to the showroom's frontal composition.
+        // This preserves the user's camera intent once the scene becomes visible, but gives
+        // the standalone model a consistent front-facing presentation.
+        // Rotate the front-facing composition 180° while keeping the same framing/radius.
+        camera.alpha = Math.PI;
+        camera.beta = Math.PI * 0.47;
+        console.log("[viewer] frameCameraToModel applied", {
+            center,
+            size,
+            radius: camera.radius,
+        });
+        this.#debugCameraFrameInfo = {
+            phase: "applied",
+            ...inspect,
+            center: { x: center.x, y: center.y, z: center.z },
+            size: { x: size.x, y: size.y, z: size.z },
+            radius: camera.radius,
+            cameraTarget: camera.target ? { x: camera.target.x, y: camera.target.y, z: camera.target.z } : null,
+            cameraPosition: camera.position ? { x: camera.position.x, y: camera.position.y, z: camera.position.z } : null,
+            cameraLocked: !!camera.metadata?.locked,
+        };
+        return true;
+    }
+
+    /**
+     * Public wrapper to force the active camera to frame the visible model.
+     * @public
+     * @returns {boolean}
+     */
+    focusModel() {
+        return this.#frameCameraToModel();
+    }
+
+    /**
+     * Returns a compact snapshot of the current debug-relevant 3D state.
+     * @public
+     * @returns {object}
+     */
+    getDebugState() {
+        const activeCamera = this.#scene?.activeCamera ?? this.#camera ?? null;
+        const modelMeshes = this.#containers.model?.assetContainer?.meshes ?? [];
+        let boundsMin = null;
+        let boundsMax = null;
+        for (const mesh of modelMeshes) {
+            if (!mesh?.getTotalVertices?.() || mesh.getTotalVertices() <= 0) continue;
+            mesh.computeWorldMatrix?.(true);
+            const boundingBox = mesh.getBoundingInfo?.()?.boundingBox;
+            if (!boundingBox?.minimumWorld || !boundingBox?.maximumWorld) continue;
+            const minimum = boundingBox.minimumWorld;
+            const maximum = boundingBox.maximumWorld;
+            boundsMin = boundsMin
+                ? { x: Math.min(boundsMin.x, minimum.x), y: Math.min(boundsMin.y, minimum.y), z: Math.min(boundsMin.z, minimum.z) }
+                : { x: minimum.x, y: minimum.y, z: minimum.z };
+            boundsMax = boundsMax
+                ? { x: Math.max(boundsMax.x, maximum.x), y: Math.max(boundsMax.y, maximum.y), z: Math.max(boundsMax.z, maximum.z) }
+                : { x: maximum.x, y: maximum.y, z: maximum.z };
+        }
+        const modelBounds = boundsMin && boundsMax ? {
+            min: boundsMin,
+            max: boundsMax,
+            center: {
+                x: (boundsMin.x + boundsMax.x) / 2,
+                y: (boundsMin.y + boundsMax.y) / 2,
+                z: (boundsMin.z + boundsMax.z) / 2,
+            },
+            size: {
+                x: boundsMax.x - boundsMin.x,
+                y: boundsMax.y - boundsMin.y,
+                z: boundsMax.z - boundsMin.z,
+            },
+        } : null;
+        return {
+            camera: activeCamera ? {
+                className: activeCamera.getClassName?.() ?? activeCamera.constructor?.name ?? null,
+                position: activeCamera.position ? { x: activeCamera.position.x, y: activeCamera.position.y, z: activeCamera.position.z } : null,
+                target: activeCamera.target ? { x: activeCamera.target.x, y: activeCamera.target.y, z: activeCamera.target.z } : null,
+                radius: typeof activeCamera.radius === "number" ? activeCamera.radius : null,
+                locked: !!activeCamera.metadata?.locked,
+            } : null,
+            model: {
+                visible: !!this.#containers.model?.state?.isVisible,
+                hasContainer: !!this.#containers.model?.assetContainer,
+                meshCount: this.#containers.model?.assetContainer?.meshes?.length ?? 0,
+                bounds: modelBounds,
+            },
+            environment: {
+                visible: !!this.#containers.environment?.state?.isVisible,
+                hasContainer: !!this.#containers.environment?.assetContainer,
+            },
+            lastCameraFrame: this.#debugCameraFrameInfo,
+            renderLoopRunning: !!this.#state?.render?.isLoopRunning,
+        };
+    }
+
     /**
      * Stops the Babylon.js render loop for the current scene.
      * @private
@@ -2571,12 +2889,25 @@ export default class BabylonJSController {
      * @private
      * @returns {Promise<void>}
      */
-    async #startRender() {
+    async #startRender({ skipWhenReady = false, forceRender = false, skipCameraDependentEffects = false } = {}) {
         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 });
+        this.#startRenderInProgress = true;
+        try {
+            if (!skipCameraDependentEffects) {
+                await this.#loadCameraDependentEffects();
+            }
+            // skipWhenReady: model materials already compiled via compileMaterials:true.
+            // Skips scene-wide whenReadyAsync so the model appears immediately (~1s).
+            if (!skipWhenReady) {
+                await this.#scene.whenReadyAsync();
+            }
+            const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
+            // forceRender: bypasses #loadingInProgress gate so loadContainerIndependent
+            // can show the model preview while #loadContainers is still loading scene/materials.
+            this.#requestRender({ frames: frames, continuousMs: this.#config.render.interactionMs, force: forceRender });
+        } finally {
+            this.#startRenderInProgress = false;
+        }
     }
 
     /**
@@ -2595,7 +2926,7 @@ export default class BabylonJSController {
      * 3. Builds the Babylon plugin options so extras are surfaced as metadata, then imports the container with
      *    `LoadAssetContainerAsync`, returning the tuple so the caller can decide how to attach it to the scene.
      */
-    async #loadAssetContainer(container, force = false) {
+    async #loadAssetContainer(container, force = false, { isIndependent = false } = {}) {
         if (container?.state?.update?.storage === undefined || container?.state?.size === undefined || container?.state?.timeStamp === undefined) {
             return [container, false];
         }
@@ -2611,12 +2942,30 @@ export default class BabylonJSController {
         const currentSize = force ? 0 : container.state.size;
         const currentTimeStamp = force ? null : container.state.timeStamp;
 
+        const storageType = container.state.update.storage?.db ? "idb" : container.state.update.storage?.url ? "url" : "?";
+        const storageId = container.state.update.storage?.id ?? container.state.update.storage?.url ?? "?";
+        const tResolve = performance.now();
         let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, currentSize, currentTimeStamp);
+        console.log(`[perf][${container.state.name}] getSource(${storageType}:${storageId}) ${Math.round(performance.now() - tResolve)}ms → ${sourceData ? `${sourceData.extension} ${sourceData.objectURLs?.length ?? 0} assets` : "skipped"}`);
 
         if (!sourceData) {
             return [container, false];
         }
 
+        // Abort if loadContainerIndependent claimed this container while getSource was in flight.
+        // isIndependent=true means THIS call IS the independent load — don't abort yourself.
+        // Returns null (not false) so #loadContainers skips setSuccess(false) for this container.
+        const isClaimedIndependently =
+            (container.state.name === "model" && this.#isLoadingModelIndependent) ||
+            (container.state.name === "environment" && this.#isLoadingEnvironmentIndependent) ||
+            (container.state.name === "materials" && this.#isLoadingMaterialsIndependent);
+        if (isClaimedIndependently && !isIndependent) {
+            if (sourceData.objectURLs?.length) {
+                this.#gltfResolver.revokeObjectURLs(sourceData.objectURLs);
+            }
+            return [container, null];
+        }
+
         container.state.setPendingCacheData(sourceData.size, sourceData.timeStamp, sourceData.metadata);
 
         // https://doc.babylonjs.com/typedoc/interfaces/BABYLON.LoadAssetContainerOptions
@@ -2635,9 +2984,12 @@ export default class BabylonJSController {
         };
 
         let assetContainer = null;
+        const t0 = performance.now();
 
         try {
             assetContainer = await LoadAssetContainerAsync(sourceData.source, this.#scene, options);
+            const elapsed = Math.round(performance.now() - t0);
+            console.log(`[perf][${container.state.name}] LoadAssetContainerAsync ${elapsed}ms`);
             return [container, assetContainer];
         } catch (error) {
             return [container, assetContainer];
@@ -2657,7 +3009,29 @@ export default class BabylonJSController {
      */
     async #loadContainers(force = false) {
         this.#detachAnimationChangedListener();
-        await this.#stopRender();
+        this.#loadingInProgress = true;
+
+        // When only the model is pending (scene/environment already rendered), skip
+        // unloading camera-dependent effects (DefaultRenderingPipeline, SSAO, shadows).
+        // Disposing those pipelines while the render loop was recently active deletes GL
+        // programs that are still referenced, causing WebGL INVALID_OPERATION errors.
+        const isModelOnlyLoad =
+            this.#containers.model?.state?.isPending === true &&
+            this.#containers.environment?.state?.isPending !== true &&
+            this.#containers.materials?.state?.isPending !== true;
+
+        if (isModelOnlyLoad) {
+            this.#stopEngineRenderLoop();
+            this.#resetRenderState();
+            // Replacing an already-visible model can leave Babylon post-process chains attached to
+            // a camera that is about to be discarded or re-bound. Tear them down here so the next
+            // startRender() rebuilds a clean pipeline instead of tripping over stale null entries.
+            if (this.#containers.model?.assetContainer) {
+                await this.#unloadCameraDependentEffects();
+            }
+        } else {
+            await this.#stopRender();
+        }
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
@@ -2672,8 +3046,12 @@ export default class BabylonJSController {
             error: null,
         };
 
+        const tSceneStart = performance.now();
+        let tAfterLoad, tAfterMerge;
+
         await Promise.allSettled(promiseArray)
             .then(async (values) => {
+                tAfterLoad = performance.now();
                 // Scene may have been disposed (disconnectedCallback) while async loading was in
                 // progress.  Abort cleanly: #replaceContainer already guards the GPU calls, but
                 // we skip the post-load option/visibility calls too to avoid further null-derefs.
@@ -2682,6 +3060,12 @@ export default class BabylonJSController {
                     return;
                 }
                 this.#disposeAnimationController();
+                this.#emitSceneLoadPhase("scene-load-assets-complete", {
+                    path: "full",
+                    containerCount: values.filter((result) => result.status === "fulfilled" && result.value?.[1]).length,
+                    tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
+                    tSceneStart: Math.round(tSceneStart),
+                });
                 values.forEach((result) => {
                     const container = result.value ? result.value[0] : null;
                     const assetContainer = result.value ? result.value[1] : null;
@@ -2697,17 +3081,29 @@ export default class BabylonJSController {
                         this.#replaceContainer(container, assetContainer);
                         container.state.setSuccess(true);
                     } else {
-                        if (container.assetContainer && container.state.mustBeShown !== container.state.isVisible && container.state.name === "materials") {
-                            container.state.mustBeShown ? this.#addContainer(container) : this.#removeContainer(container);
+                        // null sentinel = claimed by loadContainerIndependent — already merged independently.
+                        // false = normal skip (no data change) or error. Only mark failure for the latter.
+                        if (assetContainer !== null) {
+                            if (container.assetContainer && container.state.mustBeShown !== container.state.isVisible && container.state.name === "materials") {
+                                container.state.mustBeShown ? this.#addContainer(container) : this.#removeContainer(container);
+                            }
+                            container.state.setSuccess(false);
                         }
-                        container.state.setSuccess(false);
                     }
                 });
 
-                this.#setOptions_Materials();
+                this.#setOptions_Materials(true);
                 this.#setOptions_Camera();
                 await this.#setOptions_IBL();
                 this.#setVisibilityOfWallAndFloorInModel();
+                this.#frameCameraToModel();
+                tAfterMerge = performance.now();
+                this.#emitSceneLoadPhase("scene-load-merge-complete", {
+                    path: "full",
+                    tAfterMerge: tAfterMerge != null ? Math.round(tAfterMerge) : null,
+                    tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
+                    tSceneStart: Math.round(tSceneStart),
+                });
                 detail.success = true;
             })
             .catch((error) => {
@@ -2720,7 +3116,9 @@ export default class BabylonJSController {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
                 this.#enhanceTextureQuality();
-                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
+                if (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,
@@ -2729,7 +3127,24 @@ export default class BabylonJSController {
                 if (this.#babylonJSAnimationController?.hasAnimations?.()) {
                     this.#attachAnimationChangedListener();
                 }
+                this.#loadingInProgress = false;
+                // If loadContainerIndependent already merged a container and started the render
+                // loop while this scene load was in flight, #startRender was already called.
+                // Calling it again is safe (pipeline guards skip recreation) but redundant only
+                // when the loop is already running AND scene/shaders are ready; whenReadyAsync
+                // will settle quickly for the newly added containers.
                 await this.#startRender();
+                this.#frameCameraToModel({ allowWhenEnvironmentVisible: true });
+                this.#emitSceneLoadPhase("scene-load-shaders-complete", {
+                    path: "full",
+                    tAfterShaders: Math.round(performance.now()),
+                    tAfterMerge: tAfterMerge != null ? Math.round(tAfterMerge) : null,
+                });
+                const tLoad = tAfterLoad ? Math.round(tAfterLoad - tSceneStart) : null;
+                const tMerge = tAfterLoad && tAfterMerge ? Math.round(tAfterMerge - tAfterLoad) : null;
+                const tShaders = tAfterMerge ? Math.round(performance.now() - tAfterMerge) : null;
+                const tTotal = Math.round(performance.now() - tSceneStart);
+                console.log(`[perf][scene] load=${tLoad}ms merge=${tMerge}ms shaders=${tShaders}ms total=${tTotal}ms`);
             });
         return detail;
     }
@@ -3180,6 +3595,296 @@ export default class BabylonJSController {
         return await this.#loadContainers(force);
     }
 
+    /**
+     * Loads a single named container in the background while the render loop keeps running,
+     * then merges it into the scene atomically (only the merge momentarily pauses the loop).
+     * Camera-dependent effects (post-processing, SSAO, shadows) are preserved across the merge.
+     * If a full #loadContainers is in progress, waits for it to finish before merging.
+     * @public
+     * @param {string} containerName - Name of the container to load ("model", "environment", "materials").
+     * @param {Function} [onReady] - Optional callback invoked after any concurrent scene load finishes
+     *   and before the asset is fetched. Use this to mark the container pending (e.g. via
+     *   #checkNeedToUpdateContainers) so that the concurrent #loadContainers doesn't consume it first.
+     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
+     */
+    async loadContainerIndependent(containerName, onReady, options = {}) {
+        const loadSessionId = containerName === "model" ? (options?.loadSessionId ?? null) : null;
+        if (containerName === "model" && this.#isLoadingModelIndependent) {
+            return { success: false, error: "Already loading model independently", loadedContainers: [], loadSessionId };
+        }
+        if (containerName === "environment" && this.#isLoadingEnvironmentIndependent) {
+            return { success: false, error: "Already loading environment independently", loadedContainers: [], loadSessionId };
+        }
+        if (containerName === "materials" && this.#isLoadingMaterialsIndependent) {
+            return { success: false, error: "Already loading materials independently", loadedContainers: [], loadSessionId };
+        }
+
+        if (containerName === "model") this.#isLoadingModelIndependent = true;
+        else if (containerName === "environment") this.#isLoadingEnvironmentIndependent = true;
+        else if (containerName === "materials") this.#isLoadingMaterialsIndependent = true;
+
+        // Only reset model-first-painted tracking for model loads — resetting it for
+        // environment/materials would stale any in-flight model-first-painted gate.
+        if (containerName === "model") {
+            this.#modelFirstPaintedEmitted = false;
+        }
+        const modelFirstPaintedLoadToken = containerName === "model"
+            ? ++this.#modelFirstPaintedLoadToken
+            : this.#modelFirstPaintedLoadToken;
+        let assetContainer = null;
+        const tIndepStart = performance.now();
+        // Whether the container was already pending inside a running #loadContainers batch.
+        // If so, we fall back to the sequential path (wait → onReady → load) to avoid a
+        // double-load conflict. Otherwise, load the GLTF in parallel with the scene load
+        // and only wait for the atomic merge window.
+        const isAlreadyHandled =
+            this.#containers[containerName]?.state?.isPending === true && this.#loadingInProgress;
+        const path = isAlreadyHandled ? "claimed" : "par";
+        let container;
+        let tAfterLoad, tAfterWait;
+        try {
+            if (!isAlreadyHandled) {
+                // Optimistic path: prepare state and load GLTF NOW, in parallel with any running
+                // #loadContainers. The merge waits for the scene, but the download does not.
+                if (!this.#scene) {
+                    return { success: false, error: "No scene available", loadedContainers: [], loadSessionId };
+                }
+                onReady?.();
+                container = this.#containers[containerName];
+                if (!container) {
+                    return { success: false, error: `Container "${containerName}" not found`, loadedContainers: [], loadSessionId };
+                }
+                // Phase 1 (parallel): load GLTF while scene may still be loading.
+                // No wait — merge happens immediately after load. #replaceContainer skips
+                // releaseEffects when the loop is running, so no WebGL programs are deleted.
+                const [, loaded] = await this.#loadAssetContainer(container, false, { isIndependent: true });
+                assetContainer = loaded || null;
+                tAfterLoad = performance.now();
+                tAfterWait = tAfterLoad; // no wait phase in optimistic path
+            } else {
+                // Parallel claim path: container was already submitted to a running #loadContainers
+                // batch. #isLoadingModelIndependent (set at the top of this method) signals
+                // #loadAssetContainer to abort the in-flight batch load and return a null sentinel,
+                // so #loadContainers skips merging this container. We load it here in parallel —
+                // no waiting for scene/materials to finish.
+                if (!this.#scene) {
+                    return { success: false, error: "No scene available", loadedContainers: [], loadSessionId };
+                }
+                // Call onReady() to ensure the container state carries this load's payload,
+                // which may differ from what #loadContainers was given if the caller swapped the model.
+                onReady?.();
+                container = this.#containers[containerName];
+                if (!container) {
+                    return { success: false, error: `Container "${containerName}" not found`, loadedContainers: [], loadSessionId };
+                }
+                const [, loaded] = await this.#loadAssetContainer(container, false, { isIndependent: true });
+                assetContainer = loaded || null;
+                tAfterLoad = performance.now();
+                tAfterWait = tIndepStart; // no wait phase — measure load from start
+            }
+
+            if (!assetContainer) {
+                return { success: false, error: "Failed to load asset container", loadedContainers: [], loadSessionId };
+            }
+            if (!this.#scene) {
+                assetContainer.dispose();
+                return { success: false, error: "Scene was disposed", loadedContainers: [], loadSessionId };
+            }
+
+            this.#emitSceneLoadPhase("scene-load-assets-complete", {
+                containerName,
+                path,
+                tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
+                tIndepStart: Math.round(tIndepStart),
+            });
+
+            // Phase 3: atomic merge — briefly stop the loop for the merge only
+            this.#stopEngineRenderLoop();
+
+            const oldModelMetadata = containerName === "model"
+                ? { ...(this.#containers.model?.state?.metadata ?? {}) }
+                : {};
+
+            this.#disposeAnimationController();
+
+            if (containerName === "model") {
+                this.#assetContainer_deleteLights(assetContainer);
+                this.#assetContainer_stopAnimations(assetContainer);
+            }
+            if (containerName === "model" || containerName === "environment") {
+                this.#assetContainer_retagCameras(assetContainer);
+            }
+
+            this.#replaceContainer(container, assetContainer, { releaseEffects: false });
+            container.state.setSuccess(true);
+
+            // Progressive independent loads may bring model/materials/environment in any order.
+            // Force material rebinding after each merge so already-visible model meshes pick up
+            // the latest material definitions instead of waiting for pending flags that may
+            // already have been cleared.
+            this.#setOptions_Materials(true);
+            this.#setOptions_Camera();
+            // For model: IBL not yet loaded (scene still in flight) — create only ambient/directional
+            // lights. #loadContainers will call #createLights() again with full IBL once scene merges.
+            // For environment: IBL state was pre-marked pending by loadSceneIndependent before calling
+            // here, so #setOptions_IBL() picks it up and applies it immediately after lights are ready.
+            await this.#createLights();
+            if (containerName === "environment") {
+                await this.#setOptions_IBL();
+            }
+
+            if (containerName === "model") {
+                const newModelMetadata = { ...(container.state.update?.metadata ?? {}) };
+                this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
+            }
+
+            if (this.#containers.model.assetContainer) {
+                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
+            }
+            const tAfterMerge = performance.now();
+            this.#emitSceneLoadPhase("scene-load-merge-complete", {
+                containerName,
+                path,
+                tAfterMerge: Math.round(tAfterMerge),
+                tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
+                tIndepStart: Math.round(tIndepStart),
+            });
+
+            // Use #startRender() so the next frame is scheduled after the atomic merge.
+            // In progressive loads, rebuilding camera-dependent effects (DefaultRenderingPipeline,
+            // SSAO, shadows) while the model is already visible can delete GL programs that are
+            // still referenced by the current frame, which leaves the canvas gray until a later
+            // full reload. Keep the existing pipeline alive for independent model/environment/
+            // materials appends; the full load path still rebuilds everything when needed.
+            await this.#startRender({ skipWhenReady: true, forceRender: true, skipCameraDependentEffects: true });
+            const tAfterShaders = performance.now();
+
+            this.#setHighlightConfig({
+                enabled: this.#settings.highlightEnabled,
+                color: this.#settings.highlightColor,
+            });
+            this.#setMaxSimultaneousLights();
+            this.#enhanceTextureQuality();
+            this.#setVisibilityOfWallAndFloorInModel();
+
+            if (this.#babylonJSAnimationController?.hasAnimations?.()) {
+                this.#attachAnimationChangedListener();
+            }
+
+            this.#requestRender({ frames: 3, continuousMs: this.#config.render.interactionMs });
+            if (containerName === "model" && !this.#modelFirstPaintedEmitted) {
+                try {
+                    performance.mark(`viewer:model-first-painted:scheduled:${modelFirstPaintedLoadToken}`);
+                } catch {
+                    // ignore
+                }
+                console.log("[viewer] model-first-painted gate scheduled", {
+                    containerName,
+                    path: isAlreadyHandled ? "claimed" : "par",
+                    loadToken: modelFirstPaintedLoadToken,
+                    renderLoopRunning: this.#state.render.isLoopRunning,
+                    loopRequested: true,
+                });
+                void (async () => {
+                    await this.#waitForPaint(2);
+                    try {
+                        performance.mark(`viewer:model-first-painted:after-wait:${modelFirstPaintedLoadToken}`);
+                    } catch {
+                        // ignore
+                    }
+                    console.log("[viewer] model-first-painted gate after paint wait", {
+                        containerName,
+                        path: isAlreadyHandled ? "claimed" : "par",
+                        loadToken: modelFirstPaintedLoadToken,
+                        currentToken: this.#modelFirstPaintedLoadToken,
+                        alreadyEmitted: this.#modelFirstPaintedEmitted,
+                        renderLoopRunning: this.#state.render.isLoopRunning,
+                    });
+                    if (modelFirstPaintedLoadToken !== this.#modelFirstPaintedLoadToken) {
+                        try {
+                            performance.mark(`viewer:model-first-painted:stale:${modelFirstPaintedLoadToken}`);
+                        } catch {
+                            // ignore
+                        }
+                        console.log("[viewer] model-first-painted gate skipped (stale load token)", {
+                            containerName,
+                            path: isAlreadyHandled ? "claimed" : "par",
+                            loadToken: modelFirstPaintedLoadToken,
+                            currentToken: this.#modelFirstPaintedLoadToken,
+                        });
+                        return;
+                    }
+                    const paintTarget = this.#prefViewer || this.#prefViewer3D || this.#canvas;
+                    if (!this.#modelFirstPaintedEmitted && paintTarget) {
+                        this.#modelFirstPaintedEmitted = true;
+                        try {
+                            performance.mark(`viewer:model-first-painted:emitted:${modelFirstPaintedLoadToken}`);
+                        } catch {
+                            // ignore
+                        }
+                        console.log("[viewer] model-first-painted ✅ emitted", {
+                            containerName,
+                            path: isAlreadyHandled ? "claimed" : "par",
+                            loadToken: modelFirstPaintedLoadToken,
+                            tAfterPaint: Math.round(performance.now()),
+                        });
+                        this.#emitModelFirstPainted({
+                            containerName,
+                            path: isAlreadyHandled ? "claimed" : "par",
+                            tIndepStart: Math.round(tIndepStart),
+                            tAfterLoad: tAfterLoad != null ? Math.round(tAfterLoad) : null,
+                            tAfterWait: tAfterWait != null ? Math.round(tAfterWait) : null,
+                            tAfterMerge: Math.round(tAfterMerge),
+                            tAfterPaint: Math.round(performance.now()),
+                        });
+                    }
+                })();
+            }
+
+            // In the optimistic path: load runs first, then wait. In the sequential path: wait
+            // runs first, then load. Compute each phase relative to its actual start point.
+            const tLoad = isAlreadyHandled
+                ? Math.round(tAfterLoad - tAfterWait)
+                : Math.round(tAfterLoad - tIndepStart);
+            const tWait = isAlreadyHandled
+                ? Math.round(tAfterWait - tIndepStart)
+                : Math.round(tAfterWait - tAfterLoad);
+            // Merge starts after the wait in both paths (optimistic: load→wait→merge; sequential: wait→load→merge)
+            const tMerge = Math.round(tAfterMerge - (isAlreadyHandled ? tAfterLoad : tAfterWait));
+            const tShaders = Math.round(tAfterShaders - tAfterMerge);
+            const tTotal = Math.round(tAfterShaders - tIndepStart);
+            this.#emitSceneLoadPhase("scene-load-shaders-complete", {
+                containerName,
+                path,
+                tAfterShaders: Math.round(tAfterShaders),
+                tAfterMerge: Math.round(tAfterMerge),
+                tTotal,
+            });
+            this.#emitSceneLoadPhase("scene-load-container-complete", {
+                containerName,
+                path,
+                tLoad,
+                tWait,
+                tMerge,
+                tShaders,
+                tTotal,
+            });
+            console.log(`[perf][${containerName}:indep:${path}] load=${tLoad}ms wait=${tWait}ms merge=${tMerge}ms shaders=${tShaders}ms total=${tTotal}ms`);
+
+            return { success: true, error: null, loadedContainers: [containerName], loadSessionId };
+        } catch (error) {
+            assetContainer?.dispose();
+            if (!this.#state.render.isLoopRunning && this.#scene && this.#engine) {
+                this.#startEngineRenderLoop();
+            }
+            return { success: false, error, loadedContainers: [], loadSessionId };
+        } finally {
+            if (containerName === "model") this.#isLoadingModelIndependent = false;
+            else if (containerName === "environment") this.#isLoadingEnvironmentIndependent = false;
+            else if (containerName === "materials") this.#isLoadingMaterialsIndependent = false;
+        }
+    }
+
     /**
      * Applies camera options from the configuration to the active camera.
      * Stops and restarts the render loop to apply changes.
@@ -3384,3 +4089,4 @@ export default class BabylonJSController {
         }
     }
 }
+