@preference-sl/pref-viewer 2.13.0-beta.8 → 2.13.0

package/Readme.md

@@ -5,4 +5,4 @@ A Web Component for visualizing GLTF models using Babylon.js.
 ## Installation
 
 ```bash
-npm install @preference-sl/pref-viewer
+npm install @preference-sl/pref-viewer

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.13.0-beta.8",
+    "version": "2.13.0",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-animation-controller.js

@@ -45,7 +45,7 @@ export default class BabylonJSAnimationController {
     #highlightColor = Color3.FromHexString(PrefViewerStyleVariables.colorPrimary);
     #highlightLayer = null;
     #overlayLayer = null;
-    #useHighlightLayer = false; // Set to true to use HighlightLayer (better performance) and false to use overlay meshes (UtilityLayerRenderer - always on top)
+    #useHighlightLayer = true; // Set to true to use HighlightLayer (better performance) and false to use overlay meshes (UtilityLayerRenderer - always on top)
     #lastHighlightedMeshId = null; // Cache to avoid redundant highlight updates
     #lastHighlightedNodeIds = []; // Cache to avoid redundant highlight updates
 
@@ -317,6 +317,9 @@ export default class BabylonJSAnimationController {
                 baseToOverlayBase.forEach((overlayBase) => {
                     overlayBase.dispose();
                 });
+
+                // Dispose utility layer scene/resources; without this each rebuild leaks GPU/JS resources.
+                utilityLayer.dispose();
             },
         };
     }
@@ -513,20 +516,26 @@ export default class BabylonJSAnimationController {
 
     /**
      * Displays the animation control menu for the animated node under the pointer.
+     * Hides the current menu when picking info is invalid or when no animated node is found.
+     * Prefers a currently started animation; otherwise falls back to the first available one.
      * @public
-     * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
+     * @param {PickingInfo|null|undefined} pickingInfo - Raycast info from pointer position.
+     * Can be null/undefined when caller intentionally skips picking.
+     * @returns {void}
      */
     showMenu(pickingInfo) {
-        if (!pickingInfo?.hit && !pickingInfo?.pickedMesh) {
+        const pickedMesh = pickingInfo?.pickedMesh;
+        if (!pickingInfo?.hit || !pickedMesh) {
+            this.hideMenu();
             return;
         }
 
-        this.hideMenu();
-
-        const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
+        const nodeIds = this.#getNodesAnimatedByMesh(pickedMesh);
         if (!nodeIds.length) {
+            this.hideMenu();
             return;
         }
+        
         const openingAnimations = [];
         nodeIds.forEach((nodeId) => {
             const openingAnimation = this.#getOpeningAnimationByNode(nodeId);
@@ -536,7 +545,19 @@ export default class BabylonJSAnimationController {
             openingAnimations.push(openingAnimation);
         });
 
+        if (!openingAnimations.length) {
+            this.hideMenu();
+            return;
+        }
+
         const startedAnimation = openingAnimations.find((animation) => animation.state !== OpeningAnimation.states.closed);
-        startedAnimation ? startedAnimation.showControls(this.#canvas, openingAnimations) : openingAnimations[0].showControls(this.#canvas, openingAnimations);
+        const animationToShow = startedAnimation ? startedAnimation : openingAnimations[0];
+
+        if (animationToShow.isControlsVisible()) {
+            return;
+        }
+
+        this.hideMenu();
+        animationToShow.showControls(this.#canvas, openingAnimations);
     }
 }

package/src/babylonjs-controller.js

@@ -18,14 +18,15 @@ import { translate } from "./localization/i18n.js";
  * turns it into a deterministic scene lifecycle with exports.
  *
  * Overview
- *  - Creates the Babylon.js engine/scene/camera stack, configures Draco decoders, wires resize + render loops, and
- *    exposes download/xR helpers.
+ *  - Creates the Babylon.js engine/scene/camera stack, configures Draco decoders, wires render loops plus a throttled
+ *    ResizeObserver, and exposes download/XR helpers.
  *  - Resolves GLTF/GLB sources via GLTFResolver, loads them into `AssetContainer`s, and toggles visibility by
  *    mutating container state plus `show-model/show-scene` attributes.
  *  - Applies/persists AA, SSAO, IBL, and shadow flags; when they change it stops the render loop, tears down pipelines,
  *    reloads containers, and reinstalls effects after environment textures finish loading.
  *  - Manages keyboard/pointer/wheel handlers, animation menus, and WebXR so PrefViewer menus and DOM attributes stay
- *    synchronized with Babylon state.
+ *    synchronized with Babylon state, using sampled pointer picking and last-picked tracking to reduce raycast/highlight
+ *    cost on dense scenes.
  *  - Generates GLB, glTF+ZIP, or USDZ exports with timestamped names and localized dialog copy.
  *  - Translates metadata (inner floor offsets, cast/receive shadows, camera locks) into scene adjustments after reloads.
  *
@@ -39,6 +40,8 @@ import { translate } from "./localization/i18n.js";
  *  5. Use `setContainerVisibility`, `setMaterialOptions`, `setCameraOptions`, or `setIBLOptions` for targeted updates; these
  *     helpers stop/restart the render loop while they rebuild camera-dependent resources.
  *  6. Invoke `disable()` when the element disconnects to tear down scenes, XR sessions, observers, and handlers.
+ *     `disable()` is asynchronous; it waits for XR/session shutdown before engine disposal and also disposes the
+ *     shared GLTF resolver, which closes its internal IndexedDB handle.
  *
  * Public API Highlights
  *  - constructor(canvas, containers, options)
@@ -62,6 +65,14 @@ import { translate } from "./localization/i18n.js";
  *    while `options.ibl.valid` remains true.
  *  - Browser-only features guard `window`, localStorage, and XR APIs before use so the controller is safe to construct
  *    in SSR/Node contexts (though functionality activates only in browsers).
+ *  - Pointer-pick lifecycle: hover/highlight raycasts are sampled on POINTERMOVE (time + distance thresholds), wheel
+ *    input avoids picks entirely, and right-click POINTERUP performs an on-demand pick for context-menu targeting.
+ *  - Runtime bookkeeping is split into mutable `#state` and tuning constants under `#config` to keep behavior changes
+ *    explicit and reduce cross-field drift.
+ *  - Resize lifecycle: canvas resize notifications are throttled (with trailing execution) before calling `engine.resize()`
+ *    and any queued resize callback is canceled during teardown.
+ *  - Teardown lifecycle: concurrent `disable()` calls are coalesced into a single in-flight promise to avoid races
+ *    during XR exit and engine disposal.
  */
 export default class BabylonJSController {
     #RENDER_SETTINGS_STORAGE_KEY = "pref-viewer/render-settings";
@@ -93,9 +104,8 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
-
+    
     #hdrTexture = null; // reusable in-memory HDR source cloned into scene.environmentTexture across reloads
-    #lastPickedMeshId = null;
 
     #containers = {};
     #options = {};
@@ -110,28 +120,61 @@ export default class BabylonJSController {
     };
 
     #handlers = {
+        onAnimationGroupChanged: null,
         onKeyUp: null,
         onPointerObservable: null,
-        onAnimationGroupChanged: null,
         onResize: null,
         renderLoop: null,
     };
 
     #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
 
-    #renderState = {
-        isLoopRunning: false,
-        dirtyFrames: 0,
-        continuousUntil: 0,
-        lastRenderAt: 0,
+    // Runtime mutable state (changes while the app is running).
+    #state = {
+        // Pointer-picking sampling state avoids expensive scene.pick on every move.
+        pointerPicking: {
+            lastMovePickAt: 0,
+            lastMovePickX: NaN,
+            lastMovePickY: NaN,
+            lastPickedMeshId: null,
+        },
+        // Render loop state balances performance with responsiveness.
+        render: {
+            isLoopRunning: false,
+            dirtyFrames: 0,
+            continuousUntil: 0,
+            lastRenderAt: 0,
+        },
+        // Resize state batches frequent ResizeObserver notifications.
+        resize: {
+            isScheduled: false,
+            timeoutId: null,
+            lastAppliedAt: 0,
+        },
     };
 
-    #renderConfig = {
-        burstFramesBase: 2,
-        burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
-        interactionMs: 250,
-        animationMs: 200,
-        idleThrottleMs: 1000 / 15,
+    // Runtime configuration constants (tuning knobs, not per-frame state).
+    #config = {
+        pointerPicking: {
+            movePickIntervalMs: 50, // cap expensive scene.pick calls to ~20 Hz while moving the pointer
+            movePickMinDistancePx: 2, // skip picks for sub-pixel jitter
+        },
+        render: {
+            burstFramesBase: 2,
+            burstFramesEnhanced: 32, // when AA/SSAO/IBL is enabled, more frames are needed to reach stable output
+            interactionMs: 250,
+            animationMs: 200,
+            idleThrottleMs: 1000 / 15,
+        },
+        resize: {
+            throttleMs: 50, // cap resize work to ~20 Hz while dragging/resizing containers
+        },
+    };
+
+    // Promises to track async disable() lifecycle when XR and general teardown may run concurrently; ensures idempotent disable calls are safe and callers can await full teardown completion.
+    #disablingPromises = {
+        xr: null,
+        general: null,
     };
 
     /**
@@ -298,11 +341,11 @@ export default class BabylonJSController {
      * @returns {boolean} True when the loop was started, false when no engine is available or it was already running.
      */
     #startEngineRenderLoop() {
-        if (!this.#engine || this.#renderState.isLoopRunning) {
+        if (!this.#engine || this.#state.render.isLoopRunning) {
             return false;
         }
         this.#engine.runRenderLoop(this.#handlers.renderLoop);
-        this.#renderState.isLoopRunning = true;
+        this.#state.render.isLoopRunning = true;
         return true;
     }
 
@@ -312,13 +355,25 @@ export default class BabylonJSController {
      * @returns {boolean} True when the loop was stopped, false when no engine is available or it was already stopped.
      */
     #stopEngineRenderLoop() {
-        if (!this.#engine || !this.#renderState.isLoopRunning) {
+        if (!this.#engine || !this.#state.render.isLoopRunning) {
             return false;
         }
         this.#engine.stopRenderLoop(this.#handlers.renderLoop);
-        this.#renderState.isLoopRunning = false;
+        this.#state.render.isLoopRunning = false;
         return true;
     }
+    
+    /**
+     * Resets transient render-loop bookkeeping so the next render request starts from a clean baseline.
+     * Clears queued burst frames, ends any active continuous-render window, and drops the idle-throttle timestamp.
+     * @private
+     * @returns {void}
+     */
+    #resetRenderState() {
+        this.#state.render.dirtyFrames = 0;
+        this.#state.render.continuousUntil = 0;
+        this.#state.render.lastRenderAt = 0;
+    }
 
     /**
      * Marks the scene as dirty and optionally extends a short continuous-render window.
@@ -335,9 +390,9 @@ export default class BabylonJSController {
         }
 
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-        this.#renderState.dirtyFrames = Math.max(this.#renderState.dirtyFrames, Math.max(1, frames));
+        this.#state.render.dirtyFrames = Math.max(this.#state.render.dirtyFrames, Math.max(1, frames));
         if (continuousMs > 0) {
-            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + continuousMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + continuousMs);
         }
         this.#startEngineRenderLoop();
         return true;
@@ -422,13 +477,13 @@ export default class BabylonJSController {
         const cameraInMotion = this.#isCameraInMotion();
 
         if (animationRunning) {
-            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + this.#renderConfig.animationMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.animationMs);
         }
         if (cameraInMotion) {
-            this.#renderState.continuousUntil = Math.max(this.#renderState.continuousUntil, now + this.#renderConfig.interactionMs);
+            this.#state.render.continuousUntil = Math.max(this.#state.render.continuousUntil, now + this.#config.render.interactionMs);
         }
 
-        return animationRunning || cameraInMotion || this.#renderState.continuousUntil > now;
+        return animationRunning || cameraInMotion || this.#state.render.continuousUntil > now;
     }
 
     /**
@@ -446,22 +501,22 @@ export default class BabylonJSController {
 
         const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         const continuous = this.#shouldRenderContinuously(now);
-        const needsRender = continuous || this.#renderState.dirtyFrames > 0;
+        const needsRender = continuous || this.#state.render.dirtyFrames > 0;
 
         if (!needsRender) {
             this.#stopEngineRenderLoop();
             return;
         }
 
-        if (!continuous && this.#renderState.lastRenderAt > 0 && now - this.#renderState.lastRenderAt < this.#renderConfig.idleThrottleMs) {
+        if (!continuous && this.#state.render.lastRenderAt > 0 && now - this.#state.render.lastRenderAt < this.#config.render.idleThrottleMs) {
             return;
         }
-
+        
         this.#scene.render();
-        this.#renderState.lastRenderAt = now;
+        this.#state.render.lastRenderAt = now;
 
-        if (this.#renderState.dirtyFrames > 0) {
-            this.#renderState.dirtyFrames -= 1;
+        if (this.#state.render.dirtyFrames > 0) {
+            this.#state.render.dirtyFrames -= 1;
         }
     }
 
@@ -1180,6 +1235,55 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Resets pointer-picking sampling state.
+     * @private
+     * @returns {void}
+     */
+    #resetPointerPickingState() {
+        this.#state.pointerPicking.lastMovePickAt = 0;
+        this.#state.pointerPicking.lastMovePickX = NaN;
+        this.#state.pointerPicking.lastMovePickY = NaN;
+        this.#state.pointerPicking.lastPickedMeshId = null;
+    }
+
+    /**
+     * Decides whether a POINTERMOVE event should trigger a scene raycast.
+     * Uses time + distance sampling to avoid expensive pick calls on every mouse move.
+     * @private
+     * @returns {boolean}
+     */
+    #shouldPickOnPointerMove() {
+        if (!this.#scene || !this.#babylonJSAnimationController) {
+            return false;
+        }
+
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const x = this.#scene.pointerX;
+        const y = this.#scene.pointerY;
+        const state = this.#state.pointerPicking;
+        const config = this.#config.pointerPicking;
+
+        if (!Number.isFinite(state.lastMovePickX) || !Number.isFinite(state.lastMovePickY)) {
+            state.lastMovePickX = x;
+            state.lastMovePickY = y;
+            state.lastMovePickAt = now;
+            return true;
+        }
+
+        const elapsed = now - state.lastMovePickAt >= config.movePickIntervalMs;
+        const moved = Math.abs(x - state.lastMovePickX) >= config.movePickMinDistancePx || Math.abs(y - state.lastMovePickY) >= config.movePickMinDistancePx;
+
+        if (!elapsed || !moved) {
+            return false;
+        }
+
+        state.lastMovePickX = x;
+        state.lastMovePickY = y;
+        state.lastMovePickAt = now;
+        return true;
+    }
+
     /**
      * Sets up interaction handlers for the Babylon.js canvas and scene.
      * @private
@@ -1193,10 +1297,7 @@ export default class BabylonJSController {
             this.#scene.onPointerObservable.add(this.#handlers.onPointerObservable);
         }
         if (this.#engine) {
-            this.#canvasResizeObserver = new ResizeObserver(() => {
-                this.#engine.resize();
-                this.#requestRender({ frames: this.#renderConfig.burstFramesBase, continuousMs: this.#renderConfig.interactionMs });
-            });
+            this.#canvasResizeObserver = new ResizeObserver(this.#handlers.onResize);
             this.#canvasResizeObserver.observe(this.#canvas);
         }
     }
@@ -1213,9 +1314,11 @@ export default class BabylonJSController {
         if (this.#scene !== null) {
             this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
         }
+        this.#cancelScheduledResize();
         this.#canvasResizeObserver?.disconnect();
         this.#canvasResizeObserver = null;
         this.#detachAnimationChangedListener();
+        this.#resetPointerPickingState();
     }
 
     /**
@@ -1231,31 +1334,56 @@ export default class BabylonJSController {
     }
 
     /**
-     * Disposes the Babylon.js WebXR experience if it exists.
+     * Disposes the shared GLTFResolver instance and closes its underlying storage handle.
      * @private
      * @returns {void}
      */
-    #disposeXRExperience() {
-        if (!this.#XRExperience) {
+    #disposeGLTFResolver() {
+        if (this.#gltfResolver) {
+            this.#gltfResolver.dispose();
+            this.#gltfResolver = null;
+        }
+    }
+
+    /**
+     * Disposes the Babylon.js WebXR experience if it exists.
+     * If XR is currently active, waits for `exitXRAsync()` before disposing to avoid
+     * tearing down the engine while the XR session is still shutting down.
+     * Concurrent calls share the same in-flight promise so disposal runs only once.
+     * @private
+     * @returns {Promise<void>}
+     */
+    async #disposeXRExperience() {
+        if (this.#disablingPromises.xr) {
+            return await this.#disablingPromises.xr;
+        }
+
+        const xrExperience = this.#XRExperience;
+        if (!xrExperience) {
             return;
         }
 
-        if (this.#XRExperience.baseExperience.state === WebXRState.IN_XR) {
-            this.#XRExperience.baseExperience
-                .exitXRAsync()
-                .then(() => {
-                    this.#XRExperience.dispose();
-                    this.#XRExperience = null;
-                })
-                .catch((error) => {
-                    console.warn("Error exiting XR experience:", error);
-                    this.#XRExperience.dispose();
+        this.#disablingPromises.xr = (async () => {
+            try {
+                if (xrExperience.baseExperience?.state === WebXRState.IN_XR) {
+                    await xrExperience.baseExperience.exitXRAsync();
+                }
+            } catch (error) {
+                console.warn("PrefViewer: Error exiting XR experience:", error);
+            } finally {
+                try {
+                    xrExperience.dispose();
+                } catch (error) {
+                    console.warn("PrefViewer: Error disposing XR experience:", error);
+                }
+                if (this.#XRExperience === xrExperience) {
                     this.#XRExperience = null;
-                });
-        } else {
-            this.#XRExperience.dispose();
-            this.#XRExperience = null;
-        }
+                }
+                this.#disablingPromises.xr = null;
+            }
+        })();
+
+        await this.#disablingPromises.xr;
     }
 
     /**
@@ -1303,7 +1431,7 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onAnimationGroupPlay() {
-        this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.animationMs });
+        this.#requestRender({ frames: 1, continuousMs: this.#config.render.animationMs });
     }
 
     /**
@@ -1312,7 +1440,11 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onAnimationGroupStop() {
-        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#renderConfig.burstFramesEnhanced : this.#renderConfig.burstFramesBase;
+        if (this.#settings.iblEnabled && this.#renderPipelines.iblShadows) {
+            this.#renderPipelines.iblShadows.updateVoxelization();
+            this.#scene?.postProcessRenderPipelineManager?.update();
+        }
+        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#config.render.burstFramesEnhanced : this.#config.render.burstFramesBase;
         this.#requestRender({ frames: frames });
     }
 
@@ -1352,10 +1484,10 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #onKeyUp(event) {
-        // CTRL + ALT + letter
-        if (event.ctrlKey && event.altKey && event.key !== undefined) {
-            switch (event.key.toLowerCase()) {
-                case "d":
+        // CTRL + ALT + letter (uses event.code for physical key, layout-independent — fixes Mac Option+D producing "∂" instead of "d")
+        if (event.ctrlKey && event.altKey && event.code !== undefined) {
+            switch (event.code) {
+                case "KeyD":
                     this.#openDownloadDialog();
                     break;
                 default:
@@ -1390,7 +1522,7 @@ export default class BabylonJSController {
                 const movementVector = direction.scale(zoomSpeed);
                 camera.position = camera.position.add(movementVector);
             }
-            this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
         }
     }
 
@@ -1403,7 +1535,9 @@ export default class BabylonJSController {
      */
     #onPointerUp(event, pickInfo) {
         if (this.#babylonJSAnimationController) {
-            this.#babylonJSAnimationController.hideMenu();
+            if (event.button !== 2 || !pickInfo || !pickInfo.pickedMesh) {
+                this.#babylonJSAnimationController.hideMenu();
+            }
             // Right click for showing animation menu
             if (event.button === 2) {
                 this.#babylonJSAnimationController.showMenu(pickInfo);
@@ -1415,20 +1549,20 @@ export default class BabylonJSController {
      * Handles pointer move events on the Babylon.js scene.
      * @private
      * @param {PointerEvent} event - The pointer move event.
-     * @param {PickInfo} pickInfo - The result of the scene pick operation.
+     * @param {PickInfo|null} pickInfo - The sampled result of the scene pick operation (may be null when sampling skips a raycast).
      * @returns {void}
      */
     #onPointerMove(event, pickInfo) {
         const camera = this.#scene?.activeCamera;
         if (camera && !camera.metadata?.locked) {
-            this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+            this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
         }
-        if (this.#babylonJSAnimationController) {
+        if (this.#babylonJSAnimationController && pickInfo) {
             const pickedMeshId = pickInfo?.pickedMesh?.id || null;
-            if (this.#lastPickedMeshId !== pickedMeshId) {
+            if (this.#state.pointerPicking.lastPickedMeshId !== pickedMeshId) {
                 const highlightResult = this.#babylonJSAnimationController.highlightMeshes(pickInfo);
                 if (highlightResult.changed) {
-                    this.#requestRender({ frames: 1, continuousMs: this.#renderConfig.interactionMs });
+                    this.#requestRender({ frames: 1, continuousMs: this.#config.render.interactionMs });
                 }
             }
         }
@@ -1436,22 +1570,30 @@ export default class BabylonJSController {
 
     /**
      * Handles pointer events observed on the Babylon.js scene.
+     * Uses pointer-move sampling to avoid running expensive `scene.pick()` on every event.
      * @private
      * @param {PointerInfo} info - The pointer event information from Babylon.js.
      * @returns {void}
      */
     #onPointerObservable(info) {
-        const pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
-        const pickedMeshId = pickInfo?.pickedMesh?.id || null;
-
         if (info.type === PointerEventTypes.POINTERMOVE) {
+            let pickInfo = null;
+            let lastPickedMeshId = null;
+            if (this.#shouldPickOnPointerMove()) {
+                pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
+                lastPickedMeshId = pickInfo?.pickedMesh?.id || null;
+            }
             this.#onPointerMove(info.event, pickInfo);
+            this.#state.pointerPicking.lastPickedMeshId = lastPickedMeshId;
         } else if (info.type === PointerEventTypes.POINTERUP) {
+            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;
+            }
             this.#onPointerUp(info.event, pickInfo);
         } else if (info.type === PointerEventTypes.POINTERWHEEL) {
-            this.#onMouseWheel(info.event, pickInfo);
+            this.#onMouseWheel(info.event, null);
         }
-        this.#lastPickedMeshId = pickedMeshId;
     }
 
     /**
@@ -1465,8 +1607,47 @@ export default class BabylonJSController {
         if (!this.#engine) {
             return;
         }
-        this.#engine.resize();
-        this.#requestRender({ frames: this.#renderConfig.burstFramesBase, continuousMs: this.#renderConfig.interactionMs });
+        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.#engine.resize();
+            this.#requestRender({ frames: this.#config.render.burstFramesBase, continuousMs: this.#config.render.interactionMs });
+        };
+
+        if (elapsed >= this.#config.resize.throttleMs) {
+            applyResize();
+            return;
+        }
+
+        if (this.#state.resize.isScheduled) {
+            return;
+        }
+
+        this.#state.resize.isScheduled = true;
+        const waitMs = Math.max(0, this.#config.resize.throttleMs - elapsed);
+        this.#state.resize.timeoutId = setTimeout(() => {
+            applyResize();
+        }, waitMs);
+    }
+
+    /**
+     * Clears any queued throttled resize callback.
+     * @private
+     * @returns {void}
+     */
+    #cancelScheduledResize() {
+        if (this.#state.resize.timeoutId !== null) {
+            clearTimeout(this.#state.resize.timeoutId);
+        }
+        this.#state.resize.timeoutId = null;
+        this.#state.resize.isScheduled = false;
     }
 
     /**
@@ -1812,11 +1993,10 @@ export default class BabylonJSController {
      */
     async #stopRender() {
         this.#stopEngineRenderLoop();
-        this.#renderState.dirtyFrames = 0;
-        this.#renderState.continuousUntil = 0;
-        this.#renderState.lastRenderAt = 0;
+        this.#resetRenderState();
         await this.#unloadCameraDependentEffects();
     }
+
     /**
      * Starts the Babylon.js render loop for the current scene.
      * Waits until the scene is ready before beginning continuous rendering.
@@ -1826,8 +2006,8 @@ export default class BabylonJSController {
     async #startRender() {
         await this.#loadCameraDependentEffects();
         await this.#scene.whenReadyAsync();
-        const frames = this.#settings.antiAliasingEnabled || this.#settings.ambientOcclusionEnabled || this.#settings.iblEnabled ? this.#renderConfig.burstFramesEnhanced : this.#renderConfig.burstFramesBase;
-        this.#requestRender({ frames: frames, continuousMs: this.#renderConfig.interactionMs });
+        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 });
     }
 
     /**
@@ -1906,7 +2086,7 @@ export default class BabylonJSController {
      * Applies material and camera options, sets wall/floor visibility, and initializes lights and shadows.
      * Returns an object with success status and error details.
      */
-    async #loadContainers() {
+    async #loadContainers(force = false) {
         this.#detachAnimationChangedListener();
         await this.#stopRender();
 
@@ -1915,7 +2095,7 @@ export default class BabylonJSController {
 
         const promiseArray = [];
         Object.values(this.#containers).forEach((container) => {
-            promiseArray.push(this.#loadAssetContainer(container));
+            promiseArray.push(this.#loadAssetContainer(container, force));
         });
 
         let detail = {
@@ -2258,17 +2438,41 @@ export default class BabylonJSController {
 
     /**
      * Disposes the Babylon.js engine and disconnects the canvas resize observer.
-     * Cleans up all scene, camera, light, and XR resources.
+     * Cleans up all scene, camera, light, XR, and GLTF resolver resources.
+     * The teardown is asynchronous: it waits for XR/session-dependent shutdown work
+     * before disposing the engine, and coalesces concurrent calls into one in-flight promise.
      * @public
-     * @returns {void}
+     * @returns {Promise<void>}
      */
-    disable() {
-        this.#disableInteraction();
-        this.#disposeAnimationController();
-        this.#disposeXRExperience();
-        this.#unloadCameraDependentEffects();
-        this.#stopEngineRenderLoop();
-        this.#disposeEngine();
+    async disable() {
+        if (this.#disablingPromises.general) {
+            return await this.#disablingPromises.general;
+        }
+
+        this.#disablingPromises.general = (async () => {
+            this.#disableInteraction();
+            this.#disposeAnimationController();
+            this.#disposeGLTFResolver();
+            try {
+                await this.#disposeXRExperience();
+            } catch (error) {
+                console.warn("PrefViewer: Error while disposing XR experience:", error);
+            }
+            try {
+                await this.#unloadCameraDependentEffects();
+            } catch (error) {
+                console.warn("PrefViewer: Error while unloading camera-dependent effects:", error);
+            } finally {
+                this.#stopEngineRenderLoop();
+                this.#disposeEngine();
+            }
+        })();
+
+        try {
+            await this.#disablingPromises.general;
+        } finally {
+            this.#disablingPromises.general = null;
+        }
     }
 
     /**
@@ -2389,8 +2593,8 @@ export default class BabylonJSController {
      * @public
      * @returns {Promise<boolean>} Resolves to true if loading succeeds, false otherwise.
      */
-    async load() {
-        return await this.#loadContainers();
+    async load(force = false) {
+        return await this.#loadContainers(force);
     }
 
     /**
@@ -2425,11 +2629,13 @@ export default class BabylonJSController {
      * @public
      * @returns {boolean} True if IBL options were set successfully, false otherwise.
      */
-    setIBLOptions() {
-        this.#stopRender();
-        const IBLOptionsSetted = this.#setOptions_IBL();
-        this.#startRender();
-        return IBLOptionsSetted;
+    async setIBLOptions() {
+        await this.#stopRender();
+        try {
+            return await this.#setOptions_IBL();
+        } finally {
+            await this.#startRender();
+        }
     }
 
     /**

package/src/file-storage.js

@@ -36,6 +36,7 @@ import { openDB } from "idb";
  *  - getBlob(uri): Retrieves file blob from cache or server.
  *  - get(uri): Gets file from cache with automatic server sync and cache versioning.
  *  - put(uri): Stores file from server in IndexedDB cache.
+ *  - dispose(): Closes the active IndexedDB handle held by the instance.
  *
  * Features:
  *  - Automatic Cache Versioning: Compares server and cached timestamps to update cache.
@@ -105,6 +106,7 @@ import { openDB } from "idb";
  *  - Supports both HTTPS and HTTP (HTTP not recommended for production)
  *  - Object URLs should be revoked after use to free memory
  *  - IndexedDB cache is auto-maintained (TTL, max entries, quota cleanup)
+ *  - Call dispose() when the owner is torn down to release the DB connection proactively.
  *
  * Error Handling:
  *  - Network failures: Returns undefined (get) or false (other methods)
@@ -753,9 +755,12 @@ export default class FileStorage {
         }
         await this.#runCleanupIfDue();
         let storedFile = await this.#getFile(uri);
-        const serverFileTimeStamp = storedFile ? await this.#getServerFileTimeStamp(uri) : 0;
-        const storedFileTimeStamp = storedFile ? storedFile.timeStamp : 0;
-        if (!storedFile || (storedFile && serverFileTimeStamp !== null && serverFileTimeStamp !== storedFileTimeStamp)) {
+        // If there is already a cached file, return it without HEAD revalidation.
+        // In ecommerce flow, new IDs/URLs from WASM drive real resource updates.
+        if (storedFile) {
+            return storedFile;
+        }
+        if (!storedFile) {
             const fileToStore = await this.#getServerFile(uri);
             if (fileToStore && !!(await this.#putFile(fileToStore, uri))) {
                 storedFile = await this.#getFile(uri);
@@ -782,4 +787,19 @@ export default class FileStorage {
         const fileToStore = await this.#getServerFile(uri);
         return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
     }
+
+    /**
+     * Closes the IndexedDB handle held by this storage instance.
+     * Safe to call multiple times; next storage operation will lazily reopen the DB.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#db) {
+            try {
+                this.#db.close();
+            } catch {}
+        }
+        this.#db = undefined;
+    }
 }

package/src/gltf-resolver.js

@@ -1,5 +1,5 @@
 import FileStorage from "./file-storage.js";
-import { initDb, loadModel } from "./gltf-storage.js";
+import { closeDb, initDb, loadModel } from "./gltf-storage.js";
 
 /**
  * GLTFResolver - Utility class for resolving, decoding, and preparing glTF/GLB assets from various sources.
@@ -19,6 +19,7 @@ import { initDb, loadModel } from "./gltf-storage.js";
  * Public Methods:
  *  - getSource(storage, currentSize, currentTimeStamp): Resolves and prepares a glTF/GLB source for loading.
  *  - revokeObjectURLs(objectURLs): Releases temporary blob URLs generated during source resolution.
+ *  - dispose(): Releases resolver resources and closes the internal FileStorage DB handle.
  *
  * Private Methods:
  *  - #initializeStorage(db, table): Ensures IndexedDB store is initialized.
@@ -231,6 +232,17 @@ export default class GLTFResolver {
         objectURLs.length = 0;
     }
 
+    /**
+     * Disposes resolver-owned resources.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        this.#fileStorage?.dispose?.();
+        this.#fileStorage = null;
+        closeDb();
+    }
+
     /**
      * Resolves and prepares a glTF/GLB source from various storage backends.
      * Supports IndexedDB, direct URLs, and base64-encoded data.

package/src/gltf-storage.js

@@ -4,6 +4,8 @@
 const PC = (globalThis.PrefConfigurator ??= {});
 PC.version = PC.version ?? "1.0.1"; // bump if your schema changes!!
 PC.db = PC.db ?? null;
+PC.dbName = PC.dbName ?? null;
+PC.storeName = PC.storeName ?? null;
 
 function _getDbOrThrow() {
     const db = PC.db;
@@ -23,22 +25,50 @@ function _openEnsuringStore(dbName, storeName) {
         }
         open.onupgradeneeded = (ev) => {
             const upgradeDb = ev.target.result;
+            const tx = ev.target.transaction;
 
-            // Eliminar la object store si ya existe
-            if (upgradeDb.objectStoreNames.contains(storeName)) {
-                upgradeDb.deleteObjectStore(storeName);
+            let store;
+            if (!upgradeDb.objectStoreNames.contains(storeName)) {
+                store = upgradeDb.createObjectStore(storeName, { keyPath: 'id' });
+            } else if (tx) {
+                store = tx.objectStore(storeName);
             }
 
-            const store = upgradeDb.createObjectStore(storeName, { keyPath: 'id' });
-            store.createIndex('expirationTimeStamp', 'expirationTimeStamp', { unique: false });
+            if (store && !store.indexNames.contains('expirationTimeStamp')) {
+                store.createIndex('expirationTimeStamp', 'expirationTimeStamp', { unique: false });
+            }
         };
     });
 }
 
+function _isRecoverableDbError(err) {
+    const msg = String(err?.message ?? err ?? "");
+    if (!msg) return false;
+    return msg.includes("Database not initialized") ||
+        msg.includes("The database connection is closing") ||
+        msg.includes("InvalidStateError") ||
+        msg.includes("NotFoundError");
+}
+
+async function _withDbRetry(work) {
+    try {
+        return await work(_getDbOrThrow());
+    } catch (e) {
+        if (!_isRecoverableDbError(e) || !PC.dbName || !PC.storeName) {
+            throw e;
+        }
+        await initDb(PC.dbName, PC.storeName);
+        return await work(_getDbOrThrow());
+    }
+}
+
 // --- public API -------------------------------------------------------------
 
 // Inicializar IndexedDB y dejar el handle en PrefConfigurator.db (público)
 export async function initDb(dbName, storeName) {
+    PC.dbName = dbName;
+    PC.storeName = storeName;
+
     const db = await _openEnsuringStore(dbName, storeName);
     // Close any previous handle to avoid versionchange blocking
     try { PC.db?.close?.(); } catch { }
@@ -54,10 +84,7 @@ export async function initDb(dbName, storeName) {
 
 // Guardar modelo
 export async function saveModel(modelDataStr, storeName) {
-    return new Promise((resolve, reject) => {
-        let db;
-        try { db = _getDbOrThrow(); } catch (e) { reject(e); return; }
-
+    return _withDbRetry((db) => new Promise((resolve, reject) => {
         let modelData;
         try { modelData = JSON.parse(modelDataStr); }
         catch (e) { reject(new Error("saveModel: modelDataStr is not valid JSON")); return; }
@@ -74,22 +101,19 @@ export async function saveModel(modelDataStr, storeName) {
 
         req.onerror = () => reject(req.error);
         req.onsuccess = () => resolve();
-    });
+    }));
 }
 
 // Cargar modelo
 export function loadModel(modelId, storeName) {
-    return new Promise((resolve, reject) => {
-        let db;
-        try { db = _getDbOrThrow(); } catch (e) { reject(e); return; }
-
+    return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readonly");
         const store = tx.objectStore(storeName);
         const req = store.get(modelId);
 
         req.onerror = () => reject(req.error);
         req.onsuccess = () => resolve(req.result ?? null);
-    });
+    }));
 }
 
 // Descargar archivo desde base64
@@ -104,10 +128,7 @@ export function downloadFileFromBytes(fileName, bytesBase64, mimeType) {
 
 // Obtener todos los modelos (solo metadata)
 export async function getAllModels(storeName) {
-    return new Promise((resolve, reject) => {
-        let db;
-        try { db = _getDbOrThrow(); } catch (e) { reject(e); return; }
-
+    return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readonly");
         const store = tx.objectStore(storeName);
         const req = store.getAll();
@@ -124,45 +145,36 @@ export async function getAllModels(storeName) {
             // keep old behavior: return JSON string
             resolve(JSON.stringify(results));
         };
-    });
+    }));
 }
 
 // Eliminar modelo por id
 export async function deleteModel(modelId, storeName) {
-    return new Promise((resolve, reject) => {
-        let db;
-        try { db = _getDbOrThrow(); } catch (e) { reject(e); return; }
-
+    return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readwrite");
         const store = tx.objectStore(storeName);
         const req = store.delete(modelId);
 
         req.onerror = () => reject(req.error);
         req.onsuccess = () => resolve();
-    });
+    }));
 }
 
 // Limpiar toda la store
 export async function clearAll(storeName) {
-    return new Promise((resolve, reject) => {
-        let db;
-        try { db = _getDbOrThrow(); } catch (e) { reject(e); return; }
-
+    return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readwrite");
         const store = tx.objectStore(storeName);
         const req = store.clear();
 
         req.onerror = () => reject(req.error);
         req.onsuccess = () => resolve();
-    });
+    }));
 }
 
 // Borrar modelos expirados usando el índice "expirationTimeStamp"
 export async function cleanExpiredModels(storeName) {
-    return new Promise((resolve, reject) => {
-        let db;
-        try { db = _getDbOrThrow(); } catch (e) { reject(e); return; }
-
+    return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readwrite");
         const store = tx.objectStore(storeName);
 
@@ -182,7 +194,7 @@ export async function cleanExpiredModels(storeName) {
 
         tx.oncomplete = () => resolve();
         tx.onerror = () => reject(tx.error);
-    });
+    }));
 }
 
 // Utilidades opcionales y visibles (por si las quieres usar en consola)

package/src/localization/i18n.js

@@ -40,7 +40,7 @@ export const setLocale = (localeId) => {
         try {
             listener(currentLocale);
         } catch (error) {
-            console.warn("PrefViewer i18n listener failed", error);
+            console.warn("PrefViewer: i18n listener failed", error);
         }
     });
     return currentLocale;

package/src/pref-viewer-3d.js

@@ -75,6 +75,7 @@ export default class PrefViewer3D extends HTMLElement {
     #isInitialized = false;
     #isLoaded = false;
     #isVisible = false;
+    #lastLoadTimestamp = undefined;
 
     #wrapper = null;
     #canvas = null;
@@ -162,7 +163,7 @@ export default class PrefViewer3D extends HTMLElement {
      */
     disconnectedCallback() {
         if (this.#babylonJSController) {
-            this.#babylonJSController.disable();
+            void this.#babylonJSController.disable();
         }
     }
 
@@ -230,6 +231,27 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.enable();
     }
 
+    /**
+     * Determines whether the next 3D load should bypass cache checks.
+     * @private
+     * @param {object} config - Incoming config payload.
+     * @returns {boolean} True when force reload should be enabled.
+     */
+    #shouldForceReload(config) {
+        if (!config || typeof config !== "object") {
+            return false;
+        }
+        if (config.forceReload === true) {
+            return true;
+        }
+        if (config.timestamp === undefined || config.timestamp === null) {
+            return false;
+        }
+        const changed = config.timestamp !== this.#lastLoadTimestamp;
+        this.#lastLoadTimestamp = config.timestamp;
+        return changed;
+    }
+
     /**
      * Resets update flags for all containers and material/camera options after loading or setting options.
      * @private
@@ -558,6 +580,7 @@ export default class PrefViewer3D extends HTMLElement {
         }
 
         this.#onLoading();
+        const forceReload = this.#shouldForceReload(config);
 
         // Containers
         this.#checkNeedToUpdateContainers(config);
@@ -566,10 +589,10 @@ export default class PrefViewer3D extends HTMLElement {
         if (config.options) {
             this.#checkNeedToUpdateCamera(config.options);
             this.#checkNeedToUpdateMaterials(config.options);
-            this.#checkNeedToUpdateIBL(config.options);
+            await this.#checkNeedToUpdateIBL(config.options);
         }
 
-        const loadDetail = await this.#babylonJSController.load();
+        const loadDetail = await this.#babylonJSController.load(forceReload);
 
         return { ...loadDetail, load: this.#onLoaded() };
     }
@@ -579,9 +602,9 @@ export default class PrefViewer3D extends HTMLElement {
      * Updates internal states, triggers option setting events, and returns the result.
      * @public
      * @param {object} options - Options object containing camera and material settings.
-     * @returns {object} Object containing success status and details of set options.
+     * @returns {Promise<object>} Object containing success status and details of set options.
      */
-    setOptions(options) {
+    async setOptions(options) {
         if (!this.#babylonJSController) {
             return;
         }
@@ -595,8 +618,9 @@ export default class PrefViewer3D extends HTMLElement {
         if (this.#checkNeedToUpdateMaterials(options)) {
             someSetted = someSetted || this.#babylonJSController.setMaterialOptions();
         }
-        if (this.#checkNeedToUpdateIBL(options)) {
-            someSetted = someSetted || this.#babylonJSController.setIBLOptions();
+        const needUpdateIBL = await this.#checkNeedToUpdateIBL(options);
+        if (needUpdateIBL) {
+            someSetted = someSetted || (await this.#babylonJSController.setIBLOptions());
         }
         const detail = this.#onSetOptions();
         return { success: someSetted, detail: detail };

package/src/pref-viewer.js

@@ -81,6 +81,7 @@ export default class PrefViewer extends HTMLElement {
         onViewerHoverStart: null,
         onViewerHoverEnd: null,
         on3DSceneLoaded: null,
+        on3DSceneError: null,
     };
 
     /**
@@ -136,6 +137,9 @@ export default class PrefViewer extends HTMLElement {
                 this.loadMaterials(value);
                 break;
             case "mode":
+                if (typeof value !== "string") {
+                    return;
+                }
                 if (_old === value || value.toLowerCase() === this.#mode) {
                     return;
                 }
@@ -151,6 +155,9 @@ export default class PrefViewer extends HTMLElement {
                 this.setOptions(value);
                 break;
             case "show-model":
+                if (typeof value !== "string") {
+                    return;
+                }
                 if (_old === value) {
                     return;
                 }
@@ -158,6 +165,9 @@ export default class PrefViewer extends HTMLElement {
                 showModel ? this.showModel() : this.hideModel();
                 break;
             case "show-scene":
+                if (typeof value !== "string") {
+                    return;
+                }
                 if (_old === value) {
                     return;
                 }
@@ -213,6 +223,7 @@ export default class PrefViewer extends HTMLElement {
         }
         if (this.#component3D) {
             this.#component3D.removeEventListener("scene-loaded", this.#handlers.on3DSceneLoaded);
+            this.#component3D.removeEventListener("scene-error", this.#handlers.on3DSceneError);
             this.#component3D.remove();
         }
         if (this.#menu3D) {
@@ -249,7 +260,11 @@ export default class PrefViewer extends HTMLElement {
             this.#menu3DSyncSettings();
             this.#menu3D?.setApplying(false);
         };
+        this.#handlers.on3DSceneError = () => {
+            this.#menu3D?.setApplying(false, true);
+        };
         this.#component3D.addEventListener("scene-loaded", this.#handlers.on3DSceneLoaded);
+        this.#component3D.addEventListener("scene-error", this.#handlers.on3DSceneError);
         this.#wrapper.appendChild(this.#component3D);
     }
 
@@ -454,7 +469,14 @@ export default class PrefViewer extends HTMLElement {
      * @returns {void}
      */
     #addTaskToQueue(value, type) {
-        this.#taskQueue.push(new PrefViewerTask(value, type));
+        const task = new PrefViewerTask(value, type);
+        if (
+            task.type === PrefViewerTask.Types.Options ||
+            task.type === PrefViewerTask.Types.Drawing
+        ) {
+            this.#taskQueue = this.#taskQueue.filter((queuedTask) => queuedTask.type !== task.type);
+        }
+        this.#taskQueue.push(task);
         if (this.#isInitialized && !this.#isLoading) {
             this.#processNextTask();
         }
@@ -552,6 +574,32 @@ export default class PrefViewer extends HTMLElement {
         this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions));
     }
 
+    /**
+     * Handles 3D load errors.
+     * Clears loading state and dispatches a "scene-error" event.
+     * @private
+     * @param {object} [detail] - Optional details about the failure.
+     * @returns {void}
+     */
+    #on3DError(detail) {
+        this.#isLoaded = false;
+        this.#isLoading = false;
+        this.#menu3D?.setApplying(false, true);
+
+        this.removeAttribute("loading-3d");
+        this.removeAttribute("loaded-3d");
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        if (detail) {
+            customEventOptions.detail = detail;
+        }
+        this.dispatchEvent(new CustomEvent("scene-error", customEventOptions));
+    }
+
     /**
      * Handles the start of a 2D loading operation.
      * Updates loading state, sets attributes, and dispatches a "drawing-loading" event.
@@ -598,6 +646,31 @@ export default class PrefViewer extends HTMLElement {
         this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
     }
 
+    /**
+     * Handles 2D load errors.
+     * Clears loading state and dispatches a "drawing-error" event.
+     * @private
+     * @param {object} [detail] - Optional details about the failure.
+     * @returns {void}
+     */
+    #on2DError(detail) {
+        this.#isLoaded = false;
+        this.#isLoading = false;
+
+        this.removeAttribute("loading-2d");
+        this.removeAttribute("loaded-2d");
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        if (detail) {
+            customEventOptions.detail = detail;
+        }
+        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions));
+    }
+
     /**
      * Handles the "drawing-zoom-changed" event from the 2D viewer component.
      * Dispatches a custom "drawing-zoom-changed" event from the PrefViewer element, forwarding the event detail to external listeners.
@@ -640,16 +713,27 @@ export default class PrefViewer extends HTMLElement {
      * @param {object} config - The configuration object to process.
      * @returns {void}
      */
-    #processConfig(config) {
+    async #processConfig(config) {
         if (!this.#component3D) {
+            this.#processNextTask();
             return;
         }
 
         this.#on3DLoading();
-        this.#component3D.load(config).then((detail) => {
-            this.#on3DLoaded(detail);
+        try {
+            const detail = await this.#component3D.load(config);
+            if (detail?.success === false) {
+                this.#on3DError(detail);
+            } else {
+                this.#on3DLoaded(detail);
+            }
+        } catch (error) {
+            this.#on3DError({
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        } finally {
             this.#processNextTask();
-        });
+        }
     }
 
     /**
@@ -670,16 +754,23 @@ export default class PrefViewer extends HTMLElement {
      * @param {object} drawing - The drawing object to process.
      * @returns {void}
      */
-    #processDrawing(drawing) {
+    async #processDrawing(drawing) {
         if (!this.#component2D) {
+            this.#processNextTask();
             return;
         }
 
         this.#on2DLoading();
-        this.#component2D.load(drawing).then((detail) => {
+        try {
+            const detail = await this.#component2D.load(drawing);
             this.#on2DLoaded(detail);
+        } catch (error) {
+            this.#on2DError({
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        } finally {
             this.#processNextTask();
-        });
+        }
     }
 
     /**
@@ -725,15 +816,23 @@ export default class PrefViewer extends HTMLElement {
      * @param {object} options - The options object to process.
      * @returns {void}
      */
-    #processOptions(options) {
+    async #processOptions(options) {
         if (!this.#component3D) {
+            this.#processNextTask();
             return;
         }
 
         this.#on3DLoading();
-        const detail = this.#component3D.setOptions(options);
-        this.#on3DLoaded(detail);
-        this.#processNextTask();
+        try {
+            const detail = await this.#component3D.setOptions(options);
+            this.#on3DLoaded(detail);
+        } catch (error) {
+            this.#on3DError({
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        } finally {
+            this.#processNextTask();
+        }
     }
 
     /**
@@ -745,6 +844,7 @@ export default class PrefViewer extends HTMLElement {
      */
     #processVisibility(config) {
         if (!this.#component3D) {
+            this.#processNextTask();
             return;
         }
         const showModel = config.model?.visible;
@@ -974,7 +1074,7 @@ export default class PrefViewer extends HTMLElement {
      * @returns {void}
      */
     setMode(mode = this.#mode) {
-        mode = mode.toLowerCase();
+        mode = typeof mode === "string" ? mode.toLowerCase() : this.#mode;
         if (mode !== "2d" && mode !== "3d") {
             console.warn(`PrefViewer: invalid mode "${mode}". Allowed modes are "2d" and "3d".`);
             mode = this.#mode;