@displayxr/inline3d 1.27.0 → 1.29.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

@@ -245,6 +245,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
     idleSpin,
     renderScale,
     feather,
+    logTag: '[inline3d/splat]',
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   // Spark renders through the ordinary three.js pipeline, so splats and meshes co-exist and
@@ -411,6 +412,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
     },
     effects: () => [],
   };
+  // The per-eye buffer scale in force (the request times the device-limit clamp,
+  // ./inline3d-buffer-limit.js) and the request as given. Accessors, so they stay live.
+  Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
+  Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
 
   // `src` may be a URL or the bytes themselves.
   //

package/js/inline3d-viewer.js

@@ -64,6 +64,14 @@ import {
   MONO_NEAR,
   MONO_FAR,
 } from './inline3d-splat-shared.js';
+import {
+  glBufferLimits,
+  clampEyeBuffer,
+  clampWarning,
+  bufferScale,
+  scaleViewport,
+  mismatchWarning,
+} from './inline3d-buffer-limit.js';
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // NaN/Infinity into a transform silently blanks the tile — three propagates it into the
@@ -283,6 +291,14 @@ export class SceneViewer {
     this.depthLimit = depthLimit;
     this.fitSweep = fitSweep;
     this.renderScale = renderScale;
+    // The device-limit clamp on the backing store (./inline3d-buffer-limit.js): the factor _resize
+    // last had to apply on top of renderScale, 1 when the request fit. effectiveRenderScale reports
+    // the product. Warned once per viewer (one viewer per handle).
+    this._bufClamp = 1;
+    this._warnedBufClamp = false;
+    this._warnedBufMismatch = false;
+    /** Prefix for this viewer's warnings; ./splat and ./model set their own. */
+    this.logTag = opts.logTag || '[inline3d/viewer]';
     this.pitchLimit = pitchLimit;
     this.idleSpin = idleSpin;
 
@@ -711,10 +727,13 @@ export class SceneViewer {
 
     // Validated: this frame WILL draw over everything it clears.
     const r = this.renderer;
+    // getViewport() splits canvas.width; a drawing buffer the browser clamped behind our back
+    // (bufferScale().mismatch) gets the same split mapped onto its real size, never canvas.width/2.
+    const b = this._bufScale();
     r.clear();
     r.setScissorTest(true);
     for (let i = 0; i < views.length; i++) {
-      const vp = vps[i];
+      const vp = scaleViewport(vps[i], b.sx, b.sy);
       r.setViewport(vp.x, vp.y, vp.width, vp.height);
       r.setScissor(vp.x, vp.y, vp.width, vp.height);
       if (eye) {
@@ -753,7 +772,8 @@ export class SceneViewer {
       this._tick();
       const r = this.renderer;
       r.clear();
-      r.setViewport(0, 0, this.canvas.width, this.canvas.height);
+      const b = this._bufScale();
+      r.setViewport(0, 0, b.w, b.h);
       r.render(this.scene, this.monoCamera);
     };
     this._monoRaf = requestAnimationFrame(loop);
@@ -849,9 +869,11 @@ export class SceneViewer {
     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;
+    // A resize between the cache and the replay changes the buffer, not the split. The cache is in
+    // canvas-attribute px (getViewport's space); the target is the REAL drawing buffer.
+    const b = this._bufScale();
+    const sx = g.bufW > 0 && b.w ? b.w / g.bufW : 1;
+    const sy = g.bufH > 0 && b.h ? b.h / g.bufH : 1;
     const scaled = sx !== 1 || sy !== 1;
     r.clear();
     r.setScissorTest(true);
@@ -903,7 +925,8 @@ export class SceneViewer {
     if (this._mode === 'mono') {
       const r = this.renderer;
       r.clear();
-      r.setViewport(0, 0, this.canvas.width, this.canvas.height);
+      const b = this._bufScale();
+      r.setViewport(0, 0, b.w, b.h);
       r.render(this.scene, this.monoCamera);
       return;
     }
@@ -955,18 +978,71 @@ export class SceneViewer {
     const box = this.canvas.getBoundingClientRect();
     if (box.width < 1 || box.height < 1) return;
     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));
-    const bufW = this._mode === 'mono' ? w : w * 2;
+    // Clamp to the device's GL limits BEFORE sizing (./inline3d-buffer-limit.js): a store past
+    // MAX_TEXTURE_SIZE is silently clamped by the browser while getViewport() keeps splitting
+    // canvas.width, which puts the eye boundary off-centre in the woven buffer.
+    const c = clampEyeBuffer(
+      Math.max(1, Math.round(box.width * dpr)),
+      Math.max(1, Math.round(box.height * dpr)),
+      glBufferLimits(this._gl()),
+      { cols: this._mode === 'mono' ? 1 : 2 },
+    );
+    this._noteClamp(c);
+    const bufW = c.bufW;
+    const h = c.bufH;
     // 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
+    if (el.width === bufW && el.height === h) {
+      this._bufScale(); // observer fired, geometry didn't move; still name a browser-side clamp
+      return;
+    }
     this.renderer.setSize(bufW, h, false);
+    this._bufScale(); // warns once if the browser clamped anyway
     this._repaintAfterResize();
   }
 
+  /**
+   * The renderScale actually in force: the request (`renderScale`) times the device-limit clamp
+   * the last resize applied. Equal to renderScale wherever the store fits.
+   */
+  get effectiveRenderScale() {
+    return this.renderScale * this._bufClamp;
+  }
+
+  _gl() {
+    try {
+      return this.renderer?.getContext?.() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Record a resize's clamp; warn once per viewer the first time the device limit bites. */
+  _noteClamp(c) {
+    this._bufClamp = c.scale;
+    if (c.clamped && !this._warnedBufClamp) {
+      this._warnedBufClamp = true;
+      console.warn(clampWarning(this.logTag, c, this.renderScale));
+    }
+  }
+
+  /**
+   * The drawing buffer's real size and its ratio to canvas.width/height (the space getViewport()
+   * reports in). Identity unless the browser clamped a store the limit query did not predict;
+   * warns once per viewer when it did.
+   */
+  _bufScale() {
+    const el = this.renderer.domElement || this.canvas;
+    const b = bufferScale(el, this._gl());
+    if (b.mismatch && !this._warnedBufMismatch) {
+      this._warnedBufMismatch = true;
+      console.warn(mismatchWarning(this.logTag, el, b));
+    }
+    return b;
+  }
+
   /** Damping + idle turntable. Called once per rendered frame, 3D or mono. */
   _tick() {
     const t = now();