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

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.
 
@@ -48,6 +54,22 @@ On eligible Safari, the AR control uses the existing XR appearance and position.
 
 The link uses `rel="ar"`, `download="model.usdz"` and a `model/vnd.usdz+zip` Blob URL with the `#allowsContentScaling=0` fragment, so its native navigation runs directly on the user tap and Quick Look keeps the authored real-world size (no pinch scaling, as on Android WebXR). Only model meshes with supported materials and current visibility are exported. Environment and viewer overlays are excluded. Physical transmission glass is exported with an equivalent alpha opacity, because USDZ has no transmission. The viewer bundles the `fflate` helper the exporter needs, so no request to `unpkg.com` is made.
 
+#### Host-supplied Quick Look asset
+
+A host that produces the AR asset elsewhere (for example a server-generated USDZ or USD) can hand it to the Quick Look action with `setQuickLookAssetProvider(provider)`. The provider is a function returning `Promise<{ data: Uint8Array | ArrayBuffer | Blob, mimeType?: string, fileName?: string }>`; `mimeType` defaults to `model/vnd.usdz+zip` and `fileName` to `model.usdz`. Pass `null` to clear it. The viewer never learns how the asset is made.
+
+```js
+viewer.setQuickLookAssetProvider(async () => {
+  const response = await fetch("/my-server/ar-model");
+  return { data: await response.arrayBuffer(), mimeType: "model/vnd.usdz+zip", fileName: "model.usdz" };
+});
+```
+
+- While a provider is set, the Quick Look link uses its asset instead of the Babylon USDZ export. It is called each time the link is prepared (after model/material loading and changes), only on the Quick Look route (eligible iOS/iPadOS Safari without WebXR AR).
+- Setting or clearing the provider re-prepares the link when Quick Look is active; a provider set earlier (even before the element is connected) is retained.
+- The ZIP signature check applies only when `mimeType` is `model/vnd.usdz+zip`. Any other MIME type (for example `model/vnd.usd`, or `text/plain` for USDA) is passed through unchanged as the Blob type, with `fileName` as the link's `download` attribute. AR Quick Look officially opens only `.usdz`/`.reality`, so what iOS does with other types is the host's experiment.
+- If the provider throws, rejects or returns empty data, the viewer logs `PrefViewer: Quick Look asset provider failed` with `console.warn` and falls back to its own USDZ export.
+
 Manual iOS Quick Look validation has been reported: its AR button remains usable even when the Babylon 3D view is empty. The empty scene/model failure has also been reproduced on an iPhone and remains unresolved; Quick Look validation does not establish successful in-page 3D rendering. Device/browser versions and itemized scale, glass, texture, close/reopen, iPad and production-iframe results were not supplied, so those details remain unconfirmed. Safari remote inspection is unavailable in the current test setup because no macOS system is available. An iframe must permit the browser's native AR/navigation behavior; no automatic top-level redirect or parent-message protocol is added. Used Blob URLs are retained through model replacement/detach until an observed browser return; if Safari emits no return signal, their lifetime ends with the document.
 
 ## Installation
@@ -432,6 +454,7 @@ Dialogs opened with `openDialog()`, including the **Ctrl+Alt+D** download dialog
 | `downloadModelGLB()` / `downloadModelGLTF()` / `downloadModelUSDZ()` | Exports the current model. |
 | `downloadSceneGLB()` / `downloadSceneGLTF()` / `downloadSceneUSDZ()` | Exports the current scene/environment. |
 | `downloadModelAndSceneGLB()` / `downloadModelAndSceneGLTF()` / `downloadModelAndSceneUSDZ()` | Exports the combined model and scene. |
+| `setQuickLookAssetProvider(provider \| null)` | Lets the host supply the asset opened by the iOS AR Quick Look action instead of the viewer's client-generated USDZ (for example a file produced by a server). See [AR and VR support](#ar-and-vr-support). |
 
 All viewer dialogs share this priority, including the model-download dialog opened with **Ctrl+Alt+D** while the 3D canvas receives keyboard input. Existing backdrop dismissal remains available: a click over a covered control may close the dialog, but does not also activate that control. Closing the dialog restores access to the underlying controls.
 

package/index.d.ts

@@ -139,6 +139,18 @@ export interface PrefViewerElementClickDetail {
   ids: string[];
 }
 
+/** Asset a host hands to the iOS AR Quick Look action. */
+export interface PrefViewerQuickLookAsset {
+  data: Uint8Array | ArrayBuffer | Blob;
+  /** Defaults to `model/vnd.usdz+zip`; the ZIP signature is checked only for that type. */
+  mimeType?: string;
+  /** Defaults to `model.usdz`; used as the link's `download` attribute. */
+  fileName?: string;
+}
+
+/** Async factory of the Quick Look asset, called each time the Quick Look link is prepared. */
+export type PrefViewerQuickLookAssetProvider = () => Promise<PrefViewerQuickLookAsset>;
+
 /** Optional speed/direction for `startTurnable` / `toggleTurnable`. */
 export interface PrefViewerTurnableOptions {
   speed?: number;
@@ -356,6 +368,13 @@ export declare class PrefViewer extends HTMLElement {
   setAnimationProgress(name: string, progress: number): boolean;
   setAnimationLoop(name: string, loop: boolean): boolean;
 
+  // ── AR Quick Look (iOS) ──
+  /**
+   * Supplies (or clears with `null`) the asset opened by the iOS AR Quick Look action instead of the
+   * viewer's client-generated USDZ. A failing provider falls back to the built-in export with a console warning.
+   */
+  setQuickLookAssetProvider(provider: PrefViewerQuickLookAssetProvider | null): void;
+
   // ── Downloads ──
   downloadModelGLB(): void;
   downloadModelGLTF(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "3.0.1-beta.0",
+    "version": "3.1.0-beta.1",
     "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";
@@ -70,6 +72,7 @@ import QuickLookAction from "./quick-look-action.js";
  *  - enable() / disable()
  *  - load(force?) / reloadWithCurrentSettings()
  *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
+ *  - setQuickLookAssetProvider(provider)
  *  - getRenderSettings() / scheduleRenderSettingsReload(settings)
  *  - getDebugInfo()
  *  - setContainerVisibility(name, show)
@@ -127,8 +130,11 @@ export default class BabylonJSController {
     #shadowGen = [];
     #XRExperience = null;
     #arPlacement = null;
+    #vrStage = null;
+    #xrButtons = null;
     #xrGeneration = 0;
     #quickLookAction = null;
+    #quickLookAssetProvider = null;
     #quickLookGlass = new BabylonJSARGlass();
     #quickLookLoads = 0;
     #quickLookValid = { model: false, materials: true };
@@ -1031,7 +1037,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 +1054,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 +1091,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 +1115,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 +1143,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 +1163,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 +1171,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 +1198,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 +1212,8 @@ export default class BabylonJSController {
                     console.warn("PrefViewer: failed to dispose obsolete WebXR experience", error);
                 } finally {
                     placement?.dispose();
+                    stage?.dispose();
+                    buttons?.dispose();
                 }
             }
         }
@@ -1191,6 +1223,7 @@ export default class BabylonJSController {
      * 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.
+     * The prepared asset comes from the host provider when one is set (see setQuickLookAssetProvider), otherwise from the export.
      * @private
      * @returns {void} Starts preparation without waiting for it or changing public task-queue ordering.
      */
@@ -1218,7 +1251,66 @@ export default class BabylonJSController {
         }
         // 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(() => this.#exportQuickLookUSDZ(asset, eligible));
+        void this.#quickLookAction.update(() => this.#prepareQuickLookAsset(asset, eligible));
+    }
+
+    /**
+     * Installs or clears the host-supplied provider of the asset opened by the iOS Quick Look action.
+     * The provider is retained even before the Quick Look route exists. While Quick Look is active, changing it
+     * re-prepares the link at once, so clearing returns to the in-browser USDZ export.
+     * @public
+     * @param {?(function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>)} provider
+     *   Async asset factory (defaults: MIME `model/vnd.usdz+zip`, file name `model.usdz`), or null to clear.
+     * @returns {void} Ignores any value that is neither a function nor null by clearing the provider.
+     */
+    setQuickLookAssetProvider(provider) {
+        this.#quickLookAssetProvider = typeof provider === "function" ? provider : null;
+        this.#refreshQuickLook();
+    }
+
+    /**
+     * Prepares the Quick Look asset: the host provider's asset when one is set, otherwise (or when the provider
+     * fails or returns no data) the in-browser USDZ export of the current model.
+     * @private
+     * @param {import("@babylonjs/core").AssetContainer} asset - Model container used by the fallback export.
+     * @param {function(import("@babylonjs/core").AbstractMesh): boolean} eligible - Mesh filter for the fallback export.
+     * @returns {Promise<Uint8Array|{data: Uint8Array, mimeType?: string, fileName?: string}>} Asset for QuickLookAction.
+     */
+    async #prepareQuickLookAsset(asset, eligible) {
+        const provider = this.#quickLookAssetProvider;
+        if (provider) {
+            try {
+                return await BabylonJSController.#readQuickLookAsset(provider);
+            } catch (error) {
+                console.warn("PrefViewer: Quick Look asset provider failed", error);
+            }
+        }
+        return this.#exportQuickLookUSDZ(asset, eligible);
+    }
+
+    /**
+     * Invokes a host asset provider and converts its data to bytes.
+     * @private
+     * @static
+     * @param {function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>} provider - Host asset factory.
+     * @returns {Promise<{data: Uint8Array, mimeType?: string, fileName?: string}>} Nonempty asset with byte data.
+     * @throws {Error} When the provider rejects, or returns no data or empty/unsupported data.
+     */
+    static async #readQuickLookAsset(provider) {
+        const result = await provider();
+        const raw = result?.data;
+        let data = null;
+        if (raw instanceof Uint8Array) {
+            data = raw;
+        } else if (raw instanceof ArrayBuffer) {
+            data = new Uint8Array(raw);
+        } else if (typeof Blob !== "undefined" && raw instanceof Blob) {
+            data = new Uint8Array(await raw.arrayBuffer());
+        }
+        if (!data || data.length === 0) {
+            throw new Error("PrefViewer: Quick Look asset provider returned no data");
+        }
+        return { data, mimeType: result.mimeType, fileName: result.fileName };
     }
 
     /**
@@ -2281,9 +2373,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 +2394,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 +2404,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 +4078,7 @@ export default class BabylonJSController {
      */
     refreshViewCube() {
         this.#quickLookAction?.refreshCulture();
+        this.#xrButtons?.refreshCulture();
         this.#viewCube?.resize();
     }
 
@@ -4148,6 +4251,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/pref-viewer-3d.js

@@ -51,6 +51,7 @@ import FileStorage from "./file-storage.js";
  *  - downloadModelGLB(): Downloads the current 3D model as a GLB file.
  *  - downloadModelGLTF(): Downloads the current 3D model as a glTF ZIP file.
  *  - downloadModelUSDZ(): Downloads the current 3D model as a USDZ file.
+ *  - setQuickLookAssetProvider(provider): Supplies (or clears) the asset opened by the iOS AR Quick Look action.
  *  - downloadModelAndSceneGLB(): Downloads both the model and scene as a GLB file.
  *  - downloadModelAndSceneGLTF(): Downloads both the model and scene as a glTF ZIP file.
  *  - downloadModelAndSceneUSDZ(): Downloads both the model and scene as a USDZ file.
@@ -102,6 +103,7 @@ export default class PrefViewer3D extends HTMLElement {
     #data = null; // Component data
 
     #babylonJSController = null; // BabylonJSController instance
+    #quickLookAssetProvider = null; // Host asset provider, reapplied to every controller this element creates
 
     /** @returns {"svg"|"canvas"} Per-instance normalized renderer; missing/invalid attributes use Canvas. */
     get viewCubeRenderer() {
@@ -283,6 +285,7 @@ export default class PrefViewer3D extends HTMLElement {
      * Initializes the Babylon controller with asset/option state and the selected visibility-aware cube contract.
      * Supplies current host culture and dispatches measured view-cube-layout events for render-menu positioning.
      * Starts asynchronous engine initialization without waiting for asset loading.
+     * Reapplies any retained Quick Look asset provider to the new controller before it starts.
      * @private
      * @returns {void}
      */
@@ -303,6 +306,7 @@ export default class PrefViewer3D extends HTMLElement {
              */
             onLayout: (offset, height) => this.dispatchEvent(new CustomEvent("view-cube-layout", { detail: { offset, height } })),
         });
+        this.#babylonJSController.setQuickLookAssetProvider(this.#quickLookAssetProvider);
         this.#babylonJSController.enable();
 
     }
@@ -875,6 +879,20 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.downloadGLTF(1);
     }
 
+    /**
+     * Sets or clears the host-supplied asset opened by the iOS AR Quick Look action instead of the in-browser USDZ export.
+     * The provider is retained across connection cycles, even when set before the element is connected.
+     * @public
+     * @param {?(function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>)} provider
+     *   Async asset factory (defaults: MIME `model/vnd.usdz+zip`, file name `model.usdz`), or null to restore the built-in export.
+     *   A failing provider falls back to the built-in export with a console warning.
+     * @returns {void}
+     */
+    setQuickLookAssetProvider(provider) {
+        this.#quickLookAssetProvider = typeof provider === "function" ? provider : null;
+        this.#babylonJSController?.setQuickLookAssetProvider(this.#quickLookAssetProvider);
+    }
+
     /**
      * Downloads the current 3D model as a USDZ file.
      * @public

package/src/pref-viewer.js

@@ -43,6 +43,7 @@ import I18n from "./localization/i18n.js";
  *  - showModel / hideModel / showScene / hideScene: Toggle visibility using the internal task queue for consistent sequencing.
  *  - zoomCenter / zoomExtentsAll / zoomIn / zoomOut: Forward zoom commands to the 2D controller when active.
  *  - downloadModelGLB / downloadModelGLTF / downloadModelUSDZ: Export the loaded model in the requested format.
+ *  - setQuickLookAssetProvider(provider): Supplies (or clears) the asset opened by the iOS AR Quick Look action.
  *  - downloadSceneGLB / downloadSceneGLTF / downloadSceneUSDZ: Export the loaded environment in the requested format.
  *  - downloadModelAndSceneGLB / downloadModelAndSceneGLTF / downloadModelAndSceneUSDZ: Export the combined scene in the requested format.
  *  - openDialog / closeDialog: Manage PrefViewerDialog instances rendered inside the shadow tree.
@@ -115,6 +116,7 @@ export default class PrefViewer extends HTMLElement {
     #wrapper = null;
     #component2D = null;
     #component3D = null;
+    #quickLookAssetProvider = null; // Host asset provider, reapplied to every 3D component this element creates
     #dialog = null;
     #menu3D = null;
 
@@ -394,6 +396,7 @@ export default class PrefViewer extends HTMLElement {
      * Creates and appends the 3D viewer component to the shadow DOM, initially hidden.
      * Forwards renderer selection and show-view-cube, stores its layout handler in #handlers and subscribes before activation
      * so the first measured layout positions the render menu correctly.
+     * Hands any retained Quick Look asset provider to the new component.
      * @private
      * @returns {void}
      */
@@ -401,6 +404,7 @@ export default class PrefViewer extends HTMLElement {
         this.#handlers.on3DElementClick = this.#on3DElementClick.bind(this);
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
+        this.#component3D.setQuickLookAssetProvider?.(this.#quickLookAssetProvider);
         this.#component3D.setAttribute("view-cube-renderer", this.viewCubeRenderer);
         this.#component3D.setAttribute("show-view-cube", this.getAttribute("show-view-cube") === "false" ? "false" : "true");
         this.#handlers.onViewCubeLayout = (event) => {
@@ -1289,6 +1293,21 @@ export default class PrefViewer extends HTMLElement {
         this.#component3D.downloadModelGLTF();
     }
 
+    /**
+     * Sets or clears the host-supplied asset opened by the iOS AR Quick Look action instead of the in-browser USDZ export.
+     * The provider is retained across connection cycles, even when set before the element is connected.
+     * The viewer knows nothing about how the host produces the asset.
+     * @public
+     * @param {?(function(): Promise<{data: (Uint8Array|ArrayBuffer|Blob), mimeType?: string, fileName?: string}>)} provider
+     *   Async asset factory (defaults: MIME `model/vnd.usdz+zip`, file name `model.usdz`), or null to restore the built-in export.
+     *   A failing provider falls back to the built-in export with a console warning.
+     * @returns {void}
+     */
+    setQuickLookAssetProvider(provider) {
+        this.#quickLookAssetProvider = typeof provider === "function" ? provider : null;
+        this.#component3D?.setQuickLookAssetProvider?.(this.#quickLookAssetProvider);
+    }
+
     /**
      * Initiates download of the current 3D model in USDZ format.
      * @public

package/src/quick-look-action.js

@@ -17,6 +17,22 @@ export default class QuickLookAction {
      */
     static QUICK_LOOK_FRAGMENT = "allowsContentScaling=0";
 
+    /**
+     * MIME type of a USDZ archive; the only type whose bytes are validated as a ZIP before being exposed.
+     * @public
+     * @static
+     * @type {string}
+     */
+    static USDZ_MIME_TYPE = "model/vnd.usdz+zip";
+
+    /**
+     * File name given to the anchor's `download` attribute when the prepared asset does not name itself.
+     * @public
+     * @static
+     * @type {string}
+     */
+    static DEFAULT_FILE_NAME = "model.usdz";
+
     #anchor;
     #style;
     #window;
@@ -55,7 +71,7 @@ export default class QuickLookAction {
         this.#anchor = document.createElement("a");
         this.#anchor.className = "babylonVRicon pref-viewer-quick-look";
         this.#anchor.rel = "ar";
-        this.#anchor.download = "model.usdz";
+        this.#anchor.download = QuickLookAction.DEFAULT_FILE_NAME;
         this.#anchor.setAttribute("role", "button");
         this.#anchor.tabIndex = 0;
         this.#anchor.hidden = true;
@@ -204,11 +220,38 @@ export default class QuickLookAction {
     }
 
     /**
-     * Queues current-model export and exposes only a nonempty ZIP-signature USDZ as a native link.
+     * Normalizes an exporter result into the bytes, MIME type and file name of the asset to expose.
+     * A bare `Uint8Array` is a USDZ with default metadata; an object carries its own optional metadata.
+     * USDZ content must be a nonempty ZIP-signature archive; other MIME types are passed through as-is.
+     * @private
+     * @static
+     * @param {Uint8Array|{data: Uint8Array, mimeType?: string, fileName?: string}} result - Exporter result.
+     * @returns {{data: Uint8Array, mimeType: string, fileName: string}} Validated asset description.
+     * @throws {Error} When the result is not byte content or a USDZ lacks the ZIP signature.
+     */
+    static #resolveAsset(result) {
+        const isDescribed = !!result && typeof result === "object" && !(result instanceof Uint8Array);
+        const data = isDescribed ? result.data : result;
+        const mimeType = (isDescribed && result.mimeType) || QuickLookAction.USDZ_MIME_TYPE;
+        const fileName = (isDescribed && result.fileName) || QuickLookAction.DEFAULT_FILE_NAME;
+        if (!(data instanceof Uint8Array) || data.length === 0) {
+            throw new Error("PrefViewer: invalid Quick Look export");
+        }
+        // USDZ is a ZIP archive; never expose empty, JSON or glTF results as native AR.
+        if (mimeType === QuickLookAction.USDZ_MIME_TYPE
+            && (data.length < 4 || data[0] !== 0x50 || data[1] !== 0x4b || data[2] !== 3 || data[3] !== 4)) {
+            throw new Error("PrefViewer: invalid USDZ export");
+        }
+        return { data, mimeType, fileName };
+    }
+
+    /**
+     * Queues current-model export and exposes only a valid asset as a native link: a nonempty ZIP-signature USDZ,
+     * or, when the exporter describes another MIME type, that asset unchanged.
      * Obsolete revisions are ignored. Export failures are logged and shown as a retry action;
      * they do not reject the returned work promise or expose an older model's content.
      * @public
-     * @param {?(function(): Promise<Uint8Array>)} exporter - Current-model serializer, or null to invalidate without preparation.
+     * @param {?(function(): Promise<Uint8Array|{data: Uint8Array, mimeType?: string, fileName?: string}>)} exporter - Current-model serializer returning USDZ bytes or a described asset (defaults: USDZ MIME type, `model.usdz`), or null to invalidate without preparation.
      * @returns {Promise<void>} Resolves after this queued preparation settles or becomes obsolete.
      */
     update(exporter) {
@@ -231,17 +274,15 @@ export default class QuickLookAction {
                 return;
             }
             try {
-                const bytes = await exporter();
+                const result = await exporter();
                 if (this.#disposed || revision !== this.#revision) {
                     return;
                 }
-                // USDZ is a ZIP archive; never expose empty, JSON or glTF results as native AR.
-                if (!(bytes instanceof Uint8Array) || bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b || bytes[2] !== 3 || bytes[3] !== 4) {
-                    throw new Error("PrefViewer: invalid USDZ export");
-                }
-                const blob = new this.#window.Blob([bytes], {
-                    type: "model/vnd.usdz+zip"
+                const asset = QuickLookAction.#resolveAsset(result);
+                const blob = new this.#window.Blob([asset.data], {
+                    type: asset.mimeType
                 });
+                this.#anchor.download = asset.fileName;
                 this.#url = this.#urlAPI.createObjectURL(blob);
                 // Quick Look reads the fragment: content scaling off keeps the authored 1:1 metre scale,
                 // matching the Android WebXR path. The bare URL is kept for revocation.

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;
+    }
+}