@preference-sl/pref-viewer 3.0.1-beta.0 → 3.1.0-beta.0

package/README.md

@@ -20,15 +20,21 @@
 - Export helpers for model, scene, or combined model + scene downloads.
 - Type declarations for TypeScript and JSX usage.
 
-## AR support
+## AR and VR support
 
 | Browser/platform | Viewer route |
 | --- | --- |
 | Android Chrome with confirmed `immersive-ar` and native plane hit-test support | WebXR AR at authored metre scale |
 | Eligible Safari on iOS/iPadOS without WebXR AR support | AR Quick Look using a client-generated USDZ of the current visible model |
-| Other browsers without a supported AR route | No AR action |
-| iPhone VR | Not implemented |
-| visionOS WebXR VR | Platform capability; this viewer does not implement `immersive-vr` |
+| Headset browsers with `immersive-vr` (Meta Quest Browser, Pico, SteamVR-backed desktop browsers, visionOS Safari with WebXR enabled) | WebXR VR at authored metre scale, standing on the virtual floor in front of the model |
+| Other browsers without a supported AR or VR route | No AR/VR action |
+| iPhone VR (Cardboard, device-orientation stereo) | Not implemented |
+
+The viewer renders one control per supported session mode (`.babylonVRicon.pref-viewer-xr-ar`, `.babylonVRicon.pref-viewer-xr-vr`) inside its `.xr-button-overlay`. Session support is queried through `navigator.xr.isSessionSupported` at viewer start; a device that supports both modes shows both controls, and the other control is hidden while a session is active.
+
+### VR
+
+VR uses the `local-floor` reference space without teleportation, controller selection, hand tracking or model interaction: the user looks around and walks within the tracked area. On entry the XR camera is placed at floor height (the model's lowest point), centred on the model's horizontal bounds and 2.5 m along the viewer's existing Inner (+Z) direction, facing the model. The world scale is forced to 1 so the glTF's authored metre dimensions apply, and restored on exit. The virtual environment stays visible (unlike AR, which hides it), model materials are not adapted, and the model keeps its current transforms. `getDebugInfo().vr` reports `phase`, `standingDistance`, `position` and `floorHeight`. Headset-specific rendering, comfort and visionOS WebXR availability still require physical-device validation.
 
 Android WebXR preserves the glTF's authored metre dimensions, including existing unit-conversion transforms. It never fits the model to the screen or permits pinch scaling. Assets must encode their dimensions in metres and orient their interior toward the viewer's existing Inner (+Z) direction; the viewer cannot infer an interior face or correct arbitrary source units. The upstream exporter owns those asset conventions.
 

package/package.json

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

package/src/babylonjs-ar-placement.js

@@ -30,6 +30,7 @@ export default class BabylonJSARPlacement {
     #manager;
     #getModel;
     #getEnvironment;
+    #isActive;
     #observers = [];
     #session = null;
     #generation = 0;
@@ -81,23 +82,36 @@ export default class BabylonJSARPlacement {
      * @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.
+     * @param {function(): boolean} [isActive] - Whether the session being entered is an AR session; defaults to always true.
+     * While it returns false and no placement is active, entry and session-init events are ignored (frames already
+     * require an active placement) so other session modes such as VR leave the scene untouched.
+     * An already active placement still ends normally.
      */
-    constructor(scene, experience, getModel, getEnvironment = () => null) {
+    constructor(scene, experience, getModel, getEnvironment = () => null, isActive = () => true) {
         this.#scene = scene;
         this.#feedback = new BabylonJSARPlacementFeedback(scene);
         this.#manager = experience.baseExperience.sessionManager;
         this.#getModel = getModel;
         this.#getEnvironment = getEnvironment;
+        this.#isActive = isActive;
         this.#observe(experience.baseExperience.onStateChangedObservable, state => {
-            if (state === WebXRState.ENTERING_XR) {
+            if (state === WebXRState.ENTERING_XR && this.#isActive()) {
                 this.#begin();
             }
-            if (state === WebXRState.NOT_IN_XR) {
+            if (state === WebXRState.NOT_IN_XR && this.#active) {
+                this.#end();
+            }
+        });
+        this.#observe(this.#manager.onXRSessionInit, session => {
+            if (this.#active || this.#isActive()) {
+                void this.#start(session);
+            }
+        });
+        this.#observe(this.#manager.onXRSessionEnded, () => {
+            if (this.#active) {
                 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));
     }
 

package/src/babylonjs-controller.js

@@ -1,5 +1,7 @@
 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 BabylonJSVRStage from "./babylonjs-vr-stage.js";
+import XRModeButtons from "./xr-mode-buttons.js";
 import BabylonJSARGlass from "./babylonjs-ar-glass.js";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
@@ -127,6 +129,8 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #arPlacement = null;
+    #vrStage = null;
+    #xrButtons = null;
     #xrGeneration = 0;
     #quickLookAction = null;
     #quickLookGlass = new BabylonJSARGlass();
@@ -1031,7 +1035,8 @@ export default class BabylonJSController {
     }
 
     /**
-     * Adds the supplied cube-and-scan-frame SVG and shared interaction styles to native XR and Quick Look buttons.
+     * Adds the supplied cube-and-scan-frame SVG, a headset icon for the VR button and shared interaction styles
+     * to the XR mode buttons and the Quick Look action.
      * Preserves the supplied 24-unit geometry and renders its filled paths white against the toggle background.
      * @private
      * @returns {void}
@@ -1047,7 +1052,8 @@ export default class BabylonJSController {
 	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"}`;
+        const vrIcon = `<svg fill="white" xmlns="http://www.w3.org/2000/svg" width="24px" height="24px" viewBox="0 0 24 24"><path fill="none" d="M0,0h24v24H0V0z"/><path d="M20.74 6H3.21C2.55 6 2 6.57 2 7.28v10.44c0 .7.55 1.28 1.23 1.28h4.79c.52 0 .96-.33 1.14-.79l1.4-3.48c.23-.59.79-1.01 1.44-1.01s1.21.42 1.45 1.01l1.39 3.48c.19.46.63.79 1.11.79h4.79c.71 0 1.26-.57 1.26-1.28V7.28c0-.7-.55-1.28-1.26-1.28zM7.5 14.62c-1.17 0-2.13-.95-2.13-2.12 0-1.17.96-2.13 2.13-2.13 1.18 0 2.12.96 2.12 2.13s-.95 2.12-2.12 2.12zm9 0c-1.17 0-2.13-.95-2.13-2.12 0-1.17.96-2.13 2.13-2.13s2.12.96 2.12 2.13-.95 2.12-2.12 2.12z"/></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.pref-viewer-xr-vr { background-image: url(data:image/svg+xml;charset=UTF-8,${encodeURIComponent(vrIcon)}) } .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");
@@ -1083,11 +1089,14 @@ export default class BabylonJSController {
     }
 
     /**
-     * Selects and initializes supported WebXR AR or an eligible Safari Quick Look action.
+     * Selects and initializes supported WebXR AR and/or VR, 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.
+     * @returns {Promise<boolean>} True when an XR route is configured, false when unsupported, obsolete or setup fails.
      * @description
-     * Checks AR support and requires native floor hit testing at real-world metre scale.
+     * Queries `immersive-ar` and `immersive-vr` support; a failed VR query only disables VR.
+     * Babylon's default enter/exit UI is disabled; an XRModeButtons overlay renders one button per supported mode,
+     * each requesting its own reference space and features. VR is standing-scale (`local-floor`) and positioned by BabylonJSVRStage.
+     * AR 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.
@@ -1104,11 +1113,16 @@ export default class BabylonJSController {
         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";
         let experience = null;
         let placement = null;
+        let stage = null;
+        let buttons = null;
         try {
-            const sessionSupported = await WebXRSessionManager.IsSessionSupportedAsync(sessionMode);
+            const [sessionSupported, vrSupported] = await Promise.all([
+                WebXRSessionManager.IsSessionSupportedAsync("immersive-ar"),
+                // An unavailable VR query must not take AR down with it.
+                Promise.resolve(WebXRSessionManager.IsSessionSupportedAsync("immersive-vr")).catch(() => null),
+            ]);
             if (!isCurrent()) {
                 return false;
             }
@@ -1127,10 +1141,19 @@ export default class BabylonJSController {
                 this.#refreshQuickLook();
                 return true;
             }
-            if (route !== "webxr") {
-                console.info("PrefViewer: WebXR in mode AR is not supported");
+            const modes = [];
+            if (route === "webxr") {
+                modes.push({ mode: "immersive-ar", referenceSpaceType: "local", requiredFeatures: ["hit-test"], optionalFeatures: ["plane-detection"] });
+            }
+            if (vrSupported === true) {
+                modes.push({ mode: "immersive-vr", referenceSpaceType: "local-floor", requiredFeatures: [], optionalFeatures: [] });
+            }
+            if (modes.length === 0) {
+                console.info("PrefViewer: WebXR in mode AR/VR is not supported");
                 return false;
             }
+            const hasAR = modes.some((item) => item.mode === "immersive-ar");
+            const hasVR = modes.some((item) => item.mode === "immersive-vr");
 
             const options = {
                 disableTeleportation: true,
@@ -1138,13 +1161,7 @@ export default class BabylonJSController {
                 disableNearInteraction: true,
                 disableHandTracking: true,
                 ignoreNativeCameraTransformation: true,
-                uiOptions: {
-                    sessionMode: sessionMode,
-                    renderTarget: "xrLayer",
-                    referenceSpaceType: "local",
-                    requiredFeatures: ["hit-test"],
-                    optionalFeatures: ["plane-detection"],
-                },
+                disableDefaultUI: true,
             };
 
             experience = await WebXRDefaultExperience.CreateAsync(scene, options);
@@ -1152,10 +1169,19 @@ export default class BabylonJSController {
                 return false;
             }
 
-            placement = new BabylonJSARPlacement(scene, experience,
-                () => this.#containers.model?.state?.isVisible && !this.#containers.model.state.isPending
-                    ? this.#containers.model.assetContainer : null,
-                () => this.#containers.environment?.assetContainer);
+            /** @returns {?AssetContainer} Visible, settled model container, or null while unavailable. */
+            const getModel = () => this.#containers.model?.state?.isVisible && !this.#containers.model.state.isPending
+                ? this.#containers.model.assetContainer : null;
+            buttons = new XRModeButtons(this.#canvas.parentElement, experience, modes,
+                () => this.#viewCubeConfig.getCulture?.() ?? I18n.getLocale());
+            if (hasAR) {
+                placement = new BabylonJSARPlacement(scene, experience, getModel,
+                    () => this.#containers.environment?.assetContainer,
+                    () => buttons?.requestedMode === "immersive-ar");
+            }
+            if (hasVR) {
+                stage = new BabylonJSVRStage(scene, experience, getModel, () => buttons?.requestedMode === "immersive-vr");
+            }
 
             experience.baseExperience.onStateChangedObservable.add(() => {
                 // Babylon schedules XR frames only while engine render callbacks are registered.
@@ -1170,6 +1196,8 @@ export default class BabylonJSController {
             this.#addStylesToARButton();
             this.#XRExperience = experience;
             this.#arPlacement = placement;
+            this.#vrStage = stage;
+            this.#xrButtons = buttons;
             return true;
         } catch (error) {
             console.warn("PrefViewer: failed to create WebXR experience", error);
@@ -1182,6 +1210,8 @@ export default class BabylonJSController {
                     console.warn("PrefViewer: failed to dispose obsolete WebXR experience", error);
                 } finally {
                     placement?.dispose();
+                    stage?.dispose();
+                    buttons?.dispose();
                 }
             }
         }
@@ -2281,9 +2311,15 @@ export default class BabylonJSController {
 
         const xrExperience = this.#XRExperience;
         const placement = this.#arPlacement;
+        const stage = this.#vrStage;
+        const buttons = this.#xrButtons;
         if (!xrExperience) {
             placement?.dispose();
+            stage?.dispose();
+            buttons?.dispose();
             this.#arPlacement = null;
+            this.#vrStage = null;
+            this.#xrButtons = null;
             return;
         }
 
@@ -2296,6 +2332,8 @@ export default class BabylonJSController {
                 console.warn("PrefViewer: Error exiting XR experience:", error);
             } finally {
                 placement?.dispose();
+                stage?.dispose();
+                buttons?.dispose();
                 try {
                     xrExperience.dispose();
                 } catch (error) {
@@ -2304,6 +2342,8 @@ export default class BabylonJSController {
                 if (this.#XRExperience === xrExperience) {
                     this.#XRExperience = null;
                     this.#arPlacement = null;
+                    this.#vrStage = null;
+                    this.#xrButtons = null;
                 }
                 this.#disablingPromises.xr = null;
             }
@@ -3976,6 +4016,7 @@ export default class BabylonJSController {
      */
     refreshViewCube() {
         this.#quickLookAction?.refreshCulture();
+        this.#xrButtons?.refreshCulture();
         this.#viewCube?.resize();
     }
 
@@ -4148,6 +4189,7 @@ export default class BabylonJSController {
 
         return {
             ar: this.#arPlacement?.getDebugInfo() ?? null,
+            vr: this.#vrStage?.getDebugInfo() ?? null,
             canvas: {
                 clientWidth: this.#canvas?.clientWidth ?? null,
                 clientHeight: this.#canvas?.clientHeight ?? null,

package/src/babylonjs-vr-stage.js

@@ -0,0 +1,191 @@
+import { Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import { FreeCamera } from "@babylonjs/core/Cameras/freeCamera.js";
+import { WebXRState } from "@babylonjs/core/XR/webXRTypes.js";
+
+/**
+ * Owns the standing pose of a native `immersive-vr` session.
+ * When Babylon announces the initial pose (after it copied the orbit camera into the XR camera) and the
+ * session was requested as VR, forces metre scale and moves the viewer to floor height, 2.5 m in front of
+ * the model's bottom-centre along +Z (the Inner face), looking at it. The model and environment are not moved or hidden.
+ * Exit or cancellation restores the previous world scale. Call dispose() before releasing the owning scene.
+ */
+export default class BabylonJSVRStage {
+    /**
+     * Distance, in metres, between the viewer and the model's bottom-centre along +Z.
+     * @public
+     * @static
+     * @type {number}
+     */
+    static STANDING_DISTANCE_METRES = 2.5;
+
+    #scene;
+    #experience;
+    #manager;
+    #getModel;
+    #isActive;
+    #observers = [];
+    #previousWorldScale = null;
+    #diagnostics = BabylonJSVRStage.#createDiagnostics();
+
+    /**
+     * Creates fresh diagnostics for an inactive stage.
+     * @private
+     * @static
+     * @returns {{phase: string, position: ?{x: number, y: number, z: number}, floorHeight: ?number}} Mutable diagnostic state.
+     */
+    static #createDiagnostics() {
+        return { phase: "inactive", position: null, floorHeight: null };
+    }
+
+    /**
+     * Subscribes to the XR pose and lifecycle events without touching the scene or session yet.
+     * @param {import("@babylonjs/core").Scene} scene - Scene containing the model.
+     * @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(): boolean} isActive - Whether the session being entered is a VR session.
+     */
+    constructor(scene, experience, getModel, isActive) {
+        this.#scene = scene;
+        this.#experience = experience;
+        this.#manager = experience.baseExperience.sessionManager;
+        this.#getModel = getModel;
+        this.#isActive = isActive;
+        this.#observe(experience.baseExperience.onInitialXRPoseSetObservable, () => this.#place());
+        this.#observe(experience.baseExperience.onStateChangedObservable, (state) => {
+            if (state === WebXRState.NOT_IN_XR) {
+                this.#end();
+            }
+        });
+        this.#observe(this.#manager.onXRSessionEnded, () => this.#end());
+    }
+
+    /**
+     * Registers a Babylon observer and retains its handle for disposal.
+     * @private
+     * @param {import("@babylonjs/core").Observable<*>} observable - Event stream.
+     * @param {function(*): void} callback - Handler invoked by that stream.
+     * @returns {void}
+     */
+    #observe(observable, callback) {
+        this.#observers.push([observable, observable.add(callback)]);
+    }
+
+    /**
+     * Computes the world bounds of the model's root meshes (and their descendants).
+     * @private
+     * @param {import("@babylonjs/core").AssetContainer} asset - Model container.
+     * @returns {?{min: Vector3, max: Vector3}} World-space bounds, or null when the model has no geometry.
+     */
+    #getBounds(asset) {
+        let min = null;
+        let max = null;
+        for (const mesh of asset.meshes ?? []) {
+            if (mesh.parent) {
+                continue;
+            }
+            mesh.computeWorldMatrix(true);
+            const bounds = mesh.getHierarchyBoundingVectors(true);
+            if (![bounds.min.x, bounds.min.y, bounds.min.z, bounds.max.x, bounds.max.y, bounds.max.z].every(Number.isFinite)) {
+                continue;
+            }
+            min = min ? Vector3.Minimize(min, bounds.min) : bounds.min.clone();
+            max = max ? Vector3.Maximize(max, bounds.max) : bounds.max.clone();
+        }
+        return min && max ? { min, max } : null;
+    }
+
+    /**
+     * Sets metre scale and places the XR camera at floor height in front of the model, facing it.
+     * Re-applies the floor height after the copy because Babylon resets it to zero (webXRCamera.js, "set the ground level").
+     * Keeps Babylon's pose when the model is unavailable. Ignores sessions that were not requested as VR.
+     * @private
+     * @returns {void}
+     */
+    #place() {
+        if (!this.#isActive()) {
+            return;
+        }
+        if (this.#previousWorldScale === null) {
+            this.#previousWorldScale = this.#manager.worldScalingFactor;
+        }
+        if (this.#manager.worldScalingFactor !== 1) {
+            this.#manager.worldScalingFactor = 1;
+        }
+        const asset = this.#getModel();
+        const bounds = asset ? this.#getBounds(asset) : null;
+        if (!bounds) {
+            this.#diagnostics = { phase: "no-model", position: null, floorHeight: null };
+            return;
+        }
+        const floorY = bounds.min.y;
+        const centreX = (bounds.min.x + bounds.max.x) / 2;
+        const centreZ = (bounds.min.z + bounds.max.z) / 2;
+        const standing = new FreeCamera("PrefViewerVRStanding",
+            new Vector3(centreX, floorY, centreZ + BabylonJSVRStage.STANDING_DISTANCE_METRES), this.#scene);
+        const camera = this.#experience.baseExperience.camera;
+        try {
+            standing.setTarget(new Vector3(centreX, floorY, centreZ));
+            camera.setTransformationFromNonVRCamera(standing, true);
+            // Babylon's WebXRCamera forces the copied ground level to y = 0; the model floor is the real
+            // ground, and the native head height is added on the first tracked frame.
+            camera.position.y = floorY;
+        } finally {
+            standing.dispose();
+        }
+        this.#diagnostics = {
+            phase: "placed",
+            position: { x: centreX, y: floorY, z: centreZ + BabylonJSVRStage.STANDING_DISTANCE_METRES },
+            floorHeight: floorY,
+        };
+    }
+
+    /**
+     * Restores the world scale saved at entry and marks the stage inactive. Safe to call repeatedly.
+     * Native update failures are logged so Babylon can finish restoring its camera.
+     * @private
+     * @returns {void}
+     */
+    #end() {
+        const previous = this.#previousWorldScale;
+        this.#previousWorldScale = null;
+        this.#diagnostics.phase = "inactive";
+        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: VR world-scale cleanup failed", error);
+            }
+        }
+    }
+
+    /**
+     * Returns a detached snapshot of the last standing placement; it survives session exit as inactive.
+     * @public
+     * @returns {{phase: string, standingDistance: number, position: ?{x: number, y: number, z: number}, floorHeight: ?number}}
+     * Phase is "inactive", "placed" or "no-model"; position is where the XR camera was placed in scene metres.
+     */
+    getDebugInfo() {
+        return {
+            phase: this.#diagnostics.phase,
+            standingDistance: BabylonJSVRStage.STANDING_DISTANCE_METRES,
+            position: this.#diagnostics.position ? { ...this.#diagnostics.position } : null,
+            floorHeight: this.#diagnostics.floorHeight,
+        };
+    }
+
+    /**
+     * Restores the world scale and removes every registered observer. Idempotent.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        this.#end();
+        for (const [observable, observer] of this.#observers) {
+            observable.remove(observer);
+        }
+        this.#observers = [];
+    }
+}

package/src/localization/translations.js

@@ -6,6 +6,9 @@ export const translations = {
                 preparing: "Preparing AR…",
                 retry: "Retry preparing AR",
             },
+            vr: {
+                open: "View in VR",
+            },
             viewCube: {
                 title: "View orientation",
                 front: "Inner",
@@ -82,6 +85,9 @@ export const translations = {
                 preparing: "Preparando RA…",
                 retry: "Reintentar preparar RA",
             },
+            vr: {
+                open: "Ver en VR",
+            },
             viewCube: {
                 title: "Orientación de vista",
                 front: "Interior",

package/src/xr-mode-buttons.js

@@ -0,0 +1,146 @@
+import { WebXRState } from "@babylonjs/core/XR/webXRTypes.js";
+import I18n from "./localization/i18n.js";
+
+/**
+ * Owns the viewer's WebXR enter/exit buttons, one per supported session mode (AR and/or VR).
+ * Replaces Babylon's default enter/exit UI so every mode requests its own reference space and features.
+ * Records the requested mode before calling `enterXRAsync`, because Babylon reports ENTERING_XR before the
+ * session manager knows the session mode; collaborators read it through `requestedMode`.
+ * Call dispose() when the owning viewer is torn down.
+ */
+export default class XRModeButtons {
+    static #CLASS_BY_MODE = { "immersive-ar": "pref-viewer-xr-ar", "immersive-vr": "pref-viewer-xr-vr" };
+    static #LABEL_BY_MODE = { "immersive-ar": "prefViewer.ar.open", "immersive-vr": "prefViewer.vr.open" };
+
+    #experience;
+    #getCulture;
+    #overlay;
+    #entries = [];
+    #requestedMode = null;
+    #stateObserver;
+    #unsubscribe;
+    #disposed = false;
+
+    /**
+     * Creates the overlay and buttons, then subscribes to XR state and locale changes.
+     * @param {HTMLElement} container - Canvas wrapper receiving the overlay.
+     * @param {import("@babylonjs/core").WebXRDefaultExperience} experience - Experience created with its default UI disabled.
+     * @param {Array<{mode: string, referenceSpaceType: string, requiredFeatures: string[], optionalFeatures: string[]}>} modes - Session modes to expose, one button each.
+     * @param {function(): string} [getCulture] - Host locale provider; defaults to the active I18n locale.
+     */
+    constructor(container, experience, modes, getCulture = () => I18n.getLocale()) {
+        this.#experience = experience;
+        this.#getCulture = getCulture;
+        const document = container.ownerDocument;
+        this.#overlay = document.createElement("div");
+        this.#overlay.className = "xr-button-overlay";
+        this.#overlay.style.cssText = "z-index:11;position:absolute;right:20px;bottom:50px;display:flex;";
+        for (const config of modes) {
+            const button = document.createElement("button");
+            button.type = "button";
+            button.className = `babylonVRicon ${XRModeButtons.#CLASS_BY_MODE[config.mode] ?? ""}`.trim();
+            button.addEventListener("click", () => { void this.#onClick(config); });
+            this.#overlay.append(button);
+            this.#entries.push({ config, button });
+        }
+        // Subscribe before attaching so a failing subscription leaves nothing in the DOM.
+        this.#stateObserver = experience.baseExperience.onStateChangedObservable.add((state) => this.#onState(state));
+        this.#unsubscribe = I18n.onLocaleChange(() => this.refreshCulture());
+        container.append(this.#overlay);
+        this.refreshCulture();
+    }
+
+    /**
+     * Mode of the session being entered or active, set before Babylon announces ENTERING_XR.
+     * @public
+     * @returns {?string} "immersive-ar", "immersive-vr", or null when no session was requested.
+     */
+    get requestedMode() {
+        return this.#requestedMode;
+    }
+
+    /**
+     * Enters the clicked mode when idle or exits the current session when active; ignores transitional states.
+     * Entry failures are logged, flagged on the button with the `xr-error` class and clear the requested mode.
+     * @private
+     * @param {{mode: string, referenceSpaceType: string, requiredFeatures: string[], optionalFeatures: string[]}} config - Mode of the clicked button.
+     * @returns {Promise<void>} Resolves after the enter/exit request settles; never rejects.
+     */
+    async #onClick(config) {
+        const base = this.#experience.baseExperience;
+        const entry = this.#entries.find((item) => item.config === config);
+        try {
+            if (base.state === WebXRState.IN_XR) {
+                await base.exitXRAsync();
+            } else if (base.state === WebXRState.NOT_IN_XR) {
+                entry?.button.classList.remove("xr-error");
+                this.#requestedMode = config.mode;
+                await base.enterXRAsync(config.mode, config.referenceSpaceType, this.#experience.renderTarget, {
+                    requiredFeatures: config.requiredFeatures,
+                    optionalFeatures: config.optionalFeatures,
+                });
+            }
+        } catch (error) {
+            if (!this.#disposed && base.state !== WebXRState.IN_XR) {
+                this.#requestedMode = null;
+                entry?.button.classList.add("xr-error");
+            }
+            console.warn("PrefViewer: WebXR session request failed", error);
+        }
+    }
+
+    /**
+     * Shows only the active mode's button as "exit" while in XR and restores all buttons on exit.
+     * @private
+     * @param {number} state - New WebXRState value.
+     * @returns {void}
+     */
+    #onState(state) {
+        if (state === WebXRState.IN_XR) {
+            for (const { config, button } of this.#entries) {
+                const active = config.mode === this.#requestedMode;
+                button.classList.toggle("vrdisplaypresenting", active);
+                button.style.display = active ? "" : "none";
+            }
+        } else if (state === WebXRState.NOT_IN_XR) {
+            this.#requestedMode = null;
+            for (const { button } of this.#entries) {
+                button.classList.remove("vrdisplaypresenting");
+                button.style.display = "";
+            }
+        }
+    }
+
+    /**
+     * Re-applies the localized accessible label and tooltip of every button from the host culture.
+     * @public
+     * @returns {void}
+     */
+    refreshCulture() {
+        if (this.#disposed) {
+            return;
+        }
+        for (const { config, button } of this.#entries) {
+            const text = I18n.translate(XRModeButtons.#LABEL_BY_MODE[config.mode], { locale: this.#getCulture() });
+            button.setAttribute("aria-label", text);
+            button.title = text;
+        }
+    }
+
+    /**
+     * Idempotently removes the overlay, the XR state observer and the locale subscription.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#experience.baseExperience.onStateChangedObservable.remove(this.#stateObserver);
+        this.#unsubscribe();
+        this.#overlay.remove();
+        this.#entries = [];
+        this.#requestedMode = null;
+    }
+}