@displayxr/inline3d 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,111 @@ 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.8.0 — 2026-09-22
+
+Touches the **preview tier** (`./splat`, plus one additive `./three` export). **Existing callers get
+the same engine and the same code path**: with no `engine` option, or `engine: 'spark'`, `addSplat`
+renders with three.js + Spark as in 1.7.1. The PlayCanvas engine is **opt-in** with
+`engine: 'playcanvas'`.
+
+**One behaviour change, for one class of file.** The camera-rig focus waterfall gains a rung (see
+*Changed*). A `.sog` whose `camera` block has **no `focus`**, or a `focus` its converter computed
+as the whole-cloud median (`focus.source: "cloud-median"`), now converges on the **nearest
+substantial clump** in the middle of the frame instead of the whole-scene median. On an open
+landscape that is 2.4 m (the tree trunk), not 46.9 m, so that file's 3D will look different, as
+intended. Blocks with a considered focus (`convergence`, `manual`, …, or no `source`), assets with
+no block, and a caller's `focus` / `convergence` are unaffected. Both engines.
+
+### Added
+
+- **`addSplat(…, { engine: 'playcanvas' })`: the PlayCanvas engine as a second splat backend**
+  (epic #36).
+  - Same handle and the same rig/lens/focus waterfall as Spark. One camera renders every view
+    through the engine's `RenderView` list, so one sort serves all eyes.
+  - A shader-chunk fix for the engine's square-pixel footprint assumption, which a side-by-side
+    buffer breaks.
+  - `perf` presets map onto engine knobs, and `perf: false` leaves the engine alone.
+  - A **URL** `.sog` yields its `camera` block too.
+  - Needs the new **optional** peer `playcanvas >=2.22.3 <3`, loaded by a dynamic `import()` only
+    when asked for.
+  - Reads `.sog`, `.ply` and a Streamed-SOG `lod-meta.json`. With `engine: 'playcanvas'`, a
+    `.spz` / `.splat` / `.ksplat` source (or a Spark-only `fileType`) **throws at call time**.
+    Those stay Spark formats.
+  - Differences from the Spark path: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md).
+- On the PlayCanvas backend:
+  - **`handle.setSource(src, { fadeMs, resetPose })`**: a crossfading in-place asset swap that
+    re-runs the rig waterfall for the new file. The pose is kept unless `resetPose`. It throws on
+    Spark.
+  - **`feather`**: the per-eye edge fade, matching `EdgeFeather`.
+  - **Tilt-and-relax `orbit`**: the drag is a fraction of the tile, capped at `orbitMaxDeg` (15°),
+    and relaxes back on release (`orbitEase` `{ drag: 0.2, rest: 0.6 }` s). Spark keeps its
+    turntable drag.
+  - **Exact `pick`**: the nearest gaussian centre over the full centre set, with haze skipped.
+- **`captureFit: 'height' | 'cover'`** on the camera rig, both backends. `'height'` (default) is
+  the 1.7 window. `'cover'` fills the tile with photograph (a 4:3 capture in a 16:9 tile crops
+  top/bottom).
+- **`handle.engine`** (advanced, not semver-covered): `{ app, root, camera }` on PlayCanvas, and
+  `{ renderer, scene, camera }` on Spark. **`handle.backend`**: `'playcanvas'` or `'spark'`.
+- **`handle.getFocus()`** and **`handle.onFocusChange(point, { focusSource })`**, in the splat's
+  own space, on both backends. `handle.rig` gains `blockFocusSource` and `clumpMassFrac`.
+- **`cameraRigFromPose(pose, opts)`** in `./three`. It builds the camera-rig descriptor from a
+  plain `{position, orientation, fov}`, bit-identical to `cameraRigFromCamera`, which is unchanged.
+
+### Changed
+
+- **Focus waterfall: `nearest-clump`** (the behaviour change above). The order is now: caller ›
+  caller convergence › block focus (any source except `cloud-median` / `median-disparity`) ›
+  **nearest-clump** (needs the block's or caller's lens) › `block-cloud-median` ›
+  `median-disparity` › 2 m.
+- **Viewer tuning constants are shared** (`inline3d-splat-shared.js`). SceneViewer reads the same
+  damping, idle, focus-ease, wheel and zoom numbers as before, now from one module the PlayCanvas
+  viewer also reads. The values are unchanged, and a side-by-side trace test pins the two viewers
+  bit-identical.
+
+## 1.7.1 — 2026-09-20
+
+Touches the **preview tier** (`./model`) only, and fixes exactly one thing: under a bundler, a
+compressed glTF never loaded at all. Uncompressed assets are unaffected, and so is every page that
+loads compressed ones through a bare importmap — same pixels, same timing. If your page builds with
+webpack / Turbopack / Vite / rollup and loads a Draco-, KTX2- or meshopt-compressed model, the tile
+that used to stay empty with a rejected `handle.ready` now renders the product.
+
+### Fixed
+
+- **`addModel` could not load ANY compressed asset under a bundler — all three decoders**
+  (preview tier). The decoders were resolved with `await import(spec.module)`, the specifier read
+  out of the `DECODERS` table — an *expression*, which no bundler can follow. The build printed
+
+  ```
+  Critical dependency: the request of a dependency is an expression
+  ```
+
+  and shipped a stub that throws `Cannot find module 'three/addons/…'` at runtime, which `addModel`
+  then reported honestly as a module-resolution failure in its own decoder error. Draco, KTX2/Basis
+  **and** meshopt all went through that one call, so the blast radius was the whole compressed path
+  — and a catalogue GLB out of a real pipeline is nearly always compressed, which is precisely the
+  case `/model` exists for. Each decoder now has a literal `import()` of its own
+  (`load: () => import('three/addons/loaders/DRACOLoader.js')`, and so on): that is what a build
+  tool can analyse, and it resolves unchanged under the `"three/addons/"` importmap prefix the
+  samples use.
+
+  It survived four releases because neither path that was exercised has the fault — `samples/` runs
+  on a bare importmap, which resolves specifiers at runtime and does not care, and the test suite is
+  deliberately dependency-free, so it never imported a decoder at all. The guard added with this fix
+  is therefore a source-level one: it reads `js/` the way a bundler does and fails if any `import()`
+  is handed a computed specifier again.
+
+  Nothing else moved. Injection (`{ DRACOLoader }`, `{ KTX2Loader }`, `{ meshoptDecoder }`, a class
+  or a ready instance you configured yourself), the shared ref-counted decoder cache, `decoderPath`
+  and the serve-the-decoder-files-yourself requirement are all as they were, and a decoder is still
+  imported only for an asset that declares its extension — bundlers now code-split each one into its
+  own chunk, so an uncompressed GLB downloads none of them.
+
+  Verified in Chrome against a Next.js 15 / webpack app loading an `EXT_meshopt_compression` GLB:
+  before, the build warning above plus `Cannot find module
+  'three/addons/libs/meshopt_decoder.module.js'` and an empty stage; after, no warning, the meshopt
+  decoder arriving as its own chunk, and the model on screen.
+
 ## 1.7.0 — 2026-09-19
 
 Touches the **preview tier** (`./splat`) only, and additively: `addSplat` with no new options

package/README.md

@@ -40,6 +40,17 @@ and only the `/three`, `/viewer` and `/splat` subpaths need them. The two viewer
 call (auto-framing on the zero-disparity plane, orbit, idle turntable, mono fallback), but their
 API is not yet covered by the semver promise below.
 
+**A second splat engine (preview).** `addSplat(wall, canvas, src, { engine: 'playcanvas' })`
+renders the same splat window with the [PlayCanvas](https://playcanvas.com/) engine instead of
+Spark — same handle, same rig/focus/camera-block behaviour, same `perf` presets (mapped onto the
+engine's knobs) — and adds `setSource(src, { fadeMs })` (crossfading asset swaps), `feather`, a
+tilt-and-relax orbit and `handle.engine` (the engine objects, for advanced pages). It needs the
+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).
+Bundlers: the engine is a literal `import('playcanvas')`; its sort workers are Blob URLs (CSP
+`worker-src blob:`), and esbuild needs `node:worker_threads` marked external.
+
 Stability & what's covered by semver (and the deferred N-view / web-components / CSS-native roadmap
 that is intentionally **not** in 1.0): [`docs/sdk-stability.md`](docs/sdk-stability.md).
 
@@ -114,6 +125,8 @@ js/
                       and the placement readback (getSubjectBounds / getPose / depthOffset)
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
                       (`perf` cuts overdraw; a `.sog`'s `camera` block picks the view rig)
+  inline3d-splat-playcanvas.js
+                      preview: the `engine: 'playcanvas'` backend of addSplat(), loaded on demand
   inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/

package/js/inline3d-model.js

@@ -63,12 +63,23 @@ async function resolveLoader(injected) {
  * One entry per decoder: the glTF extension that demands it, where its class lives, where its
  * runtime files live, and which option overrides each. The error messages are generated from
  * this table, so a message can never name an option that does not exist.
+ *
+ * `load` is a thunk around a **literal** `import()` and `module` is the same specifier as a
+ * string, and the duplication is deliberate. A bundler can only follow an import whose specifier
+ * is written out at the call site: `import(spec.module)` — reading the string out of this table —
+ * is an *expression*, which webpack/Turbopack/rollup cannot resolve, so they emit
+ * "Critical dependency: the request of a dependency is an expression" at build time and a stub
+ * that throws `Cannot find module …` at runtime. That made EVERY compressed asset unloadable for
+ * every bundler consumer, while the bare-importmap path (which resolves at runtime and does not
+ * care) kept working — so it survived the samples. The string stays because the error messages
+ * quote it; the thunk is what actually loads.
  */
 const DECODERS = {
   draco: {
     ext: 'KHR_draco_mesh_compression',
     label: 'Draco mesh compression',
     module: 'three/addons/loaders/DRACOLoader.js',
+    load: () => import('three/addons/loaders/DRACOLoader.js'),
     exportName: 'DRACOLoader',
     option: 'DRACOLoader',
     pathKey: 'draco',
@@ -79,6 +90,7 @@ const DECODERS = {
     ext: 'KHR_texture_basisu',
     label: 'KTX2 / Basis Universal textures',
     module: 'three/addons/loaders/KTX2Loader.js',
+    load: () => import('three/addons/loaders/KTX2Loader.js'),
     exportName: 'KTX2Loader',
     option: 'KTX2Loader',
     pathKey: 'basis',
@@ -89,6 +101,7 @@ const DECODERS = {
     ext: 'EXT_meshopt_compression',
     label: 'meshopt compression',
     module: 'three/addons/libs/meshopt_decoder.module.js',
+    load: () => import('three/addons/libs/meshopt_decoder.module.js'),
     exportName: 'MeshoptDecoder',
     option: 'meshoptDecoder',
     pathKey: null, // pure JS + inlined wasm; nothing for the page to serve
@@ -159,7 +172,10 @@ async function buildDecoder(kind, paths, injected) {
   const spec = DECODERS[kind];
   let thing = injected;
   if (!thing) {
-    const mod = await import(spec.module);
+    // spec.load(), never `import(spec.module)` — see the note on DECODERS. One literal specifier
+    // per kind is what makes this analysable, and a bundler then code-splits each decoder into
+    // its own chunk, still fetched only for an asset that declares the extension.
+    const mod = await spec.load();
     thing = mod[spec.exportName];
     if (!thing) throw new Error(`${spec.module} has no export "${spec.exportName}"`);
   }

package/js/inline3d-splat-perf.js

@@ -253,3 +253,129 @@ export function splatPerfMeshOptions(perf) {
   if (!profile || !profile.lod) return {};
   return { lod: profile.lod === 'quality' ? 'quality' : true };
 }
+
+// ── the same presets on the PlayCanvas engine (`addSplat(…, { engine: 'playcanvas' })`) ──────
+//
+// Same contract as the Spark half above: nothing moves unless asked, and every knob can be
+// switched off. The presets are Spark-shaped (they were measured on Spark), so this maps each
+// knob onto the engine's nearest equivalent rather than inventing engine presets:
+//
+// | Spark knob | engine (2.22.3) | note |
+// |---|---|---|
+// | `alphaRadius` | always on | the engine ALREADY shrinks every quad to its own alpha radius (`clipCorner` in `gsplatCommonVS`: `min(1, sqrt(ln(a / alphaClip)) / 2)` of the √8σ quad — the same cut `patchAlphaRadius` puts into Spark). It cannot be turned off, so `alphaRadius: false` is reported as `'native'`. |
+// | `minAlpha` | `scene.gsplat.alphaClipForward` | engine default is already 1/255 |
+// | `maxStdDev` | chunk override of `gsplatCommonVS` | the engine's quad is a fixed √8σ; the override caps `clipCorner`'s scale at `maxStdDev/√8`, which truncates both the quad AND the gaussian's uv, i.e. Spark's semantics. Only ever SHRINKS (≤ √8σ). |
+// | `minPixelRadius` | `scene.gsplat.minPixelSize` = 2 × radius | the engine compares a quad DIAMETER in px (`max(l1,l2)`) |
+// | `lod`, `lodSplat*`, `maxPixelRadius`, `falloff`, `alphaFloor` | none | Spark-only; ignored with one warning. The engine's splat-count lever is `splatBudget` (below) |
+//
+// Engine-native keys may be passed in an options object as well and win over the mapping:
+// `alphaClipForward`, `minPixelSize`, `splatBudget` (a global splat count, per app = per tile),
+// `antiAlias` (only for AA-trained assets).
+//
+// `minPixelSize` IS THE ONE DEFAULT CHANGED. The engine drops every splat whose quad is under
+// 2 px by default; Spark keeps them (its `minPixelRadius` default is 0). On a lifted photograph
+// the sub-2px grain is real texture, so every `perf` value except `false` starts from 0 — the
+// Spark-parity baseline — and only a preset or option that states a size moves it. `perf: false`
+// is the kill switch: the engine's own defaults, untouched, 2 px included.
+
+/** The engine's quad half-extent, in σ: `l = 2·sqrt(2λ)` over cornerUV ∈ [-1,1] (gsplatCorner). */
+export const PLAYCANVAS_QUAD_SIGMA = Math.sqrt(8);
+
+/** Knobs that are engine-native and pass straight through to `app.scene.gsplat`. */
+const PC_NATIVE = ['alphaClipForward', 'minPixelSize', 'splatBudget'];
+
+/** Spark knobs with no engine equivalent — named once in a warning, then ignored. */
+const PC_UNMAPPED = ['lod', 'lodSplatCount', 'lodSplatScale', 'lodRenderScale', 'maxPixelRadius', 'falloff', 'alphaFloor'];
+
+/**
+ * Resolve `perf` into engine settings. Pure: no engine, no GPU — the adapter applies the result.
+ *
+ * @param {undefined|null|false|true|string|object} perf  the `addSplat` option, as given.
+ * @returns {{settings:object, quadExtent:number|null, applied:object|null, ignored:string[]}}
+ *          `settings` go onto `app.scene.gsplat`; `quadExtent` (a fraction of the √8σ quad, or
+ *          null for untouched) goes into the `gsplatCommonVS` override; `applied` is what the
+ *          handle reports (null for `perf: false`).
+ */
+export function playcanvasPerfSettings(perf) {
+  const out = { settings: {}, quadExtent: null, applied: null, ignored: [] };
+  if (perf === false) return out; // kill switch: engine defaults, untouched
+
+  let profile = null;
+  let name = null;
+  if (perf === undefined || perf === null) name = 'default';
+  else if (perf === true) {
+    profile = SPLAT_PERF_PRESETS.balanced;
+    name = 'balanced';
+  } else if (typeof perf === 'string') {
+    profile = SPLAT_PERF_PRESETS[perf] || null;
+    name = profile ? perf : 'default';
+    if (!profile) {
+      console.warn(
+        `[inline3d/splat] unknown perf preset "${perf}" — ignored. ` +
+          `Known: ${Object.keys(SPLAT_PERF_PRESETS).join(', ')}, or an options object.`,
+      );
+    }
+  } else if (typeof perf === 'object') {
+    profile = perf;
+    name = 'custom';
+  }
+
+  const s = out.settings;
+  const applied = { preset: name };
+  // The Spark-parity baseline. See the block comment above.
+  s.minPixelSize = 0;
+  if (profile) {
+    if (isNum(profile.minAlpha)) s.alphaClipForward = profile.minAlpha;
+    if (isNum(profile.minPixelRadius)) s.minPixelSize = 2 * Math.max(0, profile.minPixelRadius);
+    if (isNum(profile.maxStdDev) && profile.maxStdDev > 0) {
+      const k = Math.min(1, profile.maxStdDev / PLAYCANVAS_QUAD_SIGMA);
+      if (k < 1) out.quadExtent = k;
+    }
+    if (profile.alphaRadius !== undefined) applied.alphaRadius = 'native';
+    for (const key of PC_NATIVE) if (isNum(profile[key])) s[key] = profile[key];
+    if (typeof profile.antiAlias === 'boolean') s.antiAlias = profile.antiAlias;
+    for (const key of PC_UNMAPPED) if (profile[key] !== undefined) out.ignored.push(key);
+    if (out.ignored.length) {
+      console.warn(
+        `[inline3d/splat] perf: ${out.ignored.join(', ')} ${out.ignored.length > 1 ? 'have' : 'has'} ` +
+          'no PlayCanvas equivalent and ' +
+          `${out.ignored.length > 1 ? 'are' : 'is'} ignored on engine:'playcanvas' — the engine's ` +
+          'splat-count lever is `splatBudget` (see js/inline3d-splat-perf.js).',
+      );
+    }
+  }
+  Object.assign(applied, s);
+  if (out.quadExtent !== null) applied.maxStdDev = out.quadExtent * PLAYCANVAS_QUAD_SIGMA;
+  out.applied = applied;
+  return out;
+}
+
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+// The anchor the quad-extent override rewrites, from the engine's `gsplatCommonVS` (2.22.3). The
+// npm build re-indents chunks with tabs and a later release may re-space them, so it is a
+// whitespace-agnostic regex, not a string.
+const PC_CLIP_ANCHOR = /float\s+clip\s*=\s*min\(\s*1\.0\s*,/;
+
+/**
+ * Cap the engine's per-splat quad at `k` of its √8σ extent — Spark's `maxStdDev`, on PlayCanvas.
+ *
+ * Rewrites `clipCorner`'s `min(1.0, …)` to `min(k, …)`, which scales the corner offset AND the uv
+ * the fragment shader evaluates the gaussian at, so the tail is truncated rather than the
+ * profile squashed. Returns the source unchanged (and `ok:false`) when the anchor is missing;
+ * the caller warns once and renders at the engine's own extent.
+ *
+ * @param {string} src  the current `gsplatCommonVS` chunk.
+ * @param {number} k  in (0, 1).
+ * @returns {{src:string, ok:boolean}}
+ */
+export function patchPlayCanvasQuadExtent(src, k) {
+  if (typeof src !== 'string' || !(k > 0 && k < 1)) return { src, ok: false };
+  if (src.includes('dxrQuadExtent')) return { src, ok: true }; // idempotent
+  if (!PC_CLIP_ANCHOR.test(src)) return { src, ok: false };
+  const lit = k.toFixed(7);
+  return {
+    src: src.replace(PC_CLIP_ANCHOR, `float clip = min(${lit} /* dxrQuadExtent */,`),
+    ok: true,
+  };
+}