@displayxr/inline3d 1.13.0 → 1.14.0

package/js/inline3d-splat-playcanvas.js

@@ -49,7 +49,7 @@ import {
   tileSplatBudget,
   budgetPerManager,
 } from './inline3d-splat-perf.js';
-import { boundsFromPositions } from './inline3d-viewer.js';
+import { boundsFromPositions, boundsFromPositionsAsync } from './inline3d-viewer.js';
 import { cameraRigFromPose } from './inline3d-three.js';
 import {
   SplatEffects,
@@ -58,6 +58,7 @@ import {
   resolveRevealOption,
   validateEffectCall,
 } from './inline3d-splat-effects.js';
+import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
 import {
   clamp,
   finite,
@@ -668,6 +669,8 @@ export class PlayCanvasSplatViewer {
     this._captureWaiters = [];
     /** The crossfade's frame snapshot: { w, h, tex, rt, mi, mat } once captured. */
     this._snap = null;
+    /** setSource's live outgoing asset (./inline3d-splat-live.js), made on first use. */
+    this._live = null;
     this.vH = virtualDisplayHeight;
     this.fit = fit;
     this.margin = margin;
@@ -987,6 +990,8 @@ export class PlayCanvasSplatViewer {
       clearTimeout(w.timer);
       w.resolve(false);
     }
+    this._live?.destroy();
+    this._live = null;
     try {
       this.app?.destroy();
     } catch (err) {
@@ -1223,8 +1228,12 @@ export class PlayCanvasSplatViewer {
       const w = this.canvas.width;
       const h = this.canvas.height;
       let s = this._snap;
-      if (!s || s.w !== w || s.h !== h) {
-        this._destroySnapshot();
+      if (!s || !s.tex || s.w !== w || s.h !== h) {
+        // A new size, or the texture was released after the last transition: a new texture.
+        // The overlay quads (and their compiled materials) are kept.
+        const parts = s?.parts || null;
+        s?.rt?.destroy?.();
+        s?.tex?.destroy?.();
         const tex = new pc.Texture(device, {
           name: 'inline3d-snapshot',
           width: w,
@@ -1236,7 +1245,7 @@ export class PlayCanvasSplatViewer {
           addressU: pc.ADDRESS_CLAMP_TO_EDGE,
           addressV: pc.ADDRESS_CLAMP_TO_EDGE,
         });
-        s = this._snap = { w, h, tex, rt: new pc.RenderTarget({ colorBuffer: tex, depth: false }), parts: null };
+        s = this._snap = { w, h, tex, rt: new pc.RenderTarget({ colorBuffer: tex, depth: false }), parts };
       }
       // null source = the back buffer, still holding this frame (same task, before compositing).
       ok = device.copyRenderTarget(null, s.rt, true, false) !== false;
@@ -1325,7 +1334,7 @@ export class PlayCanvasSplatViewer {
   setSnapshotAlpha(alpha, wipe = null) {
     const s = this._snap;
     if (!s?.parts) return false;
-    const fits = s.w === this.canvas.width && s.h === this.canvas.height;
+    const fits = !!s.tex && s.w === this.canvas.width && s.h === this.canvas.height;
     const show = alpha > 0 && fits;
     for (const p of s.parts) {
       p.mi.visible = show;
@@ -1341,6 +1350,67 @@ export class PlayCanvasSplatViewer {
     return alpha <= 0 || fits;
   }
 
+  /**
+   * The overlay's source: the live outgoing target, or null for the frozen capture. The same two
+   * quads, the same lerp / wipe — only the texture changes.
+   */
+  setSnapshotSource(tex) {
+    const s = this._snap;
+    if (!s?.parts) return;
+    for (const p of s.parts) {
+      p.mat.setParameter('dxrSnap', tex || s.tex);
+      p.mat.update();
+    }
+  }
+
+  /**
+   * The mono/capture camera as a lens frame, for the live outgoing's rig chain
+   * (./inline3d-splat-live.js): the rig node's matrix, the camera pose in rig space, the
+   * convergence distance c (along the view axis to the focus, which the pivot puts at the orbit
+   * centre) and t = tan(vertical fov / 2).
+   */
+  lensFrame() {
+    const pose = Float64Array.from(this.mono.pose);
+    const o = this._orbitCentre;
+    const fz = o.z + this._depthOffset;
+    let c = -((o.x - pose[12]) * pose[8] + (o.y - pose[13]) * pose[9] + (fz - pose[14]) * pose[10]);
+    if (!(c > 1e-6)) c = 1;
+    return { rig: this.rigMatrix(), pose, c, t: Math.tan((this.mono.fov * DEG) / 2) };
+  }
+
+  /** Can this tile render a live outgoing asset (the single-camera RenderView path)? */
+  get canLiveOutgoing() {
+    return LiveOutgoing.supported(this);
+  }
+
+  /** Start rendering `entity` live into its own target (see ./inline3d-splat-live.js). */
+  startLiveOutgoing(entity, oldFrame) {
+    this._live ||= new LiveOutgoing(this);
+    return this._live.start(entity, oldFrame) ? this._live : null;
+  }
+
+  /** End the live window: overlay back on the frozen capture, camera off, target freed. */
+  stopLiveOutgoing() {
+    if (!this._live?.active) return;
+    this.setSnapshotSource(null);
+    this._live.stop();
+  }
+
+  /**
+   * A transition has ended: free the frozen frame's texture (7 MB at 2560×720; it used to stay
+   * allocated until the next swap). The overlay quads stay, hidden; the next capture makes a new
+   * texture.
+   */
+  releaseSnapshot() {
+    const s = this._snap;
+    if (!s?.tex) return;
+    for (const p of s.parts || []) p.mi.visible = false;
+    s.rt?.destroy?.();
+    s.tex.destroy?.();
+    s.rt = s.tex = null;
+    s.w = s.h = 0;
+  }
+
   /** How many eye viewports sit side by side in the buffer right now (1 in mono). */
   get viewsAcross() {
     return this._mode === '3d' && this._lastGood ? this._lastGood.entries.length : 1;
@@ -1500,6 +1570,8 @@ export class PlayCanvasSplatViewer {
       // The camera NODE drives the sort direction and LOD distance; the views ignore it (they
       // compose the node's PARENT with their own pose). Park it on the first eye.
       placeNode(this.eye, entries[0].pose);
+      // setSource's live outgoing: the same views on its own camera, into its own target.
+      if (this._live?.active) this._live.sync(entries, rect, f);
     } else {
       // Fallback: one camera per view, `rect` + `calculateProjection`.
       const cams = this._views;
@@ -1640,7 +1712,7 @@ export class PlayCanvasSplatViewer {
   /**
    * The eyes' frame in WORLD (content) space, for effects keyed on "where the viewer is":
    * `origin` = the midpoint of the eyes drawn last (the mono camera in 2D), `axis`/`right`/`up` =
-   * the first eye's forward/right/up, `tanHalfFovX` its lens half-width.
+   * the first eye's forward/right/up, `tanHalfFovX` / `tanHalfFovY` its lens half-extents.
    */
   eyeFrame() {
     const R = this.rigMatrix();
@@ -1667,6 +1739,7 @@ export class PlayCanvasSplatViewer {
       right: unit(M[0], M[1], M[2]),
       up: unit(M[4], M[5], M[6]),
       tanHalfFovX: p0 > 0 ? 1 / p0 : 0.5,
+      tanHalfFovY: es[0].proj?.[5] > 0 ? 1 / es[0].proj[5] : 0,
     };
   }
 
@@ -1859,7 +1932,7 @@ function perfSpan(name, t0) {
   }
 }
 
-export async function readCloud(resource) {
+export async function readCloud(resource, yielder = yieldToMain) {
   if (!resource) return null;
   const centers = resource.centers;
   const data = resource.gsplatData;
@@ -1869,7 +1942,7 @@ export async function readCloud(resource) {
   const total = Math.ceil(sourceTotal / stride);
   // Not in the task that delivered the asset: the engine's own end-of-load work (its centre
   // readback unpack) runs there, and stacking ours on it made one long task.
-  await yieldToMain();
+  await yielder();
   let t0 = performance.now();
   const xyz = new Float32Array(total * 3);
   for (let j = 0, i = 0; j < total; j++, i += stride) {
@@ -1878,7 +1951,7 @@ export async function readCloud(resource) {
     xyz[j * 3 + 2] = centers[i * 3 + 2];
   }
   perfSpan('readCloud:copy', t0);
-  await yieldToMain();
+  await yielder();
   let opacity = null;
   // Full-resolution peak opacity, ONE BYTE per splat, kept for the exact pick (which walks the
   // engine's own full centre set at pick time): 1.18 MB on the 1.18M bench asset.
@@ -1888,7 +1961,7 @@ export async function readCloud(resource) {
       t0 = performance.now();
       const px = await data.sh0.read(0, 0, data.sh0.width, data.sh0.height, { mipLevel: 0, face: 0, immediate: true });
       perfSpan('readCloud:sh0-readback(async)', t0);
-      await yieldToMain();
+      await yielder();
       t0 = performance.now();
       if (px && px.length >= sourceTotal * 4) {
         const v2 = data.meta?.version === 2;
@@ -2091,7 +2164,8 @@ export function resolveSwap(o = {}) {
   if (transition === 'wavefront') {
     EFFECTS.wavefront.validate({ band, ridge, ridgeMaxDisparity });
   }
-  return { transition, durationMs: transition === 'crossfade' && durationMs === 0 ? 800 : durationMs, easing, reveal, band, ridge, ridgeMaxDisparity };
+  const outgoing = resolveOutgoingOption(o.outgoing);
+  return { transition, durationMs: transition === 'crossfade' && durationMs === 0 ? 800 : durationMs, easing, reveal, band, ridge, ridgeMaxDisparity, outgoing };
 }
 
 /**
@@ -2164,6 +2238,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let handle = null;
   let unbindFocusInput = null;
   let removed = false;
+  /** prepareSource: prepared handle → { loaded, state: 'ready' | 'used' | 'disposed', dispose }. */
+  const preparedAssets = new WeakMap();
+  const livePrepared = new Set();
   /** The asset on screen: its resource, kind, the pick data it keeps. */
   let current = null; // { asset, entity, res, kind, streamedBounds, alpha8, pickCentres }
 
@@ -2232,6 +2309,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       return pickModel(clientX, clientY);
     },
     setSource,
+    prepareSource,
     /**
      * Play a transition effect (inflate, deflate, sweep, dissolve, fade, pulse, custom) — see
      * docs/splat-effects.md. Validated now; runs once the first asset is on screen. Resolves
@@ -2259,6 +2337,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     remove() {
       removed = true;
       current = null;
+      for (const p of [...livePrepared]) p.dispose();
       fx?.dispose();
       fx = null;
       unbindFocusInput?.();
@@ -2587,7 +2666,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // ── load ──
   let byteSeqLocal = 0;
   /** Fetch/parse one source into an engine asset, and read what the waterfall needs from it. */
-  async function loadOne(pc, app, source) {
+  async function loadOne(pc, app, source, { background = false } = {}) {
+    // prepareSource: our own passes run in idle periods; setSource: at the task's own priority.
+    const y = background ? yieldIdle : yieldToMain;
     let bytes = null;
     if (typeof source !== 'string') {
       const buf = source instanceof Blob ? await source.arrayBuffer() : source;
@@ -2634,7 +2715,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // A URL `.sog` carries its meta in the resource (the engine keeps unknown keys); a Streamed
     // SOG carries it at the top level of lod-meta.json. Both validated by the same reader.
     if (!bytes && rigOpts.rig !== 'display') camera = sogCameraFromMeta(desc.meta);
-    const cloud = desc.kind === 'flat' ? await readCloud(res) : null;
+    const cloud = desc.kind === 'flat' ? await readCloud(res, y) : null;
     // The cloud passes, each in its OWN task: framing, the rest-space sample and the pick set
     // were one ~60 ms main-thread block on a 1.18M-gaussian swap — pointer input waited on it.
     // Split with a yield between them (and a linear-time percentile in boundsFromPositions),
@@ -2642,20 +2723,26 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const pre = { local: null, rest: null, pickCentres: null };
     if (cloud) {
       const walk = centresVisitor(cloud.xyz, cloud.opacity, cloud.total);
-      await yieldToMain();
+      await y();
       let t = performance.now();
-      pre.local = boundsFromPositions(sampleCloudCentres(cloud.total, walk) || []);
+      const framed = sampleCloudCentres(cloud.total, walk) || [];
+      perfSpan('cloud:frame-sample', t);
+      await y();
+      // The percentile core per axis + the window pass, each in its own task (bit-identical to
+      // boundsFromPositions): one ~60-80 ms task per 1.18M gaussians at 4× CPU before.
+      t = performance.now();
+      pre.local = await boundsFromPositionsAsync(framed, undefined, y);
       perfSpan('cloud:bounds', t);
-      await yieldToMain();
+      await y();
       t = performance.now();
       if (rigNeedsCloud(camera)) pre.rest = sampleCloudRestSpace(cloud.total, walk, camera?.rest);
       perfSpan('cloud:rest-sample', t);
-      await yieldToMain();
+      await y();
       t = performance.now();
       const s = sampleCloudCentres(cloud.total, walk, { cap: RIG_SAMPLE_CAP });
       pre.pickCentres = s ? s.slice() : null;
       perfSpan('cloud:pick-set', t);
-      await yieldToMain();
+      await y();
     }
     return { asset, res, desc, camera, cloud, pre };
   }
@@ -2796,6 +2883,49 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return out;
   });
 
+  // ── prepareSource: load the next asset in the background, for a setSource with no load ──
+  /**
+   * Fetch, decode and upload `src` now, without rendering it: the engine's load (its own unpack
+   * runs when it must) and our cloud passes (framing, rig sample, pick set — in IDLE periods).
+   * Resolves to an opaque handle for setSource(prepared, opts), which then starts on the next
+   * frame with no load on the transition frame. `dispose()` if the page changes its mind.
+   * Memory: the prepared asset is fully resident (a 1.18M-gaussian SOG: its GPU textures plus the
+   * engine's centre array) alongside the current one until it is used or disposed.
+   */
+  async function prepareSource(src) {
+    const app = await booted;
+    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 });
+    perfSpan('prepareSource', t0);
+    const entry = { loaded, state: 'ready', dispose: null };
+    const prepared = {
+      [PREPARED_TAG]: true,
+      /** The asset's own count (every splat of a flat source). */
+      numSplats: loaded.desc.numSplats || loaded.cloud?.sourceTotal || 0,
+      /** 'ready' until setSource uses it ('used') or dispose() drops it ('disposed'). */
+      get state() {
+        return entry.state;
+      },
+      dispose() {
+        if (entry.state !== 'ready') return;
+        entry.state = 'disposed';
+        livePrepared.delete(entry);
+        app.assets.remove(loaded.asset);
+        loaded.asset.unload?.();
+      },
+    };
+    entry.dispose = prepared.dispose;
+    preparedAssets.set(prepared, entry);
+    if (removed) {
+      prepared.dispose();
+      throw new Error('@displayxr/inline3d/splat: prepareSource on a removed tile.');
+    }
+    livePrepared.add(entry);
+    return prepared;
+  }
+
   // ── setSource: swap the asset — a cut, a crossfade, or a transition ──
   let sourceGen = 0;
   let pendingSwap = null;
@@ -2818,11 +2948,22 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const plan = resolveSwap(o);
     const { resetPose = false } = o;
     const gen = ++sourceGen;
+    // A prepareSource() result: already fetched, decoded and uploaded — no load on this path.
+    const prep = preparedAssets.get(next) || null;
+    if (prep) {
+      if (prep.state !== 'ready') {
+        throw new Error(`@displayxr/inline3d/splat: setSource got a prepared source that was already ${prep.state === 'used' ? 'used' : 'disposed'}.`);
+      }
+      prep.state = 'used';
+      livePrepared.delete(prep);
+    } else if (next && typeof next === 'object' && next[PREPARED_TAG]) {
+      throw new Error('@displayxr/inline3d/splat: setSource got a prepared source from another handle.');
+    }
     const app = await booted;
     await first.catch(() => null); // a failed first asset may be replaced
     if (!app || removed) return out;
     const pc = pcModule;
-    const loaded = await loadOne(pc, app, next);
+    const loaded = prep ? prep.loaded : await loadOne(pc, app, next);
     if (removed || gen !== sourceGen) {
       app.assets.remove(loaded.asset);
       loaded.asset.unload?.();
@@ -2841,6 +2982,19 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       return out;
     }
     if (snapped) viewer.setSnapshotAlpha(1, transition === 'wavefront' ? { t: 0, band: plan.band, views: viewer.viewsAcross } : null);
+    // LIVE outgoing (default in 3D): the old asset stays resident and keeps rendering, through the
+    // same eye views, into its own target; the frozen capture above bridges the first frames until
+    // its camera has drawn a sorted frame. Its lens frame is read BEFORE adopt() switches the rig.
+    const outgoingMode = plan.outgoing || defaultOutgoing(viewer.is3D);
+    const live =
+      snapped && outgoingMode === 'live' && viewer.canLiveOutgoing ? viewer.startLiveOutgoing(prev.entity, viewer.lensFrame()) : null;
+    /** 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;
+    };
 
     const release = (p) => {
       if (!p) return;
@@ -2925,16 +3079,30 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     }
 
     if (transition === 'wavefront' && snapped) {
-      release(prev); // the snapshot shows it from here on
+      if (live) {
+        finishers.push(() => {
+          viewer.stopLiveOutgoing();
+          release(prev);
+        });
+      } else release(prev); // the snapshot shows it from here on
       const band = plan.band;
       const ridge = fx.play(
         'wavefront',
         { durationMs: plan.durationMs, easing: plan.easing, band, ridge: plan.ridge, ridgeMaxDisparity: plan.ridgeMaxDisparity, scope: 'entity' },
         { entity, gate: afterTicks(2), internal: true },
       );
-      finishers.push(() => viewer.setSnapshotAlpha(0));
+      finishers.push(() => {
+        viewer.setSnapshotAlpha(0);
+        viewer.releaseSnapshot();
+      });
       viewer._hooks.push(() => {
         if (finished || removed) return false;
+        if (live && !live.fits) {
+          fx?.stop('wavefront', { finish: true, entity });
+          finish();
+          return false;
+        }
+        pumpLive();
         const inst = fx?.scopes.get(entity)?.get('wavefront');
         const amount = inst ? inst.amount : 1;
         if (!viewer.setSnapshotAlpha(1, { t: amount, band, views: viewer.viewsAcross })) {
@@ -2953,14 +3121,21 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // the 1.12.1 one-pass fade, over the same duration.
     const fade = plan.durationMs;
     if (plan.reveal) fx.play(plan.reveal.type, { ...plan.reveal.raw, scope: 'entity' }, { entity, gate: afterTicks(2) });
-    if (snapped) release(prev); // the snapshot shows it from here on
-    else {
+    if (snapped) {
+      if (!live) release(prev); // the snapshot shows it from here on
+    } else {
       setFade(entity, 0);
       setFade(prev.entity, 1);
     }
     finishers.push(() => {
-      if (snapped) viewer.setSnapshotAlpha(0);
-      else {
+      if (snapped) {
+        viewer.setSnapshotAlpha(0);
+        viewer.releaseSnapshot();
+        if (live) {
+          viewer.stopLiveOutgoing();
+          release(prev);
+        }
+      } else {
         setFade(entity, null);
         release(prev);
       }
@@ -2974,12 +3149,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     viewer._hooks.push((t) => {
       if (removed) return (finish(), false);
       if (finished) return false; // superseded: already finished
+      pumpLive();
       if (++ticks < 2) return true;
       if (t0 === null) t0 = t;
       const k = Math.min(1, Math.max(0, (t - t0) / fade));
       if (snapped) {
         // A resize or a 2D/3D switch mid-fade: the capture no longer fits the buffer — end now.
-        if (!viewer.setSnapshotAlpha(1 - k)) {
+        if (!viewer.setSnapshotAlpha(1 - k) || (live && !live.fits)) {
           finish();
           return false;
         }
@@ -3008,3 +3184,5 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 }
 
 let byteSeq = 0;
+/** Marks a prepareSource() result (so one from another handle is caught, not loaded as bytes). */
+const PREPARED_TAG = Symbol.for('@displayxr/inline3d/splat.prepared');

package/js/inline3d-splat.js

@@ -369,6 +369,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
           "only; with the Spark backend, remove() this handle and addSplat() the new asset.",
       );
     },
+    /** Not on this backend: prepareSource() feeds setSource(), a PlayCanvas-backend feature. */
+    prepareSource() {
+      throw new Error("@displayxr/inline3d/splat: prepareSource() is implemented on the PlayCanvas backend only.");
+    },
     /** Not on this backend (splat effects are PlayCanvas-only in this version). */
     playEffect() {
       throw effectsNotOnSpark('playEffect()');
@@ -706,6 +710,7 @@ function addSplatDeferred(wall, canvas, src, opts) {
     // A swap requested before the first asset has landed runs once it has (the adapter's own
     // setSource replaces this stub on the same object by then).
     setSource: (...args) => out.ready.then(() => out.setSource(...args)),
+    prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
     // Effects before the adapter has loaded: validated NOW (a bad call throws at its own line),
     // then run once the first asset is on screen.
     playEffect: (name, o) => {

package/js/inline3d-viewer.js

@@ -152,7 +152,30 @@ function swap(a, i, j) {
  *        Set 0 to get the old percentile-only box back.
  * @returns {{center:number[], extent:number[]}|null} null if there is nothing to measure.
  */
-export function boundsFromPositions(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 } = {}) {
+export function boundsFromPositions(xyz, opts) {
+  const it = boundsSteps(xyz, opts);
+  let r = it.next();
+  while (!r.done) r = it.next();
+  return r.value;
+}
+
+/**
+ * boundsFromPositions, in steps: the same code, the same numbers bit for bit, but a caller can
+ * give the main thread back between the per-axis selections and the window pass. On a 1.18M
+ * gaussian cloud under 4× CPU throttling the one-shot version was a single 60-80 ms task.
+ * `await boundsFromPositionsAsync(xyz, opts, yielder)` runs it with `yielder()` between steps.
+ */
+export async function boundsFromPositionsAsync(xyz, opts, yielder) {
+  const it = boundsSteps(xyz, opts);
+  let r = it.next();
+  while (!r.done) {
+    await yielder();
+    r = it.next();
+  }
+  return r.value;
+}
+
+function* boundsSteps(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 } = {}) {
   const n = Math.floor(xyz.length / 3);
   if (n < 1) return null;
   // Below a few hundred points the percentiles are noise — just use the true box.
@@ -171,6 +194,7 @@ export function boundsFromPositions(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 }
     const hiV = selectKth(axisVals, n, kHi);
     center[axis] = 0.5 * (loV + hiV);
     extent[axis] = Math.max(hiV - loV, 1e-6);
+    yield;
   }
   // Untrimmed already IS the true box, and expand 0 asks for the old behaviour.
   if (!trim || expand <= 0) return { center, extent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.13.0",
+  "version": "1.14.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",
@@ -51,6 +51,7 @@
     "js/inline3d-splat-playcanvas.js",
     "js/inline3d-splat-shared.js",
     "js/inline3d-splat-effects.js",
+    "js/inline3d-splat-live.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",

package/splat.d.ts

@@ -336,7 +336,62 @@ export interface SplatOptions {
 }
 
 /** The transition effects `reveal` accepts. */
-export type SplatRevealName = 'inflate' | 'sweep' | 'dissolve' | 'fade';
+export type SplatRevealName = 'inflate' | 'sweep' | 'dissolve' | 'fade' | SplatParticleRevealName;
+
+/** The particle reveals: every gaussian is a particle with its own start time (docs/splat-effects.md §Particle reveals). */
+export type SplatParticleRevealName = 'assemble' | 'dissolve-in' | 'converge' | 'shimmer';
+
+/**
+ * Options every particle reveal takes (plus its timing). All sizes are in PICTURE units, so the
+ * look is the same on a 2 cm object and a 40 m street.
+ */
+export interface SplatParticleOptions {
+  /**
+   * What staggers the particles: `'radial'` (distance in the picture from the origin), `'depth'`
+   * (near first), `'noise'` (fbm patches), `'random'`, or `'layers'` (a SHARP photo's grid order:
+   * layer 0, the visible surface, then layer 1, the disocclusion fill, each outward from the
+   * origin — reads `splat.index`, so it forces `scope: 'entity'`).
+   */
+  order?: 'radial' | 'depth' | 'noise' | 'random' | 'layers';
+  /** Fraction of the duration spent launching particles, 0..0.95. */
+  stagger?: number;
+  /** How much of each particle's key is random, 0..1. */
+  jitter?: number;
+  /** A particle in flight is a dot this size (a fraction of the view width). */
+  dotSize?: number;
+  /** A particle grows back to its own splat over the last (1 − grow) of its flight. */
+  grow?: number;
+  /** In-flight alpha multiplier, 0..1. */
+  flightAlpha?: number;
+  /** In-flight tint, added as `color · glow`. */
+  color?: [number, number, number];
+  glow?: number;
+  /** Size of the noise patches, per half-view-width. */
+  noiseScale?: number;
+  /**
+   * Comfort cap: no particle is ever nearer the eyes than its home depth by more than this much
+   * extra disparity, a fraction of the eye view's width (default 0.004; 0 = never nearer than
+   * home; max 0.05). In 2D a nominal 64 mm-at-1.7 m separation is assumed.
+   */
+  maxDisparity?: number;
+  /** `order: 'layers'`: gaussians per layer (default 768² = 589 824, SHARP). */
+  layerSize?: number;
+  /** `assemble`: how far out the swarm starts (half-view-widths), its spiral (rad), its curl turbulence, how coherent its start field is (0..1), and how much of it reaches back in depth (0..1). */
+  spread?: number;
+  swirl?: number;
+  turbulence?: number;
+  coherence?: number;
+  depth?: number;
+  /** `dissolve-in`: the wind's lift and the random drift (half-view-widths). */
+  lift?: number;
+  drift?: number;
+  /** `converge`: the spiral (rad) and the launch ball's radius (half-view-widths). */
+  spin?: number;
+  burst?: number;
+  /** `shimmer`: twinkle rate (rad/s) and sparkle strength. */
+  twinkle?: number;
+  sparkle?: number;
+}
 
 /** Named easings; a function `(x) => y` on [0, 1] also works. */
 export type SplatEasing =
@@ -397,7 +452,7 @@ export interface SplatCustomEffect extends SplatEffectTiming {
   hold?: boolean;
 }
 
-export type SplatEffectName = 'inflate' | 'deflate' | 'sweep' | 'dissolve' | 'fade' | 'pulse' | 'grade' | 'clip' | 'custom' | `custom:${string}`;
+export type SplatEffectName = 'inflate' | 'deflate' | 'sweep' | 'dissolve' | 'fade' | SplatParticleRevealName | 'pulse' | 'grade' | 'clip' | 'custom' | `custom:${string}`;
 
 /** `setEffect('grade', …)`. */
 export interface SplatGradeParams {
@@ -454,6 +509,29 @@ export interface SplatSourceOptions {
   ridge?: number;
   /** `wavefront`: the ridge's disparity cap, a fraction of the eye view's width (default 0.004, max 0.05). */
   ridgeMaxDisparity?: number;
+  /**
+   * `crossfade` / `wavefront`: how the OUTGOING photo is shown during the window.
+   * `'live'` (the default in a woven 3D session): it stays resident and keeps rendering every frame
+   * through the same eye views (head motion included) into its own target, blended per eye with
+   * the live incoming one — about 2× draw for the window, both assets resident. `'frozen'` (the
+   * default in 2D): its last frame, frozen into a texture (1.12.1); one draw, but no head parallax
+   * on the outgoing photo — on a tracked panel it reads as tracking pausing. Engine builds without
+   * the single-camera RenderView path always use `'frozen'`.
+   */
+  outgoing?: 'live' | 'frozen';
+}
+
+/**
+ * What `prepareSource()` resolves to: an opaque, single-use handle for `setSource`. The asset is
+ * fully resident (GPU textures + the engine's centre array) until used or disposed.
+ */
+export interface SplatPreparedSource {
+  /** The asset's own count (every splat of a flat source). */
+  readonly numSplats: number;
+  /** `'ready'` until `setSource` uses it (`'used'`) or `dispose()` drops it (`'disposed'`). */
+  readonly state: 'ready' | 'used' | 'disposed';
+  /** Release the prepared asset (no-op once used or disposed). */
+  dispose(): void;
 }
 
 /** What `onBeforeFrame` receives. */
@@ -592,20 +670,32 @@ export interface SplatHandle {
   /**
    * Swap the asset (URL or bytes) in place. PlayCanvas backend only — throws on Spark.
    *
-   * The new file loads BEHIND the current one; then the two crossfade over `fadeMs` (0 = a cut)
-   * and the old one is released. The crossfade blends the two IMAGES linearly: the last frame of
-   * the old asset is frozen (both eyes) and lerped with the live new one, so the mix is exactly
-   * `t` whatever the two photos' depth order (the old asset's own motion stops during the fade). The rig waterfall re-runs for the new file (rig, lens, focus and
+   * The new file loads BEHIND the current one (or pass a `prepareSource()` result: no load at all
+   * on this path); then the two crossfade over `fadeMs` (0 = a cut) and the old one is released.
+   * The crossfade blends the two IMAGES linearly, per eye, so the mix is exactly `t` whatever the
+   * two photos' depth order. The old image is LIVE in a woven 3D session (it keeps rendering with
+   * head motion; `outgoing: 'frozen'` restores the 1.12.1 frozen last frame, the 2D default). The
+   * end state is exactly a plain swap. The rig waterfall re-runs for the new file (rig, lens, focus and
    * frame update; `onFocusChange` fires). The pose (yaw/pitch/zoom/depth) is kept unless
    * `resetPose`. A newer call supersedes an older one still loading. Resolves once the fade has
    * finished; rejects if the new asset cannot be loaded (the current one stays on screen).
    */
-  setSource(src: string | Blob | ArrayBuffer | Uint8Array, opts?: SplatSourceOptions): Promise<SplatHandle>;
+  setSource(src: string | Blob | ArrayBuffer | Uint8Array | SplatPreparedSource, opts?: SplatSourceOptions): Promise<SplatHandle>;
+  /**
+   * PlayCanvas backend only — throws on Spark. Fetch, decode and upload `src` now, in the
+   * background (the SDK's own passes in idle periods; the engine's end-of-load unpack runs when
+   * it must), without rendering it. `setSource(prepared, opts)` then starts on the next frame with
+   * no load on the transition path. Single use; `dispose()` it if the page changes its mind.
+   * Memory: two full assets resident until the swap (≈ +70 MB of GPU textures per 1.18M-gaussian
+   * SOG). `remove()` disposes any still unused.
+   */
+  prepareSource(src: string | Blob | ArrayBuffer | Uint8Array): Promise<SplatPreparedSource>;
   /**
    * `engine: 'playcanvas'` only (throws on Spark). Play a transition/pulse/custom effect;
    * validated at the call, run once the first asset is on screen. Resolves `{ finished }` —
    * false when stopped or replaced. docs/splat-effects.md.
    */
+  playEffect(name: SplatParticleRevealName, opts?: Omit<SplatEffectTiming, 'direction'> & SplatParticleOptions): Promise<{ finished: boolean }>;
   playEffect(
     name: Exclude<SplatEffectName, 'grade' | 'clip'>,
     opts?: SplatEffectTiming & Record<string, unknown>,