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

package/src/babylonjs-ar-placement.js

@@ -0,0 +1,1038 @@
+import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import { TransformNode } from "@babylonjs/core/Meshes/transformNode.js";
+import { Ray } from "@babylonjs/core/Culling/ray.js";
+import { WebXRState } from "@babylonjs/core/XR/webXRTypes.js";
+import BabylonJSCameraFraming from "./babylonjs-camera-framing.js";
+import BabylonJSARFloorBounds from "./babylonjs-ar-floor-bounds.js";
+import BabylonJSARGlass from "./babylonjs-ar-glass.js";
+import BabylonJSARPlacementFeedback from "./babylonjs-ar-placement-feedback.js";
+
+/**
+ * Owns metric model placement, gesture feedback, two-finger yaw and one-finger translation inside a Babylon native AR session.
+ * After native floor detection, touch rays translate on that retained plane without fresh hit subscriptions.
+ * Model drags preserve their initial offset; short off-model taps reposition the bottom anchor.
+ * Uses plane hit tests and a unit-scale parent to retain authored glTF dimensions, with Inner (+Z)
+ * initially snapped to the nearest detected-floor axis orientation from its phone-facing pose. Source units/orientation remain the asset producer's responsibility.
+ * Retains detected floor height within the same reference space while waiting for a usable phone heading.
+ * Prefers a full-footprint fit up to three metres on an observed contour; otherwise provisionally uses three metres.
+ * The initial floor position is chosen once; later contour growth cannot move a placed model.
+ * Without a qualifying floor, previews the model centre two metres along the first valid view ray at authored scale.
+ * Retains that world pose without following the camera; native tracking drift can still affect apparent size/position.
+ * The preview cannot be dragged or used for physical measurement; floor evidence enables spatial placement.
+ * Records bounded session and drag diagnostics, retaining gesture rejection reasons after release.
+ * Temporarily hides the environment, reparents model roots and adapts physical model glass to alpha blending.
+ * Exit/cancellation restores authored transforms and exact original material values; shared textures remain owned by the model.
+ * Contains native hit-source and world-scale cleanup errors so Babylon can restore its camera and render loop.
+ * Call dispose() before releasing the owning scene to remove observers and native input resources.
+ */
+export default class BabylonJSARPlacement {
+    #scene;
+    #manager;
+    #getModel;
+    #getEnvironment;
+    #observers = [];
+    #session = null;
+    #generation = 0;
+    #active = false;
+    #disposed = false;
+    #state = "inactive";
+    #floorSource = null;
+    #floorEvidence = null;
+    #previousWorldScale = null;
+    #asset = null;
+    #root = null;
+    #roots = [];
+    #environment = new Map();
+    #glass = new BabylonJSARGlass();
+    #pivot = null;
+    #centre = null;
+    #footprintCorners = [];
+    #previewSpace = null;
+    #target = null;
+    #rotation = null;
+    #touches = new Set();
+    #blockedGesture = false;
+    #drag = null;
+    #turn = null;
+    #feedback;
+    #diagnostics = this.#createDiagnostics();
+    static #INITIAL_DISTANCE = 3;
+    static #TAP_ANGLE_COS = Math.cos(Math.PI / 180);
+
+    /**
+     * Creates bounded placement, contour/pose-only floor-axis evidence and drag counters, retaining the latest gesture outcome until the next session.
+     * @private
+     * @returns {object} Fresh mutable state; no frame history or native resources are retained.
+     */
+    #createDiagnostics() {
+        return { frames: 0, trackedFrames: 0, phase: "inactive", hitTestStatus: "not-requested",
+            lastHitCount: 0, maxHitCount: 0, lastSurface: null, lastError: null, ended: false,
+            floorAlignmentSource: "not-placed", floorAlignmentStatus: "not-placed", floorAlignmentYaw: null,
+            floorAlignmentHeightDifference: null, initialYaw: null,
+            placementDistance: null, placementStatus: "not-placed", detectedPlaneCount: 0, floorBoundsStatus: "not-queried",
+            drag: { selectStarts: 0, selectEnds: 0, lastInputMode: null, status: "no-input",
+                hitTestStatus: "not-requested", frames: 0, lastHitCount: 0, moves: 0,
+                pickedMesh: null, lastError: null } };
+    }
+
+    /**
+     * Subscribes to XR lifecycle and owns lazy gesture feedback without starting a session or changing the scene yet.
+     * @param {import("@babylonjs/core").Scene} scene - Scene containing the authored assets.
+     * @param {import("@babylonjs/core").WebXRDefaultExperience} experience - Native XR lifecycle owner.
+     * @param {function(): ?import("@babylonjs/core").AssetContainer} getModel - Current usable model, or null while unavailable.
+     * @param {function(): ?import("@babylonjs/core").AssetContainer} [getEnvironment] - Current environment; defaults to returning null.
+     */
+    constructor(scene, experience, getModel, getEnvironment = () => null) {
+        this.#scene = scene;
+        this.#feedback = new BabylonJSARPlacementFeedback(scene);
+        this.#manager = experience.baseExperience.sessionManager;
+        this.#getModel = getModel;
+        this.#getEnvironment = getEnvironment;
+        this.#observe(experience.baseExperience.onStateChangedObservable, state => {
+            if (state === WebXRState.ENTERING_XR) {
+                this.#begin();
+            }
+            if (state === WebXRState.NOT_IN_XR) {
+                this.#end();
+            }
+        });
+        this.#observe(this.#manager.onXRSessionInit, session => { void this.#start(session); });
+        this.#observe(this.#manager.onXRSessionEnded, () => this.#end());
+        this.#observe(this.#manager.onXRFrameObservable, frame => this.#frame(frame));
+    }
+
+    /**
+     * Registers a Babylon observer and retains its handle for disposal.
+     * @private
+     * @param {import("@babylonjs/core").Observable<*>} observable - Lifecycle or frame event stream.
+     * @param {function(*): void} callback - Handler invoked by that stream.
+     * @returns {void}
+     */
+    #observe(observable, callback) {
+        this.#observers.push([observable, observable.add(callback)]);
+    }
+
+    /**
+     * Resets prior placement and hides content until a valid camera pose permits a metric preview or floor placement.
+     * Starts fresh diagnostic counters; the previous attempt remains inspectable only until this reset.
+     * @private
+     * @returns {void}
+     */
+    #begin() {
+        this.#end();
+        this.#diagnostics = this.#createDiagnostics();
+        this.#diagnostics.phase = "waiting-session";
+        this.#active = true;
+        this.#state = "detecting-floor";
+        this.#syncModel();
+        this.#hideEnvironment();
+    }
+
+    /**
+     * Sets metre-scale XR, binds native input and requests a viewer-space plane hit-test source.
+     * Late sources are cancelled; rejected requests retain a stationary initial preview without floor dragging.
+     * Records request stages and native error name/message for remote troubleshooting.
+     * Source cancellation tolerates resources invalidated by session termination, including late results.
+     * Sets the manager's scale only when a change is needed, avoiding redundant native camera updates.
+     * @private
+     * @param {XRSession} session - Newly initialized native immersive-ar session.
+     * @returns {Promise<void>} Resolves after setup, cancellation or a logged native request failure.
+     */
+    async #start(session) {
+        if (this.#disposed) {
+            return;
+        }
+        if (!this.#active) {
+            this.#begin();
+        }
+        const generation = ++this.#generation;
+        this.#session = session;
+        this.#previousWorldScale = this.#manager.worldScalingFactor;
+        if (this.#manager.worldScalingFactor !== 1) {
+            this.#manager.worldScalingFactor = 1;
+        }
+        session.addEventListener("selectstart", this.#selectStart);
+        session.addEventListener("selectend", this.#selectEnd);
+        session.addEventListener("inputsourceschange", this.#inputsChanged);
+        try {
+            this.#diagnostics.hitTestStatus = "requesting-viewer-space";
+            const space = await session.requestReferenceSpace("viewer");
+            if (this.#session !== session || generation !== this.#generation) {
+                return;
+            }
+            this.#diagnostics.hitTestStatus = "requesting-hit-test";
+            const source = await session.requestHitTestSource({ space, entityTypes: ["plane"] });
+            if (this.#session !== session || generation !== this.#generation) {
+                this.#cancelHitTestSource(source);
+            } else {
+                this.#floorSource = source;
+                this.#diagnostics.hitTestStatus = "ready";
+            }
+        } catch (error) {
+            if (this.#session === session && generation === this.#generation) {
+                if (!this.#target) {
+                    this.#state = "unavailable";
+                }
+                this.#diagnostics.hitTestStatus = "error";
+                this.#diagnostics.lastError = {
+                    name: error?.name ?? "Error",
+                    message: error?.message ?? String(error)
+                };
+                console.warn("PrefViewer: AR floor hit testing unavailable", error);
+            }
+        }
+    }
+
+    /**
+     * Converts a native right-handed pose into the scene's handedness without scaling it.
+     * @private
+     * @param {XRPose} pose - Native pose relative to the manager's reference space.
+     * @returns {Matrix} A new scene-space transformation matrix.
+     */
+    #matrix(pose) {
+        const matrix = Matrix.FromArray(pose.transform.matrix);
+        if (!this.#scene.useRightHandedSystem) {
+            matrix.toggleModelMatrixHandInPlace();
+        }
+        return matrix;
+    }
+
+    /**
+     * Finds a finite, upward horizontal hit below the phone; hit tests cannot identify semantic floor.
+     * Records the latest checked surface and the exact rejection reason without changing the acceptance filter.
+     * @private
+     * @param {XRHitTestResult[]} results - Native plane hits for the current frame.
+     * @param {number} viewerY - Tracked phone height in scene-space metres.
+     * @returns {?Vector3} First acceptable hit position, or null when no plane qualifies.
+     */
+    #floorPoint(results, viewerY) {
+        for (const result of results) {
+            const pose = result.getPose(this.#manager.referenceSpace);
+            if (!pose) {
+                this.#diagnostics.lastSurface = {
+                    reason: "pose-unavailable",
+                    position: null,
+                    normal: null,
+                    viewerY
+                };
+                continue;
+            }
+            const matrix = this.#matrix(pose);
+            const point = matrix.getTranslation();
+            const up = Vector3.TransformNormal(Vector3.Up(), matrix).normalize();
+            // Reject walls, ceilings and invalid tracking data. The runtime supplies the plane;
+            // it cannot identify semantic "floor" on every Android device.
+            const reason = ![point.x, point.y, point.z].every(Number.isFinite) ? "invalid-position" : !(up.y >= 0.95) ? "not-horizontal" : !(point.y < viewerY) ? "not-below-camera" : "accepted";
+            this.#diagnostics.lastSurface = {
+                reason,
+                position: {
+                    x: point.x,
+                    y: point.y,
+                    z: point.z
+                },
+                normal: {
+                    x: up.x,
+                    y: up.y,
+                    z: up.z
+                },
+                viewerY
+            };
+            if (reason === "accepted") {
+                return point;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Attaches the current model to an owned unit-scale pivot while preserving authored transforms.
+     * Retains centre/bottom pivots and the original world bounding corners for preview/floor footprint alignment.
+     * Replacement retains the current anchor; missing content stays hidden until usable again.
+     * Cancels input and feedback when content disappears or is replaced.
+     * Syncs reversible glass overrides on referenced mesh materials, including swaps during an active session.
+     * @private
+     * @returns {void}
+     */
+    #syncModel() {
+        const asset = this.#getModel();
+        if (!asset) {
+            this.#cancelDrag();
+            this.#glass.restore();
+            this.#root?.setEnabled(false);
+            return;
+        }
+        if (asset !== this.#asset) {
+            this.#releaseModel();
+            const bounds = BabylonJSCameraFraming.getModelBounds(asset);
+            if (!bounds) {
+                return;
+            }
+            this.#asset = asset;
+            this.#pivot = new Vector3(bounds.center.x, Math.min(...bounds.corners.map(v => v.y)), bounds.center.z);
+            this.#centre = bounds.center.clone();
+            this.#footprintCorners = bounds.corners.map(corner => corner.clone());
+            this.#root = new TransformNode("PrefViewerARPlacement", this.#scene);
+            const nodes = new Set([...(asset.meshes ?? []), ...(asset.transformNodes ?? [])]);
+            for (const node of nodes) {
+                if (node.parent && nodes.has(node.parent)) {
+                    continue;
+                }
+                const snapshot = {
+                    node,
+                    parent: node.parent,
+                    position: node.position.clone(),
+                    rotation: node.rotation.clone(),
+                    quaternion: node.rotationQuaternion?.clone(),
+                    scaling: node.scaling.clone()
+                };
+                this.#roots.push(snapshot);
+                if (node.parent) {
+                    node.setParent(this.#root, true);
+                } else {
+                    node.parent = this.#root;
+                }
+            }
+        }
+        this.#glass.sync(asset);
+        this.#applyPlacement();
+        this.#root.setEnabled(this.#target !== null);
+    }
+
+    /**
+     * Hides current environment roots, remembering their original local enabled states for exit.
+     * @private
+     * @returns {void}
+     */
+    #hideEnvironment() {
+        const asset = this.#getEnvironment();
+        const nodes = new Set([...(asset?.meshes ?? []), ...(asset?.transformNodes ?? [])]);
+        for (const node of nodes) {
+            if (node.parent && nodes.has(node.parent)) {
+                continue;
+            }
+            if (!this.#environment.has(node)) {
+                this.#environment.set(node, node.isEnabled(false));
+            }
+            node.setEnabled(false);
+        }
+    }
+
+    /**
+     * Applies yaw and translation so the model centre meets the preview anchor, or its bottom meets a real floor anchor.
+     * Leaves all model and unit-conversion scales unchanged; does nothing before placement exists.
+     * @private
+     * @returns {void}
+     */
+    #applyPlacement() {
+        if (!this.#root || !this.#target) {
+            return;
+        }
+        this.#root.rotationQuaternion = this.#rotation.clone();
+        // Unit-scale parent: only yaw and translation, including source offsets and centre/bottom alignment.
+        const rotation = Matrix.Identity();
+        this.#rotation.toRotationMatrix(rotation);
+        const rotatedPivot = Vector3.TransformCoordinates(this.#state === "preview" ? this.#centre : this.#pivot, rotation);
+        this.#root.position.copyFrom(this.#target.subtract(rotatedPivot));
+        this.#root.computeWorldMatrix(true);
+    }
+
+    /**
+     * Places an upright, unit-scale preview once, centred two metres along the first valid camera ray.
+     * Retains its world position and yaw through camera movement/tracking loss within the same reference space.
+     * Does not compensate native drift, fabricate floor height or enable dragging; physical anchoring remains unverified.
+     * A missing model defers preview creation. The caller must supply a finite camera transform.
+     * @private
+     * @param {Matrix} view - Camera pose in scene coordinates, including pitch and roll.
+     * @returns {void}
+     */
+    #preview(view) {
+        if (this.#target || !this.#root) {
+            return;
+        }
+        const forward = Vector3.TransformNormal(new Vector3(0, 0, this.#scene.useRightHandedSystem ? -1 : 1), view).normalize();
+        const heading = new Vector3(forward.x, 0, forward.z);
+        if (heading.lengthSquared() <= 1e-8) {
+            const right = Vector3.TransformNormal(Vector3.Right(), view);
+            heading.set(-right.z, 0, right.x);
+            if (this.#scene.useRightHandedSystem) {
+                heading.negateInPlace();
+            }
+        }
+        this.#target = view.getTranslation().add(forward.scale(2));
+        this.#rotation = Quaternion.RotationYawPitchRoll(Math.atan2(-heading.x, -heading.z), 0, 0);
+        this.#previewSpace = this.#manager.referenceSpace;
+        this.#state = "preview";
+        this.#applyPlacement();
+        this.#root.setEnabled(true);
+    }
+
+    /**
+     * Reads placement hits, retiring a failing native source so the camera preview can still render.
+     * Records the actual error once; does not synthesize a surface or retry a rejected source.
+     * An already-invalid source cannot interrupt retirement or the subsequent preview frame.
+     * @private
+     * @param {XRFrame} frame - Current active native frame.
+     * @returns {XRHitTestResult[]} Native plane results, or an empty list after a native read error.
+     */
+    #readFloorHits(frame) {
+        try {
+            return frame.getHitTestResults(this.#floorSource);
+        } catch (error) {
+            this.#cancelHitTestSource(this.#floorSource);
+            this.#floorSource = null;
+            this.#diagnostics.hitTestStatus = "error";
+            this.#diagnostics.lastError = { name: error?.name ?? "Error", message: error?.message ?? String(error) };
+            console.warn("PrefViewer: AR floor hit results unavailable", error);
+            return [];
+        }
+    }
+
+    /**
+     * Places once up to three horizontal metres ahead where the model fits an observed floor contour.
+     * Missing/too-small contours use a provisional three-metre floor placement; later contours do not reposition it.
+     * Creates a stationary preview while floor evidence/setup is absent or rejected, without following the camera.
+     * Missing tracking retains the last pose; interaction remains on the originally detected floor height.
+     * Remembers actual floor evidence while the phone points vertically; a changed reference space discards it.
+     * Counts delivered/tracked frames and native placement hits, recording the current wait stage.
+     * Retires the floor source without allowing native cancellation errors to interrupt placement/rendering.
+     * Expires confirmation feedback and processes two-finger yaw; hides feedback on tracking loss.
+     * Updates the selected finger on the known floor plane, even without fresh hits or when other surfaces occlude it.
+     * @private
+     * @param {XRFrame} frame - Active native XR frame, valid only during its callback.
+     * @returns {void}
+     */
+    #frame(frame) {
+        if (!this.#active) {
+            return;
+        }
+        this.#feedback.update();
+        this.#diagnostics.frames++;
+        this.#diagnostics.phase = "waiting-session";
+        if (!this.#session) {
+            return;
+        }
+        this.#diagnostics.phase = "waiting-reference-space";
+        if (!this.#manager.referenceSpace) {
+            this.#cancelDrag();
+            return;
+        }
+        if (this.#state === "placed" && this.#floorEvidence?.space !== this.#manager.referenceSpace) {
+            this.#cancelDrag();
+        }
+        if (this.#state === "preview" && this.#previewSpace !== this.#manager.referenceSpace) {
+            this.#target = this.#rotation = null;
+            this.#state = "detecting-floor";
+        }
+        this.#diagnostics.phase = "syncing-content";
+        this.#syncModel();
+        this.#hideEnvironment();
+        this.#diagnostics.phase = "waiting-tracking";
+        const viewer = frame.getViewerPose(this.#manager.referenceSpace);
+        if (!viewer) {
+            this.#feedback.hide();
+            if (this.#turn) {
+                this.#cancelDrag();
+            }
+            if (this.#drag) {
+                this.#drag.tracked = false;
+                if (this.#drag.mode === "tap") {
+                    this.#drag.moved = true;
+                }
+            }
+            return;
+        } // Tracking loss must not cause a new placement or scale change.
+        const view = this.#matrix(viewer);
+        if (!Array.from(view.m).every(Number.isFinite)) {
+            this.#feedback.hide();
+            if (this.#turn) {
+                this.#cancelDrag();
+            }
+            if (this.#drag) {
+                this.#drag.tracked = false;
+                if (this.#drag.mode === "tap") {
+                    this.#drag.moved = true;
+                }
+            }
+            return;
+        }
+        this.#diagnostics.trackedFrames++;
+        this.#diagnostics.phase = this.#state === "placed" ? "placed" : "waiting-hit-test";
+        const camera = view.getTranslation();
+        if (this.#state !== "placed" && this.#floorSource) {
+            if (this.#floorEvidence?.space !== this.#manager.referenceSpace) {
+                this.#floorEvidence = null;
+            }
+            this.#diagnostics.phase = "reading-hit-results";
+            const results = this.#readFloorHits(frame);
+            this.#diagnostics.lastHitCount = results.length;
+            this.#diagnostics.maxHitCount = Math.max(this.#diagnostics.maxHitCount, results.length);
+            this.#diagnostics.phase = "checking-surfaces";
+            const point = this.#floorPoint(results, camera.y);
+            if (point) {
+                this.#floorEvidence = {
+                    height: point.y,
+                    point: point.clone(),
+                    space: this.#manager.referenceSpace
+                };
+            }
+            this.#diagnostics.phase = !this.#floorEvidence ? "waiting-floor" : !this.#root ? "waiting-model" : "waiting-heading";
+            const forward = Vector3.TransformNormal(new Vector3(0, 0, this.#scene.useRightHandedSystem ? -1 : 1), view);
+            forward.y = 0;
+            if (this.#root && this.#floorEvidence && this.#floorEvidence.height < camera.y && forward.lengthSquared() > 1e-8) {
+                forward.normalize();
+                this.#placeOnFloor(frame, camera, forward);
+            }
+        }
+        this.#preview(view);
+        if (this.#turn) {
+            this.#updateTurn(frame);
+        } else {
+            this.#updateDrag(frame);
+        }
+    }
+
+    /**
+     * Chooses initial placement once, snapping phone-facing yaw by the minimum quarter-turn to matched floor axes.
+     * Native plane yaw is selected independently of footprint fitting; reference axes are used only without a usable pose.
+     * Matching contours take priority over the nearest horizontal pose below the camera; height/distance are not changed.
+     * Fits the original authored footprint after snapping, and freezes the same axes for feedback.
+     * Fits the entire horizontal bounding footprint on the camera's forward segment, preferring three metres.
+     * With no usable contour or fit, preserves visibility at three metres without claiming a bounded fit.
+     * @private
+     * @param {XRFrame} frame - Active frame supplying optional detected planes in the current reference space.
+     * @param {Vector3} camera - Finite tracked camera position in scene-space metres.
+     * @param {Vector3} forward - Normalized horizontal camera direction.
+     * @returns {void} Sets detached fit diagnostics, reveals the model and retires only the initial native hit source.
+     */
+    #placeOnFloor(frame, camera, forward) {
+        const bounds = BabylonJSARFloorBounds.getFloorPolygons(frame, this.#manager.referenceSpace,
+            this.#floorEvidence.point, this.#scene.useRightHandedSystem, camera.y);
+        const floorYaw = bounds.alignment?.yaw ?? 0;
+        const facing = Math.atan2(-forward.x, -forward.z);
+        const difference = Math.atan2(Math.sin(facing - floorYaw), Math.cos(facing - floorYaw));
+        const yaw = floorYaw + Math.round(difference / (Math.PI / 2)) * (Math.PI / 2);
+        this.#rotation = Quaternion.RotationYawPitchRoll(yaw, 0, 0);
+        this.#feedback.setFloorYaw(floorYaw);
+        this.#diagnostics.floorAlignmentSource = bounds.alignment ? "detected-plane" : "reference-space";
+        this.#diagnostics.floorAlignmentStatus = bounds.alignment?.status ?? "reference-space";
+        this.#diagnostics.floorAlignmentHeightDifference = bounds.alignment?.heightDifference ?? null;
+        this.#diagnostics.floorAlignmentYaw = floorYaw;
+        this.#diagnostics.initialYaw = yaw;
+        const rotation = Matrix.Identity();
+        this.#rotation.toRotationMatrix(rotation);
+        const footprint = this.#footprintCorners.map(corner => Vector3.TransformCoordinates(corner.subtract(this.#pivot), rotation));
+        let fittedDistance = null;
+        for (const polygon of bounds.polygons) {
+            const candidate = BabylonJSARFloorBounds.getPlacementDistance(polygon, footprint, camera, forward, BabylonJSARPlacement.#INITIAL_DISTANCE);
+            if (candidate !== null && (fittedDistance === null || candidate > fittedDistance)) {
+                fittedDistance = candidate;
+            }
+        }
+        const distance = fittedDistance ?? BabylonJSARPlacement.#INITIAL_DISTANCE;
+        this.#diagnostics.placementDistance = distance;
+        this.#diagnostics.placementStatus = fittedDistance !== null ? "bounded-fit"
+            : bounds.polygons.length ? "provisional-no-fit" : "provisional-no-contour";
+        this.#diagnostics.floorBoundsStatus = bounds.status;
+        this.#diagnostics.detectedPlaneCount = bounds.planeCount;
+        this.#target = camera.add(forward.scale(distance));
+        this.#target.y = this.#floorEvidence.height;
+        this.#state = "placed";
+        this.#diagnostics.phase = "placed";
+        this.#cancelHitTestSource(this.#floorSource);
+        this.#floorSource = null;
+        this.#applyPlacement();
+        this.#root.setEnabled(true);
+    }
+
+    /**
+     * Builds a scene-space ray from the selected screen input in the current XR reference space.
+     * @private
+     * @param {XRFrame} frame - Active native animation or selection frame.
+     * @param {XRInputSource} input - Finger whose pose is queried; other fingers are ignored.
+     * @returns {?Ray} Finite normalized ray, or null when input tracking is unavailable.
+     */
+    #inputRay(frame, input) {
+        const pose = frame.getPose(input.targetRaySpace, this.#manager.referenceSpace);
+        if (!pose) {
+            return null;
+        }
+        const matrix = this.#matrix(pose);
+        if (!Array.from(matrix.m).every(Number.isFinite)) {
+            return null;
+        }
+        const direction = Vector3.TransformNormal(new Vector3(0, 0, this.#scene.useRightHandedSystem ? -1 : 1), matrix).normalize();
+        return new Ray(matrix.getTranslation(), direction);
+    }
+
+    /**
+     * Intersects a forward touch ray with the horizontal plane of the previously detected floor.
+     * Never invents floor height, follows another level, or projects horizon/behind-camera rays.
+     * @private
+     * @param {Ray} ray - Finite scene-space touch ray.
+     * @returns {?Vector3} Floor point in metres, or null for parallel, backward or invalid intersections.
+     */
+    #floorIntersection(ray) {
+        if (!this.#target || this.#floorEvidence?.space !== this.#manager.referenceSpace
+            || Math.abs(ray.direction.y) <= 1e-6) {
+            return null;
+        }
+        const distance = (this.#target.y - ray.origin.y) / ray.direction.y;
+        if (!(distance >= 0) || !Number.isFinite(distance)) {
+            return null;
+        }
+        const point = ray.origin.add(ray.direction.scale(distance));
+        point.y = this.#target.y;
+        return [point.x, point.y, point.z].every(Number.isFinite) ? point : null;
+    }
+
+    /**
+     * Applies horizontal translation only, preserving authored scale, placed height and yaw.
+     * @private
+     * @param {Vector3} point - Desired bottom-anchor coordinates on the retained plane.
+     * @param {string} status - Diagnostic outcome for drag or tap placement.
+     * @returns {void} Updates bounded movement counters and the owned placement pivot.
+     */
+    #moveOnFloor(point, status) {
+        if (this.#target.x !== point.x || this.#target.z !== point.z) {
+            this.#diagnostics.drag.moves++;
+        }
+        this.#target.x = point.x;
+        this.#target.z = point.z;
+        this.#diagnostics.drag.status = status;
+        this.#applyPlacement();
+    }
+
+    /**
+     * Samples the owned finger on the detected floor without requesting additional native hit sources.
+     * Model drags retain their grab offset. Off-model taps are candidates until release; one degree of
+     * ray movement cancels tap placement, including a movement that later returns to its starting point.
+     * Shows a candidate reticle or directional drag arrows; invalid input hides them.
+     * Missing/invalid poses retain position and prevent stale tap commits; reference-space changes cancel ownership.
+     * @private
+     * @param {XRFrame} frame - Active frame supplying the selected finger pose.
+     * @returns {void} Contains pose failures so later XR observers remain usable.
+     */
+    #updateDrag(frame) {
+        const drag = this.#drag;
+        if (!drag) {
+            return;
+        }
+        if (drag.space !== this.#manager.referenceSpace) {
+            this.#diagnostics.drag.status = "reference-space-changed";
+            this.#cancelDrag();
+            return;
+        }
+        const diagnostics = this.#diagnostics.drag;
+        diagnostics.frames++;
+        try {
+            const ray = this.#inputRay(frame, drag.input);
+            drag.tracked = !!ray;
+            if (!ray) {
+                this.#feedback.hide();
+                if (drag.mode === "tap") {
+                    drag.moved = true;
+                }
+                diagnostics.status = "missing-input-pose";
+                return;
+            }
+            if (Vector3.Dot(drag.direction, ray.direction) < BabylonJSARPlacement.#TAP_ANGLE_COS) {
+                drag.moved = true;
+            }
+            const point = this.#floorIntersection(ray);
+            drag.point = point;
+            if (!point) {
+                this.#feedback.hide();
+                if (drag.mode === "tap") {
+                    drag.moved = true;
+                }
+                diagnostics.status = "no-floor-intersection";
+                return;
+            }
+            if (drag.mode === "tap") {
+                diagnostics.status = drag.moved ? "tap-cancelled" : "tap-pending";
+                if (drag.moved) {
+                    this.#feedback.hide();
+                } else {
+                    this.#feedback.show("tap", point);
+                }
+                return;
+            }
+            if (!drag.offset) {
+                drag.offset = this.#target.subtract(point);
+            }
+            const previous = this.#target.clone();
+            this.#moveOnFloor(point.add(drag.offset), "dragging");
+            this.#feedback.show("drag", this.#target, this.#target.subtract(previous));
+        } catch (error) {
+            this.#failDrag(error, "read-input-pose");
+        }
+    }
+
+    /**
+     * Reads two native screen rays in viewer coordinates and applies only their wrapped angular delta as yaw.
+     * Common translation/pinch does not change scale or anchor. Coincident rays and lost poses cancel ownership.
+     * Inverts the former two-finger direction while preserving handedness. Passes the applied signed yaw to directional feedback. Rotation retains the model bottom pivot; all fingers must lift before a new translation is accepted.
+     * @private
+     * Only animation frames permit getViewerPose; selection events must defer sampling to the XR loop.
+     * @param {XRFrame} frame - Active XR animation frame; native poses are never retained.
+     * @returns {void} Contains pose errors and hides stale feedback on cancellation.
+     */
+    #updateTurn(frame) {
+        const turn = this.#turn;
+        try {
+            if (turn.space !== this.#manager.referenceSpace || !this.#root?.isEnabled()) {
+                this.#cancelDrag();
+                return;
+            }
+            const viewer = frame.getViewerPose(this.#manager.referenceSpace);
+            if (!viewer) {
+                this.#cancelDrag();
+                return;
+            }
+            const inverse = this.#matrix(viewer).invert();
+            const points = turn.inputs.map(input => {
+                const ray = this.#inputRay(frame, input);
+                if (!ray) {
+                    return null;
+                }
+                const direction = Vector3.TransformNormal(ray.direction, inverse);
+                const depth = direction.z * (this.#scene.useRightHandedSystem ? -1 : 1);
+                return depth > 1e-6 ? { x: direction.x / depth, y: direction.y / depth } : null;
+            });
+            if (points.some(point => !point) || Math.hypot(points[1].x - points[0].x, points[1].y - points[0].y) < .005) {
+                this.#diagnostics.drag.status = "rotation-pose-unavailable";
+                this.#cancelDrag();
+                return;
+            }
+            const angle = Math.atan2(points[1].y - points[0].y, points[1].x - points[0].x);
+            let yawDelta = 0;
+            if (turn.angle !== null) {
+                const delta = Math.atan2(Math.sin(angle - turn.angle), Math.cos(angle - turn.angle));
+                yawDelta = delta * (this.#scene.useRightHandedSystem ? 1 : -1);
+                const yaw = Quaternion.RotationYawPitchRoll(yawDelta, 0, 0);
+                this.#rotation = yaw.multiply(this.#rotation).normalize();
+                this.#applyPlacement();
+            }
+            turn.angle = angle;
+            this.#diagnostics.drag.status = "rotating";
+            this.#feedback.show("rotate", this.#target, null, yawDelta);
+        } catch (error) {
+            this.#failDrag(error, "rotation-input-pose");
+        }
+    }
+
+    /**
+     * Starts a one-finger model drag, or a pending floor tap outside model geometry after real floor placement.
+     * Preserves model grab offset; a second finger schedules yaw for the next animation frame.
+     * Never reads viewer poses from a selection frame; further fingers cancel until all lift.
+     * No per-finger hit subscription is needed because floor height was already established natively.
+     * @private
+     * @param {XRInputSourceEvent} event - Native primary-action start with an active input pose.
+     * @returns {void} Owns the input until release/removal; pose and picking errors are contained.
+     */
+    #selectStart = event => {
+        const input = event.inputSource;
+        const diagnostics = this.#diagnostics.drag;
+        diagnostics.selectStarts++;
+        diagnostics.lastInputMode = input.targetRayMode;
+        diagnostics.lastError = null;
+        diagnostics.pickedMesh = null;
+        diagnostics.hitTestStatus = "not-requested";
+        diagnostics.lastHitCount = 0;
+        if (this.#state !== "placed" || !this.#target) {
+            diagnostics.status = "not-placed";
+            return;
+        }
+        if (input.targetRayMode !== "screen") {
+            diagnostics.status = "unsupported-input-mode";
+            return;
+        }
+        this.#touches.add(input);
+        if (this.#touches.size === 2 && !this.#blockedGesture && this.#drag && event.frame) {
+            this.#cancelDrag();
+            this.#blockedGesture = true;
+            this.#turn = { inputs: [...this.#touches], space: this.#manager.referenceSpace, angle: null };
+            diagnostics.status = "rotation-pending-frame";
+            return;
+        }
+        if (this.#touches.size > 1) {
+            this.#blockedGesture = true;
+            diagnostics.status = "multi-touch";
+            this.#cancelDrag();
+            return;
+        }
+        if (this.#blockedGesture || !event.frame || !this.#root?.isEnabled()
+            || this.#floorEvidence?.space !== this.#manager.referenceSpace) {
+            diagnostics.status = this.#blockedGesture ? "gesture-blocked" : !event.frame ? "missing-frame"
+                : !this.#root?.isEnabled() ? "model-hidden" : "reference-space-changed";
+            return;
+        }
+        try {
+            const ray = this.#inputRay(event.frame, input);
+            if (!ray) {
+                diagnostics.status = "missing-input-pose";
+                return;
+            }
+            const hit = this.#scene.pickWithRay(ray, mesh => this.#asset.meshes.includes(mesh) && mesh.isEnabled() && mesh.isVisible);
+            const point = this.#floorIntersection(ray);
+            if (!hit?.hit && !point) {
+                diagnostics.status = "no-floor-intersection";
+                return;
+            }
+            diagnostics.pickedMesh = hit?.hit ? hit.pickedMesh?.name ?? null : null;
+            diagnostics.hitTestStatus = "retained-floor";
+            diagnostics.status = hit?.hit ? "drag-ready" : "tap-pending";
+            this.#drag = { input, space: this.#manager.referenceSpace, mode: hit?.hit ? "drag" : "tap",
+                direction: ray.direction.clone(), moved: false, tracked: true, point,
+                offset: hit?.hit && point ? this.#target.subtract(point) : null };
+            if (point) {
+                this.#feedback.show(hit?.hit ? "drag" : "tap", hit?.hit ? this.#target : point);
+            }
+        } catch (error) {
+            this.#failDrag(error, "pick-model");
+        }
+    };
+
+    /**
+     * Completes an unmoved off-model floor tap on native release, then forgets input ownership.
+     * Confirms valid taps briefly; rotation ends on either finger release, blocking translation until all lift.
+     * Removal/cancellation never commits a tap; multiple fingers block placement until every finger lifts.
+     * @private
+     * @param {{inputSource: XRInputSource, type?: string, frame?: XRFrame}} event - Native release or removed input.
+     * @returns {void} Retains the latest diagnostic outcome without holding native resources.
+     */
+    #selectEnd = event => {
+        this.#diagnostics.drag.selectEnds++;
+        let confirmed = null;
+        if (this.#turn?.inputs.includes(event.inputSource)) {
+            this.#cancelDrag();
+        }
+        const drag = this.#drag;
+        if (drag?.input === event.inputSource) {
+            if (event.type === "selectend" && drag.mode === "tap" && !this.#blockedGesture
+                && drag.space === this.#manager.referenceSpace && drag.tracked) {
+                if (event.frame) {
+                    this.#updateDrag(event.frame);
+                }
+                if (this.#drag === drag && !drag.moved && drag.tracked && drag.point) {
+                    this.#moveOnFloor(drag.point, "tap-placed");
+                    confirmed = drag.point.clone();
+                }
+            }
+            this.#cancelDrag();
+        }
+        if (confirmed) {
+            this.#feedback.confirm(confirmed);
+        }
+        this.#touches.delete(event.inputSource);
+        if (this.#touches.size === 0) {
+            this.#blockedGesture = false;
+        }
+    };
+
+    /**
+     * Treats removed native input sources as lifted fingers so interrupted gestures cannot persist.
+     * @private
+     * @param {XRInputSourcesChangeEvent} event - Native input-source membership update.
+     * @returns {void}
+     */
+    #inputsChanged = event => {
+        for (const inputSource of event.removed) {
+            this.#selectEnd({
+                inputSource
+            });
+        }
+    };
+
+    /**
+     * Records a bounded input-pose/picking failure and forgets only the current gesture.
+     * Leaves the placed model and XR frame/lifecycle observers usable; retains no Error/native resource objects.
+     * @private
+     * @param {*} error - Native pose or model-picking failure.
+     * @param {string} stage - Failed operation for remote diagnostics.
+     * @returns {void}
+     */
+    #failDrag(error, stage) {
+        const diagnostics = this.#diagnostics.drag;
+        diagnostics.status = "error";
+        diagnostics.hitTestStatus = "error";
+        diagnostics.lastError = { stage, name: error?.name ?? "Error", message: error?.message ?? String(error) };
+        this.#cancelDrag();
+        console.warn("PrefViewer: AR floor interaction unavailable", error);
+    }
+
+    /**
+     * Hides feedback and forgets rotation, the selected drag or pending tap without moving the model or committing a cancelled tap.
+     * @private
+     * @returns {void}
+     */
+    #cancelDrag() {
+        this.#drag = null;
+        this.#turn = null;
+        this.#feedback.hide();
+    }
+
+    /**
+     * Releases a native hit subscription without interrupting Babylon's synchronous lifecycle observers.
+     * WebXR may already have invalidated it at session end; InvalidStateError means no active source remains.
+     * Reports other native cleanup failures, while allowing scene, camera and framebuffer restoration to continue.
+     * Callers must discard their owned reference after this attempt, including asynchronous late results.
+     * @private
+     * @param {?XRHitTestSource} [source] - Owned subscription; null/undefined are harmless no-ops.
+     * @returns {void} Native cancellation failures are contained and never escape into lifecycle callbacks.
+     */
+    #cancelHitTestSource(source) {
+        try {
+            source?.cancel();
+        } catch (error) {
+            if (error?.name !== "InvalidStateError") {
+                console.warn("PrefViewer: AR hit-test source cleanup failed", error);
+            }
+        }
+    }
+
+    /**
+     * Restores the saved manager scale once without interrupting synchronous session-end observers.
+     * Skips unchanged values: Babylon notifies its XR camera even when the scale is identical, and that camera
+     * can call updateRenderState on an ended session because the manager retains its last native frame.
+     * Babylon assigns its scale before notifying observers, so a changed value is restored even if that native
+     * update throws InvalidStateError. Logs other failures and lets camera/framebuffer restoration continue.
+     * @private
+     * @returns {void} Clears saved ownership before restoration; repeated cleanup does not retry the setter.
+     */
+    #restoreWorldScale() {
+        const previous = this.#previousWorldScale;
+        this.#previousWorldScale = null;
+        if (previous === null || this.#manager.worldScalingFactor === previous) {
+            return;
+        }
+        try {
+            this.#manager.worldScalingFactor = previous;
+        } catch (error) {
+            if (error?.name !== "InvalidStateError" || this.#manager.inXRSession) {
+                console.warn("PrefViewer: AR world-scale cleanup failed", error);
+            }
+        }
+    }
+
+    /**
+     * Restores surviving model roots to their original parents and removes only the owned pivot.
+     * Restores decomposed external-parent transforms while retaining ordinary glTF root animations.
+     * Discards cached footprint corners so replacement assets cannot reuse earlier bounds.
+     * Cancels gestures/feedback before replacing content.
+     * Restores original glass values and releases material observers before releasing model ownership.
+     * @private
+     * @returns {void}
+     */
+    #releaseModel() {
+        this.#cancelDrag();
+        this.#glass.restore();
+        for (const saved of this.#roots) {
+            const {
+                node,
+                parent
+            } = saved;
+            if (node.isDisposed()) {
+                continue;
+            }
+            node.parent = parent?.isDisposed() ? null : parent;
+            // Ordinary glTF roots kept their local transforms, including animated ones.
+            // Only externally parented roots needed setParent's world-preserving decomposition.
+            if (parent) {
+                node.position.copyFrom(saved.position);
+                node.rotation.copyFrom(saved.rotation);
+                node.rotationQuaternion = saved.quaternion?.clone() ?? null;
+                node.scaling.copyFrom(saved.scaling);
+            }
+            node.computeWorldMatrix(true);
+        }
+        this.#roots = [];
+        this.#root?.dispose(true);
+        this.#root = this.#asset = this.#pivot = this.#centre = null;
+        this.#footprintCorners = [];
+    }
+
+    /**
+     * Invalidates pending native work, releases input/hit sources and restores scene/world-scale and glass state.
+     * May run repeatedly for exit, failed entry or disposal; leaves lifecycle observers subscribed.
+     * Discards detected floor evidence so a later session must scan its own physical surface.
+     * Resets frozen indicator floor axes and clears the initial preview reference space and centre along with the owned model pivot.
+     * Keeps bounded diagnostics marked as ended, allowing inspection after leaving native AR.
+     * Native hit-source cancellation failures cannot prevent Babylon's subsequent exit observers from running.
+     * Restores world scale without redundant notifications or propagating native camera updates after session end.
+     * @private
+     * @returns {void}
+     */
+    #end() {
+        if (this.#active) {
+            this.#diagnostics.ended = true;
+        }
+        this.#generation++;
+        this.#session?.removeEventListener("selectstart", this.#selectStart);
+        this.#session?.removeEventListener("selectend", this.#selectEnd);
+        this.#session?.removeEventListener("inputsourceschange", this.#inputsChanged);
+        this.#session = null;
+        this.#cancelHitTestSource(this.#floorSource);
+        this.#floorSource = null;
+        this.#floorEvidence = null;
+        this.#feedback.setFloorYaw(0);
+        this.#previewSpace = null;
+        this.#cancelDrag();
+        this.#touches.clear();
+        this.#blockedGesture = false;
+        this.#releaseModel();
+        for (const [node, enabled] of this.#environment) {
+            if (!node.isDisposed()) {
+                node.setEnabled(enabled);
+            }
+        }
+        this.#environment.clear();
+        this.#restoreWorldScale();
+        this.#target = this.#rotation = null;
+        this.#active = false;
+        this.#state = "inactive";
+    }
+
+    /**
+     * Returns a detached metric-placement snapshot without mutating the scene.
+     * Nested drag counters, last outcome and errors remain inspectable after release and session exit.
+     * @public
+     * @returns {{state: string, metresPerUnit: number, initialDistance: number, floorHeight: ?number, position: ?{x: number, y: number, z: number}, dragging: boolean, model: boolean, sessionActive: boolean, referenceSpaceReady: boolean, floorSourceActive: boolean, diagnostics: object}}
+     * Placement, resource availability and detached frame/hit diagnostics. The last attempt's diagnostics survive
+     * session exit until the next entry; lastSurface describes native placement hits. Drag diagnostics identify
+     * retained-floor projection and input-pose failures; dragging excludes a pending off-model tap.
+     * In state preview, position is the model-centre anchor without a confirmed floor; in placed it is the bottom anchor.
+     * initialDistance is the preferred floor distance; diagnostics distinguish actual distance, bounded fit and provisional placement.
+     */
+    getDebugInfo() {
+        return { state: this.#state, metresPerUnit: 1, initialDistance: BabylonJSARPlacement.#INITIAL_DISTANCE,
+            floorHeight: this.#floorEvidence?.height ?? null,
+            position: this.#target ? { x: this.#target.x, y: this.#target.y, z: this.#target.z } : null,
+            dragging: this.#drag?.mode === "drag", model: !!this.#asset,
+            sessionActive: !!this.#session, referenceSpaceReady: !!this.#manager.referenceSpace,
+            floorSourceActive: !!this.#floorSource,
+            diagnostics: { ...this.#diagnostics,
+                drag: { ...this.#diagnostics.drag,
+                    lastError: this.#diagnostics.drag.lastError ? { ...this.#diagnostics.drag.lastError } : null },
+                lastError: this.#diagnostics.lastError ? { ...this.#diagnostics.lastError } : null,
+                lastSurface: this.#diagnostics.lastSurface ? { ...this.#diagnostics.lastSurface,
+                    position: this.#diagnostics.lastSurface.position ? { ...this.#diagnostics.lastSurface.position } : null,
+                    normal: this.#diagnostics.lastSurface.normal ? { ...this.#diagnostics.lastSurface.normal } : null } : null } };
+    }
+
+    /**
+     * Restores owned scene state and removes all registered lifecycle/frame observers.
+     * Disposes owned feedback geometry and materials. Pending source requests cannot publish new state after disposal.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        this.#disposed = true;
+        this.#end();
+        this.#feedback.dispose();
+        for (const [observable, observer] of this.#observers) {
+            observable.remove(observer);
+        }
+        this.#observers = [];
+    }
+}