@displayxr/inline3d 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.15.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive; the existing transitions
+and reveals render the same pixels.
+
+### Added
+
+- **Particle transitions for `setSource`** (#36): `transition: 'swarm' | 'burst' | 'shimmer-cross' | 'dust'`.
+  They play the particle reveals across a slide change, with both photos live, in 3D and in 2D.
+  The old photo plays its effect backwards while the new one plays it forwards, on overlapping
+  spans of one clock (`overlap`).
+  - `swarm`: the old photo disperses into a curl-noise swarm and the new one assembles out of one.
+  - `burst`: the old photo collapses into its focus and the new one bursts out of its own.
+  - `shimmer-cross`: twinkling points out and twinkling points in; nothing moves.
+  - `dust`: drifting dust out, gathering dust in.
+
+  Defaults are 2.6–2.8 s on a linear shared clock; each particle eases on its own path. The end
+  state is a `cut`, MAE 0.000 in colour and alpha in both eyes, and VRAM goes back to baseline.
+  A hidden tab gets the crossfade.
+  See [`docs/splat-effects.md` § Particle transitions](docs/splat-effects.md#particle-transitions).
+- They render at RENDER TIME. One tile-scope chunk serves both photos, and each photo's values
+  sit on the mesh instance of the gsplat manager that draws it. A first cut used entity-scope
+  work-buffer modifiers, which rewrote both 1.18M work buffers and re-sorted both every frame.
+  Measured in a visible Chrome, that cost 2D pacing its 120 Hz: p95 went from 16.7 ms to 9.8–10.1.
+  A photo with nothing to draw skips its draw.
+- **`prepareSource(src, { transition, … })`**: with a particle transition, this also compiles and
+  links its shaders in the dwell. Otherwise the first transition of each kind blocks its first
+  frame on the link: 35–50 ms, and 190 + 260 ms on a variant the machine has never compiled.
+- Particle options `vanish` (fade over the first part of the flight) and `density` (the share
+  drawn in flight). Both are off for the reveals.
+
+### Not changed
+
+- The live `crossfade` / `wavefront` still run at about 40 Hz in stereo on an M1 (median 25.6 ms).
+  They draw both photos in full for the whole window. The same skip-what-is-not-visible idea may
+  apply there; that is a follow-up.
+
 ## 1.14.0 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). New particle reveals are additive. One default changes pixels

package/js/inline3d-splat-effects.js

@@ -626,6 +626,8 @@ uniform float ${P}grow;
 uniform float ${P}tx;
 uniform vec3 ${P}glow;
 uniform float ${P}falpha;
+uniform float ${P}van;
+uniform float ${P}dens;
 float ${P}lp = -1.0;
 float ${P}h(vec3 c, float s) { return dxrFxHash(c + vec3(s * 17.13, s * 31.71, s * 7.31)); }
 // where a point sits in the PICTURE (image x, y in half-view-widths) and its log depth: noise is
@@ -683,6 +685,12 @@ void ${P}color(vec3 c, inout vec4 col) {
   float g = smoothstep(${P}grow, 1.0, lp);
   col.rgb += ${P}glow * (1.0 - g);
   col.a *= mix(${P}falpha, 1.0, g);
+  // setSource's particle transitions: a particle fades over the first "vanish" of its flight, so a
+  // swarm gathers out of nothing and a leaving photo's swarm thins out to nothing (0 = off)
+  if (${P}van > 0.0) col.a *= smoothstep(0.0, ${P}van, lp);
+  // "density" < 1: only that share of the gaussians is drawn in flight (the rest appear as they
+  // grow home), so a million-point swarm reads as a swarm, not as snow
+  if (${P}dens < 1.0 && ${P}h(c, 9.0) > ${P}dens) col.a *= g;
   ${extra}
 }
 `;
@@ -705,6 +713,8 @@ const PARTICLE_VALIDATE = (what, o) => {
   if (o.color !== undefined) vec3Of(o.color, `${what} color`);
   if (o.noiseScale !== undefined) num(o.noiseScale, `${what} noiseScale`, 1e-3, 1e3);
   if (o.maxDisparity !== undefined) num(o.maxDisparity, `${what} maxDisparity`, 0, 0.05);
+  if (o.vanish !== undefined) num(o.vanish, `${what} vanish`, 0, 1);
+  if (o.density !== undefined) num(o.density, `${what} density`, 0, 1);
   if (o.layerSize !== undefined && !(Number.isInteger(o.layerSize) && o.layerSize > 0)) {
     throw new RangeError(`@displayxr/inline3d/splat: ${what} layerSize must be a positive integer.`);
   }
@@ -773,6 +783,8 @@ const particleUniforms = (ctx, inst, amount, tMs) => {
     tx: s.tanX,
     glow: o.color.map((x) => x * o.glow),
     falpha: o.flightAlpha,
+    van: o.vanish,
+    dens: o.density,
   };
 };
 
@@ -785,11 +797,18 @@ const PARTICLE_DEFAULTS = {
   noiseScale: 2,
   dotSize: 0.0007,
   grow: 0.6,
+  vanish: 0,
+  density: 1,
 };
 
-/** A particle reveal's registry entry: `body(P)` adds the centre/rs stages (and extra uniforms). */
-function particleEffect(name, defaults, { body, color = particleColor, uniforms: extra = () => ({}), validate }) {
+/**
+ * A particle reveal's registry entry: `body(P)` adds the centre/rs stages (and extra uniforms).
+ * `hiddenAtZero(opts)`: nothing is drawn at amount 0 (converge / shimmer: not yet launched; the
+ * others with `vanish` > 0) — a setSource transition then skips that photo's draw.
+ */
+function particleEffect(name, defaults, { body, color = particleColor, uniforms: extra = () => ({}), validate, hiddenAtZero = (o) => o.vanish > 0 }) {
   return {
+    hiddenAtZero,
     stage: 'reveal',
     kind: 'transition',
     particle: true,
@@ -967,6 +986,7 @@ void ${P}rs(vec3 oc, vec3 mc, inout vec4 r, inout vec3 sc) {
 }
 `,
       color: (P) => particleColor(P, 'col.a *= smoothstep(0.0, 0.15, lp);'),
+      hiddenAtZero: () => true,
     },
   ),
 
@@ -1009,10 +1029,68 @@ void ${P}rs(vec3 oc, vec3 mc, inout vec4 r, inout vec3 sc) {
   col.rgb = mix(col.rgb, ${P}sc, min(1.0, tw * ${P}sp) * (1.0 - g));
   col.a *= smoothstep(0.0, 0.12, lp) * mix(0.55 + 0.45 * tw, 1.0, g);`,
         ),
+      hiddenAtZero: () => true,
     },
   ),
 });
 
+// ── setSource's particle transitions ─────────────────────────────────────────────────────────
+//
+// swarm / burst / shimmer-cross / dust: the OUTGOING photo plays a particle reveal backwards (its
+// gaussians leave home as dots and thin out to nothing, `vanish`) while the INCOMING one plays it
+// forwards, on overlapping spans of one clock. Both run as entity-scope effects driven by the
+// adapter (SplatEffects.drive); the outgoing one is drawn by the LIVE outgoing camera, and the
+// adapter composites the two live images per eye, the old one OVER the new one.
+
+/**
+ * The transitions and their defaults. `out` / `in` = the particle effect each side plays (out: in
+ * reverse) with its option overrides; `overlap` = how much of the clock the two spans share (0 =
+ * one after the other, 1 = both over the whole clock): out over [0, (1 + overlap)/2], in over
+ * [(1 − overlap)/2, 1] of the eased clock.
+ */
+export const PARTICLE_TRANSITIONS = Object.freeze({
+  swarm: {
+    durationMs: 2800,
+    easing: 'linear',
+    overlap: 0.45,
+    out: { effect: 'assemble', opts: { stagger: 0.65, jitter: 0.35, spread: 0.3, swirl: 1.8, density: 0.2, dotSize: 0.0009, vanish: 0.45, glow: 0.1 } },
+    in: { effect: 'assemble', opts: { stagger: 0.65, spread: 0.3, swirl: 1.8, density: 0.2, dotSize: 0.0009, vanish: 0.35, glow: 0.1 } },
+  },
+  burst: {
+    durationMs: 2600,
+    easing: 'linear',
+    overlap: 0.3,
+    out: { effect: 'converge', opts: { stagger: 0.5, density: 0.5, glow: 0.25 } },
+    in: { effect: 'converge', opts: { stagger: 0.55, density: 0.5 } },
+  },
+  'shimmer-cross': {
+    durationMs: 2600,
+    easing: 'linear',
+    overlap: 0.45,
+    out: { effect: 'shimmer', opts: { stagger: 0.75 } },
+    in: { effect: 'shimmer', opts: { stagger: 0.75 } },
+  },
+  dust: {
+    durationMs: 2800,
+    easing: 'linear',
+    overlap: 0.4,
+    out: { effect: 'dissolve-in', opts: { density: 0.4, vanish: 0.4, drift: 0.45 } },
+    in: { effect: 'dissolve-in', opts: { density: 0.4, vanish: 0.3 } },
+  },
+});
+
+/** Where a side stands at eased clock t: 0..1 over its span. */
+export function particleSpan(t, overlap, side) {
+  const v = Math.min(1, Math.max(0, overlap));
+  const a = side === 'out' ? 0 : (1 - v) / 2;
+  const b = side === 'out' ? (1 + v) / 2 : 1;
+  return Math.min(1, Math.max(0, (t - a) / Math.max(b - a, 1e-6)));
+}
+
+/** Options a page may pass through setSource to both sides of a particle transition. */
+export const PARTICLE_TRANSITION_OPTIONS = Object.freeze(['order', 'stagger', 'jitter', 'maxDisparity', 'dotSize', 'noiseScale', 'layerSize', 'origin']);
+
+
 /**
  * The wavefront's per-column commit, lt ∈ [0, 1], for eased progress `t` at normalised u — the
  * prototype's formula: column u starts at t = u·(1 − band) and has committed band later, so
@@ -1243,7 +1321,8 @@ export class SplatEffects {
       resolve: null,
       promise: null,
       originPoint: (ctx, eyes) => this._origin(inst, ctx, eyes),
-      elapsedS: (tMs) => (inst.startedAt === null ? 0 : Math.max(0, (tMs - inst.startedAt) / 1000)),
+      // a driven instance (drive()) is handed its time by the adapter's clock
+      elapsedS: (tMs) => (inst.timeS !== undefined ? inst.timeS : inst.startedAt === null ? 0 : Math.max(0, (tMs - inst.startedAt) / 1000)),
     };
     inst.promise = new Promise((r) => (inst.resolve = r));
     return inst;
@@ -1326,6 +1405,134 @@ export class SplatEffects {
     this._install(entity);
   }
 
+  /**
+   * An effect on one entity driven by the ADAPTER's clock, not the runner's (setSource's particle
+   * transitions: two effects on two assets, on overlapping spans of one transition clock). Hidden
+   * from effects() and from a page's stopEffect(). Returns { set(amount, timeS), restart(),
+   * remove() }: `amount` as the GLSL reads it (1 = the untouched asset), `restart()` re-takes the
+   * effect's frame (start()) — the incoming asset's, once its rig and first frames are in.
+   */
+  drive(entity, name, opts) {
+    const o = resolveEffectOptions(name, { ...opts, scope: 'entity', direction: 'in', progress: 0 }, 'set', { internal: true });
+    o.entity = entity;
+    const inst = this._makeInstance(name, o, 'set');
+    inst.hidden = true;
+    inst.timeS = 0;
+    this._replace(entity, name, inst);
+    this._setupInstance(inst);
+    this._apply(entity, inst, this.ctx.now());
+    this._install(entity);
+    const alive = () => !this._disposed && this.scopes.get(entity)?.get(name) === inst;
+    return {
+      set: (amount, timeS = inst.timeS) => {
+        if (!alive()) return;
+        inst.opts.progress = Math.min(1, Math.max(0, amount));
+        inst.timeS = timeS;
+        this._apply(entity, inst, this.ctx.now());
+      },
+      restart: () => {
+        if (!alive()) return;
+        inst.state = {};
+        this._setupInstance(inst);
+        this._apply(entity, inst, this.ctx.now());
+      },
+      remove: () => {
+        if (!alive()) return;
+        this.scopes.get(entity).delete(name);
+        inst.resolve({ finished: true });
+        this._install(entity);
+      },
+      get alive() {
+        return alive();
+      },
+    };
+  }
+
+  /**
+   * ONE tile-scope body for the two photos of a setSource particle transition, with each photo's
+   * values on its OWN mesh instance (the engine draws each photo through its own gsplat manager and
+   * renderer: the eye camera's for the incoming photo, the live camera's for the outgoing one).
+   * Render-time only: no work-buffer rewrite, no per-frame re-sort (an entity-scope modifier forces
+   * both, every frame, for each 1.18M asset — measured as the transitions' hitches). The chunk's
+   * material values are the untouched asset's (amount 1). Returns { side(getMeshInstance, opts),
+   * remove() }; a side is { set(amount, timeS), restart() }. `opts` of the two sides share what
+   * the GLSL is compiled from (the `order`).
+   */
+  driveShared(name, effect, opts) {
+    const def = EFFECTS[effect];
+    const o = resolveEffectOptions(effect, { ...opts, scope: 'tile', direction: 'in', progress: 1 }, 'set', { internal: true });
+    const inst = this._makeInstance(name, o, 'set');
+    inst.def = def;
+    inst.hidden = true;
+    inst.fixed = true; // its material values never change: no per-frame upload
+    this._replace('tile', name, inst);
+    this._setupInstance(inst);
+    this._apply('tile', inst, this.ctx.now());
+    this._install('tile');
+    const P = prefixOf(name);
+    const alive = () => !this._disposed && this.scopes.get('tile')?.get(name) === inst;
+    const touched = new Set();
+    const hidden = new Set(); // mesh instances this transition turned off (a photo with nothing to draw)
+    return {
+      side: (getMeshInstance, sideOpts) => {
+        const s = { opts: resolveEffectOptions(effect, { ...sideOpts, order: o.order, scope: 'tile', direction: 'in' }, 'set', { internal: true }), state: {}, timeS: 0 };
+        s.originPoint = (ctx, eyes) => this._origin(s, ctx, eyes);
+        s.elapsedS = () => s.timeS;
+        def.start?.(this.ctx, s);
+        return {
+          /** Upload this photo's values; false when its mesh instance is not there (yet). */
+          set: (amount, timeS = s.timeS) => {
+            if (!alive()) return false;
+            const mi = getMeshInstance();
+            if (!mi?.setParameter) return false;
+            s.timeS = timeS;
+            touched.add(mi);
+            // the values first, always: should the engine show the mesh again on its own (a
+            // rebuild sets its visibility), it draws this state, never the untouched photo
+            const values = def.uniforms(this.ctx, s, Math.min(1, Math.max(0, amount)), this.ctx.now());
+            for (const [k, v] of Object.entries(values)) mi.setParameter(P + k, v);
+            // Nothing of this photo is drawn at amount 0 (every particle hidden before its flight):
+            // skip its draw call rather than run the vertex stage for 1.18M invisible gaussians —
+            // the two photos then share the GPU only while their spans overlap.
+            if (amount <= 0 && def.hiddenAtZero?.(s.opts)) {
+              if (mi.visible !== false) {
+                mi.visible = false;
+                hidden.add(mi);
+              }
+            } else if (hidden.delete(mi)) mi.visible = true;
+            return true;
+          },
+          restart: () => {
+            s.state = {};
+            def.start?.(this.ctx, s);
+          },
+        };
+      },
+      remove: () => {
+        for (const mi of hidden) mi.visible = true;
+        hidden.clear();
+        for (const mi of touched) {
+          for (const k of Object.keys(mi.parameters || {})) if (k.startsWith(P)) mi.deleteParameter?.(k);
+        }
+        touched.clear();
+        if (!alive()) return;
+        this.scopes.get('tile').delete(name);
+        inst.resolve({ finished: true });
+        this._install('tile');
+      },
+    };
+  }
+
+  /**
+   * The tile chunk driveShared(name, effect, opts) WOULD install, without installing it — what
+   * setSource's shader pre-warm compiles ahead of the transition.
+   */
+  sharedChunkCode(name, effect, opts) {
+    const o = resolveEffectOptions(effect, { ...opts, scope: 'tile', direction: 'in', progress: 1 }, 'set', { internal: true });
+    const insts = [...(this.scopes.get('tile')?.values() ?? [])].filter((i) => i.name !== name);
+    return composeModifier([...insts, { name, def: EFFECTS[effect], opts: o }]).code;
+  }
+
   _setupInstance(inst) {
     // Also for a gated one (its held START state needs the geometry); re-run when the gate opens,
     // since the rig/framing may have changed meanwhile (setSource's flip adopts a new asset).
@@ -1346,7 +1553,7 @@ export class SplatEffects {
    */
   stop(name, { finish = false, entity = null } = {}) {
     for (const [key, n, inst] of [...this._all()]) {
-      if (name ? n !== name : inst.def.internal) continue;
+      if (inst.hidden || (name ? n !== name : inst.def.internal)) continue;
       if (entity && key !== entity) continue;
       const m = this.scopes.get(key);
       if (finish && inst.mode === 'play' && inst.opts.direction === 'out') {
@@ -1366,7 +1573,7 @@ export class SplatEffects {
   list() {
     const out = [];
     for (const [key, name, inst] of this._all()) {
-      if (inst.def.internal) continue;
+      if (inst.def.internal || inst.hidden) continue;
       out.push({
         name,
         scope: key === 'tile' ? 'tile' : 'entity',
@@ -1398,6 +1605,7 @@ export class SplatEffects {
   tick(tMs) {
     if (this._disposed) return;
     for (const [key, name, inst] of [...this._all()]) {
+      if (inst.fixed) continue;
       if (inst.mode === 'play') {
         if (inst.startGate) {
           this._apply(key, inst, tMs); // hold the start state

package/js/inline3d-splat-playcanvas.js

@@ -56,7 +56,11 @@ import {
   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 {
@@ -1269,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]);
@@ -1295,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);
@@ -1309,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;
@@ -1321,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));
@@ -1331,7 +1347,7 @@ 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.tex && s.w === this.canvas.width && s.h === this.canvas.height;
@@ -1344,6 +1360,8 @@ 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();
       }
     }
@@ -2139,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.');
@@ -2155,9 +2205,10 @@ 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;
@@ -2165,7 +2216,7 @@ export function resolveSwap(o = {}) {
     EFFECTS.wavefront.validate({ band, ridge, ridgeMaxDisparity });
   }
   const outgoing = resolveOutgoingOption(o.outgoing);
-  return { transition, durationMs: transition === 'crossfade' && durationMs === 0 ? 800 : durationMs, easing, reveal, band, ridge, ridgeMaxDisparity, outgoing };
+  return { transition, durationMs: transition === 'crossfade' && durationMs === 0 ? 800 : durationMs, easing, reveal, band, ridge, ridgeMaxDisparity, outgoing, particles };
 }
 
 /**
@@ -2892,13 +2943,17 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * 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) {
+  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,
@@ -2926,6 +2981,98 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     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;
@@ -2972,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);
@@ -2985,7 +3133,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // 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);
+    // 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. */
@@ -3070,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);
@@ -3173,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

package/package.json

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

@@ -374,6 +374,10 @@ export interface SplatParticleOptions {
    * home; max 0.05). In 2D a nominal 64 mm-at-1.7 m separation is assumed.
    */
   maxDisparity?: number;
+  /** Fade a particle over the first `vanish` of its flight (0 = off, the reveals' default; the particle transitions use ~0.3–0.45). */
+  vanish?: number;
+  /** Share of the gaussians drawn while in flight, 0..1 (1 = all, the reveals' default; the swarm uses 0.2). */
+  density?: 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). */
@@ -497,8 +501,15 @@ export interface SplatSourceOptions {
    * inflates out of its own; default 2200 ms), `'wavefront'` (a soft front crosses left → right
    * with a thin depth ridge riding it; default 2000 ms, ease-in-out; falls back to the crossfade
    * in a hidden tab). For photo slideshows: `crossfade` or `wavefront`.
-   */
-  transition?: 'cut' | 'crossfade' | 'flip' | 'wavefront';
+   *
+   * The particle transitions (docs/splat-effects.md §Particle transitions): `'swarm'` (the old
+   * photo disperses into a curl-noise swarm while the new one assembles out of one), `'burst'`
+   * (the old one collapses into its focus, the new one bursts out of its own), `'shimmer-cross'`
+   * (nothing moves: twinkling points out, twinkling points in) and `'dust'` (drifting dust out,
+   * gathering dust in). 2.6–2.8 s, linear shared clock (each particle eases itself). The old
+   * photo is live, in 2D too; a hidden tab gets the crossfade.
+   */
+  transition?: 'cut' | 'crossfade' | 'flip' | 'wavefront' | SplatParticleTransitionName;
   durationMs?: number;
   easing?: SplatEasing;
   /** `cut`/`crossfade` only: reveal the INCOMING asset (entity scope) while the old one fades. */
@@ -519,8 +530,34 @@ export interface SplatSourceOptions {
    * the single-camera RenderView path always use `'frozen'`.
    */
   outgoing?: 'live' | 'frozen';
+  /** Particle transitions: particle options for BOTH photos (the shared ones of the particle reveals). */
+  order?: SplatParticleOptions['order'];
+  stagger?: number;
+  jitter?: number;
+  maxDisparity?: number;
+  dotSize?: number;
+  noiseScale?: number;
+  layerSize?: number;
+  origin?: SplatEffectOrigin;
+  /** Particle transitions: how much of the clock the two photos' spans share, 0..1 (0 = one after the other). */
+  overlap?: number;
+  /** Particle transitions: option overrides for the OUTGOING photo's effect. */
+  outgoingFx?: SplatParticleOptions & Record<string, unknown>;
+  /** Particle transitions: option overrides for the INCOMING photo's effect. */
+  incomingFx?: SplatParticleOptions & Record<string, unknown>;
 }
 
+/**
+ * `prepareSource`'s options: the `setSource` options the prepared asset will be swapped in with.
+ * For a particle transition, its shaders are compiled and linked NOW, in the dwell — otherwise the
+ * first transition of each kind in a page blocks its first frame on the link (tens of ms, hundreds
+ * the first time a machine sees the variant). Validated like setSource's.
+ */
+export type SplatPrepareOptions = SplatSourceOptions;
+
+/** setSource's particle transitions (docs/splat-effects.md §Particle transitions). */
+export type SplatParticleTransitionName = 'swarm' | 'burst' | 'shimmer-cross' | 'dust';
+
 /**
  * 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.
@@ -689,7 +726,7 @@ export interface SplatHandle {
    * 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>;
+  prepareSource(src: string | Blob | ArrayBuffer | Uint8Array, opts?: SplatPrepareOptions): 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 }` —