@displayxr/inline3d 1.5.1 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,93 @@ 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.1 — 2026-09-09
+
+Touches the **core tier** (`.`) with a behaviour fix only — no API changes — and the **preview tier**
+(`./viewer`, `./splat`, `./model`) with one additive option. A page that ignores everything below
+renders identically while it is weaving; the changes only decide what a canvas shows once nothing
+weaves it any more.
+
+### Fixed
+
+- **A canvas nothing is weaving can no longer be left holding a raw side-by-side pair**
+  ([#28](https://github.com/DisplayXR/displayxr-web/issues/28), field report
+  [browser-pvt#99](https://github.com/DisplayXR/displayxr-browser-pvt/issues/99)). Every fallback in
+  this SDK was decided once at boot, so four paths ended with a tile showing a flat squeezed
+  left|right pair, permanently — the symptom users report as "3D element shows SBS", usually on a
+  slow connection:
+  - session `end` tore down without the mono repaint `_deactivate` does — every image and video
+    canvas kept its last SBS frame; teardown, deactivate and a failed activate now share one
+    `_paintMono`;
+  - an image whose download landed **after** teardown painted a fresh SBS pair into a canvas with no
+    layer — `_paint` now forces the mono branch (and a 1:1 buffer) whenever the manager is stopped or
+    the window has no live layer, whatever `win.sbs` says;
+  - a throwing `new XRDisplayLayer()` was swallowed silently and left the canvas as it was — it now
+    warns once per window (with the error) and repaints mono; still no retry;
+  - a buffering video (`readyState < 2`) skipped its paint entirely, so its canvas layer went idle and
+    could drop out of the browser's aggregated frame — it now re-commits its last decoded frame with
+    an identity blit.
+- **One throwing scene no longer stops the windows after it from repainting.** `onFrame` is contained
+  per window and warned about once; an un-redrawn canvas is exactly what the browser's weave join
+  loses.
+
+### Added
+
+- **`addScene({ onLayerLost })`** (preview tier): called once when a scene window's layer goes away
+  for good (session end, or the layer could not be created) — not when a lazy tile scrolls off. The
+  SDK does not own a scene canvas's pixels, so this is how it tells the owner to go flat.
+  `SceneViewer.onLayerLost` is the ready-made handler (`startMono()`), and `./splat` / `./model` wire
+  it for you.
+
+## 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

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/index.d.ts

@@ -179,6 +179,15 @@ export interface SceneOptions extends TileOptions {
   viewRig?: XRViewRigInit;
   /** Element whose visibility drives the lazy create/close lifecycle (defaults to the canvas). */
   observe?: Element;
+  /**
+   * Called once when this window's weave layer goes away for good — the session ended, or the
+   * layer could not be created. You own a scene canvas's pixels, so this is the SDK's only way
+   * to tell you that the side-by-side pair in it is no longer being woven and is now just
+   * squeezed 2D on the page: take the canvas flat here (`SceneViewer.startMono`, or your own
+   * mono path). NOT called when a lazy tile merely scrolls off screen — that layer is coming
+   * back. A throw is caught and warned about.
+   */
+  onLayerLost?: () => void;
 }
 
 /** The per-frame render callback passed to {@link Inline3D.addScene}. */

package/js/inline3d-model.js

@@ -393,6 +393,9 @@ export function addModel(wall, canvas, src, opts = {}) {
   if (wall && wall.supported) {
     handle = wall.addScene(canvas, viewer.onFrame, {
       virtualDisplayHeight,
+      // The layer can go away for good (the session ends, the constructor refuses): take the
+      // canvas flat rather than leave its last side-by-side frame on the page (web#28).
+      onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
     });
   } else {

package/js/inline3d-splat.js

@@ -228,6 +228,9 @@ export function addSplat(wall, canvas, src, opts = {}) {
   if (wall && wall.supported) {
     handle = wall.addScene(canvas, viewer.onFrame, {
       virtualDisplayHeight,
+      // The layer can go away for good (the session ends, the constructor refuses): take the
+      // canvas flat rather than leave its last side-by-side frame on the page (web#28).
+      onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
     });
   } else {

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-viewer.js

@@ -28,7 +28,11 @@
 //   viewer.content.add(myMesh);
 //   viewer.fitTo(center, extent);              // model-space bounds of the subject
 //   const wall = await createInline3D();
-//   if (wall.supported) wall.addScene(canvas, viewer.onFrame, { virtualDisplayHeight: 0.18 });
+//   if (wall.supported)
+//     wall.addScene(canvas, viewer.onFrame, {
+//       virtualDisplayHeight: 0.18,
+//       onLayerLost: viewer.onLayerLost,   // the session ended: go flat rather than show raw SBS
+//     });
 //   else viewer.startMono();
 //
 // WHY FRAMING IS SCENE-GRAPH WORK AND NOT A RIG FIELD. The native display rig
@@ -49,6 +53,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 +227,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;
@@ -258,8 +273,23 @@ export class SceneViewer {
     if (orbit) this._bindOrbit();
     this._resize();
 
-    // Bound so it can be passed straight to addScene without a wrapper closure.
+    // Bound so they can be passed straight to addScene without a wrapper closure.
     this.onFrame = this.onFrame.bind(this);
+    this.onLayerLost = this.onLayerLost.bind(this);
+  }
+
+  /**
+   * The weave layer went away for good — pass this to `wall.addScene(canvas, viewer.onFrame,
+   * { onLayerLost: viewer.onLayerLost })` (`./splat` and `./model` do it for you).
+   *
+   * Without it the canvas keeps its last woven side-by-side frame on screen as ordinary squeezed
+   * 2D, because `_mode` stays `'3d'` and every mono fallback in this SDK is a one-shot decision
+   * made at boot (web#28). Going mono here is safe even if a tile is later re-woven: `onFrame`
+   * calls `stopMono()` on the first 3D frame it gets.
+   */
+  onLayerLost() {
+    if (this._disposed) return;
+    this.startMono();
   }
 
   /**
@@ -278,10 +308,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 +357,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 +374,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 +754,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

@@ -860,6 +860,12 @@ class Inline3D {
    *        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.
+   * @param {() => void} [opts.onLayerLost]  called once when this window's weave layer goes away
+   *        for good — the session ended, or the layer could not be created. YOU own a scene
+   *        canvas's pixels, so this is the SDK's only way to tell you that the side-by-side pair
+   *        in it is no longer being woven and is now just squeezed 2D on the page; take the
+   *        canvas flat here (`SceneViewer.startMono`, or your own mono path). NOT called when a
+   *        lazy tile merely scrolls off screen — that layer is coming back. Errors are caught.
    * @returns {{remove():void}}
    */
   addScene(canvas, onFrame, opts = {}) {
@@ -1746,6 +1752,12 @@ class Inline3D {
       img: null,
       video: null,
       onFrame: null,
+      // Scene windows only (addScene's `onLayerLost`): the layer went away for good. See
+      // _notifyLayerLost — `layerLostSent` keeps it one-shot per loss. Read from the options
+      // HERE rather than after `_register` returns, because a non-lazy window activates (and can
+      // therefore already fail to build its layer) inside this call.
+      onLayerLost: typeof opts.onLayerLost === 'function' ? opts.onLayerLost : null,
+      layerLostSent: false,
       ready: null,
       ownsBuffer: kind !== 'scene',
       cornerRadius: opts.cornerRadius || 0,
@@ -1844,10 +1856,27 @@ class Inline3D {
           ? { virtualDisplayHeight: win.virtualDisplayHeight }
           : {};
       win.layer = new XRDisplayLayer(this.session, win.canvas, init);
-    } catch {
+    } catch (err) {
       win.layer = null;
+      // Say so, once per window, and take the canvas flat. Swallowed silently this was
+      // undiagnosable in the field AND left a re-activated tile holding the SBS pair it wove
+      // with last time — nothing repaints it, and the IntersectionObserver does not re-fire
+      // while the tile stays intersecting. No retry: a constructor that refused this canvas will
+      // refuse it again, and a retry loop would run per frame with nothing to report (web#28).
+      if (!win.layerFailWarned) {
+        win.layerFailWarned = true;
+        console.warn(
+          '[inline3d] new XRDisplayLayer() failed for this window — it will show FLAT 2D ' +
+            'instead of woven 3D, and the SDK will not retry. The canvas has been repainted ' +
+            'mono so it cannot be left holding a raw side-by-side pair.',
+          err
+        );
+      }
+      this._paintMono(win);
+      this._notifyLayerLost(win);
       return;
     }
+    win.layerLostSent = false; // a live layer again: a future loss is worth reporting again
     // 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
@@ -1898,9 +1927,47 @@ class Inline3D {
       win.layer = null;
     }
     // Leave a flat (left-eye-only) frame so an off-screen image/video still shows 2D.
-    if (win.ownsBuffer && win.kind !== 'scene') {
-      this._sizeBuffer(win, /*sbs*/ false);
-      this._paint(win, null);
+    //
+    // A SCENE is deliberately NOT notified here (see _notifyLayerLost): its layer is coming
+    // back the moment the tile scrolls into view again, and `SceneViewer.onFrame` takes the
+    // backing store back to SBS by itself — collapsing on every scroll would make the lazy
+    // lifecycle visible as a mode change.
+    this._paintMono(win);
+  }
+
+  /**
+   * Take a window whose layer is gone back to the ONE state a canvas nothing weaves may be left
+   * in: a flat, left-eye-only frame in a 1:1 buffer (web#28).
+   *
+   * Shared by _deactivate, _teardown and the _activate failure path precisely so the three
+   * cannot drift — _teardown used to skip it entirely, which left every image and video tile on
+   * the page holding its last side-by-side frame, forever, the moment the session ended.
+   * Scene canvases are the page's pixels and are handled by _notifyLayerLost instead.
+   */
+  _paintMono(win) {
+    if (!win.ownsBuffer || win.kind === 'scene') return;
+    this._sizeBuffer(win, /*sbs*/ false);
+    this._paint(win, null);
+  }
+
+  /**
+   * The scene half of the same problem. The SDK does not own a scene canvas's backing store, so
+   * the most it can do is SAY the layer went away and let the owner take itself flat —
+   * `SceneViewer` wires its `startMono()` here (`addScene({ onLayerLost })`), and `./splat` and
+   * `./model` do that for you. Without it a scene tile keeps its last woven side-by-side frame
+   * on screen after the session ends, because every mono fallback in this SDK and its samples is
+   * a one-shot `!supported` branch decided at boot.
+   *
+   * One-shot per loss and never allowed to throw: this runs inside teardown, where a page
+   * callback that raises must not strand the windows behind it.
+   */
+  _notifyLayerLost(win) {
+    if (win.kind !== 'scene' || typeof win.onLayerLost !== 'function' || win.layerLostSent) return;
+    win.layerLostSent = true;
+    try {
+      win.onLayerLost();
+    } catch (err) {
+      console.warn('[inline3d] a scene window\'s onLayerLost callback threw', err);
     }
   }
 
@@ -2208,9 +2275,28 @@ class Inline3D {
 
   _paint(win, _views) {
     if (win.kind === 'scene' || !win.ctx) return;
+    // NOTHING IS WEAVING THIS CANVAS (web#28, browser-pvt#99). A dead manager or a window with
+    // no layer means the browser is not consuming this canvas as a stereo pair any more — so an
+    // SBS paint here puts the raw squeezed left|right pair on screen as ordinary 2D page
+    // content, permanently, because nothing ever repaints it. The path that makes this a FIELD
+    // bug rather than a theoretical one is a slow download: `addImage`'s load resolves after the
+    // session ended and calls `win.repaint()` straight into a canvas whose layer is gone.
+    // Forced here rather than at each call site because the call sites are the async ones.
+    // The buffer comes with it — the mono branch below stretches ONE eye across the whole
+    // backing store, so leaving a 2:1 store would show a double-width half-image.
+    const live = this._running && !!win.layer;
+    if (!live && win.sbs) this._sizeBuffer(win, /*sbs*/ false);
     const src = win.kind === 'video' ? win.video : win.img;
     if (!src) return;
-    if (win.kind === 'video' && (src.readyState || 0) < 2) return; // no frame yet
+    if (win.kind === 'video' && (src.readyState || 0) < 2) {
+      // Buffering: no new frame to draw, and drawing an unready <video> is a no-op per spec (it
+      // would leave the clearRect below as the only thing that happened, i.e. blank the tile).
+      // Skipping the paint entirely is what the old code did, and that is its own bug — see
+      // _frame: a canvas that is not redrawn can have its layer dropped from the aggregated
+      // frame. So re-commit what the canvas already holds instead.
+      if (live) this._recommitLastFrame(win);
+      return;
+    }
     const c = win.canvas;
     const ctx = win.ctx;
     const srcW = src.videoWidth || src.naturalWidth || src.width;
@@ -2234,6 +2320,30 @@ class Inline3D {
     }
   }
 
+  /**
+   * Re-commit the pixels the canvas already holds, unchanged — the cheapest "last decoded frame"
+   * there is, because the last decoded frame is already in the backing store.
+   *
+   * Drawing the canvas onto itself is one same-size blit that dirties the canvas (which is the
+   * whole point: see the every-frame-repaint note in _frame), and `globalCompositeOperation =
+   * 'copy'` is what makes it a true identity — source-over would composite a feathered buffer's
+   * transparent edges onto themselves and darken the ramp a little more every stalled frame.
+   * Only ever reached while a source has nothing new, so a healthy video never pays for it.
+   */
+  _recommitLastFrame(win) {
+    const c = win.canvas;
+    if (!c.width || !c.height) return;
+    const ctx = win.ctx;
+    try {
+      ctx.save();
+      ctx.globalCompositeOperation = 'copy';
+      ctx.drawImage(c, 0, 0);
+      ctx.restore();
+    } catch {
+      /* a context that refuses a self-blit: leave the stale pixels rather than blank the tile */
+    }
+  }
+
   /**
    * Arm the next session frame. `force` starts a NEW loop even though one is nominally
    * pending: each loop carries an id and only the current id re-arms, so a stalled
@@ -2293,7 +2403,22 @@ class Inline3D {
               );
             }
           }
-          win.onFrame(views, win.layer, f);
+          // Contained, and warned about once. A scene that throws (a texture that 404s, a
+          // decoder that gives up) used to abort this loop body for every window AFTER it in the
+          // map — and an un-redrawn canvas can have its layer dropped from the aggregated frame
+          // (see the note below), so one broken tile took its neighbours' weave with it (web#28).
+          try {
+            win.onFrame(views, win.layer, f);
+          } catch (err) {
+            if (!win.frameThrewWarned) {
+              win.frameThrewWarned = true;
+              console.warn(
+                "[inline3d] a scene window's onFrame threw; this window will keep whatever it " +
+                  'last drew, and the other windows carry on. Further throws from it are silent.',
+                err
+              );
+            }
+          }
         }
       } else {
         // Repaint image AND video every frame. The weave reads each window's
@@ -2430,6 +2555,13 @@ class Inline3D {
         }
         win.layer = null;
       }
+      // The repaint _deactivate has always done, which this path used to skip (web#28). Closing
+      // the layer also clears the browser's tracked rect, so from here nothing suppresses these
+      // canvases and nothing will ever repaint them either — whatever is in the backing store
+      // when the session ends is what the page shows from now on. A side-by-side pair is the one
+      // thing that must not be. AFTER the close, so the flat frame is the last thing committed.
+      this._paintMono(win);
+      this._notifyLayerLost(win);
     }
     this._windows.clear();
     // Page listeners go with the session that fed them: a manager whose session has ended will

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "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;
 
   /**
@@ -89,6 +139,12 @@ export declare class SceneViewer {
    * frame either way, so the tile never goes dark and never smears (web#12).
    */
   onFrame(views: readonly XRView[], layer: object): void;
+  /**
+   * The weave layer went away for good — pass to `addScene(canvas, viewer.onFrame,
+   * { onLayerLost: viewer.onLayerLost })` so the tile goes flat instead of showing its last
+   * side-by-side frame as squeezed 2D. Pre-bound; `./splat` and `./model` wire it for you.
+   */
+  onLayerLost(): void;
 
   /** Supply the ./three glue so the 3D path can build its eye camera. Returns `this`. */
   useEyeCamera(EyeCameraClass: unknown, EdgeFeatherClass?: unknown): this;