@displayxr/inline3d 1.14.0 → 1.16.0

package/js/inline3d-splat-playcanvas.js

@@ -50,13 +50,17 @@ import {
   budgetPerManager,
 } from './inline3d-splat-perf.js';
 import { boundsFromPositions, boundsFromPositionsAsync } from './inline3d-viewer.js';
-import { cameraRigFromPose } from './inline3d-three.js';
+import { cameraRigFromPose, displayRig } 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 {
@@ -908,6 +912,21 @@ export class PlayCanvasSplatViewer {
     this._updateMonoProjection();
   }
 
+  /**
+   * Switch the eye camera(s) to another tone mapping, by name (TONE_MAPPINGS). Live: the engine
+   * picks the new shader variant on the next draw. handle.setRig's display rig uses it to give a
+   * page's meshes addModel's 'neutral' while the splat is hidden.
+   */
+  setToneMapping(name) {
+    const key = TONE_MAPPINGS[name] ? name : 'none';
+    this.toneMapping = key;
+    const pc = this.pc;
+    if (!pc) return;
+    const v = pc[TONE_MAPPINGS[key]] ?? pc.TONEMAP_NONE;
+    if (this.eye?.camera) this.eye.camera.toneMapping = v;
+    if (this._viewPath === 'cameras') for (const c of this._views) if (c?.camera) c.camera.toneMapping = v;
+  }
+
   /** Forget the auto-fit (scale 1, no subject box) — the camera rig's framing. */
   resetFit() {
     this._fitScale = 1;
@@ -1269,8 +1288,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 +1315,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 +1330,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 +1345,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 +1362,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 +1375,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();
       }
     }
@@ -2133,14 +2166,140 @@ export function describeResource(res) {
  * one-pass fade, with the coverage-linear alpha remap on both assets.
  */
 
+/**
+ * handle.setRig's DISPLAY-rig defaults: addModel's, so a mesh framed through setRig('display')
+ * sits exactly where `addModel(url, { engine: 'playcanvas' })` puts it (docs/playcanvas-adapter.md
+ * §setRig). `toneMapping` applies to the page's meshes while the splat is hidden (the splat keeps
+ * 'none' whenever it is shown); `environment: 'room'` installs addModel's neutral-studio IBL when
+ * the page has no `scene.envAtlas` of its own, and removes it again when the rig changes back.
+ */
+export const SET_RIG_DISPLAY_DEFAULTS = Object.freeze({
+  virtualDisplayHeight: 0.24,
+  fit: 'contain',
+  margin: 0.8,
+  depthLimit: DEFAULT_DEPTH_LIMIT,
+  fitSweep: true,
+  idleSpin: 8,
+  ipdFactor: 1,
+  parallaxFactor: 1,
+  perspectiveFactor: 1,
+  toneMapping: 'neutral',
+  environment: 'room',
+});
+
+export const SET_RIG_TYPES = Object.freeze(['display', 'camera', 'auto']);
+const SET_RIG_FITS = ['contain', 'cover', 'height', 'none'];
+let warnedSetRigKeys = false;
+
+const PAGE_SETRIG_ERROR =
+  "@displayxr/inline3d/splat: setRig() is not available with controls:'page' — the page owns the " +
+  'camera (its camera IS the rig). Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).';
+
+/**
+ * handle.setRig's arguments, validated and resolved (throws at the call, before anything runs).
+ * @returns {{type:'display'|'camera'|'auto', o?:object}}
+ */
+export function validateSetRig(type, o = {}, pageMode = false) {
+  if (pageMode) throw new Error(PAGE_SETRIG_ERROR);
+  if (!SET_RIG_TYPES.includes(type)) {
+    throw new Error(`@displayxr/inline3d/splat: setRig("${type}") — expected 'display', 'camera' or 'auto'.`);
+  }
+  if (o === null || typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setRig options must be an object.');
+  if (type !== 'display') return { type };
+  const D = SET_RIG_DISPLAY_DEFAULTS;
+  const known = new Set([...Object.keys(D), 'frame']);
+  const unknown = Object.keys(o).filter((k) => !known.has(k));
+  if (unknown.length && !warnedSetRigKeys) {
+    warnedSetRigKeys = true;
+    console.warn(
+      `[inline3d/splat] setRig('display') ignores ${unknown.join(', ')}` +
+        (unknown.includes('transitionMs') ? ' — a rig switch is a clean cut (no eased transition in this version)' : '') +
+        '.',
+    );
+  }
+  const num = (k, ok) => {
+    const v = o[k] === undefined ? D[k] : o[k];
+    if (!Number.isFinite(v) || !ok(v)) throw new Error(`@displayxr/inline3d/splat: setRig('display') — bad ${k}: ${o[k]}.`);
+    return v;
+  };
+  const fit = o.fit === undefined ? D.fit : o.fit;
+  if (!SET_RIG_FITS.includes(fit)) throw new Error(`@displayxr/inline3d/splat: setRig('display') — fit "${fit}", expected ${SET_RIG_FITS.join(' | ')}.`);
+  const toneMapping = o.toneMapping === undefined ? D.toneMapping : o.toneMapping;
+  if (!TONE_MAPPINGS[toneMapping]) {
+    throw new Error(`@displayxr/inline3d/splat: setRig('display') — toneMapping "${toneMapping}", expected ${Object.keys(TONE_MAPPINGS).join(' | ')}.`);
+  }
+  const environment = o.environment === undefined ? D.environment : o.environment;
+  if (!['room', 'neutral', 'none'].includes(environment)) {
+    throw new Error(`@displayxr/inline3d/splat: setRig('display') — environment "${environment}", expected 'room' | 'neutral' | 'none'.`);
+  }
+  let frame = null;
+  if (o.frame != null) {
+    const c = o.frame.center;
+    const e = o.frame.extent;
+    const v3 = (v) => (Array.isArray(v) || ArrayBuffer.isView(v) ? v.length >= 3 && [0, 1, 2].every((i) => Number.isFinite(v[i])) : v && [v.x, v.y, v.z].every(Number.isFinite));
+    if (!v3(c) || !v3(e)) throw new Error("@displayxr/inline3d/splat: setRig('display') — frame must be { center: [x,y,z], extent: [x,y,z] }.");
+    const a3 = (v) => (Array.isArray(v) || ArrayBuffer.isView(v) ? [v[0], v[1], v[2]] : [v.x, v.y, v.z]);
+    frame = { center: a3(c), extent: a3(e) };
+  }
+  return {
+    type,
+    o: {
+      vH: num('virtualDisplayHeight', (v) => v > 0),
+      fit,
+      margin: num('margin', (v) => v > 0),
+      depthLimit: num('depthLimit', (v) => v > 0),
+      fitSweep: o.fitSweep === undefined ? D.fitSweep : o.fitSweep !== false,
+      idleSpin: num('idleSpin', () => true),
+      ipdFactor: num('ipdFactor', (v) => v >= 0),
+      parallaxFactor: num('parallaxFactor', (v) => v >= 0),
+      perspectiveFactor: num('perspectiveFactor', (v) => v > 0),
+      toneMapping,
+      environment,
+      frame,
+    },
+  };
+}
+
 /** setSource's transitions and their defaults. */
 export const SOURCE_TRANSITIONS = Object.freeze({
   cut: {},
   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 +2314,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 +2325,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 };
 }
 
 /**
@@ -2197,6 +2357,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     observe,
     firstWovenHoldMs,
     preserveDrawingBuffer = false,
+    antialias = false,
   } = opts;
   // `sortIntervalMs` is accepted and has no effect here: the engine re-sorts when the camera
   // ROTATES (one directional sort serves every view), not on a timer — docs/playcanvas-adapter.md.
@@ -2310,6 +2471,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     },
     setSource,
     prepareSource,
+    setRig,
     /**
      * 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
@@ -2537,6 +2699,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   // ── focus → view rig ──
   let lastConvergence = Number.NaN;
+  // The camera rig's descriptor object (rewritten in place per focus change) and the DISPLAY rig
+  // declared through setViewRig, if any. `declaredDisplay` null + no camera rig pushed = the
+  // `virtualDisplayHeight` shorthand addScene was built with, which is where every non-page tile
+  // starts. A display rig after a camera rig has to be SENT (the shorthand cannot be restored),
+  // as the explicit descriptor it is shorthand for (displayRig: identity pose, factors 1).
+  let camRigObj = null;
+  let declaredDisplay = pageMode ? 'page' : 'shorthand';
   function pushViewRig(force) {
     if (pageMode) return; // pageTick declares the rig every frame
     if (!out.rig || out.rig.type !== 'camera') return;
@@ -2549,7 +2718,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     lastConvergence = d;
     out.rig.convergence = d;
     const q = quatFromMatrix(pose);
-    out.viewRig = cameraRigFromPose(
+    camRigObj ||= {};
+    declaredDisplay = null;
+    out.viewRig = camRigObj = cameraRigFromPose(
       {
         position: { x: pose[12], y: pose[13], z: pose[14] },
         orientation: { x: q[0], y: q[1], z: q[2], w: q[3] },
@@ -2559,7 +2730,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         convergence: d > 0 ? d : 0,
         ipdFactor: out.rig.ipdFactor,
         parallaxFactor: out.rig.parallaxFactor,
-        out: out.viewRig || {},
+        out: camRigObj,
       },
     );
     handle?.setViewRig?.(out.viewRig);
@@ -2770,16 +2941,11 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
             ? lift(frame)
             : null;
 
-    const sample = loaded.pre?.rest || null;
-    const box = canvas.getBoundingClientRect();
-    const resolved = resolveRig({
-      camera: loaded.camera,
-      opts: rigOpts,
-      cloud: sample,
-      canvasAspect: box.height > 0 ? box.width / box.height : 4 / 3,
-    });
-    resolved.focusDefault = resolved.focus.slice();
-    resolved.focusDefaultSource = resolved.focusSource;
+    // What the waterfall was fed, kept with the asset: handle.setRig re-resolves from exactly this
+    // (never from a stale copy of the result), so setRig('camera') / ('auto') land where a load did.
+    const rigIn = { camera: loaded.camera, sample: loaded.pre?.rest || null, bounds };
+    // A setRig choice is STICKY across setSource: the new asset is resolved on the chosen rig.
+    const resolved = resolveFor(rigIn, rigOverride ? rigOverride.type : 'auto');
     perfSpan('applyLoaded:rig', tB);
     out.camera = loaded.camera;
     out.rig = resolved;
@@ -2811,8 +2977,66 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
           }),
         );
       }
-    } else if (resolved.type === 'camera') {
+    } else {
+      applyRig(resolved, bounds, false);
+    }
+    return { pickCentres, alpha8: cloud?.alpha8 || null, rigIn };
+  }
+
+  /** resolveRig on an asset's kept inputs: 'auto' = the load-time waterfall, else forced. */
+  function resolveFor(rigIn, type) {
+    const box = canvas.getBoundingClientRect();
+    const resolved = resolveRig({
+      camera: rigIn.camera,
+      opts: type === 'auto' ? rigOpts : { ...rigOpts, rig: type },
+      cloud: rigIn.sample,
+      canvasAspect: box.height > 0 ? box.width / box.height : 4 / 3,
+    });
+    if (type !== 'auto') resolved.typeSource = 'setRig';
+    resolved.focusDefault = resolved.focus.slice();
+    resolved.focusDefaultSource = resolved.focusSource;
+    return resolved;
+  }
+
+  /** The framing knobs the viewer's fit reads, as addSplat was booted with. */
+  const bootFraming = { vH: virtualDisplayHeight, fit, margin, depthLimit, fitSweep };
+  function setFraming(f) {
+    viewer.vH = f.vH;
+    viewer.fit = f.fit;
+    viewer.margin = f.margin;
+    viewer.depthLimit = f.depthLimit;
+    viewer.fitSweep = f.fitSweep;
+  }
+
+  /** Declare a DISPLAY rig to the runtime, unless that exact one is already declared. */
+  function declareDisplay(f) {
+    const key = `${f.vH}|${f.ipdFactor ?? 1}|${f.parallaxFactor ?? 1}|${f.perspectiveFactor ?? 1}`;
+    if (declaredDisplay === key) return;
+    // Back at the boot rig from the shorthand it was built with: nothing to say.
+    if (declaredDisplay === 'shorthand' && key === `${bootFraming.vH}|1|1|1`) return;
+    declaredDisplay = key;
+    lastConvergence = Number.NaN;
+    out.viewRig = displayRig({
+      virtualDisplayHeight: f.vH,
+      ipdFactor: f.ipdFactor ?? 1,
+      parallaxFactor: f.parallaxFactor ?? 1,
+      perspectiveFactor: f.perspectiveFactor ?? 1,
+    });
+    handle?.setViewRig?.(out.viewRig);
+  }
+
+  /**
+   * Put the viewer on a resolved rig: lens, framing, focus, and the rig declared to the runtime.
+   * Shared by every load / setSource (reset=false: the pose is kept) and handle.setRig
+   * (reset=true: the pose goes back to the rig's rest, yaw = pitch = 0, zoom 1, depth 0).
+   */
+  function applyRig(resolved, bounds, reset) {
+    const disp = rigOverride?.type === 'display' ? rigOverride.o : null;
+    if (reset) viewer.resetPose();
+    if (resolved.type === 'camera') {
+      setFraming(bootFraming);
       if (!('idleSpin' in opts)) viewer.idleSpin = 0;
+      else if (reset) viewer.idleSpin = idleSpin;
       // The camera rig never auto-fits (the capture IS the framing): a scale left by a previous
       // display-rig asset (setSource) must not shrink this one.
       viewer.resetFit();
@@ -2820,15 +3044,170 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       viewer.setFocus(modelToContent(resolved.focus), { snap: true, recentre: false });
       lastConvergence = Number.NaN;
       pushViewRig(true);
-    } else {
-      if (viewer.mono.capture) viewer.useDisplayCamera();
-      if (bounds) viewer.fitTo(bounds.center, bounds.extent);
-      else console.warn('[inline3d/splat] no usable bounds — subject is UNFRAMED (model scale)', src);
-      if (resolved.focusSource === 'caller' || resolved.focusSource === 'block') {
-        viewer.setFocus(modelToContent(resolved.focus), { snap: true, recentre: true });
+      return;
+    }
+    if (viewer.mono.capture) viewer.useDisplayCamera();
+    // The display rig orbits the frame centre (SceneViewer's recentre), whatever a camera rig
+    // before it left in the viewer.
+    viewer._focusRecentres = true;
+    const target = disp ? displayTarget(disp) : null;
+    if (target) {
+      // setRig('display') framing the page's content: addModel's fit, on addModel's defaults.
+      setFraming(disp);
+      viewer.idleSpin = disp.idleSpin;
+      viewer.fitTo(target.center, target.extent);
+      resolved.focus = contentToModel(target.center);
+      resolved.focusSource = 'frame';
+      resolved.focusDefault = resolved.focus.slice();
+      resolved.focusDefaultSource = 'frame';
+      resolved.frame = target;
+      declareDisplay(disp);
+      return;
+    }
+    // The splat itself, as a display-rig addSplat frames it (the load-time path).
+    setFraming(disp || bootFraming);
+    if (reset) viewer.idleSpin = disp ? disp.idleSpin : idleSpin;
+    if (bounds) viewer.fitTo(bounds.center, bounds.extent);
+    else console.warn('[inline3d/splat] no usable bounds — subject is UNFRAMED (model scale)', src);
+    if (resolved.focusSource === 'caller' || resolved.focusSource === 'block') {
+      viewer.setFocus(modelToContent(resolved.focus), { snap: true, recentre: true });
+    }
+    if (disp) resolved.frame = bounds ? { center: bounds.center.slice(), extent: bounds.extent.slice(), source: 'splat' } : null;
+    declareDisplay(disp || { vH: bootFraming.vH });
+  }
+
+  // ── handle.setRig: a live, reversible rig switch (docs/playcanvas-adapter.md §setRig) ──
+  /** null = 'auto' (the per-asset waterfall); else { type: 'camera' } | { type: 'display', o }. */
+  let rigOverride = null;
+  let rigSeq = 0;
+  /** The neutral-studio IBL setRig('display') installed, and what it replaced — or null. */
+  let rigEnv = null;
+  const baseToneMapping = viewer.toneMapping;
+
+  /** Is the splat on screen: its entity (and every ancestor) enabled. */
+  function splatShown() {
+    let e = current?.entity || null;
+    if (!e) return false;
+    for (; e; e = e.parent) if (e.enabled === false) return false;
+    return true;
+  }
+
+  /**
+   * World AABB of the page's meshes under handle.engine.root — enabled render components only,
+   * union of their mesh instances' `aabb` (the engine's world box, skinning included). Content
+   * space. The same measurement addModel's boundsOfEntity takes of its glTF.
+   */
+  function rootMeshBounds() {
+    const root = viewer.content;
+    const renders = root?.findComponents ? root.findComponents('render') : [];
+    let min = null;
+    let max = null;
+    for (const r of renders) {
+      if (r.enabled === false || r.entity?.enabled === false) continue;
+      for (const mi of r.meshInstances || []) {
+        const b = mi.aabb;
+        if (!b) continue;
+        const c = b.center;
+        const h = b.halfExtents;
+        const lo = [c.x - h.x, c.y - h.y, c.z - h.z];
+        const hi = [c.x + h.x, c.y + h.y, c.z + h.z];
+        if (!lo.every(Number.isFinite) || !hi.every(Number.isFinite)) continue;
+        if (!min) {
+          min = lo;
+          max = hi;
+        } else {
+          for (let i = 0; i < 3; i++) {
+            if (lo[i] < min[i]) min[i] = lo[i];
+            if (hi[i] > max[i]) max[i] = hi[i];
+          }
+        }
       }
     }
-    return { pickCentres, alpha8: cloud?.alpha8 || null };
+    return min ? { min, max } : null;
+  }
+
+  /**
+   * What setRig('display') frames: the caller's `frame`, else the meshes under root (plus the
+   * splat's measured box if it is shown), else null — the splat, as a display-rig addSplat would.
+   */
+  function displayTarget(disp) {
+    if (disp.frame) {
+      return { center: toArray3(disp.frame.center), extent: toArray3(disp.frame.extent).map((v) => Math.max(Math.abs(v), 1e-6)), source: 'caller' };
+    }
+    const m = rootMeshBounds();
+    if (!m) return null;
+    let { min, max } = m;
+    let source = 'root';
+    const sb = splatShown() ? out.frame : null;
+    if (sb) {
+      source = 'root+splat';
+      min = min.map((v, i) => Math.min(v, sb.center[i] - sb.extent[i] / 2));
+      max = max.map((v, i) => Math.max(v, sb.center[i] + sb.extent[i] / 2));
+    }
+    return {
+      center: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
+      extent: [Math.max(max[0] - min[0], 1e-6), Math.max(max[1] - min[1], 1e-6), Math.max(max[2] - min[2], 1e-6)],
+      source,
+    };
+  }
+
+  /** Per tick: addModel's tone mapping for the page's meshes while the splat is hidden. */
+  viewer.onTick = pageMode
+    ? viewer.onTick
+    : () => {
+        const want = rigOverride?.type === 'display' && !splatShown() ? rigOverride.o.toneMapping : baseToneMapping;
+        if (want !== viewer.toneMapping) viewer.setToneMapping(want);
+      };
+
+  /** Install addModel's default IBL for the display rig, if the page has none of its own. */
+  async function ensureRigEnvironment(disp, seq) {
+    if (disp.environment === 'none' || viewer.sky || rigEnv) return;
+    const app = viewer.app;
+    const scene = app?.scene;
+    if (!scene || scene.envAtlas) return; // the page lights its own meshes: leave it alone
+    const m = await import('./inline3d-model-playcanvas.js');
+    if (removed || seq !== rigSeq || rigOverride?.type !== 'display' || scene.envAtlas || rigEnv) return;
+    const prev = { skyboxIntensity: scene.skyboxIntensity, exposure: scene.exposure, skyboxRotation: scene.skyboxRotation };
+    const atlas = m.useNeutralStudio(pcModule, app, m.ENV_YAW_DEG);
+    rigEnv = { atlas, prev };
+  }
+
+  /** Undo ensureRigEnvironment (only what it installed, only if the page has not replaced it). */
+  function dropRigEnvironment() {
+    if (!rigEnv) return;
+    const scene = viewer.app?.scene;
+    const { atlas, prev } = rigEnv;
+    rigEnv = null;
+    if (!scene || scene.envAtlas !== atlas) return;
+    scene.envAtlas = null;
+    scene.skyboxIntensity = prev.skyboxIntensity;
+    scene.exposure = prev.exposure;
+    if (prev.skyboxRotation !== undefined) scene.skyboxRotation = prev.skyboxRotation;
+    atlas.destroy?.();
+  }
+
+  /**
+   * handle.setRig(type, options) — switch the rig the window is seen through, live: no remount,
+   * no reload, no new session. 'display' frames the page's meshes under handle.engine.root (plus
+   * the splat when shown) on addModel's defaults; 'camera' is the asset's capture rig re-resolved
+   * from the waterfall's own inputs; 'auto' is exactly what the load resolved. The pose resets to
+   * the new rig's rest. Sticky across setSource until setRig('auto'). Resolves to the handle once
+   * applied (the display rig's default environment included).
+   */
+  function setRig(type, o = {}) {
+    const req = validateSetRig(type, o, pageMode);
+    const seq = ++rigSeq;
+    return first.then(async () => {
+      if (removed || seq !== rigSeq || !current) return out;
+      rigOverride = req.type === 'auto' ? null : req;
+      if (req.type !== 'display') dropRigEnvironment();
+      const resolved = resolveFor(current.rigIn, req.type);
+      out.rig = resolved;
+      applyRig(resolved, current.rigIn.bounds, true);
+      viewer.onTick?.(); // tone mapping now, not a frame late
+      if (req.type === 'display') await ensureRigEnvironment(req.o, seq);
+      return out;
+    });
   }
 
   let pcModule = null;
@@ -2841,6 +3220,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       preserveDrawingBuffer,
       perf: perfResolved,
       viewPath: opts.playcanvasViewPath,
+      antialias: antialias === true,
     });
     if (!app || removed) return null;
     pcModule = pc;
@@ -2892,13 +3272,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 +3310,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 +3448,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 +3462,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 +3549,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 +3658,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