@displayxr/inline3d 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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**.

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-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
@@ -269,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();
   }
 
   /**

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.6.0",
+  "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

@@ -139,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;