@displayxr/inline3d 1.28.0 → 1.29.0

package/js/inline3d-splat-playcanvas.js

@@ -1915,6 +1915,9 @@ export class PlayCanvasSplatViewer {
     const box = this.canvas.getBoundingClientRect();
     const aspect = box.height > 0 ? box.width / box.height : 1;
     this.boxAspect = aspect; // setVideo's plane reads it per frame (no layout read in the draw)
+    // and this, for its on-screen rect: a NEW object only when the size changed (the plane's rect
+    // check compares identity, so an unchanged frame allocates nothing).
+    if (!this.boxCss || this.boxCss.w !== (box.width || 0) || this.boxCss.h !== (box.height || 0)) this.boxCss = { w: box.width || 0, h: box.height || 0 };
     if (this.mono.capture) {
       captureProjection(this.mono.capture, aspect, this.mono.near, this.mono.far, this.mono.proj, this.captureFit);
       if (this.captureFit !== 'height') {
@@ -3125,6 +3128,12 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // copy a getter's value once.
   Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
   Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
+  // setVideo's current element: the <video> the plane is SHOWING (not one still waiting for its first
+  // frame), else null. Read-only. A player attached to this handle (./player attachPlayer) reads it
+  // to notice another setVideo taking the slot, which no event reports.
+  Object.defineProperty(out, 'videoElement', { get: () => (vid && vid.on ? vid.el : null), enumerable: true, configurable: true });
+  // The tile's canvas, for page chrome that sits beside it (attachPlayer's controls are its siblings).
+  Object.defineProperty(out, 'canvas', { value: canvas, enumerable: true, configurable: true });
   // The current eye offset (after the unit-disc clamp), a fresh object per read.
   Object.defineProperty(out, 'viewOffset', {
     get: () => ({ x: viewer._viewOffset[0], y: viewer._viewOffset[1] }),
@@ -4405,7 +4414,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * handle.setVideo(src, options) — play a stereo video on THIS handle: no new canvas, layer or
    * session. The splat is hidden and a screen-locked plane on the display rig shows the video, each
    * eye its own half (sbs: left/right, tb: top/bottom); flat (mono), the left half at full
-   * resolution. Applies on the first frame the video has. Resolves to `{ video, remove(), stats() }`;
+   * resolution. Applies on the first frame the video has; `transition: 'crossfade'` (with
+   * `durationMs`, `easing`) dissolves from a video already on the plane, on the GPU, and is a cut
+   * from the splat. Resolves to `{ video, transition, remove(), stats() }`;
    * the page drives transport through `video`. setVideo(null) exits and restores the splat, the rig
    * and its declaration exactly as they were. Throws during an in-flight setSource.
    */
@@ -4432,7 +4443,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     if (owned ? r.autoplay !== false : r.autoplay === true) autoplay(el);
     // The guard state is taken NOW (setSource / setRig refuse from this call on), the pixels change
     // on the first frame the video has.
-    const state = { seq, el, owned, format: r.format, fit: r.fit, vH: r.vH ?? bootFraming.vH, on: false, saved: null, pending: true };
+    const state = { seq, el, owned, format: r.format, fit: r.fit, band: r.band, vH: r.vH ?? bootFraming.vH, on: false, saved: null, pending: true, rectOffs: new Set() };
     if (!prev || !prev.on) vid = state; // a pending one it supersedes is cancelled above
     return first
       .catch(() => null)
@@ -4444,6 +4455,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
           // Another video on screen: keep ITS snapshot (the pre-video state), swap the source.
           state.saved = live.saved;
           state.on = true;
+          // S2: the plane outlives this swap; the replaced video's rect subscriptions go with it.
+          for (const off of live.rectOffs) off();
+          live.rectOffs.clear();
           if (live.owned && live.el !== el) releaseOwned(live.el);
           if (state.vH !== live.vH) {
             viewer.vH = state.vH;
@@ -4454,13 +4468,42 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         } else enterVideo(state);
         vid = state;
         state.pending = false;
+        // A crossfade only dissolves between two videos: from the splat (entry) it is a cut.
+        const fade = live && r.transition.type === 'crossfade' && r.transition.durationMs > 0 ? r.transition : null;
         viewer._videoPlane ||= new VideoPlane(viewer);
-        viewer._videoPlane.setSource(el, { format: state.format, fit: state.fit, vH: state.vH });
+        const faded = viewer._videoPlane.setSource(el, { format: state.format, fit: state.fit, vH: state.vH, band: state.band }, fade);
         const plane = viewer._videoPlane;
         return Object.freeze({
           video: el,
           format: state.format,
           fit: state.fit,
+          /** The letterbox band's aspect, or null. */
+          band: state.band,
+          /**
+           * Where the picture is on screen, in CSS px from the canvas's top-left, clipped to the
+           * canvas: `{ x, y, width, height }`. The bars are the canvas minus this. Null once
+           * another setVideo replaced this one, or before the first drawn frame.
+           */
+          get rect() {
+            return vid === state && viewer._videoPlane === plane ? plane.rect : null;
+          },
+          /** Called with the new rect whenever it changes (resize, band, a new size). Returns an unsubscribe. */
+          onRectChange(cb) {
+            if (typeof cb !== 'function') throw new TypeError('@displayxr/inline3d/splat: onRectChange(cb) — expected a function.');
+            if (vid !== state) return () => {};
+            // S2: never outlives this video — every subscription is dropped at the swap that
+            // replaces it (and with the plane on setVideo(null)).
+            // Each subscription is its own entry on the plane, so calling this twice is harmless.
+            const off = plane.onRect(cb);
+            const unsubscribe = () => {
+              off();
+              state.rectOffs.delete(unsubscribe);
+            };
+            state.rectOffs.add(unsubscribe);
+            return unsubscribe;
+          },
+          /** What this swap did: 'crossfade' only when a fade actually started, else 'cut'. */
+          transition: faded ? 'crossfade' : 'cut',
           /** Exit (setVideo(null)) — a no-op once another setVideo replaced this one. */
           remove: () => (vid === state ? setVideo(null) : Promise.resolve(null)),
           /** Upload accounting: frames drawn with the plane up, and texture uploads (new frames). */

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]);