@displayxr/inline3d 1.19.3 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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

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,
@@ -1406,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) {
@@ -1429,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();
@@ -1489,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;
@@ -1673,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 {
@@ -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 })));
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.19.3",
+  "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.