@displayxr/inline3d 1.19.2 → 1.19.3

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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

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-playcanvas.js

@@ -99,6 +99,7 @@ import {
   resolveControls,
   normalizeCameraPose,
   coverageExponent,
+  declareViewRig,
 } from './inline3d-splat-shared.js';
 
 /**
@@ -2348,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).';
@@ -2832,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) {
@@ -2905,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);
@@ -3195,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);
   }
 
   /**
@@ -3601,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;

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.2",
+  "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",