@displayxr/inline3d 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,72 @@ 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.1.1 — 2026-08-20
+
+### Fixed
+
+- **`./viewer` validates a frame before it clears the canvas — the dark blink under GPU load
+  (web#12).** `SceneViewer.onFrame` cleared unconditionally and then rendered whatever it could.
+  Under load the session hands the callback a **short view list** — one view, or none, a per-frame
+  mono fallback — and the old loop turned that into a cleared buffer with a single origin-camera
+  view drawn into it whose content is entirely near-plane-clipped: a fully transparent
+  side-by-side buffer, i.e. **one dark woven tile**. The blink was the viewer's, not the weave's;
+  it was reported as a compositor fault (glTF and splat tiles blinking on a busy box) with the
+  whole submit/match path provably healthy.
+
+  Now every disqualifying condition — a short view list, a `null` or degenerate
+  `layer.getViewport(view)`, a disposed viewer — is checked **while the canvas still holds the
+  last good image**, and only a frame that will draw is allowed to clear. A frame that cannot
+  draw **replays the last good one** from per-eye `Float32Array(16)` copies of
+  `projectionMatrix` / `transform.matrix` plus the viewport rects (copies, because an `XRView` is
+  valid only inside its own frame callback), rather than skipping the commit — the SDK's
+  every-frame-repaint invariant is real, and an un-redrawn canvas can drop out of the aggregated
+  frame and leave the weave reading a stale sub-rect. A one-frame-stale eye pose is
+  imperceptible; a black frame and a smear are not. Before the first good frame there is nothing
+  to replay, and the frame simply returns without clearing.
+
+  **This changes pixels only on frames that were previously black.** A frame that passed
+  validation renders byte-for-byte as it did in 1.1.0 — same clear, same viewports, same
+  matrices, same order. *(preview tier)*
+
+- **A no-op resize no longer blanks the tile (web#12).** `renderer.setSize()` writes
+  `canvas.width`/`canvas.height` unconditionally, and writing either — *including the same value*
+  — reallocates and clears the drawing buffer. `ResizeObserver` fires on things that leave the
+  buffer's dimensions exactly where they were (a sub-pixel reflow, a scrollbar coming and going, a
+  sibling settling), and its callback runs after rAF and before paint, so each one committed a
+  black frame with nothing on the way to repaint it. `_resize` now compares against
+  `renderer.domElement.width/height` and returns early when nothing moved; a real change resizes
+  and then **immediately** re-renders from the replay cache (rects scaled to the new buffer), so
+  the cleared store never reaches the compositor. Observer bursts coalesce to one animation frame,
+  matching what the core already does for its own windows. *(preview tier)*
+
+- **`SceneViewer` without `useEyeCamera()` says so instead of rendering nothing.** With no
+  `./three` glue the 3D path had no eye camera, so it cleared and drew nothing every frame,
+  forever, in silence — and this module's own header example omitted the call, making the failure
+  reachable by copy-paste. It now warns once and renders the **mono camera** into both eye
+  viewports (flat, but visible), and the example passes `EyeCamera`. `./splat` and `./model` were
+  never affected — they supply the glue for you. *(preview tier)*
+
+### Added
+
+- **`EyeCamera.setFromMatrices(projectionMatrix, transformMatrix)`** — the same two matrices an
+  `XRView` carries, handed over separately, for re-drawing a frame you have already drawn.
+  `setFromView` is now a one-line forward to it, so a replay path can never drift from the live
+  one. *(core tier — additive)*
+- **`handle.stats()` → `{ frames, monoFrames }`** on the handle every `add*()` returns. For scene
+  windows, `monoFrames` counts the deliveries that carried fewer than two views — the
+  load-induced fallback that used to be invisible from the page, since nothing throws and nothing
+  logs. A rising ratio is the machine telling you the session is degrading before it becomes a bug
+  report about "blinking"; one throttled `console.debug` (the first, then 1-in-300) names the
+  rate. The core's own contract is unchanged: the view list is passed to `onFrame` exactly as
+  reported, filtered by nothing and synthesised from nothing. *(core tier — additive)*
+- **Unit tests.** `test/*.test.mjs` under `node --test`, with the DOM and three.js stubbed by
+  hand (`test/stubs.mjs`) so the test run needs no dependency either. They pin the rules above:
+  zero `clear()` calls for an empty view list, a one-eye list, a null viewport and a missing
+  layer; a replay that renders the cached matrices and survives the UA recycling the views it
+  cached from; no `setSize` on a no-op resize; an immediate repaint after a real one. 13 of the
+  15 fail against 1.1.0. Wired into CI as a second job.
+
 ## 1.1.0 — 2026-08-19
 
 ### Added

package/index.d.ts

@@ -52,6 +52,18 @@ export interface TileHandle {
    * @deprecated See {@link TileHandle.exclude} — no-op on browsers with draw-order occlusion.
    */
   unexclude(el: Element): void;
+  /**
+   * Per-window frame counters, for diagnosing the load-induced mono fallback.
+   *
+   * `frames` counts `onFrame` deliveries; `monoFrames` counts the ones that carried fewer than
+   * two views — a session under GPU pressure reporting a single view where it normally reports
+   * two. `./viewer` replays its last good stereo frame for those rather than clearing (web#12);
+   * a rising ratio is the machine telling you the session is falling back, and is worth
+   * surfacing before it turns into a bug report about "blinking".
+   *
+   * Scene windows only — image/video windows always report `{ frames: 0, monoFrames: 0 }`.
+   */
+  stats(): { frames: number; monoFrames: number };
 }
 
 /** An open inline-3D session you add weaved windows to. Returned by {@link createInline3D}. */

package/js/inline3d-three.js

@@ -60,10 +60,31 @@ export class EyeCamera {
 
   /** Set the camera's projection + world pose from an XRView (call once per eye per frame). */
   setFromView(view) {
+    return this.setFromMatrices(view.projectionMatrix, view.transform.matrix);
+  }
+
+  /**
+   * Set the camera from RAW matrices — the same two an XRView carries, handed over
+   * separately.
+   *
+   * WHY THIS EXISTS AND NOT JUST setFromView. An `XRView` is valid only inside the frame
+   * callback that produced it: hold one and its matrices are live views onto memory the UA
+   * recycles. So a renderer that wants to re-draw a frame it has ALREADY drawn — because
+   * this frame's view list arrived short, or because the backing store was just reallocated
+   * and cleared — cannot keep the view; it has to keep a COPY of the two matrices and feed
+   * them back here. `./viewer`'s last-good replay does exactly that (see SceneViewer.onFrame).
+   *
+   * Deliberately the single implementation of both: setFromView is a one-line forward, so
+   * the replay path can never drift from the live one.
+   *
+   * @param {ArrayLike<number>} projectionMatrix  16 floats, column-major (view.projectionMatrix).
+   * @param {ArrayLike<number>} transformMatrix   16 floats, column-major (view.transform.matrix).
+   */
+  setFromMatrices(projectionMatrix, transformMatrix) {
     const cam = this.camera;
-    cam.projectionMatrix.fromArray(view.projectionMatrix);
+    cam.projectionMatrix.fromArray(projectionMatrix);
     cam.projectionMatrixInverse.copy(cam.projectionMatrix).invert();
-    cam.matrix.fromArray(view.transform.matrix);
+    cam.matrix.fromArray(transformMatrix);
     cam.matrixWorld.copy(cam.matrix);
     cam.matrixWorldInverse.copy(cam.matrixWorld).invert();
     return cam;

package/js/inline3d-viewer.js

@@ -20,9 +20,11 @@
 //
 //   import * as THREE from 'three';
 //   import { createInline3D } from '@displayxr/inline3d';
+//   import { EyeCamera } from '@displayxr/inline3d/three';
 //   import { SceneViewer } from '@displayxr/inline3d/viewer';
 //
 //   const viewer = new SceneViewer(THREE, canvas, { virtualDisplayHeight: 0.18 });
+//   viewer.useEyeCamera(EyeCamera);            // REQUIRED for stereo; ./splat and ./model do it
 //   viewer.content.add(myMesh);
 //   viewer.fitTo(center, extent);              // model-space bounds of the subject
 //   const wall = await createInline3D();
@@ -226,6 +228,12 @@ export class SceneViewer {
     this._monoRaf = 0;
     this._mode = '3d'; // drives the backing-store shape; see _resize
     this._disposed = false;
+    this._resizePending = false;
+    // Last frame this viewer actually DREW, as raw matrices + viewport rects — never XRViews,
+    // which are only valid inside their own frame callback. See _cacheGood / _replayLastGood.
+    this._lastGood = null;
+    this._vps = []; // scratch, reused per frame so validation allocates nothing
+    this._warnedNoEye = false;
 
     this._reduceMotion =
       typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
@@ -238,7 +246,10 @@ export class SceneViewer {
     // plane to be in focus at, so we just look at the framed subject from the front.
     this.monoCamera = new THREE.PerspectiveCamera(35, 1, 0.001, 1000);
 
-    this._onResize = () => this._resize();
+    // Coalesced: ResizeObserver and window resize both fire in BURSTS during a drag-resize or a
+    // zoom, and every genuine resize reallocates (and clears) the backing store. One rAF per
+    // burst, exactly as the core does for its own windows (inline3d.js _onBoxChange).
+    this._onResize = () => this._scheduleResize();
     this._ro = typeof ResizeObserver === 'function' ? new ResizeObserver(this._onResize) : null;
     if (this._ro) this._ro.observe(canvas);
     else addEventListener('resize', this._onResize);
@@ -348,6 +359,22 @@ export class SceneViewer {
   /**
    * The per-frame callback for `wall.addScene`. Renders the scene once per eye into the
    * side-by-side halves the layer reports.
+   *
+   * VALIDATE BEFORE YOU CLEAR — the dark-blink rule (web#12). `r.clear()` is the point of no
+   * return: after it the canvas is transparent-black, and if the frame then fails to draw
+   * anything over it, that empty buffer is what the weave consumes. Under GPU load the session
+   * can hand this callback a SHORT view list (one view, or none — a per-frame mono fallback),
+   * and the old loop cleared first and rendered what it could: a single origin-camera view whose
+   * content is entirely near-plane-clipped, i.e. a fully transparent side-by-side buffer, i.e.
+   * one dark woven tile. The blink was ours, not the weave's.
+   *
+   * So: everything that can disqualify a frame is checked while the canvas still holds the last
+   * good image, and only a frame that WILL draw is allowed to clear. A frame that cannot draw
+   * REPLAYS the last good one instead (see _replayLastGood) rather than skipping the commit —
+   * the SDK's every-frame-repaint invariant is real (inline3d.js `_frame`: a canvas that isn't
+   * redrawn can have its layer dropped from the aggregated frame and the weave then reads a
+   * stale sub-rect, which smears). A one-frame-stale eye pose is imperceptible; a smear and a
+   * black frame are not.
    */
   onFrame(views, layer) {
     if (this._disposed) return;
@@ -355,23 +382,62 @@ export class SceneViewer {
     // after a scroll-away/scroll-back). Take the buffer back to the SBS shape when that happens
     // — otherwise the first 3D frames render into a 1:1 store and each eye is half a subject.
     if (this._mode !== '3d') this.stopMono();
+    // Before the validation gate on purpose: a replayed frame still damps and still turns on the
+    // turntable, so only the EYE pose is one frame stale, not the whole scene.
     this._tick();
-    const r = this.renderer;
+
+    // 1. A short view list is the load-induced mono fallback. Stereo needs two.
+    if (!views || views.length < 2) {
+      this._replayLastGood();
+      return;
+    }
+
+    // 2. No ./three glue: the 3D path has no eye camera to build. This used to clear and draw
+    //    NOTHING, silently, forever — and this module's own header example omitted
+    //    useEyeCamera() until now, so the failure was reachable by copy-paste. Both ends are
+    //    fixed: the example passes it, and this says so once and renders the mono camera, which
+    //    at least shows the subject (flat, both halves the same) instead of a dark tile.
     const eye = this._ensureEye();
+    if (!eye && !this._warnedNoEye) {
+      this._warnedNoEye = true;
+      console.warn(
+        '[inline3d] SceneViewer.onFrame without useEyeCamera(): falling back to the mono camera. ' +
+          'Pass the ./three glue — viewer.useEyeCamera(EyeCamera, EdgeFeather) — for real ' +
+          'off-axis stereo. (./splat and ./model do this for you.)',
+      );
+    }
+
+    // 3. Every eye must have a viewport to render into. A missing or degenerate one means this
+    //    frame cannot fill the buffer, so it must not empty it either.
+    const vps = this._vps;
+    vps.length = 0;
+    for (const view of views) {
+      const vp = layer && typeof layer.getViewport === 'function' ? layer.getViewport(view) : null;
+      if (!vp || !(vp.width > 0) || !(vp.height > 0)) {
+        this._replayLastGood();
+        return;
+      }
+      vps.push(vp);
+    }
+
+    // Validated: this frame WILL draw over everything it clears.
+    const r = this.renderer;
     r.clear();
     r.setScissorTest(true);
-    for (const view of views) {
-      const vp = layer.getViewport(view);
-      if (!vp) continue;
+    for (let i = 0; i < views.length; i++) {
+      const vp = vps[i];
       r.setViewport(vp.x, vp.y, vp.width, vp.height);
       r.setScissor(vp.x, vp.y, vp.width, vp.height);
       if (eye) {
-        eye.setFromView(view);
+        eye.setFromView(views[i]);
         r.render(this.scene, eye.camera);
+      } else {
+        r.render(this.scene, this.monoCamera);
       }
       if (this._feather) this._feather.render(r, vp);
     }
     r.setScissorTest(false);
+    this._cacheGood(views, vps, !eye);
   }
 
   /**
@@ -418,6 +484,8 @@ export class SceneViewer {
 
   dispose() {
     this._disposed = true;
+    this._resizePending = false;
+    this._lastGood = null;
     this.stopMono();
     if (this._ro) this._ro.disconnect();
     else removeEventListener('resize', this._onResize);
@@ -432,6 +500,127 @@ export class SceneViewer {
     return this._eye;
   }
 
+  /**
+   * Remember the frame just drawn, so a frame that CANNOT draw has something to put on the
+   * canvas instead of a clear (web#12).
+   *
+   * COPIES, never references. An `XRView` — and the `projectionMatrix` / `transform.matrix`
+   * hanging off it — is valid only inside the frame callback that delivered it; the UA is free
+   * to recycle that memory afterwards. Retaining one would give a replay that reads whatever
+   * the next frame happened to write there, which is a worse bug than the blink. So each eye
+   * gets two `Float32Array(16)` copies, allocated once and overwritten in place: the cache
+   * costs 128 bytes an eye and zero allocations per frame.
+   *
+   * The buffer dimensions go in too, so a replay after a resize can scale the rects (the SBS
+   * split is proportional, so the scaling is exact).
+   */
+  _cacheGood(views, vps, mono) {
+    const el = this.renderer.domElement || this.canvas;
+    let g = this._lastGood;
+    if (!g || g.entries.length !== views.length) {
+      g = this._lastGood = { entries: [], mono, bufW: 0, bufH: 0 };
+      for (let i = 0; i < views.length; i++) {
+        g.entries.push({
+          proj: new Float32Array(16),
+          pose: new Float32Array(16),
+          x: 0,
+          y: 0,
+          width: 0,
+          height: 0,
+        });
+      }
+    }
+    g.mono = mono;
+    g.bufW = el.width || 0;
+    g.bufH = el.height || 0;
+    for (let i = 0; i < views.length; i++) {
+      const e = g.entries[i];
+      const vp = vps[i];
+      if (!mono) {
+        const view = views[i];
+        e.proj.set(view.projectionMatrix);
+        e.pose.set(view.transform.matrix);
+      }
+      e.x = vp.x;
+      e.y = vp.y;
+      e.width = vp.width;
+      e.height = vp.height;
+    }
+  }
+
+  /**
+   * Re-render the last good frame from the cached matrices. Returns false when there is no
+   * cache yet — and the caller must then do NOTHING, not clear: before the first good frame
+   * the canvas holds either the page's own initial state or the mono fallback's output, both
+   * of which are better than black.
+   */
+  _replayLastGood() {
+    const g = this._lastGood;
+    if (!g || this._disposed) return false;
+    const r = this.renderer;
+    const eye = g.mono ? null : this._ensureEye();
+    const el = this.renderer.domElement || this.canvas;
+    // A resize between the cache and the replay changes the buffer, not the split.
+    const sx = g.bufW > 0 && el.width ? el.width / g.bufW : 1;
+    const sy = g.bufH > 0 && el.height ? el.height / g.bufH : 1;
+    const scaled = sx !== 1 || sy !== 1;
+    r.clear();
+    r.setScissorTest(true);
+    for (const e of g.entries) {
+      const vp = scaled
+        ? {
+            x: Math.round(e.x * sx),
+            y: Math.round(e.y * sy),
+            width: Math.max(1, Math.round(e.width * sx)),
+            height: Math.max(1, Math.round(e.height * sy)),
+          }
+        : e;
+      r.setViewport(vp.x, vp.y, vp.width, vp.height);
+      r.setScissor(vp.x, vp.y, vp.width, vp.height);
+      if (eye) {
+        eye.setFromMatrices(e.proj, e.pose);
+        r.render(this.scene, eye.camera);
+      } else {
+        r.render(this.scene, this.monoCamera);
+      }
+      if (this._feather) this._feather.render(r, vp);
+    }
+    r.setScissorTest(false);
+    return true;
+  }
+
+  /** One rAF per burst of observer callbacks. See the _onResize comment. */
+  _scheduleResize() {
+    if (this._disposed || this._resizePending) return;
+    this._resizePending = true;
+    const run = () => {
+      if (!this._resizePending) return;
+      this._resizePending = false;
+      this._resize();
+    };
+    if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run);
+    else run();
+  }
+
+  /**
+   * Put the last good frame back on a buffer that was just cleared, NOW — not on the next
+   * animation frame. A ResizeObserver callback runs after rAF and before paint, so the frame
+   * that reallocated the buffer is the frame that gets committed: without this the tile weaves
+   * one black frame per box change, with nothing on the way to repaint it. Mirrors the core's
+   * "repaint NOW: setting canvas.width cleared the buffer" (inline3d.js _onBoxChange).
+   */
+  _repaintAfterResize() {
+    if (this._disposed) return;
+    if (this._mode === 'mono') {
+      const r = this.renderer;
+      r.clear();
+      r.setViewport(0, 0, this.canvas.width, this.canvas.height);
+      r.render(this.scene, this.monoCamera);
+      return;
+    }
+    this._replayLastGood();
+  }
+
   _applyTransform() {
     const s = this._fitScale * this._zoom;
     this._pivot.scale.setScalar(s);
@@ -454,6 +643,13 @@ export class SceneViewer {
    * getViewport() splits canvas.width in half for the two eyes — the browser squashing that
    * 2:1 buffer into the 1:1 CSS box IS the side-by-side squeeze, and the weave un-squeezes it.
    * In mono it must stay 1:1 or the flat render is stretched.
+   *
+   * NON-DESTRUCTIVE (web#12). `setSize` writes `canvas.width`/`canvas.height` UNCONDITIONALLY,
+   * and writing either one reallocates and CLEARS the drawing buffer even when the value does
+   * not change. Since a ResizeObserver fires on plenty of things that leave the buffer's
+   * dimensions exactly where they were (a sub-pixel reflow, a scrollbar appearing and going, a
+   * sibling settling), the old unconditional call meant a black frame for every no-op. So:
+   * compare first, and when it IS a real change, put the picture back before the frame commits.
    */
   _resize() {
     if (this._disposed) return;
@@ -462,9 +658,14 @@ export class SceneViewer {
     const dpr = Math.min(window.devicePixelRatio || 1, 2) * this.renderScale;
     const w = Math.max(1, Math.round(box.width * dpr));
     const h = Math.max(1, Math.round(box.height * dpr));
-    this.renderer.setSize(this._mode === 'mono' ? w : w * 2, h, false);
+    const bufW = this._mode === 'mono' ? w : w * 2;
+    // Cheap and always correct to refresh, whether or not the backing store moves.
     this.monoCamera.aspect = box.width / box.height;
     this.monoCamera.updateProjectionMatrix();
+    const el = this.renderer.domElement || this.canvas;
+    if (el.width === bufW && el.height === h) return; // observer fired, geometry didn't move
+    this.renderer.setSize(bufW, h, false);
+    this._repaintAfterResize();
   }
 
   /** Damping + idle turntable. Called once per rendered frame, 3D or mono. */

package/js/inline3d.js

@@ -528,6 +528,9 @@ class Inline3D {
         if (!el || !win.excluded.delete(el)) return;
         this._dropExclusion(win, el);
       },
+      // 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 }),
     };
   }
 
@@ -574,6 +577,10 @@ class Inline3D {
       // Box/dpr watch, live only while the window is (see _startSizeWatch).
       sizeObserver: null,
       resizePending: false,
+      // Scene diagnostics (web#12), read back through the handle's stats(). frames counts
+      // onFrame deliveries; monoFrames counts the ones that carried fewer than two views.
+      frames: 0,
+      monoFrames: 0,
     };
     this._windows.set(canvas, win);
     if (this._lazy && this._observer) {
@@ -1020,7 +1027,32 @@ class Inline3D {
     for (const win of this._windows.values()) {
       if (!win.layer) continue;
       if (win.kind === 'scene') {
-        if (views && win.onFrame) win.onFrame(views, win.layer, f);
+        if (views && win.onFrame) {
+          // Count the SHORT view lists and hand them over unchanged. Under GPU load the session
+          // can report a single view (a per-frame mono fallback) where it normally reports two,
+          // and a renderer that clears before it validates turns that into a dark tile
+          // (web#12 — ./viewer now validates first and replays its last good frame instead).
+          //
+          // The core deliberately does NOT filter or synthesise: the contract is "here is what
+          // the frame reported", and a window that can do something sensible with one view
+          // (a mono preview, say) must be allowed to. What the core owes you is VISIBILITY —
+          // this is otherwise invisible from the page, since nothing throws and nothing logs.
+          win.frames++;
+          if (views.length < 2) {
+            win.monoFrames++;
+            // 1-in-300 so a sustained rate is reported without the log itself becoming the load;
+            // `% 300 === 1` also names the FIRST one immediately.
+            if (win.monoFrames % 300 === 1 && typeof console !== 'undefined' && console.debug) {
+              const pct = ((100 * win.monoFrames) / Math.max(1, win.frames)).toFixed(1);
+              console.debug(
+                `[inline3d] scene window: ${win.monoFrames} non-stereo view lists in ` +
+                  `${win.frames} frames (${pct}%). The viewer replays its last good stereo ` +
+                  'frame for these; a rising rate means the session is falling back under load.',
+              );
+            }
+          }
+          win.onFrame(views, win.layer, f);
+        }
       } else {
         // Repaint image AND video every frame. The weave reads each window's
         // composited canvas quad per frame; a canvas that isn't redrawn can have

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.1.0",
+  "version": "1.1.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",
@@ -83,7 +83,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "npm run typecheck"
+    "test": "tsc --noEmit -p tsconfig.json && node --test \"test/*.test.mjs\""
   },
   "devDependencies": {
     "typescript": "^5.4.0",

package/three.d.ts

@@ -15,6 +15,18 @@ export class EyeCamera {
   readonly camera: unknown;
   /** Set the camera's projection + world pose straight from an XRView (call once per eye). */
   setFromView(view: XRView): void;
+  /**
+   * Set the camera from the two raw matrices an XRView carries, handed over separately.
+   *
+   * For re-drawing a frame you have already drawn: an `XRView` is valid only inside its own
+   * frame callback, so a renderer that wants to repaint (a short view list, a backing store
+   * just reallocated and cleared) must keep COPIES of these two matrices, not the view.
+   * `setFromView` forwards to this, so both paths are the same code.
+   */
+  setFromMatrices(
+    projectionMatrix: ArrayLike<number>,
+    transformMatrix: ArrayLike<number>,
+  ): void;
 }
 
 /**

package/viewer.d.ts

@@ -80,7 +80,14 @@ export declare class SceneViewer {
   setPose(pose?: OrbitPose): void;
   resetPose(): void;
 
-  /** Pass straight to `wall.addScene(canvas, viewer.onFrame, …)`. Pre-bound. */
+  /**
+   * Pass straight to `wall.addScene(canvas, viewer.onFrame, …)`. Pre-bound.
+   *
+   * Validates before it clears: a frame that cannot draw both eyes (a short view list from a
+   * session falling back under load, a missing viewport) re-renders the last good frame from
+   * cached matrices instead of clearing the canvas to black — the canvas is committed every
+   * frame either way, so the tile never goes dark and never smears (web#12).
+   */
   onFrame(views: readonly XRView[], layer: object): void;
 
   /** Supply the ./three glue so the 3D path can build its eye camera. Returns `this`. */