@displayxr/inline3d 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.24.0 — 2026-09-25
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change. Pixels change
+during a live transition between two camera-rig photos (they were wrong), and for the frames in
+which a newly declared rig has not yet reached the runtime's views.
+
+- **No camera jump at the start of a live transition.** Crossfade, wavefront and the particle
+  transitions keep the outgoing photo alive next to the incoming one. Between two photos with
+  camera rigs (SOG camera blocks: each its own convergence and vertical FOV), the outgoing photo
+  was drawn from eyes scaled by the two rigs' window ratio from the swap on, a jump in its
+  disparity and head parallax. For the frame(s) before the declaration reached the views, both
+  photos were drawn through the wrong rig. Each photo is now drawn through its own rig for the whole
+  window. The SDK reads off the views which declared rig they were located for, and remaps them
+  exactly (window onto window, eye onto eye; the runtime's projection verbatim, no Kooima) where
+  they are not the photo's own. `reassemble` was never affected. Headless: 102–208 px of
+  reference-point error → < 0.005 px, and the live outgoing image equals the frame before the swap
+  (MAE 0.000). Docs: `docs/playcanvas-adapter.md` § Each photo through its own rig.
+- **Kill switch `?dxrdiag=oldrig`** (the 1.23 behaviour). The diag's per-frame record gains
+  `rigAt` / `rigIn` / `rigOut`: the rig the views were located for, the rig the current photo was
+  drawn through (`+` = remapped), and how the live outgoing photo was drawn.
+- `tools/rig-swap-capture`: the headless harness behind the numbers.
+
 ## 1.23.0 — 2026-09-25
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). New API; no pixel change for a

package/js/inline3d-splat-diag.js

@@ -30,6 +30,15 @@
 //              pick index. Tests "the page's picks are what blocks the main thread".
 //   nolayerrig — handle.setLayerRig is recorded but never applied: every layer stays on the eye
 //              camera and the photo's camera rig (the pre-1.23 path, byte for byte).
+//   oldrig   — no rig tracking (./inline3d-splat-rig-map.js): the views are drawn as the runtime
+//              located them, and a live outgoing photo goes back on the pre-1.24 node chain (which
+//              scales its disparity by the two rigs' window ratio at the swap). A/B for "the
+//              outgoing photo jumps when the incoming rig is declared".
+//
+// Per frame, `rigAt` / `rigIn` / `rigOut` say which declared rig the views were located for
+// (the tracker's id; null = none matched), which rig the current photo was drawn through
+// (`+` = remapped to it) and how the live outgoing photo was drawn ('own' = its rig as located,
+// 'remapped', 'eye', 'chain'; null = no live outgoing).
 //
 // WHAT RUNS ON THE MAIN THREAD, per transition phase (the fifth cause: a stall at the swap's END
 // that is not the SDK's transition at all):
@@ -44,7 +53,7 @@
 //     after it (the page's continuation of `await setSource`).
 
 /** The switches `diag` / `?dxrdiag` understand, besides the plain on values. */
-export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig']);
+export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig', 'oldrig']);
 const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
 
 /**
@@ -191,6 +200,7 @@ export class DiagRecorder {
     this._frameNo = 0;
     this._open = null; // the transition being recorded
     this.imageState = null; // () => { overlay: 'none' | 'frozen' | 'live', w }
+    this.rigState = null; // () => { at, in, out } (see the header)
     this.longTasks = [];
     this._lto = null;
     this.rigLocked = null; // norig: the summary of the rig kept
@@ -373,6 +383,7 @@ export class DiagRecorder {
     this._lastFrameAt = t;
     this._frameNo++;
     const img = this.imageState ? safe(this.imageState) : null;
+    const rs = this.rigState ? safe(this.rigState) : null;
     const f = {
       n: this._frameNo,
       t: round1(t),
@@ -388,6 +399,9 @@ export class DiagRecorder {
       afterRig: this._frameNo - this._rigFrame <= 3,
       img: img ? img.overlay : 'none',
       imgW: img ? round4(img.w) : 0,
+      rigAt: rs ? rs.at : null,
+      rigIn: rs ? rs.in : null,
+      rigOut: rs ? rs.out : null,
     };
     this.frames.push(f);
     if (this.frames.length > FRAME_CAP) this.frames.splice(0, this.frames.length - FRAME_CAP);

package/js/inline3d-splat-layer-rig.js

@@ -19,6 +19,8 @@
 // nominal viewer distance in metres — the one quantity the browser does not expose (see the
 // design note §5). Everything here is PLAIN ARITHMETIC on arrays, unit-testable without a GPU.
 
+import { invertAffine } from './inline3d-splat-rig-map.js';
+
 /** handle.setLayerRig's rigs. 'camera' is the default every layer starts on. */
 export const LAYER_RIGS = Object.freeze(['display', 'camera']);
 
@@ -189,7 +191,7 @@ export function roundViews(entries, frame, k, into = []) {
     o.eye[1] = Eround[1];
     o.eye[2] = Eround[2];
     mul4(o.Minv, P, o.viewInv);
-    mul4(invertRigid(P), o.M, o.view);
+    mul4(invertAffine(P), o.M, o.view); // P is rigid, or affine once remapped to the declared rig (./inline3d-splat-rig-map.js)
   }
   return into;
 }
@@ -402,7 +404,7 @@ export class LayerRigCameras {
         cam.camera.camera.setXrProperties({ ...f, horizontalFov: false });
       }
       // The node drives transparent sorting (the views ignore it): on the (round) first eye.
-      const p = entries[0].pose;
+      const p = entries[0].node || entries[0].pose; // `node`: a rigid pose when the views are remapped
       const q = quatOf(p);
       cam.setLocalRotation(q[0], q[1], q[2], q[3]);
       if (r) cam.setLocalPosition(r[0].eye[0], r[0].eye[1], r[0].eye[2]);

package/js/inline3d-splat-live.js

@@ -25,14 +25,29 @@
 //
 // THE RIG. The incoming asset's rig (camera rig: its capture pose, lens and convergence; display
 // rig: its fit and focus) is adopted at once, as in the frozen path, so the views the runtime
-// hands us after that are the INCOMING photo's. The outgoing camera is parented under a node
-// chain that maps them back to the OUTGOING photo's framing:
+// hands us — once the declaration has reached them, a frame or more later — are the INCOMING
+// photo's. The outgoing photo must keep being drawn through ITS OWN rig for the whole window.
+//
+// Two camera rigs (a photo slideshow: every photo a SOG with a camera block): the views are
+// remapped, per frame, from the rig they were LOCATED for to the outgoing photo's rig, by the
+// exact portal map of ./inline3d-splat-rig-map.js — window onto window, eye onto eye, the
+// runtime's projection verbatim — under the outgoing photo's rig node R_o. Before the
+// declaration arrives the located rig IS the outgoing one and the views pass through untouched.
+//
+// Otherwise (a display rig on either side, views no declared rig explains, the kill switch
+// `?dxrdiag=oldrig`): the pre-1.24 node chain, which maps the incoming views back to the outgoing
+// photo's framing:
 //     N = R_o · K_o · D_o · D_n⁻¹ · K_n⁻¹
 // with R the rig node (inverse pivot), K the mono/capture pose in rig space and
 // D = diag(c·t, c·t, c) (c = convergence distance, t = tan(vfov/2)). The eye poses (head
 // motion) pass through untouched; the outgoing photo keeps its own window and zero-disparity
 // plane. Two display-rig assets cancel to N = R_o (the old fit and focus); in controls:'page' the
-// page owns the camera and N is the rig node itself.
+// page owns the camera and N is the rig node itself. For two CAMERA rigs this chain is not exact:
+// it scales the eyes with the window, by (c_o·t_o)/(c_n·t_n) — the outgoing photo's disparity and
+// head parallax jumped by that factor at the swap (the "camera change right before the
+// transition" report) — and it assumed the views were already the incoming rig's.
+
+import { remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
 
 /** setSource's `outgoing` option. */
 export const OUTGOING_MODES = Object.freeze(['live', 'frozen']);
@@ -151,6 +166,12 @@ export class LiveOutgoing {
     /** PRE-SORT (warm): the current asset is ALSO on the live layer, before the swap. */
     this.warming = false;
     this._warmLayers = null;
+    /** The outgoing photo's own declared rig (a RigTracker entry), taken at start(). */
+    this.ownRig = null;
+    this._map = [];
+    this._node = new Float64Array(16);
+    /** What the last sync drew through: 'eye' (the eye's views), 'own' (the photo's rig, as located), 'remapped', 'chain'. */
+    this.path = null;
   }
 
   /** Engine support for this path: RenderViews on one camera, render targets, layers. */
@@ -299,6 +320,8 @@ export class LiveOutgoing {
       entity.gsplat.layers = [this.layer.id];
       this.entity = entity;
       this.oldFrame = oldFrame;
+      // Read BEFORE the incoming asset's rig is declared: the last declared rig is the outgoing's.
+      this.ownRig = v.rigTrack?.latest ?? null;
       if (!warmed) this.frames = 0;
       this.warming = false;
       this._warmLayers = null;
@@ -347,10 +370,11 @@ export class LiveOutgoing {
   }
 
   /**
-   * Per frame, before the engine tick: the eye's views on the outgoing camera (same proj, pose,
-   * viewport), the eye's node pose, and the rig chain.
+   * Per frame, before the engine tick: the views on the outgoing camera — through the outgoing
+   * photo's own rig (see the header) — the viewports, and the node chain. `rf` is the viewer's rig
+   * mapping for this frame (viewer._mapViews), or undefined.
    */
-  sync(entries, rect, frustum) {
+  sync(entries, rect, frustum, rf) {
     if (!this.active && !this.warming) return;
     const v = this.viewer;
     const pc = v.pc;
@@ -360,11 +384,50 @@ export class LiveOutgoing {
       for (let i = 0; i < entries.length; i++) rvs.push(new pc.RenderView());
       this.cam.camera.camera.xrViews = rvs.slice();
     }
+    // Which views: the pre-sort (and controls:'page', where both photos are the page camera's)
+    // draws what the eye draws; an active window draws the outgoing photo's own rig.
+    let mapped = null; // remapped views, or null = the entries as they are
+    let exact = false; // the rig map applies: no node chain
+    let nodeRig = null; // the portal the remapped views belong to (for the camera node)
+    const own = this.ownRig;
+    if (rf && v.rigTrack && (!this.active || v.pageCamera)) {
+      exact = true;
+      mapped = rf.remapped ? rf.entries : null;
+      nodeRig = rf.eye?.portal ?? null;
+      this.path = 'eye';
+    } else if (rf?.located && own?.portal && this.active && !v.pageCamera) {
+      if (rf.located === own || sameRig(rf.located.rig, own.rig)) {
+        exact = true;
+        this.path = 'own';
+      } else {
+        mapped = remapViews(entries, rf.located.portal, own.portal, this._map);
+        exact = !!mapped;
+        nodeRig = own.portal;
+        if (mapped) this.path = 'remapped';
+      }
+    }
+    if (!exact) this.path = 'chain';
     for (let i = 0; i < entries.length; i++) {
-      rvs[i].setView(entries[i].proj, entries[i].pose);
+      if (mapped) rvs[i].setView(mapped[i].proj, mapped[i].viewInv, mapped[i].view);
+      else rvs[i].setView(entries[i].proj, entries[i].pose);
       const [x, y, w, h] = rect(entries[i]);
       rvs[i].setViewport(x, y, w, h);
     }
+    // The wavefront's cull reads the views this camera really draws (viewer.cullViews).
+    if (mapped) {
+      const cull = (this._cull ||= []);
+      cull.length = mapped.length;
+      for (let i = 0; i < mapped.length; i++) {
+        const c = (cull[i] ||= {});
+        c.proj = mapped[i].proj;
+        c.pose = mapped[i].viewInv;
+        c.x = mapped[i].x;
+        c.y = mapped[i].y;
+        c.width = mapped[i].width;
+        c.height = mapped[i].height;
+      }
+      this.cam._dxrViews = cull;
+    } else this.cam._dxrViews = null;
     if (frustum) {
       const key = `${frustum.fov.toFixed(4)}|${frustum.aspectRatio.toFixed(4)}|${frustum.nearClip}|${frustum.farClip}`;
       if (key !== this._frustumKey) {
@@ -374,6 +437,20 @@ export class LiveOutgoing {
     }
     // The node chain (see the header). controls:'page': the page's camera, for both assets.
     const { n1, n2, n3 } = this.nodes;
+    if (exact) {
+      // The views are in rig space already: only the photo's rig node above them — the one the
+      // outgoing photo had at the swap (the pre-sort and controls:'page': the current one).
+      setTRS(n1, similarityTRS(this.active && !v.pageCamera && this.oldFrame ? this.oldFrame.rig : v.rigMatrix()));
+      n2.setLocalScale(1, 1, 1);
+      setTRS(n3, { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: 1 });
+      // The camera NODE (sort direction, LOD distance) on the first eye this camera draws from.
+      const pose = mapped && nodeRig ? nodePose(nodeRig, mapped[0].eye, this._node) : entries[0].pose;
+      const q = similarityTRS(pose).rotation;
+      this.cam.setLocalPosition(pose[12], pose[13], pose[14]);
+      this.cam.setLocalRotation(q[0], q[1], q[2], q[3]);
+      this.frames++;
+      return;
+    }
     if (v.pageCamera || !this.oldFrame) {
       const r = similarityTRS(v.rigMatrix());
       setTRS(n1, r);
@@ -401,6 +478,9 @@ export class LiveOutgoing {
     if (this.warming) return this.cancelWarm();
     this.entity = null;
     this.oldFrame = null;
+    this.ownRig = null;
+    this.path = null;
+    if (this.cam) this.cam._dxrViews = null;
     this.active = false;
     this.warmed = false;
     if (this.cam) this.cam.enabled = false;

package/js/inline3d-splat-playcanvas.js

@@ -69,6 +69,7 @@ import {
 import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
 import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR, eyeSplit, EYE_SPLIT_UNIFORM, makeSbsMaterial } from './inline3d-splat-video.js';
 import { LayerRigCameras, validateLayerRig } from './inline3d-splat-layer-rig.js';
+import { RigTracker, remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
 import { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, DIAG_SWITCHES } from './inline3d-splat-diag.js';
 import {
   clamp,
@@ -823,6 +824,16 @@ export class PlayCanvasSplatViewer {
     this.layerRigSource = null;
     /** That descriptor as it stood when THIS frame's views were pulled (snapshotted in onFrame). */
     this._rigSnap = null;
+    /**
+     * The rigs this tile declared and which one each frame's views were located for
+     * (./inline3d-splat-rig-map.js). Null = the kill switch (diag 'oldrig'): views drawn as
+     * located, the live outgoing on its pre-1.24 node chain.
+     */
+    this.rigTrack = null;
+    /** This frame's rig mapping: { located, eye, remapped, entries } (see _mapViews). */
+    this.rigFrame = null;
+    this._eyeMap = [];
+    this._rigAtPull = null;
     this._eyeSplit = NaN;
     this.boxAspect = 1;
     this.featherPx = feather > 0 ? feather : 0;
@@ -1136,6 +1147,8 @@ export class PlayCanvasSplatViewer {
     // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
     // and the tick below may declare a new one (a focus ease) for the NEXT locate.
     if (this.layerRigs?.active) this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+    // Same moment, for the rig map: the rig these views were most likely located for (a tie-break).
+    this._rigAtPull = this.rigTrack ? this.rigTrack.latest : null;
     // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
     this._beforeFrame?.(views || null);
     this._tick();
@@ -1588,6 +1601,44 @@ export class PlayCanvasSplatViewer {
     }
   }
 
+  /**
+   * This frame's rig mapping (./inline3d-splat-rig-map.js): which declared rig the views were
+   * located for (`located`), which the current photo wants (`eye`, the last declared), and — only
+   * when those differ and both are camera rigs — the views remapped to `eye` (`entries`: proj,
+   * viewInv, view per view; `cull`: the same as { proj, pose } entries; `node`: the first eye's
+   * rigid pose). Otherwise `remapped` is false and the views are drawn exactly as located.
+   */
+  _mapViews(entries, prefer = null) {
+    const rt = this.rigTrack;
+    const rf = (this.rigFrame ||= { located: null, eye: null, remapped: false, entries: null, cull: [], node: new Float64Array(16) });
+    rf.remapped = false;
+    rf.located = rf.eye = null;
+    if (!rt || this._mode !== '3d' || entries.length < 2) return rf;
+    rf.located = rt.locate(entries, prefer);
+    rf.eye = rt.latest;
+    const L = rf.located;
+    const T = rf.eye;
+    if (!L || !T?.portal || L === T || sameRig(L.rig, T.rig)) return rf;
+    const r = remapViews(entries, L.portal, T.portal, this._eyeMap);
+    if (!r) return rf;
+    rf.remapped = true;
+    rf.entries = r;
+    rf.cull.length = r.length;
+    for (let i = 0; i < r.length; i++) {
+      const c = (rf.cull[i] ||= {});
+      c.proj = r[i].proj;
+      c.pose = r[i].viewInv;
+      c.x = r[i].x;
+      c.y = r[i].y;
+      c.width = r[i].width;
+      c.height = r[i].height;
+      c.node = null;
+    }
+    nodePose(T.portal, r[0].eye, rf.node);
+    rf.cull[0].node = rf.node; // a rigid pose for a camera NODE (the views are affine)
+    return rf;
+  }
+
   /**
    * The mono/capture camera as a lens frame, for the live outgoing's rig chain
    * (./inline3d-splat-live.js): the rig node's matrix, the camera pose in rig space, the
@@ -1612,6 +1663,8 @@ export class PlayCanvasSplatViewer {
    */
   cullViews(cam, entries, rect, into = []) {
     const parent = cam?.parent?.getWorldTransform?.()?.data ?? null;
+    // A camera drawing remapped views (./inline3d-splat-rig-map.js) publishes them as _dxrViews.
+    if (cam?._dxrViews?.length === entries.length) entries = cam._dxrViews;
     into.length = entries.length;
     for (let i = 0; i < entries.length; i++) {
       const e = entries[i];
@@ -1625,7 +1678,8 @@ export class PlayCanvasSplatViewer {
       o.W[0] = C[3]; o.W[1] = C[7]; o.W[2] = C[11]; o.W[3] = C[15];
       o.K[0] = w * e.proj[0];
       o.K[1] = 1 / w;
-      o.K[2] = V[0] * V[0] + V[1] * V[1] + V[2] * V[2];
+      // The view's largest column scale² (1 for a rigid view; a remapped view is affine).
+      o.K[2] = Math.max(V[0] * V[0] + V[1] * V[1] + V[2] * V[2], V[4] * V[4] + V[5] * V[5] + V[6] * V[6], V[8] * V[8] + V[9] * V[9] + V[10] * V[10]);
       o.K[3] = 0;
     }
     return into;
@@ -1857,12 +1911,18 @@ export class PlayCanvasSplatViewer {
         for (let i = 0; i < entries.length; i++) rvs.push(new pc.RenderView());
         this.eye.camera.camera.xrViews = rvs.slice();
       }
+      // The current photo through ITS rig (the last declared): the views are remapped only while
+      // they were located for another one (a declaration still in flight, ./inline3d-splat-rig-map.js).
+      const rf = this._mapViews(entries, cache ? cache.rigAt : null);
+      const eyeViews = rf.remapped ? rf.entries : null;
       for (let i = 0; i < entries.length; i++) {
         const e = entries[i];
-        rvs[i].setView(e.proj, e.pose);
+        if (eyeViews) rvs[i].setView(eyeViews[i].proj, eyeViews[i].viewInv, eyeViews[i].view);
+        else rvs[i].setView(e.proj, e.pose);
         const [x, y, w, h] = rect(e);
         rvs[i].setViewport(x, y, w, h);
       }
+      this.eye._dxrViews = eyeViews ? rf.cull : null;
       // LOD and FOV-compensation read camera.fov/near/far, which under xrViews come from the
       // XR properties — the frustum the views actually have, as XrManager does it.
       const f = frustumFromProjection(entries[0].proj);
@@ -1873,13 +1933,16 @@ export class PlayCanvasSplatViewer {
       }
       // The camera NODE drives the sort direction and LOD distance; the views ignore it (they
       // compose the node's PARENT with their own pose). Park it on the first eye.
-      placeNode(this.eye, entries[0].pose);
-      // setSource's live outgoing: the same views on its own camera, into its own target.
-      if (this._live?.active || this._live?.warming) this._live.sync(entries, rect, f);
+      placeNode(this.eye, eyeViews ? rf.node : entries[0].pose);
+      // setSource's live outgoing: the same views on its own camera (through ITS photo's rig),
+      // into its own target.
+      if (this._live?.active || this._live?.warming) this._live.sync(entries, rect, f, rf);
       // setSource's wavefront: this frame's eye views, as the engine is about to compose them.
       this.onBeforeRender?.(entries, rect);
       // handle.setLayerRig: the display / post run cameras, on the same views (display: rounded).
-      if (this.layerRigs && this.layerRigs.sync()) this.layerRigs.frame(entries, rect, f, cache ? cache.rig : null);
+      if (this.layerRigs && this.layerRigs.sync()) {
+        this.layerRigs.frame(eyeViews ? rf.cull : entries, rect, f, eyeViews ? rf.eye.rig : rf.located ? rf.located.rig : cache ? cache.rig : null);
+      }
     } else {
       // Fallback: one camera per view, `rect` + `calculateProjection`.
       const cams = this._views;
@@ -1938,6 +2001,7 @@ export class PlayCanvasSplatViewer {
     g.bufW = el.width || 0;
     g.bufH = el.height || 0;
     g.rig = this._rigSnap ? { ...this._rigSnap } : null; // a replay re-uses the rig of its views
+    g.rigAt = this._rigAtPull ?? null;
     for (let i = 0; i < views.length; i++) {
       const e = g.entries[i];
       const vp = vps[i];
@@ -2869,6 +2933,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let rigLockArmed = false;
   if (diag) {
     diag.imageState = () => viewer.diagImageState();
+    diag.rigState = () => {
+      const rf = viewer.rigFrame;
+      if (!viewer.rigTrack || !rf) return null;
+      return {
+        at: rf.located ? rf.located.id : null,
+        in: rf.eye ? `${rf.eye.id}${rf.remapped ? '+' : ''}` : null,
+        out: viewer._live?.active ? viewer._live.path : null,
+      };
+    };
     diag.observeLongTasks();
     diag.observeLongFrames();
     diag.log(`on — switches [${[...diag.switches].join(', ') || 'none'}]; dump: copy(__dxrDiag.dump())`);
@@ -3109,6 +3182,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // toward `target` at the viewer's FOCUS_EASE unless snapped.
   const pageFocus = { d: Number.NaN, target: Number.NaN, fired: Number.NaN, source: null };
 
+  let initialViewRig = null; // the rig addScene is created with (controls:'page'), else the shorthand
   if (wall && wall.supported) {
     const onFrame = diag
       ? (views, layer) => {
@@ -3121,7 +3195,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       // controls:'page' starts on a camera rig (attach, provisional FOV/convergence until the page
       // and the waterfall say otherwise); the display rig's height means nothing there.
       ...(pageMode
-        ? { viewRig: pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: 2, comfortDepth: ctl.comfortDepth }) }
+        ? { viewRig: (initialViewRig = pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: 2, comfortDepth: ctl.comfortDepth })) }
         : { virtualDisplayHeight }),
       onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
@@ -3130,6 +3204,20 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   } else {
     viewer.startMono();
   }
+  // Every rig this tile declares, by VALUE (./inline3d-splat-rig-map.js): which one a frame's
+  // views were located for is read off the views, so each photo can be drawn through its own rig
+  // while a declaration is in flight or while a live outgoing photo is still on screen.
+  // `?dxrdiag=oldrig` turns it off (views drawn as located; the live outgoing's node chain).
+  if (handle && typeof handle.setViewRig === 'function' && !diag?.has('oldrig')) {
+    const rt = (viewer.rigTrack = new RigTracker());
+    rt.note(initialViewRig || { type: 'display', virtualDisplayHeight });
+    const push = handle.setViewRig;
+    handle.setViewRig = (rig) => {
+      const r = push.call(handle, rig);
+      rt.note(rig);
+      return r;
+    };
+  }
   let diagLoop = null;
   if (diag) {
     // Every rig push, logged with its values; under `norig`, every push after the first

package/js/inline3d-splat-rig-map.js

@@ -0,0 +1,369 @@
+// inline3d-splat-rig-map.js — each photo through ITS OWN camera rig, whatever camera rig the
+// runtime's views were located for. Internal to ./inline3d-splat-playcanvas.js (and
+// ./inline3d-splat-live.js).
+//
+// THE BUG THIS FIXES. A live transition (crossfade, wavefront, the particle transitions) keeps the
+// outgoing photo on screen while the incoming photo's rig is declared. The runtime's views are
+// then the INCOMING rig's, and the outgoing photo was mapped back to its own framing by a node
+// chain N = R_o·K_o·D_o·D_n⁻¹·K_n⁻¹, D = diag(c·t, c·t, c). That maps the incoming WINDOW onto
+// the outgoing one exactly, but it scales the EYES with it: a camera rig's eyes do not scale with
+// its window (they are the viewer's eyes, times metersToVirtual), so the outgoing photo was drawn
+// from eyes scaled by (c_o·t_o)/(c_n·t_n) — its disparity and head parallax jumped by that factor
+// the moment the rig switched. And a declaration reaches the views a frame or more later, so for
+// those frames the chain mapped views that were still the OUTGOING rig's (and the incoming photo
+// was drawn through them).
+//
+// NO KOOIMA HERE, and no frustum is built. The runtime's projection matrices are used verbatim
+// (only their depth rows are rescaled, as clampProjectionDepth already does). What this does is
+// exact algebra on the runtime's outputs and the descriptors we declared:
+//
+//   1. A camera rig is a PORTAL (displayxr-common's dxr_camera3d_compute_view): every view looks,
+//      from its own eye, through ONE window rectangle on the convergence plane — centre
+//      Wc = N0 + D·fwd, half-height t·D (t = tan(vfov/2)), half-width aspect·t·D — and its eye is
+//      N0 + R·m·(π·c̄ + ι·(q − c̄)) (q the viewer's eye relative to the nominal viewer, c̄ their
+//      centroid, π/ι the parallax/ipd factors, m metersToVirtual).
+//   2. WHICH rig a view set was located for is read off the views: under the right descriptor
+//      every view's frustum crosses the window plane exactly in the window (`viewResidual`). The
+//      candidates are the descriptors declared recently (`RigTracker`); none within tolerance ⇒
+//      unknown ⇒ nothing is remapped (the caller keeps its old path).
+//   3. From the located rig F to a target rig T, per view: the eye maps exactly (step 1 inverted
+//      and re-applied — the eye centroid and offsets come from the views themselves), and the
+//      affine map A_i that sends F's window onto T's (in-plane scale σ = t_T·D_T / t_F·D_F, the
+//      same for x and y: both windows have the canvas's aspect) and F's eye onto T's eye maps
+//      every ray from F's eye through a window point onto the ray from T's eye through the
+//      matching window point. So
+//
+//          viewInv_T,i = A_i · viewInv_F,i        proj_T,i = proj_F,i  (depth rows rescaled)
+//
+//      renders EXACTLY what T's own view i would (same pixel for every point: both frusta are
+//      the pyramid through the window, and A_i maps one pyramid onto the other with the window
+//      rectangle onto the window rectangle). Vertical FOV, convergence, metersToVirtual and the
+//      two factors may all differ. Only the depth mapping moves (A_i scales depth by a_z), which
+//      is why the near/far planes are divided by a_z: the target keeps the runtime's near/far.
+//
+// A display rig is NOT mapped: its eyes are absolute (the viewer's z includes the nominal
+// distance, which the browser does not expose), so display ↔ camera would need that one scalar.
+// Everything here is PLAIN ARITHMETIC on arrays, unit-testable without a GPU.
+
+/** A view set matches a rig when every residual is below this, in window HALF-HEIGHTS (≈0.2 px at 720 px). */
+export const RIG_MATCH_TOL = 5e-4;
+
+/** How many recently declared rigs the tracker keeps as candidates. */
+export const RIG_HISTORY = 8;
+
+const FIELDS = ['convergenceDiopters', 'verticalFov', 'metersToVirtual', 'ipdFactor', 'parallaxFactor', 'virtualDisplayHeight', 'perspectiveFactor'];
+
+/** Rotate v by unit quaternion q (xyzw). */
+function rotate(q, v) {
+  const [x, y, z, w] = q;
+  const tx = 2 * (y * v[2] - z * v[1]);
+  const ty = 2 * (z * v[0] - x * v[2]);
+  const tz = 2 * (x * v[1] - y * v[0]);
+  return [v[0] + w * tx + (y * tz - z * ty), v[1] + w * ty + (z * tx - x * tz), v[2] + w * tz + (x * ty - y * tx)];
+}
+
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+
+/** A value copy of a declared descriptor (the SDK rewrites its camera-rig object in place), or null. */
+export function rigSnapshot(rig) {
+  if (!rig || typeof rig !== 'object') return null;
+  const p = rig.position || {};
+  const q = rig.orientation || {};
+  const o = {
+    type: rig.type,
+    position: { x: +p.x || 0, y: +p.y || 0, z: +p.z || 0 },
+    orientation: { x: +q.x || 0, y: +q.y || 0, z: +q.z || 0, w: q.w === undefined ? 1 : +q.w },
+  };
+  for (const k of FIELDS) if (rig[k] !== undefined) o[k] = rig[k];
+  return o;
+}
+
+/** Same declared values (snapshots)? */
+export function sameRig(a, b) {
+  if (a === b) return true;
+  if (!a || !b || a.type !== b.type) return false;
+  for (const k of ['x', 'y', 'z']) if (a.position[k] !== b.position[k]) return false;
+  for (const k of ['x', 'y', 'z', 'w']) if (a.orientation[k] !== b.orientation[k]) return false;
+  for (const k of FIELDS) if (a[k] !== b[k]) return false;
+  return true;
+}
+
+/**
+ * The portal of a CAMERA-rig descriptor, or null (a display rig, convergence at infinity, a
+ * factor of 0 — nothing to invert — or a non-finite field).
+ * @returns {{ N0: number[], q: number[], right: number[], up: number[], back: number[], Wc: number[], D: number, t: number, m: number, ipd: number, par: number }|null}
+ */
+export function cameraPortal(rig) {
+  if (!rig || rig.type !== 'camera') return null;
+  const inv = rig.convergenceDiopters;
+  const vfov = rig.verticalFov;
+  if (!(Number.isFinite(inv) && inv > 0) || !(Number.isFinite(vfov) && vfov > 0 && vfov < Math.PI)) return null;
+  const m = Number.isFinite(rig.metersToVirtual) && rig.metersToVirtual > 0 ? rig.metersToVirtual : 1;
+  const ipd = rig.ipdFactor ?? 1;
+  const par = rig.parallaxFactor ?? 1;
+  if (!(Number.isFinite(ipd) && ipd > 0) || !(Number.isFinite(par) && par > 0)) return null;
+  const p = rig.position || {};
+  const o = rig.orientation || {};
+  let q = [+o.x || 0, +o.y || 0, +o.z || 0, o.w === undefined ? 1 : +o.w];
+  const qn = Math.hypot(q[0], q[1], q[2], q[3]);
+  if (!(qn > 0)) return null;
+  q = q.map((c) => c / qn);
+  const N0 = [+p.x || 0, +p.y || 0, +p.z || 0];
+  const right = rotate(q, [1, 0, 0]);
+  const up = rotate(q, [0, 1, 0]);
+  const back = rotate(q, [0, 0, 1]);
+  const D = 1 / inv;
+  const Wc = [N0[0] - D * back[0], N0[1] - D * back[1], N0[2] - D * back[2]];
+  return { N0, q, right, up, back, Wc, D, t: Math.tan(vfov / 2), m, ipd, par };
+}
+
+/** Window-local coordinates (right, up, toward the viewer) of a point, about the window centre. */
+function local(P, X) {
+  const d = [X[0] - P.Wc[0], X[1] - P.Wc[1], X[2] - P.Wc[2]];
+  return [dot(P.right, d), dot(P.up, d), dot(P.back, d)];
+}
+
+/**
+ * How far one runtime view is from being a view of portal P, in window half-heights: its
+ * rotation must be P's, and its frustum must cross P's window plane exactly in the window
+ * (centred on Wc, t·D tall). Reads the projection's off-axis tangents; builds nothing.
+ */
+export function viewResidual(entry, P) {
+  const m = entry.pose;
+  const pr = entry.proj;
+  // rotation: the pose's columns against the rig's axes (unit vectors; 1e-7 is float32 noise)
+  const rot = Math.max(
+    Math.abs(m[0] - P.right[0]), Math.abs(m[1] - P.right[1]), Math.abs(m[2] - P.right[2]),
+    Math.abs(m[4] - P.up[0]), Math.abs(m[5] - P.up[1]), Math.abs(m[6] - P.up[2]),
+    Math.abs(m[8] - P.back[0]), Math.abs(m[9] - P.back[1]), Math.abs(m[10] - P.back[2]),
+  );
+  if (!(pr[0] > 0) || !(pr[5] > 0) || Math.abs(pr[11] + 1) > 1e-6 || Math.abs(pr[4]) > 1e-6) return Infinity;
+  const u = local(P, [m[12], m[13], m[14]]);
+  if (!(u[2] > 0)) return Infinity;
+  const tl = (pr[8] - 1) / pr[0];
+  const tr = (pr[8] + 1) / pr[0];
+  const tb = (pr[9] - 1) / pr[5];
+  const tt = (pr[9] + 1) / pr[5];
+  const h = P.t * P.D;
+  const cx = u[0] + 0.5 * (tl + tr) * u[2];
+  const cy = u[1] + 0.5 * (tb + tt) * u[2];
+  const hy = 0.5 * (tt - tb) * u[2];
+  return Math.max(rot, Math.abs(cx) / h, Math.abs(cy) / h, Math.abs(hy - h) / h);
+}
+
+/** The worst view's residual for portal P (Infinity when P is null). */
+export function viewsResidual(entries, P) {
+  if (!P || !entries?.length) return Infinity;
+  let r = 0;
+  for (const e of entries) r = Math.max(r, viewResidual(e, P));
+  return r;
+}
+
+function mul4(a, b, out = new Float64Array(16)) {
+  const r = new Float64Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let row = 0; row < 4; row++) {
+      r[c * 4 + row] = a[row] * b[c * 4] + a[4 + row] * b[c * 4 + 1] + a[8 + row] * b[c * 4 + 2] + a[12 + row] * b[c * 4 + 3];
+    }
+  }
+  out.set(r);
+  return out;
+}
+
+/** Inverse of an affine column-major 4×4 (last row 0 0 0 1). Null when singular. */
+export function invertAffine(m, out = new Float64Array(16)) {
+  const a = m[0], b = m[4], c = m[8];
+  const d = m[1], e = m[5], f = m[9];
+  const g = m[2], h = m[6], i = m[10];
+  const A = e * i - f * h, B = -(d * i - f * g), C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  if (!(Math.abs(det) > 1e-300)) return null;
+  const k = 1 / det;
+  const r00 = A * k, r01 = -(b * i - c * h) * k, r02 = (b * f - c * e) * k;
+  const r10 = B * k, r11 = (a * i - c * g) * k, r12 = -(a * f - c * d) * k;
+  const r20 = C * k, r21 = -(a * h - b * g) * k, r22 = (a * e - b * d) * k;
+  const tx = m[12], ty = m[13], tz = m[14];
+  out[0] = r00; out[1] = r10; out[2] = r20; out[3] = 0;
+  out[4] = r01; out[5] = r11; out[6] = r21; out[7] = 0;
+  out[8] = r02; out[9] = r12; out[10] = r22; out[11] = 0;
+  out[12] = -(r00 * tx + r01 * ty + r02 * tz);
+  out[13] = -(r10 * tx + r11 * ty + r12 * tz);
+  out[14] = -(r20 * tx + r21 * ty + r22 * tz);
+  out[15] = 1;
+  return out;
+}
+
+/**
+ * The eyes of target portal T for the same physical eyes that produced these views of portal F
+ * (dxr_display3d_apply_eye_factors_n inverted for F, re-applied for T). Rig space.
+ */
+export function mapEyes(entries, F, T) {
+  const n = entries.length;
+  const l = [];
+  const c = [0, 0, 0];
+  for (const e of entries) {
+    const d = [e.pose[12] - F.N0[0], e.pose[13] - F.N0[1], e.pose[14] - F.N0[2]];
+    const v = [dot(F.right, d) / F.m, dot(F.up, d) / F.m, dot(F.back, d) / F.m];
+    l.push(v);
+    c[0] += v[0] / n; c[1] += v[1] / n; c[2] += v[2] / n;
+  }
+  const kc = T.par / F.par;
+  const ko = T.ipd / F.ipd;
+  return l.map((v) => {
+    const w = [0, 1, 2].map((k) => T.m * (kc * c[k] + ko * (v[k] - c[k])));
+    return [0, 1, 2].map((k) => T.N0[k] + T.right[k] * w[0] + T.up[k] * w[1] + T.back[k] * w[2]);
+  });
+}
+
+/**
+ * The affine map A (column-major 4×4) that sends F's window onto T's window (in-plane scale σ)
+ * and eye Ef onto eye Et. Null when either eye is not in front of its window.
+ */
+export function portalMap(F, T, Ef, Et, sigma = (T.t * T.D) / (F.t * F.D)) {
+  const uf = local(F, Ef);
+  const ut = local(T, Et);
+  if (!(uf[2] > 0) || !(ut[2] > 0)) return null;
+  // L (window-local, F → T): [σ 0 ax; 0 σ ay; 0 0 az], with L·uf = ut.
+  const ax = (ut[0] - sigma * uf[0]) / uf[2];
+  const ay = (ut[1] - sigma * uf[1]) / uf[2];
+  const az = ut[2] / uf[2];
+  // A(X) = Wc_T + B_T · L · B_Fᵀ · (X − Wc_F), B = [right up back] (columns).
+  const BT = [T.right, T.up, T.back];
+  const BF = [F.right, F.up, F.back];
+  const Lc = [[sigma, 0, 0], [0, sigma, 0], [ax, ay, az]]; // columns of L
+  // M = B_T · L · B_Fᵀ: column j = Σ_k (B_T · L)_col_k · BF[k][j]
+  const TL = Lc.map((col) => [0, 1, 2].map((r) => BT[0][r] * col[0] + BT[1][r] * col[1] + BT[2][r] * col[2]));
+  const A = new Float64Array(16);
+  for (let j = 0; j < 3; j++) {
+    for (let r = 0; r < 3; r++) A[j * 4 + r] = TL[0][r] * BF[0][j] + TL[1][r] * BF[1][j] + TL[2][r] * BF[2][j];
+  }
+  for (let r = 0; r < 3; r++) A[12 + r] = T.Wc[r] - (A[r] * F.Wc[0] + A[4 + r] * F.Wc[1] + A[8 + r] * F.Wc[2]);
+  A[15] = 1;
+  return { A, az };
+}
+
+/** Rewrite a projection's depth rows for near/far divided by `k` (the map's depth scale). */
+function scaleDepth(P, k, out) {
+  out.set(P);
+  if (!(k > 0) || k === 1) return out;
+  if (Math.abs(P[11] + 1) > 1e-6 || Math.abs(P[15]) > 1e-6) return out; // not a perspective: leave it
+  const n = P[14] / (P[10] - 1);
+  if (Math.abs(P[10] + 1) < 1e-9) {
+    out[14] = -2 * (n / k); // infinite far: only the near plane moves
+    return out;
+  }
+  const f = P[14] / (P[10] + 1);
+  const n2 = n / k;
+  const f2 = f / k;
+  out[10] = -(f2 + n2) / (f2 - n2);
+  out[14] = (-2 * f2 * n2) / (f2 - n2);
+  return out;
+}
+
+/**
+ * These views (located for portal F) as portal T's views. Per view: { proj, viewInv, view, eye }
+ * — what RenderView.setView takes, and the target eye (rig space) for the camera node. Null when
+ * there is nothing to do (F and T the same portal) or the map does not exist (an eye at or behind
+ * a window): the caller keeps the views as they are.
+ */
+export function remapViews(entries, F, T, into = []) {
+  if (!F || !T || !entries?.length) return null;
+  if (F === T) return null;
+  const Et = mapEyes(entries, F, T);
+  const sigma = (T.t * T.D) / (F.t * F.D);
+  into.length = entries.length;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const Ef = [e.pose[12], e.pose[13], e.pose[14]];
+    const pm = portalMap(F, T, Ef, Et[i], sigma);
+    if (!pm) return null;
+    const o = (into[i] ||= { proj: new Float64Array(16), viewInv: new Float64Array(16), view: new Float64Array(16), eye: [0, 0, 0] });
+    mul4(pm.A, e.pose, o.viewInv);
+    if (!invertAffine(o.viewInv, o.view)) return null;
+    scaleDepth(e.proj, pm.az, o.proj);
+    o.eye[0] = Et[i][0];
+    o.eye[1] = Et[i][1];
+    o.eye[2] = Et[i][2];
+    o.x = e.x;
+    o.y = e.y;
+    o.width = e.width;
+    o.height = e.height;
+  }
+  return into;
+}
+
+/** Two portals with the same window (pose, convergence, vertical FOV) — only their eyes can differ. */
+export function sameWindow(a, b) {
+  return a.D === b.D && a.t === b.t && a.N0.every((x, k) => x === b.N0[k]) && a.q.every((x, k) => x === b.q[k]);
+}
+
+/** Rigid pose matrix (column-major) from a portal's orientation at `eye` — a camera node's pose. */
+export function nodePose(T, eye, out = new Float64Array(16)) {
+  out[0] = T.right[0]; out[1] = T.right[1]; out[2] = T.right[2]; out[3] = 0;
+  out[4] = T.up[0]; out[5] = T.up[1]; out[6] = T.up[2]; out[7] = 0;
+  out[8] = T.back[0]; out[9] = T.back[1]; out[10] = T.back[2]; out[11] = 0;
+  out[12] = eye[0]; out[13] = eye[1]; out[14] = eye[2]; out[15] = 1;
+  return out;
+}
+
+/**
+ * The rigs this tile declared, newest last, and which one a view set was located for.
+ * `note(rig)` on every declaration; `locate(entries)` per drawn frame.
+ */
+export class RigTracker {
+  constructor({ history = RIG_HISTORY, tol = RIG_MATCH_TOL } = {}) {
+    this.history = history;
+    this.tol = tol;
+    /** [{ id, rig (snapshot), portal (or null) }], oldest first. */
+    this.rigs = [];
+    this._seq = 0;
+  }
+
+  /** A declaration (the value, not the object: the SDK rewrites its descriptor in place). */
+  note(rig) {
+    const snap = rigSnapshot(rig);
+    const last = this.rigs[this.rigs.length - 1];
+    if (last && sameRig(last.rig, snap)) return last;
+    const entry = { id: ++this._seq, rig: snap, portal: cameraPortal(snap) };
+    this.rigs.push(entry);
+    if (this.rigs.length > this.history) this.rigs.splice(0, this.rigs.length - this.history);
+    return entry;
+  }
+
+  /** The rig declared last (what the drawing photo wants now), or null. */
+  get latest() {
+    return this.rigs[this.rigs.length - 1] || null;
+  }
+
+  /**
+   * The declared camera rig these views were located for, or null when none matches within
+   * tolerance (a display rig, a runtime clamp, a rig older than the history).
+   *
+   * The views pin down the WINDOW (pose, convergence, vertical FOV) exactly, but not the eye
+   * factors: any eyes are consistent with a window (metersToVirtual, ipdFactor and
+   * parallaxFactor only move the eyes). When several candidates match — rigs that differ ONLY in
+   * those — `prefer` wins if it is among them (the rig declared when these views were pulled:
+   * Blink's one frame of latency), else the newest.
+   */
+  locate(entries, prefer = null) {
+    let best = null;
+    let bestR = Infinity;
+    const matches = [];
+    for (let i = this.rigs.length - 1; i >= 0; i--) {
+      const c = this.rigs[i];
+      if (!c.portal) continue;
+      const r = viewsResidual(entries, c.portal);
+      if (r <= this.tol) matches.push(c); // newest first
+      if (r < bestR) {
+        bestR = r;
+        best = c;
+      }
+    }
+    this.lastResidual = bestR;
+    if (!best || !(bestR <= this.tol)) return null;
+    // Among the rigs sharing the best match's window (they differ only in the eye factors):
+    // `prefer` if it is one of them, else the newest.
+    const group = matches.filter((c) => sameWindow(c.portal, best.portal));
+    return group.includes(prefer) ? prefer : group[0];
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.23.0",
+  "version": "1.24.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",
@@ -55,6 +55,7 @@
     "js/inline3d-splat-diag.js",
     "js/inline3d-splat-video.js",
     "js/inline3d-splat-layer-rig.js",
+    "js/inline3d-splat-rig-map.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",

package/splat.d.ts

@@ -277,11 +277,12 @@ export interface SplatOptions {
    * A string / array adds A/B kill switches (also accepted as `?dxrdiag=norig,frozen`): `'norig'`
    * keeps the rig declared before the first setSource (drops every re-declaration), `'frozen'`
    * forces `outgoing: 'frozen'`, `'nowarm'` skips the transition shader pre-warm, `'cold'` skips
-   * the live outgoing pre-sort, `'nooverlay'` records without the overlay. The option wins over the
+   * the live outgoing pre-sort, `'nooverlay'` records without the overlay, `'oldrig'` draws the
+   * views as located (no rig tracking; the live outgoing photo on the pre-1.24 chain). The option wins over the
    * URL; `false` turns it off even with `?dxrdiag` present. See docs/playcanvas-adapter.md
    * § Diagnosing transition stalls.
    */
-  diag?: boolean | string | ReadonlyArray<'norig' | 'frozen' | 'nowarm' | 'cold' | 'nooverlay' | '1'>;
+  diag?: boolean | string | ReadonlyArray<'norig' | 'frozen' | 'nowarm' | 'cold' | 'nooverlay' | 'oldpick' | 'nolayerrig' | 'oldrig' | '1'>;
   /**
    * `engine: 'playcanvas'` only: the WebGL context's `preserveDrawingBuffer` (default false) —
    * the knob for the weave's zero-copy read race on large canvases.