@displayxr/inline3d 1.19.1 → 1.19.2

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.19.2 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change and no pixel
+change: every frame of a `crossfade` or `wavefront` is the one 1.19.1 draws, and the end is still a
+plain `cut` (MAE 0.000).
+
+### Changed
+
+- **The live `wavefront` costs about one photo's draw, not two** (#36).
+  - Its depth ridge was an entity-scope work-buffer modifier: a full rewrite of the new photo's
+    1.18M-gaussian work buffer and a CPU re-sort, every frame (0.9–1.0 of each per frame, measured).
+    It now runs at render time on the eye camera's gsplat manager, as the particle transitions do:
+    0 rewrites and 0 sorts in the window.
+  - Each photo is drawn only on its side of the front: the new one left of where its commit
+    starts, the old one right of where it ends, so the two overlap only in the band. A gaussian
+    whose on-screen footprint (bounded the way the engine sizes its quad) lies wholly on the far
+    side in every eye gets alpha 0, which the engine culls in the vertex stage. Frames with the
+    cull on and off are bit-identical (both eyes, colour and alpha, 5 points of the window).
+  - An engine whose managers are not reachable keeps the entity-scope ridge (`_transitionPath`
+    says which ran).
+- **No shader links inside a `crossfade` or `wavefront` window.** The overlay's two quads compiled
+  on the window's first frames (30–180 ms on the M1). `prepareSource()` now warms them whatever
+  transition follows, `prepareSource(src, { transition: 'wavefront' })` also builds the render-time
+  ridge and cull, and an unprepared `setSource` warms them while its asset loads.
+
+Measured pacing and GPU cost: [`docs/splat-effects.md` § Wavefront: one draw's worth](docs/splat-effects.md#wavefront-one-draws-worth).
+The live `crossfade` still draws both photos in full: at mid-fade every pixel needs both images.
+
 ## 1.19.1 — 2026-09-24
 
 Touches packaging only (`./splat` and `./model`, `engine: 'playcanvas'`). No pixels move: the

package/js/inline3d-splat-effects.js

@@ -35,7 +35,8 @@
 // same splats; a decision keyed on a screen position would differ between the eyes and read as
 // rivalry. So no effect here reads gl_FragCoord or a view matrix, and the custom hook exposes no
 // screen-space input. (The one image-space piece, setSource's frame snapshot, lives in the
-// adapter and samples each eye's own half at the zero-disparity plane.)
+// adapter and samples each eye's own half at the zero-disparity plane.) The one exception,
+// `wipecull`, is not an effect: it only skips gaussians no shown pixel can receive.
 //
 // ── Sort caveat ───────────────────────────────────────────────────────────────────────────────
 //
@@ -46,7 +47,12 @@
 import { coverageExponent, FADE_TRANSMITTANCE_FLOOR } from './inline3d-splat-shared.js';
 
 /** The fixed composition order of a generated chunk. */
-export const STAGE_ORDER = Object.freeze(['grade', 'clip', 'reveal', 'pulse', 'custom']);
+export const STAGE_ORDER = Object.freeze(['grade', 'clip', 'reveal', 'pulse', 'custom', 'cull']);
+
+/** The most eye views setSource's wavefront culls for (more: every gaussian is drawn). */
+export const WIPE_CULL_MAX_VIEWS = 4;
+const IDENTITY16 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+const ZERO4 = new Float32Array(4);
 
 /** Named easings (a function `(x) => y` on [0, 1] is accepted too). */
 export const EASINGS = Object.freeze({
@@ -529,6 +535,74 @@ void ${P}color(vec3 c, inout vec4 col) {}
     }),
   },
 
+  // Internal: setSource's wavefront, both photos — draw each photo only on ITS side of the image
+  // front. NOT an effect: nothing it removes could have reached a pixel the overlay shows (the
+  // frame is bit-exact with it on or off), it only saves the fragments of the half nobody sees.
+  // Each gaussian whose on-screen footprint lies wholly on the far side of the front in EVERY eye
+  // gets alpha 0, which the engine's own alpha clip culls in the vertex stage. The footprint is
+  // bounded the way the engine sizes its quad (gsplatCorner): λ₁ ≤ ‖J‖²·s²·σ²max + 0.3 with
+  // ‖J‖² = (f/z)²·(1 + (x² + y²)/z²), l₁ = 2·√(2λ₁), and a corner offset ≤ l₁ + l₂ ≤ 2·l₁, plus
+  // 4 px. The front is the overlay's own (setSnapshotAlpha's wipe), in each eye's viewport-
+  // relative NDC. The eye views are the camera's (its parent's world transform · each view's
+  // pose), set by the adapter just before the engine renders — the live outgoing camera has its
+  // own. It is the LAST stage, so it sees the final centre and scale of every stage before it.
+  // Per mesh instance: `side` +1 keeps the right of `edge` (the outgoing photo), −1 the left
+  // (the incoming one); the material default is off.
+  wipecull: {
+    stage: 'cull',
+    kind: 'transition',
+    internal: true,
+    defaults: { durationMs: 0, easing: 'linear', holdMs: 0, direction: 'in' },
+    glsl: (P) => {
+      const views = [0, 1, 2, 3];
+      return `
+uniform float ${P}on;
+uniform float ${P}side;
+uniform float ${P}edge;
+uniform float ${P}n;
+${views.map((i) => `uniform mat4 ${P}V${i};\nuniform vec4 ${P}X${i};\nuniform vec4 ${P}W${i};\nuniform vec4 ${P}K${i};`).join('\n')}
+bool ${P}cut;
+// true when some of the footprint may reach the kept side of the front in this view
+bool ${P}reach(mat4 V, vec4 X, vec4 Wr, vec4 K, vec3 c, float s) {
+  vec4 p = vec4(c, 1.0);
+  vec4 v = V * p;
+  float z = -v.z;
+  float w = dot(Wr, p);
+  if (z <= 1e-6 || w <= 1e-6) return true; // at or behind the eye: the engine decides
+  float xn = dot(X, p) / w;
+  float jz = K.x / z;
+  float j2 = jz * jz * (1.0 + dot(v.xy, v.xy) / (z * z));
+  float l1 = 2.0 * sqrt(2.0 * (j2 * K.z * s * s + 0.3));
+  return ${P}side * (xn - ${P}edge) + (2.0 * l1 + 8.0) * K.y > 0.0;
+}
+void ${P}center(inout vec3 c) {}
+void ${P}rs(vec3 oc, vec3 mc, inout vec4 r, inout vec3 sc) {
+  ${P}cut = false;
+  if (${P}on < 0.5) return;
+  float s = max(sc.x, max(sc.y, sc.z));
+${views.map((i) => `  if (${i > 0 ? `${P}n > ${i}.5 && ` : ''}${P}reach(${P}V${i}, ${P}X${i}, ${P}W${i}, ${P}K${i}, mc, s)) return;`).join('\n')}
+  ${P}cut = true;
+}
+void ${P}color(vec3 c, inout vec4 col) { if (${P}cut) col.a = 0.0; }
+`;
+    },
+    // opts.cull() → { side, edge, views: [{ V, X, W, K }] } (at most WIPE_CULL_MAX_VIEWS), or null
+    // (off: every gaussian drawn). No `cull` (the material default): off.
+    uniforms: (ctx, inst) => {
+      const c = typeof inst.opts.cull === 'function' ? inst.opts.cull() : null;
+      const on = !!(c && c.views.length && c.views.length <= WIPE_CULL_MAX_VIEWS);
+      const out = { on: on ? 1 : 0, side: on ? c.side : 1, edge: on ? c.edge : 0, n: on ? c.views.length : 0 };
+      for (let i = 0; i < WIPE_CULL_MAX_VIEWS; i++) {
+        const v = on ? c.views[i] : null;
+        out['V' + i] = v ? v.V : IDENTITY16;
+        out['X' + i] = v ? v.X : ZERO4;
+        out['W' + i] = v ? v.W : ZERO4;
+        out['K' + i] = v ? v.K : ZERO4;
+      }
+      return out;
+    },
+  },
+
   // Internal: setSource's crossfade FALLBACK (no frame snapshot) — the coverage remap on one
   // entity, driven by the adapter.
   xfade: {
@@ -1528,9 +1602,18 @@ export class SplatEffects {
    * 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;
+    return this.sharedChunkCodeFor([[name, effect, opts]]);
+  }
+
+  /** sharedChunkCode for several driveShared bodies at once: [[name, effect, opts], …]. */
+  sharedChunkCodeFor(list) {
+    const names = new Set(list.map((x) => x[0]));
+    const insts = [...(this.scopes.get('tile')?.values() ?? [])].filter((i) => !names.has(i.name));
+    for (const [name, effect, opts] of list) {
+      const o = resolveEffectOptions(effect, { ...opts, scope: 'tile', direction: 'in', progress: 1 }, 'set', { internal: true });
+      insts.push({ name, def: EFFECTS[effect], opts: o });
+    }
+    return composeModifier(insts).code;
   }
 
   _setupInstance(inst) {

package/js/inline3d-splat-playcanvas.js

@@ -693,6 +693,8 @@ export class PlayCanvasSplatViewer {
     this._snap = null;
     /** setSource's live outgoing asset (./inline3d-splat-live.js), made on first use. */
     this._live = null;
+    /** (entries, rect) => void: once per drawn frame, after the views are set, before the engine renders. */
+    this.onBeforeRender = null;
     this.vH = virtualDisplayHeight;
     this.fit = fit;
     this.margin = margin;
@@ -1447,6 +1449,34 @@ export class PlayCanvasSplatViewer {
     return { rig: this.rigMatrix(), pose, c, t: Math.tan((this.mono.fov * DEG) / 2) };
   }
 
+  /**
+   * One camera's eye views as the engine composes them this frame (RenderView.updateTransforms:
+   * the camera node's PARENT world transform · each view's pose), packed for the wavefront's cull
+   * (EFFECTS.wipecull): V = the view matrix, X / W = rows 0 and 3 of proj · V, K = (the engine's
+   * focal f = viewport width · proj[0], 1 / viewport width, the view's squared scale). `into` is
+   * reused frame to frame. Null when a matrix is singular.
+   */
+  cullViews(cam, entries, rect, into = []) {
+    const parent = cam?.parent?.getWorldTransform?.()?.data ?? null;
+    into.length = entries.length;
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      const V = mat4Invert(parent ? mat4Mul(parent, e.pose) : e.pose);
+      if (!V) return null;
+      const C = mat4Mul(e.proj, V);
+      const w = Math.max(1, rect(e)[2]);
+      const o = (into[i] ||= { V: new Float32Array(16), X: new Float32Array(4), W: new Float32Array(4), K: new Float32Array(4) });
+      o.V.set(V);
+      o.X[0] = C[0]; o.X[1] = C[4]; o.X[2] = C[8]; o.X[3] = C[12];
+      o.W[0] = C[3]; o.W[1] = C[7]; o.W[2] = C[11]; o.W[3] = C[15];
+      o.K[0] = w * e.proj[0];
+      o.K[1] = 1 / w;
+      o.K[2] = V[0] * V[0] + V[1] * V[1] + V[2] * V[2];
+      o.K[3] = 0;
+    }
+    return into;
+  }
+
   /** Can this tile render a live outgoing asset (the single-camera RenderView path)? */
   get canLiveOutgoing() {
     return LiveOutgoing.supported(this);
@@ -1643,6 +1673,8 @@ export class PlayCanvasSplatViewer {
       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);
+      // setSource's wavefront: this frame's eye views, as the engine is about to compose them.
+      this.onBeforeRender?.(entries, rect);
     } else {
       // Fallback: one camera per view, `rect` + `calculateProjection`.
       const cams = this._views;
@@ -3680,7 +3712,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     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);
+    await prewarmTransition(warm); // null (no transition declared): the overlay only
     const entry = { loaded, state: 'ready', dispose: null };
     const prepared = {
       [PREPARED_TAG]: true,
@@ -3721,46 +3753,61 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * 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;
+    // The chunk variant the transition installs (particles, wavefront), and the overlay's two quads
+    // (crossfade, wavefront and the particles all composite through them; created on the first
+    // capture otherwise, and compiled on its draw: 30–180 ms on the first frames of the window).
+    const chunkKey = plan?.particles
+      ? `${plan.particles.in.effect}|${plan.particles.in.opts.order ?? ''}`
+      : plan?.transition === 'wavefront'
+        ? 'wavefront'
+        : null;
+    const wantChunk = !!(fx && chunkKey && !prewarmed.has(chunkKey));
+    const wantOverlay = !prewarmed.has('overlay');
+    if (!wantChunk && !wantOverlay) return;
     await yieldIdle();
-    if (removed || !fx) return;
+    if (removed) 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++;
+      if (wantChunk && fx) {
+        const cams = [viewer.eye, viewer._live?.cam].filter(Boolean);
+        const code = plan.particles
+          ? fx.sharedChunkCode('transition', plan.particles.in.effect, { order: plan.particles.in.opts.order })
+          : fx.sharedChunkCodeFor([
+              ['transition', 'wavefront', {}],
+              ['transition-cull', 'wipecull', {}],
+            ]);
+        let issued = 0;
+        for (const cam of cams) {
+          const mi = managerMi(cam, 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++;
+        }
+        if (issued) prewarmed.add(chunkKey);
       }
-      // 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) {
+      if (wantOverlay && cam?.shaderParams) {
         viewer._ensureSnapshotOverlay();
+        let issued = 0;
         for (const p of viewer._snap?.parts || []) {
-          made.push(p.mat.getShaderVariant?.({
+          const v = p.mat.getShaderVariant?.({
             device: viewer.app.graphicsDevice,
             scene: viewer.app.scene,
             objDefs: p.mi._shaderDefs,
@@ -3769,16 +3816,18 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
             sortedLights: [],
             viewUniformFormat: viewer.app.renderer?.viewUniformFormat ?? null,
             vertexFormat: p.mi.mesh?.vertexBuffer?.format,
-          }));
+          });
+          if (v) (made.push(v), issued++);
         }
+        if (issued) prewarmed.add('overlay');
       }
-      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
@@ -3845,6 +3894,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     await first.catch(() => null); // a failed first asset may be replaced
     if (!app || removed) return out;
     const pc = pcModule;
+    // Not prepared: compile what the transition draws with (its chunk, the overlay) while the asset
+    // loads, rather than on the window's first frames. Best effort, not awaited.
+    if (!prep && current && plan.transition !== 'cut') prewarmTransition(plan);
     const loaded = prep ? prep.loaded : await loadOne(pc, app, next);
     if (removed || gen !== sourceGen) {
       app.assets.remove(loaded.asset);
@@ -3977,15 +4029,24 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         });
       } else release(prev); // the snapshot shows it from here on
       const band = plan.band;
+      finishers.push(() => {
+        viewer._transitionState = null;
+        viewer.setSnapshotAlpha(0);
+        viewer.releaseSnapshot();
+      });
+      if (fx && managerMi(viewer.eye, null)) {
+        playWavefrontRender({ plan, entity, live, finishers, finish, isFinished: () => finished, pumpLive });
+        await done;
+        return out;
+      }
+      // FALLBACK (an engine whose managers are not reachable): the ridge as an entity-scope
+      // modifier — correct, but it rewrites the new photo's work buffer and re-sorts it every frame.
+      viewer._transitionPath = 'entity';
       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);
-        viewer.releaseSnapshot();
-      });
       viewer._hooks.push(() => {
         if (finished || removed) return false;
         if (live && !live.fits) {
@@ -4064,6 +4125,94 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return out;
   }
 
+  /** The mesh instance of the gsplat manager that `cam` draws `layer` with (any layer: null). */
+  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;
+  };
+
+  /**
+   * setSource's wavefront, RENDER-TIME (the default): the ridge is a tile-scope body whose values
+   * sit on the eye camera's manager (the incoming photo), as the particle transitions do — no
+   * work-buffer rewrite and no re-sort per frame. Each photo is drawn only on its side of the
+   * front (EFFECTS.wipecull, the last stage): the incoming one left of where its commit starts,
+   * the outgoing one (on the live camera) right of where it ends, so the two share only the
+   * `band`. The overlay still wipes the same two live images on the same lt; the frame is the
+   * one the full draws give, bit for bit. The clock starts on the second tick (the incoming
+   * asset's first frame builds its work buffer), as the crossfade's does.
+   */
+  function playWavefrontRender({ plan, entity, live, finishers, finish, isFinished, pumpLive }) {
+    const band = plan.band;
+    const ease = typeof plan.easing === 'function' ? plan.easing : EASINGS[plan.easing] || EASINGS.linear;
+    const eyeMi = () => managerMi(viewer.eye, null);
+    const liveMi = () => (live?.active ? managerMi(live.cam, live.layer) : null);
+    const ridgeFx = fx.driveShared('transition', 'wavefront', {});
+    const cullFx = fx.driveShared('transition-cull', 'wipecull', {});
+    const ridgeIn = ridgeFx.side(eyeMi, { band, ridge: plan.ridge, ridgeMaxDisparity: plan.ridgeMaxDisparity });
+    const cull = { in: null, out: null };
+    const cullIn = cullFx.side(eyeMi, { cull: () => cull.in });
+    const cullOut = live ? cullFx.side(liveMi, { cull: () => cull.out }) : null;
+    const views = { in: [], out: [] };
+    let amount = 0;
+    ridgeIn.set(0);
+    viewer._transitionPath = 'render';
+    // Where each photo still shows, in each eye's viewport-relative NDC (setSnapshotAlpha's wipe:
+    // column u has committed lt = clamp((t − u·(1 − band)) / band, 0, 1) to the new photo).
+    const clampEdge = (x) => Math.min(3, Math.max(-3, x));
+    viewer.onBeforeRender = (entries, rect) => {
+      if (isFinished()) return;
+      const span = 1 - band;
+      // band 1: the whole picture is the band — draw both in full. `_wipeCull = false`: the
+      // diagnostics switch the exactness gate compares against (docs §Gates).
+      if (!(span > 1e-6) || viewer._wipeCull === false) {
+        cull.in = cull.out = null;
+        cullIn.set(amount);
+        cullOut?.set(amount);
+        return;
+      }
+      const vin = viewer.cullViews(viewer.eye, entries, rect, views.in);
+      cull.in = vin ? { side: -1, edge: clampEdge((2 * amount) / span - 1), views: vin } : null;
+      cullIn.set(amount);
+      if (cullOut) {
+        const vout = viewer.cullViews(live.cam, entries, rect, views.out);
+        cull.out = vout ? { side: 1, edge: clampEdge((2 * (amount - band)) / span - 1), views: vout } : null;
+        cullOut.set(amount);
+      }
+    };
+    finishers.push(() => {
+      if (viewer.onBeforeRender) viewer.onBeforeRender = null;
+      ridgeFx.remove();
+      cullFx.remove();
+    });
+    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();
+      if (++ticks >= 2 && t0 === null) {
+        t0 = t;
+        ridgeIn.restart(); // the eyes' frame, now the new rig and first frames are in
+      }
+      const raw = t0 === null ? 0 : plan.durationMs > 0 ? Math.min(1, Math.max(0, (t - t0) / plan.durationMs)) : 1;
+      amount = ease(raw);
+      viewer._transitionState = { raw, live: !!live }; // diagnostics
+      ridgeIn.set(amount);
+      if (!viewer.setSnapshotAlpha(1, { t: amount, band, views: viewer.viewsAcross }) || raw >= 1) {
+        finish();
+        return false;
+      }
+      return true;
+    });
+  }
+
   /**
    * 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
@@ -4083,13 +4232,6 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // (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;

package/package.json

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