@displayxr/inline3d 1.19.2 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.
 
+## Unreleased
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No pixel change at rest; the
+first frames of a live `crossfade` / `wavefront` / particle transition change (see Fixed).
+
+### Added
+
+- **Transition diagnostics: `diag` / `?dxrdiag`** (#36). Off by default. Records every woven
+  frame (interval, whether its eye poses are bit-identical to the previous frame's, what the
+  transition overlay shows), every `setViewRig` push with its values, long tasks and the
+  `setSource` phases. Shows a small overlay excluded from the weave, logs one
+  `[dxr-diag] transition #N <verdict>` line per transition, and exposes `window.__dxrDiag`
+  (`copy(__dxrDiag.dump())`). Kill switches for A/B: `norig`, `frozen`, `nowarm`, `cold`,
+  `nooverlay`. See `docs/playcanvas-adapter.md` § Diagnosing transition stalls.
+
+### Fixed
+
+- **The live outgoing photo no longer starts as a still** (#36). A live transition put the old
+  photo on a FRESH gsplat manager at the swap, and until that manager's first sort came back the
+  overlay showed the frozen capture at full weight: the whole picture stood still for 2–7 frames
+  right as the transition started. The live camera now pre-sorts the current photo BEFORE the swap
+  (it stays on screen, untouched, meanwhile), so the overlay samples the live image from the swap
+  frame on: 0 frozen frames. The transition starts later by about the length of that sort instead
+  (bounded at 1.5 s, then the old bridge). `?dxrdiag=cold` restores the 1.19.2 path.
+
+## 1.19.3 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `./model`). No API change and no pixel change on a core that
+has view rigs.
+
+### Fixed
+
+- **A view rig the wall cannot take is no longer dropped silently** (#36).
+  - Every scene backend (`./splat` Spark and PlayCanvas, `./model` PlayCanvas) declared its rig
+    with `handle?.setViewRig?.(rig)`. On a handle from a core that predates view rigs, that call
+    does nothing.
+  - A page that vendors an older `inline3d.js` and hands that wall to `./splat` therefore had its
+    CAMERA rig thrown away. The wall wove the metric photo scene on the `addScene` display-rig
+    shorthand (`virtualDisplayHeight` 0.24): way off in convergence and scale in 3D, correct in 2D.
+    That is how the gallery's Spatial View wall regressed; the rig this SDK declared was the same
+    from 1.8.0 to 1.19.2.
+  - Now it logs one `console.warn` per page ("the view rig was dropped: your inline3d core
+    predates view rigs …") carrying the dropped rig.
+  - The Spark path used `handle?.setViewRig(…)` without the second `?.`, so it would have THROWN
+    there. It now takes the same warning path.
+  - Regression tests pin the declared rig for a camera-rig asset with `zoom {1, 2, relax}` and the
+    `assemble` reveal, at rest and after the reveal, on the fake engine.
+
 ## 1.19.2 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change and no pixel

package/README.md

@@ -55,6 +55,8 @@ its own half, with no second canvas ([§setVideo](docs/playcanvas-adapter.md#set
 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).
+The repo's splat sample (`samples/splat/`) renders with PlayCanvas and keeps `?engine=spark` as
+its A/B switch.
 Bundlers: the engine is reached through a named-import module (`js/inline3d-playcanvas-engine.js`,
 so the unused ~40% of the engine tree-shakes away); its sort workers are Blob URLs (CSP
 `worker-src blob:`), and esbuild needs `node:worker_threads` marked external.
@@ -160,7 +162,7 @@ samples/
                       convergence + comfort, the attach pattern, C to A/B a display rig
   windows/            mixed 3D windows — still photos + a live video + a real-time three.js scene,
                       each woven with one SDK call, all on one session
-  splat/              a 3D Gaussian splat in a tile, auto-framed, with a 2D price plate over it
+  splat/              a 3D Gaussian splat in a tile (PlayCanvas; ?engine=spark), with a 2D plate over it
   model/              a glTF mesh, a mesh+splat scene, and a Draco-COMPRESSED glTF (PlayCanvas; ?engine=three)
   composition/        the 14-case 2D/3D overlap matrix — demo AND standing hardware regression
                       surface; red cases ship red (see samples/README.md)

package/THIRD_PARTY_NOTICES.md

@@ -74,3 +74,15 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+## Sample assets (repo samples only, not in the npm package)
+
+The pages under `samples/` show these assets. None is in the published `@displayxr/inline3d`
+package.
+
+| Asset | Used by | Source | Credit and licence |
+|---|---|---|---|
+| Damaged Helmet (`DamagedHelmet.glb`) | `samples/model/` (tiles A and B), loaded at run time, not vendored | [KhronosGroup/glTF-Sample-Assets](https://github.com/KhronosGroup/glTF-Sample-Assets/tree/c6a6bd13ab2b3c685c7903d03561b8a9392f38b8/Models/DamagedHelmet) at commit `c6a6bd13ab2b3c685c7903d03561b8a9392f38b8`, via jsDelivr, unmodified | © 2018 ctxwing (rebuild and conversion to glTF 2.0), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). Earlier version of the model ("Battle Damaged Sci-fi Helmet") © 2016 theblueturtle_, [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/legalcode). As stated in the asset's `README.md` and `LICENSE.md`. |
+| Duck, Draco variant (`samples/model/assets/glTF-Draco/`) | `samples/model/` (tile C) | Khronos glTF-Sample-Assets | © Sony, [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). |
+| Butterfly splat (`samples/splat/assets/butterfly.sog`) | `samples/splat/`, `samples/model/` (tile B) | [Spark](https://sparkjs.dev/) `assets/splats/butterfly.spz`, converted to SOG with PlayCanvas splat-transform (177,132 gaussians, 3 SH bands kept) | Butterfly splat © World Labs (from Spark, sparkjs.dev), used with permission; converted to SOG. |
+| Draco decoder (`vendor/draco/`) | `samples/model/` | three.js `examples/jsm/libs/draco/` | © The Draco Authors, Apache-2.0. |

package/js/inline3d-model-playcanvas.js

@@ -38,7 +38,7 @@
 //       └── eye camera, N RenderViews, TONEMAP_NEUTRAL, no sky layer
 
 import { PlayCanvasSplatViewer, pageRigTRS, pageViewAxis, pageViewRig } from './inline3d-splat-playcanvas.js';
-import { resolveControls, normalizeCameraPose, now, MAX_DT_S } from './inline3d-splat-shared.js';
+import { resolveControls, normalizeCameraPose, now, MAX_DT_S, declareViewRig } from './inline3d-splat-shared.js';
 import {
   NEUTRAL_STUDIO,
   neutralStudioRadiance,
@@ -551,7 +551,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
         if (dm > 0) d = dm / (ax.scale || 1);
       }
       out.viewRig = pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: d ?? 2, comfortDepth: ctl.comfortDepth }, out.viewRig || {});
-      handle?.setViewRig?.(out.viewRig);
+      declareViewRig(handle, out.viewRig);
     };
     if (typeof opts.onBeforeFrame === 'function') {
       const cb = opts.onBeforeFrame;

package/js/inline3d-splat-diag.js

@@ -0,0 +1,599 @@
+// inline3d-splat-diag.js — transition diagnostics for the PlayCanvas splat handle (#36).
+//
+// Internal. Used by ./inline3d-splat-playcanvas.js only. Off unless the page asks for it:
+// `addSplat(..., { engine: 'playcanvas', diag: true })`, or `?dxrdiag=1` on the page URL.
+//
+// WHY. "Head tracking stops for a moment at every photo transition" has four candidate causes
+// that look identical on the panel, and only one of them is visible from a headless browser:
+//   - a MAIN-THREAD stall: the page misses session frames, so nothing new is drawn. Shows here as
+//     a gap in the session-frame intervals (and in the window rAF), usually with a long task.
+//   - a TRACKING hold: frames keep coming, but the eye poses in them do not move. The browser
+//     keeps the last good views when a locate reply comes back empty, and reuses the previous
+//     reply while its UI thread is busy. Shows here as frames whose XRView transforms are
+//     BIT-IDENTICAL to the previous frame's (a live eye tracker never repeats itself exactly).
+//   - a FROZEN IMAGE: frames come, poses move, but what is on screen is a still capture (the
+//     crossfade's frozen bridge, shown until the live outgoing camera has sorted). Shows here as
+//     frames where the transition overlay samples the frozen capture at a high weight.
+//   - a RIG change applied late or badly: every setViewRig push is logged with its values, so a
+//     pose jump or a hold can be lined up against the rig it followed.
+// Each frame of the session is recorded with all four, so one run on the panel says which.
+//
+// KILL SWITCHES, for A/B on the panel (comma-separated, in `diag` or in `?dxrdiag=`):
+//   norig    — the rig declared before the first setSource stays declared; every later
+//              re-declaration is DROPPED (logged as dropped). Tests "the rig change freezes it".
+//   frozen   — force `outgoing: 'frozen'` (the 1.12.1 frozen outgoing photo) on every setSource.
+//   nowarm   — skip the transition shader pre-warm (prepareSource / setSource compile nothing).
+//   cold     — skip the live outgoing PRE-SORT (the 1.19.2 behaviour: the frozen capture bridges
+//              until a fresh manager has sorted).
+//   nooverlay — record + console + window.__dxrDiag, but no on-screen overlay.
+
+/** The switches `diag` / `?dxrdiag` understand, besides the plain on values. */
+export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay']);
+const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
+
+/**
+ * `diag` option (true | string | string[]) and/or the page query, into { on, switches }.
+ * The option wins when it is given (false turns diag off even with `?dxrdiag` on the URL).
+ * Unknown tokens are returned in `unknown` (warned once by the caller), never thrown on: a
+ * diagnostic flag must not be able to break a page.
+ */
+export function resolveDiag(opt, search = pageSearch()) {
+  let raw = null;
+  if (opt === false) return { on: false, switches: new Set(), unknown: [] };
+  if (opt === true) raw = '1';
+  else if (typeof opt === 'string') raw = opt;
+  else if (Array.isArray(opt)) raw = opt.join(',');
+  else if (opt === undefined || opt === null) raw = queryValue(search);
+  if (raw === null) return { on: false, switches: new Set(), unknown: [] };
+  const switches = new Set();
+  const unknown = [];
+  for (const tok of String(raw).split(/[,\s+]+/).map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+    if (ON_TOKENS.has(tok)) continue;
+    if (tok === '0' || tok === 'off' || tok === 'false') return { on: false, switches: new Set(), unknown: [] };
+    if (DIAG_SWITCHES.includes(tok)) switches.add(tok);
+    else unknown.push(tok);
+  }
+  return { on: true, switches, unknown };
+}
+
+function pageSearch() {
+  try {
+    return typeof location !== 'undefined' && typeof location.search === 'string' ? location.search : '';
+  } catch {
+    return '';
+  }
+}
+
+/** `?dxrdiag=...` (every occurrence, joined), or null when absent. `?dxrdiag` alone = on. */
+function queryValue(search) {
+  if (!search) return null;
+  let q;
+  try {
+    q = new URLSearchParams(search);
+  } catch {
+    return null;
+  }
+  if (!q.has('dxrdiag')) return null;
+  const all = q.getAll('dxrdiag').map((v) => v || '1');
+  return all.join(',');
+}
+
+/**
+ * One frame's eye-pose metrics against the previous frame's views.
+ *   held   — every view's transform AND projection bit-identical to the previous frame (a hold:
+ *            a live tracker never repeats itself to the last bit).
+ *   delta  — the largest eye-position move, in the views' world units.
+ *   ipd    — the eye separation this frame, same units (it scales with the rig).
+ *   rel    — delta / ipd: head motion in eye separations, comparable across rigs.
+ * `prev` is the previous frame's packed state (or null); returns { m, state }, `state` being
+ * this frame's packed copy for the next call.
+ */
+export function poseDelta(views, prev) {
+  const n = views ? views.length : 0;
+  const state = new Float64Array(n * 32);
+  for (let i = 0; i < n; i++) {
+    const t = views[i]?.transform?.matrix;
+    const p = views[i]?.projectionMatrix;
+    for (let k = 0; k < 16; k++) {
+      state[i * 32 + k] = t ? t[k] : NaN;
+      state[i * 32 + 16 + k] = p ? p[k] : NaN;
+    }
+  }
+  const m = { views: n, held: false, delta: NaN, ipd: NaN, rel: NaN };
+  if (n >= 2) {
+    const dx = state[12] - state[32 + 12];
+    const dy = state[13] - state[32 + 13];
+    const dz = state[14] - state[32 + 14];
+    m.ipd = Math.hypot(dx, dy, dz);
+  }
+  if (prev && prev.length === state.length && n > 0) {
+    let same = true;
+    for (let k = 0; k < state.length; k++) {
+      if (!Object.is(state[k], prev[k])) {
+        same = false;
+        break;
+      }
+    }
+    m.held = same;
+    let d = 0;
+    for (let i = 0; i < n; i++) {
+      const o = i * 32;
+      d = Math.max(d, Math.hypot(state[o + 12] - prev[o + 12], state[o + 13] - prev[o + 13], state[o + 14] - prev[o + 14]));
+    }
+    m.delta = d;
+    m.rel = m.ipd > 0 ? d / m.ipd : NaN;
+  }
+  return { m, state };
+}
+
+/** A view rig descriptor, summarised for the log (numbers rounded; nothing else kept). */
+export function summarizeRig(rig) {
+  if (!rig || typeof rig !== 'object') return { type: rig === null ? 'none' : typeof rig };
+  const r4 = (x) => (Number.isFinite(x) ? Math.round(x * 1e4) / 1e4 : x);
+  const out = {};
+  const walk = (o, prefix, depth) => {
+    for (const [k, v] of Object.entries(o)) {
+      const key = prefix ? `${prefix}.${k}` : k;
+      if (typeof v === 'number') out[key] = r4(v);
+      else if (typeof v === 'string' || typeof v === 'boolean') out[key] = v;
+      else if (v && typeof v === 'object' && depth < 2 && !ArrayBuffer.isView(v)) walk(v, key, depth + 1);
+    }
+  };
+  walk(rig, '', 0);
+  return out;
+}
+
+/** Phase names, in order: prepare (prepareSource), swap (setSource → adopt), window, settle. */
+export const DIAG_PHASES = Object.freeze(['idle', 'prepare', 'swap', 'window', 'settle']);
+
+const FRAME_CAP = 1800; // ~30 s at 60 Hz
+const EVENT_CAP = 600;
+const SETTLE_MS = 1000; // a transition's summary covers its window + this much after it
+const PRE_MS = 300; // ... and this much before the setSource call
+
+/**
+ * The recorder. `now` is injectable (tests); everything else is plain data, so the recorder runs
+ * (and is tested) without a DOM. The overlay (attachOverlay) is optional on top.
+ */
+export class DiagRecorder {
+  constructor({ switches = new Set(), now = () => performance.now(), log = defaultLog, label = 'splat' } = {}) {
+    this.switches = switches;
+    this.now = now;
+    this.log = log;
+    this.label = label;
+    this.frames = [];
+    this.events = [];
+    this.transitions = [];
+    this.phase = 'idle';
+    this.phaseAt = 0;
+    this.callAt = NaN; // the current / last setSource call
+    this._prevState = null;
+    this._lastFrameAt = NaN;
+    this._lastRafAt = NaN;
+    this._rigAt = -Infinity;
+    this._rigFrame = -Infinity;
+    this._frameNo = 0;
+    this._open = null; // the transition being recorded
+    this.imageState = null; // () => { overlay: 'none' | 'frozen' | 'live', w }
+    this.longTasks = [];
+    this._lto = null;
+    this.rigLocked = null; // norig: the summary of the rig kept
+    this._listeners = new Set();
+  }
+
+  has(sw) {
+    return this.switches.has(sw);
+  }
+
+  /** Observe long tasks (where the browser has the API). */
+  observeLongTasks() {
+    try {
+      if (typeof PerformanceObserver !== 'function') return;
+      this._lto = new PerformanceObserver((list) => {
+        for (const e of list.getEntries()) this.longTask(e.startTime, e.duration);
+      });
+      this._lto.observe({ type: 'longtask', buffered: false });
+    } catch {
+      this._lto = null;
+    }
+  }
+
+  longTask(start, duration) {
+    const lt = { s: round1(start), d: round1(duration) };
+    this.longTasks.push(lt);
+    if (this.longTasks.length > EVENT_CAP) this.longTasks.splice(0, this.longTasks.length - EVENT_CAP);
+    this._event('longtask', lt, start);
+  }
+
+  /** A window rAF tick (the diag's own loop): main-thread cadence independent of the session. */
+  raf(t = this.now()) {
+    const gap = Number.isFinite(this._lastRafAt) ? t - this._lastRafAt : NaN;
+    this._lastRafAt = t;
+    if (this._open && Number.isFinite(gap)) this._open.maxRafGap = Math.max(this._open.maxRafGap, gap);
+    return gap;
+  }
+
+  /** One session frame (the woven path's onFrame), BEFORE the draw. */
+  frame(views, t = this.now()) {
+    const { m, state } = poseDelta(views, this._prevState);
+    this._prevState = state;
+    const dt = Number.isFinite(this._lastFrameAt) ? t - this._lastFrameAt : NaN;
+    this._lastFrameAt = t;
+    this._frameNo++;
+    const img = this.imageState ? safe(this.imageState) : null;
+    const f = {
+      n: this._frameNo,
+      t: round1(t),
+      dt: round1(dt),
+      phase: this.phase,
+      sinceCall: Number.isFinite(this.callAt) ? round1(t - this.callAt) : null,
+      views: m.views,
+      held: m.held,
+      delta: round6(m.delta),
+      rel: round4(m.rel),
+      ipd: round6(m.ipd),
+      // A rig push in the last 3 frames: a pose jump here is the rig, not the head.
+      afterRig: this._frameNo - this._rigFrame <= 3,
+      img: img ? img.overlay : 'none',
+      imgW: img ? round4(img.w) : 0,
+    };
+    this.frames.push(f);
+    if (this.frames.length > FRAME_CAP) this.frames.splice(0, this.frames.length - FRAME_CAP);
+    if (this._open) this._accumulate(this._open, f);
+    this._maybeClose(t);
+    this._emit();
+    return f;
+  }
+
+  /** A setViewRig push (or, under `norig`, a dropped one). */
+  rig(rig, { dropped = false } = {}) {
+    const t = this.now();
+    const s = summarizeRig(rig);
+    // controls:'page' re-declares every frame: only a CHANGED rig is an event.
+    const key = (dropped ? 'd' : 'p') + JSON.stringify(s);
+    if (key === this._lastRigKey) {
+      this.rigRepeats = (this.rigRepeats || 0) + 1;
+      return null;
+    }
+    this._lastRigKey = key;
+    this._rigAt = t;
+    if (!dropped) this._rigFrame = this._frameNo;
+    const ev = this._event(dropped ? 'rig-dropped' : 'rig', { rig: s }, t);
+    if (this._open) this._open.rigs.push({ at: round1(t - this._open.callAt), dropped, rig: s });
+    this.log(`${dropped ? 'rig DROPPED (norig)' : 'rig'} ${fmtT(this, t)} ${JSON.stringify(s)}`);
+    return ev;
+  }
+
+  /** Enter a phase ('prepare', 'swap', 'window', 'settle', 'idle'); `detail` is logged with it. */
+  setPhase(phase, detail) {
+    const t = this.now();
+    if (phase === 'swap') this._openTransition(t, detail);
+    this.phase = phase;
+    this.phaseAt = t;
+    if (this._open) this._open.phases.push({ phase, at: round1(t - this._open.callAt), ...(detail ? { detail } : {}) });
+    this._event('phase', { phase, ...(detail ? { detail } : {}) }, t);
+    this.log(`phase ${phase} ${fmtT(this, t)}${detail ? ' ' + JSON.stringify(detail) : ''}`);
+    if (phase === 'settle' && this._open) this._open.settleAt = t;
+  }
+
+  /** A named instant inside the current transition (e.g. 'presorted', 'live-shown'). */
+  mark(name, detail) {
+    const t = this.now();
+    if (this._open) this._open.marks.push({ name, at: round1(t - this._open.callAt), ...(detail ? { detail } : {}) });
+    this._event('mark', { name, ...(detail ? { detail } : {}) }, t);
+    this.log(`mark ${name} ${fmtT(this, t)}${detail ? ' ' + JSON.stringify(detail) : ''}`);
+  }
+
+  _openTransition(t, detail) {
+    if (this._open) this._close(this._open, t, 'superseded');
+    this.callAt = t;
+    this._open = {
+      id: this.transitions.length + 1,
+      callAt: t,
+      detail: detail || null,
+      settleAt: NaN,
+      phases: [],
+      marks: [],
+      rigs: [],
+      frames: 0,
+      maxFrameGap: 0,
+      maxRafGap: 0,
+      held: 0,
+      heldRun: 0,
+      heldRunMax: 0,
+      heldRunMaxMs: 0,
+      _heldRunStart: NaN,
+      frozenImg: 0,
+      frozenImgMs: 0,
+      _lastT: NaN,
+      firstFrameAt: NaN,
+      lastFrameAt: NaN,
+      window: [], // the frame records kept for the frozen overlay strip
+    };
+    // Frames already recorded in the lead-in (PRE_MS before the call) belong to it too.
+    for (const f of this.frames) if (f.t >= t - PRE_MS) this._open.window.push(f);
+  }
+
+  _accumulate(o, f) {
+    o.frames++;
+    o.window.push(f);
+    if (!Number.isFinite(o.firstFrameAt)) o.firstFrameAt = f.t;
+    o.lastFrameAt = f.t;
+    if (Number.isFinite(f.dt)) o.maxFrameGap = Math.max(o.maxFrameGap, f.dt);
+    if (f.held) {
+      o.held++;
+      if (o.heldRun === 0) o._heldRunStart = Number.isFinite(f.dt) ? f.t - f.dt : f.t;
+      o.heldRun++;
+      if (o.heldRun > o.heldRunMax) {
+        o.heldRunMax = o.heldRun;
+        o.heldRunMaxMs = round1(f.t - o._heldRunStart);
+      }
+    } else o.heldRun = 0;
+    if (f.img === 'frozen' && f.imgW >= 0.5) {
+      o.frozenImg++;
+      if (Number.isFinite(f.dt)) o.frozenImgMs = round1(o.frozenImgMs + f.dt);
+    }
+  }
+
+  _maybeClose(t) {
+    const o = this._open;
+    if (o && Number.isFinite(o.settleAt) && t - o.settleAt >= SETTLE_MS) this._close(o, t, 'settled');
+  }
+
+  /** Force the open transition's summary now (tests, or a page that wants it early). */
+  flush() {
+    if (this._open) this._close(this._open, this.now(), 'flushed');
+  }
+
+  _close(o, t, how) {
+    this._open = null;
+    if (how === 'settled' && this.phase === 'settle') {
+      this.phase = 'idle';
+      this.phaseAt = t;
+    }
+    const lts = this.longTasks.filter((e) => e.s + e.d > o.callAt - PRE_MS && e.s < t);
+    const s = {
+      id: o.id,
+      how,
+      detail: o.detail,
+      at: round1(o.callAt),
+      windowMs: Number.isFinite(o.settleAt) ? round1(o.settleAt - o.callAt) : null,
+      phases: o.phases,
+      marks: o.marks,
+      rigs: o.rigs,
+      frames: o.frames,
+      maxFrameGapMs: round1(o.maxFrameGap),
+      maxRafGapMs: round1(o.maxRafGap),
+      longTasks: lts.map((e) => ({ at: round1(e.s - o.callAt), d: e.d })),
+      longestTaskMs: lts.length ? Math.max(...lts.map((e) => e.d)) : 0,
+      heldFrames: o.held,
+      heldRunMax: o.heldRunMax,
+      heldRunMaxMs: o.heldRunMaxMs,
+      frozenImageFrames: o.frozenImg,
+      frozenImageMs: o.frozenImgMs,
+    };
+    s.verdict = verdict(s);
+    s.window = o.window.map((f) => ({ ...f, t: round1(f.t - o.callAt) }));
+    this.transitions.push(s);
+    if (this.transitions.length > 50) this.transitions.shift();
+    const { window: _w, ...brief } = s;
+    this.log(`transition #${s.id} ${s.verdict} ${JSON.stringify(brief)}`);
+    this._emit(s);
+  }
+
+  _event(type, data, t = this.now()) {
+    const ev = { ...data, type, t: round1(t), sinceCall: Number.isFinite(this.callAt) ? round1(t - this.callAt) : null };
+    this.events.push(ev);
+    if (this.events.length > EVENT_CAP) this.events.splice(0, this.events.length - EVENT_CAP);
+    return ev;
+  }
+
+  onUpdate(cb) {
+    this._listeners.add(cb);
+    return () => this._listeners.delete(cb);
+  }
+
+  _emit(summary) {
+    for (const cb of this._listeners) safe(() => cb(summary));
+  }
+
+  /** Everything, as plain JSON (what David pastes back). */
+  toJSON() {
+    return {
+      label: this.label,
+      switches: [...this.switches],
+      rigLocked: this.rigLocked,
+      transitions: this.transitions,
+      events: this.events,
+      frames: this.frames,
+    };
+  }
+
+  dump() {
+    return JSON.stringify(this.toJSON());
+  }
+
+  dispose() {
+    try {
+      this._lto?.disconnect();
+    } catch {
+      /* already gone */
+    }
+    this._lto = null;
+    this._listeners.clear();
+  }
+}
+
+/**
+ * The one-line verdict. Thresholds: a session-frame gap > 50 ms (three missed frames at 60 Hz) is
+ * a stall; 2+ consecutive bit-identical frames is a hold; 2+ frames of the frozen capture at
+ * weight >= 0.5 is a frozen image.
+ */
+export function verdict(s) {
+  const out = [];
+  if (s.heldRunMax >= 2) out.push(`TRACKING-HELD ${s.heldRunMax} frames (${s.heldRunMaxMs} ms) with frames still arriving`);
+  if (s.maxFrameGapMs > 50) out.push(`MAIN-THREAD gap ${s.maxFrameGapMs} ms (longest task ${s.longestTaskMs} ms)`);
+  if (s.frozenImageFrames >= 2) out.push(`IMAGE-FROZEN ${s.frozenImageFrames} frames (${s.frozenImageMs} ms) on the frozen capture`);
+  return out.length ? out.join(' + ') : 'CLEAN (no hold, no gap > 50 ms, no frozen image)';
+}
+
+function defaultLog(msg) {
+  if (typeof console !== 'undefined') console.info(`[dxr-diag] ${msg}`);
+}
+function fmtT(rec, t) {
+  return Number.isFinite(rec.callAt) ? `t=${round1(t - rec.callAt)}ms` : `t=${round1(t)}`;
+}
+function safe(fn) {
+  try {
+    return fn();
+  } catch {
+    return null;
+  }
+}
+const round1 = (x) => (Number.isFinite(x) ? Math.round(x * 10) / 10 : x);
+const round4 = (x) => (Number.isFinite(x) ? Math.round(x * 1e4) / 1e4 : x);
+const round6 = (x) => (Number.isFinite(x) ? Math.round(x * 1e6) / 1e6 : x);
+
+// ── the on-screen overlay (2D DOM; the caller excludes it from the weave) ─────────────────────
+
+const W = 360;
+const STRIP_H = 44;
+const WINDOW_MS = 3000;
+
+/**
+ * A compact overlay, fixed to the viewport's bottom-left: two strips (the rolling last 3 s, and
+ * the last transition, frozen at its settle) plus a text line. Per session frame, one bar: its
+ * height is the frame interval (0–100 ms), its colour what the frame was — blue normal, RED held
+ * (bit-identical poses), ORANGE the frozen capture on screen, GREY a rig push just before; the
+ * white line is the head motion (delta / eye separation). Repainted at ~10 Hz by the diag's own
+ * window rAF, which also measures the main thread's cadence (also without the overlay).
+ * Returns { el, remove } (el null without the overlay).
+ */
+export function startDiagLoop(rec, { overlay = true, doc = typeof document !== 'undefined' ? document : null } = {}) {
+  const hasRaf = typeof requestAnimationFrame === 'function';
+  if (!overlay || !doc?.createElement || !doc.body) {
+    // No overlay: the window rAF cadence is still measured (the main thread's own clock).
+    let raf = 0;
+    const tick = (t) => {
+      rec.raf(t);
+      raf = requestAnimationFrame(tick);
+    };
+    if (hasRaf) raf = requestAnimationFrame(tick);
+    return { el: null, remove: () => raf && typeof cancelAnimationFrame === 'function' && cancelAnimationFrame(raf) };
+  }
+  const el = doc.createElement('div');
+  el.setAttribute('data-dxr-diag', '');
+  el.style.cssText =
+    'position:fixed;left:8px;bottom:8px;z-index:2147483647;width:' +
+    W +
+    'px;padding:6px;background:rgba(0,0,0,0.78);color:#e8e8e8;font:11px/1.3 ui-monospace,Menlo,Consolas,monospace;' +
+    'border-radius:6px;pointer-events:none;white-space:pre-wrap;';
+  const head = doc.createElement('div');
+  const cv = doc.createElement('canvas');
+  cv.width = W;
+  cv.height = STRIP_H * 2 + 18;
+  cv.style.cssText = `display:block;width:${W}px;height:${STRIP_H * 2 + 18}px;margin:4px 0`;
+  const foot = doc.createElement('div');
+  el.append(head, cv, foot);
+  doc.body.appendChild(el);
+  const g = cv.getContext && cv.getContext('2d');
+  let frozen = null; // the last transition's summary
+  let raf = 0;
+  let lastPaint = 0;
+  const off = rec.onUpdate((s) => {
+    if (s) frozen = s;
+  });
+  const strip = (frames, y0, t0, t1, callT) => {
+    if (!g) return;
+    g.fillStyle = '#111';
+    g.fillRect(0, y0, W, STRIP_H);
+    const x = (t) => ((t - t0) / (t1 - t0)) * W;
+    if (Number.isFinite(callT)) {
+      g.fillStyle = '#555';
+      g.fillRect(Math.round(x(callT)), y0, 1, STRIP_H);
+    }
+    let prev = null;
+    for (const f of frames) {
+      if (f.t < t0 || f.t > t1) continue;
+      const h = Math.min(STRIP_H, (Number.isFinite(f.dt) ? f.dt : 0) * (STRIP_H / 100));
+      g.fillStyle = f.held ? '#ff3b30' : f.img === 'frozen' && f.imgW >= 0.5 ? '#ff9f0a' : f.afterRig ? '#8e8e93' : '#0a84ff';
+      g.fillRect(Math.round(x(f.t)), y0 + STRIP_H - h, 2, h);
+      if (Number.isFinite(f.rel)) {
+        const yy = y0 + STRIP_H - Math.min(STRIP_H, f.rel * STRIP_H * 20);
+        if (prev) {
+          g.strokeStyle = '#fff';
+          g.beginPath();
+          g.moveTo(prev[0], prev[1]);
+          g.lineTo(x(f.t), yy);
+          g.stroke();
+        }
+        prev = [x(f.t), yy];
+      } else prev = null;
+    }
+  };
+  const paint = (t) => {
+    rec.raf(t);
+    raf = typeof requestAnimationFrame === 'function' ? requestAnimationFrame(paint) : 0;
+    if (t - lastPaint < 100) return;
+    lastPaint = t;
+    const last = rec.frames[rec.frames.length - 1];
+    const now = last ? last.t : t;
+    head.textContent =
+      `dxr-diag ${rec.label}  phase ${rec.phase}` +
+      (Number.isFinite(rec.callAt) ? `  +${Math.round(now - rec.callAt)} ms since setSource` : '') +
+      (rec.switches.size ? `  [${[...rec.switches].join(',')}]` : '') +
+      (last ? `\nframe dt ${last.dt} ms  held ${last.held ? 'YES' : 'no'}  img ${last.img}${last.img !== 'none' ? ' ' + last.imgW : ''}` : '');
+    strip(rec.frames, 0, now - WINDOW_MS, now, rec.callAt);
+    if (frozen && g) {
+      strip(frozen.window.map((f) => ({ ...f })), STRIP_H + 18, -PRE_MS, WINDOW_MS - PRE_MS, 0);
+    }
+    if (g) {
+      g.clearRect(0, STRIP_H, W, 18); // the label band: repainted, never accumulated
+      g.fillStyle = '#e8e8e8';
+      g.font = '10px ui-monospace, monospace';
+      g.fillText(frozen ? `last transition #${frozen.id} (frozen)` : 'last transition: none yet', 4, STRIP_H + 13);
+    }
+    foot.textContent = frozen ? `#${frozen.id}: ${frozen.verdict}` : 'red = held poses · orange = frozen image · bar = frame interval';
+  };
+  raf = typeof requestAnimationFrame === 'function' ? requestAnimationFrame(paint) : 0;
+  return {
+    el,
+    remove() {
+      off();
+      if (raf && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(raf);
+      el.remove?.();
+    },
+  };
+}
+
+/**
+ * `window.__dxrDiag`: every diag tile on the page. `dump()` is the JSON to paste back;
+ * `last` the most recent tile's recorder; `transitions` every tile's transition summaries.
+ */
+export function registerDiag(rec) {
+  if (typeof window === 'undefined' || !window) return null;
+  let g = window.__dxrDiag;
+  if (!g || !Array.isArray(g.tiles)) {
+    g = window.__dxrDiag = {
+      tiles: [],
+      get last() {
+        return this.tiles[this.tiles.length - 1] || null;
+      },
+      get transitions() {
+        return this.tiles.flatMap((r) => r.transitions.map((s) => ({ tile: r.label, ...s })));
+      },
+      dump() {
+        return JSON.stringify({ ua: typeof navigator !== 'undefined' ? navigator.userAgent : null, at: new Date().toISOString(), tiles: this.tiles.map((r) => r.toJSON()) });
+      },
+    };
+  }
+  rec.label = `splat#${g.tiles.length + 1}`;
+  g.tiles.push(rec);
+  const dispose = rec.dispose.bind(rec);
+  rec.dispose = () => {
+    dispose();
+    const i = g.tiles.indexOf(rec);
+    if (i >= 0) g.tiles.splice(i, 1);
+  };
+  return g;
+}

package/js/inline3d-splat-live.js

@@ -148,6 +148,9 @@ export class LiveOutgoing {
     this.frames = 0;
     this.views = [];
     this._frustumKey = '';
+    /** PRE-SORT (warm): the current asset is ALSO on the live layer, before the swap. */
+    this.warming = false;
+    this._warmLayers = null;
   }
 
   /** Engine support for this path: RenderViews on one camera, render targets, layers. */
@@ -212,21 +215,94 @@ export class LiveOutgoing {
     this.w = this.h = 0;
   }
 
+  /**
+   * PRE-SORT the live camera BEFORE the swap (the fix for the frozen bridge, #36). The current
+   * asset goes on the live layer IN ADDITION to its own (the eye keeps drawing it, untouched: its
+   * World placement set is unchanged, so its manager neither rebuilds nor re-sorts), and the live
+   * camera starts rendering it, through the same views, into its target. Its manager builds its
+   * work buffer and runs its first sort NOW, while the photo is still on screen and live. At the
+   * swap, start() takes the asset OFF World only: the live layer's placement set does not change,
+   * so its manager keeps its sorted state and the overlay can sample it on the very first frame.
+   *
+   * Without it, start() moved the asset onto a FRESH manager at the swap, and the overlay showed
+   * the frozen capture until that manager's first sort came back from the sort worker — a still
+   * image under a moving head for as long as that takes (the "tracking stops for a moment at
+   * every transition" report). Returns false if this engine build cannot (nothing changed).
+   */
+  warm(entity) {
+    const v = this.viewer;
+    if (this.active || !LiveOutgoing.supported(v) || !entity?.gsplat) return false;
+    if (this.warming) {
+      if (this.entity === entity) return true;
+      this.cancelWarm();
+    }
+    try {
+      this._ensureEngineObjects();
+      this._ensureTarget(v.canvas.width, v.canvas.height);
+      const own = Array.isArray(entity.gsplat.layers) ? entity.gsplat.layers.slice() : [];
+      this._warmLayers = own;
+      entity.gsplat.layers = [...own.filter((id) => id !== this.layer.id), this.layer.id];
+      this.entity = entity;
+      this.oldFrame = null; // same asset, same rig: the chain is the rig node itself
+      this.frames = 0;
+      this.cam.enabled = true;
+      this.warming = true;
+      return true;
+    } catch (err) {
+      console.warn('[inline3d/splat] live outgoing pre-sort unavailable; the transition keeps the frozen bridge', err);
+      this.cancelWarm();
+      return false;
+    }
+  }
+
+  /** The pre-sorted manager has drawn a sorted frame (what start() will then need no bridge for). */
+  get warmReady() {
+    if (!this.warming) return false;
+    const mgr = this.manager;
+    if (mgr === undefined) return this.frames >= 3;
+    const w = mgr?.world;
+    const st = w?.getState?.(w.lastWorldStateVersion);
+    return !!st?.sortedBefore && this.frames >= 1;
+  }
+
+  /** Drop a pre-sort that did not become a live window: the asset back on only its own layers. */
+  cancelWarm() {
+    if (!this.warming) return;
+    const e = this.entity;
+    const own = this._warmLayers;
+    this.warming = false;
+    this._warmLayers = null;
+    this.entity = null;
+    if (this.cam) this.cam.enabled = false;
+    this._destroyTarget();
+    try {
+      if (e?.gsplat && own) e.gsplat.layers = own;
+    } catch {
+      /* entity already gone */
+    }
+  }
+
   /**
    * Take `entity` (the outgoing splat, still enabled) onto the live layer. `oldFrame` is
    * viewer.lensFrame() read BEFORE the incoming asset's rig was adopted. Returns false if this
-   * engine build cannot (the caller keeps the frozen frame).
+   * engine build cannot (the caller keeps the frozen frame). After warm(entity) the live
+   * manager is kept (only the World placement goes), so `ready` holds from the first frame.
    */
   start(entity, oldFrame) {
     const v = this.viewer;
     if (!LiveOutgoing.supported(v) || !entity?.gsplat) return false;
+    const warmed = this.warming && this.entity === entity;
+    if (this.warming && !warmed) this.cancelWarm();
     try {
       this._ensureEngineObjects();
       this._ensureTarget(v.canvas.width, v.canvas.height);
       entity.gsplat.layers = [this.layer.id];
       this.entity = entity;
       this.oldFrame = oldFrame;
-      this.frames = 0;
+      if (!warmed) this.frames = 0;
+      this.warming = false;
+      this._warmLayers = null;
+      this.warmed = warmed;
       this.cam.enabled = true;
       this.active = true;
       return true;
@@ -275,7 +351,7 @@ export class LiveOutgoing {
    * viewport), the eye's node pose, and the rig chain.
    */
   sync(entries, rect, frustum) {
-    if (!this.active) return;
+    if (!this.active && !this.warming) return;
     const v = this.viewer;
     const pc = v.pc;
     const rvs = this.views;
@@ -322,9 +398,11 @@ export class LiveOutgoing {
   stop() {
     // The outgoing entity is NOT put back on its old layer: the caller releases it right after,
     // and a round trip through World would dirty the eye's manager (a work-buffer rebuild).
+    if (this.warming) return this.cancelWarm();
     this.entity = null;
     this.oldFrame = null;
     this.active = false;
+    this.warmed = false;
     if (this.cam) this.cam.enabled = false;
     this._destroyTarget();
   }

package/js/inline3d-splat-playcanvas.js

@@ -64,6 +64,7 @@ import {
 } 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 { resolveDiag, DiagRecorder, startDiagLoop, registerDiag } from './inline3d-splat-diag.js';
 import {
   clamp,
   finite,
@@ -99,6 +100,7 @@ import {
   resolveControls,
   normalizeCameraPose,
   coverageExponent,
+  declareViewRig,
 } from './inline3d-splat-shared.js';
 
 /**
@@ -1405,6 +1407,11 @@ export class PlayCanvasSplatViewer {
     if (!s?.parts) return false;
     const fits = !!s.tex && s.w === this.canvas.width && s.h === this.canvas.height;
     const show = alpha > 0 && fits;
+    // What the overlay shows, for diagnostics (diagImageState): its weight on screen.
+    const st = (this._snapState ||= { alpha: 0, wipe: -2, over: false, live: false });
+    st.alpha = show ? Math.min(1, alpha) : 0;
+    st.wipe = wipe ? wipe.t : -2;
+    st.over = !!mix?.over;
     for (const p of s.parts) {
       p.mi.visible = show;
       if (show) {
@@ -1428,6 +1435,7 @@ export class PlayCanvasSplatViewer {
   setSnapshotSource(tex) {
     const s = this._snap;
     if (!s?.parts) return;
+    (this._snapState ||= { alpha: 0, wipe: -2, over: false, live: false }).live = !!tex;
     for (const p of s.parts) {
       p.mat.setParameter('dxrSnap', tex || s.tex);
       p.mat.update();
@@ -1488,6 +1496,55 @@ export class PlayCanvasSplatViewer {
     return this._live.start(entity, oldFrame) ? this._live : null;
   }
 
+  /**
+   * Diagnostics: what the transition overlay puts on screen this frame — 'none', or the 'frozen'
+   * capture / the 'live' outgoing target with `w`, the share of the picture it covers (the wipe's
+   * uncommitted part times the lerp weight).
+   */
+  diagImageState() {
+    const st = this._snapState;
+    if (!st || !(st.alpha > 0)) return { overlay: 'none', w: 0 };
+    const left = st.wipe < -1 ? 1 : Math.min(1, Math.max(0, 1 - st.wipe));
+    return { overlay: st.live ? 'live' : 'frozen', w: st.alpha * left };
+  }
+
+  /** Pre-sort the live outgoing camera on `entity` before a swap (see LiveOutgoing.warm). */
+  warmLiveOutgoing(entity) {
+    this._live ||= new LiveOutgoing(this);
+    return this._live.warm(entity);
+  }
+
+  /**
+   * Resolves true once the pre-sorted live manager has drawn a sorted frame, false after
+   * `timeoutMs` (a hidden tab, a stalled sorter) or once the pre-sort was dropped.
+   */
+  liveWarmed(timeoutMs = 1500) {
+    const live = this._live;
+    if (!live?.warming) return Promise.resolve(false);
+    if (live.warmReady) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      let done = false;
+      const end = (v) => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        resolve(v);
+      };
+      const timer = setTimeout(() => end(false), timeoutMs);
+      this._hooks.push(() => {
+        if (done) return false;
+        if (this._disposed || !live.warming) return end(false), false;
+        if (live.warmReady) return end(true), false;
+        return true;
+      });
+    });
+  }
+
+  /** Drop a pre-sort that is not going to become a live window. */
+  cancelLiveWarm() {
+    this._live?.cancelWarm();
+  }
+
   /** End the live window: overlay back on the frozen capture, camera off, target freed. */
   stopLiveOutgoing() {
     if (!this._live?.active) return;
@@ -1672,7 +1729,7 @@ export class PlayCanvasSplatViewer {
       // 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.sync(entries, rect, f);
+      if (this._live?.active || this._live?.warming) this._live.sync(entries, rect, f);
       // setSource's wavefront: this frame's eye views, as the engine is about to compose them.
       this.onBeforeRender?.(entries, rect);
     } else {
@@ -2348,7 +2405,6 @@ const SET_RIG_ENV_TONE_MAPPING = Object.freeze({ neutral: 'neutral', room: 'none
 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).';
@@ -2561,6 +2617,18 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   let handle = null;
   let unbindFocusInput = null;
+
+  // ── diagnostics (diag / ?dxrdiag — ./inline3d-splat-diag.js) ──
+  const diagCfg = resolveDiag(opts.diag);
+  if (diagCfg.unknown.length) console.warn(`[inline3d/splat] diag: unknown switch(es) ${diagCfg.unknown.join(', ')} — known: norig, frozen, nowarm, cold, nooverlay.`);
+  const diag = diagCfg.on ? new DiagRecorder({ switches: diagCfg.switches }) : null;
+  /** norig: armed by the first setSource — from then on the declared rig is kept. */
+  let rigLockArmed = false;
+  if (diag) {
+    diag.imageState = () => viewer.diagImageState();
+    diag.observeLongTasks();
+    diag.log(`on — switches [${[...diag.switches].join(', ') || 'none'}]; dump: copy(__dxrDiag.dump())`);
+  }
   let removed = false;
   /** prepareSource: prepared handle → { loaded, state: 'ready' | 'used' | 'disposed', dispose }. */
   const preparedAssets = new WeakMap();
@@ -2675,6 +2743,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       fx = null;
       unbindFocusInput?.();
       viewer.onFocusChange = null;
+      diagLoop?.remove();
+      diag?.dispose();
       handle?.remove();
       viewer.dispose(); // app.destroy(): every entity — ours and any a page added — goes with it
     },
@@ -2749,7 +2819,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   const pageFocus = { d: Number.NaN, target: Number.NaN, fired: Number.NaN, source: null };
 
   if (wall && wall.supported) {
-    handle = wall.addScene(canvas, viewer.onFrame, {
+    const onFrame = diag
+      ? (views, layer) => {
+          const t = performance.now();
+          viewer.onFrame(views, layer);
+          diag.frame(views, t); // after the draw: the overlay state is what this frame showed
+        }
+      : viewer.onFrame;
+    handle = wall.addScene(canvas, onFrame, {
       // 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
@@ -2762,6 +2839,26 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   } else {
     viewer.startMono();
   }
+  let diagLoop = null;
+  if (diag) {
+    // Every rig push, logged with its values; under `norig`, every push after the first
+    // setSource is DROPPED (the rig declared before it stays in force).
+    if (handle && typeof handle.setViewRig === 'function') {
+      const push = handle.setViewRig;
+      handle.setViewRig = (rig) => {
+        if (diag.has('norig') && rigLockArmed) {
+          diag.rig(rig, { dropped: true });
+          return false;
+        }
+        diag.rig(rig);
+        return push(rig);
+      };
+    }
+    diagLoop = startDiagLoop(diag, { overlay: !diag.has('nooverlay') && !!handle });
+    // 2D DOM over the woven canvas: out of the weave (a no-op where occlusion is automatic).
+    if (diagLoop?.el) handle?.exclude?.(diagLoop.el);
+    registerDiag(diag);
+  }
   // Settle the stub's `firstWoven` (addSplatDeferred) with the core handle's own.
   if (typeof out._resolveFirstWoven === 'function') {
     out._resolveFirstWoven(handle ? handle.firstWoven : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 })));
@@ -2832,7 +2929,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       },
       out.viewRig || {},
     );
-    handle?.setViewRig?.(out.viewRig);
+    declareViewRig(handle, out.viewRig);
     if (!out.rig) return;
     out.rig.convergence = d;
     if (Math.abs(d - pageFocus.fired) > 1e-3 || source !== pageFocus.source) {
@@ -2905,7 +3002,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         out: camRigObj,
       },
     );
-    handle?.setViewRig?.(out.viewRig);
+    declareViewRig(handle, out.viewRig);
   }
   viewer.onFocusChange = (f) => {
     pushViewRig(false);
@@ -3195,7 +3292,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       parallaxFactor: f.parallaxFactor ?? 1,
       perspectiveFactor: f.perspectiveFactor ?? 1,
     });
-    handle?.setViewRig?.(out.viewRig);
+    declareViewRig(handle, out.viewRig);
   }
 
   /**
@@ -3601,7 +3698,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       } else {
         declaredDisplay = s.declaredDisplay;
         out.viewRig = s.viewRig;
-        handle?.setViewRig?.(out.viewRig);
+        declareViewRig(handle, out.viewRig);
       }
     } else out.viewRig = s.viewRig;
     lastConvergence = s.lastConvergence;
@@ -3709,8 +3806,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     await first.catch(() => null);
     if (!app || removed) throw new Error('@displayxr/inline3d/splat: prepareSource on a removed tile.');
     const t0 = performance.now();
-    const loaded = await loadOne(pcModule, app, src, { background: true });
+    if (diag && diag.phase === 'idle') diag.setPhase('prepare');
+    let loaded;
+    try {
+      loaded = await loadOne(pcModule, app, src, { background: true });
+    } finally {
+      if (diag?.phase === 'prepare') diag.setPhase('idle');
+    }
     perfSpan('prepareSource', t0);
+    diag?.mark('prepared', { ms: Math.round(performance.now() - t0) });
     // The transition the page declared: compile its shader now, in the dwell, not on its first frame.
     await prewarmTransition(warm); // null (no transition declared): the overlay only
     const entry = { loaded, state: 'ready', dispose: null };
@@ -3753,6 +3857,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * engine whose internals differ just compiles on the transition's first frame, as before.
    */
   async function prewarmTransition(plan) {
+    if (diag?.has('nowarm')) return;
     // The chunk variant the transition installs (particles, wavefront), and the overlay's two quads
     // (crossfade, wavefront and the particles all composite through them; created on the first
     // capture otherwise, and compiled on its draw: 30–180 ms on the first frames of the window).
@@ -3877,8 +3982,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   }
   async function setSourceNow(next, o = {}) {
     const plan = resolveSwap(o);
+    if (diag?.has('frozen')) plan.outgoing = 'frozen'; // kill switch: the 1.12.1 frozen outgoing
     const { resetPose = false } = o;
     const gen = ++sourceGen;
+    if (diag) {
+      rigLockArmed = true;
+      diag.setPhase('swap', { transition: plan.transition, outgoing: plan.outgoing || 'default', prepared: preparedAssets.has(next) });
+    }
     // A prepareSource() result: already fetched, decoded and uploaded — no load on this path.
     const prep = preparedAssets.get(next) || null;
     if (prep) {
@@ -3910,6 +4020,23 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // FRAME_SNAPSHOT: freeze the outgoing frame BEFORE anything of the new asset (or its rig) is
     // drawn. The overlay goes up in the same task, so no frame shows neither photo.
     const wantsSnapshot = transition === 'crossfade' || transition === 'wavefront' || !!particle;
+    const outgoingMode = plan.outgoing || (particle ? 'live' : defaultOutgoing(viewer.is3D));
+    // PRE-SORT the live outgoing camera on the current asset BEFORE the swap (LiveOutgoing.warm):
+    // its first sort runs while the photo is still on screen and live, so the frozen capture has
+    // nothing to bridge. The transition starts once it has sorted (bounded; a hidden tab or a
+    // stalled sorter falls back to the bridge). `?dxrdiag=cold` skips it (the 1.19.2 path).
+    if (wantsSnapshot && outgoingMode === 'live' && viewer.canLiveOutgoing && !diag?.has('cold') && viewer.warmLiveOutgoing(prev.entity)) {
+      const tw = performance.now();
+      const ok = await viewer.liveWarmed();
+      perfSpan('setSource:presort(async)', tw);
+      diag?.mark('presorted', { ok, ms: Math.round(performance.now() - tw) });
+      if (removed || gen !== sourceGen) {
+        // A newer setSource owns the pre-sort now (it warms the same asset, or drops it).
+        app.assets.remove(loaded.asset);
+        loaded.asset.unload?.();
+        return out;
+      }
+    }
     const snapped = wantsSnapshot ? await viewer.captureFrame() : false;
     if (removed || gen !== sourceGen) {
       app.assets.remove(loaded.asset);
@@ -3922,16 +4049,20 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // its camera has drawn a sorted frame. Its lens frame is read BEFORE adopt() switches the rig.
     // A particle transition's outgoing photo MOVES, so it is live in 2D too (where the engine has
     // the RenderView path); 'frozen' there = its snapshot fades out while the new one plays in.
-    const outgoingMode = plan.outgoing || (particle ? 'live' : defaultOutgoing(viewer.is3D));
     const live =
       snapped && outgoingMode === 'live' && viewer.canLiveOutgoing ? viewer.startLiveOutgoing(prev.entity, viewer.lensFrame()) : null;
+    if (!live) viewer.cancelLiveWarm(); // a pre-sort that is not becoming a live window
+    diag?.mark('outgoing', { mode: live ? (live.warmed ? 'live (pre-sorted)' : 'live (cold: frozen bridge until sorted)') : snapped ? 'frozen' : 'none' });
     /** Each frame of the window: once the live camera is ready, the overlay samples it. */
     let liveShown = false;
     const pumpLive = () => {
       if (!live || liveShown || !live.active || !live.ready) return;
       viewer.setSnapshotSource(live.texture);
       liveShown = true;
+      diag?.mark('live-shown');
     };
+    // Pre-sorted: the live target is already sorted, so the overlay samples it from the swap on.
+    if (live?.warmed) pumpLive();
 
     const release = (p) => {
       if (!p) return;
@@ -3960,6 +4091,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       const kept = applyLoaded(loaded);
       current = { asset: loaded.asset, entity, res: loaded.res, kind: loaded.desc.kind, ...kept };
       if (resetPose && !pageMode) viewer.resetPose(); // the page owns the pose on controls:'page'
+      diag?.setPhase('window');
     };
 
     const entity = viewer.addSplatAsset(loaded.asset);
@@ -3971,6 +4103,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       if (finished) return;
       finished = true;
       for (const f of finishers) f();
+      if (gen === sourceGen) diag?.setPhase('settle');
       if (pendingSwap?.finish === finish) pendingSwap = null;
       settle();
     };

package/js/inline3d-splat-shared.js

@@ -514,3 +514,35 @@ export function coverageExponent(c, L = FADE_OPTICAL_DEPTH) {
   if (c >= 1) return 1;
   return -Math.log(1 - c * (1 - Math.exp(-L))) / L;
 }
+
+// ── view-rig declaration (all three backends) ────────────────────────────────────────────────
+
+let warnedNoViewRig = false;
+
+/**
+ * Declare a view rig on the scene handle. A handle without `setViewRig` is a core that predates
+ * view rigs (inline3d.js before the view-rig commit — e.g. a page that vendors an older core and
+ * hands its wall to this adapter): the rig cannot reach the browser, and the wall weaves on the
+ * addScene display-rig shorthand instead. For a CAMERA rig that is a metric photo scene on a
+ * 0.24 m display rig — convergence and scale way off while 2D looks right — so it is said out
+ * loud, once per page, rather than dropped the way `handle?.setViewRig?.()` used to drop it.
+ * Returns whether the handle took the rig.
+ */
+export function declareViewRig(handle, rig) {
+  if (!handle) return false; // no wall (mono): nothing to declare to
+  if (typeof handle.setViewRig === 'function') {
+    handle.setViewRig(rig);
+    return true;
+  }
+  if (rig?.type === 'camera' && !warnedNoViewRig) {
+    warnedNoViewRig = true;
+    console.warn(
+      '[inline3d/splat] the view rig was dropped: your inline3d core predates view rigs (its ' +
+        'addScene handle has no setViewRig), so the wall will use the addScene display-rig ' +
+        'shorthand, not this camera rig — the scene will be mis-converged and mis-scaled in 3D. ' +
+        'Update the core (js/inline3d.js) that created the wall to the same SDK version as ./splat.',
+      rig,
+    );
+  }
+  return false;
+}

package/js/inline3d-splat.js

@@ -37,6 +37,7 @@ import {
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
   normalizeCameraPose,
+  declareViewRig,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -486,7 +487,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
       parallaxFactor: out.rig.parallaxFactor,
       out: out.viewRig || {},
     });
-    handle?.setViewRig(out.viewRig);
+    declareViewRig(handle, out.viewRig);
   }
   viewer.onFocusChange = () => {
     pushViewRig(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.19.2",
+  "version": "1.20.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-diag.js",
     "js/inline3d-splat-video.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",

package/splat.d.ts

@@ -219,6 +219,23 @@ export interface SplatOptions {
    * URL with `engine: 'spark'`.
    */
   engine?: 'spark' | 'playcanvas';
+  /**
+   * `engine: 'playcanvas'` only: TRANSITION DIAGNOSTICS (#36). Off by default; `true` (or the page
+   * URL's `?dxrdiag=1`) records every woven frame — its interval, whether its eye poses are
+   * bit-identical to the previous frame's (a tracking HOLD), whether the transition overlay shows
+   * the frozen capture — plus every `setViewRig` push with its values, long tasks, and the
+   * setSource phases (`prepare`, `swap`, `window`, `settle`). It shows a small overlay (excluded
+   * from the weave), logs `[dxr-diag]` console lines (one summary with a verdict per transition),
+   * and exposes `window.__dxrDiag` (`copy(__dxrDiag.dump())` for the JSON).
+   *
+   * 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
+   * 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'>;
   /**
    * `engine: 'playcanvas'` only: the WebGL context's `preserveDrawingBuffer` (default false) —
    * the knob for the weave's zero-copy read race on large canvases.