@displayxr/inline3d 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,68 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.6.0 — 2026-09-08
+
+Touches the **preview tier** (`./viewer`) and fixes a **documentation error in the core tier**.
+Purely additive to the viewer's API: no framing behaviour changes and no existing option changes
+meaning, so a page that ignores everything below renders identically to 1.5.1.
+
+### Added
+
+- **`SceneViewer` has an output surface** ([#26](https://github.com/DisplayXR/displayxr-web/issues/26)).
+  It could frame, scale and orbit a subject but never say where the subject ended up, so pages
+  that needed that — a pop-out readout, a depth-budget check, a HUD that must clear the model —
+  had to read `_pivot`, `_fitScale` and `_zoom`. Three additions replace all of it:
+  - **`getSubjectBounds()`** → `{center, extent, front, back, scale}` in **display metres**, for
+    the pose being drawn. `front` is the surface nearest the viewer (`> 0` = out of the glass),
+    `back` the far side, `scale` the model-unit → metre factor in force (fit × zoom).
+    **Call it per frame.** The orbit rotates the *subject*, so yaw swings its depth into the
+    display's `z`: a page-shaped subject 1 m × 0.02 m is 0.01 m deep face-on and 0.5 m deep
+    turned side-on. Anything measured once at load is correct at yaw 0 and wrong everywhere
+    else — and with `idleSpin` on, yaw 0 is a passing instant. The call allocates one object and
+    does no matrix work.
+  - **`depthOffset`** (get/set) — slides the subject along the depth axis in display metres,
+    `+` toward the viewer. It **translates and never rescales**, so it moves the depth budget
+    without resizing it.
+  - **`getPose({target})`** — the counterpart to `setPose`. Yaw/pitch/zoom are eased, so
+    mid-gesture "what is drawn" and "what it is settling toward" genuinely differ; the default
+    reports the drawn value, `target: true` the destination.
+  - `setPose()` now also accepts `depthOffset`.
+
+### Changed
+
+- **`fitTo()` no longer discards `depthOffset`.** It used to hardcode the pivot's z to 0, so
+  reframing a subject silently threw away where the author had placed it. `resetPose()` clears
+  it, which is where "back to default" belongs. **No effect on any 1.5.x page**: the offset is 0
+  unless something sets it, and 0 is what `fitTo` used to write.
+- `samples/model` reads `getSubjectBounds()` instead of `_fitScale`, and prints its footprint and
+  pop-out **live** — the visible disagreement between that and the static fit numbers is the
+  point, and is why the call is per-frame.
+
+### Fixed
+
+- **The depth axis was documented BACKWARDS.** `docs/authoring-inline-3d.md` and the header of
+  `inline3d-three.js` both said "`+z` behind the glass, `−z` in front". It is the other way
+  round: the runtime places the nominal viewer at `z = +0.6 m` with the glass at `z = 0`
+  (`dxr_view_math`'s `nomv`), so **`+z` is toward the viewer, out of the glass**. Every mono
+  fallback camera in this repo already sat at `+z` for that reason, so only the prose was wrong —
+  but the prose is what authors code against, and the symptom is a depth control whose labels are
+  inverted. Symmetric subjects hide it completely. New section:
+  [Which way is out](docs/authoring-inline-3d.md#which-way-is-out).
+
+## 1.5.1 — 2026-09-06
+
+### Fixed
+
+- **Undock: `ended` now means the viewer exited.** The browser contract (browser-pvt#25) resolves
+  `layer.undock()` on a successful LAUNCH and reports the viewer's exit separately as the XRSession's
+  `undockend` event; 1.4.0/1.5.0 derived `ended` from the launch promise, so it resolved a frame after
+  the window opened. The helper now arms an `undockend` listener before launching and resolves
+  `ended` on it; the browser's DOMException names (NotAllowedError, NotSupportedError,
+  SecurityError, InvalidStateError, OperationError) map onto the four contract names. The
+  fallback path is unchanged (`detached === true`, `ended` immediate).
+- README: vendoring note — `inline3d-mode-switch.js` is a static dependency of `inline3d.js`.
+
 ## 1.5.0 — 2026-09-06
 
 ### Added

package/README.md

@@ -65,8 +65,14 @@ if (!wall.supported) {
 The browser weaves each element's stereo pair at its on-screen rect; the surrounding DOM stays flat.
 The runtime batches every visible window into one weave per frame, so it scales to a wall of elements.
 
-A scene with its own camera can hand that camera to the runtime instead of being told where the eyes
-are — a **camera rig** — and let eye tracking perturb its frustum:
+Most pages want the default — a **display rig**, where the canvas is a portal onto a virtual
+display and the runtime places the eyes. That includes every scene that frames a *subject* (a model
+or splat viewer, an avatar, a product hero) **even when the user orbits it**: rotate the subject,
+not the camera, and the stereo comes out the same for a figurine and an airliner.
+
+A scene whose viewpoint the user *moves through a world* — first person, a walkthrough, a game, a
+map, an editor, a ported VR app — can instead hand its own camera to the runtime and let eye
+tracking perturb that frustum. That is a **camera rig**:
 
 ```js
 import { cameraRigFromCamera } from '@displayxr/inline3d/three';
@@ -104,7 +110,8 @@ js/
   inline3d.js         the SDK: createInline3D() → { addImage, addVideo, addScene }, feature-detect,
                       SBS buffer management, and a lazy create/close lifecycle for many windows
   inline3d-three.js   optional three.js helper (EyeCamera: off-axis projection from the session's eyes)
-  inline3d-viewer.js  experimental: SceneViewer — framing, orbit, idle turntable, mono fallback
+  inline3d-viewer.js  experimental: SceneViewer — framing, orbit, idle turntable, mono fallback,
+                      and the placement readback (getSubjectBounds / getPose / depthOffset)
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
   inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
                       from what the asset declares (you serve the decoder files — see the guide)

package/js/inline3d-three.js

@@ -41,8 +41,8 @@
 // are already scaled to your scene by the layer's `virtualDisplayHeight` (see addScene) — the
 // runtime places each eye at eye_physical × (virtualDisplayHeight / element_physical_height),
 // so the z=0 plane spans that virtual display. Author your scene in metres for a display that
-// tall (0.24 m by default), put focused content at z=0 (positive z behind the glass, negative
-// in front), and render `eye.camera` directly. No per-frame world scaling — that is the whole
+// tall (0.24 m by default), put focused content at z=0 (POSITIVE z is toward the viewer, out
+// of the glass; negative z is behind it), and render `eye.camera` directly. No per-frame world scaling — that is the whole
 // point of using the rig instead of re-deriving it in the app, and it mirrors the native
 // reference apps (cube_handle), which supply one scale number and consume render-ready views.
 //
@@ -167,10 +167,18 @@ function scratch(THREE) {
  * anything here: this function only fills in a descriptor, and every off-axis projection stays
  * in the runtime, where it is the same code the native apps use.
  *
+ * WHICH RIG. Decide by what the USER moves, not by whether you hold a camera. If the user turns
+ * a SUBJECT — a model, a splat, an avatar, a product hero, and yes, an orbit around one — use a
+ * display rig and rotate the subject under a fixed portal: a display rig is scale-invariant, so a
+ * figurine and an airframe get the same stereo. A camera rig is literal (two eyes 63 mm apart at
+ * your camera), so its disparity falls off as baseline / framing distance and a big subject framed
+ * from far away renders FLAT. Use a camera rig for a viewpoint the user moves through a world:
+ * first person, a walkthrough, a game, a map, an editor, a ported VR app.
+ *
  * CONVERGENCE IS THE ONE KNOB TO GET RIGHT. It is the distance at which content sits ON the
  * glass; everything nearer pops out, everything further recedes. Point it at whatever the viewer
- * is meant to be looking at (an orbit target, a hit-tested surface) — for an orbiting camera
- * that is usually just the orbit radius. Left at 0 it means infinity, which puts the entire
+ * is meant to be looking at (the subject's centre, a hit-tested surface) — with a moving camera
+ * that is usually just the distance to it. Left at 0 it means infinity, which puts the entire
  * scene in front of the display and is comfortable for almost nothing.
  *
  * COMFORT. The runtime's rule is `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1`
@@ -180,6 +188,16 @@ function scratch(THREE) {
  * runtime clamps out-of-range values itself, once, with a warning — but a scene authored in
  * centimetres with a 0.1-unit convergence is the shape of the mistake.
  *
+ * COMFORT IS NOT A DEPTH METER. It bounds where the depth budget SITS (it guards the background
+ * against divergence), not how big the budget is. The budget is
+ * `(baseline / tan(vFov/2)) * (1/z_near - 1/z_far)`, which convergence cancels out of exactly —
+ * convergence slides the scene relative to the glass and never resizes its depth, which is why
+ * ipdFactor/parallaxFactor here are ABSOLUTE rather than scaled by the convergence distance. A
+ * window that weaves but looks FLAT is a budget problem (a 63 mm baseline framing a large subject
+ * from far away) and comfort will report a healthy number while it happens. Do not rescale the
+ * baseline to paper over it: a camera rig needing a scale correction is a scene that wanted a
+ * display rig.
+ *
  * @param {object} THREE  your imported three.js module namespace.
  * @param {object} camera  a THREE.PerspectiveCamera (`.fov` in degrees, `.matrixWorld` current).
  * @param {object} [opts]

package/js/inline3d-undock.js

@@ -135,9 +135,19 @@ function launchProtocol(url) {
 
 const UNDOCK_ERRORS = ['not-installed', 'src-not-allowed', 'no-activation', 'busy'];
 
+// The browser refuses with DOMException names (patch 0130); each maps onto one contract name.
+const DOM_ERROR_NAMES = {
+  NotAllowedError: 'no-activation', // no transient user activation
+  NotSupportedError: 'not-installed', // no registered viewer for this type
+  SecurityError: 'src-not-allowed', // src outside the allowlist
+  InvalidStateError: 'busy', // an undock is already live in this frame
+  OperationError: 'not-installed', // the viewer failed to launch
+};
+
 /** Give a rejection one of the four contract names, keeping the browser's own where it has one. */
 function undockError(e, fallbackName, message) {
-  const name = e && UNDOCK_ERRORS.includes(e.name) ? e.name : fallbackName;
+  const name =
+    e && UNDOCK_ERRORS.includes(e.name) ? e.name : (e && DOM_ERROR_NAMES[e.name]) || fallbackName;
   const err = new Error(message || (e && e.message) || `[inline3d] undock failed (${name}).`);
   err.name = name;
   if (e) err.cause = e;
@@ -166,8 +176,10 @@ let inFlight = false;
  * @param {number} [opts.margin]  the page's fit margin, when it overrides the default.
  * @param {string} [opts.title]
  * @returns {Promise<{ended:Promise<void>, viewer:UndockType, detached?:boolean}>}
- *   `ended` resolves when the viewer exits (fallback path: immediately, with
- *   `detached === true` — a protocol launch is fire-and-forget and the page never hears back).
+ *   Resolves once the viewer has LAUNCHED (API path: `layer.undock()` resolved, i.e. the viewer
+ *   process was spawned; it never waits for the viewer). `ended` resolves when the viewer exits -
+ *   the API path hears that as the XRSession's `undockend` event; the fallback path never hears
+ *   back, so there `ended` resolves immediately and `detached === true`.
  *   Rejects with an Error named `not-installed` | `src-not-allowed` | `no-activation` | `busy`.
  */
 export function undock(target, opts) {
@@ -184,7 +196,11 @@ export function undock(target, opts) {
   }
   if (inFlight) return Promise.reject(undockError(null, 'busy', '[inline3d] an undock is already in flight.'));
 
-  const layer = layerResolver ? layerResolver(target) : null;
+  // The resolver hands back `{layer, session}` (the session carries the `undockend` event); a bare
+  // layer is accepted too, in which case the viewer's exit is simply not observable.
+  const found = layerResolver ? layerResolver(target) : null;
+  const layer = found && typeof found === 'object' && 'layer' in found ? found.layer : found;
+  const session = found && typeof found === 'object' && 'session' in found ? found.session : null;
   const viewer = opts.type;
 
   // ── fallback: the OS protocol ──────────────────────────────────────────────────────────
@@ -211,41 +227,53 @@ export function undock(target, opts) {
   if (opts.margin !== undefined) init.margin = opts.margin;
   if (opts.title) init.title = opts.title;
 
+  // THE BROWSER CONTRACT (browser-pvt#25 / patch 0130): `layer.undock(init)` RESOLVES ON A
+  // SUCCESSFUL LAUNCH - as soon as the viewer process is spawned - and never waits for it; every
+  // refusal is a prompt rejection (NotAllowedError / NotSupportedError / SecurityError /
+  // InvalidStateError / OperationError). The viewer's exit arrives separately, as the `undockend`
+  // event on the XRSession. One live undock per frame, so the NEXT `undockend` after a
+  // successful launch is this one's - no correlation id needed. The listener is armed BEFORE the
+  // launch so a viewer that exits immediately cannot slip between the two.
+  let endedResolve = null;
+  const ended = new Promise((resolve) => {
+    if (!session || typeof session.addEventListener !== 'function') {
+      // No session to listen on: the launch still works, the exit is simply not observable -
+      // so `ended` resolves at launch (as the fallback path does) rather than holding the
+      // one-live-undock guard for ever.
+      endedResolve = resolve;
+      resolve();
+      return;
+    }
+    const onEnd = () => {
+      session.removeEventListener('undockend', onEnd);
+      resolve();
+    };
+    session.addEventListener('undockend', onEnd);
+    endedResolve = () => {
+      session.removeEventListener('undockend', onEnd);
+      resolve();
+    };
+  });
+
   let call;
   try {
     call = Promise.resolve(layer.undock(init));
   } catch (e) {
     // A synchronous throw is the same failure as a rejection; one .catch() should cover both.
+    if (endedResolve) endedResolve();
     return Promise.reject(undockError(e, 'src-not-allowed'));
   }
   inFlight = true;
-  const settled = call.finally(() => {
+  ended.then(() => {
     inFlight = false;
   });
-
-  // TWO PROMISE SHAPES, ONE ANSWER. `undock()` either rejects PROMPTLY — every refusal
-  // (not-installed / src-not-allowed / no-activation / busy) is decided before any window
-  // exists — or it stays pending until the viewer exits. A short race tells them apart without
-  // inventing an event: whatever has not rejected by then launched. The launch has already
-  // happened synchronously above, so this wait costs the user nothing.
-  const LAUNCH_MS = 150;
-  const launchProbe = settled.then(
-    () => 'launched',
+  return call.then(
+    () => ({ ended, viewer, detached: false }),
     (e) => {
+      // Refused before any window existed: nothing is in flight and nothing will end.
+      inFlight = false;
+      if (endedResolve) endedResolve();
       throw undockError(e, 'not-installed');
     }
   );
-  // The probe LOSES the race whenever the viewer stays open, and a rejection arriving after that
-  // would otherwise be an unhandled one. Marked handled here; the same rejection still reaches
-  // the caller through `ended`, which is where a late failure belongs.
-  launchProbe.catch(() => {});
-  return Promise.race([
-    launchProbe,
-    new Promise((resolve) => window.setTimeout(() => resolve('launched'), LAUNCH_MS)),
-  ]).then(() => ({
-    // A rejection AFTER the launch window is the viewer failing later, and it belongs on `ended`.
-    ended: settled.then(() => undefined),
-    viewer,
-    detached: false,
-  }));
 }

package/js/inline3d-viewer.js

@@ -49,6 +49,9 @@ const DEFAULT_DEPTH_LIMIT = 4.0;
 const IDLE_DELAY_MS = 2500;
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+// NaN/Infinity into a transform silently blanks the tile — three propagates it into the
+// matrix and every vertex lands undefined. Reject at the setter instead.
+const finite = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
 
 /**
  * Robust model-space bounds from a flat array of splat/vertex centres.
@@ -220,6 +223,14 @@ export class SceneViewer {
     this._fitScale = 1;
     this._zoom = 1;
     this._targetZoom = 1;
+    // Author-driven slide along the depth axis, display metres, +z toward the viewer. Applied
+    // by _applyTransform, PRESERVED by fitTo, cleared by resetPose. Default 0 means every page
+    // that never touches it is bit-identical to 1.5.x.
+    this._depthOffset = 0;
+    // Subject half-extents in MODEL units, from the last fitTo. getSubjectBounds turns these
+    // into a display-space box under the live pose; without them it would have to re-measure
+    // the content every call.
+    this._subjectHalf = [0, 0, 0];
     this._yaw = 0;
     this._pitch = 0;
     this._targetYaw = 0;
@@ -278,10 +289,12 @@ export class SceneViewer {
     const e = Array.isArray(extent) ? extent : [extent.x, extent.y, extent.z];
 
     this._centering.position.set(-c[0], -c[1], -c[2]);
+    // Recorded for getSubjectBounds(). Model units; the fit scale is applied at read time so a
+    // later zoom or orbit needs no re-measure.
+    this._subjectHalf = [Math.abs(e[0]) / 2, Math.abs(e[1]) / 2, Math.abs(e[2]) / 2];
 
     if (this.fit === 'none') {
       this._fitScale = 1;
-      this._pivot.position.z = 0;
     } else {
       const box = this.canvas.getBoundingClientRect();
       const aspect = box.height > 0 ? box.width / box.height : 1;
@@ -325,8 +338,9 @@ export class SceneViewer {
       //
       // A biased variant that slid the subject behind the glass was tried and dropped: on
       // hardware it read WORSE, and it moved content the wrong way besides. Do not re-add it
-      // without a hardware comparison.
-      this._pivot.position.z = 0;
+      // without a hardware comparison. `depthOffset` is NOT that variant: it is an author
+      // asking for a specific placement, and it stays 0 unless someone sets it — so the
+      // default framing this comment defends is unchanged.
 
       // Backstop only: something pathologically deep still gets scaled down.
       const sz = (this.depthLimit * vH) / ez;
@@ -341,19 +355,115 @@ export class SceneViewer {
     this.monoCamera.lookAt(0, 0, 0);
   }
 
-  /** Set the orbit pose directly. Angles in degrees; zoom is a multiplier on the fit scale. */
-  setPose({ yaw, pitch, zoom } = {}) {
+  /**
+   * Set the pose directly. Angles in degrees; zoom is a multiplier on the fit scale;
+   * depthOffset is display metres along the depth axis (+ toward the viewer).
+   *
+   * This SNAPS — it writes the eased value and its target together. The easing in _tick exists
+   * for input, not for programmatic placement.
+   */
+  setPose({ yaw, pitch, zoom, depthOffset } = {}) {
     if (yaw !== undefined) this._targetYaw = this._yaw = yaw;
     if (pitch !== undefined) {
       this._targetPitch = this._pitch = clamp(pitch, this.pitchLimit[0], this.pitchLimit[1]);
     }
     if (zoom !== undefined) this._targetZoom = this._zoom = clamp(zoom, ZOOM_MIN, ZOOM_MAX);
+    if (depthOffset !== undefined) this._depthOffset = finite(depthOffset, this._depthOffset);
+    this._applyTransform();
+  }
+
+  /**
+   * What the pose IS right now — the counterpart to setPose, and the reason an app no longer
+   * has to read `_zoom` to know where its subject sits.
+   *
+   * `_tick` eases yaw/pitch/zoom toward their targets, so during an orbit or a wheel-zoom the
+   * two answers genuinely differ and consumers want different ones: a readout that describes
+   * what is ON SCREEN wants the eased value (the default), while "remember this view" wants
+   * the target it is settling on. depthOffset never eases, so both agree.
+   *
+   * @param {object} [opts]
+   * @param {boolean} [opts.target=false]  report the values being eased TOWARD.
+   * @returns {{yaw:number, pitch:number, zoom:number, depthOffset:number}} degrees / multiplier
+   *          / metres.
+   */
+  getPose({ target = false } = {}) {
+    return {
+      yaw: target ? this._targetYaw : this._yaw,
+      pitch: target ? this._targetPitch : this._pitch,
+      zoom: target ? this._targetZoom : this._zoom,
+      depthOffset: this._depthOffset,
+    };
+  }
+
+  /**
+   * Where the subject actually IS, in display metres, under the pose being drawn.
+   *
+   * This is the viewer's output surface. Everything a page needs in order to reason about
+   * depth — a pop-out readout, a depth-budget check, a HUD that must clear the subject — is a
+   * function of this box, and none of it is derivable from the outside: the fit scale, the
+   * live zoom and the orbit are all viewer state.
+   *
+   * THE ORBIT IS WHY THIS CANNOT BE CACHED. The pivot rotates about Y (and X), so yaw swings
+   * the subject's DEPTH into the display's z and its width out of it. A page that measures its
+   * model once at load and scales by zoom is correct at yaw 0 and wrong everywhere else — and
+   * with `idleSpin` on, yaw 0 is a passing instant. Call this per frame; it allocates one
+   * object and does no matrix work.
+   *
+   * SIGNS. Display space puts the viewer at +z and the glass at z = 0, so `front` (the surface
+   * nearest the viewer) is the LARGER z and a positive `front` means the subject pops out of
+   * the glass. `back` is the far side; a negative `back` is depth behind the glass. See
+   * docs/authoring-inline-3d.md § "Which way is out".
+   *
+   * The box is axis-aligned in display space and encloses the oriented subject — the standard
+   * conservative bound, so it never under-reports pop-out.
+   *
+   * @returns {{center:{x:number,y:number,z:number}, extent:{x:number,y:number,z:number},
+   *           front:number, back:number, scale:number}} metres, except `scale` which is the
+   *          model-unit → metre factor currently in force (fit x zoom).
+   */
+  getSubjectBounds() {
+    const s = this._fitScale * this._zoom;
+    const [hx, hy, hz] = this._subjectHalf;
+    const p = (this._pitch * Math.PI) / 180;
+    const y = (this._yaw * Math.PI) / 180;
+    // Rows of R = Rx(pitch) . Ry(yaw) — the same product _applyTransform builds, and the same
+    // order, which is the part that matters (see its comment on why 'XYZ' and not 'YXZ').
+    // |row| . half gives the AABB half-extent along that world axis.
+    const cp = Math.cos(p);
+    const sp = Math.sin(p);
+    const cy = Math.cos(y);
+    const sy = Math.sin(y);
+    const ex = s * (Math.abs(cy) * hx + Math.abs(sy) * hz);
+    const ey = s * (Math.abs(sp * sy) * hx + Math.abs(cp) * hy + Math.abs(sp * cy) * hz);
+    const ez = s * (Math.abs(cp * sy) * hx + Math.abs(sp) * hy + Math.abs(cp * cy) * hz);
+    const cz = this._depthOffset;
+    return {
+      center: { x: 0, y: 0, z: cz },
+      extent: { x: 2 * ex, y: 2 * ey, z: 2 * ez },
+      front: cz + ez,
+      back: cz - ez,
+      scale: s,
+    };
+  }
+
+  /**
+   * Slide the whole subject along the depth axis, display metres, + toward the viewer.
+   *
+   * Survives `fitTo` — a refit reframes the subject without discarding where the author put
+   * it — and is cleared by `resetPose`, which is where "back to default" belongs.
+   */
+  get depthOffset() {
+    return this._depthOffset;
+  }
+
+  set depthOffset(m) {
+    this._depthOffset = finite(m, this._depthOffset);
     this._applyTransform();
   }
 
-  /** Return to the framed default pose. */
+  /** Return to the framed default pose, depth slide included. */
   resetPose() {
-    this.setPose({ yaw: 0, pitch: 0, zoom: 1 });
+    this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
     this._lastInput = now();
   }
 
@@ -625,6 +735,10 @@ export class SceneViewer {
   _applyTransform() {
     const s = this._fitScale * this._zoom;
     this._pivot.scale.setScalar(s);
+    // The depth slide lives here, not in fitTo, so it survives a refit and cannot be left
+    // stale by a code path that forgets it. x/y are never written: the fit centres the subject
+    // on the tile and sliding it sideways is a scene concern, not a viewer one.
+    this._pivot.position.z = this._depthOffset;
     // Order 'XYZ' == R = Rx(pitch) · Ry(yaw), and the order is the whole point.
     //
     // Yaw must act in the subject's OWN frame (spin it on its axis); pitch must act in the

package/js/inline3d.js

@@ -59,13 +59,15 @@ setUndockLayerResolver((el) => {
   // 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;
+  // The session rides along: the viewer's exit is the XRSession's `undockend` event.
+  const hit = (win) => ({ layer: win.layer, session: m.session });
+  for (const win of m._windows.values()) if (win.canvas === el && win.layer) return hit(win);
   for (const win of m._windows.values()) {
-    if (win.layer && typeof el.contains === 'function' && el.contains(win.canvas)) return win.layer;
+    if (win.layer && typeof el.contains === 'function' && el.contains(win.canvas)) return hit(win);
   }
   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;
+    if (win.layer && box && typeof box.contains === 'function' && box.contains(el)) return hit(win);
   }
   return null;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",

package/viewer.d.ts

@@ -38,9 +38,35 @@ export interface SceneViewerOptions {
 }
 
 export interface OrbitPose {
+  /** Degrees about Y. */
   yaw?: number;
+  /** Degrees about X, clamped to `pitchLimit`. */
   pitch?: number;
+  /** Multiplier on the fit scale. */
   zoom?: number;
+  /** Display metres along the depth axis, `+` toward the viewer (out of the glass). */
+  depthOffset?: number;
+}
+
+/**
+ * Where the subject sits in DISPLAY METRES under the pose currently being drawn — an
+ * axis-aligned box enclosing the oriented subject.
+ *
+ * Display space puts the viewer at `+z` and the glass at `z = 0`, so `front` is the larger z:
+ * a positive `front` means the subject pops OUT of the glass, a negative `back` means depth
+ * behind it.
+ */
+export interface SubjectPlacement {
+  /** Box centre. x and y are always 0 — the fit centres the subject on the tile. */
+  center: { x: number; y: number; z: number };
+  /** Full box size (not half-extents). */
+  extent: { x: number; y: number; z: number };
+  /** z of the surface nearest the viewer. `> 0` = in front of the glass. */
+  front: number;
+  /** z of the surface furthest from the viewer. `< 0` = behind the glass. */
+  back: number;
+  /** Model units → display metres currently in force (fit scale × zoom). */
+  scale: number;
 }
 
 /**
@@ -77,7 +103,31 @@ export declare class SceneViewer {
     extent: number[] | { x: number; y: number; z: number },
   ): void;
 
+  /** Snap the pose. Writes the eased value and its target together. */
   setPose(pose?: OrbitPose): void;
+
+  /**
+   * The pose as it is right now. `target: true` reports what it is easing TOWARD, which differs
+   * mid-orbit — a readout wants the default (eased), "save this view" wants the target.
+   */
+  getPose(opts?: { target?: boolean }): Required<OrbitPose>;
+
+  /**
+   * Where the subject is, in display metres, under the live pose. Safe and cheap to call every
+   * frame; allocates one object and does no matrix work.
+   *
+   * Recompute per frame rather than caching: orbit swings the subject's depth into the
+   * display's z, so a value measured at load is only correct at yaw 0.
+   */
+  getSubjectBounds(): SubjectPlacement;
+
+  /**
+   * Slide the subject along the depth axis, display metres, `+` toward the viewer. Survives
+   * `fitTo`; cleared by `resetPose`.
+   */
+  depthOffset: number;
+
+  /** Return to the framed default pose, depth slide included. */
   resetPose(): void;
 
   /**