@displayxr/inline3d 1.28.0 → 1.30.0

package/js/inline3d-splat-video.js

@@ -26,11 +26,33 @@
 // per-frame allocation on our side. RGBA8, sampled and written UNCHANGED — the same encoded sRGB
 // values a 2D canvas drawImage() of the frame puts in the buffer (addVideo's paint), so the woven
 // video and the flat one are the same pixels.
+//
+// CROSSFADE (transition: 'crossfade', A5.1 of RFC 0001). A video -> video swap can dissolve on the
+// GPU instead of cutting. At the swap the plane's current quad is handed off, as it is, to a GHOST:
+// its texture is frozen (no more uploads, so the outgoing <video> can be released at once), and its
+// material turns blended, drawn after the incoming quad, fading 1 -> 0 over `durationMs`. The
+// incoming video goes onto a fresh quad underneath, opaque from its first frame. So each quad keeps
+// its own size, format and fit, and a swap between two aspects fades bar-for-bar. Only between two
+// videos: entering from the splat and setVideo(null) stay cuts. A swap while a fade is still
+// running drops the old ghost (a small pop) and fades from the video then on screen.
+//
+// BAND (A5.2). `band: 2.39` (or '2.39:1') narrows the window to a centred letterbox slot of that
+// aspect before fitting, exactly as ./player's `band` narrows its tile: the rest of the element
+// stays clear. 'contain' in the band is a smaller quad. 'cover' in the band cannot lean on the
+// window's frustum edges to cut the overflow (the band is inside the window), so the quad is the
+// band exactly and the overflow is cropped in TEXTURE space instead: each eye's region is narrowed
+// about its centre. Without a band nothing changes.
+import { EASINGS } from './inline3d-splat-effects.js';
 
 /** handle.setVideo's formats, fits and rigs. */
 export const VIDEO_FORMATS = Object.freeze(['sbs', 'tb', 'mono']);
 export const VIDEO_FITS = Object.freeze(['contain', 'cover']);
-const VIDEO_OPTION_KEYS = new Set(['format', 'fit', 'rig', 'virtualDisplayHeight', 'loop', 'muted', 'autoplay']);
+const VIDEO_OPTION_KEYS = new Set(['format', 'fit', 'rig', 'virtualDisplayHeight', 'loop', 'muted', 'autoplay', 'transition', 'durationMs', 'easing', 'outgoing', 'band']);
+/** setVideo's transitions: the player's vocabulary (./player), not setSource's gaussian ones. */
+export const VIDEO_TRANSITIONS = Object.freeze(['cut', 'crossfade']);
+/** The player's defaults (DEFAULT_CROSSFADE_MS / easeInOutSine), so both surfaces fade alike. */
+export const VIDEO_CROSSFADE_MS = 600;
+const VIDEO_CROSSFADE_EASING = 'easeInOutSine';
 let warnedVideoKeys = false;
 
 export const PAGE_VIDEO_ERROR =
@@ -41,7 +63,9 @@ export const PAGE_VIDEO_ERROR =
  * setVideo's arguments, validated and resolved (throws at the call, before anything runs).
  * `src` null/undefined is the exit call and is not validated here.
  * @returns {{ src: string|HTMLVideoElement, format: 'sbs'|'tb'|'mono', fit: 'contain'|'cover',
- *            vH: number|undefined, loop?: boolean, muted?: boolean, autoplay?: boolean }}
+ *            vH: number|undefined, loop?: boolean, muted?: boolean, autoplay?: boolean,
+ *            transition: { type: 'cut'|'crossfade', durationMs: number, easing: string|Function },
+ *            band: number|null }}
  */
 export function validateSetVideo(src, o = {}, pageMode = false) {
   if (pageMode) throw new Error(PAGE_VIDEO_ERROR);
@@ -70,7 +94,43 @@ export function validateSetVideo(src, o = {}, pageMode = false) {
     if (!Number.isFinite(vH) || !(vH > 0)) throw new Error(`@displayxr/inline3d/splat: setVideo — bad virtualDisplayHeight: ${o.virtualDisplayHeight}.`);
   }
   const bool = (k) => (o[k] === undefined ? undefined : !!o[k]);
-  return { src, format, fit, vH, loop: bool('loop'), muted: bool('muted'), autoplay: bool('autoplay') };
+  let band = null;
+  if (o.band !== undefined && o.band !== null) {
+    band = parseBandAspect(o.band);
+    if (band === null) throw new Error(`@displayxr/inline3d/splat: setVideo — bad band: ${JSON.stringify(o.band)} (a number > 0, or 'W:H').`);
+  }
+  return { src, format, fit, vH, loop: bool('loop'), muted: bool('muted'), autoplay: bool('autoplay'), transition: resolveVideoTransition(o), band };
+}
+
+/** A band aspect: a number > 0, or 'W:H' / 'W/H' / 'WxH' / a numeric string. Null if unusable. */
+export function parseBandAspect(a) {
+  if (typeof a === 'number') return Number.isFinite(a) && a > 0 ? a : null;
+  if (typeof a !== 'string') return null;
+  const m = a.trim().match(/^(\d+(?:\.\d+)?)\s*[:/x]\s*(\d+(?:\.\d+)?)$/i);
+  const v = m ? Number(m[1]) / Number(m[2]) : Number(a);
+  return Number.isFinite(v) && v > 0 ? v : null;
+}
+
+/** setVideo's transition options: `{ type, durationMs, easing }`. Throws on a page bug. */
+export function resolveVideoTransition(o = {}) {
+  const type = o.transition === undefined ? 'cut' : o.transition;
+  if (!VIDEO_TRANSITIONS.includes(type)) {
+    const name = typeof type === 'string' ? type : type && typeof type === 'object' ? type.type || 'object' : String(type);
+    throw new Error(
+      `@displayxr/inline3d/splat: setVideo transition '${name}' — expected ${VIDEO_TRANSITIONS.join(' | ')}. ` +
+        "setSource's other transitions move a 3D photo's gaussians; a video frame has none.",
+    );
+  }
+  if (o.outgoing !== undefined && o.outgoing !== 'frozen') {
+    throw new Error(`@displayxr/inline3d/splat: setVideo outgoing '${o.outgoing}' — a video crossfade dissolves from the outgoing video's last frame ('frozen').`);
+  }
+  const durationMs = o.durationMs === undefined ? VIDEO_CROSSFADE_MS : o.durationMs;
+  if (!Number.isFinite(durationMs) || durationMs < 0) throw new RangeError(`@displayxr/inline3d/splat: setVideo durationMs must be ≥ 0, got ${o.durationMs}.`);
+  const easing = o.easing === undefined ? VIDEO_CROSSFADE_EASING : o.easing;
+  if (typeof easing !== 'function' && !(typeof easing === 'string' && Object.prototype.hasOwnProperty.call(EASINGS, easing))) {
+    throw new Error(`@displayxr/inline3d/splat: unknown easing '${easing}'.`);
+  }
+  return { type, durationMs, easing };
 }
 
 /**
@@ -96,15 +156,58 @@ export function eyeAspect(format, w, h) {
  * the window contained ('contain': all of the frame, bars where the aspects differ) or covered
  * ('cover': the window full, the overflow cut by the window's own frustum edges).
  */
-export function videoPlaneSize({ boxAspect, eyeAspect: a, vH, fit = 'contain' }) {
+export function videoPlaneSize({ boxAspect, eyeAspect: a, vH, fit = 'contain', band = null }) {
   const W = vH * boxAspect;
   const H = vH;
   if (!(a > 0) || !(boxAspect > 0)) return { w: W, h: H };
+  if (band > 0) {
+    const b = videoBandSlot(W, H, band);
+    // 'cover': the quad IS the band, and the overflow is cut in texture space (videoCrop).
+    if (fit === 'cover') return { w: b.w, h: b.h };
+    return a >= band ? { w: b.w, h: b.w / a } : { w: b.h * a, h: b.h }; // the slot's aspect is `band`
+  }
   const wider = a >= boxAspect;
   if ((fit === 'contain') === wider) return { w: W, h: W / a };
   return { w: H * a, h: H };
 }
 
+/** The centred band slot of aspect `band` inside a W × H window (./player's bandBox, sizes only). */
+export function videoBandSlot(W, H, band) {
+  if (!(band > 0) || !(W > 0 && H > 0)) return { w: W, h: H };
+  return band >= W / H ? { w: W, h: W / band } : { w: H * band, h: H };
+}
+
+/**
+ * The fraction of each eye's region the quad shows, [fx, fy], centred: [1, 1] except 'cover' in a
+ * band, where the quad is the band and the overflow is cropped in texture space.
+ */
+export function videoCrop({ boxAspect, eyeAspect: a, fit, band }) {
+  if (fit !== 'cover' || !(band > 0) || !(a > 0) || !(boxAspect > 0)) return [1, 1];
+  // The slot keeps the band's aspect whatever the window, so crop the eye to `band` directly.
+  return a >= band ? [band / a, 1] : [1, a / band];
+}
+
+/**
+ * The quad's on-screen rect in CSS px of a `boxW × boxH` canvas: the display rig's z = 0 plane spans
+ * the element, so window units map linearly onto it, centred. Clipped to the canvas (a 'cover' quad
+ * outside a band overflows it), rounded to 1/100 px.
+ */
+export function videoScreenRect({ w, h, W, H }, boxW, boxH) {
+  const pw = (w / W) * boxW;
+  const ph = (h / H) * boxH;
+  const x0 = Math.max(0, (boxW - pw) / 2);
+  const y0 = Math.max(0, (boxH - ph) / 2);
+  const x1 = Math.min(boxW, (boxW + pw) / 2);
+  const y1 = Math.min(boxH, (boxH + ph) / 2);
+  const q = (v) => Math.round(v * 100) / 100;
+  return Object.freeze({ x: q(x0), y: q(y0), width: q(x1 - x0), height: q(y1 - y0) });
+}
+
+/** An eye region [s0, t0, ds, dt] narrowed about its centre to [fx, fy] of itself. */
+export function cropRegion(r, [fx, fy]) {
+  return [r[0] + (r[2] * (1 - fx)) / 2, r[1] + (r[3] * (1 - fy)) / 2, r[2] * fx, r[3] * fy];
+}
+
 /**
  * The first right-eye pixel column in the buffer for this frame's views (entries in BUFFER px,
  * through `rect`), or +∞ for one view (mono: every fragment is the left eye). With N > 2 views the
@@ -132,11 +235,12 @@ uniform vec4 dxrVidL;      // left eye's region: s0, t0, ds, dt (t = image rows,
 uniform vec4 dxrVidR;      // right eye's
 uniform vec2 dxrVidTexel;  // half a texel, per axis
 uniform float dxrVidSplit; // first right-eye pixel column in the buffer (1e9 = mono)
+uniform float dxrVidAlpha; // 1, except on a crossfade's outgoing ghost
 void main() {
   vec4 r = gl_FragCoord.x >= dxrVidSplit ? dxrVidR : dxrVidL;
   vec2 st = r.xy + vec2(vUv.x, 1.0 - vUv.y) * r.zw;
   st = clamp(st, r.xy + dxrVidTexel, r.xy + r.zw - dxrVidTexel);
-  gl_FragColor = vec4(texture2D(dxrVid, st).rgb, 1.0);
+  gl_FragColor = vec4(texture2D(dxrVid, st).rgb, dxrVidAlpha);
 }`;
 
 /**
@@ -154,6 +258,45 @@ export class VideoPlane {
     mesh.setIndices([0, 1, 2, 0, 2, 3]);
     mesh.update();
     this.mesh = mesh;
+    this.layer = viewer.app.scene.layers.getLayerById(pc.LAYERID_WORLD ?? 0);
+    this._split = NaN;
+    this._build();
+    /** A crossfade's outgoing quad: { mat, node, mi, tex, durationMs, ease, t0 }, or null. */
+    this.ghost = null;
+
+    this.video = null;
+    this.tex = null;
+    this.format = 'sbs';
+    this.fit = 'contain';
+    this.band = null;
+    this.vH = viewer.vH;
+    this._dirty = false;
+    this._lastT = -1;
+    this._rvfc = 0;
+    this._sizeKey = '';
+    this._onSeeked = () => (this._dirty = true);
+    /** The picture's on-screen rect (CSS px, canvas-relative, clipped), and who wants to know. */
+    this.rect = null;
+    this._rectKey = '';
+    this._planeSize = null;
+    this._rectListeners = new Set();
+    this._rectBox = null;
+    this._rectPlane = null;
+    this._texSource = null;
+    this._eyeA = 0; // the current video's eye aspect, as last sized (the ghost's geometry)
+    this._drawn = false; // sized + cropped for the current setSource's options (review N-B)
+    this._texW = 0;
+    this._texH = 0;
+    /** How many times the rect was recomputed (a test hook for the no-per-frame-allocation promise). */
+    this.rectComputes = 0;
+    /** Upload accounting (handle.setVideo(...).stats()). */
+    this.uploads = 0;
+    this.frames = 0;
+  }
+
+  /** The quad this plane draws the current video on: material, node (under the rig), instance. */
+  _build() {
+    const pc = this.pc;
     const mat = new pc.ShaderMaterial({
       uniqueName: 'inline3dVideoPlane',
       attributes: { vertex_position: pc.SEMANTIC_POSITION, vertex_texCoord0: pc.SEMANTIC_TEXCOORD0 },
@@ -161,40 +304,130 @@ export class VideoPlane {
       fragmentGLSL: FRAG,
     });
     mat.cull = pc.CULLFACE_NONE;
-    mat.setParameter('dxrVidSplit', 1e9);
+    mat.setParameter('dxrVidSplit', Number.isFinite(this._split) ? this._split : 1e9);
+    mat.setParameter('dxrVidAlpha', 1);
     mat.update();
     this.mat = mat;
     // Under the rig node: fixed relative to the eyes (see the header).
     this.node = new pc.GraphNode('inline3d-video');
-    viewer.rigNode.addChild(this.node);
-    const mi = new pc.MeshInstance(mesh, mat, this.node);
+    this.viewer.rigNode.addChild(this.node);
+    const mi = new pc.MeshInstance(this.mesh, mat, this.node);
     mi.cull = false;
     mi.visible = false;
     this.mi = mi;
-    this.layer = viewer.app.scene.layers.getLayerById(pc.LAYERID_WORLD ?? 0);
     this.layer.addMeshInstances([mi]);
+  }
 
-    this.video = null;
+  /**
+   * Hand the current quad, as it is, to the ghost that fades out over it, and build a fresh one for
+   * the incoming video. The ghost's texture is never uploaded again, so its <video> may go.
+   * (One exception, accepted: a WebGL context loss mid-fade re-uploads every texture on restore,
+   * and the ghost's element may have been released by then — the ghost is blank for what is left
+   * of the fade, under a second.)
+   */
+  _startFade({ durationMs, easing }) {
+    this._dropGhost();
+    this._unwatch();
+    const pc = this.pc;
+    const mat = this.mat;
+    // Colour: over. Alpha: ONE / ONE_MINUS_SRC_ALPHA, so the buffer stays opaque where the incoming
+    // quad is (1·a + 1·(1−a) = 1) and fades to the page where only the ghost is (its bars differ):
+    // plain SRC_ALPHA on alpha too would leave a² + (1−a) < 1 mid-fade, and the page would show
+    // through the picture.
+    // (The factors are straight-alpha colour + ONE on alpha: a premultiplied result into the
+    // premultipliedAlpha canvas. No guard: the 2.22.3 floor always has BlendState, and without it
+    // the ghost would silently be an opaque quad with depth test off.)
+    mat.blendState = new pc.BlendState(true, pc.BLENDEQUATION_ADD, pc.BLENDMODE_SRC_ALPHA, pc.BLENDMODE_ONE_MINUS_SRC_ALPHA,
+      pc.BLENDEQUATION_ADD, pc.BLENDMODE_ONE, pc.BLENDMODE_ONE_MINUS_SRC_ALPHA);
+    // The same plane as the incoming quad: drawn over it, never z-fighting it. The cost: for the
+    // fade's length the ghost also paints over opaque page geometry IN FRONT of the screen plane
+    // (a makeSbsMaterial quad, handle.engine content), which the incoming quad sits behind.
+    mat.depthTest = false;
+    mat.depthWrite = false;
+    mat.setParameter('dxrVidAlpha', 1);
+    mat.update();
+    const ease = typeof easing === 'function' ? easing : EASINGS[easing] || EASINGS.linear;
+    // S4: its size as a fraction of the window, so a refit (a new virtualDisplayHeight) or a resize
+    // during the fade keeps the outgoing picture where it was on screen instead of jumping.
+    // S4 / review R4: the ghost keeps its OWN geometry (eye aspect, fit, band) and is re-sized every
+    // tick against the current window, so a refit (a new virtualDisplayHeight) or a resize mid-fade
+    // keeps the outgoing picture where it was, without stretching it.
+    // The eye aspect cached when this quad was last sized, NOT read off the element now: for a URL
+    // source setVideo has already released the outgoing <video> (load() zeroes videoWidth), and a
+    // NaN aspect would stretch the ghost over the letterbox bars for the whole fade.
+    const geom = { a: this._eyeA, fit: this.fit, band: this.band };
+    this.ghost = { mat, node: this.node, mi: this.mi, tex: this.tex, durationMs, ease, t0: null, geom };
     this.tex = null;
-    this.format = 'sbs';
-    this.fit = 'contain';
-    this.vH = viewer.vH;
-    this._dirty = false;
-    this._lastT = -1;
-    this._rvfc = 0;
-    this._sizeKey = '';
-    this._split = NaN;
-    this._onSeeked = () => (this._dirty = true);
-    /** Upload accounting (handle.setVideo(...).stats()). */
-    this.uploads = 0;
-    this.frames = 0;
+    this._texSource = null;
+    this.video = null;
+    this._build();
+  }
+
+  _dropGhost() {
+    const g = this.ghost;
+    if (!g) return;
+    this.ghost = null;
+    this.layer?.removeMeshInstances?.([g.mi]);
+    g.mi.destroy?.(); // its reference on the shared mesh
+    g.node.parent?.removeChild?.(g.node);
+    g.tex?.destroy?.();
+    g.mat.destroy?.();
+  }
+
+  /** One engine tick of the fade: the ghost's opacity and eye split; gone at the end. */
+  _tickGhost(split) {
+    const g = this.ghost;
+    if (!g) return;
+    const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    if (g.t0 === null) g.t0 = now; // the clock starts on the incoming video's first drawn frame
+    const x = g.durationMs > 0 ? Math.min(1, Math.max(0, (now - g.t0) / g.durationMs)) : 1;
+    if (x >= 1) return this._dropGhost();
+    const s = videoPlaneSize({ boxAspect: this.viewer.boxAspect, eyeAspect: g.geom.a, vH: this.vH, fit: g.geom.fit, band: g.geom.band });
+    g.node.setLocalScale(s.w, s.h, 1);
+    // Review R2: a page easing may overshoot (easeOutBack) or throw. Clamp it (a negative
+    // ONE_MINUS_SRC_ALPHA would wreck the colours and the buffer's opacity), and a throw ends the
+    // fade instead of aborting every frame's draw until it would have finished.
+    let e;
+    try {
+      e = g.ease(x);
+    } catch (err) {
+      console.error('[inline3d/splat] setVideo easing threw; ending the crossfade:', err);
+      return this._dropGhost();
+    }
+    const alpha = Number.isFinite(e) ? 1 - Math.min(1, Math.max(0, e)) : 0;
+    g.mat.setParameter('dxrVidSplit', split);
+    g.mat.setParameter('dxrVidAlpha', alpha);
   }
 
-  /** Play `video` on the quad (a new element, format or fit). The element must have a frame. */
-  setSource(video, { format, fit, vH }) {
+  /** True while a crossfade is running. */
+  get fading() {
+    return !!this.ghost;
+  }
+
+  /**
+   * Play `video` on the quad (a new element, format or fit). The element must have a frame.
+   * `fade` ({ durationMs, easing }): dissolve from the video now on the quad instead of cutting.
+   * Returns true when a crossfade actually started.
+   */
+  setSource(video, { format, fit, vH, band = null }, fade = null) {
+    const newElement = video !== this.video;
+    // Review R1: only a video that has been DRAWN can be a ghost (it has a size, crop and a bound
+    // texture). Two swaps before the next frame make the middle one a cut, never a blank quad.
+    const fading = !!(fade && fade.durationMs > 0 && this.video && this.tex && this._drawn && newElement);
+    if (fading) this._startFade(fade);
+    else if (newElement) this._dropGhost(); // S1: a cut ends any fade still running
+    if (newElement) {
+      // S3: the new video has no on-screen rect until its first drawn frame.
+      this.rect = null;
+      this._rectKey = '';
+      this._planeSize = null;
+      this._eyeA = 0;
+      this._rectBox = null;
+    }
     this.format = format;
     this.fit = fit;
     this.vH = vH;
+    this.band = band;
     const r = eyeRegions(format);
     this.mat.setParameter('dxrVidL', r.L);
     this.mat.setParameter('dxrVidR', r.R);
@@ -208,6 +441,8 @@ export class VideoPlane {
     this._dirty = true;
     this.mat.update();
     this.mi.visible = true;
+    this._drawn = false; // the quad's regions/size for these options arrive with the next draw
+    return fading;
   }
 
   _watch() {
@@ -236,8 +471,24 @@ export class VideoPlane {
     const v = this.video;
     const w = v.videoWidth || 0;
     const h = v.videoHeight || 0;
-    if (this.tex && this.tex.width === w && this.tex.height === h) return;
+    // Our own record of the size the texture was made for: the real engine re-derives tex.width at
+    // upload from `video.width || videoWidth`, and `video.width` is the HTML attribute, so a
+    // <video width="640"> playing 1920 wide would never match and every swap would re-make it.
+    if (this.tex && this._texW === w && this._texH === h) {
+      // B1: same size, but maybe a different element (a cut between two same-size titles): the
+      // texture must be re-pointed, or it keeps sampling the old video.
+      if (this._texSource !== v) {
+        this.tex.setSource?.(v);
+        this._texSource = v;
+        this._lastT = v.currentTime;
+        this._dirty = false;
+        this.uploads++;
+      }
+      return;
+    }
     this.tex?.destroy?.();
+    this._texW = w;
+    this._texH = h;
     this.tex = new pc.Texture(this.viewer.app.graphicsDevice, {
       name: 'inline3d-video',
       width: Math.max(1, w),
@@ -251,6 +502,7 @@ export class VideoPlane {
       addressV: pc.ADDRESS_CLAMP_TO_EDGE,
     });
     this.tex.setSource?.(v);
+    this._texSource = v;
     this.mat.setParameter('dxrVid', this.tex);
     this.mat.setParameter('dxrVidTexel', [0.5 / Math.max(1, w), 0.5 / Math.max(1, h)]);
     this._lastT = v.currentTime;
@@ -268,14 +520,24 @@ export class VideoPlane {
       this._split = split;
       this.mat.setParameter('dxrVidSplit', split);
     }
+    this._tickGhost(split);
     const boxAspect = this.viewer.boxAspect;
-    const key = `${boxAspect}|${v.videoWidth}x${v.videoHeight}|${this.format}|${this.fit}|${this.vH}`;
+    const key = `${boxAspect}|${v.videoWidth}x${v.videoHeight}|${this.format}|${this.fit}|${this.vH}|${this.band}`;
     if (key !== this._sizeKey) {
       this._sizeKey = key;
       this._ensureTexture();
-      const s = videoPlaneSize({ boxAspect, eyeAspect: eyeAspect(this.format, v.videoWidth, v.videoHeight), vH: this.vH, fit: this.fit });
+      const a = eyeAspect(this.format, v.videoWidth, v.videoHeight);
+      this._eyeA = a;
+      this._drawn = true; // sized and cropped for the current options: it can be a ghost now
+      const s = videoPlaneSize({ boxAspect, eyeAspect: a, vH: this.vH, fit: this.fit, band: this.band });
       this.node.setLocalScale(s.w, s.h, 1);
+      this._planeSize = { w: s.w, h: s.h, W: this.vH * boxAspect, H: this.vH };
+      const crop = videoCrop({ boxAspect, eyeAspect: a, fit: this.fit, band: this.band });
+      const r = eyeRegions(this.format);
+      this.mat.setParameter('dxrVidL', cropRegion(r.L, crop));
+      this.mat.setParameter('dxrVidR', cropRegion(r.R, crop));
     }
+    this._updateRect();
     // A new frame: rVFC said so, a seek landed, or (no rVFC) the clock moved.
     const t = v.currentTime;
     if (this._dirty || (!this._rvfc && t !== this._lastT)) {
@@ -288,11 +550,48 @@ export class VideoPlane {
     }
   }
 
-  hide() {
-    this.mi.visible = false;
+  /** `cb(rect)` on every change of the on-screen rect; returns an unsubscribe. */
+  onRect(cb) {
+    // One entry per SUBSCRIPTION, not per function: the same `place` subscribed on two results (or
+    // twice) must not share an entry, or the first unsubscribe would silently remove both.
+    const sub = { cb };
+    this._rectListeners.add(sub);
+    return () => this._rectListeners.delete(sub);
+  }
+
+  /** The quad in CSS px of the canvas box, per frame; listeners hear only a change. */
+  _updateRect() {
+    const box = this.viewer.boxCss;
+    const s = this._planeSize;
+    if (!box || !s || !(box.w > 0) || !(box.h > 0)) return;
+    // N3: nothing moved, nothing allocated (the viewer replaces boxCss only when it re-measures).
+    if (box === this._rectBox && s === this._rectPlane) return;
+    this._rectBox = box;
+    this._rectPlane = s;
+    this.rectComputes++;
+    const r = videoScreenRect(s, box.w, box.h);
+    const key = `${r.x}|${r.y}|${r.width}|${r.height}`;
+    if (key === this._rectKey) return;
+    this._rectKey = key;
+    this.rect = r;
+    for (const sub of [...this._rectListeners]) {
+      // A microtask: after this draw, still inside the same rAF task (before paint), so controls
+      // move in the same frame and a throw is isolated. A callback that READS layout still forces
+      // layout inside the frame.
+      queueMicrotask(() => {
+        if (!this._rectListeners.has(sub)) return; // unsubscribed (or its video replaced) since
+        try {
+          sub.cb(r);
+        } catch (err) {
+          console.error('[inline3d/splat] onRectChange callback threw:', err);
+        }
+      });
+    }
   }
 
   destroy() {
+    this._rectListeners.clear();
+    this._dropGhost();
     this._unwatch();
     this.video = null;
     this.layer?.removeMeshInstances?.([this.mi]);

package/js/inline3d-splat.js

@@ -23,8 +23,9 @@ import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
 import { EyeCamera, EdgeFeather, cameraRigFromCamera } from './inline3d-three.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
 import { readSogCamera } from './inline3d-sog.js';
-import { resolveRevealOption, effectsNotOnSpark, validateEffectCall } from './inline3d-splat-effects.js';
+import { resolveRevealOption, effectsNotOnSpark } from './inline3d-splat-effects.js';
 import { applySplatPerf, splatPerfMeshOptions } from './inline3d-splat-perf.js';
+import { addSplatDeferred } from './inline3d-splat-deferred.js';
 import {
   toArray3,
   canvasNdc,
@@ -36,7 +37,6 @@ import {
   isStreamedUrl,
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
-  normalizeCameraPose,
   declareViewRig,
 } from './inline3d-splat-shared.js';
 import {
@@ -677,149 +677,6 @@ export function addSplat(wall, canvas, src, opts = {}) {
   return out;
 }
 
-/**
- * The `engine: 'playcanvas'` handle, returned SYNCHRONOUSLY like the Spark one.
- *
- * The adapter module is loaded on demand, so for a moment the handle exists before its
- * implementation does. Rather than make every caller await something new, the handle starts as
- * stubs that QUEUE: `exclude()` (which a product page calls on the very next line), `setPose`,
- * `setFocus`, `remove` — and the adapter replays the queue into the real implementation, on the
- * SAME object, the moment it arrives. `ready` resolves to this object, as it does on Spark.
- * Fields (`viewer`, `mesh`, `rig`, …) are null until then; `viewer` in particular appears one
- * module-load later than on Spark.
- */
-/** setRig's type/options shape, checked at the call before the adapter has loaded (it re-checks all of it). */
-function validateSetRigArgs(type, o) {
-  if (!['display', 'camera', 'auto'].includes(type)) {
-    throw new Error(`@displayxr/inline3d/splat: setRig("${type}") — expected 'display', 'camera' or 'auto'.`);
-  }
-  if (o !== undefined && (o === null || typeof o !== 'object')) {
-    throw new TypeError('@displayxr/inline3d/splat: setRig options must be an object.');
-  }
-}
-
-function addSplatDeferred(wall, canvas, src, opts) {
-  const pending = [];
-  const queue = (name) => (...args) => {
-    pending.push([name, args]);
-    return name === 'setFocus' ? out : undefined;
-  };
-  const page = opts.controls === 'page';
-  const pageOnly = (name) => () => {
-    throw new Error(
-      `@displayxr/inline3d/splat: ${name}() is not available with controls:'page' — the page owns the ` +
-        'camera. Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).',
-    );
-  };
-  // Before the adapter lands, a page calling setCameraPose every frame keeps ONE pending pose
-  // (validated now, so a bad call throws at its own line): last call wins, as it will after.
-  let pendingPose = null;
-  const out = {
-    backend: 'playcanvas',
-    engine: null,
-    viewer: null,
-    mesh: null,
-    frame: null,
-    camera: null,
-    rig: null,
-    perf: null,
-    setPose: page ? pageOnly('setPose') : queue('setPose'),
-    resetPose: page ? pageOnly('resetPose') : queue('resetPose'),
-    setCameraPose(matrixWorld, o) {
-      if (!page) {
-        throw new Error(
-          "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { controls:'page' }) — " +
-            'with the default controls the SDK owns the camera (use setPose).',
-        );
-      }
-      const pose = normalizeCameraPose(matrixWorld, o);
-      if (pendingPose) pendingPose[1] = [pose.matrixWorld, pose];
-      else pending.push((pendingPose = ['setCameraPose', [pose.matrixWorld, pose]]));
-      return out;
-    },
-    getCameraPose: () =>
-      pendingPose
-        ? {
-            matrixWorld: Float32Array.from(pendingPose[1][1].matrixWorld),
-            verticalFovDeg: pendingPose[1][1].verticalFovDeg,
-            near: pendingPose[1][1].near,
-            far: pendingPose[1][1].far,
-            convergence: pendingPose[1][1].convergence,
-          }
-        : null,
-    setFocus: queue('setFocus'),
-    // A swap requested before the first asset has landed runs once it has (the adapter's own
-    // setSource replaces this stub on the same object by then).
-    setSource: (...args) => out.ready.then(() => out.setSource(...args)),
-    prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
-    // A rig switch before the first asset has landed: validated now (controls:'page' and a bad
-    // type throw at the call's own line), applied once it has.
-    setRig: page
-      ? pageOnly('setRig')
-      : (type, o) => {
-          validateSetRigArgs(type, o);
-          return out.ready.then(() => out.setRig(type, o));
-        },
-    // A video before the first asset has landed: controls:'page' throws at the call's own line,
-    // the rest is validated by the adapter's setVideo, which runs once the asset is on screen.
-    setVideo: page ? pageOnly('setVideo') : (src, o) => out.ready.then(() => out.setVideo(src, o)),
-    // Effects before the adapter has loaded: validated NOW (a bad call throws at its own line),
-    // then run once the first asset is on screen.
-    playEffect: (name, o) => {
-      validateEffectCall(name, o, 'play');
-      return out.ready.then(() => out.playEffect(name, o));
-    },
-    setEffect: (name, params) => {
-      validateEffectCall(name, params, 'set');
-      pending.push(['setEffect', [name, params]]);
-      return out;
-    },
-    stopEffect: queue('stopEffect'),
-    // A layer-rig request before the adapter has loaded: queued, replayed in order once it has
-    // (it needs no asset, only the engine's layers — which the adapter resolves lazily).
-    setLayerRig: (...args) => {
-      pending.push(['setLayerRig', args]);
-      return out;
-    },
-    setLayerRigOptions: (...args) => {
-      pending.push(['setLayerRigOptions', args]);
-      return out;
-    },
-    layerRigState: () => ({ display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'the PlayCanvas adapter has not loaded yet', viewerDistance: 0.6, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null }),
-    makeSbsMaterial: () => {
-      throw new Error('@displayxr/inline3d/splat: makeSbsMaterial() needs the engine — call it after `await handle.ready`.');
-    },
-    effects: () => [],
-    getFocus: () => null,
-    // A plain data slot the adapter reads at call time, so a callback assigned on the very next
-    // line after addSplat — before the module has loaded — is the one that fires.
-    onFocusChange: null,
-    pick: () => null,
-    // Splat accounting (resident / budget / first frame); null until the adapter has loaded.
-    stats: () => null,
-    remove: queue('remove'),
-    exclude: queue('exclude'),
-    unexclude: queue('unexclude'),
-  };
-  // `firstWoven` exists from the first line, like every other field a page reads right away; the
-  // adapter settles it with the core handle's own once the module has loaded.
-  out.firstWoven = new Promise((resolve) => {
-    out._resolveFirstWoven = resolve;
-  });
-  // The ONE owner of `ready`: the adapter returns its load promise and never touches this field.
-  out.ready = import('./inline3d-splat-playcanvas.js')
-    .then((m) => m.attachPlayCanvasSplat(out, wall, canvas, src, opts, pending))
-    .catch((err) => {
-      // The adapter warns about its own load failures; this is for the module not arriving.
-      if (!out.viewer) console.warn('[inline3d/splat] engine:playcanvas failed to start', err);
-      if (out._resolveFirstWoven) {
-        out._resolveFirstWoven(Object.freeze({ woven: false, confirmed: false, reason: 'layer-failed', ms: 0 }));
-        delete out._resolveFirstWoven;
-      }
-      throw err;
-    });
-  return out;
-}
 
 /**
  * Percentile bounds from the loaded splats — the fallback when no sidecar was supplied.