@displayxr/inline3d 1.29.0 → 1.30.0

package/js/inline3d-splat-deferred.js

@@ -0,0 +1,153 @@
+// inline3d-splat-deferred.js — the engine:'playcanvas' handle, shared by both splat entries.
+//
+// Internal. ./splat (Spark by default) and ./splat/playcanvas (PlayCanvas only) both build their
+// PlayCanvas handle here. This module must never import `three` or `@sparkjsdev/spark`, directly
+// or through anything it imports: that is what lets ./splat/playcanvas keep both off the page
+// (test/splat-pc-entry.test.mjs walks the import graph to hold it to that).
+
+import { normalizeCameraPose } from './inline3d-splat-shared.js';
+import { validateEffectCall } from './inline3d-splat-effects.js';
+
+/**
+ * The `engine: 'playcanvas'` handle, returned SYNCHRONOUSLY like the Spark one.
+ *
+ * The adapter module is loaded on demand, so for a moment the handle exists before its
+ * implementation does. Rather than make every caller await something new, the handle starts as
+ * stubs that QUEUE: `exclude()` (which a product page calls on the very next line), `setPose`,
+ * `setFocus`, `remove` — and the adapter replays the queue into the real implementation, on the
+ * SAME object, the moment it arrives. `ready` resolves to this object, as it does on Spark.
+ * Fields (`viewer`, `mesh`, `rig`, …) are null until then; `viewer` in particular appears one
+ * module-load later than on Spark.
+ */
+/** setRig's type/options shape, checked at the call before the adapter has loaded (it re-checks all of it). */
+function validateSetRigArgs(type, o) {
+  if (!['display', 'camera', 'auto'].includes(type)) {
+    throw new Error(`@displayxr/inline3d/splat: setRig("${type}") — expected 'display', 'camera' or 'auto'.`);
+  }
+  if (o !== undefined && (o === null || typeof o !== 'object')) {
+    throw new TypeError('@displayxr/inline3d/splat: setRig options must be an object.');
+  }
+}
+
+export function addSplatDeferred(wall, canvas, src, opts) {
+  const pending = [];
+  const queue = (name) => (...args) => {
+    pending.push([name, args]);
+    return name === 'setFocus' ? out : undefined;
+  };
+  const page = opts.controls === 'page';
+  const pageOnly = (name) => () => {
+    throw new Error(
+      `@displayxr/inline3d/splat: ${name}() is not available with controls:'page' — the page owns the ` +
+        'camera. Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).',
+    );
+  };
+  // Before the adapter lands, a page calling setCameraPose every frame keeps ONE pending pose
+  // (validated now, so a bad call throws at its own line): last call wins, as it will after.
+  let pendingPose = null;
+  const out = {
+    backend: 'playcanvas',
+    engine: null,
+    viewer: null,
+    mesh: null,
+    frame: null,
+    camera: null,
+    rig: null,
+    perf: null,
+    setPose: page ? pageOnly('setPose') : queue('setPose'),
+    resetPose: page ? pageOnly('resetPose') : queue('resetPose'),
+    setCameraPose(matrixWorld, o) {
+      if (!page) {
+        throw new Error(
+          "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { controls:'page' }) — " +
+            'with the default controls the SDK owns the camera (use setPose).',
+        );
+      }
+      const pose = normalizeCameraPose(matrixWorld, o);
+      if (pendingPose) pendingPose[1] = [pose.matrixWorld, pose];
+      else pending.push((pendingPose = ['setCameraPose', [pose.matrixWorld, pose]]));
+      return out;
+    },
+    getCameraPose: () =>
+      pendingPose
+        ? {
+            matrixWorld: Float32Array.from(pendingPose[1][1].matrixWorld),
+            verticalFovDeg: pendingPose[1][1].verticalFovDeg,
+            near: pendingPose[1][1].near,
+            far: pendingPose[1][1].far,
+            convergence: pendingPose[1][1].convergence,
+          }
+        : null,
+    setFocus: queue('setFocus'),
+    // A swap requested before the first asset has landed runs once it has (the adapter's own
+    // setSource replaces this stub on the same object by then).
+    setSource: (...args) => out.ready.then(() => out.setSource(...args)),
+    prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
+    // A rig switch before the first asset has landed: validated now (controls:'page' and a bad
+    // type throw at the call's own line), applied once it has.
+    setRig: page
+      ? pageOnly('setRig')
+      : (type, o) => {
+          validateSetRigArgs(type, o);
+          return out.ready.then(() => out.setRig(type, o));
+        },
+    // A video before the first asset has landed: controls:'page' throws at the call's own line,
+    // the rest is validated by the adapter's setVideo, which runs once the asset is on screen.
+    setVideo: page ? pageOnly('setVideo') : (src, o) => out.ready.then(() => out.setVideo(src, o)),
+    // Effects before the adapter has loaded: validated NOW (a bad call throws at its own line),
+    // then run once the first asset is on screen.
+    playEffect: (name, o) => {
+      validateEffectCall(name, o, 'play');
+      return out.ready.then(() => out.playEffect(name, o));
+    },
+    setEffect: (name, params) => {
+      validateEffectCall(name, params, 'set');
+      pending.push(['setEffect', [name, params]]);
+      return out;
+    },
+    stopEffect: queue('stopEffect'),
+    // A layer-rig request before the adapter has loaded: queued, replayed in order once it has
+    // (it needs no asset, only the engine's layers — which the adapter resolves lazily).
+    setLayerRig: (...args) => {
+      pending.push(['setLayerRig', args]);
+      return out;
+    },
+    setLayerRigOptions: (...args) => {
+      pending.push(['setLayerRigOptions', args]);
+      return out;
+    },
+    layerRigState: () => ({ display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'the PlayCanvas adapter has not loaded yet', viewerDistance: 0.6, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null }),
+    makeSbsMaterial: () => {
+      throw new Error('@displayxr/inline3d/splat: makeSbsMaterial() needs the engine — call it after `await handle.ready`.');
+    },
+    effects: () => [],
+    getFocus: () => null,
+    // A plain data slot the adapter reads at call time, so a callback assigned on the very next
+    // line after addSplat — before the module has loaded — is the one that fires.
+    onFocusChange: null,
+    pick: () => null,
+    // Splat accounting (resident / budget / first frame); null until the adapter has loaded.
+    stats: () => null,
+    remove: queue('remove'),
+    exclude: queue('exclude'),
+    unexclude: queue('unexclude'),
+  };
+  // `firstWoven` exists from the first line, like every other field a page reads right away; the
+  // adapter settles it with the core handle's own once the module has loaded.
+  out.firstWoven = new Promise((resolve) => {
+    out._resolveFirstWoven = resolve;
+  });
+  // The ONE owner of `ready`: the adapter returns its load promise and never touches this field.
+  out.ready = import('./inline3d-splat-playcanvas.js')
+    .then((m) => m.attachPlayCanvasSplat(out, wall, canvas, src, opts, pending))
+    .catch((err) => {
+      // The adapter warns about its own load failures; this is for the module not arriving.
+      if (!out.viewer) console.warn('[inline3d/splat] engine:playcanvas failed to start', err);
+      if (out._resolveFirstWoven) {
+        out._resolveFirstWoven(Object.freeze({ woven: false, confirmed: false, reason: 'layer-failed', ms: 0 }));
+        delete out._resolveFirstWoven;
+      }
+      throw err;
+    });
+  return out;
+}

package/js/inline3d-splat-pc-entry.js

@@ -0,0 +1,45 @@
+// inline3d-splat-pc-entry.js — `@displayxr/inline3d/splat/playcanvas`: addSplat on PlayCanvas only.
+//
+// EXPERIMENTAL, like ./splat. Same addSplat, same handle, same options, with the engine fixed to
+// 'playcanvas'. The difference is what the page downloads: ./splat statically imports `three`
+// and `@sparkjsdev/spark` because Spark is its default engine and its Spark path is synchronous,
+// so a page passing engine:'playcanvas' there still pays for both (~1.7 MB gzipped). This entry
+// imports neither, directly or transitively. `playcanvas` itself is still loaded on demand, when
+// the first splat is added.
+//
+//   import { createInline3D } from '@displayxr/inline3d';
+//   import { addSplat } from '@displayxr/inline3d/splat/playcanvas';
+//
+//   const wall = await createInline3D();
+//   const scene = addSplat(wall, canvas, 'lake.sog', { reveal: 'sweep' });
+//
+// Not here: measureSplatBounds (it measures a Spark mesh — import it from ./splat).
+
+import { resolveRevealOption } from './inline3d-splat-effects.js';
+import { CAPTURE_FITS, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
+import { addSplatDeferred } from './inline3d-splat-deferred.js';
+
+export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
+export { readSogCamera, readSogMeta } from './inline3d-sog.js';
+export { resolveRig } from './inline3d-splat-rig.js';
+
+/** addSplat with `engine: 'playcanvas'`; the same validation, at the call, as ./splat's. */
+export function addSplat(wall, canvas, src, opts = {}) {
+  if (opts.engine !== undefined && opts.engine !== 'playcanvas') {
+    throw new Error(
+      `@displayxr/inline3d/splat/playcanvas: engine "${opts.engine}" — this entry is PlayCanvas ` +
+        "only. Import addSplat from '@displayxr/inline3d/splat' for Spark.",
+    );
+  }
+  if (opts.captureFit !== undefined && !CAPTURE_FITS.includes(opts.captureFit)) {
+    throw new Error(
+      `@displayxr/inline3d/splat: captureFit "${opts.captureFit}" — expected ` +
+        `${CAPTURE_FITS.map((f) => `'${f}'`).join(' or ')}.`,
+    );
+  }
+  resolveControls(opts);
+  resolveRevealOption(opts.reveal);
+  const why = playcanvasCannotRead(src, opts);
+  if (why) throw new Error(`@displayxr/inline3d/splat: ${why}`);
+  return addSplatDeferred(wall, canvas, src, { ...opts, engine: 'playcanvas' });
+}

package/js/inline3d-splat.js

@@ -23,8 +23,9 @@ import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
 import { EyeCamera, EdgeFeather, cameraRigFromCamera } from './inline3d-three.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
 import { readSogCamera } from './inline3d-sog.js';
-import { resolveRevealOption, effectsNotOnSpark, validateEffectCall } from './inline3d-splat-effects.js';
+import { resolveRevealOption, effectsNotOnSpark } from './inline3d-splat-effects.js';
 import { applySplatPerf, splatPerfMeshOptions } from './inline3d-splat-perf.js';
+import { addSplatDeferred } from './inline3d-splat-deferred.js';
 import {
   toArray3,
   canvasNdc,
@@ -36,7 +37,6 @@ import {
   isStreamedUrl,
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
-  normalizeCameraPose,
   declareViewRig,
 } from './inline3d-splat-shared.js';
 import {
@@ -677,149 +677,6 @@ export function addSplat(wall, canvas, src, opts = {}) {
   return out;
 }
 
-/**
- * The `engine: 'playcanvas'` handle, returned SYNCHRONOUSLY like the Spark one.
- *
- * The adapter module is loaded on demand, so for a moment the handle exists before its
- * implementation does. Rather than make every caller await something new, the handle starts as
- * stubs that QUEUE: `exclude()` (which a product page calls on the very next line), `setPose`,
- * `setFocus`, `remove` — and the adapter replays the queue into the real implementation, on the
- * SAME object, the moment it arrives. `ready` resolves to this object, as it does on Spark.
- * Fields (`viewer`, `mesh`, `rig`, …) are null until then; `viewer` in particular appears one
- * module-load later than on Spark.
- */
-/** setRig's type/options shape, checked at the call before the adapter has loaded (it re-checks all of it). */
-function validateSetRigArgs(type, o) {
-  if (!['display', 'camera', 'auto'].includes(type)) {
-    throw new Error(`@displayxr/inline3d/splat: setRig("${type}") — expected 'display', 'camera' or 'auto'.`);
-  }
-  if (o !== undefined && (o === null || typeof o !== 'object')) {
-    throw new TypeError('@displayxr/inline3d/splat: setRig options must be an object.');
-  }
-}
-
-function addSplatDeferred(wall, canvas, src, opts) {
-  const pending = [];
-  const queue = (name) => (...args) => {
-    pending.push([name, args]);
-    return name === 'setFocus' ? out : undefined;
-  };
-  const page = opts.controls === 'page';
-  const pageOnly = (name) => () => {
-    throw new Error(
-      `@displayxr/inline3d/splat: ${name}() is not available with controls:'page' — the page owns the ` +
-        'camera. Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).',
-    );
-  };
-  // Before the adapter lands, a page calling setCameraPose every frame keeps ONE pending pose
-  // (validated now, so a bad call throws at its own line): last call wins, as it will after.
-  let pendingPose = null;
-  const out = {
-    backend: 'playcanvas',
-    engine: null,
-    viewer: null,
-    mesh: null,
-    frame: null,
-    camera: null,
-    rig: null,
-    perf: null,
-    setPose: page ? pageOnly('setPose') : queue('setPose'),
-    resetPose: page ? pageOnly('resetPose') : queue('resetPose'),
-    setCameraPose(matrixWorld, o) {
-      if (!page) {
-        throw new Error(
-          "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { controls:'page' }) — " +
-            'with the default controls the SDK owns the camera (use setPose).',
-        );
-      }
-      const pose = normalizeCameraPose(matrixWorld, o);
-      if (pendingPose) pendingPose[1] = [pose.matrixWorld, pose];
-      else pending.push((pendingPose = ['setCameraPose', [pose.matrixWorld, pose]]));
-      return out;
-    },
-    getCameraPose: () =>
-      pendingPose
-        ? {
-            matrixWorld: Float32Array.from(pendingPose[1][1].matrixWorld),
-            verticalFovDeg: pendingPose[1][1].verticalFovDeg,
-            near: pendingPose[1][1].near,
-            far: pendingPose[1][1].far,
-            convergence: pendingPose[1][1].convergence,
-          }
-        : null,
-    setFocus: queue('setFocus'),
-    // A swap requested before the first asset has landed runs once it has (the adapter's own
-    // setSource replaces this stub on the same object by then).
-    setSource: (...args) => out.ready.then(() => out.setSource(...args)),
-    prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
-    // A rig switch before the first asset has landed: validated now (controls:'page' and a bad
-    // type throw at the call's own line), applied once it has.
-    setRig: page
-      ? pageOnly('setRig')
-      : (type, o) => {
-          validateSetRigArgs(type, o);
-          return out.ready.then(() => out.setRig(type, o));
-        },
-    // A video before the first asset has landed: controls:'page' throws at the call's own line,
-    // the rest is validated by the adapter's setVideo, which runs once the asset is on screen.
-    setVideo: page ? pageOnly('setVideo') : (src, o) => out.ready.then(() => out.setVideo(src, o)),
-    // Effects before the adapter has loaded: validated NOW (a bad call throws at its own line),
-    // then run once the first asset is on screen.
-    playEffect: (name, o) => {
-      validateEffectCall(name, o, 'play');
-      return out.ready.then(() => out.playEffect(name, o));
-    },
-    setEffect: (name, params) => {
-      validateEffectCall(name, params, 'set');
-      pending.push(['setEffect', [name, params]]);
-      return out;
-    },
-    stopEffect: queue('stopEffect'),
-    // A layer-rig request before the adapter has loaded: queued, replayed in order once it has
-    // (it needs no asset, only the engine's layers — which the adapter resolves lazily).
-    setLayerRig: (...args) => {
-      pending.push(['setLayerRig', args]);
-      return out;
-    },
-    setLayerRigOptions: (...args) => {
-      pending.push(['setLayerRigOptions', args]);
-      return out;
-    },
-    layerRigState: () => ({ display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'the PlayCanvas adapter has not loaded yet', viewerDistance: 0.6, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null }),
-    makeSbsMaterial: () => {
-      throw new Error('@displayxr/inline3d/splat: makeSbsMaterial() needs the engine — call it after `await handle.ready`.');
-    },
-    effects: () => [],
-    getFocus: () => null,
-    // A plain data slot the adapter reads at call time, so a callback assigned on the very next
-    // line after addSplat — before the module has loaded — is the one that fires.
-    onFocusChange: null,
-    pick: () => null,
-    // Splat accounting (resident / budget / first frame); null until the adapter has loaded.
-    stats: () => null,
-    remove: queue('remove'),
-    exclude: queue('exclude'),
-    unexclude: queue('unexclude'),
-  };
-  // `firstWoven` exists from the first line, like every other field a page reads right away; the
-  // adapter settles it with the core handle's own once the module has loaded.
-  out.firstWoven = new Promise((resolve) => {
-    out._resolveFirstWoven = resolve;
-  });
-  // The ONE owner of `ready`: the adapter returns its load promise and never touches this field.
-  out.ready = import('./inline3d-splat-playcanvas.js')
-    .then((m) => m.attachPlayCanvasSplat(out, wall, canvas, src, opts, pending))
-    .catch((err) => {
-      // The adapter warns about its own load failures; this is for the module not arriving.
-      if (!out.viewer) console.warn('[inline3d/splat] engine:playcanvas failed to start', err);
-      if (out._resolveFirstWoven) {
-        out._resolveFirstWoven(Object.freeze({ woven: false, confirmed: false, reason: 'layer-failed', ms: 0 }));
-        delete out._resolveFirstWoven;
-      }
-      throw err;
-    });
-  return out;
-}
 
 /**
  * Percentile bounds from the loaded splats — the fallback when no sidecar was supplied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "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",
@@ -23,6 +23,10 @@
       "types": "./splat.d.ts",
       "import": "./js/inline3d-splat.js"
     },
+    "./splat/playcanvas": {
+      "types": "./splat-playcanvas.d.ts",
+      "import": "./js/inline3d-splat-pc-entry.js"
+    },
     "./model": {
       "types": "./model.d.ts",
       "import": "./js/inline3d-model-entry.js"
@@ -36,6 +40,10 @@
       "types": "./player.d.ts",
       "import": "./js/inline3d-player.js"
     },
+    "./camera": {
+      "types": "./camera.d.ts",
+      "import": "./js/inline3d-camera.js"
+    },
     "./call": {
       "types": "./call.d.ts",
       "import": "./js/inline3d-call.js"
@@ -62,6 +70,8 @@
     "js/inline3d-three.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
+    "js/inline3d-splat-pc-entry.js",
+    "js/inline3d-splat-deferred.js",
     "js/inline3d-sog.js",
     "js/inline3d-splat-perf.js",
     "js/inline3d-splat-rig.js",
@@ -79,8 +89,10 @@
     "js/inline3d-pc-look.js",
     "js/inline3d-playcanvas-engine.js",
     "js/inline3d-player.js",
+    "js/inline3d-camera.js",
     "js/inline3d-call.js",
     "js/inline3d-call-full.js",
+    "js/camera/",
     "js/call/",
     "js/lift/",
     "dist/",
@@ -88,8 +100,10 @@
     "three.d.ts",
     "viewer.d.ts",
     "splat.d.ts",
+    "splat-playcanvas.d.ts",
     "model.d.ts",
     "player.d.ts",
+    "camera.d.ts",
     "call.d.ts",
     "call-full.d.ts",
     "CHANGELOG.md",
@@ -149,6 +163,10 @@
     "build:dist": "node tools/dist/build.mjs",
     "prepack": "node tools/dist/build.mjs",
     "test:e2e": "node test/e2e/call-element.e2e.mjs",
+    "test:e2e:camera": "node test/e2e/camera.e2e.mjs",
+    "api:check": "node tools/api-surface.mjs --check",
+    "api:update": "node tools/api-surface.mjs --update",
+    "check:snippets": "node tools/check-snippets.mjs",
     "test:bundlers": "node test/bundlers/run.mjs"
   },
   "devDependencies": {

package/splat-playcanvas.d.ts

@@ -0,0 +1,4 @@
+// Types for `@displayxr/inline3d/splat/playcanvas`: ./splat's addSplat with the engine fixed to
+// 'playcanvas', without the Spark/three peers. Same handle and options as ./splat.
+export { addSplat } from './splat';
+export type * from './splat';