@displayxr/inline3d 1.19.1 → 1.19.3

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.3 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `./model`). No API change and no pixel change on a core that
+has view rigs.
+
+### Fixed
+
+- **A view rig the wall cannot take is no longer dropped silently** (#36).
+  - Every scene backend (`./splat` Spark and PlayCanvas, `./model` PlayCanvas) declared its rig
+    with `handle?.setViewRig?.(rig)`. On a handle from a core that predates view rigs, that call
+    does nothing.
+  - A page that vendors an older `inline3d.js` and hands that wall to `./splat` therefore had its
+    CAMERA rig thrown away. The wall wove the metric photo scene on the `addScene` display-rig
+    shorthand (`virtualDisplayHeight` 0.24): way off in convergence and scale in 3D, correct in 2D.
+    That is how the gallery's Spatial View wall regressed; the rig this SDK declared was the same
+    from 1.8.0 to 1.19.2.
+  - Now it logs one `console.warn` per page ("the view rig was dropped: your inline3d core
+    predates view rigs …") carrying the dropped rig.
+  - The Spark path used `handle?.setViewRig(…)` without the second `?.`, so it would have THROWN
+    there. It now takes the same warning path.
+  - Regression tests pin the declared rig for a camera-rig asset with `zoom {1, 2, relax}` and the
+    `assemble` reveal, at rest and after the reveal, on the fake engine.
+
+## 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/README.md

@@ -55,6 +55,8 @@ its own half, with no second canvas ([§setVideo](docs/playcanvas-adapter.md#set
 optional peer `playcanvas` (`>=2.22.3 <3`) and reads `.sog`, `.ply` and a Streamed-SOG
 `lod-meta.json`. **Spark stays the default**; a page that never passes `engine` never loads
 `playcanvas`. What differs, and why: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md).
+The repo's splat sample (`samples/splat/`) renders with PlayCanvas and keeps `?engine=spark` as
+its A/B switch.
 Bundlers: the engine is reached through a named-import module (`js/inline3d-playcanvas-engine.js`,
 so the unused ~40% of the engine tree-shakes away); its sort workers are Blob URLs (CSP
 `worker-src blob:`), and esbuild needs `node:worker_threads` marked external.
@@ -160,7 +162,7 @@ samples/
                       convergence + comfort, the attach pattern, C to A/B a display rig
   windows/            mixed 3D windows — still photos + a live video + a real-time three.js scene,
                       each woven with one SDK call, all on one session
-  splat/              a 3D Gaussian splat in a tile, auto-framed, with a 2D price plate over it
+  splat/              a 3D Gaussian splat in a tile (PlayCanvas; ?engine=spark), with a 2D plate over it
   model/              a glTF mesh, a mesh+splat scene, and a Draco-COMPRESSED glTF (PlayCanvas; ?engine=three)
   composition/        the 14-case 2D/3D overlap matrix — demo AND standing hardware regression
                       surface; red cases ship red (see samples/README.md)

package/THIRD_PARTY_NOTICES.md

@@ -74,3 +74,15 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+## Sample assets (repo samples only, not in the npm package)
+
+The pages under `samples/` show these assets. None is in the published `@displayxr/inline3d`
+package.
+
+| Asset | Used by | Source | Credit and licence |
+|---|---|---|---|
+| Damaged Helmet (`DamagedHelmet.glb`) | `samples/model/` (tiles A and B), loaded at run time, not vendored | [KhronosGroup/glTF-Sample-Assets](https://github.com/KhronosGroup/glTF-Sample-Assets/tree/c6a6bd13ab2b3c685c7903d03561b8a9392f38b8/Models/DamagedHelmet) at commit `c6a6bd13ab2b3c685c7903d03561b8a9392f38b8`, via jsDelivr, unmodified | © 2018 ctxwing (rebuild and conversion to glTF 2.0), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). Earlier version of the model ("Battle Damaged Sci-fi Helmet") © 2016 theblueturtle_, [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/legalcode). As stated in the asset's `README.md` and `LICENSE.md`. |
+| Duck, Draco variant (`samples/model/assets/glTF-Draco/`) | `samples/model/` (tile C) | Khronos glTF-Sample-Assets | © Sony, [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). |
+| Butterfly splat (`samples/splat/assets/butterfly.sog`) | `samples/splat/`, `samples/model/` (tile B) | [Spark](https://sparkjs.dev/) `assets/splats/butterfly.spz`, converted to SOG with PlayCanvas splat-transform (177,132 gaussians, 3 SH bands kept) | Butterfly splat © World Labs (from Spark, sparkjs.dev), used with permission; converted to SOG. |
+| Draco decoder (`vendor/draco/`) | `samples/model/` | three.js `examples/jsm/libs/draco/` | © The Draco Authors, Apache-2.0. |

package/js/inline3d-model-playcanvas.js

@@ -38,7 +38,7 @@
 //       └── eye camera, N RenderViews, TONEMAP_NEUTRAL, no sky layer
 
 import { PlayCanvasSplatViewer, pageRigTRS, pageViewAxis, pageViewRig } from './inline3d-splat-playcanvas.js';
-import { resolveControls, normalizeCameraPose, now, MAX_DT_S } from './inline3d-splat-shared.js';
+import { resolveControls, normalizeCameraPose, now, MAX_DT_S, declareViewRig } from './inline3d-splat-shared.js';
 import {
   NEUTRAL_STUDIO,
   neutralStudioRadiance,
@@ -551,7 +551,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
         if (dm > 0) d = dm / (ax.scale || 1);
       }
       out.viewRig = pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: d ?? 2, comfortDepth: ctl.comfortDepth }, out.viewRig || {});
-      handle?.setViewRig?.(out.viewRig);
+      declareViewRig(handle, out.viewRig);
     };
     if (typeof opts.onBeforeFrame === 'function') {
       const cb = opts.onBeforeFrame;

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

@@ -99,6 +99,7 @@ import {
   resolveControls,
   normalizeCameraPose,
   coverageExponent,
+  declareViewRig,
 } from './inline3d-splat-shared.js';
 
 /**
@@ -693,6 +694,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 +1450,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 +1674,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;
@@ -2316,7 +2349,6 @@ const SET_RIG_ENV_TONE_MAPPING = Object.freeze({ neutral: 'neutral', room: 'none
 export const SET_RIG_TYPES = Object.freeze(['display', 'camera', 'auto']);
 const SET_RIG_FITS = ['contain', 'cover', 'height', 'none'];
 let warnedSetRigKeys = false;
-
 const VIDEO_BUSY = (what) =>
   `@displayxr/inline3d/splat: ${what}() while a video is on — call handle.setVideo(null) first ` +
   '(the video holds the display rig and hides the splat until it exits).';
@@ -2800,7 +2832,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       },
       out.viewRig || {},
     );
-    handle?.setViewRig?.(out.viewRig);
+    declareViewRig(handle, out.viewRig);
     if (!out.rig) return;
     out.rig.convergence = d;
     if (Math.abs(d - pageFocus.fired) > 1e-3 || source !== pageFocus.source) {
@@ -2873,7 +2905,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         out: camRigObj,
       },
     );
-    handle?.setViewRig?.(out.viewRig);
+    declareViewRig(handle, out.viewRig);
   }
   viewer.onFocusChange = (f) => {
     pushViewRig(false);
@@ -3163,7 +3195,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       parallaxFactor: f.parallaxFactor ?? 1,
       perspectiveFactor: f.perspectiveFactor ?? 1,
     });
-    handle?.setViewRig?.(out.viewRig);
+    declareViewRig(handle, out.viewRig);
   }
 
   /**
@@ -3569,7 +3601,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       } else {
         declaredDisplay = s.declaredDisplay;
         out.viewRig = s.viewRig;
-        handle?.setViewRig?.(out.viewRig);
+        declareViewRig(handle, out.viewRig);
       }
     } else out.viewRig = s.viewRig;
     lastConvergence = s.lastConvergence;
@@ -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/js/inline3d-splat-shared.js

@@ -514,3 +514,35 @@ export function coverageExponent(c, L = FADE_OPTICAL_DEPTH) {
   if (c >= 1) return 1;
   return -Math.log(1 - c * (1 - Math.exp(-L))) / L;
 }
+
+// ── view-rig declaration (all three backends) ────────────────────────────────────────────────
+
+let warnedNoViewRig = false;
+
+/**
+ * Declare a view rig on the scene handle. A handle without `setViewRig` is a core that predates
+ * view rigs (inline3d.js before the view-rig commit — e.g. a page that vendors an older core and
+ * hands its wall to this adapter): the rig cannot reach the browser, and the wall weaves on the
+ * addScene display-rig shorthand instead. For a CAMERA rig that is a metric photo scene on a
+ * 0.24 m display rig — convergence and scale way off while 2D looks right — so it is said out
+ * loud, once per page, rather than dropped the way `handle?.setViewRig?.()` used to drop it.
+ * Returns whether the handle took the rig.
+ */
+export function declareViewRig(handle, rig) {
+  if (!handle) return false; // no wall (mono): nothing to declare to
+  if (typeof handle.setViewRig === 'function') {
+    handle.setViewRig(rig);
+    return true;
+  }
+  if (rig?.type === 'camera' && !warnedNoViewRig) {
+    warnedNoViewRig = true;
+    console.warn(
+      '[inline3d/splat] the view rig was dropped: your inline3d core predates view rigs (its ' +
+        'addScene handle has no setViewRig), so the wall will use the addScene display-rig ' +
+        'shorthand, not this camera rig — the scene will be mis-converged and mis-scaled in 3D. ' +
+        'Update the core (js/inline3d.js) that created the wall to the same SDK version as ./splat.',
+      rig,
+    );
+  }
+  return false;
+}

package/js/inline3d-splat.js

@@ -37,6 +37,7 @@ import {
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
   normalizeCameraPose,
+  declareViewRig,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -486,7 +487,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
       parallaxFactor: out.rig.parallaxFactor,
       out: out.viewRig || {},
     });
-    handle?.setViewRig(out.viewRig);
+    declareViewRig(handle, out.viewRig);
   }
   viewer.onFocusChange = () => {
     pushViewRig(false);

package/package.json

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