@displayxr/inline3d 1.3.0 → 1.5.0

package/js/inline3d.js

@@ -24,6 +24,25 @@
 // { supported:false } and your page shows its normal 2D content — inline-3D is progressive
 // enhancement, never a hard dependency.
 
+// Undock lives in its own module (it is a page-level action, not a per-frame concern, and it
+// works standalone on a browser with no inline-3D at all). Imported here for ONE reason: to hand
+// it a resolver so its API-first path can find the live XRDisplayLayer behind an element. The
+// dependency runs one way — inline3d-undock.js imports nothing — so there is no cycle, and the
+// three entry points are re-exported below so a page has a single import site.
+import { undock, undockAvailable, undockUrl, tileScreenRect, setUndockLayerResolver } from './inline3d-undock.js';
+export { undock, undockAvailable, undockUrl, tileScreenRect };
+
+// The eased 2D<->3D transition. A pure state machine (no DOM, no WebXR) ported from the native
+// `dxr::ModeSwitch`, so the browser eases the disparity around a mode switch the same way — and in
+// the same ORDER — as the native apps and the demos. See _requestRenderingModeEased.
+import {
+  ModeSwitch,
+  MODE_SWITCH_DEFAULT_DURATION_MS,
+  MODE_SWITCH_DEFAULT_EASING,
+  MODE_SWITCH_EASINGS,
+  normaliseModeSwitchEasing,
+} from './inline3d-mode-switch.js';
+
 // The document's single live manager. The browser's per-frame element-rect report is a
 // WHOLE-WIDGET setter — each live session pushes the complete list of rects to weave — so two
 // managers in one document overwrite each other frame by frame and neither one's tiles hold
@@ -31,6 +50,26 @@
 // manager and opens the next) are legitimate and the common case, so nothing is refused.
 let liveManager = null;
 
+// How the undock helper's API-first path finds the layer behind an element. Registered here
+// because only this module knows the canvas -> window -> layer map; the helper stays importable
+// on its own (with no resolver, every call takes the protocol fallback).
+setUndockLayerResolver((el) => {
+  const m = liveManager;
+  if (!m || !m._running || !el) return null;
+  // The canvas itself, then a woven canvas INSIDE the element (a card wrapping its tile), then
+  // the element sitting inside a window's own container (a button in the tile's box). Anything
+  // further away is not this window's rect and takes the fallback.
+  for (const win of m._windows.values()) if (win.canvas === el && win.layer) return win.layer;
+  for (const win of m._windows.values()) {
+    if (win.layer && typeof el.contains === 'function' && el.contains(win.canvas)) return win.layer;
+  }
+  for (const win of m._windows.values()) {
+    const box = win.canvas.parentElement;
+    if (win.layer && box && typeof box.contains === 'function' && box.contains(el)) return win.layer;
+  }
+  return null;
+});
+
 const hasWebXR = () => typeof navigator !== 'undefined' && !!navigator.xr;
 const hasLayer = () =>
   typeof window !== 'undefined' && typeof window.XRDisplayLayer === 'function';
@@ -58,6 +97,59 @@ const hasViewRig = () => {
     return false; // a prototype that refuses to be probed is not a capability
   }
 };
+// Display modes — the display's own capabilities, and the one thing a page can ask it to
+// change. Three methods, all on XRDisplayLayer, all promise-returning:
+//
+//   getDisplayInfo()          the panel: physical size, pixel size, the view scale it
+//                             RECOMMENDS. Null on a machine with no glasses-free display.
+//   getRenderingModes()       every mode the runtime can put the panel in — view count, tile
+//                             grid, per-view pixels, whether it is a hardware-3D mode, which
+//                             one is active, and whether the browser may request it.
+//   requestRenderingMode(i)   switch the panel to mode i. The browser renders exactly TWO
+//                             views, so a mode with viewCount > 2 is listed and refused; a
+//                             ONE-view mode IS requestable and is how a page goes flat.
+//
+// THE HARDWARE DISPLAY STATE (2D/3D) IS NOT A SEPARATE CONTROL, and that is the whole shape of
+// this API. It is a CONSEQUENCE of the active rendering mode: request a one-view mode and the
+// browser puts the panel in its 2D state and reports that mode active (the runtime carries on
+// weaving the same fixed two-view atlas); request the two-view mode and the panel goes back to
+// 3D. The transition arrives as `hardwaredisplaystatechange`. There is deliberately NO
+// page-facing request for the hardware state on its own: a page that could move the panel flat
+// while still submitting stereo would be showing the woven atlas flat, which is a blurry double
+// image rather than 2D. Tying the two together makes that state unreachable.
+//
+// Probed the same way as setViewRig, and for the same reason: these are METHODS, so reading
+// them off the prototype is a plain data-property read that calls nothing (an IDL *attribute*
+// getter would throw `Illegal invocation` on the very browser that has it). All three are
+// required — a browser with a partial set is a browser mid-implementation, and treating it as
+// supported would hand a page a `requestRenderingMode is not a function` at the worst moment.
+const DISPLAY_MODE_METHODS = ['getDisplayInfo', 'getRenderingModes', 'requestRenderingMode'];
+// The two display events, fired on the XRSession rather than the layer — so a page hears about a
+// mode or hardware-state change even while its tile's layer is closed (lazy mode), and one
+// subscription covers every window in the document.
+const DISPLAY_EVENTS = ['renderingmodechange', 'hardwaredisplaystatechange'];
+const hasDisplayModes = () => {
+  if (!hasLayer()) return false;
+  try {
+    const proto = window.XRDisplayLayer.prototype;
+    return DISPLAY_MODE_METHODS.every((m) => typeof proto[m] === 'function');
+  } catch {
+    return false; // a prototype that refuses to be probed is not a capability
+  }
+};
+// Undock (XRDisplayLayer.undock / getUndockCapabilities) — lifting this window's asset out of
+// the page into a floating native viewer over the desktop. Same METHOD probe, same reason. The
+// helper in ./inline3d-undock.js falls back to the `displayxr-view:` OS protocol where this is
+// absent, so a page never has to branch on it; what it IS good for is deciding whether to show
+// an "undock" affordance at all (see `wall.undock`).
+const hasUndock = () => {
+  if (!hasLayer()) return false;
+  try {
+    return typeof window.XRDisplayLayer.prototype.undock === 'function';
+  } catch {
+    return false;
+  }
+};
 // ── draw-order occlusion (browser Phase 2, browser patches 0063/0064) ─────────────────────
 //
 // The browser composites ANY 2D content over a woven tile per-pixel BY DRAW ORDER — headers,
@@ -202,6 +294,157 @@ export function inline3dViewRigSupported() {
   return inline3DAvailable() && hasViewRig();
 }
 
+/**
+ * True when this browser exposes the DISPLAY-MODE API — `getDisplayInfo()`,
+ * `getRenderingModes()` and `requestRenderingMode()` on the tile handle, i.e. the page can read
+ * what the panel is and ask it to change. Sync + cheap; implies {@link inline3DAvailable}.
+ *
+ * Reads a capability (the presence of all three methods on `XRDisplayLayer.prototype`), never a
+ * version or UA string, and demands ALL THREE: a browser shipping half the set is one mid-
+ * implementation, and calling it supported would surface as a `not a function` inside a click
+ * handler rather than as a feature that is simply absent.
+ *
+ * Everything the API drives is optional enhancement — the window weaves identically without it —
+ * so a page needs this only to decide whether to SHOW display controls. The handle methods
+ * themselves reject with a clear Error rather than throwing at import or create time.
+ */
+export function inline3dDisplayModesSupported() {
+  return inline3DAvailable() && hasDisplayModes();
+}
+
+/**
+ * True when this browser can UNDOCK a window's asset into a floating native viewer through
+ * `XRDisplayLayer.undock()` — i.e. without the `displayxr-view:` protocol prompt the fallback
+ * path needs. Sync + cheap; implies {@link inline3DAvailable}.
+ *
+ * A page does not have to branch on this to undock (the helper falls back on its own); it is the
+ * probe for whether `wall.undock` carries capabilities, and for a UI that wants to say WHICH
+ * asset kinds this build can float.
+ */
+export function inline3dUndockSupported() {
+  return inline3DAvailable() && hasUndock();
+}
+
+// The rig `virtualDisplayHeight` is shorthand for: a display rig, identity pose, all factors 1.
+// Written out here because the automatic 1-view collapse has to be able to say "the default rig,
+// but flat", and there is no way to express that as a scalar — the whole descriptor has to be sent.
+function defaultDisplayRig(win) {
+  return {
+    type: 'display',
+    position: { x: 0, y: 0, z: 0 },
+    orientation: { x: 0, y: 0, z: 0, w: 1 },
+    virtualDisplayHeight: win.virtualDisplayHeight > 0 ? win.virtualDisplayHeight : 0.24,
+    ipdFactor: 1,
+    parallaxFactor: 1,
+    perspectiveFactor: 1,
+  };
+}
+
+// The page's rig with the stereo dialled DOWN by `factor`: eye separation and head-tracking
+// response scaled together, so `factor` 0 renders both eyes from the SAME place (the woven atlas
+// carries one image twice) and `factor` 1 is exactly what the page asked for. Everything between
+// is the eased 2D<->3D transition (see ModeSwitch) — which is why this is a scale and not a
+// boolean: a flat panel and a full-disparity one are the two ENDS of one continuum.
+//
+// A COPY, never a mutation. A page driving a rig per frame reuses one descriptor object
+// (cameraRigFromCamera's `out`), so scaling the factors in place would write the flattening into
+// the page's own state and it would never come back — the restore would restore 0.
+//
+// An unset factor is the runtime's default of 1, so it scales like an explicit 1 rather than
+// staying absent: a rig that says nothing about disparity still goes flat.
+function scaledRig(rig, factor) {
+  const ipd = Number.isFinite(rig.ipdFactor) ? rig.ipdFactor : 1;
+  const parallax = Number.isFinite(rig.parallaxFactor) ? rig.parallaxFactor : 1;
+  return { ...rig, ipdFactor: ipd * factor, parallaxFactor: parallax * factor };
+}
+
+// How often the fallback tick advances a transition when session frames are NOT arriving (a
+// background tab, every tile scrolled away). Roughly one 60 Hz frame — the ramp is time-based, so
+// this is a floor on smoothness, never on duration.
+const MODE_SWITCH_TICK_MS = 16;
+
+// Wall clock for the transition ramp, in ms. Read through the global on every call (never
+// captured) so a test can install its own clock, and so a page that runs before `performance`
+// exists still gets a monotonic-enough source. Frame COUNTS are deliberately not used: the ramp
+// has to take the same time at 30 fps and at 144 fps.
+function nowMs() {
+  return typeof performance !== 'undefined' && performance && typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now();
+}
+
+// The easing option, validated here rather than in the state machine: the sequencer falls back
+// silently (it has no opinion about a caller's config), but a typo in `createInline3D` is worth
+// exactly one warning — a page that asked for 'ease-in-out' and got smoothstep should know.
+let notedModeSwitchEasing = false;
+function resolveModeSwitchEasing(easing) {
+  if (easing === undefined || easing === null) return MODE_SWITCH_DEFAULT_EASING;
+  const known = normaliseModeSwitchEasing(easing);
+  if (known) return known;
+  if (!notedModeSwitchEasing) {
+    notedModeSwitchEasing = true;
+    console.warn(
+      `[inline3d] createInline3D({ modeSwitch: { easing: ${JSON.stringify(easing)} } }) is not a ` +
+        `curve this SDK knows (${MODE_SWITCH_EASINGS.join(' / ')}); using ` +
+        `'${MODE_SWITCH_DEFAULT_EASING}'.`
+    );
+  }
+  return MODE_SWITCH_DEFAULT_EASING;
+}
+
+// Why the SDK collapses the rig behind the page's back, said once, where the code is.
+let notedAutoCollapse = false;
+function noteAutoCollapse() {
+  if (notedAutoCollapse) return;
+  notedAutoCollapse = true;
+  console.info(
+    '[inline3d] The active rendering mode is 1-view, so this SDK has zeroed every window rig ' +
+      '(ipdFactor/parallaxFactor -> 0) — both eyes now render from one place. The runtime keeps ' +
+      'weaving the same two-view atlas whatever the page submits, so leaving stereo in it would ' +
+      'put two slightly different images on a flat panel, i.e. a blurry double image instead of ' +
+      '2D. Your rendering is unchanged; the flattening is a copy applied on the way to the layer ' +
+      'and it is undone the moment a 2-view mode goes active again.'
+  );
+}
+
+// ── reading the two display events ──────────────────────────────────────────────────────
+//
+// The payload is read DEFENSIVELY, in the shape the 0128-era handling already established: an
+// event's own `detail` when it carries one, and otherwise the event object itself. A browser
+// mid-implementation carried nothing at all and the state had to be read back — which still
+// works, because an unreadable payload leaves the value unknown and the mode list answers it.
+// `!== undefined` rather than `in`: a CustomEvent always HAS a `detail` property, and a null one
+// is not a payload.
+function eventDetail(e) {
+  return e && e.detail !== undefined && e.detail !== null ? e.detail : undefined;
+}
+function eventPayloads(e) {
+  const d = eventDetail(e);
+  return d !== undefined ? [d, e] : [e];
+}
+/** The new active mode index an event carries — a bare number, `.modeIndex`, or `.mode`. -1 = not stated. */
+function eventModeIndex(e) {
+  for (const src of eventPayloads(e)) {
+    if (typeof src === 'number' && Number.isFinite(src)) return src;
+    if (src && typeof src === 'object') {
+      const v = src.modeIndex !== undefined ? src.modeIndex : src.mode;
+      if (typeof v === 'number' && Number.isFinite(v)) return v;
+    }
+  }
+  return -1;
+}
+/** The hardware display state an event carries — a bare '2d'/'3d' or `.state`. null = not stated. */
+function eventHardwareState(e) {
+  for (const src of eventPayloads(e)) {
+    if (src === '2d' || src === '3d') return src;
+    if (src && typeof src === 'object') {
+      const v = src.state !== undefined ? src.state : src.hardwareDisplayState;
+      if (v === '2d' || v === '3d') return v;
+    }
+  }
+  return null;
+}
+
 // One-shot notices about view rigs. Both are per-document, and both describe a situation that is
 // identical on every frame — so warning per call would bury the page's own logs in a rAF loop.
 let notedNoViewRig = false;
@@ -249,10 +492,30 @@ function noteRigWinsOverHeight() {
  *        exclusively via addGlobalOverlay()/data-inline3d-overlay. Ignored (nothing is
  *        scanned, no `will-change` is set on your DOM) on a browser with draw-order
  *        occlusion, where chrome occludes tiles by itself.
- * @returns {Promise<Inline3D | {supported:false, error?:Error}>}
+ * @param {object} [opts.modeSwitch]  The EASED 2D<->3D transition, on by default.
+ *        `{ durationMs=180, easing='smoothstep'|'linear'|'easeoutcubic', enabled=true }` — the
+ *        same defaults the native DisplayXR apps configure. Instead of snapping the stereo rig
+ *        the moment the panel's mode changes, a page-initiated switch ramps every window's
+ *        `ipdFactor`/`parallaxFactor` between 0 and what the page asked for, in the order that
+ *        looks right: going FLAT ramps the disparity out first and only then asks the panel to
+ *        switch, and coming BACK asks first and eases the disparity in once the panel reports
+ *        3D. `enabled:false` restores the plain snap. It is aesthetic policy only — the runtime
+ *        keeps the eye set coherent either way — and a mode change the page did NOT request
+ *        (another tab, the shell, a panel opening flat) always snaps, because there is nothing
+ *        to ramp from. Read the live state on `wall.modeSwitch`.
+ * @returns {Promise<Inline3D | {supported:false, error?:Error}>} the manager, which also carries
+ *        the display API (`getDisplayInfo` / `getRenderingModes` / `requestRenderingMode` /
+ *        `setStereoEnabled`, `on`/`off`) and `undock` — `{model, splat}` on a browser with
+ *        `XRDisplayLayer.undock`, `null` on one without.
  */
 export async function createInline3D(opts = {}) {
-  const { referenceSpace = 'viewer', lazy = true, rootMargin = '50% 0px', autoChrome = true } = opts;
+  const {
+    referenceSpace = 'viewer',
+    lazy = true,
+    rootMargin = '50% 0px',
+    autoChrome = true,
+    modeSwitch = null,
+  } = opts;
   if (!inline3DAvailable()) return { supported: false };
   let session;
   try {
@@ -268,7 +531,7 @@ export async function createInline3D(opts = {}) {
   } catch {
     /* rAF still fires without a ref space; views are just null (fine for image/video). */
   }
-  return new Inline3D(session, refSpace, { lazy, rootMargin, autoChrome });
+  return new Inline3D(session, refSpace, { lazy, rootMargin, autoChrome, modeSwitch });
 }
 
 /**
@@ -320,7 +583,7 @@ function chromeTextPlates(root) {
 }
 
 class Inline3D {
-  constructor(session, refSpace, { lazy, rootMargin, autoChrome = true }) {
+  constructor(session, refSpace, { lazy, rootMargin, autoChrome = true, modeSwitch = null }) {
     this.supported = true;
     this.session = session;
     this.refSpace = refSpace;
@@ -346,6 +609,41 @@ class Inline3D {
     // Set once the legacy occlusion machinery has been retired (draw-order browser whose
     // capability flag could only be read from a live layer). See _standDownLegacyOcclusion.
     this._stoodDown = false;
+    // ── display state ────────────────────────────────────────────────────────────────
+    // What the panel is doing, as last REPORTED (the first getRenderingModes read, then every
+    // renderingmodechange / hardwaredisplaystatechange). Never what was last requested: a
+    // refused request must leave every one of these untouched.
+    this._activeModeIndex = -1;
+    this._activeViewCount = 0; // 0 = not read yet
+    this._hardwareDisplayState = null; // '2d' | '3d' | null (never reported)
+    this._modes = null; // last getRenderingModes() result, for the viewCount lookup
+    // The rig-collapse latch, MANAGER-wide because the mode is the display's, not a window's.
+    // While true every rig that leaves for a layer is pushed flat (a copy — each window's own
+    // `viewRig` always holds what the page asked for, untouched).
+    this._stereoCollapsed = false;
+    this._displayListeners = new Map(); // event type -> Set(callback), for on()/off()
+    this._primedDisplayState = false;
+    // ── the eased 2D<->3D transition (opts.modeSwitch) ───────────────────────────────
+    // The collapse above is a LATCH; what actually reaches each layer is that latch turned into a
+    // SCALE — `_stereoFactor`, 0 (flat) to 1 (exactly the rig the page set). With the sequencer
+    // off, or for a mode change the page did not request, the scale is only ever 0 or 1 and
+    // nothing looks different. With it on, a page-initiated switch walks the scale across that
+    // range over `durationMs` and holds the mode request until the right end of the ramp.
+    const msOpts = modeSwitch && typeof modeSwitch === 'object' ? modeSwitch : {};
+    this._msEnabled = msOpts.enabled !== false;
+    this._modeSwitch = new ModeSwitch(
+      (Number.isFinite(msOpts.durationMs) ? Math.max(0, msOpts.durationMs) : MODE_SWITCH_DEFAULT_DURATION_MS) / 1000,
+      resolveModeSwitchEasing(msOpts.easing)
+    );
+    this._stereoFactor = 1; // what every window's ipd/parallax is multiplied by on the way out
+    this._msFire = null; // a ->2D request HELD until the ramp-down lands
+    this._msArmedUp = false; // a ->3D request went out; the up-ramp waits for the panel to say 3D
+    this._msLastMs = null; // wall clock of the previous advance (null = the ramp has not ticked)
+    this._msTick = null; // the frames-stopped fallback timer; see _armModeSwitchTick
+    // Undock capabilities, refreshed off the first live layer (see _refreshUndock). Null is the
+    // load-bearing value: it means this browser has no XRDisplayLayer.undock at all.
+    this.undock = hasUndock() ? { model: false, splat: false } : null;
+    this._undockRead = false;
     this._running = true;
     this._lazy = lazy;
     this._observer =
@@ -370,6 +668,7 @@ class Inline3D {
     }
     liveManager = this;
     session.addEventListener('end', () => this._teardown());
+    this._bindDisplayEvents();
     this._scanChrome(); // page chrome usually exists before the session does
     this._bindLifecycle();
     this._armDprWatch();
@@ -616,29 +915,202 @@ class Inline3D {
        * pointer it is not, and the fix is not to fight it — send an IDENTITY-posed camera rig
        * and parent your eye cameras under the app camera, so three composes the world pose with
        * zero lag (see `cameraRigFromCamera(..., {attach:true})` + `EyeCamera.setLocalFromView`).
+       *
+       * While `setStereoEnabled(false)` is in force the rig you pass here is STORED AS GIVEN and
+       * pushed FLAT (ipd/parallax 0) — the flattening is a latch on the way out, not a value
+       * written into your descriptor, so a page driving a rig every frame cannot undo the 2D
+       * state by simply carrying on, and `setStereoEnabled(true)` restores exactly what you last
+       * asked for. During the eased 2D<->3D transition the same applies with a FRACTION in place
+       * of the 0: what leaves for the layer is your rig scaled by `wall.modeSwitch.factor`.
        */
       setViewRig: (rig) => {
         win.viewRig = rig || null;
-        if (!hasViewRig()) {
-          noteNoViewRig();
-          return false;
-        }
-        if (!win.layer) return false;
-        try {
-          win.layer.setViewRig(rig);
-          return true;
-        } catch {
-          // A closed layer or a descriptor the browser refused. Neither is worth throwing over
-          // in a per-frame call — the window keeps weaving on the rig it already has.
-          return false;
-        }
+        return this._pushViewRig(win);
       },
+      /**
+       * The panel this window is weaving on: physical size in metres, pixel size, and the view
+       * scale the runtime RECOMMENDS. Resolves null on a machine with no glasses-free display.
+       *
+       * `recommendedViewScaleX/Y` are ADVISORY. The browser cannot resize a page's canvas, so
+       * nothing applies them for you: a page honours them by sizing its OWN backing store
+       * (canvas.width/height, `renderer.setSize`) to `viewPixels x scale`. Ignoring them costs
+       * sharpness or fill rate, never correctness.
+       *
+       * @returns {Promise<object|null>}
+       */
+      getDisplayInfo: () => this._layerCall(win, 'getDisplayInfo', 'getDisplayInfo()'),
+      /**
+       * Every rendering mode the runtime can put this display in, as reported by the runtime:
+       * `{modeIndex, modeName, viewCount, viewScaleX, viewScaleY, tileColumns, tileRows,
+       * viewWidthPixels, viewHeightPixels, hardwareDisplay3D, isActive, isRequestable}`.
+       *
+       * The list is the DISPLAY's, not the browser's, so it includes modes this browser cannot
+       * drive: the browser is fixed at TWO views, so any mode with `viewCount !== 2` is reported
+       * with `isRequestable: false` and `requestRenderingMode` refuses it. Show those rows — they
+       * are what the panel can do — but mark them, don't offer them.
+       *
+       * @returns {Promise<ReadonlyArray<object>>}
+       */
+      getRenderingModes: () => this._getRenderingModes(win),
+      /**
+       * Ask the runtime to switch the display to the mode with this `modeIndex`. A thin
+       * pass-through — it resolves and rejects exactly as the browser does.
+       *
+       * Rejects with a `TypeError` for a mode with `viewCount > 2` (the browser renders exactly
+       * two views and cannot fill a 4-view atlas — no view synthesis exists anywhere in this
+       * stack) or an unknown index, and with a `NotSupportedError` `DOMException` when the
+       * request was not forwardable. The browser raises the TypeError SYNCHRONOUSLY; this
+       * pass-through is async, so it reaches you as a rejection either way and one `.catch()`
+       * covers both. On a browser without the API at all it rejects with a plain Error saying so.
+       *
+       * A ONE-VIEW MODE IS REQUESTABLE, and requesting it is how a page goes flat: the browser
+       * puts the panel in its 2D hardware state and reports that mode active. The SDK then
+       * collapses every window's rig automatically (see {@link setStereoEnabled}) off the
+       * resulting `renderingmodechange` — so the request itself changes nothing about your
+       * rendering, and a REFUSED request changes nothing at all.
+       *
+       * On success the session fires `renderingmodechange` — see {@link on}. That event, not
+       * this promise, is when the new mode is in effect.
+       *
+       * EASED BY DEFAULT (`createInline3D({modeSwitch})`). A GOING-FLAT request (`viewCount === 1`)
+       * is HELD while the disparity ramps out, and forwarded only when it lands — so this promise
+       * resolves when the browser actually got the request, roughly `durationMs` later, and the
+       * panel flips on already-flat content. A request that a reversal drops in that window
+       * rejects with an `Error` named `superseded`; nothing was ever asked of the display. Coming
+       * BACK is unchanged in timing: the request goes out at once and the disparity eases in when
+       * the panel reports 3D.
+       *
+       * @param {number} modeIndex
+       * @returns {Promise<void>}
+       */
+      requestRenderingMode: (modeIndex) => this._requestRenderingModeEased(modeIndex, win),
+      /**
+       * SUGAR over {@link requestRenderingMode}, and nothing more. `false` requests the first
+       * mode with `viewCount === 1 && isRequestable`; `true` requests the first with
+       * `viewCount === 2 && isRequestable`. It never touches the hardware display state
+       * directly — there is no such call in this API — and it never touches your rig.
+       *
+       * THE RIG COLLAPSE IS NOT PART OF THIS CALL. When a 1-view mode actually goes ACTIVE the
+       * SDK zeroes every window's `ipdFactor`/`parallaxFactor` on the way to the layer, and
+       * restores them when a 2-view mode goes active; that is driven by the
+       * `renderingmodechange` event (and by the first `getRenderingModes()` read), so it happens
+       * however the mode changed — this call, another tab, the shell — and a request that is
+       * REFUSED leaves everything exactly as it was, in both directions.
+       *
+       * The flattening is a COPY pushed at the layer, never a write into your descriptor: a page
+       * driving `setViewRig` every frame keeps having its rig stored intact and pushed flat, and
+       * the restore is exactly the rig it last asked for. A page that never set a rig gets the
+       * exact descriptor equivalent of its `virtualDisplayHeight`.
+       *
+       * Rejects when no such mode is listed (a plain Error naming what was looked for), and
+       * otherwise exactly as `requestRenderingMode` does. Resolves to the boolean asked for —
+       * the request was accepted; the mode is in force when the event says so.
+       *
+       * Eased by default, exactly as {@link requestRenderingMode} is: `false` ramps the disparity
+       * out before the request goes anywhere, `true` requests first and eases the disparity back
+       * in once the panel reports 3D, and pressing the pair in quick succession reverses cleanly
+       * rather than firing a stale switch.
+       *
+       * @param {boolean} enabled
+       * @returns {Promise<boolean>}
+       */
+      setStereoEnabled: (enabled) => this._setStereoEnabled(enabled, win),
+      /**
+       * Subscribe to one display event, re-emitted on this handle:
+       *
+       *   `renderingmodechange`        `{type, modeIndex, viewCount, mode, detail}`
+       *   `hardwaredisplaystatechange` `{type, state:'2d'|'3d', detail}`
+       *
+       * They originate on the XRSession, not on the layer — so they arrive even for a window
+       * whose layer is currently closed, and a page that only wants to KNOW does not have to
+       * hold a live tile. `detail` is the browser's own payload, kept as-is.
+       *
+       * Returns an unsubscribe function; `off(type, cb)` does the same. Inert (returns a no-op)
+       * on a browser without the API.
+       *
+       * @param {'renderingmodechange'|'hardwaredisplaystatechange'} type
+       * @param {(e:object) => void} cb
+       * @returns {() => void}
+       */
+      on: (type, cb) => this.on(type, cb),
+      /** Drop a listener registered with {@link on}. */
+      off: (type, cb) => this.off(type, cb),
+      /**
+       * BOTH display events through one callback — the older shape, kept because pages use it.
+       * The callback gets the same normalised object `on()` delivers (`{type, ...}` plus
+       * `detail`). Returns an unsubscribe function.
+       *
+       * @param {(e:{type:string, detail:any}) => void} cb
+       * @returns {() => void}
+       */
+      onDisplayModeChange: (cb) => this._onDisplayModeChange(cb),
       // Read-only counters, for pages that want to see the load-induced mono fallback rather
       // than wait for a bug report about "blinking". Scene windows only; 0/0 elsewhere.
       stats: () => ({ frames: win.frames, monoFrames: win.monoFrames }),
     };
   }
 
+  // ── the display (wall level) ──────────────────────────────────────────────────────────
+  //
+  // The panel is the DOCUMENT's, not a tile's: one display, one active rendering mode, one
+  // hardware state. These four are the same calls the tile handles carry (kept there because
+  // pages use them), routed through whichever window currently holds a live layer — so they
+  // keep working while a lazy tile is scrolled away, as long as ANY tile is live.
+
+  /** The panel: physical size, pixel size, the view scale it recommends. Null where there is none. */
+  getDisplayInfo() {
+    return this._layerCall(this._liveWindow(null), 'getDisplayInfo', 'getDisplayInfo()');
+  }
+
+  /** Every rendering mode the runtime can put this display in. See the handle's doc comment. */
+  getRenderingModes() {
+    return this._getRenderingModes(null);
+  }
+
+  /** Ask the runtime to switch the display to `modeIndex`. Pass-through; see the handle's doc. */
+  requestRenderingMode(modeIndex) {
+    return this._requestRenderingModeEased(modeIndex, null);
+  }
+
+  /** Sugar over {@link requestRenderingMode}: false -> a 1-view mode, true -> the 2-view mode. */
+  setStereoEnabled(enabled) {
+    return this._setStereoEnabled(enabled, null);
+  }
+
+  /**
+   * The hardware display state as last REPORTED by `hardwaredisplaystatechange` — `'2d'`,
+   * `'3d'`, or `null` when the browser has not said yet. Never what was last requested.
+   */
+  get hardwareDisplayState() {
+    return this._hardwareDisplayState;
+  }
+
+  /** The active mode's index and view count as last read/reported. `viewCount` 0 = not read yet. */
+  get activeMode() {
+    return { modeIndex: this._activeModeIndex, viewCount: this._activeViewCount };
+  }
+
+  /** True while the SDK is holding every window's rig flat because a 1-view mode is active. */
+  get stereoCollapsed() {
+    return this._stereoCollapsed;
+  }
+
+  /**
+   * The eased 2D<->3D transition, live: `{active, factor}`.
+   *
+   * `factor` is what every window's `ipdFactor`/`parallaxFactor` is being multiplied by on the way
+   * to the layer — `1` in 3D, `0` flat, in between mid-ramp. `active` is true while a
+   * page-initiated switch is in any of its phases: ramping the disparity out, holding the ->2D
+   * request until it lands, waiting for the panel to report 3D, or easing back in.
+   *
+   * Read-only and purely informational — a page that wants to grey a button or cross-fade some 2D
+   * chrome alongside the panel can, and one that does not care never has to look. The SDK adds no
+   * UI of its own for this, and never will: which key or button toggles the display is the page's.
+   */
+  get modeSwitch() {
+    return { active: this._msTransitionActive(), factor: this._stereoFactor };
+  }
+
   close() {
     try {
       this.session.end();
@@ -650,6 +1122,615 @@ class Inline3D {
 
   // ── internals ───────────────────────────────────────────────────────────────────────
 
+  // ── view rig + display modes ──────────────────────────────────────────────────────────
+
+  /**
+   * The rig this window's layer should actually be holding right now: what the page asked for,
+   * scaled by the manager's current stereo factor (0 while a 1-view mode is active, 1 in 3D, and
+   * everything between during an eased transition). Null means "say nothing" — leave the browser
+   * on the `virtualDisplayHeight` shorthand it was built with.
+   *
+   * Used in BOTH directions (push at a live layer, build a new one), which is the point: a tile
+   * that scrolls away and rebuilds while stereo is off must not come back in 3D.
+   */
+  _effectiveViewRig(win) {
+    if (this._stereoFactor >= 1) {
+      // `stereoSynthRig`: this window never had a rig of its own, so going flat had to SEND one
+      // (there is no way to say "the default, but flat" as a scalar). Coming back therefore has
+      // to send the un-flat version explicitly too — returning null here would leave the layer
+      // holding the flattened rig forever. The descriptor it sends is the exact equivalent of the
+      // `virtualDisplayHeight` the layer was built with, so nothing about the framing moves.
+      return win.viewRig || (win.stereoSynthRig ? defaultDisplayRig(win) : null);
+    }
+    // Going flat has to SEND a descriptor even for a window that never had a rig of its own
+    // (there is no way to say "the default, but flat" as a scalar), and that fact has to be
+    // remembered: coming back must then send the un-flat version explicitly, or the layer would
+    // hold the flattened rig forever. Recorded here rather than in the collapse itself because a
+    // window CREATED while the panel is already flat goes down this path on its first activate.
+    if (!win.viewRig) win.stereoSynthRig = true;
+    return scaledRig(win.viewRig || defaultDisplayRig(win), this._stereoFactor);
+  }
+
+  /**
+   * Latch (or release) the manager-wide rig collapse and push every window's rig again.
+   *
+   * Driven ONLY by what the display reports — the first `getRenderingModes()` read and every
+   * `renderingmodechange` — never by a request. That is what makes a refused request a no-op in
+   * both directions: nothing here runs unless the mode actually changed.
+   *
+   * THE REPORT OWNS THE FACTOR ONLY WHEN THE SEQUENCER DOES NOT. A mode change the page did not
+   * ask for (another tab, the shell, a panel that opened flat) snaps, because there is nothing to
+   * ramp FROM — the transition is a page-initiated aesthetic, not a correctness step. The two
+   * exceptions are the two halves of a page-initiated switch: while a ramp is in flight it owns
+   * the factor outright, and a report of 3D that a `->3D` request armed starts the up-ramp here
+   * rather than snapping (the whole reason that request fires first and eases second).
+   */
+  _setStereoCollapsed(collapsed) {
+    const next = !!collapsed;
+    if (this._stereoCollapsed === next) return;
+    this._stereoCollapsed = next;
+    if (next) noteAutoCollapse();
+    if (!next && this._msArmedUp) {
+      this._msArmedUp = false;
+      this._startUpRamp(); // the panel is in 3D at last — ease the disparity back in
+    } else if (!this._modeSwitch.active()) {
+      this._stereoFactor = next ? 0 : 1;
+    }
+    for (const win of this._windows.values()) {
+      // Diagnostics only: the factors that were in force when the panel went flat. The restore
+      // itself just re-pushes `win.viewRig`, which was never mutated.
+      if (next) {
+        const rig = win.viewRig || defaultDisplayRig(win);
+        win.stereoSaved = { ipdFactor: rig.ipdFactor, parallaxFactor: rig.parallaxFactor };
+      } else {
+        win.stereoSaved = null;
+      }
+      this._pushViewRig(win);
+    }
+  }
+
+  /**
+   * Push the effective rig at the live layer. Returns whether it reached one — the boolean
+   * `handle.setViewRig` documents ("false = stored, and it will build the next layer").
+   */
+  _pushViewRig(win) {
+    if (!hasViewRig()) {
+      noteNoViewRig();
+      return false;
+    }
+    if (!win.layer) return false;
+    const rig = this._effectiveViewRig(win);
+    try {
+      win.layer.setViewRig(rig);
+      return true;
+    } catch {
+      // A closed layer or a descriptor the browser refused. Neither is worth throwing over in a
+      // per-frame call — the window keeps weaving on the rig it already has.
+      return false;
+    }
+  }
+
+  /**
+   * Forward one display-mode call to this window's live layer, as a promise.
+   *
+   * Two ways it cannot proceed, and they are DIFFERENT failures worth different messages: the
+   * browser has no such API at all (nothing will ever make this work — check
+   * `inline3dDisplayModesSupported()` first), or the API is there but this window has no live
+   * layer yet (lazy mode, scrolled away, or called before the first activation — try again once
+   * the tile is on screen). Neither throws synchronously: these sit behind click handlers and a
+   * rejected promise is what a page can actually handle.
+   */
+  _layerCall(win, method, label, args = []) {
+    if (!hasDisplayModes()) {
+      return Promise.reject(
+        new Error(
+          `[inline3d] ${label} needs a DisplayXR Browser with the display-mode API ` +
+            '(XRDisplayLayer.getDisplayInfo/getRenderingModes/requestRenderingMode). ' +
+            'Gate on inline3dDisplayModesSupported().'
+        )
+      );
+    }
+    // `win` is null when the WALL-level call ran with no window live at all — the same failure
+    // as a window whose layer is closed, and the same message covers both.
+    if (!win || !win.layer) {
+      return Promise.reject(
+        new Error(
+          `[inline3d] ${label} needs a live weave layer, and this window has none right now ` +
+            '(lazy mode closes the layer while the tile is off screen). Call it once the tile ' +
+            'is visible, or create the manager with { lazy: false }.'
+        )
+      );
+    }
+    // Wrapped so a SYNCHRONOUS throw from the browser (requestRenderingMode raises TypeError
+    // that way for a non-2-view mode) arrives as a rejection like every other failure.
+    try {
+      return Promise.resolve(win.layer[method](...args));
+    } catch (e) {
+      return Promise.reject(e);
+    }
+  }
+
+  /** The first window currently holding a live layer, or null. Every display call needs one. */
+  _liveWindow(preferred) {
+    if (preferred && preferred.layer) return preferred;
+    for (const win of this._windows.values()) if (win.layer) return win;
+    return preferred || null;
+  }
+
+  /**
+   * `getRenderingModes()` with the manager's cache kept honest — every read updates the list the
+   * event path looks `viewCount` up in, and the first one PRIMES the display state (a page can
+   * open with the panel already flat, and the rig has to be collapsed for that too).
+   */
+  async _getRenderingModes(win) {
+    const list = await this._layerCall(
+      this._liveWindow(win),
+      'getRenderingModes',
+      'getRenderingModes()'
+    );
+    const modes = Array.isArray(list) ? list : [];
+    this._modes = modes;
+    const active = modes.find((m) => m.isActive);
+    if (active) {
+      this._activeModeIndex = active.modeIndex;
+      this._activeViewCount = active.viewCount;
+      if (active.viewCount === 1 || active.viewCount === 2) {
+        this._setStereoCollapsed(active.viewCount === 1);
+      }
+    }
+    this._primedDisplayState = true;
+    return list;
+  }
+
+  /** `requestRenderingMode()` — a pass-through; see the handle's doc comment for the contract. */
+  _requestRenderingMode(modeIndex, win) {
+    return this._layerCall(
+      this._liveWindow(win),
+      'requestRenderingMode',
+      'requestRenderingMode()',
+      [modeIndex]
+    );
+  }
+
+  // ── the eased 2D<->3D transition ──────────────────────────────────────────────────────
+  //
+  // Every PAGE-INITIATED mode request goes through here; a mode change reported from elsewhere
+  // does not (see _setStereoCollapsed). The asymmetry below is the whole helper, and it is the
+  // native `dxr::ModeSwitch` contract, unchanged:
+  //
+  //   -> 2D : ramp the disparity out FIRST, and fire the request only when it lands, so the panel
+  //           flips on already-flat content instead of snapping a stereo image flat.
+  //   -> 3D : fire the request FIRST and ease the disparity in afterwards — and in the browser,
+  //           only once the panel REPORTS 3D, because until then the disparity would be going up
+  //           on a flat panel, which is the double-image the whole mode API exists to prevent.
+  //
+  // Everything else is fall-through: the sequencer disabled, a browser with no `setViewRig` (there
+  // is nothing to ramp), an unknown target or current view count, a `viewCount > 2` mode the
+  // browser will refuse anyway, and a same-dimensionality change (2D->2D, 3D->3D) which needs no
+  // flatten at all.
+
+  /** True while a page-initiated transition is in flight in any of its phases. */
+  _msTransitionActive() {
+    return this._modeSwitch.active() || this._msArmedUp || this._msFire !== null;
+  }
+
+  /**
+   * `requestRenderingMode()` with the transition applied. Resolves when the request has actually
+   * been FORWARDED to the browser (so, for a ->2D switch, after the ramp) and rejects exactly as
+   * the pass-through does — plus one new failure: an `Error` named `superseded` when a second
+   * request replaced this one before it ever fired.
+   */
+  async _requestRenderingModeEased(modeIndex, win) {
+    if (!this._msEnabled || !hasViewRig()) return this._requestRenderingMode(modeIndex, win);
+    // The mode table is what says whether this index is 2D or 3D. It is normally already cached
+    // (the first activation primes it), and a read that fails just means the sequencer has no
+    // opinion — the request still goes out.
+    let modes = this._modes;
+    if (!Array.isArray(modes) || modes.length === 0) {
+      try {
+        modes = await this._getRenderingModes(win);
+      } catch {
+        modes = null;
+      }
+    }
+    const target = (Array.isArray(modes) ? modes : []).find((m) => m && m.modeIndex === modeIndex);
+    const targetViews = target && Number.isFinite(target.viewCount) ? target.viewCount : 0;
+    const currentViews = this._activeViewCount;
+    if (targetViews < 1 || targetViews > 2 || currentViews < 1) {
+      return this._requestRenderingMode(modeIndex, win);
+    }
+    if (targetViews === 1) {
+      if (currentViews === 1) return this._requestRenderingMode(modeIndex, win); // 2D -> 2D
+      return this._rampDownThenRequest(modeIndex, win);
+    }
+    return this._requestThenRampUp(modeIndex, win);
+  }
+
+  /**
+   * 3D -> 2D. Ramp the disparity to 0, THEN forward the request (see _advanceModeSwitch, which is
+   * what actually fires it). The returned promise is the page's, and it settles on the forwarded
+   * request — so `await wall.setStereoEnabled(false)` still means "the browser has it".
+   *
+   * A second ->2D request for the SAME mode mid-ramp is idempotent: the page gets the promise
+   * already in flight rather than a superseded rejection, because mashing one button twice is not
+   * an error. A different target retargets from the CURRENT disparity, seamlessly.
+   */
+  _rampDownThenRequest(modeIndex, win) {
+    if (this._msFire && this._msFire.modeIndex === modeIndex) return this._msFire.promise;
+    this._settlePendingDown('superseded', `a request for mode ${modeIndex} replaced it`);
+    const pending = { modeIndex, win, resolve: null, reject: null, promise: null };
+    pending.promise = new Promise((resolve, reject) => {
+      pending.resolve = resolve;
+      pending.reject = reject;
+    });
+    this._msFire = pending;
+    this._modeSwitch.request({
+      targetMode: modeIndex,
+      targetViewCount: 1,
+      currentMode: this._activeModeIndex,
+      currentViewCount: this._activeViewCount,
+      // The value ON SCREEN right now: the ramp's own output mid-flight, and the page's steady
+      // rig (factor 1) when idle. Passing the sequencer's internal 0 while idle is the classic
+      // first-press snap — there would be nothing to ramp down from.
+      current: this._stereoFactor,
+      steady: 1,
+    });
+    this._msLastMs = nowMs();
+    this._armModeSwitchTick();
+    return pending.promise;
+  }
+
+  /**
+   * -> 3D. Forward the request NOW (the browser needs the panel moving before the disparity can
+   * mean anything), then ease the disparity in — starting only when the panel REPORTS 3D, which
+   * is `_setStereoCollapsed(false)` releasing the latch.
+   *
+   * The one case that does not wait: a REVERSAL of a ramp-down that never fired. The panel never
+   * left 3D, so there is no report coming; the disparity just walks back up from wherever the
+   * ramp got to, and the stale 2D request is dropped rather than fired.
+   */
+  _requestThenRampUp(modeIndex, win) {
+    const reversal = this._msFire !== null;
+    const noopReversal = reversal && modeIndex === this._activeModeIndex;
+    this._settlePendingDown('superseded', `a request for mode ${modeIndex} reversed it`);
+    // A reversal back to the mode that is STILL active asks the browser for nothing: the runtime
+    // never changed mode, so the only thing owed is the disparity.
+    const forwarded = noopReversal
+      ? Promise.resolve(undefined)
+      : this._requestRenderingMode(modeIndex, win);
+    if (this._stereoFactor < 1) {
+      if (this._stereoCollapsed) {
+        // The panel is really flat: hold at 0 and wait for it to say otherwise.
+        this._msArmedUp = true;
+        this._modeSwitch.cancel();
+        this._stereoFactor = 0;
+      } else {
+        this._startUpRamp();
+      }
+    }
+    return forwarded.catch((err) => {
+      // Refused. Nothing about the panel moved, so neither may the disparity: drop the armed
+      // up-ramp and settle back on whatever the display last REPORTED.
+      if (this._msArmedUp) {
+        this._msArmedUp = false;
+        if (!this._modeSwitch.active()) this._stereoFactor = this._stereoCollapsed ? 0 : 1;
+      }
+      throw err;
+    });
+  }
+
+  /**
+   * Start (or restart) the up-ramp from the current disparity to the page's steady rig. Used both
+   * when the panel reports 3D after a `->3D` request and when a ->2D request was REFUSED — a
+   * refusal must leave the page in 3D, not flat.
+   *
+   * No request is ever fired from here: whatever there was to send went out before the ramp
+   * started, which is why `_msFire` is empty by construction.
+   */
+  _startUpRamp() {
+    this._settlePendingDown('superseded', 'the display returned to 3D');
+    this._modeSwitch.request({
+      targetMode: this._activeModeIndex,
+      targetViewCount: 2,
+      currentMode: this._activeModeIndex, // equal ⇒ the sequencer fires nothing
+      currentViewCount: 2,
+      current: this._stereoFactor,
+      steady: 1,
+    });
+    this._msLastMs = nowMs();
+    this._armModeSwitchTick();
+  }
+
+  /** Settle a held ->2D request that will now never fire. Never throws into the caller. */
+  _settlePendingDown(name, why) {
+    const pending = this._msFire;
+    if (!pending) return;
+    this._msFire = null;
+    const err = new Error(
+      `[inline3d] the request for rendering mode ${pending.modeIndex} was never forwarded: ${why}. ` +
+        'A ->2D switch is held until the disparity has ramped out, so a request that is reversed ' +
+        'or replaced in that window is dropped rather than fired late.'
+    );
+    err.name = name;
+    pending.reject(err);
+  }
+
+  /**
+   * Advance the transition by WALL-CLOCK dt and act on what it says. Called from the session's
+   * frame loop and from the fallback tick; both are safe because the ramp is time-based, so a
+   * double advance in one frame moves it by dt = 0.
+   *
+   * Rigs are pushed only when the factor actually MOVED — an idle manager must not re-push every
+   * frame, and a landed ramp pushes its last value once.
+   */
+  _advanceModeSwitch() {
+    if (!this._modeSwitch.active()) {
+      this._msLastMs = null;
+      this._disarmModeSwitchTick();
+      return;
+    }
+    const now = nowMs();
+    const dt = typeof this._msLastMs === 'number' ? Math.max(0, (now - this._msLastMs) / 1000) : 0;
+    this._msLastMs = now;
+    const out = this._modeSwitch.update(dt);
+    if (out.factor !== this._stereoFactor) {
+      this._stereoFactor = out.factor;
+      for (const win of this._windows.values()) this._pushViewRig(win);
+    }
+    if (out.fire && this._msFire) {
+      const pending = this._msFire;
+      this._msFire = null;
+      this._requestRenderingMode(pending.modeIndex, pending.win).then(
+        (v) => pending.resolve(v),
+        (err) => {
+          // The panel refused to go flat, so the page must not be left flat either — ease the
+          // disparity back to steady before handing the rejection on.
+          this._startUpRamp();
+          pending.reject(err);
+        }
+      );
+    }
+    if (!this._modeSwitch.active()) {
+      this._msLastMs = null;
+      this._disarmModeSwitchTick();
+    }
+  }
+
+  /**
+   * A timer that advances the ramp when SESSION FRAMES are not arriving. The frame loop is the
+   * normal driver, but a held ->2D request must not sit forever because every tile scrolled away,
+   * the tab went background, or the page simply has no live layer — the page awaited a promise
+   * and the browser is owed a request.
+   */
+  _armModeSwitchTick() {
+    if (this._msTick !== null || typeof setTimeout !== 'function') return;
+    this._msTick = setTimeout(() => {
+      this._msTick = null;
+      if (!this._running) return;
+      this._advanceModeSwitch();
+      if (this._modeSwitch.active()) this._armModeSwitchTick();
+    }, MODE_SWITCH_TICK_MS);
+  }
+
+  _disarmModeSwitchTick() {
+    if (this._msTick === null) return;
+    if (typeof clearTimeout === 'function') clearTimeout(this._msTick);
+    this._msTick = null;
+  }
+
+  /**
+   * The sugar behind `setStereoEnabled` — pick a mode by view count and request it. Nothing
+   * else: the rig follows the resulting `renderingmodechange` (eased, when a transition is
+   * configured), not this call.
+   */
+  async _setStereoEnabled(enabled, win) {
+    const want = enabled ? 2 : 1;
+    const modes = await this._getRenderingModes(win);
+    const list = Array.isArray(modes) ? modes : [];
+    const mode = list.find((m) => m.viewCount === want && m.isRequestable);
+    if (!mode) {
+      throw new Error(
+        `[inline3d] setStereoEnabled(${!!enabled}) found no requestable ${want}-view mode on ` +
+          `this display (${list.length} mode(s) listed). It is sugar over requestRenderingMode() ` +
+          'and cannot invent one — read getRenderingModes() and drive the list yourself.'
+      );
+    }
+    // Already there ⇒ the request would be a no-op... UNLESS a transition is in flight, in which
+    // case this is the user reversing the toggle and the disparity still has to walk back. Taking
+    // the early-out there would leave a page that pressed 2D then 3D stuck part-way flat.
+    if (mode.isActive && !this._msTransitionActive()) return !!enabled;
+    await this._requestRenderingModeEased(mode.modeIndex, win);
+    return !!enabled;
+  }
+
+  // ── display events ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Subscribe the manager ONCE to each session event and fan out from there. One subscription
+   * per document rather than one per caller, because the SDK has to act on these itself (the
+   * automatic rig collapse) whether or not the page is listening.
+   */
+  _bindDisplayEvents() {
+    const session = this.session;
+    if (!session || typeof session.addEventListener !== 'function') return;
+    if (!hasDisplayModes()) return;
+    session.addEventListener('renderingmodechange', (e) => {
+      this._onRenderingModeChange(e).catch(() => {});
+    });
+    session.addEventListener('hardwaredisplaystatechange', (e) => {
+      this._onHardwareDisplayStateChange(e).catch(() => {});
+    });
+  }
+
+  /**
+   * The hardware display state moved. The browser's event is payload-free (an XRSessionEvent),
+   * so the state is READ, not parsed: under the mode-only contract the page-facing active mode's
+   * `hardwareDisplay3D` IS the hardware state by construction (a 1-view mode is presented for
+   * exactly as long as the hardware is in the state it declares; a 2-view mode's default state
+   * is what the runtime restored). A payload, if a future browser adds one, wins over the read.
+   */
+  _onHardwareDisplayStateChange(e) {
+    const stated = eventHardwareState(e);
+    const detail = eventDetail(e);
+    const deliver = (state) => {
+      if (state) this._hardwareDisplayState = state;
+      this._emitDisplay({
+        type: 'hardwaredisplaystatechange',
+        state: state || this._hardwareDisplayState,
+        detail,
+      });
+    };
+    // A stated payload is delivered synchronously (a page can act in the same task); the
+    // browser's payload-free event is delivered once the table has been read below.
+    if (stated) deliver(stated);
+    // Re-read the table either way and adopt what it says the active mode is. This is what
+    // carries the 1-view -> 2-view RETURN: the browser presents a 1-view mode on top of the
+    // runtime's unchanged 2-view mode, so when the page asks for the 2-view mode back the
+    // runtime has no mode change to report and fires no renderingmodechange - only the
+    // hardware moves. Read here, that return still restores the rig, and in the right order
+    // (hardware back in 3D first, then the parallax comes back).
+    // _getRenderingModes adopts the active mode (and moves the rig) itself; remember what was
+    // active BEFORE the read so a change can still be told to the page afterwards.
+    const prevIndex = this._activeModeIndex;
+    const prevViews = this._activeViewCount;
+    return this._getRenderingModes(null)
+      .then((list) => {
+        const active = (Array.isArray(list) ? list : []).find((m) => m.isActive) || null;
+        if (active && (active.modeIndex !== prevIndex || active.viewCount !== prevViews)) {
+          this._emitDisplay({
+            type: 'renderingmodechange',
+            modeIndex: this._activeModeIndex,
+            viewCount: this._activeViewCount || null,
+            mode: active,
+            detail: null,
+          });
+        }
+        if (!stated) {
+          const read = active && typeof active.hardwareDisplay3D === 'boolean' ? (active.hardwareDisplay3D ? '3d' : '2d') : null;
+          deliver(read);
+        }
+      })
+      .catch(() => {
+        // no live layer / no API: the stated payload already went out; a payload-free event is
+        // still delivered with whatever was last known.
+        if (!stated) deliver(null);
+      });
+  }
+
+  /**
+   * A rendering mode went active. Two jobs, in this order: learn its VIEW COUNT (which is what
+   * the rig collapse turns on, and which only the mode list carries), then tell the page.
+   *
+   * The list is re-read rather than trusted from cache — it is the runtime's, and a mode can
+   * change under us — but the read is best-effort: with no live layer the index the event
+   * carried is all there is, and the event is still worth delivering.
+   */
+  async _onRenderingModeChange(e) {
+    const detail = eventDetail(e);
+    const evIndex = eventModeIndex(e);
+    let mode = null;
+    try {
+      const list = await this._getRenderingModes(null);
+      const arr = Array.isArray(list) ? list : [];
+      mode = (evIndex >= 0 ? arr.find((m) => m.modeIndex === evIndex) : null) || arr.find((m) => m.isActive) || null;
+    } catch {
+      /* no live layer / no API — fall through to what the event itself said */
+    }
+    if (mode) {
+      this._activeModeIndex = mode.modeIndex;
+      this._activeViewCount = mode.viewCount;
+    } else if (evIndex >= 0) {
+      this._activeModeIndex = evIndex;
+    }
+    // Only ever driven by a REPORTED view count. An unknown one (the read failed) leaves the rig
+    // exactly as it is — half-collapsing on a guess is worse than being one event late.
+    if (this._activeViewCount === 1 || this._activeViewCount === 2) {
+      this._setStereoCollapsed(this._activeViewCount === 1);
+    }
+    this._emitDisplay({
+      type: 'renderingmodechange',
+      modeIndex: this._activeModeIndex,
+      viewCount: this._activeViewCount || null,
+      mode,
+      detail,
+    });
+  }
+
+  /** Deliver one normalised display event to every listener. A throwing page handler is contained. */
+  _emitDisplay(ev) {
+    const set = this._displayListeners.get(ev.type);
+    if (!set) return;
+    for (const cb of [...set]) {
+      try {
+        cb(ev);
+      } catch (err) {
+        console.error(`[inline3d] ${ev.type} listener threw`, err);
+      }
+    }
+  }
+
+  /**
+   * Listen for `renderingmodechange` / `hardwaredisplaystatechange` on this manager. See the
+   * handle's `on()` doc for the payload shapes. Returns an unsubscribe function.
+   */
+  on(type, cb) {
+    if (typeof cb !== 'function') throw new TypeError('[inline3d] on() takes (type, function).');
+    if (!DISPLAY_EVENTS.includes(type)) {
+      throw new TypeError(
+        `[inline3d] on() knows ${DISPLAY_EVENTS.join(' / ')}, got ${JSON.stringify(type)}.`
+      );
+    }
+    let set = this._displayListeners.get(type);
+    if (!set) this._displayListeners.set(type, (set = new Set()));
+    set.add(cb);
+    return () => this.off(type, cb);
+  }
+
+  /** Drop a listener registered with {@link on}. */
+  off(type, cb) {
+    const set = this._displayListeners.get(type);
+    if (set) set.delete(cb);
+  }
+
+  /** Both display events through one callback — the older shape. Returns an unsubscribe. */
+  _onDisplayModeChange(cb) {
+    if (typeof cb !== 'function') {
+      throw new TypeError('[inline3d] onDisplayModeChange() takes a function.');
+    }
+    const offs = DISPLAY_EVENTS.map((type) => this.on(type, cb));
+    return () => {
+      for (const off of offs) off();
+    };
+  }
+
+  // ── undock ────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Re-read `layer.getUndockCapabilities()` into `wall.undock`.
+   *
+   * `undock` starts as `{model:false, splat:false}` on a browser that HAS the API, because the
+   * capabilities can only be read off a live layer and there is none at create time — false is
+   * the honest pre-read value ("not known to work"), and `null` is reserved for the thing a page
+   * actually branches on: no `XRDisplayLayer.undock` at all. Called automatically on the first
+   * layer activation; call it again whenever a page wants a fresh answer.
+   *
+   * @returns {Promise<{model:boolean, splat:boolean}|null>}
+   */
+  async refreshUndock() {
+    if (!hasUndock()) return (this.undock = null);
+    const win = this._liveWindow(null);
+    if (!win || !win.layer || typeof win.layer.getUndockCapabilities !== 'function') {
+      return this.undock;
+    }
+    try {
+      const caps = await win.layer.getUndockCapabilities();
+      this.undock = { model: !!(caps && caps.model), splat: !!(caps && caps.splat) };
+    } catch {
+      /* a refusal is not a capability change — keep the last answer */
+    }
+    return this.undock;
+  }
+
   _register(canvas, kind, opts) {
     if (this._windows.has(canvas)) this._remove(canvas);
     // Own compositing layer: makes the canvas a distinct quad the weave can track. Harmless
@@ -675,6 +1756,13 @@ class Inline3D {
       // and rebuilds layers behind the page's back: a tile that scrolls away and back would
       // otherwise silently revert to the default display rig mid-scene.
       viewRig: opts.viewRig || null,
+      // The automatic 1-view collapse (the latch itself is manager-wide — the mode is the
+      // display's, not this window's). `stereoSaved` records the factors in force when the panel
+      // went flat, for diagnostics; the restore just re-pushes `viewRig`, which the flattening
+      // never touched. `stereoSynthRig` records that this window's LAYER has been handed an
+      // explicit rig at least once, so coming back has to send the un-flat one explicitly.
+      stereoSaved: null,
+      stereoSynthRig: false,
       observeEl: opts.observe || canvas,
       ctx: kind === 'scene' ? null : canvas.getContext('2d'),
       repaint: () => this._paint(win, null),
@@ -742,17 +1830,42 @@ class Inline3D {
       // object, find no member it knows, and fall back to its own default height — so a page
       // that passed both (a camera rig plus the height an older browser should use) would get
       // neither. Gating here is what makes that fallback pair actually work.
-      const init =
-        win.viewRig && hasViewRig()
-          ? { viewRig: win.viewRig }
-          : win.virtualDisplayHeight > 0
-            ? { virtualDisplayHeight: win.virtualDisplayHeight }
-            : {};
+      //
+      // _effectiveViewRig, not win.viewRig: while setStereoEnabled(false) is latched the rig is
+      // the FLAT one, and a window with no rig of its own still gets one (the exact descriptor
+      // equivalent of its virtualDisplayHeight, with the factors zeroed) — otherwise a tile that
+      // scrolled away in 2D would rebuild itself in 3D behind the page's back.
+      const rig = hasViewRig() ? this._effectiveViewRig(win) : null;
+      const init = rig
+        ? { viewRig: rig }
+        : win.virtualDisplayHeight > 0
+          ? { virtualDisplayHeight: win.virtualDisplayHeight }
+          : {};
       win.layer = new XRDisplayLayer(this.session, win.canvas, init);
     } catch {
       win.layer = null;
       return;
     }
+    // Nothing about the hardware state is re-asserted here, and that is the point: the panel's
+    // mode is the DISPLAY's, it survives a tile scrolling away, and this SDK never requests it
+    // behind the page's back. The rig went into the init above already flattened if a 1-view
+    // mode is active (_effectiveViewRig), which is the only half a new layer has to be told.
+    //
+    // FIRST LAYER, FIRST READ. The display's capabilities can only be read off a live layer, so
+    // this is the earliest point the SDK can learn (a) which mode is active — a page can open
+    // with the panel already flat, and the rig has to be collapsed for that too — and (b) what
+    // this build can undock. Both best-effort and unawaited: they run inside the scroll-driven
+    // activation path and must never break it.
+    if (!this._primedDisplayState && hasDisplayModes()) {
+      this._primedDisplayState = true; // one attempt per manager, not one per activation
+      this._getRenderingModes(win).catch(() => {
+        this._primedDisplayState = false; // the read failed; let the next activation try again
+      });
+    }
+    if (hasUndock() && this.undock && !this._undockRead) {
+      this._undockRead = true;
+      this.refreshUndock().catch(() => {});
+    }
     // First real layer: if the occlusion capability is per-instance, this is the earliest point
     // it can be read (see sampleDrawOrderOcclusion) — and if it says the browser occludes by
     // draw order, retire whatever legacy machinery already started before we could know.
@@ -1145,6 +2258,10 @@ class Inline3D {
   _frame(t, f) {
     if (!this._running) return;
     this._requestFrame();
+    // The 2D<->3D ramp, on WALL-CLOCK dt (never a frame count, so it lasts the same wall time at
+    // 30 fps and 144 fps). Before the windows, so the rig this frame's views are located against
+    // is the ramped one. No-op — and pushes nothing — when no transition is in flight.
+    this._advanceModeSwitch();
     const pose = this.refSpace ? f.getViewerPose(this.refSpace) : null;
     const views = pose ? pose.views : null;
     for (const win of this._windows.values()) {
@@ -1293,6 +2410,12 @@ class Inline3D {
     if (liveManager === this) liveManager = null;
     this._unbindLifecycle();
     this._disarmDprWatch();
+    // A transition in flight dies with the session: nothing will drive the ramp, and the held
+    // request has nowhere to go — so the page's promise is settled rather than left pending.
+    this._disarmModeSwitchTick();
+    this._modeSwitch.cancel();
+    this._msArmedUp = false;
+    this._settlePendingDown('closed', 'the inline-3D session closed first');
     if (this._observer) this._observer.disconnect();
     for (const win of this._windows.values()) {
       this._stopOverlayScan(win);
@@ -1307,6 +2430,9 @@ class Inline3D {
       }
     }
     this._windows.clear();
+    // Page listeners go with the session that fed them: a manager whose session has ended will
+    // never emit again, and holding the callbacks would keep the page's closures alive.
+    this._displayListeners.clear();
   }
 }
 
@@ -1343,8 +2469,8 @@ function drawEye(ctx, src, sx, sy, sw, sh, dx, dy, dw, dh, radius, feather) {
 
 // Fade this EYE's outer edges to transparent, so the 3D window dissolves into the page
 // instead of ending at a hard rectangle. Same spirit as the runtime feathering a 3D zone's
-// edge — but note that is the hardware WISH MASK (lens control, never content); this is the
-// content-side equivalent, and the two are independent.
+// edge — but note that is the hardware WISH MASK (it drives the hardware display state, never
+// content); this is the content-side equivalent, and the two are independent.
 //
 // Per-eye, like cornerRadius, and for the same reason: the weave splits the element's rect
 // down the middle, so anything applied across the whole (side-by-side) buffer gets halved —