@displayxr/inline3d 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.18.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive: a page that never
+calls `setVideo` renders the same pixels.
+
+### Added
+
+- **`handle.setVideo(src, options?)`** (#36): a stereo video on the persistent PlayCanvas splat
+  handle, with no second canvas, layer or session. This is for pages that keep one woven canvas for
+  the whole app, where a fresh `addVideo` canvas after a navigation is the side-by-side flash.
+  - `src` is a URL (an SDK-owned `<video>`, autoplaying) or your `HTMLVideoElement`. Options:
+    `format: 'sbs' | 'tb' | 'mono'`, `fit: 'contain' | 'cover'`, `rig: 'display'`,
+    `virtualDisplayHeight`, `loop`, `muted`, `autoplay`.
+  - It resolves on the video's first frame to `{ video, format, fit, remove(), stats() }`. The page
+    drives transport through `video`.
+  - The splat is hidden and a screen-locked plane on the display rig shows the video. Each eye
+    samples only its own half. Flat (mono), it shows the left half at full resolution.
+  - Upload is gated on `requestVideoFrameCallback`. The colour is `addVideo`'s own.
+  - `setVideo(null)` restores the splat, the pose, the lens and the declared view rig exactly.
+  - It throws during an in-flight `setSource`. While a video is on, `setSource` rejects and
+    `setRig` throws. `controls:'page'` throws.
+  - Gates, on a real GPU: each eye shows 0 px of the other half, exit renders **MAE 0.0000**
+    against the pre-video frame with the same declared rig, and colour matches `addVideo`'s paint
+    at MAE 0.003. At 3840×1080 the upload runs 29.9/s with `texImage2D` at p50 0.1 ms, and 0 video
+    frames drop on a 120 Hz panel.
+  - See [`docs/playcanvas-adapter.md` § setVideo](docs/playcanvas-adapter.md#setvideo--a-stereo-video-on-the-persistent-handle-36).
+
 ## 1.17.0 — 2026-09-24
 
 Touches the **preview tier** (`./model` and `./splat`, `engine: 'playcanvas'` only). The default look

package/README.md

@@ -48,7 +48,9 @@ engine's knobs) — and adds `setSource(src, { fadeMs })` (crossfading asset swa
 tilt-and-relax orbit, `handle.engine` (the engine objects, for advanced pages) and
 `handle.setRig('display' | 'camera' | 'auto')`: a live, reversible rig switch, so one persistent tile
 can show a glTF under `handle.engine.root` exactly as `addModel` would and then go back to the photo's
-capture rig ([§setRig](docs/playcanvas-adapter.md#setrig--switching-between-the-display-rig-and-the-camera-rig-36)). It needs the
+capture rig ([§setRig](docs/playcanvas-adapter.md#setrig--switching-between-the-display-rig-and-the-camera-rig-36)), and
+`handle.setVideo(src, { format: 'sbs' | 'tb' | 'mono' })`: a stereo video on that same tile, each eye
+its own half, with no second canvas ([§setVideo](docs/playcanvas-adapter.md#setvideo--a-stereo-video-on-the-persistent-handle-36)). It needs the
 optional peer `playcanvas` (`>=2.22.3 <3`) and reads `.sog`, `.ply` and a Streamed-SOG
 `lod-meta.json`. **Spark stays the default**; a page that never passes `engine` never loads
 `playcanvas`. What differs, and why: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md).

package/js/inline3d-splat-playcanvas.js

@@ -63,6 +63,7 @@ import {
   particleSpan,
 } from './inline3d-splat-effects.js';
 import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
+import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR } from './inline3d-splat-video.js';
 import {
   clamp,
   finite,
@@ -664,6 +665,11 @@ export class PlayCanvasSplatViewer {
     this.orbitMaxDeg = orbitMaxDeg;
     this.orbitEase = { drag: orbitEase.drag ?? ORBIT_TAU_DRAG_S, rest: orbitEase.rest ?? ORBIT_TAU_REST_S };
     this._orbitMode = null;
+    /** handle.setVideo: orbit/zoom input ignored while a video plane is on. */
+    this.inputLocked = false;
+    /** handle.setVideo's plane (./inline3d-splat-video.js) while a video is on, else null. */
+    this._videoPlane = null;
+    this.boxAspect = 1;
     this.featherPx = feather > 0 ? feather : 0;
     this.captureFit = captureFit;
     /** Called when the capture camera's vertical FOV changes (captureFit 'cover' on a resize). */
@@ -1024,6 +1030,8 @@ export class PlayCanvasSplatViewer {
     }
     this._live?.destroy();
     this._live = null;
+    this._videoPlane?.destroy();
+    this._videoPlane = null;
     try {
       this.app?.destroy();
     } catch (err) {
@@ -1544,6 +1552,7 @@ export class PlayCanvasSplatViewer {
   _updateMonoProjection() {
     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)
     if (this.mono.capture) {
       captureProjection(this.mono.capture, aspect, this.mono.near, this.mono.far, this.mono.proj, this.captureFit);
       if (this.captureFit !== 'height') {
@@ -1652,6 +1661,8 @@ export class PlayCanvasSplatViewer {
       }
     }
     this._updateFeather(entries[0].width * sx, entries[0].height * sy);
+    // handle.setVideo's plane: size, eye split, and a new frame's upload (./inline3d-splat-video.js).
+    this._videoPlane?.beforeDraw(entries, rect);
     app.tick(now());
     this._afterTick();
     return true;
@@ -1859,6 +1870,7 @@ export class PlayCanvasSplatViewer {
     let restYaw = 0;
     let restPitch = 0;
     this._onDown = (ev) => {
+      if (this.inputLocked) return; // handle.setVideo: a screen-locked plane has nothing to orbit
       dragging = true;
       startX = ev.clientX;
       startY = ev.clientY;
@@ -1893,6 +1905,7 @@ export class PlayCanvasSplatViewer {
       el.releasePointerCapture?.(ev.pointerId);
     };
     this._onWheel = (ev) => {
+      if (this.inputLocked) return;
       ev.preventDefault();
       let px = ev.deltaY;
       if (ev.deltaMode === 1) px *= WHEEL_LINE_PX;
@@ -2210,6 +2223,10 @@ export const SET_RIG_TYPES = Object.freeze(['display', 'camera', 'auto']);
 const SET_RIG_FITS = ['contain', 'cover', 'height', 'none'];
 let warnedSetRigKeys = false;
 
+const VIDEO_BUSY = (what) =>
+  `@displayxr/inline3d/splat: ${what}() while a video is on — call handle.setVideo(null) first ` +
+  '(the video holds the display rig and hides the splat until it exits).';
+
 const PAGE_SETRIG_ERROR =
   "@displayxr/inline3d/splat: setRig() is not available with controls:'page' — the page owns the " +
   'camera (its camera IS the rig). Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).';
@@ -2423,6 +2440,12 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   const livePrepared = new Set();
   /** The asset on screen: its resource, kind, the pick data it keeps. */
   let current = null; // { asset, entity, res, kind, streamedBounds, alpha8, pickCentres }
+  // handle.setVideo (below). Declared up here: a remove() queued before load runs during attach.
+  let vid = null;
+  let videoSeq = 0;
+  /** The pending setVideo's canceller (a newer call, setVideo(null) or remove() supersedes it). */
+  let cancelPendingVideo = null;
+  let warnedAutoplayMuted = false;
 
   Object.assign(out, {
     backend: 'playcanvas',
@@ -2491,6 +2514,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     setSource,
     prepareSource,
     setRig,
+    setVideo,
     /**
      * Play a transition effect (inflate, deflate, sweep, dissolve, fade, pulse, custom) — see
      * docs/splat-effects.md. Validated now; runs once the first asset is on screen. Resolves
@@ -2517,6 +2541,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     effects: () => (fx ? fx.list() : []),
     remove() {
       removed = true;
+      dropVideo(); // before the app goes: the plane's rVFC, and a <video> this handle made
       current = null;
       for (const p of [...livePrepared]) p.dispose();
       fx?.dispose();
@@ -2727,6 +2752,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let declaredDisplay = pageMode ? 'page' : 'shorthand';
   function pushViewRig(force) {
     if (pageMode) return; // pageTick declares the rig every frame
+    if (vid?.on) return; // setVideo holds the display rig; exit re-declares what was there
     if (!out.rig || out.rig.type !== 'camera') return;
     const pose = viewer.mono.pose;
     const f = viewer.getFocus();
@@ -2841,6 +2867,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     if (pageMode || focusInput === false || unbindFocusInput) return;
     unbindFocusInput = bindFocusGestures(canvas, {
       onDoubleClick: (e) => {
+        if (vid?.on) return false; // a video plane: nothing to focus on
         const m = pickModel(e.clientX, e.clientY);
         if (!m) return false;
         out.rig.focus = m;
@@ -3239,6 +3266,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    */
   function setRig(type, o = {}) {
     const req = validateSetRig(type, o, pageMode);
+    if (vid) throw new Error(VIDEO_BUSY('setRig'));
     const seq = ++rigSeq;
     return first.then(async () => {
       if (removed || seq !== rigSeq || !current) return out;
@@ -3312,6 +3340,231 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return out;
   });
 
+  // ── handle.setVideo: a stereo video on this handle (docs/playcanvas-adapter.md §setVideo) ──
+  /**
+   * The video state: null = no video. `on` once the plane is up (the splat hidden, the display rig
+   * declared); `saved` is everything the entry changed, restored exactly by setVideo(null).
+   */
+  // (state: `vid`, `videoSeq`, `cancelPendingVideo` — declared with `current`, above: remove() reads them)
+
+  /** The <video> for a URL: made here, owned (and released) by this handle. */
+  function makeVideoElement(url) {
+    const v = document.createElement('video');
+    v.crossOrigin = 'anonymous'; // WebGL refuses a tainted frame; same-origin is unaffected
+    v.playsInline = true;
+    v.preload = 'auto';
+    v.src = url;
+    return v;
+  }
+  /** Let go of a <video> this handle made: stop it and free its decoder. */
+  function releaseOwned(v) {
+    try {
+      v.pause();
+      v.removeAttribute('src');
+      v.load();
+    } catch {
+      /* already gone */
+    }
+  }
+  /** Resolves once `v` has a current frame (readyState ≥ 2); rejects on error or cancel. */
+  function waitForFrame(v, seq) {
+    return new Promise((resolve, reject) => {
+      const off = () => {
+        v.removeEventListener('loadeddata', ok);
+        v.removeEventListener('error', bad);
+        if (cancelPendingVideo === cancel) cancelPendingVideo = null;
+      };
+      const ok = () => (off(), resolve());
+      const bad = () => {
+        off();
+        const e = v.error;
+        reject(new Error(`@displayxr/inline3d/splat: setVideo — the video failed to load${e ? ` (${e.message || `code ${e.code}`})` : ''}.`));
+      };
+      const cancel = () => {
+        off();
+        const err = new Error('@displayxr/inline3d/splat: setVideo — superseded by a later setVideo / remove() before its first frame.');
+        err.name = 'AbortError';
+        reject(err);
+      };
+      cancelPendingVideo = cancel;
+      if (seq !== videoSeq) return cancel();
+      if ((v.readyState || 0) >= 2 && v.videoWidth > 0) return ok();
+      v.addEventListener('loadeddata', ok);
+      v.addEventListener('error', bad);
+    });
+  }
+  function autoplay(v) {
+    const p = v.play?.();
+    if (!p || typeof p.catch !== 'function') return;
+    p.catch((err) => {
+      // No user gesture yet: the browser allows a MUTED play. The page unmutes on its next gesture.
+      if (err?.name !== 'NotAllowedError' || v.muted) return;
+      v.muted = true;
+      if (!warnedAutoplayMuted) {
+        warnedAutoplayMuted = true;
+        console.info('[inline3d/splat] setVideo: autoplay with sound was refused (no user gesture yet) — playing MUTED; set video.muted = false on a gesture.');
+      }
+      v.play().catch(() => {});
+    });
+  }
+
+  /** Everything the entry changes, for an exact restore. */
+  function snapshotForVideo() {
+    const v = viewer;
+    const entity = current?.entity || null;
+    return {
+      entity,
+      splatEnabled: entity ? entity.enabled : null,
+      vH: v.vH,
+      idleSpin: v.idleSpin,
+      mono: { fov: v.mono.fov, near: v.mono.near, far: v.mono.far, pose: Float64Array.from(v.mono.pose), capture: v.mono.capture },
+      pose: {
+        _yaw: v._yaw, _pitch: v._pitch, _targetYaw: v._targetYaw, _targetPitch: v._targetPitch,
+        _zoom: v._zoom, _targetZoom: v._targetZoom, _depthOffset: v._depthOffset,
+        _focusSettled: v._focusSettled, _focusRecentres: v._focusRecentres, _orbitMode: v._orbitMode, _lastInput: v._lastInput,
+      },
+      focus: { ...v._focus },
+      targetFocus: { ...v._targetFocus },
+      viewRig: out.viewRig,
+      declaredDisplay,
+      lastConvergence,
+    };
+  }
+
+  /** Enter: the splat hidden, the display camera + rig, the plane up. One task: one frame sees it all. */
+  function enterVideo(state) {
+    const v = viewer;
+    state.saved = snapshotForVideo();
+    if (state.saved.entity) state.saved.entity.enabled = false;
+    v.inputLocked = true;
+    v.idleSpin = 0;
+    v.vH = state.vH;
+    if (v.mono.capture) v.useDisplayCamera(); // camera rig → the display rig's mono camera
+    else {
+      v._placeMonoForFit();
+      v._updateMonoProjection();
+    }
+    declareDisplay({ vH: state.vH });
+    state.on = true;
+  }
+
+  /** Exit: put back exactly what enterVideo changed, and the declaration that was there. */
+  function exitVideo(state) {
+    const v = viewer;
+    const s = state.saved;
+    v._videoPlane?.destroy();
+    v._videoPlane = null;
+    if (s.entity) s.entity.enabled = s.splatEnabled;
+    v.vH = s.vH;
+    v.idleSpin = s.idleSpin;
+    Object.assign(v.mono, { fov: s.mono.fov, near: s.mono.near, far: s.mono.far, pose: s.mono.pose, capture: s.mono.capture });
+    Object.assign(v, s.pose);
+    v._focus = { ...s.focus };
+    v._targetFocus = { ...s.targetFocus };
+    v._updateMonoProjection(); // recomputed, not copied: the box may have been resized meanwhile
+    v._applyTransform();
+    v.inputLocked = false;
+    lastConvergence = s.lastConvergence;
+    if (declaredDisplay !== s.declaredDisplay) {
+      if (s.declaredDisplay === 'shorthand') {
+        // The boot shorthand cannot be restored: its explicit form (what it is shorthand for).
+        declaredDisplay = null;
+        declareDisplay({ vH: bootFraming.vH });
+      } else {
+        declaredDisplay = s.declaredDisplay;
+        out.viewRig = s.viewRig;
+        handle?.setViewRig?.(out.viewRig);
+      }
+    } else out.viewRig = s.viewRig;
+    lastConvergence = s.lastConvergence;
+    state.on = false;
+  }
+
+  /** Tear the video down now (setVideo(null) / remove()). */
+  function dropVideo() {
+    videoSeq++;
+    cancelPendingVideo?.();
+    const state = vid;
+    vid = null;
+    if (!state) return;
+    if (state.on) exitVideo(state);
+    if (state.owned) releaseOwned(state.el);
+  }
+
+  /**
+   * 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() }`;
+   * 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.
+   */
+  function setVideo(src, o = {}) {
+    if (src === null || src === undefined) {
+      if (pageMode) throw new Error(PAGE_VIDEO_ERROR);
+      dropVideo();
+      return Promise.resolve(null);
+    }
+    const r = validateSetVideo(src, o, pageMode);
+    if (sourceInFlight > 0) {
+      throw new Error(
+        '@displayxr/inline3d/splat: setVideo() during an in-flight setSource() — await the swap first ' +
+          '(a video and a transition cannot share the tile).',
+      );
+    }
+    const seq = ++videoSeq;
+    cancelPendingVideo?.();
+    const prev = vid;
+    const owned = typeof r.src === 'string';
+    const el = owned ? makeVideoElement(r.src) : r.src;
+    if (r.loop !== undefined) el.loop = r.loop;
+    if (r.muted !== undefined) el.muted = r.muted;
+    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 };
+    if (!prev || !prev.on) vid = state; // a pending one it supersedes is cancelled above
+    return first
+      .catch(() => null)
+      .then(() => waitForFrame(el, seq))
+      .then(() => {
+        if (removed || seq !== videoSeq || !viewer.app) throw Object.assign(new Error('@displayxr/inline3d/splat: setVideo — superseded.'), { name: 'AbortError' });
+        const live = vid && vid.on ? vid : null;
+        if (live) {
+          // Another video on screen: keep ITS snapshot (the pre-video state), swap the source.
+          state.saved = live.saved;
+          state.on = true;
+          if (live.owned && live.el !== el) releaseOwned(live.el);
+          if (state.vH !== live.vH) {
+            viewer.vH = state.vH;
+            viewer._placeMonoForFit();
+            viewer._updateMonoProjection();
+            declareDisplay({ vH: state.vH });
+          }
+        } else enterVideo(state);
+        vid = state;
+        state.pending = false;
+        viewer._videoPlane ||= new VideoPlane(viewer);
+        viewer._videoPlane.setSource(el, { format: state.format, fit: state.fit, vH: state.vH });
+        const plane = viewer._videoPlane;
+        return Object.freeze({
+          video: el,
+          format: state.format,
+          fit: state.fit,
+          /** 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). */
+          stats: () => ({ frames: plane.frames, uploads: plane.uploads }),
+        });
+      })
+      .catch((err) => {
+        // Failed or superseded before it showed: nothing changed on screen; free what we made.
+        if (vid === state) vid = null;
+        if (owned && (!vid || vid.el !== el)) releaseOwned(el);
+        throw err;
+      });
+  }
+
   // ── prepareSource: load the next asset in the background, for a setSource with no load ──
   /**
    * Fetch, decode and upload `src` now, without rendering it: the engine's load (its own unpack
@@ -3453,6 +3706,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   // ── setSource: swap the asset — a cut, a crossfade, or a transition ──
   let sourceGen = 0;
+  /** setSource calls between their call and their settle (setVideo refuses to start inside one). */
+  let sourceInFlight = 0;
   let pendingSwap = null;
   /** setSource's crossfade FALLBACK: the coverage remap on one entity (null clears it). */
   const setFade = (entity, k) => fx?.setInternal(entity, 'xfade', k === null ? null : { k });
@@ -3469,7 +3724,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * `onFocusChange` fires); the pose is kept unless `resetPose: true`. A newer call supersedes an
    * older one still loading. Resolves to the handle once the swap has finished.
    */
-  async function setSource(next, o = {}) {
+  function setSource(next, o = {}) {
+    // A video owns the tile (display rig, splat hidden) until setVideo(null).
+    if (vid) return Promise.reject(new Error(VIDEO_BUSY('setSource')));
+    sourceInFlight++;
+    return setSourceNow(next, o).finally(() => sourceInFlight--);
+  }
+  async function setSourceNow(next, o = {}) {
     const plan = resolveSwap(o);
     const { resetPose = false } = o;
     const gen = ++sourceGen;

package/js/inline3d-splat-video.js

@@ -0,0 +1,305 @@
+// inline3d-splat-video.js — handle.setVideo(): a stereo video ON the persistent PlayCanvas splat
+// handle (docs/playcanvas-adapter.md §setVideo). Internal to ./inline3d-splat-playcanvas.js.
+//
+// WHY ON THE HANDLE. A page that renders everything through ONE persistent woven canvas (rule 3 of
+// docs/woven-canvas-rules.md) cannot put a movie in a second canvas without re-creating the very
+// window the persistent stage exists to remove (a fresh canvas is fresh to the compositor: the raw
+// side-by-side flash). So the video is drawn by the tile's own engine, in the tile's own frame.
+//
+// HOW IT IS DRAWN. One quad, parented under the RIG NODE (the eye camera's parent), at display
+// space z = 0: RenderView composes the rig node into every view, so a child of it is fixed relative
+// to the eyes whatever the pose (orbit, zoom, focus) — the plane is screen-locked by construction,
+// and exit restores the pose untouched. On the display rig the z = 0 plane spans the element
+// (docs/authoring-inline-3d.md §display rig), so the quad is the element box contained / covered by
+// the video's per-eye aspect. Zero disparity for the quad itself: the depth is the video's own.
+//
+// EACH EYE SEES ONLY ITS HALF. One camera draws every view (the RenderView path), so the shader
+// cannot be told "this is the right eye" by a uniform per view. It does not need to be: the eye
+// viewports sit side by side in the buffer, so gl_FragCoord.x against the first right-eye
+// viewport's x says which eye this fragment belongs to. Mono (not woven): the split is +∞, every
+// fragment samples the LEFT half, at the full buffer resolution. The sample is clamped half a texel
+// inside its half, so linear filtering never bleeds the other eye across the seam.
+//
+// UPLOAD. Gated on requestVideoFrameCallback (a new frame was presented), with `seeked` and a
+// currentTime change as fallbacks (no rVFC; a paused seek on a build that does not fire it). One
+// texture, re-specified from the <video> by the engine (texImage2D; GPU-to-GPU in Chromium): no
+// 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.
+
+/** 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']);
+let warnedVideoKeys = false;
+
+export const PAGE_VIDEO_ERROR =
+  "@displayxr/inline3d/splat: setVideo() is not available with controls:'page' — the page owns the " +
+  'camera, and a video plane needs the display rig. Draw the video into your own scene instead.';
+
+/**
+ * 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 }}
+ */
+export function validateSetVideo(src, o = {}, pageMode = false) {
+  if (pageMode) throw new Error(PAGE_VIDEO_ERROR);
+  const isVideo = typeof HTMLVideoElement !== 'undefined' ? src instanceof HTMLVideoElement : !!src && typeof src === 'object' && 'videoWidth' in src;
+  if (!(typeof src === 'string' && src.length > 0) && !isVideo) {
+    throw new TypeError('@displayxr/inline3d/splat: setVideo(src) — expected a URL string, an HTMLVideoElement, or null to exit.');
+  }
+  if (o === null || typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setVideo options must be an object.');
+  const unknown = Object.keys(o).filter((k) => !VIDEO_OPTION_KEYS.has(k));
+  if (unknown.length && !warnedVideoKeys) {
+    warnedVideoKeys = true;
+    console.warn(`[inline3d/splat] setVideo ignores ${unknown.join(', ')}.`);
+  }
+  const format = o.format === undefined ? 'sbs' : o.format;
+  if (!VIDEO_FORMATS.includes(format)) {
+    throw new Error(`@displayxr/inline3d/splat: setVideo — format "${format}", expected ${VIDEO_FORMATS.join(' | ')}.`);
+  }
+  const fit = o.fit === undefined ? 'contain' : o.fit;
+  if (!VIDEO_FITS.includes(fit)) throw new Error(`@displayxr/inline3d/splat: setVideo — fit "${fit}", expected ${VIDEO_FITS.join(' | ')}.`);
+  if (o.rig !== undefined && o.rig !== 'display') {
+    throw new Error(`@displayxr/inline3d/splat: setVideo — rig "${o.rig}"; a video plays on the display rig only ('display').`);
+  }
+  let vH;
+  if (o.virtualDisplayHeight !== undefined) {
+    vH = o.virtualDisplayHeight;
+    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') };
+}
+
+/**
+ * The per-eye source regions in texture space (st: s → right, t → DOWN, i.e. image rows), as
+ * [s0, t0, ds, dt] for the left and the right eye.
+ */
+export function eyeRegions(format) {
+  if (format === 'tb') return { L: [0, 0, 1, 0.5], R: [0, 0.5, 1, 0.5] };
+  if (format === 'mono') return { L: [0, 0, 1, 1], R: [0, 0, 1, 1] };
+  return { L: [0, 0, 0.5, 1], R: [0.5, 0, 0.5, 1] };
+}
+
+/** One eye's aspect (width / height) of a `videoWidth × videoHeight` frame in `format`. */
+export function eyeAspect(format, w, h) {
+  if (!(w > 0) || !(h > 0)) return 0;
+  if (format === 'sbs') return w / 2 / h;
+  if (format === 'tb') return w / (h / 2);
+  return w / h;
+}
+
+/**
+ * The quad's size at display-space z = 0, where the window is `vH · boxAspect` wide and `vH` tall:
+ * 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' }) {
+  const W = vH * boxAspect;
+  const H = vH;
+  if (!(a > 0) || !(boxAspect > 0)) return { w: W, h: H };
+  const wider = a >= boxAspect;
+  if ((fit === 'contain') === wider) return { w: W, h: W / a };
+  return { w: H * a, h: H };
+}
+
+/**
+ * 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
+ * first half of them are left eyes.
+ */
+export function eyeSplit(entries, rect) {
+  if (!entries || entries.length < 2) return 1e9;
+  return rect(entries[entries.length >> 1])[0];
+}
+
+const VERT = `
+attribute vec3 vertex_position;
+attribute vec2 vertex_texCoord0;
+uniform mat4 matrix_model;
+uniform mat4 matrix_viewProjection;
+varying vec2 vUv;
+void main() {
+  vUv = vertex_texCoord0;
+  gl_Position = matrix_viewProjection * matrix_model * vec4(vertex_position, 1.0);
+}`;
+const FRAG = `
+varying vec2 vUv;
+uniform sampler2D dxrVid;
+uniform vec4 dxrVidL;      // left eye's region: s0, t0, ds, dt (t = image rows, top = 0)
+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)
+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);
+}`;
+
+/**
+ * The quad, its material and its texture, owned by the viewer (`viewer._videoPlane`) while a video
+ * is on. `beforeDraw` is called by the viewer's draw, once per engine tick, before the tick.
+ */
+export class VideoPlane {
+  constructor(viewer) {
+    this.viewer = viewer;
+    const pc = (this.pc = viewer.pc);
+    const device = viewer.app.graphicsDevice;
+    const mesh = new pc.Mesh(device);
+    mesh.setPositions(new Float32Array([-0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.5, 0, -0.5, 0.5, 0]));
+    mesh.setUvs(0, new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]));
+    mesh.setIndices([0, 1, 2, 0, 2, 3]);
+    mesh.update();
+    this.mesh = mesh;
+    const mat = new pc.ShaderMaterial({
+      uniqueName: 'inline3dVideoPlane',
+      attributes: { vertex_position: pc.SEMANTIC_POSITION, vertex_texCoord0: pc.SEMANTIC_TEXCOORD0 },
+      vertexGLSL: VERT,
+      fragmentGLSL: FRAG,
+    });
+    mat.cull = pc.CULLFACE_NONE;
+    mat.setParameter('dxrVidSplit', 1e9);
+    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);
+    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;
+    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;
+  }
+
+  /** Play `video` on the quad (a new element, format or fit). The element must have a frame. */
+  setSource(video, { format, fit, vH }) {
+    this.format = format;
+    this.fit = fit;
+    this.vH = vH;
+    const r = eyeRegions(format);
+    this.mat.setParameter('dxrVidL', r.L);
+    this.mat.setParameter('dxrVidR', r.R);
+    if (video !== this.video) {
+      this._unwatch();
+      this.video = video;
+      this._watch();
+    }
+    this._ensureTexture();
+    this._sizeKey = '';
+    this._dirty = true;
+    this.mat.update();
+    this.mi.visible = true;
+  }
+
+  _watch() {
+    const v = this.video;
+    v.addEventListener?.('seeked', this._onSeeked);
+    if (typeof v.requestVideoFrameCallback === 'function') {
+      const cb = () => {
+        this._dirty = true;
+        if (this.video === v) this._rvfc = v.requestVideoFrameCallback(cb);
+      };
+      this._rvfc = v.requestVideoFrameCallback(cb);
+    }
+  }
+
+  _unwatch() {
+    const v = this.video;
+    if (!v) return;
+    v.removeEventListener?.('seeked', this._onSeeked);
+    if (this._rvfc && typeof v.cancelVideoFrameCallback === 'function') v.cancelVideoFrameCallback(this._rvfc);
+    this._rvfc = 0;
+  }
+
+  /** One texture per video size; re-made only when the frame size changes. */
+  _ensureTexture() {
+    const pc = this.pc;
+    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;
+    this.tex?.destroy?.();
+    this.tex = new pc.Texture(this.viewer.app.graphicsDevice, {
+      name: 'inline3d-video',
+      width: Math.max(1, w),
+      height: Math.max(1, h),
+      format: pc.PIXELFORMAT_RGBA8,
+      mipmaps: false,
+      flipY: false,
+      minFilter: pc.FILTER_LINEAR,
+      magFilter: pc.FILTER_LINEAR,
+      addressU: pc.ADDRESS_CLAMP_TO_EDGE,
+      addressV: pc.ADDRESS_CLAMP_TO_EDGE,
+    });
+    this.tex.setSource?.(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;
+    this._dirty = false;
+    this.uploads++; // setSource uploads
+  }
+
+  /** Per engine tick, before it: size the quad, place the eye split, upload a new frame. */
+  beforeDraw(entries, rect) {
+    const v = this.video;
+    if (!v || !this.mi.visible) return;
+    this.frames++;
+    const split = eyeSplit(entries, rect);
+    if (split !== this._split) {
+      this._split = split;
+      this.mat.setParameter('dxrVidSplit', split);
+    }
+    const boxAspect = this.viewer.boxAspect;
+    const key = `${boxAspect}|${v.videoWidth}x${v.videoHeight}|${this.format}|${this.fit}|${this.vH}`;
+    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 });
+      this.node.setLocalScale(s.w, s.h, 1);
+    }
+    // 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)) {
+      if ((v.readyState || 0) >= 2) {
+        this.tex.upload();
+        this.uploads++;
+      }
+      this._dirty = false;
+      this._lastT = t;
+    }
+  }
+
+  hide() {
+    this.mi.visible = false;
+  }
+
+  destroy() {
+    this._unwatch();
+    this.video = null;
+    this.layer?.removeMeshInstances?.([this.mi]);
+    this.node.parent?.removeChild?.(this.node);
+    this.tex?.destroy?.();
+    this.tex = null;
+    this.mat.destroy?.();
+    this.mesh.destroy?.();
+  }
+}

package/js/inline3d-splat.js

@@ -373,6 +373,13 @@ export function addSplat(wall, canvas, src, opts = {}) {
     prepareSource() {
       throw new Error("@displayxr/inline3d/splat: prepareSource() is implemented on the PlayCanvas backend only.");
     },
+    /** Not on this backend: a video on the splat handle is a PlayCanvas-backend feature. */
+    setVideo() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setVideo() is implemented on the PlayCanvas backend only " +
+          "(addSplat(…, { engine:'playcanvas' })); with Spark, use wall.addVideo on its own canvas.",
+      );
+    },
     /** Not on this backend: the live rig switch is a PlayCanvas-backend feature. */
     setRig() {
       throw new Error(
@@ -736,6 +743,9 @@ function addSplatDeferred(wall, canvas, src, opts) {
           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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -52,6 +52,7 @@
     "js/inline3d-splat-shared.js",
     "js/inline3d-splat-effects.js",
     "js/inline3d-splat-live.js",
+    "js/inline3d-splat-video.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",

package/splat.d.ts

@@ -178,6 +178,35 @@ export interface ResolvedRig {
   parallaxFactor: number;
 }
 
+/** `handle.setVideo` options. */
+export interface SplatVideoOptions {
+  /** Stereo layout of the frame: `'sbs'` (default, left eye = left half), `'tb'` (left = top), `'mono'` (both eyes the whole frame). */
+  format?: 'sbs' | 'tb' | 'mono';
+  /** `'contain'` (default): the whole eye image, bars where the aspects differ. `'cover'`: the window full, the overflow cropped. */
+  fit?: 'contain' | 'cover';
+  /** Only `'display'`. */
+  rig?: 'display';
+  /** The display rig's height while the video is on (default: the tile's own `virtualDisplayHeight`). No visible effect on a flat plane at the window. */
+  virtualDisplayHeight?: number;
+  /** Applied to the element when given. */
+  loop?: boolean;
+  muted?: boolean;
+  /** Default true for a URL (the SDK's own element), false for an element you pass. */
+  autoplay?: boolean;
+}
+
+/** What `handle.setVideo(src)` resolves to. */
+export interface SplatVideo {
+  /** The element: play / pause / currentTime / duration / ended / events are the page's to drive. */
+  readonly video: HTMLVideoElement;
+  readonly format: 'sbs' | 'tb' | 'mono';
+  readonly fit: 'contain' | 'cover';
+  /** `handle.setVideo(null)`, or a no-op if another setVideo has replaced this one. */
+  remove(): Promise<null>;
+  /** Frames drawn with the plane up, and texture uploads (new video frames). */
+  stats(): { frames: number; uploads: number };
+}
+
 export interface SplatOptions {
   /**
    * Which renderer. `'spark'` (the default) is three.js + Spark. `'playcanvas'` is the PlayCanvas
@@ -800,6 +829,25 @@ export interface SplatHandle {
    */
   setRig(type: 'display', opts?: SplatSetRigDisplayOptions): Promise<SplatHandle>;
   setRig(type: 'camera' | 'auto'): Promise<SplatHandle>;
+  /**
+   * PlayCanvas backend only — throws on Spark, and with `controls:'page'`. Play a stereo video ON
+   * this handle: no new canvas, layer or session (docs/playcanvas-adapter.md §setVideo). The splat
+   * is hidden and a screen-locked plane on the display rig shows the video, sized to its per-eye
+   * aspect by `fit`; each eye samples only its own half (`'sbs'`: left/right, `'tb'`: top/bottom).
+   * Not woven (the mono path): the LEFT half at the full buffer resolution. The texture is
+   * re-uploaded only when the video presents a new frame (requestVideoFrameCallback).
+   *
+   * Applies on the first frame the video has; resolves to a {@link SplatVideo}. The page drives
+   * transport through `v.video`. A URL makes an SDK-owned `<video>` (autoplays unless
+   * `autoplay: false`; muted automatically if the browser refuses sound without a gesture); an
+   * element you pass stays yours (the SDK never plays or pauses it unless `autoplay: true`).
+   * `setVideo(null)` exits and restores the splat's visibility, the pose, the lens and the declared
+   * view rig exactly as they were. A second setVideo replaces the video and keeps the pre-video
+   * state. Throws during an in-flight `setSource`; while a video is on, `setSource` rejects and
+   * `setRig` throws (`setVideo(null)` first). `prepareSource` stays available.
+   */
+  setVideo(src: string | HTMLVideoElement, opts?: SplatVideoOptions): Promise<SplatVideo>;
+  setVideo(src: null): Promise<null>;
   /**
    * `engine: 'playcanvas'` only (throws on Spark). Play a transition/pulse/custom effect;
    * validated at the call, run once the first asset is on screen. Resolves `{ finished }` —