@displayxr/inline3d 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.22.0 — 2026-09-25
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change; no pixel change.
+
+- **A burst of `pick()` calls no longer blocks the main thread.** Each pick scanned every centre of
+  the photo (~7.5 ms for 1.18M on an M1, more on a panel PC); a page that picks 24 then 81 times
+  right after `setSource` resolves (a photo slideshow app planning its companion's path) stalled
+  the main thread for ~1.3 s at every swap's end, so the woven image stopped following the head.
+  A second pick from the same eye position now builds a pick index (about two scans), and every
+  further pick from there reads a few cells: 105 picks went from ~820 ms to ~70 ms on an M1. The
+  answer is unchanged (the full scan's, exactly; the full scan still runs when the pick's cone is
+  empty). `?dxrdiag=oldpick` restores the full scan.
+- **`?dxrdiag` names what is on the main thread.** Per transition phase: every GL call that can
+  block (compile, link, status queries, readbacks, syncs; count and ms), `pick()` calls and their
+  per-task bursts, how long the settle's task kept running after the SDK resolved `setSource` (the
+  page's continuation), and long animation frames with their top scripts (file + function). The
+  verdict names them. The settle teardown is a User Timing measure, `inline3d:settle:teardown`.
+- **Measured: the SDK's settle does no GL work that can block.** Zero compile, link, status query,
+  readback or sync from the `setSource` call to 1.5 s after the settle, for `reassemble`,
+  `crossfade` and `wavefront` (docs/playcanvas-adapter.md § Diagnosing transition stalls).
+
+## 1.21.1 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change; nothing changes at rest.
+
+- **A gated `reveal` no longer shows its start state frozen.** The splat is hidden until the reveal's clock
+  starts, so its first visible frame is the first frame of motion; previously the start state (e.g.
+  `assemble`'s scatter) sat still for up to the rest of the `firstWoven` hold, then jumped. On a cached
+  asset the tile is empty for the rest of the hold instead.
+
 ## 1.21.0 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Minor: a new `setSource`

package/js/inline3d-splat-diag.js

@@ -26,9 +26,23 @@
 //   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.
+//   oldpick  — handle.pick() always runs the full scan over every centre (the 1.21.1 path), no
+//              pick index. Tests "the page's picks are what blocks the main thread".
+//
+// WHAT RUNS ON THE MAIN THREAD, per transition phase (the fifth cause: a stall at the swap's END
+// that is not the SDK's transition at all):
+//   - GL calls that can block: shader compile / program link / program + shader status queries
+//     (a link resolves there), readPixels, getBufferSubData, fenceSync / clientWaitSync, finish —
+//     counted and timed, per phase, on the tile's own context (./inline3d-splat-diag.js wraps
+//     them while diag is on).
+//   - handle.pick() calls, counted and timed per phase and grouped into BURSTS (one task's worth).
+//   - long animation frames (where the browser has the API) with their top SCRIPTS — the source
+//     file and function that ran: the page's own code or the SDK's.
+//   - the settle itself: the SDK's settle work in ms, then how long the SAME task kept running
+//     after it (the page's continuation of `await setSource`).
 
 /** The switches `diag` / `?dxrdiag` understand, besides the plain on values. */
-export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay']);
+export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick']);
 const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
 
 /**
@@ -179,6 +193,9 @@ export class DiagRecorder {
     this._lto = null;
     this.rigLocked = null; // norig: the summary of the rig kept
     this._listeners = new Set();
+    this._lafo = null;
+    this._gl = null; // the wrapped context + its originals, for dispose()
+    this._burst = null; // the pick burst of the current task
   }
 
   has(sw) {
@@ -190,7 +207,7 @@ export class DiagRecorder {
     try {
       if (typeof PerformanceObserver !== 'function') return;
       this._lto = new PerformanceObserver((list) => {
-        for (const e of list.getEntries()) this.longTask(e.startTime, e.duration);
+        for (const e of list.getEntries()) this.longTask(e.startTime, e.duration, e.attribution);
       });
       this._lto.observe({ type: 'longtask', buffered: false });
     } catch {
@@ -198,8 +215,141 @@ export class DiagRecorder {
     }
   }
 
-  longTask(start, duration) {
+  /**
+   * Observe long ANIMATION FRAMES (Chrome 123+): unlike a long task, each one names the scripts
+   * that ran in it — source file, function, what invoked it — so a stall is pinned on the page's
+   * code or the SDK's. Silently absent elsewhere.
+   */
+  observeLongFrames() {
+    try {
+      if (typeof PerformanceObserver !== 'function' || !PerformanceObserver.supportedEntryTypes?.includes?.('long-animation-frame')) return;
+      this._lafo = new PerformanceObserver((list) => {
+        for (const e of list.getEntries()) this.longFrame(e);
+      });
+      this._lafo.observe({ type: 'long-animation-frame', buffered: false });
+    } catch {
+      this._lafo = null;
+    }
+  }
+
+  /** One long animation frame: its span, its blocking time, and its top three scripts. */
+  longFrame(e) {
+    if (!e || !(e.duration >= 50)) return null;
+    const scripts = [...(e.scripts || [])]
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, 3)
+      .map((x) => ({
+        src: shortSrc(x.sourceURL),
+        fn: x.sourceFunctionName || '',
+        inv: String(x.invoker || x.invokerType || '').slice(0, 80),
+        d: round1(x.duration),
+      }));
+    return this._event('loaf', { s: round1(e.startTime), d: round1(e.duration), block: round1(e.blockingDuration ?? NaN), scripts }, e.startTime);
+  }
+
+  /**
+   * Count and time the GL calls that can block the main thread, on `gl` (the tile's own context:
+   * its own methods shadow the prototype's; dispose() removes them). Each call is booked to the
+   * phase it ran in (and to the open transition).
+   */
+  instrumentGl(gl) {
+    if (!gl || this._gl) return;
+    const LINK = 0x8b82;
+    const COMPLETION = 0x91b1;
+    const kinds = {
+      compileShader: 'compile',
+      linkProgram: 'link',
+      getProgramParameter: (a) => (a[1] === COMPLETION ? 'poll' : a[1] === LINK ? 'linkQuery' : 'programQuery'),
+      getShaderParameter: 'shaderQuery',
+      readPixels: 'readPixels',
+      getBufferSubData: 'readback',
+      fenceSync: 'fence',
+      clientWaitSync: 'wait',
+      finish: 'finish',
+    };
+    const saved = [];
+    for (const [name, kind] of Object.entries(kinds)) {
+      const orig = gl[name];
+      if (typeof orig !== 'function') continue;
+      const rec = this;
+      gl[name] = function (...a) {
+        const t = performance.now();
+        try {
+          return orig.apply(this, a);
+        } finally {
+          rec.glCall(typeof kind === 'function' ? kind(a) : kind, performance.now() - t, t);
+        }
+      };
+      saved.push(name);
+    }
+    this._gl = { gl, saved };
+  }
+
+  /** One GL call of `kind` that took `ms`, at `t` (instrumentGl's wrappers; tests call it directly). */
+  glCall(kind, ms, t = this.now()) {
+    const b = (this._glByPhase ||= {});
+    const p = (b[this.phase] ||= {});
+    const k = (p[kind] ||= { n: 0, ms: 0 });
+    k.n++;
+    k.ms += ms;
+    if (this._open) {
+      const op = (this._open.gl[this.phase] ||= {});
+      const ok = (op[kind] ||= { n: 0, ms: 0 });
+      ok.n++;
+      ok.ms += ms;
+    }
+    // a call that blocked noticeably is an event of its own
+    if (ms >= 8) this._event('gl', { kind, ms: round1(ms) }, t);
+  }
+
+  /**
+   * One handle.pick() that took `ms` (`how`: 'scan' the full scan, 'build' it built the pick
+   * index, 'index' it read the index, 'build+scan' both). Grouped into BURSTS: every pick until
+   * the task ends is one burst, logged as one event with its total.
+   */
+  pick(ms, how = 'scan') {
+    const t = this.now();
+    if (this._open) {
+      const p = (this._open.picks[this.phase] ||= { n: 0, ms: 0 });
+      p.n++;
+      p.ms += ms;
+    }
+    let b = this._burst;
+    if (!b) {
+      b = this._burst = { t, phase: this.phase, n: 0, ms: 0, how: {} };
+      const end = () => {
+        if (this._burst !== b) return;
+        this._burst = null;
+        this._event('picks', { phase: b.phase, n: b.n, ms: round1(b.ms), how: b.how }, b.t);
+        if (b.ms >= 50) this.log(`picks: ${b.n} pick() calls in one task, ${round1(b.ms)} ms (${JSON.stringify(b.how)}) in phase ${b.phase}`);
+      };
+      postTask(end);
+    }
+    b.n++;
+    b.ms += ms;
+    b.how[how] = (b.how[how] || 0) + 1;
+  }
+
+  /**
+   * The settle: `sdkMs` is the SDK's own settle work. Then the time until the task that ran it
+   * ended: what ran after the SDK resolved setSource — the page's continuation, in that same task.
+   */
+  settled(sdkMs) {
+    const t = this.now();
+    const o = this._open;
+    this.mark('settle-sdk', { ms: round1(sdkMs) });
+    postTask(() => {
+      const ms = this.now() - t;
+      if (o) o.afterSettleTaskMs = round1(ms);
+      this._event('mark', { name: 'settle-task-end', detail: { ms: round1(ms) } }, t + ms);
+      if (o && ms >= 50) this.log(`settle: the task kept running ${round1(ms)} ms after the SDK's settle (${round1(sdkMs)} ms) — the page's continuation of setSource`);
+    });
+  }
+
+  longTask(start, duration, attribution) {
     const lt = { s: round1(start), d: round1(duration) };
+    const a = attribution?.[0];
+    if (a && (a.containerType || a.containerName || a.containerSrc)) lt.attr = [a.containerType, a.containerName || a.containerSrc].filter(Boolean).join(':').slice(0, 80);
     this.longTasks.push(lt);
     if (this.longTasks.length > EVENT_CAP) this.longTasks.splice(0, this.longTasks.length - EVENT_CAP);
     this._event('longtask', lt, start);
@@ -309,6 +459,9 @@ export class DiagRecorder {
       firstFrameAt: NaN,
       lastFrameAt: NaN,
       window: [], // the frame records kept for the frozen overlay strip
+      gl: {}, // phase -> kind -> { n, ms }
+      picks: {}, // phase -> { n, ms }
+      afterSettleTaskMs: null,
     };
     // 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);
@@ -371,6 +524,12 @@ export class DiagRecorder {
       heldRunMaxMs: o.heldRunMaxMs,
       frozenImageFrames: o.frozenImg,
       frozenImageMs: o.frozenImgMs,
+      gl: roundBuckets(o.gl),
+      picks: roundBuckets(o.picks),
+      afterSettleTaskMs: o.afterSettleTaskMs,
+      longFrames: this.events
+        .filter((e) => e.type === 'loaf' && e.s + e.d > o.callAt - PRE_MS && e.s < t)
+        .map((e) => ({ at: round1(e.s - o.callAt), d: e.d, block: e.block, scripts: e.scripts })),
     };
     s.verdict = verdict(s);
     s.window = o.window.map((f) => ({ ...f, t: round1(f.t - o.callAt) }));
@@ -420,6 +579,16 @@ export class DiagRecorder {
       /* already gone */
     }
     this._lto = null;
+    try {
+      this._lafo?.disconnect();
+    } catch {
+      /* already gone */
+    }
+    this._lafo = null;
+    if (this._gl) {
+      for (const name of this._gl.saved) delete this._gl.gl[name]; // the prototype's method again
+      this._gl = null;
+    }
     this._listeners.clear();
   }
 }
@@ -434,7 +603,74 @@ export function verdict(s) {
   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)';
+  if (!out.length) return 'CLEAN (no hold, no gap > 50 ms, no frozen image)';
+  // What was on the main thread: blocking GL calls, the page's picks, the settle task's tail.
+  const why = [];
+  const gl = sumBuckets(s.gl, ['compile', 'link', 'linkQuery', 'readPixels', 'readback', 'wait', 'finish']);
+  if (gl.n) why.push(`GL compile/link/sync ×${gl.n} ${gl.ms} ms`);
+  const pk = sumBuckets(s.picks);
+  if (pk.n) why.push(`pick() ×${pk.n} ${pk.ms} ms`);
+  if (s.afterSettleTaskMs >= 50) why.push(`page code ${s.afterSettleTaskMs} ms in the settle task`);
+  const top = (s.longFrames || []).flatMap((f) => f.scripts || []).sort((a, b) => b.d - a.d)[0];
+  if (top) why.push(`top script ${top.fn || '(anonymous)'}@${top.src} ${top.d} ms`);
+  return out.join(' + ') + (why.length ? ` — ${why.join('; ')}` : '');
+}
+
+/** { phase: { kind: { n, ms } } } or { phase: { n, ms } } → the same, ms rounded. */
+function roundBuckets(b) {
+  const out = {};
+  for (const [ph, v] of Object.entries(b || {})) {
+    if (v && typeof v.n === 'number') out[ph] = { n: v.n, ms: round1(v.ms) };
+    else {
+      out[ph] = {};
+      for (const [k, x] of Object.entries(v || {})) out[ph][k] = { n: x.n, ms: round1(x.ms) };
+    }
+  }
+  return out;
+}
+
+/** Total { n, ms } over every phase (and, for GL buckets, over `kinds`). */
+function sumBuckets(b, kinds = null) {
+  let n = 0;
+  let ms = 0;
+  for (const v of Object.values(b || {})) {
+    if (v && typeof v.n === 'number') {
+      n += v.n;
+      ms += v.ms;
+    } else {
+      for (const [k, x] of Object.entries(v || {})) {
+        if (kinds && !kinds.includes(k)) continue;
+        n += x.n;
+        ms += x.ms;
+      }
+    }
+  }
+  return { n, ms: round1(ms) };
+}
+
+/** Run `fn` in a NEW task (after the current one and its microtasks): MessageChannel, else a timeout. */
+function postTask(fn) {
+  try {
+    if (typeof MessageChannel === 'function') {
+      const ch = new MessageChannel();
+      ch.port1.onmessage = () => {
+        ch.port1.close();
+        fn();
+      };
+      ch.port2.postMessage(0);
+      return;
+    }
+  } catch {
+    /* fall through */
+  }
+  setTimeout(fn, 0);
+}
+
+/** A script URL, trimmed to its file name (plus a query, cut short). */
+function shortSrc(url) {
+  if (!url) return '';
+  const m = /([^/?#]+)(\?[^#]*)?(#.*)?$/.exec(String(url));
+  return m ? m[1] + (m[2] ? m[2].slice(0, 20) : '') : String(url).slice(-60);
 }
 
 function defaultLog(msg) {

package/js/inline3d-splat-playcanvas.js

@@ -68,7 +68,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 { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, DIAG_SWITCHES } from './inline3d-splat-diag.js';
 import {
   clamp,
   finite,
@@ -614,6 +614,136 @@ export function nearestCentreToRay(xyz, origin, dir, coneRad = PICK_CONE_RAD, al
   return bestInCone || bestAny;
 }
 
+/** Cells per side of a pick index (PICK_INDEX_GRID² cells over the view's direction square). */
+export const PICK_INDEX_GRID = 128;
+
+/**
+ * A pick INDEX over one centre set, for one eye position: every usable centre (opacity at or above
+ * RIG_MIN_OPACITY, in front of the eye) bucketed by its DIRECTION from the eye — its gnomonic
+ * coordinates (u, v) = ((p − eye)·right, (p − eye)·up) / ((p − eye)·fwd) on a PICK_INDEX_GRID² grid
+ * over [−U, U] × [−V, V] (centres outside land in the border cells). One pass over the set, about
+ * one full-scan pick's cost; every later pick from the same eye then reads only the few cells
+ * around its ray (queryPickIndex), not the whole set.
+ *
+ * Why (a photo slideshow app, on the panel): a page that picks in bursts — 24 rays to plan a
+ * companion's waypoints, then an 81-ray depth grid, on every photo swap — ran 105 full scans of a
+ * 1.18M-centre photo on the main thread, two long tasks of ~0.3 s and ~1 s right at the swap's
+ * end: no session frames, so the woven image stopped following the head.
+ *
+ * `f`, `r`, `up`: an orthonormal frame (any; the eye's own is the tightest). Returns null when
+ * nothing usable is in front of the eye.
+ */
+export function buildPickIndex(xyz, count, alpha8, eye, f, r, up, U, V, G = PICK_INDEX_GRID) {
+  const n = count;
+  const cells = G * G;
+  const su = G / (2 * U);
+  const sv = G / (2 * V);
+  const minA = Math.ceil(RIG_MIN_OPACITY * 255);
+  const cellOf = new Uint16Array(n); // G ≤ 255: cells < 65535, which marks "not indexed"
+  const start = new Uint32Array(cells + 1);
+  const [ex, ey, ez] = eye;
+  const [f0, f1, f2] = f;
+  const [r0, r1, r2] = r;
+  const [u0, u1, u2] = up;
+  let m = 0;
+  for (let i = 0; i < n; i++) {
+    if (alpha8 && alpha8[i] < minA) {
+      cellOf[i] = 65535;
+      continue;
+    }
+    const rx = xyz[i * 3] - ex;
+    const ry = xyz[i * 3 + 1] - ey;
+    const rz = xyz[i * 3 + 2] - ez;
+    const z = rx * f0 + ry * f1 + rz * f2;
+    if (!(z > 0)) {
+      cellOf[i] = 65535;
+      continue;
+    }
+    // z > 0 held, so every coordinate is finite (a NaN or ∞ one makes z NaN). Truncation, not
+    // floor: below the grid's edge both land in the border cell after the clamp.
+    const iz = 1 / z;
+    let cu = ((rx * r0 + ry * r1 + rz * r2) * iz + U) * su;
+    let cv = ((rx * u0 + ry * u1 + rz * u2) * iz + V) * sv;
+    cu = cu < 0 ? 0 : cu >= G ? G - 1 : cu | 0;
+    cv = cv < 0 ? 0 : cv >= G ? G - 1 : cv | 0;
+    const c = cv * G + cu;
+    cellOf[i] = c;
+    start[c + 1]++;
+    m++;
+  }
+  if (!m) return null;
+  for (let c = 0; c < cells; c++) start[c + 1] += start[c];
+  const order = new Uint32Array(m);
+  const cursor = start.slice(0, cells);
+  for (let i = 0; i < n; i++) {
+    const c = cellOf[i];
+    if (c !== 65535) order[cursor[c]++] = i;
+  }
+  return { eye: [ex, ey, ez], f: [f0, f1, f2], r: [r0, r1, r2], up: [u0, u1, u2], U, V, G, su, sv, start, order, size: m };
+}
+
+/**
+ * nearestCentreToRay's IN-CONE answer from a pick index: the same point, exactly (the same
+ * arithmetic on the same centres, ties to the lowest index as the full scan's first-wins), read
+ * from the cells the cone can reach. The ray must pass through the index's eye (any pick ray of
+ * that view does: it runs from its near-plane point through the eye). Returns the point, or
+ * undefined when the index cannot answer — no centre inside the cone (the full scan's
+ * nearest-by-angle fallback needs every centre), a ray not through the eye, or one too far off
+ * the index's axis — and the caller runs the full scan.
+ *
+ * Why the cells suffice: along a ray through the eye, t from the near-plane origin is t from the
+ * eye minus the near distance, so perp / t (the cone test) ≥ perp / t_eye = tan of the angle at
+ * the eye. A centre inside the cone is within atan(coneRad) of the ray AT THE EYE, and a cap of
+ * angular radius θ around a direction φ0 off the axis projects (gnomonic) inside a radius of
+ * tan(φ0 + θ) − tan(φ0) around the ray's own (u, v). The search square takes 1.25× that plus a
+ * cell.
+ */
+export function queryPickIndex(ix, xyz, origin, dir, coneRad = PICK_CONE_RAD) {
+  const { eye, f, r, up, U, V, G, su, sv, start, order } = ix;
+  // the ray must pass through the eye (a relative tolerance: numerical noise, not a design gap)
+  const ox = eye[0] - origin[0], oy = eye[1] - origin[1], oz = eye[2] - origin[2];
+  const along = ox * dir[0] + oy * dir[1] + oz * dir[2];
+  const off2 = ox * ox + oy * oy + oz * oz - along * along;
+  if (!(along < 0) || off2 > 1e-12 * (along * along) + 1e-18) return undefined; // the eye sits BEHIND the near-plane origin
+  const dz = dir[0] * f[0] + dir[1] * f[1] + dir[2] * f[2];
+  if (!(dz > 0)) return undefined;
+  const du = (dir[0] * r[0] + dir[1] * r[1] + dir[2] * r[2]) / dz;
+  const dv = (dir[0] * up[0] + dir[1] * up[1] + dir[2] * up[2]) / dz;
+  const rho = Math.hypot(du, dv);
+  const phi0 = Math.atan(rho);
+  const th = Math.atan(coneRad) * 1.05 + 1e-6;
+  if (phi0 + th >= 1.4) return undefined; // ~80°: the projection's stretch is no longer worth bounding
+  const R = (Math.tan(phi0 + th) - rho) * 1.25;
+  const clampCell = (x) => (x < 0 ? 0 : x >= G ? G - 1 : x);
+  const cu0 = clampCell(Math.floor((du - R + U) * su) - 1);
+  const cu1 = clampCell(Math.floor((du + R + U) * su) + 1);
+  const cv0 = clampCell(Math.floor((dv - R + V) * sv) - 1);
+  const cv1 = clampCell(Math.floor((dv + R + V) * sv) + 1);
+  if (!(cu0 <= cu1 && cv0 <= cv1)) return undefined;
+  let bestT = Infinity;
+  let bestI = -1;
+  for (let cv = cv0; cv <= cv1; cv++) {
+    const row = cv * G;
+    for (let k = start[row + cu0], k1 = start[row + cu1 + 1]; k < k1; k++) {
+      const i = order[k];
+      // nearestCentreToRay's own arithmetic, term for term
+      const rx = xyz[i * 3] - origin[0];
+      const ry = xyz[i * 3 + 1] - origin[1];
+      const rz = xyz[i * 3 + 2] - origin[2];
+      const t = rx * dir[0] + ry * dir[1] + rz * dir[2];
+      if (!(t > 0)) continue;
+      const perp = Math.sqrt(Math.max(0, rx * rx + ry * ry + rz * rz - t * t));
+      const angle = perp / t;
+      if (angle <= coneRad && (t < bestT || (t === bestT && i < bestI))) {
+        bestT = t;
+        bestI = i;
+      }
+    }
+  }
+  if (bestI < 0) return undefined;
+  return [xyz[bestI * 3], xyz[bestI * 3 + 1], xyz[bestI * 3 + 2]];
+}
+
 // ── the viewer: pose state + frame loop + the engine ────────────────────────────────────────
 
 /**
@@ -2695,13 +2825,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   // ── 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.`);
+  if (diagCfg.unknown.length) console.warn(`[inline3d/splat] diag: unknown switch(es) ${diagCfg.unknown.join(', ')} — known: ${DIAG_SWITCHES.join(', ')}.`);
   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.observeLongFrames();
     diag.log(`on — switches [${[...diag.switches].join(', ') || 'none'}]; dump: copy(__dxrDiag.dump())`);
   }
   let removed = false;
@@ -3156,11 +3287,91 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       return best;
     }
     const full = c.res?.centers;
-    if (full && full.length) return nearestCentreToRay(full, ray.o, ray.d, undefined, c.alpha8);
+    if (full && full.length) return pickFull(c, full, ray);
     // The engine released its centres: fall back to the strided set kept at load.
     return c.pickCentres ? nearestCentreToRay(c.pickCentres, ray.o, ray.d) : null;
   }
 
+  /**
+   * The eye of the view on screen and an orthonormal frame at it, in MODEL space, plus the
+   * direction extent of its frustum (gnomonic, per axis): what a pick index is built for. Every
+   * pick ray of this view passes through `eye`. null when the view is not a plain perspective one.
+   */
+  function pickFrame() {
+    const v = viewer.currentView();
+    const invP = mat4Invert(v.proj);
+    if (!invP) return null;
+    const T = mat4Mul(viewer.rigMatrix(), v.pose);
+    const at = (x, y, z) => contentToModel(transformPoint(T, x, y, z));
+    const eye = at(0, 0, 0);
+    const sub = (p) => [p[0] - eye[0], p[1] - eye[1], p[2] - eye[2]];
+    const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+    const norm = (a) => {
+      const l = Math.hypot(a[0], a[1], a[2]);
+      return l > 0 ? [a[0] / l, a[1] / l, a[2] / l] : null;
+    };
+    const f = norm(sub(at(0, 0, -1)));
+    if (!f) return null;
+    let r = sub(at(1, 0, 0));
+    const rf = dot(r, f);
+    r = norm([r[0] - rf * f[0], r[1] - rf * f[1], r[2] - rf * f[2]]);
+    if (!r) return null;
+    const up = [f[1] * r[2] - f[2] * r[1], f[2] * r[0] - f[0] * r[2], f[0] * r[1] - f[1] * r[0]];
+    let U = 0;
+    let V = 0;
+    for (const [x, y] of [[-1, -1], [1, -1], [-1, 1], [1, 1]]) {
+      const d = sub(at(...transformPoint(invP, x, y, 1)));
+      const z = dot(d, f);
+      if (!(z > 0)) return null;
+      U = Math.max(U, Math.abs(dot(d, r) / z));
+      V = Math.max(V, Math.abs(dot(d, up) / z));
+    }
+    if (!(U > 0 && V > 0)) return null;
+    // a margin past the frustum: a pick at its edge reaches a little outside it
+    U = U * 1.1 + 0.02;
+    V = V * 1.1 + 0.02;
+    return { eye, f, r, up, U, V, key: [...eye, ...f, ...r, U, V].join(',') };
+  }
+
+  /**
+   * A pick over the full centre set. The first pick from an eye position is the plain full scan
+   * (a page picking once per frame pays what it always did); a SECOND pick from the same eye
+   * builds a pick index for it (buildPickIndex: about one scan) and every further pick from there
+   * reads a few cells — a burst of N picks costs ~2 scans, not N. Same answer as the full scan
+   * (queryPickIndex falls back to it when it cannot answer exactly). `?dxrdiag=oldpick`: always
+   * the full scan (the 1.21.1 path), for A/B.
+   */
+  function pickFull(c, full, ray) {
+    const t0 = diag ? performance.now() : 0;
+    let how = 'scan';
+    let hit;
+    if (!diag?.has('oldpick')) {
+      const fr = pickFrame();
+      if (fr) {
+        const same = (p) => p && p.key === fr.key && p.xyz === full && p.alpha8 === c.alpha8;
+        let ix = same(c.pickIx) ? c.pickIx.ix : null;
+        if (!ix && same(c.pickPrev)) {
+          const count = Math.floor(full.length / 3);
+          ix = buildPickIndex(full, count, c.alpha8, fr.eye, fr.f, fr.r, fr.up, fr.U, fr.V);
+          c.pickIx = ix ? { key: fr.key, xyz: full, alpha8: c.alpha8, ix } : null;
+          how = 'build';
+        }
+        c.pickPrev = { key: fr.key, xyz: full, alpha8: c.alpha8 };
+        if (ix) {
+          hit = queryPickIndex(ix, full, ray.o, ray.d);
+          if (hit !== undefined && how === 'scan') how = 'index';
+        }
+      }
+    }
+    if (hit === undefined) {
+      hit = nearestCentreToRay(full, ray.o, ray.d, undefined, c.alpha8);
+      if (how === 'build') how = 'build+scan';
+      else if (how === 'index') how = 'scan';
+    }
+    if (diag) diag.pick(performance.now() - t0, how);
+    return hit;
+  }
+
   function bindFocusInput() {
     // controls:'page' binds no input at all: gestures are the page's (pick + setFocus remain).
     if (pageMode || focusInput === false || unbindFocusInput) return;
@@ -3601,6 +3812,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     });
     if (!app || removed) return null;
     pcModule = pc;
+    // diag: count the GL calls that can block (compile, link, status queries, readbacks, syncs),
+    // from before the first asset's compile on
+    if (diag) diag.instrumentGl(app.graphicsDevice?.gl);
     /**
      * ADVANCED, not covered by the semver promise: the engine objects behind this window.
      * `app` is the tile's `pc.AppBase`; `root` the content root, in the splat's content space
@@ -3630,7 +3844,22 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // tile is woven (handle.firstWoven — which is immediate in 2D) and the first frames are built.
     if (revealSpec) {
       const gate = Promise.resolve(out.firstWoven).then(() => afterTicks(2));
+      // The splat stays HIDDEN until the gate opens, so the first frame anyone sees is the first
+      // frame of motion. The gate is `firstWoven`, a worst-case hold of up to 1.2 s past the
+      // layer's birth (docs/woven-canvas-rules.md §5), and the browser usually joins the canvas
+      // well before it ends. Drawn meanwhile, the start state (a particle reveal's scatter) sat
+      // frozen on the woven panel for the rest of the hold and then jumped into motion. Hidden,
+      // the tile is empty for that span, which also keeps stereo pixels off a canvas that may
+      // not be joined yet (rule 5). Registered after fx.play's own `.then`, so it lands in the
+      // same microtask that releases the effect: the clock starts on the frame it first shows.
+      entity.enabled = false;
       fx.play(revealSpec.type, revealSpec.raw, { gate });
+      gate.then(() => {
+        if (removed || current?.entity !== entity) return;
+        // setVideo took the splat off screen meanwhile: its exit restores what it saved.
+        if (vid?.saved?.entity === entity) vid.saved.splatEnabled = true;
+        else entity.enabled = true;
+      });
     }
     for (const [what, name, arg] of fxPending.splice(0)) {
       if (what === 'set') fx.set(name, arg);
@@ -4202,10 +4431,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const finish = () => {
       if (finished) return;
       finished = true;
+      const ts = performance.now();
       for (const f of finishers) f();
+      perfSpan('settle:teardown', ts);
       if (gen === sourceGen) diag?.setPhase('settle');
       if (pendingSwap?.finish === finish) pendingSwap = null;
       settle();
+      if (gen === sourceGen) diag?.settled(performance.now() - ts);
     };
     pendingSwap = { finish };
 
@@ -4414,12 +4646,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const finish = () => {
       if (finished) return;
       finished = true;
+      const ts = performance.now();
       for (const f of finishers) f();
+      perfSpan('settle:teardown', ts);
       for (const w of [...wakers]) w();
       wakers.clear();
       viewer._transitionState = null;
       if (gen === sourceGen) diag?.setPhase('settle');
       if (pendingSwap?.finish === finish) pendingSwap = null;
+      if (gen === sourceGen) diag?.settled(performance.now() - ts);
     };
     const ac = typeof AbortController === 'function' ? new AbortController() : null;
     finishers.push(() => ac?.abort());

package/package.json

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

package/splat.d.ts

@@ -941,7 +941,9 @@ export interface SplatHandle {
    * What is under a point on the canvas, in the splat's own space — the double-click's pick.
    * PlayCanvas: the nearest gaussian CENTRE to the ray over the FULL centre set (haze under 5 %
    * opacity skipped); on a Streamed SOG, over the chunks currently resident. Spark: its surface
-   * raycast, falling back to the nearest centre.
+   * raycast, falling back to the nearest centre. PlayCanvas: a BURST of picks from one view (the
+   * same frame) builds a pick index at the second one, so N picks cost about three full scans, not
+   * N; the answer is the full scan's, exactly.
    */
   pick(clientX: number, clientY: number): number[] | null;
   /**