@displayxr/inline3d 1.13.1 → 1.15.0

package/js/inline3d-splat-playcanvas.js

@@ -49,15 +49,20 @@ 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,
   EFFECTS,
   EASINGS,
   resolveRevealOption,
+  resolveEffectOptions,
   validateEffectCall,
+  PARTICLE_TRANSITIONS,
+  PARTICLE_TRANSITION_OPTIONS,
+  particleSpan,
 } from './inline3d-splat-effects.js';
+import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
 import {
   clamp,
   finite,
@@ -668,6 +673,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 +994,8 @@ export class PlayCanvasSplatViewer {
       clearTimeout(w.timer);
       w.resolve(false);
     }
+    this._live?.destroy();
+    this._live = null;
     try {
       this.app?.destroy();
     } catch (err) {
@@ -1223,8 +1232,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 +1249,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;
@@ -1260,8 +1273,9 @@ export class PlayCanvasSplatViewer {
    * so a region only one of the two photos covers fades against the page, not against black.
    */
   _ensureSnapshotOverlay() {
-    const s = this._snap;
+    const s = (this._snap ||= { w: 0, h: 0, tex: null, rt: null, parts: null }); // prewarm: no capture yet
     if (s.parts) {
+      if (!s.tex) return;
       for (const p of s.parts) {
         p.mat.setParameter('dxrSnap', s.tex);
         p.mat.setParameter('dxrSnapInvSize', [1 / s.w, 1 / s.h]);
@@ -1286,6 +1300,7 @@ export class PlayCanvasSplatViewer {
         uniform vec2 dxrSnapInvSize;
         uniform float dxrSnapAlpha;
         uniform vec3 dxrSnapWipe; // t, band, views across (t < -1: no wipe)
+        uniform float dxrSnapOver; // 0 = lerp, 1 = A OVER the scene (the particle transitions)
         float dxrSnapWeight() {
           if (dxrSnapWipe.x < -1.0) return dxrSnapAlpha;
           float vw = 1.0 / (dxrSnapInvSize.x * dxrSnapWipe.z);
@@ -1300,10 +1315,13 @@ export class PlayCanvasSplatViewer {
       mat.depthTest = false;
       mat.depthWrite = false;
       mat.cull = pc.CULLFACE_NONE;
-      mat.setParameter('dxrSnap', s.tex);
-      mat.setParameter('dxrSnapInvSize', [1 / s.w, 1 / s.h]);
+      if (s.tex) {
+        mat.setParameter('dxrSnap', s.tex);
+        mat.setParameter('dxrSnapInvSize', [1 / s.w, 1 / s.h]);
+      }
       mat.setParameter('dxrSnapAlpha', 0);
       mat.setParameter('dxrSnapWipe', [-2, 0.1, 1]);
+      mat.setParameter('dxrSnapOver', 0);
       mat.update();
       const mi = new pc.MeshInstance(mesh, mat, new pc.GraphNode(name));
       mi.cull = false;
@@ -1312,7 +1330,14 @@ export class PlayCanvasSplatViewer {
       return { mat, mi };
     };
     s.parts = [
-      part('inline3dSnapshotScale', 'gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0 - dxrSnapWeight());', pc.BLENDMODE_ZERO, pc.BLENDMODE_SRC_ALPHA, -2),
+      // lerp: dst·(1 − w); over: dst·(1 − w·A.a) — premultiplied A over the scene
+      part(
+        'inline3dSnapshotScale',
+        'float w = dxrSnapWeight(); float a = texture2D(dxrSnap, gl_FragCoord.xy * dxrSnapInvSize).a; gl_FragColor = vec4(0.0, 0.0, 0.0, mix(1.0 - w, 1.0 - w * a, dxrSnapOver));',
+        pc.BLENDMODE_ZERO,
+        pc.BLENDMODE_SRC_ALPHA,
+        -2,
+      ),
       part('inline3dSnapshotAdd', 'gl_FragColor = texture2D(dxrSnap, gl_FragCoord.xy * dxrSnapInvSize) * dxrSnapWeight();', pc.BLENDMODE_ONE, pc.BLENDMODE_ONE, -1),
     ];
     this.app.scene.layers.getLayerById(pc.LAYERID_UI).addMeshInstances(s.parts.map((p) => p.mi));
@@ -1322,10 +1347,10 @@ export class PlayCanvasSplatViewer {
    * Lerp the snapshot over the scene at `alpha` (0 hides it). Returns false when the canvas buffer
    * no longer matches the capture (resize, 2D/3D switch): the caller ends its fade.
    */
-  setSnapshotAlpha(alpha, wipe = null) {
+  setSnapshotAlpha(alpha, wipe = null, mix = 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;
@@ -1335,12 +1360,75 @@ export class PlayCanvasSplatViewer {
         // SAME viewport-relative x in every eye — a front at the zero-disparity plane, so both
         // eyes agree. `views` = eye viewports side by side across the buffer.
         p.mat.setParameter('dxrSnapWipe', wipe ? [wipe.t, wipe.band, wipe.views] : [-2, 0.1, 1]);
+        // setSource's particle transitions: the live outgoing image OVER the incoming one
+        p.mat.setParameter('dxrSnapOver', mix?.over ? 1 : 0);
         p.mat.update();
       }
     }
     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 +1588,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 +1730,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 +1757,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 +1950,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 +1960,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 +1969,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 +1979,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;
@@ -2066,8 +2157,40 @@ export const SOURCE_TRANSITIONS = Object.freeze({
   crossfade: {},
   flip: { durationMs: 2200, easing: 'easeInOutSine' },
   wavefront: { durationMs: 2000, easing: 'easeInOutSine', band: 0.18, ridge: 0.03, ridgeMaxDisparity: 0.004 },
+  // the particle transitions (./inline3d-splat-effects.js PARTICLE_TRANSITIONS)
+  ...Object.fromEntries(Object.entries(PARTICLE_TRANSITIONS).map(([k, v]) => [k, { durationMs: v.durationMs, easing: v.easing, particle: true }])),
 });
 
+/**
+ * A particle transition's two sides, resolved: { out: { effect, opts }, in: { effect, opts },
+ * overlap } — the table's defaults, then the page's shared particle options, then its
+ * per-side `outgoingFx` / `incomingFx` overrides. Every side is validated as its effect (throws).
+ */
+export function resolveParticleTransition(name, o = {}) {
+  const spec = PARTICLE_TRANSITIONS[name];
+  const shared = {};
+  for (const k of PARTICLE_TRANSITION_OPTIONS) if (o[k] !== undefined) shared[k] = o[k];
+  for (const k of ['outgoingFx', 'incomingFx']) {
+    if (o[k] !== undefined && (o[k] === null || typeof o[k] !== 'object')) throw new TypeError(`@displayxr/inline3d/splat: setSource ${k} must be an object of effect options.`);
+  }
+  const overlap = o.overlap ?? spec.overlap ?? 0;
+  if (!(typeof overlap === 'number' && overlap >= 0 && overlap <= 1)) throw new RangeError(`@displayxr/inline3d/splat: setSource overlap must be a number in [0, 1], got ${o.overlap}.`);
+  const side = (which, dflt, extra) => {
+    const effect = dflt.effect;
+    const opts = { ...dflt.opts, ...shared, ...(extra || {}) };
+    resolveEffectOptions(effect, { ...opts, scope: 'entity' }, 'set', { internal: true }); // throws on a bad one
+    return { effect, opts };
+  };
+  const out = side('out', spec.out, o.outgoingFx);
+  const inc = side('in', spec.in, o.incomingFx);
+  // Both photos run ONE render-time body, compiled for one `order`; `layers` reads splat.index,
+  // which is a file index only in a work-buffer modifier (not at render time).
+  const order = (x) => x.opts.order ?? EFFECTS[x.effect].defaults.order;
+  if (order(out) !== order(inc)) throw new Error(`@displayxr/inline3d/splat: setSource ${name}: both photos take the same order (got '${order(out)}' and '${order(inc)}').`);
+  if (order(inc) === 'layers') throw new Error(`@displayxr/inline3d/splat: setSource ${name}: order 'layers' is a reveal-only order (it needs the file index, which a transition's render-time body does not have).`);
+  return { out, in: inc, overlap };
+}
+
 /** Validate setSource's options into a plan (throws on a page bug, before anything loads). */
 export function resolveSwap(o = {}) {
   if (o === null || typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setSource options must be an object.');
@@ -2082,16 +2205,18 @@ export function resolveSwap(o = {}) {
   const easing = o.easing ?? d.easing ?? 'linear';
   if (typeof easing !== 'function' && !EASINGS[easing]) throw new Error(`@displayxr/inline3d/splat: unknown easing '${easing}'.`);
   const reveal = resolveRevealOption(o.reveal);
-  if (reveal && (transition === 'flip' || transition === 'wavefront')) {
+  if (reveal && (transition === 'flip' || transition === 'wavefront' || d.particle)) {
     throw new Error(`@displayxr/inline3d/splat: setSource reveal plays with transition 'cut' or 'crossfade'; '${transition}' is its own reveal.`);
   }
+  const particles = d.particle ? resolveParticleTransition(transition, o) : null;
   const band = o.band ?? d.band ?? 0.18;
   const ridge = o.ridge ?? d.ridge ?? 0.03;
   const ridgeMaxDisparity = o.ridgeMaxDisparity ?? d.ridgeMaxDisparity ?? 0.004;
   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, particles };
 }
 
 /**
@@ -2164,6 +2289,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 +2360,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 +2388,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 +2717,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 +2766,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 +2774,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 +2934,145 @@ 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, po = {}) {
+    if (po === null || typeof po !== 'object') throw new TypeError('@displayxr/inline3d/splat: prepareSource options must be an object.');
+    const warm = po.transition !== undefined ? resolveSwap(po) : null; // the setSource options it will get; throws on a bad one
+    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);
+    // The transition the page declared: compile its shader now, in the dwell, not on its first frame.
+    if (warm?.particles) await prewarmTransition(warm);
+    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;
+  }
+
+  // ── shader pre-warm for the particle transitions ──
+  const prewarmed = new Set();
+  /**
+   * Compile + link the render-time variant a particle transition will install, ahead of it. The
+   * first frame of a transition otherwise blocks on the link (GetProgramiv: 35–45 ms on an M1,
+   * measured with a trace) — on the very transition a user sees first. A throwaway material with
+   * the eye renderer's own description, defines and chunks, plus the transition's chunk, asks the
+   * engine's program library for the same variant the renderer will ask for (the library keys on
+   * the generated source + processing options, not on the material), so the compile is issued
+   * now and, with KHR_parallel_shader_compile, finishes off the main thread. Best effort: an
+   * engine whose internals differ just compiles on the transition's first frame, as before.
+   */
+  async function prewarmTransition(plan) {
+    const key = `${plan.particles.in.effect}|${plan.particles.in.opts.order ?? ''}`;
+    if (!fx || prewarmed.has(key)) return;
+    await yieldIdle();
+    if (removed || !fx) return;
+    try {
+      const pc = pcModule;
+      const cams = [viewer.eye, viewer._live?.cam].filter(Boolean);
+      const code = fx.sharedChunkCode('transition', plan.particles.in.effect, { order: plan.particles.in.opts.order });
+      const made = [];
+      let issued = 0;
+      for (const cam of cams) {
+        const cd = viewer.app?.renderer?.gsplatDirector?.camerasMap?.get?.(cam.camera?.camera);
+        let mi = null;
+        if (cd?.layersMap) for (const ld of cd.layersMap.values()) mi ||= ld?.gsplatManager?.renderer?.meshInstance ?? null;
+        const src = mi?.material;
+        const camera = cam.camera?.camera;
+        if (!src?.shaderDesc || !camera?.shaderParams || typeof src.getShaderVariant !== 'function') continue;
+        const m = new pc.ShaderMaterial(src.shaderDesc);
+        src.defines.forEach((v, k) => m.setDefine(k, v));
+        m.shaderChunks.copy(src.shaderChunks);
+        m.getShaderChunks(pc.SHADERLANGUAGE_GLSL).set('gsplatModifyVS', code);
+        m.blendState = src.blendState;
+        made.push(m.getShaderVariant({
+          device: viewer.app.graphicsDevice,
+          scene: viewer.app.scene,
+          objDefs: mi._shaderDefs,
+          cameraShaderParams: camera.shaderParams,
+          pass: 0, // SHADER_FORWARD
+          sortedLights: [],
+          viewUniformFormat: viewer.app.renderer?.viewUniformFormat ?? null,
+          vertexFormat: mi.mesh?.vertexBuffer?.format,
+        }));
+        issued++;
+      }
+      // the overlay's two quads (created on the first capture otherwise, and compiled on its draw)
+      const cam = viewer.eye?.camera?.camera;
+      if (cam?.shaderParams) {
+        viewer._ensureSnapshotOverlay();
+        for (const p of viewer._snap?.parts || []) {
+          made.push(p.mat.getShaderVariant?.({
+            device: viewer.app.graphicsDevice,
+            scene: viewer.app.scene,
+            objDefs: p.mi._shaderDefs,
+            cameraShaderParams: cam.shaderParams,
+            pass: 0,
+            sortedLights: [],
+            viewUniformFormat: viewer.app.renderer?.viewUniformFormat ?? null,
+            vertexFormat: p.mi.mesh?.vertexBuffer?.format,
+          }));
+        }
+      }
+      if (issued) prewarmed.add(key);
+      await finalizeWhenLinked(made.filter(Boolean));
+    } catch (err) {
+      console.info('[inline3d/splat] transition shader pre-warm skipped', err);
+    }
+  }
+
+  /**
+   * Creating a program only ISSUES its compile + link; the browser resolves the link when the
+   * program is first queried — the engine's first draw, blocking (the 35–50 ms GetProgramiv the
+   * trace shows, even for a program created seconds earlier). So finish the engine's own
+   * finalize here, in the dwell: wait (in idle periods, not blocking) for the link to complete
+   * where the browser reports it (KHR_parallel_shader_compile), then finalize.
+   */
+  async function finalizeWhenLinked(shaders) {
+    const dev = viewer.app?.graphicsDevice;
+    if (!dev) return;
+    const pending = () => shaders.filter((x) => x && !x.ready && !x.failed && x.impl?.finalize);
+    for (let i = 0; i < 40 && pending().length; i++) {
+      for (const x of pending()) if (x.impl.isLinked?.(dev)) x.impl.finalize(dev, x) || (x.failed = true);
+      if (pending().length) await yieldIdle(50);
+      if (removed) return;
+    }
+    // still linking (or no completion query): finalize now — a block in the dwell, not on the
+    // transition's first frame
+    for (const x of pending()) x.impl.finalize(dev, x) || (x.failed = true);
+  }
+
   // ── setSource: swap the asset — a cut, a crossfade, or a transition ──
   let sourceGen = 0;
   let pendingSwap = null;
@@ -2818,11 +3095,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?.();
@@ -2831,9 +3119,10 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const prev = current;
     pendingSwap?.finish();
     const transition = prev ? plan.transition : 'cut';
+    const particle = plan.particles && transition in PARTICLE_TRANSITIONS ? plan.particles : null;
     // 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';
+    const wantsSnapshot = transition === 'crossfade' || transition === 'wavefront' || !!particle;
     const snapped = wantsSnapshot ? await viewer.captureFrame() : false;
     if (removed || gen !== sourceGen) {
       app.assets.remove(loaded.asset);
@@ -2841,6 +3130,21 @@ 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.
+    // 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;
+    /** 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;
@@ -2916,6 +3220,12 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       return out;
     }
 
+    if (particle && snapped) {
+      playParticleTransition({ particle, plan, prev, entity, live, adopt, release, finishers, finish, isFinished: () => finished, pumpLive, isLiveShown: () => liveShown });
+      await done;
+      return out;
+    }
+
     adopt(entity);
     if (transition === 'cut') {
       release(prev);
@@ -2925,16 +3235,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 +3277,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 +3305,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;
         }
@@ -2997,6 +3329,108 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return out;
   }
 
+  /**
+   * setSource's particle transitions (swarm, burst, shimmer-cross, dust), once the frame snapshot
+   * is up. The OUTGOING asset plays its effect in reverse, on the live camera, keyed on its own
+   * frame (taken here, before the rig switches); the INCOMING one plays forwards on the eye camera,
+   * its frame re-taken when the clock starts. One clock drives both, on overlapping spans
+   * (particleSpan). The overlay puts the live outgoing image OVER the incoming one, per eye. With
+   * no live camera (outgoing:'frozen', or an engine without the RenderView path) the frozen frame
+   * fades out over the outgoing span while the incoming asset plays its side. The end: effects
+   * removed (modifiers deleted), overlay hidden, live camera off, old asset released — the frame
+   * is a plain cut's.
+   */
+  function playParticleTransition({ particle, plan, prev, entity, live, adopt, release, finishers, finish, isFinished, pumpLive, isLiveShown }) {
+    const ease = typeof plan.easing === 'function' ? plan.easing : EASINGS[plan.easing] || EASINGS.linear;
+    const overlap = particle.overlap;
+    // RENDER-TIME (the default): one tile-scope body, each photo's values on the mesh instance of
+    // the gsplat manager that draws it — the eye camera's (incoming) and the live camera's
+    // (outgoing). No work-buffer rewrite and no re-sort per frame. An engine that does not expose
+    // the managers' mesh instances gets the entity-scope modifiers instead (a full work-buffer
+    // rewrite + a re-sort per asset per frame: correct, but it hitches on a 1.18M photo).
+    const managerMi = (cam, layer) => {
+      const cd = viewer.app?.renderer?.gsplatDirector?.camerasMap?.get?.(cam?.camera?.camera);
+      if (!cd?.layersMap) return null;
+      if (layer) return cd.layersMap.get(layer)?.gsplatManager?.renderer?.meshInstance ?? null;
+      for (const ld of cd.layersMap.values()) if (ld?.gsplatManager?.renderer?.meshInstance) return ld.gsplatManager.renderer.meshInstance;
+      return null;
+    };
+    const eyeMi = () => managerMi(viewer.eye, null);
+    const liveMi = () => (live?.active ? managerMi(live.cam, live.layer) : null);
+    const shared = particle.out.effect === particle.in.effect && eyeMi() ? fx.driveShared('transition', particle.in.effect, { order: particle.in.opts.order }) : null;
+    // the outgoing side, BEFORE adopt(): its frame (eyes, focus, framing) is the old asset's
+    let outFx = null;
+    if (live) {
+      outFx = shared ? shared.side(liveMi, particle.out.opts) : fx.drive(prev.entity, particle.out.effect, particle.out.opts);
+      outFx.set(1, 0);
+    } else {
+      release(prev); // the frozen frame shows it from here on
+    }
+    adopt(entity);
+    // the incoming side, hidden (amount 0) until the clock starts
+    const inFx = shared ? shared.side(eyeMi, particle.in.opts) : fx.drive(entity, particle.in.effect, particle.in.opts);
+    inFx.set(0, 0);
+    viewer._transitionPath = shared ? 'render' : 'entity'; // diagnostics (docs §Gates)
+    finishers.push(() => {
+      viewer._transitionState = null;
+      if (shared) shared.remove();
+      else {
+        outFx?.remove();
+        inFx.remove();
+      }
+      viewer.setSnapshotAlpha(0);
+      viewer.releaseSnapshot();
+      if (live) {
+        viewer.stopLiveOutgoing();
+        release(prev);
+      }
+    });
+    const dur = plan.durationMs;
+    let t0 = null;
+    let ticks = 0;
+    viewer._hooks.push((t) => {
+      if (removed) return (finish(), false);
+      if (isFinished()) return false;
+      if (live && !live.fits) {
+        finish(); // a resize or a 2D/3D switch mid-window: end now
+        return false;
+      }
+      pumpLive();
+      // The clock starts on the SECOND tick (the incoming asset's first frame builds its work
+      // buffer) and, live, once the live camera has drawn a sorted frame (until then the frozen
+      // capture stands in for the outgoing photo, untouched).
+      if (++ticks < 2 || (live && !isLiveShown())) {
+        if (shared) {
+          // the managers (and their mesh instances) may be new: keep both photos' values on them
+          outFx?.set(1, 0);
+          inFx.set(0, 0);
+        }
+        if (!viewer.setSnapshotAlpha(1)) {
+          finish();
+          return false;
+        }
+        return true;
+      }
+      if (t0 === null) {
+        t0 = t;
+        inFx.restart(); // the incoming asset's frame, now its rig and first frames are in
+      }
+      const raw = dur > 0 ? Math.min(1, Math.max(0, (t - t0) / dur)) : 1;
+      const te = ease(raw);
+      const timeS = (t - t0) / 1000;
+      viewer._transitionState = { raw, live: !!live }; // diagnostics (docs §Gates)
+      const outSpan = particleSpan(te, overlap, 'out');
+      outFx?.set(1 - outSpan, timeS);
+      inFx.set(particleSpan(te, overlap, 'in'), timeS);
+      const ok = live ? viewer.setSnapshotAlpha(1, null, { over: true }) : viewer.setSnapshotAlpha(1 - outSpan);
+      if (!ok || raw >= 1) {
+        finish();
+        return false;
+      }
+      return true;
+    });
+  }
+
   // The load promise is RETURNED, never written to `out.ready`: ./splat's addSplat owns that
   // field (one promise, one owner).
   return first
@@ -3008,3 +3442,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');