@preference-sl/pref-viewer 2.18.0 → 3.0.0-beta.0

package/src/babylonjs-controller.js

@@ -1,4 +1,5 @@
-import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, CubeTexture, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, CubeTexture, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+import BabylonJSARPlacement from "./babylonjs-ar-placement.js";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -11,13 +12,15 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 import BabylonJSViewCubeController from "./babylonjs-view-cube-controller.js";
 import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
 import BabylonJSCameraZoomController from "./babylonjs-camera-zoom-controller.js";
+import BabylonJSOrbitalPointersInput from "./babylonjs-orbital-pointers-input.js";
 import BabylonJSCameraWheelMotion from "./babylonjs-camera-wheel-motion.js";
 import BabylonJSSelectionController from "./babylonjs-selection-controller.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 import I18n from "./localization/i18n.js";
 import { PrefViewerStyleVariables } from "./styles.js";
-import RenderMath from "./render-math.js";
+import BabylonJSRenderMath from "./babylonjs-render-math.js";
 import MaterialUtils from "./material-utils.js";
+import QuickLookAction from "./quick-look-action.js";
 
 /**
  * BabylonJSController coordinates the PrefViewer 3D runtime: it bootstraps Babylon.js, manages asset containers,
@@ -35,8 +38,12 @@ import MaterialUtils from "./material-utils.js";
  *  - Manages keyboard/pointer/wheel handlers, animation menus, and WebXR so PrefViewer menus and DOM attributes stay
  *    synchronized with Babylon state, using sampled pointer picking and last-picked tracking to reduce raycast/highlight
  *    cost on dense scenes.
+ *  - Configures distance-proportional orbital wheel/pinch zoom, with focal-enabled touch pinch following the two-finger midpoint.
  *  - Lazily owns the ViewCube overlay and binds a model-only orbital zoom guard independently of cube visibility.
- *  - Generates GLB, glTF+ZIP, or USDZ exports with timestamped names and localized dialog copy.
+ *  - Generates GLB, glTF+ZIP, or USDZ exports with timestamped names and localized, density-aware download dialogs.
+ *  - Shares cube-and-scan-frame AR artwork between native XR and Quick Look controls.
+ *  - Owns metric WebXR floor placement or an eligible Safari Quick Look action. Prepared native content tracks
+ *    completed model/material state; obsolete asynchronous work cannot publish into a replacement lifecycle.
  *  - Translates metadata (inner floor offsets, cast/receive shadows, camera locks) into scene adjustments after reloads.
  *
  * Runtime Flow
@@ -55,7 +62,7 @@ import MaterialUtils from "./material-utils.js";
  *
  * Public API Highlights
  *  - constructor(canvas, containers, options, viewCubeConfig?)
- *  - setViewCubeEnabled(enabled) / refreshViewCube()
+ *  - setViewCubeEnabled(enabled) / setViewCubeRenderer(renderer) / refreshViewCube()
  *  - enable() / disable()
  *  - load(force?) / reloadWithCurrentSettings()
  *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
@@ -82,13 +89,20 @@ import MaterialUtils from "./material-utils.js";
  *    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 interaction picks; post-input orbital zoom protection separately probes only model meshes.
- *    Right-click POINTERUP performs an on-demand interaction pick for context-menu targeting.
+ *    Right-click POINTERUP and a stationary touch hold perform on-demand animation-menu picking.
+ *    Touch holds consume release selection and are cancelled by navigation, interruption or teardown.
+ *    Touch feedback lasts only while a hold is pending; touch-generated hover cannot retain animation highlights.
  *  - Runtime bookkeeping is split into mutable `#state` and shared tuning settings under `BabylonJSController.config` to keep behavior changes
  *    explicit and reduce cross-field drift.
  *  - Resize lifecycle: canvas resize notifications are throttled (with trailing execution) before calling `engine.resize()`
  *    and any queued resize callback is canceled during teardown.
  *  - Teardown lifecycle: concurrent `disable()` calls are coalesced into a single in-flight promise to avoid races
  *    during XR exit and engine disposal.
+ *  - AR routing is selected internally from confirmed WebXR capability and eligible Safari browser signals.
+ *  - XR lifecycle: entry wakes an idle engine and keeps its frame pump running through session transitions;
+ *    otherwise Babylon cannot request native frames or deliver floor hit tests to placement.
+ *    Transient AR gesture feedback is excluded from all scene/model download formats.
+ *    Optional native plane detection exposes contours for initial footprint fitting when the runtime supports it.
  */
 export default class BabylonJSController {
     // Canvas HTML element
@@ -108,6 +122,11 @@ export default class BabylonJSController {
     #cameraLight = null;
     #shadowGen = [];
     #XRExperience = null;
+    #arPlacement = null;
+    #xrGeneration = 0;
+    #quickLookAction = null;
+    #quickLookLoads = 0;
+    #quickLookValid = { model: false, materials: true };
     #canvasResizeObserver = null;
 
     #hdrTexture = null; // Reusable in-memory HDR source cloned into scene.environmentTexture across reloads
@@ -152,6 +171,9 @@ export default class BabylonJSController {
             lastMovePickY: NaN,
             lastPickedMeshId: null,
             pointerDown: null,
+            touchPointers: new Set(),
+            longPressTimeout: null,
+            touchHighlightActive: false,
         },
         // Render loop state balances performance with responsiveness.
         render: {
@@ -166,6 +188,7 @@ export default class BabylonJSController {
         resize: {
             isScheduled: false,
             timeoutId: null,
+            frameId: null,
             lastAppliedAt: 0,
         },
     };
@@ -175,6 +198,7 @@ export default class BabylonJSController {
      * All instances use this object, including the quality preset updated by hardware detection.
      * render.defaultSettings supplies defaults for each instance's persisted render settings snapshot.
      * Per-instance render and interaction bookkeeping remains in #state.
+     * camera wheel/pinch percentages tune separate native inputs; both scale zoom by the current orbital radius.
      * @public
      * @static
      * @type {object}
@@ -182,6 +206,7 @@ export default class BabylonJSController {
     static config = {
         camera: {
             wheelDeltaPercentage: 0.015,
+            pinchDeltaPercentage: 0.001, // Native pinch uses squared finger separation, unlike wheel deltas
             fitMarginFactor: 0.15, // Total free viewport fraction: 0.15 leaves 85% for the model
             maxRadiusFactor: 4,    // Pull back past the whole model
             minRadiusFactor: 0.25, // ViewCube minimum radius relative to transition distance
@@ -229,6 +254,7 @@ export default class BabylonJSController {
             movePickIntervalMs: 50, // Cap expensive scene.pick calls to ~20 Hz while moving the pointer
             movePickMinDistancePx: 2, // Skip picks for sub-pixel jitter
             clickMaxDistancePx: 6,
+            longPressMs: 500,
         },
         selection: {
             selectableColor: [1, 1, 0],
@@ -531,13 +557,14 @@ export default class BabylonJSController {
      * Constructs a new BabylonJSController instance.
      * Initializes the canvas, asset containers, and options for the Babylon.js scene.
      * @public
-     * @param {HTMLCanvasElement|null} canvas - The canvas element to render the scene on.
-     * @param {object} containers - An object containing container states for model, environment, materials, etc.
-     * @param {object} options - Configuration options for the Babylon.js scene and assets.
+     * @param {HTMLCanvasElement|null} [canvas=null] - The canvas element to render the scene on.
+     * @param {object} [containers={}] - An object containing container states for model, environment, materials, etc.
+     * @param {object} [options={}] - Configuration options for the Babylon.js scene and assets.
      * @param {object} [viewCubeConfig={}] - Internal overlay integration options.
+     * @param {"svg"|"canvas"} [viewCubeConfig.renderer="canvas"] - ViewCube implementation; invalid values select Canvas.
      * @param {boolean} [viewCubeConfig.enabled=true] - Desired activation; creation waits for a live scene and camera.
      * @param {function(): string} [viewCubeConfig.getCulture] - Current UI culture for cube labels.
-     * @param {function(number, number): void} [viewCubeConfig.onLayout] - Measured cube SVG height and scene viewport height in CSS pixels; (0, 0) on disposal.
+     * @param {function(number, number): void} [viewCubeConfig.onLayout] - Measured active ViewCube height and scene viewport height in CSS pixels; (0, 0) on disposal.
      * @returns {BabylonJSController}
      * @description
      *   - Assigns the provided canvas to the controller.
@@ -904,6 +931,7 @@ export default class BabylonJSController {
      * Evaluates whether the renderer should stay in continuous mode.
      * Pending ViewCube transitions and active XR force continuous rendering; animation/camera motion extends the
      * continuous deadline window to avoid abrupt stop-start behavior.
+     * Entering/exiting XR also stays continuous: the native frame pump must survive asynchronous setup and teardown.
      * OPTIMIZATION: Added true idle mode - stops rendering completely after idleThresholdMs of inactivity.
      * @private
      * @param {number} now - Current high-resolution timestamp.
@@ -913,8 +941,8 @@ export default class BabylonJSController {
         if (this.#viewCube?.isAnimating) {
             return true;
         }
-        const inXR = this.#XRExperience?.baseExperience?.state === WebXRState.IN_XR;
-        if (inXR) {
+        const xrState = this.#XRExperience?.baseExperience?.state;
+        if (xrState === WebXRState.ENTERING_XR || xrState === WebXRState.IN_XR || xrState === WebXRState.EXITING_XR) {
             this.#state.render.isIdle = false;
             this.#state.render.lastActivityAt = now;
             return true;
@@ -998,12 +1026,23 @@ export default class BabylonJSController {
     }
 
     /**
-     * Adds custom CSS styles to the Babylon.js AR button for consistent appearance and interaction.
+     * Adds the supplied cube-and-scan-frame SVG and shared interaction styles to native XR and Quick Look buttons.
+     * Preserves the supplied 24-unit geometry and renders its filled paths white against the toggle background.
      * @private
      * @returns {void}
      */
     #addStylesToARButton() {
-        const css = '.babylonVRicon { color: #868686; border-color: #868686; border-style: solid; margin-left: 10px; height: 50px; width: 80px; background-color: rgba(51,51,51,0.7); background-image: url(data:image/svg+xml;charset=UTF-8,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%222048%22%20height%3D%221152%22%20viewBox%3D%220%200%202048%201152%22%20version%3D%221.1%22%3E%3Cpath%20transform%3D%22rotate%28180%201024%2C576.0000000000001%29%22%20d%3D%22m1109%2C896q17%2C0%2030%2C-12t13%2C-30t-12.5%2C-30.5t-30.5%2C-12.5l-170%2C0q-18%2C0%20-30.5%2C12.5t-12.5%2C30.5t13%2C30t30%2C12l170%2C0zm-85%2C256q59%2C0%20132.5%2C-1.5t154.5%2C-5.5t164.5%2C-11.5t163%2C-20t150%2C-30t124.5%2C-41.5q23%2C-11%2042%2C-24t38%2C-30q27%2C-25%2041%2C-61.5t14%2C-72.5l0%2C-257q0%2C-123%20-47%2C-232t-128%2C-190t-190%2C-128t-232%2C-47l-81%2C0q-37%2C0%20-68.5%2C14t-60.5%2C34.5t-55.5%2C45t-53%2C45t-53%2C34.5t-55.5%2C14t-55.5%2C-14t-53%2C-34.5t-53%2C-45t-55.5%2C-45t-60.5%2C-34.5t-68.5%2C-14l-81%2C0q-123%2C0%20-232%2C47t-190%2C128t-128%2C190t-47%2C232l0%2C257q0%2C68%2038%2C115t97%2C73q54%2C24%20124.5%2C41.5t150%2C30t163%2C20t164.5%2C11.5t154.5%2C5.5t132.5%2C1.5zm939%2C-298q0%2C39%20-24.5%2C67t-58.5%2C42q-54%2C23%20-122%2C39.5t-143.5%2C28t-155.5%2C19t-157%2C11t-148.5%2C5t-129.5%2C1.5q-59%2C0%20-130%2C-1.5t-148%2C-5t-157%2C-11t-155.5%2C-19t-143.5%2C-28t-122%2C-39.5q-34%2C-14%20-58.5%2C-42t-24.5%2C-67l0%2C-257q0%2C-106%2040.5%2C-199t110%2C-162.5t162.5%2C-109.5t199%2C-40l81%2C0q27%2C0%2052%2C14t50%2C34.5t51%2C44.5t55.5%2C44.5t63.5%2C34.5t74%2C14t74%2C-14t63.5%2C-34.5t55.5%2C-44.5t51%2C-44.5t50%2C-34.5t52%2C-14l14%2C0q37%2C0%2070%2C0.5t64.5%2C4.5t63.5%2C12t68%2C23q71%2C30%20128.5%2C78.5t98.5%2C110t63.5%2C133.5t22.5%2C149l0%2C257z%22%20fill%3D%22white%22%20/%3E%3C/svg%3E%0A); background-size: 80%; background-repeat:no-repeat; background-position: center; border: none; outline: none; transition: transform 0.125s ease-out } .babylonVRicon:hover { transform: scale(1.05) } .babylonVRicon:active {background-color: rgba(51,51,51,1) } .babylonVRicon:focus {background-color: rgba(51,51,51,1) }.babylonVRicon.vrdisplaypresenting { background-image: none;} .vrdisplaypresenting::after { content: "EXIT"} .xr-error::after { content: "ERROR"}';
+        const icon = `<svg fill="white" version="1.0" id="ar" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="24px" height="24px" viewBox="0 0 24 24" enable-background="new 0 0 24 24" xml:space="preserve">
+<path fill="none" d="M0,0h24v24H0V0z"/>
+<path d="M17,22v-2h3v-3h2v3.5c0,0.39-0.16,0.74-0.46,1.04c-0.3,0.3-0.65,0.46-1.04,0.46H17 M7,22H3.5c-0.39,0-0.74-0.16-1.04-0.46
+	C2.16,21.24,2,20.89,2,20.5V17h2v3h3V22 M17,2h3.5c0.39,0,0.74,0.16,1.04,0.46C21.84,2.76,22,3.11,22,3.5V7h-2V4h-3V2 M7,2v2H4v3H2
+	V3.5c0-0.39,0.16-0.74,0.46-1.04S3.11,2,3.5,2H7 M13,17.25l4-2.3v-4.59l-4,2.3V17.25 M12,10.92l4-2.29l-4-2.35L8,8.63L12,10.92
+	 M7,14.95l4,2.3v-4.59l-4-2.3V14.95 M18.23,7.59C18.73,7.91,19,8.34,19,8.91v6.32c0,0.57-0.27,1-0.77,1.32l-5.48,3.18
+	c-0.5,0.32-1,0.32-1.5,0l-5.48-3.18C5.27,16.23,5,15.8,5,15.23V8.91c0-0.57,0.27-1,0.77-1.32l5.48-3.18
+	c0.25-0.13,0.5-0.19,0.75-0.19s0.5,0.06,0.75,0.19L18.23,7.59z"/>
+</svg>`;
+        const css = `.babylonVRicon { color: #868686; border-color: #868686; border-style: solid; margin-left: 10px; height: 50px; width: 80px; background-color: rgba(51,51,51,0.7); background-image: url(data:image/svg+xml;charset=UTF-8,${encodeURIComponent(icon)}); background-size: 80%; background-repeat:no-repeat; background-position: center; border: none; outline: none; transition: transform 0.125s ease-out } .babylonVRicon:hover { transform: scale(1.05) } .babylonVRicon:active {background-color: rgba(51,51,51,1) } .babylonVRicon:focus {background-color: rgba(51,51,51,1) }.babylonVRicon.vrdisplaypresenting { background-image: none;} .vrdisplaypresenting::after { content: "EXIT"} .xr-error::after { content: "ERROR"}`;
         let style = this.#canvas.parentElement.parentElement.querySelector("style");
         if (!style) {
             style = document.createElement("style");
@@ -1013,66 +1052,172 @@ export default class BabylonJSController {
     }
 
     /**
-     * Creates and initializes the Babylon.js WebXR experience for augmented reality (AR).
+     * Selects an AR candidate from a completed WebXR support query and browser signals.
+     * A failed or pending query is unknown, not permission to use the native fallback.
+     * Native content preparation/opening is a separate step from this decision.
+     * @param {boolean|null} webXRSupported Resolved immersive-ar support, or null if unknown.
+     * @param {object} [browser=globalThis.navigator] Navigator-like browser signals; no GPU-tier inference.
      * @private
-     * @returns {Promise<boolean|void>} Resolves to true if XR experience is created, false if not supported, or void on error.
+     * @returns {"webxr"|"quick-look"|null} Candidate route, not confirmation of native opening.
+     */
+    static #selectARRoute(webXRSupported, browser = globalThis.navigator) {
+        if (webXRSupported === true) {
+            return "webxr";
+        }
+        if (webXRSupported !== false || !browser) {
+            return null;
+        }
+
+        const userAgent = browser.userAgent ?? "";
+        const isIOS = /iPhone|iPad|iPod/.test(userAgent);
+        // iPadOS can request a desktop user agent. MacIntel alone also matches Macs.
+        const isTouchIPad = browser.platform === "MacIntel" && browser.maxTouchPoints > 1;
+        const isSafari = /AppleWebKit\//.test(userAgent) && /Version\//.test(userAgent) && /Safari\//.test(userAgent)
+            && !/CriOS|FxiOS|EdgiOS|OPiOS|Chrome|Chromium|Android/.test(userAgent);
+        return (isIOS || isTouchIPad) && isSafari ? "quick-look" : null;
+    }
+
+    /**
+     * Selects and initializes supported WebXR AR or an eligible Safari Quick Look action.
+     * @private
+     * @returns {Promise<boolean>} True when an AR route is configured, false when unsupported, obsolete or setup fails.
      * @description
-     * Checks for AR session support, creates a hidden ground mesh, and configures session and UI options.
-     * Enables teleportation feature and sets the initial XR camera pose when the session starts.
+     * Checks AR support and requires native floor hit testing at real-world metre scale.
+     * Requests optional plane detection so initial placement can use an observed floor contour when supplied.
+     * Placement follows the tracked XR camera rather than inheriting the showroom camera's fit.
      * Adds custom styles to the AR button for consistent appearance.
-     * If AR is not supported or initialization fails, logs a warning and sets XRExperience to null.
+     * Unsupported or failed XR setup leaves ordinary 3D usable. Obsolete setup owns its own cleanup.
+     * Quick Look prepares current-model USDZ separately; configured routing does not prove native opening.
+     * Native state changes wake the idle engine; transition states keep rendering alive before the first XR frame.
      */
     async #createXRExperience() {
         if (this.#XRExperience) {
             return true;
         }
 
+        const scene = this.#scene;
+        const generation = this.#xrGeneration;
+        /** @returns {boolean} Whether this setup still owns the live scene generation. */
+        const isCurrent = () => this.#scene === scene && this.#xrGeneration === generation && !scene.isDisposed;
         const sessionMode = "immersive-ar";
-        const sessionSupported = await WebXRSessionManager.IsSessionSupportedAsync(sessionMode);
-        if (!sessionSupported) {
-            console.info("PrefViewer: WebXR in mode AR is not supported");
-            return false;
-        }
-
+        let experience = null;
+        let placement = null;
         try {
-            const ground = MeshBuilder.CreateGround("ground", { width: 1000, height: 1000 }, this.#scene);
-            ground.isVisible = false;
+            const sessionSupported = await WebXRSessionManager.IsSessionSupportedAsync(sessionMode);
+            if (!isCurrent()) {
+                return false;
+            }
+            const browser = this.#canvas?.ownerDocument?.defaultView?.navigator ?? globalThis.navigator;
+            const route = BabylonJSController.#selectARRoute(sessionSupported, browser);
+            if (route === "quick-look") {
+                this.#addStylesToARButton();
+                this.#quickLookAction = new QuickLookAction(this.#canvas.parentElement, () => {
+                    const component = this.#canvas.closest("pref-viewer-3d");
+                    const root = component?.getRootNode();
+                    const viewer = root?.host?.matches("pref-viewer") ? root : component?.closest("pref-viewer") ?? component;
+                    return this.#quickLookLoads === 0 && !this.#containers.model?.state?.isPending
+                        && !this.#containers.materials?.state?.isPending
+                        && component?.getAttribute("visible") !== "false" && !viewer?.querySelector("pref-viewer-dialog[open]");
+                }, () => this.#viewCubeConfig.getCulture?.() ?? I18n.getLocale());
+                this.#refreshQuickLook();
+                return true;
+            }
+            if (route !== "webxr") {
+                console.info("PrefViewer: WebXR in mode AR is not supported");
+                return false;
+            }
 
             const options = {
-                floorMeshes: [ground],
+                disableTeleportation: true,
+                disablePointerSelection: true,
+                disableNearInteraction: true,
+                disableHandTracking: true,
+                ignoreNativeCameraTransformation: true,
                 uiOptions: {
                     sessionMode: sessionMode,
                     renderTarget: "xrLayer",
                     referenceSpaceType: "local",
+                    requiredFeatures: ["hit-test"],
+                    optionalFeatures: ["plane-detection"],
                 },
-                optionalFeatures: true,
             };
 
-            this.#XRExperience = await WebXRDefaultExperience.CreateAsync(this.#scene, options);
-
-            const featuresManager = this.#XRExperience.baseExperience.featuresManager;
-            featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
-                xrInput: this.#XRExperience.input,
-                floorMeshes: [ground],
-                timeToTeleport: 1500,
-            });
+            experience = await WebXRDefaultExperience.CreateAsync(scene, options);
+            if (!isCurrent()) {
+                return false;
+            }
 
-            this.#XRExperience.baseExperience.sessionManager.onXRReady.add(() => {
-                // Set the initial position of xrCamera: use nonVRCamera, which contains a copy of the original this.#scene.activeCamera before entering XR
-                this.#XRExperience.baseExperience.camera.setTransformationFromNonVRCamera(this.#XRExperience.baseExperience._nonVRCamera);
-                this.#XRExperience.baseExperience.camera.setTarget(Vector3.Zero());
-                this.#XRExperience.baseExperience.onInitialXRPoseSetObservable.notifyObservers(this.#XRExperience.baseExperience.camera);
+            placement = new BabylonJSARPlacement(scene, experience,
+                () => this.#containers.model?.state?.isVisible && !this.#containers.model.state.isPending
+                    ? this.#containers.model.assetContainer : null,
+                () => this.#containers.environment?.assetContainer);
+
+            experience.baseExperience.onStateChangedObservable.add(() => {
+                // Babylon schedules XR frames only while engine render callbacks are registered.
+                // Clicking its external AR control need not have woken the idle canvas first.
+                if (isCurrent() && this.#XRExperience === experience) {
+                    this.#requestRender({
+                        frames: 1
+                    });
+                }
             });
 
             this.#addStylesToARButton();
+            this.#XRExperience = experience;
+            this.#arPlacement = placement;
+            return true;
         } catch (error) {
             console.warn("PrefViewer: failed to create WebXR experience", error);
-            this.#XRExperience = null;
+            return false;
+        } finally {
+            if (experience !== this.#XRExperience || !experience) {
+                try {
+                    experience?.dispose();
+                } catch (error) {
+                    console.warn("PrefViewer: failed to dispose obsolete WebXR experience", error);
+                } finally {
+                    placement?.dispose();
+                }
+            }
+        }
+    }
+
+    /**
+     * Prepares Quick Look from completed, visible model/material state without changing download helpers.
+     * Invalid or absent content invalidates the link. Only supported visible model meshes are serialized;
+     * asynchronous export ownership, stale results and preparation errors are handled by QuickLookAction.
+     * @private
+     * @returns {void} Starts preparation without waiting for it or changing public task-queue ordering.
+     */
+    #refreshQuickLook() {
+        if (!this.#quickLookAction || this.#quickLookLoads > 0) {
+            return;
+        }
+        const model = this.#containers.model;
+        const asset = model?.assetContainer;
+        if (!this.#scene || !asset || !model.state.isVisible || !this.#quickLookValid.model || !this.#quickLookValid.materials) {
+            this.#quickLookAction.invalidate();
+            return;
+        }
+        /**
+         * Selects current visible geometry supported by the installed USDZ material exporter.
+         * @param {import("@babylonjs/core").AbstractMesh} mesh - Candidate model mesh.
+         * @returns {boolean} Whether the mesh can be included in prepared native content.
+         */
+        const eligible = (mesh) => !!mesh.geometry && mesh.getTotalVertices() > 0
+            && mesh.isVisible !== false && mesh.visibility > 0 && mesh.isEnabled()
+            && ["StandardMaterial", "PBRMaterial", "PBRMetallicRoughnessMaterial"].includes(mesh.material?.getClassName());
+        if (!asset.meshes.some(eligible)) {
+            this.#quickLookAction.invalidate();
+            return;
         }
+        // AssetContainer contains only model meshes; applied materials and world transforms are retained.
+        // No environment, XR ground, ViewCube or utility-scene overlays enter this export.
+        void this.#quickLookAction.update(() => USDZExportAsync(asset, {}, eligible));
     }
 
     /**
-     * Creates the default ArcRotateCamera with unrestricted beta, upright orbit and proportional native wheel zoom.
+     * Creates the default ArcRotateCamera with unrestricted beta, upright orbit and proportional wheel/pinch zoom.
      * Starts at the exact Inner orientation (+Z, alpha/beta pi/2), matching the ViewCube before loading.
      * Starts without a fixed lower radius; the independent model zoom guard supplies the dynamic floor.
      * Imported-camera configuration is applied separately and is not reset here.
@@ -1084,7 +1229,7 @@ export default class BabylonJSController {
         this.#camera.upperBetaLimit = null;
         this.#camera.lowerBetaLimit = null;
         this.#camera.allowUpsideDown = false;
-        this.#camera.wheelDeltaPercentage = BabylonJSController.config.camera.wheelDeltaPercentage;
+        this.#configureOrbitalZoom(this.#camera);
         this.#camera.zoomToMouseLocation = true;
         this.#camera.lowerRadiusLimit = null;
         this.#camera.upperRadiusLimit = 20;
@@ -1107,6 +1252,28 @@ export default class BabylonJSController {
         BabylonJSCameraWheelMotion.focusOnSurface(camera, () => this.#containers.model?.state?.isVisible ? this.#containers.model.assetContainer?.meshes : null);
     }
 
+    /**
+     * Applies distance-proportional native wheel and pinch inputs to an unlocked orbital camera.
+     * Pinch uses its own sensitivity because Babylon measures squared finger separation, not wheel pixels.
+     * Disables natural pinch's direct-radius override so both inputs keep Babylon's inertia and zoom guard.
+     * Shares surface-focused wheel zoom with midpoint-focused pinch when mouse-location zoom is enabled.
+     * Installs accumulated-motion gesture discrimination so slow pinch cannot become premature touch panning.
+     * Combined pan/zoom stays disabled; classification is owned by the pointers input until release or detachment.
+     * @private
+     * @param {ArcRotateCamera} camera - Orbital camera being initialized or selected for interactive navigation.
+     * @returns {void}
+     */
+    #configureOrbitalZoom(camera) {
+        camera.wheelDeltaPercentage = BabylonJSController.config.camera.wheelDeltaPercentage;
+        camera.pinchDeltaPercentage = BabylonJSController.config.camera.pinchDeltaPercentage;
+        camera.useNaturalPinchZoom = false;
+        const pointers = BabylonJSOrbitalPointersInput.install(camera);
+        if (pointers) {
+            pointers.multiTouchPanAndZoom = false;
+            pointers.multiTouchPanning = true;
+        }
+    }
+
     /**
      * Creates and configures the main lights for the Babylon.js scene.
      * Initializes the environment texture if needed.
@@ -1780,16 +1947,16 @@ export default class BabylonJSController {
         }
 
         const showroom = BabylonJSController.config.look?.showroom || {};
-        const timeOfDay = RenderMath.clamp01(this.#renderSettings.lightingTimeOfDay ? this.#renderSettings.lightingTimeOfDay ?? 0.5 : 0.5);
-        const profile = RenderMath.getLightingCycleProfile(timeOfDay);
+        const timeOfDay = BabylonJSRenderMath.clamp01(this.#renderSettings.lightingTimeOfDay ? this.#renderSettings.lightingTimeOfDay ?? 0.5 : 0.5);
+        const profile = BabylonJSRenderMath.getLightingCycleProfile(timeOfDay);
         const daylight = profile.dayFactor;
         const peakLight = daylight > 0 ? Math.pow(daylight, 0.72) : 0;
         const twilight = 1 - peakLight;
 
         if (this.#scene.imageProcessingConfiguration) {
             const imageProcessing = this.#scene.imageProcessingConfiguration;
-            imageProcessing.exposure = RenderMath.lerp(0.78, showroom.exposure ?? 0.92, peakLight);
-            imageProcessing.contrast = RenderMath.lerp(0.98, showroom.contrast ?? 1.02, peakLight);
+            imageProcessing.exposure = BabylonJSRenderMath.lerp(0.78, showroom.exposure ?? 0.92, peakLight);
+            imageProcessing.contrast = BabylonJSRenderMath.lerp(0.98, showroom.contrast ?? 1.02, peakLight);
             imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
             imageProcessing.toneMappingType = showroom.toneMappingType ?? (ImageProcessingConfiguration?.TONEMAPPING_ACES ?? 0);
             imageProcessing.vignetteEnabled = false;
@@ -1800,57 +1967,57 @@ export default class BabylonJSController {
         // HDR off-white. Both are linear already, so no toLinearSpace() on either.
         const bgDay = showroom.backgroundDay ?? BabylonJSController.config.look.showroom.backgroundDay;
         this.#scene.clearColor = new Color4(
-            RenderMath.lerp(0.000627, bgDay[0], daylight),
-            RenderMath.lerp(0.001089, bgDay[1], daylight),
-            RenderMath.lerp(0.004413, bgDay[2], daylight),
+            BabylonJSRenderMath.lerp(0.000627, bgDay[0], daylight),
+            BabylonJSRenderMath.lerp(0.001089, bgDay[1], daylight),
+            BabylonJSRenderMath.lerp(0.004413, bgDay[2], daylight),
             1,
         );
 
         if ("environmentIntensity" in this.#scene) {
-            this.#scene.environmentIntensity = RenderMath.lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
+            this.#scene.environmentIntensity = BabylonJSRenderMath.lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
         }
 
         if (this.#hemiLight) {
             this.#hemiLight.direction = new Vector3(
-                RenderMath.lerp(-0.45, -0.8, peakLight),
-                RenderMath.lerp(0.45, 0.95, peakLight),
-                RenderMath.lerp(-0.75, -0.35, peakLight),
+                BabylonJSRenderMath.lerp(-0.45, -0.8, peakLight),
+                BabylonJSRenderMath.lerp(0.45, 0.95, peakLight),
+                BabylonJSRenderMath.lerp(-0.75, -0.35, peakLight),
             );
-            this.#hemiLight.intensity = RenderMath.lerp(0.18, showroom.hemiLightIntensity ?? 0.52, peakLight);
+            this.#hemiLight.intensity = BabylonJSRenderMath.lerp(0.18, showroom.hemiLightIntensity ?? 0.52, peakLight);
             this.#hemiLight.diffuse = new Color3(
-                RenderMath.lerp(0.42, 0.92, peakLight),
-                RenderMath.lerp(0.48, 0.96, peakLight),
-                RenderMath.lerp(0.62, 0.98, peakLight),
+                BabylonJSRenderMath.lerp(0.42, 0.92, peakLight),
+                BabylonJSRenderMath.lerp(0.48, 0.96, peakLight),
+                BabylonJSRenderMath.lerp(0.62, 0.98, peakLight),
             );
             this.#hemiLight.groundColor = new Color3(
-                RenderMath.lerp(0.08, 0.3, twilight),
-                RenderMath.lerp(0.08, 0.28, twilight),
-                RenderMath.lerp(0.1, 0.22, twilight),
+                BabylonJSRenderMath.lerp(0.08, 0.3, twilight),
+                BabylonJSRenderMath.lerp(0.08, 0.28, twilight),
+                BabylonJSRenderMath.lerp(0.1, 0.22, twilight),
             );
         }
 
         if (this.#dirLight) {
             this.#dirLight.direction = new Vector3(profile.sunDirection.x, profile.sunDirection.y, profile.sunDirection.z);
-            this.#dirLight.intensity = RenderMath.lerp(0.02, showroom.dirLightIntensity ?? 0.56, peakLight);
+            this.#dirLight.intensity = BabylonJSRenderMath.lerp(0.02, showroom.dirLightIntensity ?? 0.56, peakLight);
             this.#dirLight.diffuse = new Color3(
-                RenderMath.lerp(0.28, 1.0, peakLight),
-                RenderMath.lerp(0.3, 0.97, peakLight),
-                RenderMath.lerp(0.34, 0.9, peakLight),
+                BabylonJSRenderMath.lerp(0.28, 1.0, peakLight),
+                BabylonJSRenderMath.lerp(0.3, 0.97, peakLight),
+                BabylonJSRenderMath.lerp(0.34, 0.9, peakLight),
             );
         }
 
         if (this.#moonLight) {
             this.#moonLight.direction = new Vector3(profile.moonDirection.x, profile.moonDirection.y, profile.moonDirection.z);
-            this.#moonLight.intensity = RenderMath.lerp(0.44, 0.03, peakLight);
+            this.#moonLight.intensity = BabylonJSRenderMath.lerp(0.44, 0.03, peakLight);
             this.#moonLight.diffuse = new Color3(0.58, 0.7, 1.0);
         }
 
         if (this.#cameraLight) {
-            this.#cameraLight.intensity = RenderMath.lerp(0.06, showroom.cameraLightIntensity ?? 0.16, peakLight);
+            this.#cameraLight.intensity = BabylonJSRenderMath.lerp(0.06, showroom.cameraLightIntensity ?? 0.16, peakLight);
             this.#cameraLight.diffuse = new Color3(
-                RenderMath.lerp(0.35, 1.0, peakLight),
-                RenderMath.lerp(0.35, 0.97, peakLight),
-                RenderMath.lerp(0.36, 0.92, peakLight),
+                BabylonJSRenderMath.lerp(0.35, 1.0, peakLight),
+                BabylonJSRenderMath.lerp(0.35, 0.97, peakLight),
+                BabylonJSRenderMath.lerp(0.36, 0.92, peakLight),
             );
         }
 
@@ -1872,7 +2039,7 @@ export default class BabylonJSController {
 
         const pixelRatio = typeof window !== "undefined" ? window.devicePixelRatio : 1;
         const baseScaling = BabylonJSController.config.quality.hardwareScaling || 1;
-        const scalingLevel = RenderMath.getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
+        const scalingLevel = BabylonJSRenderMath.getAdaptiveHardwareScalingLevel(baseScaling, pixelRatio);
         this.#engine.setHardwareScalingLevel(scalingLevel);
     }
 
@@ -1934,7 +2101,7 @@ export default class BabylonJSController {
      * The 3D showroom is meant to feel compositionally stable, so we prefer a horizontal-fixed
      * field of view on ArcRotate cameras to avoid the background appearing undersized on wide layouts.
      * @private
-     * @param {Camera|null|undefined} camera - Active camera to adjust.
+     * @param {Camera|null|undefined} [camera] - Active camera to adjust; defaults to the current scene camera.
      * @returns {void}
      */
     #applyShowroomCameraFraming(camera = this.#scene?.activeCamera) {
@@ -1946,11 +2113,13 @@ export default class BabylonJSController {
     }
 
     /**
-     * Resets pointer-picking sampling state.
+     * Resets pointer-picking sampling and active touch state, cancelling any pending animation-menu hold.
      * @private
      * @returns {void}
      */
     #resetPointerPickingState() {
+        this.#cancelTouchMenuHold();
+        this.#state.pointerPicking.touchPointers.clear();
         this.#state.pointerPicking.lastMovePickAt = 0;
         this.#state.pointerPicking.lastMovePickX = NaN;
         this.#state.pointerPicking.lastMovePickY = NaN;
@@ -1996,7 +2165,7 @@ export default class BabylonJSController {
     }
 
     /**
-     * Sets up interaction handlers for the Babylon.js canvas and scene.
+     * Sets up canvas/scene interactions and cancels incomplete gestures when the owning window loses focus.
      * @private
      * @returns {void}
      */
@@ -2004,6 +2173,7 @@ export default class BabylonJSController {
         if (this.#canvas) {
             this.#canvas.addEventListener("keyup", this.#handlers.onKeyUp);
             this.#canvas.addEventListener("pointercancel", this.#handlers.onPointerCancel);
+            this.#canvas.ownerDocument?.defaultView?.addEventListener("blur", this.#handlers.onPointerCancel);
         }
         if (this.#scene) {
             this.#scene.onPointerObservable.add(this.#handlers.onPointerObservable);
@@ -2015,7 +2185,7 @@ export default class BabylonJSController {
     }
 
     /**
-     * Removes interaction event listeners from the Babylon.js canvas.
+     * Removes canvas/scene/window interaction listeners and releases pending gesture/resize resources.
      * @private
      * @returns {void}
      */
@@ -2023,6 +2193,7 @@ export default class BabylonJSController {
         if (this.#canvas) {
             this.#canvas.removeEventListener("keyup", this.#handlers.onKeyUp);
             this.#canvas.removeEventListener("pointercancel", this.#handlers.onPointerCancel);
+            this.#canvas.ownerDocument?.defaultView?.removeEventListener("blur", this.#handlers.onPointerCancel);
         }
         if (this.#scene !== null) {
             this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
@@ -2035,11 +2206,12 @@ export default class BabylonJSController {
     }
 
     /**
-     * Disposes the BabylonJSAnimationController instance if it exists.
+     * Cancels pending touch-menu activation and disposes the animation controller if it exists.
      * @private
      * @returns {void}
      */
     #disposeAnimationController() {
+        this.#cancelTouchMenuHold();
         if (this.#babylonJSAnimationController) {
             this.#babylonJSAnimationController.dispose();
             this.#babylonJSAnimationController = null;
@@ -2063,6 +2235,7 @@ export default class BabylonJSController {
      * 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.
+     * Restores metric-placement transforms and releases owned native hit-test/input observers before disposal.
      * @private
      * @returns {Promise<void>}
      */
@@ -2072,7 +2245,10 @@ export default class BabylonJSController {
         }
 
         const xrExperience = this.#XRExperience;
+        const placement = this.#arPlacement;
         if (!xrExperience) {
+            placement?.dispose();
+            this.#arPlacement = null;
             return;
         }
 
@@ -2084,6 +2260,7 @@ export default class BabylonJSController {
             } catch (error) {
                 console.warn("PrefViewer: Error exiting XR experience:", error);
             } finally {
+                placement?.dispose();
                 try {
                     xrExperience.dispose();
                 } catch (error) {
@@ -2091,6 +2268,7 @@ export default class BabylonJSController {
                 }
                 if (this.#XRExperience === xrExperience) {
                     this.#XRExperience = null;
+                    this.#arPlacement = null;
                 }
                 this.#disablingPromises.xr = null;
             }
@@ -2270,7 +2448,7 @@ export default class BabylonJSController {
     }
 
     /**
-     * Handles pointer move events on the Babylon.js scene.
+     * Handles camera activity and mouse/pen hover; touch-generated moves never enable persistent animation hover.
      * OPTIMIZATION: Tracks activity for idle mode.
      * @private
      * @param {PointerEvent} event - The pointer move event.
@@ -2287,7 +2465,7 @@ export default class BabylonJSController {
         if (camera && !camera.metadata?.locked) {
             this.#requestRender({ frames: 1, continuousMs: BabylonJSController.config.render.interactionMs });
         }
-        if (this.#babylonJSAnimationController && pickInfo) {
+        if (!this.#isTouchPointerEvent(event) && this.#babylonJSAnimationController && pickInfo) {
             const pickedMeshId = pickInfo?.pickedMesh?.id || null;
             if (this.#state.pointerPicking.lastPickedMeshId !== pickedMeshId) {
                 const highlightResult = this.#babylonJSAnimationController.highlightMeshes(pickInfo);
@@ -2299,14 +2477,108 @@ export default class BabylonJSController {
     }
 
     /**
-     * Invalidates an incomplete click gesture when the browser cancels its pointer.
+     * Invalidates incomplete clicks/holds and tracked touches on pointer cancellation or window focus loss.
      * @private
      * @returns {void}
      */
     #onPointerCancel() {
+        this.#cancelTouchMenuHold();
+        this.#state.pointerPicking.touchPointers.clear();
         this.#state.pointerPicking.pointerDown = null;
     }
 
+    /**
+     * Clears the owned long-press timer and temporary touch highlight, preserving selection, camera controls and menu visibility.
+     * @private
+     * @returns {void}
+     */
+    #cancelTouchMenuHold() {
+        clearTimeout(this.#state.pointerPicking.longPressTimeout);
+        this.#state.pointerPicking.longPressTimeout = null;
+        if (this.#state.pointerPicking.touchHighlightActive) {
+            this.#setTouchAnimationHighlight(null);
+        }
+    }
+
+    /**
+     * Identifies direct touch input and compatibility mouse events explicitly marked as touch-generated.
+     * @private
+     * @param {PointerEvent|MouseEvent|null|undefined} event - Current browser pointer event.
+     * @returns {boolean} True when the event must not drive persistent mouse hover.
+     */
+    #isTouchPointerEvent(event) {
+        return event?.pointerType === "touch" || event?.sourceCapabilities?.firesTouchEvents === true;
+    }
+
+    /**
+     * Applies opening-only feedback for a pending touch hold, or clears previous touch/mouse highlight.
+     * Honors the configured highlight preference without changing it; invalidates the hover cache and wakes rendering on changes.
+     * @private
+     * @param {PickingInfo|null} pick - Opening candidate, or null to remove feedback.
+     * @returns {void}
+     */
+    #setTouchAnimationHighlight(pick) {
+        const result = this.#babylonJSAnimationController?.highlightMeshes(this.#renderSettings.highlightEnabled ? pick : null, true);
+        this.#state.pointerPicking.touchHighlightActive = result?.highlighted ?? false;
+        this.#state.pointerPicking.lastPickedMeshId = null;
+        this.#state.pointerPicking.lastMovePickX = NaN;
+        this.#state.pointerPicking.lastMovePickY = NaN;
+        if (result?.changed) {
+            this.#requestRender({
+                frames: 1
+            });
+        }
+    }
+
+    /**
+     * Checks whether current content and UI can accept a touch opening-menu gesture or its temporary feedback.
+     * @private
+     * @returns {boolean} False for missing content, hidden/modal UI, disconnected canvas or an active XR transition/session.
+     */
+    #canUseTouchAnimationMenu() {
+        const component = this.#canvas?.closest("pref-viewer-3d");
+        const viewer = this.#canvas?.closest("pref-viewer");
+        const xrState = this.#XRExperience?.baseExperience?.state;
+        return !!(this.#scene && this.#canvas?.isConnected && this.#babylonJSAnimationController?.hasAnimations()
+            && this.#canvas.ownerDocument.visibilityState !== "hidden" && component?.getAttribute("visible") !== "false"
+            && viewer?.getAttribute("mode") !== "2d" && !viewer?.querySelector("pref-viewer-dialog[open]")
+            && (xrState === undefined || xrState === WebXRState.NOT_IN_XR));
+    }
+
+    /**
+     * Schedules a single-touch context action using the existing click movement tolerance.
+     * Highlights the opening candidate during the pending half-second only, if enabled; early release or cancellation clears it.
+     * Rechecks current content, visible UI and XR eligibility before picking the original CSS touch position.
+     * Recognized holds consume the click and its release; no camera input is prevented or captured here.
+     * @private
+     * @param {PointerEvent} event - Primary touch down on this viewer's canvas.
+     * @returns {void} Owns one cancellable timer until activation, interruption or teardown.
+     */
+    #scheduleTouchMenuHold(event) {
+        this.#cancelTouchMenuHold();
+        const state = this.#state.pointerPicking;
+        const start = state.pointerDown;
+        if (event?.pointerType !== "touch" || !start || state.touchPointers.size !== 1 || !this.#canUseTouchAnimationMenu()) {
+            return;
+        }
+        const rect = this.#canvas.getBoundingClientRect();
+        this.#setTouchAnimationHighlight(this.#scene.pick(start.x - rect.left, start.y - rect.top));
+        state.longPressTimeout = setTimeout(() => {
+            state.longPressTimeout = null;
+            this.#cancelTouchMenuHold();
+            if (state.pointerDown !== start || start.dragged || state.touchPointers.size !== 1 || !this.#canUseTouchAnimationMenu()) {
+                return;
+            }
+            start.longPressed = start.dragged = true;
+            const rect = this.#canvas.getBoundingClientRect();
+            const pick = this.#scene.pick(start.x - rect.left, start.y - rect.top);
+            this.#babylonJSAnimationController.showMenu(pick);
+            this.#requestRender({
+                frames: 1
+            });
+        }, BabylonJSController.config.pointerPicking.longPressMs);
+    }
+
     /**
      * Emits the internal 3D click contract for every model mesh crossed by the pointer ray.
      * @private
@@ -2344,6 +2616,8 @@ 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.
+     * Recognizes stationary primary touch holds independently of short-click selection; release preserves their menu.
+     * Touch motion skips hover raycasts; touch down clears stale hover before starting temporary hold feedback.
      * @private
      * @param {PointerInfo} info - The pointer event information from Babylon.js.
      * @returns {void}
@@ -2351,26 +2625,47 @@ export default class BabylonJSController {
     #onPointerObservable(info) {
         if (info.type === PointerEventTypes.POINTERMOVE) {
             const start = this.#state.pointerPicking.pointerDown;
-            if (start && (info.event?.pointerId !== start.pointerId || (info.event?.buttons & 1) === 0
-                || Math.hypot(info.event?.clientX - start.x, info.event?.clientY - start.y) > BabylonJSController.config.pointerPicking.clickMaxDistancePx)) {
+            if (start && (info.event?.pointerId !== start.pointerId || (info.event?.buttons & 1) === 0 || Math.hypot(info.event?.clientX - start.x, info.event?.clientY - start.y) > BabylonJSController.config.pointerPicking.clickMaxDistancePx)) {
                 start.dragged = true;
+                this.#cancelTouchMenuHold();
             }
             let pickInfo = null;
             let lastPickedMeshId = null;
-            if (this.#shouldPickOnPointerMove()) {
+            if (!this.#isTouchPointerEvent(info.event) && 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.POINTERDOWN) {
-            this.#state.pointerPicking.pointerDown = info.event?.button === 0 && !this.#state.pointerPicking.pointerDown
-                ? { x: info.event.clientX, y: info.event.clientY, button: info.event.button, pointerId: info.event.pointerId }
-                : null;
+            this.#cancelTouchMenuHold();
+            if (this.#isTouchPointerEvent(info.event)) {
+                this.#setTouchAnimationHighlight(null);
+            }
+            if (info.event?.pointerType === "touch") {
+                this.#state.pointerPicking.touchPointers.add(info.event.pointerId);
+            }
+            this.#state.pointerPicking.pointerDown = info.event?.button === 0 && info.event.isPrimary !== false && this.#state.pointerPicking.touchPointers.size <= 1 && !this.#state.pointerPicking.pointerDown ? {
+                x: info.event.clientX,
+                y: info.event.clientY,
+                button: info.event.button,
+                pointerId: info.event.pointerId
+            } : null;
+            this.#scheduleTouchMenuHold(info.event);
         } else if (info.type === PointerEventTypes.POINTERUP) {
+            this.#cancelTouchMenuHold();
+            this.#state.pointerPicking.touchPointers.delete(info.event?.pointerId);
             const pointerDown = this.#state.pointerPicking.pointerDown;
             this.#state.pointerPicking.pointerDown = null;
-            const pointerUp = { x: info.event?.clientX, y: info.event?.clientY, button: info.event?.button, pointerId: info.event?.pointerId };
+            if (pointerDown?.longPressed && pointerDown.pointerId === info.event?.pointerId) {
+                return;
+            }
+            const pointerUp = {
+                x: info.event?.clientX,
+                y: info.event?.clientY,
+                button: info.event?.button,
+                pointerId: info.event?.pointerId
+            };
             if (BabylonJSSelectionController.isPrimaryClickGesture(pointerDown, pointerUp, BabylonJSController.config.pointerPicking.clickMaxDistancePx)) {
                 this.#emitModelMeshClick();
             }
@@ -2386,6 +2681,7 @@ export default class BabylonJSController {
 
     /**
      * Applies a pending engine resize, cancels cube navigation and wakes rendering.
+     * Skips zero-sized hidden canvases to prevent intrinsic-buffer/DPR growth; a visible resize retries later.
      * @private
      * @param {number} elapsed - Time since the previous resize, retained for diagnostics.
      * @returns {void}
@@ -2396,6 +2692,12 @@ export default class BabylonJSController {
         if (!this.#engine) {
             return;
         }
+        // Babylon falls back to the intrinsic canvas size for hidden elements, then applies
+        // DPR again. Repeated hidden resizes can exponentially grow GPU attachments on WebKit.
+        // ResizeObserver will notify us again when the canvas has a visible CSS size.
+        if (!this.#canvas.clientWidth || !this.#canvas.clientHeight) {
+            return;
+        }
         this.#state.resize.lastAppliedAt = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         console.log(`PrefViewer: Applying resize after ${Math.round(elapsed)}ms`);
         this.#applyShowroomCameraFraming();
@@ -2531,6 +2833,7 @@ export default class BabylonJSController {
      * Handles canvas resize notifications.
      * Resizes the Babylon engine and requests a short on-demand render burst so camera-dependent
      * buffers and post-process pipelines are redrawn at the new viewport size.
+     * Coalesces notifications through a throttled timer and animation frame, outside ResizeObserver delivery.
      * @private
      * @returns {void}
      */
@@ -2542,28 +2845,33 @@ export default class BabylonJSController {
         const elapsed = now - this.#state.resize.lastAppliedAt;
 
 
-        if (elapsed >= BabylonJSController.config.resize.throttleMs) {
-            this.#applyResize(elapsed);
-            return;
-        }
-
         if (this.#state.resize.isScheduled) {
             return;
         }
 
         this.#state.resize.isScheduled = true;
+        // Mutating canvas buffers/layout inside ResizeObserver delivery causes WebKit's
+        // "undelivered notifications" loop. Apply before the next paint instead.
         const waitMs = Math.max(0, BabylonJSController.config.resize.throttleMs - elapsed);
         this.#state.resize.timeoutId = setTimeout(() => {
-            this.#applyResize(elapsed);
+            this.#state.resize.timeoutId = null;
+            this.#state.resize.frameId = requestAnimationFrame(() => {
+                this.#state.resize.frameId = null;
+                this.#applyResize(elapsed);
+            });
         }, waitMs);
     }
 
     /**
-     * Clears any queued throttled resize callback.
+     * Clears both the queued throttle timer and animation-frame resize callback during teardown.
      * @private
      * @returns {void}
      */
     #cancelScheduledResize() {
+        if (this.#state.resize.frameId != null) {
+            cancelAnimationFrame(this.#state.resize.frameId);
+        }
+        this.#state.resize.frameId = null;
         if (this.#state.resize.timeoutId !== null) {
             clearTimeout(this.#state.resize.timeoutId);
         }
@@ -2639,7 +2947,7 @@ export default class BabylonJSController {
 
     /**
      * Cancels pending cube navigation and applies configured camera selection and locking.
-     * Configures unlocked orbital cameras for proportional native wheel input, rebinds the model zoom guard
+     * Configures unlocked orbital cameras for proportional native wheel/pinch input, rebinds the model zoom guard
      * and synchronizes the cube after selecting the active camera.
      * A missing named camera falls back to the unlocked default camera, rather than retaining an imported view.
      * @private
@@ -2694,7 +3002,7 @@ export default class BabylonJSController {
         camera.detachControl();
         if (!cameraState.locked) {
             if (camera instanceof ArcRotateCamera) {
-                camera.wheelDeltaPercentage = BabylonJSController.config.camera.wheelDeltaPercentage;
+                this.#configureOrbitalZoom(camera);
             }
             camera.attachControl(this.#canvas, true);
         }
@@ -3000,11 +3308,13 @@ export default class BabylonJSController {
      * Loads a single asset container (model, environment, materials, etc.) based on the container state flags.
      * Skips work when nothing is pending, otherwise resolves the GLTF source, refreshes cache metadata and streams it
      * into the Babylon.js scene via `LoadAssetContainerAsync`.
+     * Distinguishes unchanged content from a failed replacement for native AR readiness and revokes source URLs
+     * after attempted imports. Resolver failures may reject; Babylon import errors are logged and returned as null.
      * @private
      * @param {object} container - Container descriptor that carries the GLTF storage pointer and current cache info.
      * @param {boolean} [force=false] - When true, bypasses cached size/timestamp so the resolver re-downloads the asset.
-     * @returns {Promise<[object, AssetContainer|boolean]>} Resolves to `[container, assetContainer]` on success, or
-     * `[container, false]` when loading was skipped or failed.
+     * @returns {Promise<[object, AssetContainer|false|null]>} Container paired with imported assets, false for skipped,
+     * unchanged or unresolved content, or null after a caught import failure.
      * @description
      * 1. Validates that the container has pending data and initializes the shared `GLTFResolver` if needed.
      * 2. Requests the source blob (respecting the cached size/timestamp unless `force` is set) and stores the new cache
@@ -3028,7 +3338,18 @@ export default class BabylonJSController {
         const currentSize = force ? 0 : container.state.size;
         const currentTimeStamp = force ? null : container.state.timeStamp;
 
-        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, currentSize, currentTimeStamp);
+        const isQuickLookContent = container.state.name === "model" || container.state.name === "materials";
+        if (isQuickLookContent) {
+            this.#quickLookValid[container.state.name] = false;
+        }
+        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, currentSize, currentTimeStamp, true);
+
+        if (sourceData?.unchanged) {
+            if (isQuickLookContent) {
+                this.#quickLookValid[container.state.name] = !!container.assetContainer;
+            }
+            return [container, false];
+        }
 
         if (!sourceData) {
             return [container, false];
@@ -3070,6 +3391,7 @@ export default class BabylonJSController {
     /**
      * Cancels pending cube navigation, loads asset containers and adds replacements to the scene.
      * Current model selection is resolved by the zoom guard on subsequent input updates.
+     * Invalidates native content during overlapping loads, then prepares only completed current-model content.
      * @private
      * @param {boolean} [force=false] - Whether to bypass existing asset cache metadata.
      * @returns {Promise<{success: boolean, error: any}>} Resolves to an object indicating if loading succeeded and any error encountered.
@@ -3079,6 +3401,29 @@ export default class BabylonJSController {
      * Returns an object with success status and error details.
      */
     async #loadContainers(force = false) {
+        this.#quickLookAction?.invalidate();
+        this.#quickLookLoads += 1;
+        try {
+            const result = await this.#loadContainersInternal(force);
+            if (!result.success) {
+                this.#quickLookValid.materials = false;
+            }
+            return result;
+        } finally {
+            this.#quickLookLoads -= 1;
+            this.#refreshQuickLook();
+        }
+    }
+
+    /**
+     * Loads pending containers in parallel, replaces scene assets and reapplies material/camera/light state.
+     * Cancels cube/animation work, stops rendering during changes and restarts it after setup. Disposed scenes
+     * discard late assets; successful model/material replacements update Quick Look content-validity state.
+     * @private
+     * @param {boolean} [force=false] - Whether to bypass cached source size/timestamp checks.
+     * @returns {Promise<{success: boolean, error: *}>} Aggregate scene-load result and any captured setup error.
+     */
+    async #loadContainersInternal(force = false) {
         this.#viewCube?.cancel();
         this.#resetPointerPickingState();
         this.#detachAnimationChangedListener();
@@ -3125,6 +3470,9 @@ export default class BabylonJSController {
                         }
                         this.#replaceContainer(container, assetContainer);
                         container.state.setSuccess(true);
+                        if (container.state.name === "model" || container.state.name === "materials") {
+                            this.#quickLookValid[container.state.name] = true;
+                        }
                     } else {
                         if (container.assetContainer && container.state.mustBeShown !== container.state.isVisible && container.state.name === "materials") {
                             container.state.mustBeShown ? this.#addContainer(container) : this.#removeContainer(container);
@@ -3345,6 +3693,7 @@ export default class BabylonJSController {
 
     /**
      * Opens a modal dialog for downloading the 3D scene, model, or environment.
+     * Uses shared dialog presentation and wrapping option groups; preserves export choices and routing.
      * @private
      * @returns {void}
      */
@@ -3358,15 +3707,15 @@ export default class BabylonJSController {
         const texts = I18n.translate("prefViewer.downloadDialog", locale ? { locale } : undefined) || {};
         const header = texts.title || "Download 3D Scene";
         const content = `
-            <form slot="content" id="download-dialog-form" style="display:flex;flex-direction:column;gap:16px;">
+            <form slot="content" id="download-dialog-form" class="download-dialog-form">
                 <h4>${texts.sections?.content || "Content"}</h4>
-                <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
+                <div class="download-dialog-options">
                     <label><input type="radio" name="content" value="1"> ${texts.options?.model || "Model"}</label>
                     <label><input type="radio" name="content" value="2"> ${texts.options?.scene || "Scene"}</label>
                     <label><input type="radio" name="content" value="0" checked> ${texts.options?.both || "Both"}</label>
                 </div>
                 <h4>${texts.sections?.format || "Format"}</h4>
-                <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
+                <div class="download-dialog-options">
                 <label><input type="radio" name="format" value="gltf" checked> glTF (ZIP)</label>
                     <label><input type="radio" name="format" value="glb"> GLB</label>
                     <label><input type="radio" name="format" value="usdz"> USDZ</label>
@@ -3416,7 +3765,7 @@ export default class BabylonJSController {
      */
 
     /**
-     * Creates the enabled cube once a live scene/camera exists and teardown is not in progress.
+     * Creates the selected SVG/Canvas cube once a live scene/camera exists and teardown is not in progress.
      * Resolves camera/model state through callbacks; does not reload assets or camera options.
      * @private
      * @returns {void}
@@ -3435,7 +3784,7 @@ export default class BabylonJSController {
             onLayout: this.#viewCubeConfig.onLayout,
             // A cube drag is pointer interaction like a main-canvas drag: keep the loop continuous for the same window.
             requestRender: (options) => this.#requestRender({ frames: 2, continuousMs: options?.interaction ? BabylonJSController.config.render.interactionMs : 0 }),
-        });
+        }, this.#viewCubeConfig.renderer);
     }
 
     /**
@@ -3444,10 +3793,15 @@ export default class BabylonJSController {
      * Observes canvas resize events, binds model-only orbital zoom protection and adaptive default-camera near clipping,
      * and lazily creates the requested cube. Imported camera clipping is preserved by the host policy.
      * Aborts remaining initialization if the scene was replaced/disposed during texture readiness.
+     * Waits for preceding teardown and guards XR route creation with the current scene generation.
      * @public
      * @returns {Promise<void>}
      */
     async enable() {
+        if (this.#disablingPromises.general) {
+            await this.#disablingPromises.general;
+        }
+        const enabledGeneration = ++this.#xrGeneration;
         this.#configureDracoCompression();
         this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false }, true);
         this.#engine.disableUniformBuffers = true;
@@ -3490,7 +3844,7 @@ export default class BabylonJSController {
         this.#initializeViewCube();
         const enabledScene = this.#scene;
         await this.#ensureEnvironmentBRDFTextureReady();
-        if (!this.#engine || this.#scene !== enabledScene) {
+        if (!this.#engine || this.#scene !== enabledScene || this.#xrGeneration !== enabledGeneration) {
             return;
         }
         this.#enableInteraction();
@@ -3503,10 +3857,16 @@ export default class BabylonJSController {
      * floor and suspending cube creation until the next enable. Cleans up light, XR and resolver resources.
      * The teardown is asynchronous: it waits for XR/session-dependent shutdown work
      * before disposing the engine, and coalesces concurrent calls into one in-flight promise.
+     * Immediately invalidates pending XR setup and disposes the Quick Look action before awaiting teardown.
      * @public
      * @returns {Promise<void>}
      */
     async disable() {
+        // Invalidate pending support/setup before the first teardown await, even while the scene is live.
+        this.#xrGeneration += 1;
+        this.#quickLookAction?.dispose();
+        this.#quickLookAction = null;
+        this.#quickLookValid = { model: false, materials: true };
         BabylonJSCameraWheelMotion.cancel(this.#scene?.activeCamera);
         BabylonJSCameraWheelMotion.cancel(this.#camera);
         BabylonJSCameraWheelMotion.releaseSurfaceFocus(this.#camera);
@@ -3564,18 +3924,30 @@ export default class BabylonJSController {
     }
 
     /**
-     * Synchronizes the existing cube after culture or camera-state changes without creating an inactive cube.
+     * Selects the cube implementation while preserving the active scene, camera and asset state.
+     * @param {"svg"|"canvas"} renderer - Per-viewer preference; invalid values use Canvas.
+     * @returns {void} Disabled cubes retain preference without allocating a new overlay.
+     */
+    setViewCubeRenderer(renderer) {
+        this.#viewCubeConfig.renderer = BabylonJSViewCubeController.normalizeRenderer(renderer);
+        this.#viewCube?.setRenderer(this.#viewCubeConfig.renderer);
+    }
+
+    /**
+     * Resizes/synchronizes the existing cube after culture, camera or presentation changes without activating it.
+     * Also refreshes the existing Quick Look action's localized label from the host culture.
      * @public
      * @returns {void}
      */
     refreshViewCube() {
-        this.#viewCube?.sync();
+        this.#quickLookAction?.refreshCulture();
+        this.#viewCube?.resize();
     }
 
     /**
      * Applies the host-owned semantic selection state to the current model meshes.
      * @public
-     * @param {object} state - Canonical PrefViewer selection snapshot.
+     * @param {object} [state={}] - Canonical PrefViewer selection snapshot.
      * @returns {void}
      */
     applySelectionState(state = {}) {
@@ -3583,9 +3955,9 @@ export default class BabylonJSController {
     }
 
     /**
-     * Downloads the current scene, model, or environment as a GLB file.
+     * Downloads the current scene, model, or environment as a GLB file, excluding transient AR feedback.
      * @public
-     * @param {number} content - 0 for full scene, 1 for model, 2 for environment.
+     * @param {number} [content=0] - 0 for full scene, 1 for model, 2 for environment.
      * @returns {void}
      */
     downloadGLB(content = 0) {
@@ -3608,7 +3980,8 @@ export default class BabylonJSController {
                 break;
         }
         fileName = this.#addDateToName(fileName);
-        GLTF2Export.GLBAsync(container, fileName, { exportWithoutWaitingForScene: true }).then((glb) => {
+        GLTF2Export.GLBAsync(container, fileName, { exportWithoutWaitingForScene: true,
+            shouldExportNode: node => !node.metadata?.prefViewerARFeedback }).then((glb) => {
             if (glb) {
                 glb.downloadFiles();
             }
@@ -3616,9 +3989,9 @@ export default class BabylonJSController {
     }
 
     /**
-     * Downloads the current scene, model, or environment as a glTF ZIP file.
+     * Downloads the current scene, model, or environment as a glTF ZIP file, excluding transient AR feedback.
      * @public
-     * @param {number} content - 0 for full scene, 1 for model, 2 for environment.
+     * @param {number} [content=0] - 0 for full scene, 1 for model, 2 for environment.
      * @returns {void}
      */
     downloadGLTF(content = 0) {
@@ -3645,7 +4018,8 @@ export default class BabylonJSController {
                 break;
         }
         comment += "\nPrefViewer by Preference, S.L.\npreference.com\n";
-        GLTF2Export.GLTFAsync(container, fileName, { exportWithoutWaitingForScene: true }).then((gltf) => {
+        GLTF2Export.GLTFAsync(container, fileName, { exportWithoutWaitingForScene: true,
+            shouldExportNode: node => !node.metadata?.prefViewerARFeedback }).then((gltf) => {
             if (gltf?.files) {
                 this.#downloadZip(gltf.files, fileName, comment, true);
             }
@@ -3653,9 +4027,9 @@ export default class BabylonJSController {
     }
 
     /**
-     * Downloads the current scene, model, or environment as a USDZ file.
+     * Downloads the current scene, model, or environment as a USDZ file, excluding transient AR feedback.
      * @public
-     * @param {number} content - 0 for full scene, 1 for model, 2 for environment.
+     * @param {number} [content=0] - 0 for full scene, 1 for model, 2 for environment.
      * @returns {void}
      */
     downloadUSDZ(content = 0) {
@@ -3678,7 +4052,7 @@ export default class BabylonJSController {
                 break;
         }
         fileName = this.#addDateToName(fileName);
-        USDZExportAsync(container).then((response) => {
+        USDZExportAsync(container, undefined, mesh => !mesh.metadata?.prefViewerARFeedback).then((response) => {
             if (response) {
                 Tools.Download(new Blob([response], { type: "model/vnd.usdz+zip" }), `${fileName}.usdz`);
             }
@@ -3698,7 +4072,8 @@ export default class BabylonJSController {
      * Returns a diagnostic snapshot of the current Babylon.js runtime state.
      * Intended for integration troubleshooting and should not mutate scene state.
      * @public
-     * @returns {object} Debug information for canvas, engine, scene, containers, render loop and settings.
+     * @returns {object} Canvas, engine, scene, container, render-loop and settings diagnostics, plus nullable
+     * `ar` placement state, metric distance/position and drag/model availability when WebXR is configured.
      */
     getDebugInfo() {
 
@@ -3737,6 +4112,7 @@ export default class BabylonJSController {
 
 
         return {
+            ar: this.#arPlacement?.getDebugInfo() ?? null,
             canvas: {
                 clientWidth: this.#canvas?.clientWidth ?? null,
                 clientHeight: this.#canvas?.clientHeight ?? null,
@@ -3833,13 +4209,16 @@ export default class BabylonJSController {
     /**
      * Applies material options from the configuration to the relevant meshes.
      * Stops and restarts the render loop to apply changes.
+     * Invalidates native content during the update and requests fresh Quick Look preparation after render readiness.
      * @public
      * @returns {boolean} True if material options were set successfully, false otherwise.
      */
     setMaterialOptions() {
+        this.#quickLookAction?.invalidate();
         this.#stopRender();
         const materialsOptionsSetted = this.#setOptions_Materials();
-        this.#startRender();
+        void this.#startRender().then(() => this.#refreshQuickLook())
+            .catch(error => console.warn("PrefViewer: failed to prepare material rendering", error));
         return materialsOptionsSetted;
     }
 
@@ -3864,7 +4243,7 @@ export default class BabylonJSController {
      * When `showLightingTimeOfDay` is set to false and no explicit `lightingTimeOfDay` is supplied,
      * the active lighting time is reset to `BabylonJSController.config.render.defaultSettings.lightingTimeOfDay` (0.5).
      * @public
-     * @param {object} config - Immediate render/illumination configuration.
+     * @param {object} [config={}] - Immediate render/illumination configuration.
      * @param {boolean|string} [config.showAnimationMenu] - Enables/disables the animation controls when animations are available.
      * @param {boolean|string|null} [config.highlightEnabled] - Enables/disables hover highlight; string "false" is normalized to false, null is ignored.
      * @param {string|null} [config.highlightColor] - Hex color used by hover highlight; null is ignored.
@@ -3896,7 +4275,7 @@ export default class BabylonJSController {
         }
 
         if (typeof config.lightingTimeOfDay === "number" && Number.isFinite(config.lightingTimeOfDay)) {
-            const normalizedTime = RenderMath.clamp01(config.lightingTimeOfDay);
+            const normalizedTime = BabylonJSRenderMath.clamp01(config.lightingTimeOfDay);
             if (this.#renderSettings.lightingTimeOfDay !== normalizedTime) {
                 this.#renderSettings.lightingTimeOfDay = normalizedTime;
                 shouldApplyLighting = true;
@@ -3947,6 +4326,8 @@ export default class BabylonJSController {
      * Sets the visibility of a container (model, environment, etc.) by name.
      * Adds or removes the container from the scene and updates wall/floor visibility.
      * Restarts the render loop to apply changes.
+     * Refreshes Quick Look readiness after rendering so hidden model content cannot retain an active native link.
+     * Render/preparation failures are logged asynchronously; this method does not wait for native preparation.
      * @public
      * @param {string} name - The name of the container to show or hide.
      * @param {boolean} show - True to show the container, false to hide it.
@@ -3964,7 +4345,8 @@ export default class BabylonJSController {
         this.#stopRender();
         show ? this.#addContainer(container) : this.#removeContainer(container);
         this.#setVisibilityOfWallAndFloorInModel();
-        this.#startRender();
+        void this.#startRender().then(() => this.#refreshQuickLook())
+            .catch(error => console.warn("PrefViewer: failed to prepare visibility rendering", error));
     }
 
     /**
@@ -3973,7 +4355,7 @@ export default class BabylonJSController {
      * Immediate settings such as highlight, animation menu, and time-of-day lighting are handled by
      * `setIlluminationConfig()` before this method receives the remaining reload settings.
      * @public
-     * @param {{antiAliasingEnabled?:boolean, ambientOcclusionEnabled?:boolean, iblEnabled?:boolean, shadowsEnabled?:boolean}} settings Partial set of reload render toggles to apply.
+     * @param {{antiAliasingEnabled?:boolean, ambientOcclusionEnabled?:boolean, iblEnabled?:boolean, shadowsEnabled?:boolean}} [settings={}] Partial set of reload render toggles to apply.
      * @returns {{changed:boolean, settings:object}} Current full render settings snapshot and whether a reload is required.
      * @description
      * Callers can inspect the `changed` flag to decide whether to trigger a reload with
@@ -4042,9 +4424,9 @@ export default class BabylonJSController {
     }
 
     /**
-     * Configures the highlight settings for animated nodes on hover.
+     * Configures animation highlights for mouse hover and pending touch holds.
      * @private
-     * @param {{enabled?: boolean, color?: string}} config - Configuration object.
+     * @param {{enabled?: boolean, color?: string}} [config={}] - Configuration object.
      * @returns {void}
      */
     #setHighlightConfig(config = {}) {