@displayxr/inline3d 1.38.0 → 1.40.0

package/js/inline3d-cursor-option.js

@@ -36,3 +36,21 @@ export function resolveCursorOption(opt, who = '@displayxr/inline3d') {
   }
   return { ...opt };
 }
+
+/** The keys `cursor: { … }` accepts on a stereo PAIR (./camera's addCameraView, ./call's tiles). */
+export const PAIR_CURSOR_OPTION_KEYS = Object.freeze(['height', 'pointerScope']);
+
+/**
+ * `cursor` on a stereo pair — a camera view or a call tile: `'depth'`, or `{ height, pointerScope }`.
+ * A pair has no scene: its depth is MEASURED off the two halves, and the sprite is drawn into them,
+ * so there is no anchor mode (it is always on the line of sight) and the margin is the SDK's. Falsy
+ * is OFF, the zero-cost default.
+ * @returns {null | {height?: number, pointerScope?: string}}
+ */
+export function resolvePairCursorOption(opt, who = '@displayxr/inline3d') {
+  const o = resolveCursorOption(opt, who);
+  if (!o) return null;
+  const unknown = Object.keys(o).filter((k) => !PAIR_CURSOR_OPTION_KEYS.includes(k));
+  if (unknown.length) throw new Error(`${who}: cursor — ${unknown.join(', ')} not supported on a stereo pair; expected ${PAIR_CURSOR_OPTION_KEYS.join(', ')}.`);
+  return o;
+}

package/js/inline3d-model-entry.js

@@ -21,6 +21,7 @@
 // engine import fails, one warning names what to install, and the tile renders on three. With
 // neither, `ready` rejects naming both. An explicit `engine` never falls back.
 
+import { guardedAttach } from './inline3d-splat-shared.js';
 /** The engines `addModel` renders with; the first is the default. */
 export const MODEL_ENGINES = Object.freeze(['playcanvas', 'three']);
 
@@ -98,6 +99,12 @@ export function validateModelCall(canvas, src, opts, route) {
  *          fill in as the backend loads.
  */
 export function addModel(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addModel', opts, (o) => addModelUnguarded(wall, canvas, src, o));
+}
+
+function addModelUnguarded(wall, canvas, src, opts = {}) {
   const route = resolveModelEngine(opts);
   validateModelCall(canvas, src, opts, route);
   if (route.engine === 'playcanvas') {

package/js/inline3d-model-playcanvas.js

@@ -531,6 +531,11 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();

package/js/inline3d-model.js

@@ -38,6 +38,7 @@
 // your own origin (`/draco/`, `/basis/`) and `opts.decoderPath` moves that. See
 // docs/authoring-inline-3d.md#compressed-gltf.
 
+import { guardedAttach } from './inline3d-splat-shared.js';
 import * as THREE from 'three';
 import { EyeCamera, EdgeFeather, DepthCursor, raycastHitTest } from './inline3d-three.js';
 import { resolveCursorOption } from './inline3d-cursor-depth.js';
@@ -345,6 +346,12 @@ function kindFromMessage(msg) {
  *          `setPose`, `resetPose`, `frame`, and `ready`.
  */
 export function addModel(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addModel', opts, (o) => addModelUnguarded(wall, canvas, src, o));
+}
+
+function addModelUnguarded(wall, canvas, src, opts = {}) {
   const {
     virtualDisplayHeight = 0.24,
     frame = null,
@@ -426,6 +433,11 @@ export function addModel(wall, canvas, src, opts = {}) {
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();

package/js/inline3d-splat-pc-entry.js

@@ -16,7 +16,7 @@
 // Not here: measureSplatBounds (it measures a Spark mesh — import it from ./splat).
 
 import { resolveRevealOption } from './inline3d-splat-effects.js';
-import { CAPTURE_FITS, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
+import { CAPTURE_FITS, guardedAttach, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
 import { addSplatDeferred } from './inline3d-splat-deferred.js';
 
 export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
@@ -25,6 +25,12 @@ export { resolveRig } from './inline3d-splat-rig.js';
 
 /** addSplat with `engine: 'playcanvas'`; the same validation, at the call, as ./splat's. */
 export function addSplat(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addSplat', opts, (o) => addSplatUnguarded(wall, canvas, src, o));
+}
+
+function addSplatUnguarded(wall, canvas, src, opts = {}) {
   if (opts.engine !== undefined && opts.engine !== 'playcanvas') {
     throw new Error(
       `@displayxr/inline3d/splat/playcanvas: engine "${opts.engine}" — this entry is PlayCanvas ` +

package/js/inline3d-splat-playcanvas.js

@@ -1002,7 +1002,11 @@ export class PlayCanvasSplatViewer {
     this._tileBudget = undefined; // undefined = the engine's own default
     this._budgetViews = 1;
 
-    this._onResize = () => this._scheduleResize();
+    // Resize AND draw inside the observer callback (it runs after the frame's animation callbacks
+    // and before the paint). Deferring to the next animation frame, as this used to, let one
+    // paint show the old backing store stretched onto the new box: a visible jolt on every
+    // CSS resize of a woven canvas. See _resizeNow for the two cases that still defer.
+    this._onResize = () => this._resizeNow();
     this._ro = typeof ResizeObserver === 'function' ? new ResizeObserver(this._onResize) : null;
     if (this._ro) this._ro.observe(canvas);
     else if (typeof addEventListener === 'function') addEventListener('resize', this._onResize);
@@ -1231,7 +1235,7 @@ export class PlayCanvasSplatViewer {
     this._beforeFrame?.(views || null);
     this._tick();
     if (!views || views.length < 2) {
-      this._replayLastGood();
+      this._replayOrFlat();
       return;
     }
     const vps = this._vps;
@@ -1239,7 +1243,7 @@ export class PlayCanvasSplatViewer {
     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();
+        this._replayOrFlat();
         return;
       }
       vps.push(vp);
@@ -2010,6 +2014,17 @@ export class PlayCanvasSplatViewer {
    * engine tick. Every entry is {proj, pose, x, y, width, height} in BUFFER pixels.
    */
   _drawEntries(entries, cache) {
+    // `_drawing` is what _resizeNow checks: never reallocate the buffer under a running render.
+    if (this._drawing) return this._drawEntriesInner(entries, cache);
+    this._drawing = true;
+    try {
+      return this._drawEntriesInner(entries, cache);
+    } finally {
+      this._drawing = false;
+    }
+  }
+
+  _drawEntriesInner(entries, cache) {
     const app = this.app;
     if (!app || !this.pc) return false;
     const pc = this.pc;
@@ -2139,6 +2154,7 @@ export class PlayCanvasSplatViewer {
     }
     g.bufW = el.width || 0;
     g.bufH = el.height || 0;
+    g.boxAspect = this.boxAspect || 0; // the CSS shape these views were located for (see _replayLastGood)
     g.rig = this._rigSnap ? { ...this._rigSnap } : null; // a replay re-uses the rig of its views
     g.rigAt = this._rigAtPull ?? null;
     for (let i = 0; i < views.length; i++) {
@@ -2153,10 +2169,90 @@ export class PlayCanvasSplatViewer {
     }
   }
 
+  /**
+   * A session frame that cannot draw its own views still PRESENTS: the last good frame, or —
+   * before there is one — the mono camera into both halves (flat, the subject if loaded, else
+   * the clear colour). A woven canvas that is not redrawn can drop out of the frame the
+   * compositor aggregates (woven-canvas-rules, "redraw every frame"), and a load-fallback frame
+   * before the first stereo one is exactly when no cache exists. The only frame this cannot
+   * cover is one before the engine has attached: there is no GL context yet, and creating one
+   * here would create it with the wrong attributes.
+   */
+  _replayOrFlat() {
+    return this._replayLastGood() || this._drawFlatPair();
+  }
+
+  _drawFlatPair() {
+    if (this._disposed || !this.app || !this.pc) return false;
+    const b = this._bufScale();
+    const W = b.w || this.canvas.width;
+    const H = b.h || this.canvas.height;
+    if (!(W > 1) || !(H > 0)) return false;
+    const half = Math.floor(W / 2);
+    const v = this._monoView();
+    const pair = (this._flatPair ||= [0, 1].map(() => ({ proj: null, pose: null, x: 0, y: 0, width: 0, height: 0 })));
+    for (let i = 0; i < 2; i++) {
+      const e = pair[i];
+      e.proj = v.proj;
+      e.pose = v.pose;
+      e.x = i * half;
+      e.y = 0;
+      e.width = half;
+      e.height = H;
+    }
+    return this._drawEntries(pair, null);
+  }
+
   _replayLastGood() {
     const g = this._lastGood;
     if (!g || this._disposed) return false;
-    return this._drawEntries(g.entries, g);
+    // A box whose aspect changed since the cache (a CSS resize replayed before the runtime has
+    // located views for the new rect): the cached frustum was built for the OLD shape, and the
+    // viewports map onto the new buffer proportionally, so the picture would be stretched by
+    // exactly the aspect ratio change. Widen (or narrow) the frustum by the same factor —
+    // dividing the projection's x row by it — so the replayed frame keeps its proportions. One
+    // frame's approximation: the next located views carry the true frustum for the new window.
+    const f = g.boxAspect > 0 && this.boxAspect > 0 ? this.boxAspect / g.boxAspect : 1;
+    if (Math.abs(f - 1) < 1e-6) return this._drawEntries(g.entries, g);
+    const fixed = (this._aspectFixed ||= []);
+    fixed.length = g.entries.length;
+    for (let i = 0; i < g.entries.length; i++) {
+      const e = g.entries[i];
+      const o = (fixed[i] ||= { proj: new Float32Array(16), pose: null, x: 0, y: 0, width: 0, height: 0 });
+      o.proj.set(e.proj);
+      o.proj[0] /= f;
+      o.proj[4] /= f;
+      o.proj[8] /= f;
+      o.proj[12] /= f;
+      o.pose = e.pose;
+      o.x = e.x;
+      o.y = e.y;
+      o.width = e.width;
+      o.height = e.height;
+    }
+    return this._drawEntries(fixed, g);
+  }
+
+  /**
+   * The observer's resize, synchronous. Two cases still take the debounced path instead: a call
+   * that arrives while this viewer is already resizing (re-entrancy: setting canvas.width can
+   * queue more observer work), and one that arrives while it is drawing (a nested dispatch from
+   * inside the engine's tick). Reallocating the drawing buffer under a running render would
+   * leave that render half on a cleared store.
+   */
+  _resizeNow() {
+    if (this._disposed) return;
+    if (this._inResize || this._drawing) {
+      this._scheduleResize();
+      return;
+    }
+    this._resizePending = false; // this run supersedes a debounced one already queued
+    this._inResize = true;
+    try {
+      this._resize();
+    } finally {
+      this._inResize = false;
+    }
   }
 
   _scheduleResize() {
@@ -3599,6 +3695,11 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();

package/js/inline3d-splat-shared.js

@@ -12,6 +12,23 @@
 // apart on how a drag, a wheel notch, an idle turntable or a focus change feels. Pinned by
 // test/splat-playcanvas.test.mjs (values, and a behavioural trace of both viewers side by side).
 
+/**
+ * Double-attach detection around a scene subpath's public entry (`addSplat`, `addModel`).
+ *
+ * The check has to run HERE, at the entry, and not only in the core's addScene: the subpaths build
+ * a renderer on the canvas BEFORE the core window exists (asynchronously, once the engine module
+ * has loaded), so a second `addSplat` during the first one's load would never reach the core's
+ * check in time. `wall._attachGuard` (the core manager) warns once per canvas and claims it; the
+ * call then proceeds exactly as before. A wall without it (no session, an older core) attaches as is.
+ */
+export function guardedAttach(wall, canvas, method, opts, attach) {
+  const g = wall && typeof wall._attachGuard === 'function' ? wall._attachGuard(canvas, method, opts) : null;
+  if (!g) return attach(opts);
+  const out = attach(g.opts);
+  g.own(out);
+  return out;
+}
+
 /**
  * Backstop on total subject depth, as a multiple of the display height. Generous on purpose:
  * depth placement is a z decision (see fitTo), not a scale one, so this only catches the

package/js/inline3d-splat.js

@@ -39,6 +39,7 @@ import {
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
   declareViewRig,
+  guardedAttach,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -162,6 +163,12 @@ function sniffFileType(bytes) {
  * good enough for a clean, isolated capture, weaker on a scene with a background wall.
  */
 export function addSplat(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addSplat', opts, (o) => addSplatUnguarded(wall, canvas, src, o));
+}
+
+function addSplatUnguarded(wall, canvas, src, opts = {}) {
   if (opts.captureFit !== undefined && !CAPTURE_FITS.includes(opts.captureFit)) {
     throw new Error(
       `@displayxr/inline3d/splat: captureFit "${opts.captureFit}" — expected ` +
@@ -487,6 +494,11 @@ export function addSplat(wall, canvas, src, opts = {}) {
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();

package/js/inline3d-viewer.js

@@ -699,7 +699,7 @@ export class SceneViewer {
 
     // 1. A short view list is the load-induced mono fallback. Stereo needs two.
     if (!views || views.length < 2) {
-      this._replayLastGood();
+      this._replayOrFlat();
       return;
     }
 
@@ -725,7 +725,7 @@ export class SceneViewer {
     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();
+        this._replayOrFlat();
         return;
       }
       vps.push(vp);
@@ -891,11 +891,41 @@ export class SceneViewer {
     }
   }
 
+  /**
+   * A session frame that cannot draw its own views still PRESENTS (1.38): the last good frame,
+   * or, before there is one, the mono camera into both halves — flat, but drawn. An undrawn
+   * woven canvas can drop out of the frame the compositor aggregates (woven-canvas-rules,
+   * "redraw every frame"), and this viewer used to leave exactly the frames before the first
+   * stereo one undrawn. Every clear here is followed by a draw, so the dark-blink rule (web#12)
+   * still holds.
+   */
+  _replayOrFlat() {
+    return this._replayLastGood() || this._drawFlatPair();
+  }
+
+  _drawFlatPair() {
+    if (this._disposed) return false;
+    const r = this.renderer;
+    const b = this._bufScale();
+    if (!(b.w > 1) || !(b.h > 0)) return false;
+    const half = Math.floor(b.w / 2);
+    r.clear();
+    r.setScissorTest(true);
+    for (const x of [0, half]) {
+      const vp = { x, y: 0, width: half, height: b.h };
+      r.setViewport(vp.x, vp.y, vp.width, vp.height);
+      r.setScissor(vp.x, vp.y, vp.width, vp.height);
+      r.render(this.scene, this.monoCamera);
+      if (this._feather) this._feather.render(r, vp);
+    }
+    r.setScissorTest(false);
+    return true;
+  }
+
   /**
    * 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.
+   * cache yet (onFrame then draws the flat pair, see _replayOrFlat; a resize leaves the
+   * freshly cleared store to the next session frame).
    */
   _replayLastGood() {
     const g = this._lastGood;