@displayxr/inline3d 1.2.1 → 1.4.0

package/js/inline3d.js

@@ -24,6 +24,14 @@
 // { 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 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 +39,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';
@@ -41,6 +69,76 @@ const hasLayer = () =>
 // no-op — the page still works, the overlay just weaves like before.
 const hasExclusion = () =>
   hasLayer() && 'excludeElement' in window.XRDisplayLayer.prototype;
+// View rigs (XR_DXR_view_rig, browser-side `XRDisplayLayer.setViewRig`). The browser has always
+// chained a rig descriptor onto its per-frame xrLocateViews — a DISPLAY rig with an identity
+// pose whose only knob was `virtualDisplayHeight`. setViewRig opens the whole descriptor: a
+// posed display rig, or a CAMERA rig that puts the app's own camera in the runtime's hands.
+//
+// The capability signal is the METHOD's presence, and that is deliberate: a Blink IDL attribute
+// getter throws `Illegal invocation` when read off the prototype (the trap documented at length
+// under occlusionByDrawOrder below), so an attribute would be undetectable on exactly the
+// browser that has it. `'setViewRig' in prototype` calls nothing and is safe.
+const hasViewRig = () => {
+  if (!hasLayer()) return false;
+  try {
+    return 'setViewRig' in window.XRDisplayLayer.prototype;
+  } catch {
+    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,
@@ -170,6 +268,158 @@ export function inline3dOcclusionByDrawOrder() {
   return hasDrawOrderOcclusion();
 }
 
+/**
+ * True when this browser accepts a full VIEW RIG descriptor — `handle.setViewRig(rig)` and
+ * `addScene`'s `viewRig` option, i.e. a posed display rig or a camera rig, instead of only the
+ * scalar `virtualDisplayHeight`. Sync + cheap; implies {@link inline3DAvailable}.
+ *
+ * Reads a capability (the presence of `XRDisplayLayer.prototype.setViewRig`), never a version or
+ * UA string. False on every browser that predates the rig API — where `virtualDisplayHeight`
+ * still works, which is why a page needs to branch on this only if a camera rig is load-bearing
+ * for it: `setViewRig` no-ops loudly-once rather than throwing, so a page that just wants the
+ * extra control when it is there can call it unconditionally.
+ */
+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 out: eye separation and head-tracking response to 0, so
+// both eyes are rendered from the SAME place and the woven atlas carries one image twice.
+//
+// A COPY, never a mutation. A page driving a rig per frame reuses one descriptor object
+// (cameraRigFromCamera's `out`), so zeroing 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.
+function flattenedRig(rig) {
+  return { ...rig, ipdFactor: 0, parallaxFactor: 0 };
+}
+
+// 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;
+function noteNoViewRig() {
+  if (notedNoViewRig) return;
+  notedNoViewRig = true;
+  console.warn(
+    '[inline3d] This browser has no XRDisplayLayer.setViewRig, so the view rig was ignored ' +
+      '(the window still weaves — the runtime keeps the default display rig, scaled by ' +
+      "virtualDisplayHeight). Gate on inline3dViewRigSupported() if your page's framing " +
+      'depends on the rig; further calls are silent.'
+  );
+}
+
+let notedRigWinsOverHeight = false;
+function noteRigWinsOverHeight() {
+  if (notedRigWinsOverHeight) return;
+  notedRigWinsOverHeight = true;
+  console.warn(
+    '[inline3d] addScene got BOTH viewRig and virtualDisplayHeight; on a browser with rig ' +
+      'support the rig wins and the height is dropped. They describe the same slot — ' +
+      'virtualDisplayHeight is shorthand for exactly one rig (display, identity pose, all ' +
+      'factors 1) — so there is no merge. This is only worth passing as a PAIR deliberately: ' +
+      'the height is what a browser without setViewRig will use, so a camera-rig scene can ' +
+      'name its own fallback framing. Otherwise say it once, inside the rig.'
+  );
+}
+
 /**
  * Open the page's inline-3D session and return a manager you add windows to.
  *
@@ -189,7 +439,10 @@ export function inline3dOcclusionByDrawOrder() {
  *        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}>}
+ * @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;
@@ -286,6 +539,24 @@ 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;
+    // 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 =
@@ -310,6 +581,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();
@@ -491,10 +763,21 @@ class Inline3D {
    * @param {object} [opts]
    * @param {number} [opts.virtualDisplayHeight=0.24]  metres of virtual display the scene is
    *        composed for. Larger = the element shows a bigger slice of the world.
+   * @param {object} [opts.viewRig]  a full view-rig descriptor (XRViewRigInit) instead of the
+   *        scalar height: a POSED display rig, or a CAMERA rig that hands the runtime your app
+   *        camera's pose/FOV/convergence and lets eye tracking perturb its frustum. Supersedes
+   *        virtualDisplayHeight (which is one particular display rig), and can be replaced per
+   *        frame with `handle.setViewRig()`. Ignored on a browser without rig support, which
+   *        falls back to `virtualDisplayHeight` if one was given (that pair is the one reason
+   *        to pass both) — either way the window still weaves.
    * @param {Element} [opts.observe=canvas]  element whose visibility gates lazy create/close.
    * @returns {{remove():void}}
    */
   addScene(canvas, onFrame, opts = {}) {
+    // The rig and the height describe the same one slot in the layer init, so warn where a
+    // caller has said it twice — silently dropping one of two things the page explicitly asked
+    // for is how a scene ends up framed at a scale nobody chose.
+    if (opts.viewRig && opts.virtualDisplayHeight !== undefined) noteRigWinsOverHeight();
     const win = this._register(canvas, 'scene', { virtualDisplayHeight: 0.24, ...opts });
     win.onFrame = onFrame;
     win.ownsBuffer = false; // the app sizes a scene canvas; we never touch canvas.width/height
@@ -528,12 +811,189 @@ class Inline3D {
         if (!el || !win.excluded.delete(el)) return;
         this._dropExclusion(win, el);
       },
+      /**
+       * Replace this window's VIEW RIG — the descriptor the runtime locates views against.
+       * Cheap enough to call every frame (that is the intended use: a rig is per-locate, so
+       * animating one means sending new values, not tweening anything).
+       *
+       * Remembered on the window as well as pushed at the layer, so the lazy lifecycle cannot
+       * quietly lose it (see `viewRig` in _register). Returns whether it reached a LIVE layer:
+       * false also means "stored, and it will build the next layer" for a window that is
+       * currently scrolled away — which is the honest answer for a page driving this per frame,
+       * and the reason it is a boolean rather than void.
+       *
+       * ONE FRAME OF LAG, by construction. The browser locates views BEFORE the page's rAF, so
+       * the rig you set during frame N drives the views delivered in frame N+1. For a slow
+       * knob (a slider, a settled camera) that is invisible; for a camera that moves with the
+       * 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.
+       */
+      setViewRig: (rig) => {
+        win.viewRig = rig || null;
+        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.
+       *
+       * @param {number} modeIndex
+       * @returns {Promise<void>}
+       */
+      requestRenderingMode: (modeIndex) => this._requestRenderingMode(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.
+       *
+       * @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._requestRenderingMode(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;
+  }
+
   close() {
     try {
       this.session.end();
@@ -545,6 +1005,371 @@ class Inline3D {
 
   // ── internals ───────────────────────────────────────────────────────────────────────
 
+  // ── view rig + display modes ──────────────────────────────────────────────────────────
+
+  /**
+   * The rig this window's layer should actually be holding right now: what the page asked for,
+   * flattened when `setStereoEnabled(false)` is latched. 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._stereoCollapsed) {
+      // `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 flattenedRig(win.viewRig || defaultDisplayRig(win));
+  }
+
+  /**
+   * 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.
+   */
+  _setStereoCollapsed(collapsed) {
+    const next = !!collapsed;
+    if (this._stereoCollapsed === next) return;
+    this._stereoCollapsed = next;
+    if (next) noteAutoCollapse();
+    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 sugar behind `setStereoEnabled` — pick a mode by view count and request it. Nothing
+   * else: the rig follows the resulting `renderingmodechange`, 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.'
+      );
+    }
+    if (mode.isActive) return !!enabled; // already there; the request would be a no-op anyway
+    await this._requestRenderingMode(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
@@ -565,6 +1390,18 @@ class Inline3D {
       reqW: opts.width || 0,
       reqH: opts.height || 0,
       virtualDisplayHeight: opts.virtualDisplayHeight || 0,
+      // The rig this window's NEXT layer is built with. Latest wins, and it is kept on the
+      // window rather than only pushed at the live layer because the lazy lifecycle destroys
+      // 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),
@@ -621,15 +1458,53 @@ class Inline3D {
     // layers churn with scroll, so activations double as cheap rescan points.
     this._scanChrome();
     try {
-      // virtualDisplayHeight (display-rig m2v) tells the runtime what scale this
-      // window's scene is authored at, so it returns render-ready scaled views.
-      const init =
-        win.virtualDisplayHeight > 0 ? { virtualDisplayHeight: win.virtualDisplayHeight } : {};
+      // What scale/pose the runtime should report views at. virtualDisplayHeight (display-rig
+      // m2v) is the scalar shorthand; a viewRig is the whole descriptor and therefore replaces
+      // it rather than combining with it. Building the layer WITH the rig (instead of
+      // constructing then calling setViewRig) matters for a re-activated window: the layer's
+      // very first located frame is already on the page's rig, so a tile scrolling back into
+      // view never shows one frame of default framing.
+      //
+      // The rig is only offered to a browser that HAS rigs. An older one would take the init
+      // 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.
+      //
+      // _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.
@@ -1184,6 +2059,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();
   }
 }
 
@@ -1220,8 +2098,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 —