@displayxr/inline3d 1.10.1 → 1.12.0

package/js/inline3d-splat-shared.js

@@ -316,3 +316,124 @@ export function playcanvasCannotRead(src, { fileType, fileName } = {}) {
     `${what}. Pass engine:'spark' for .spz / .splat / .ksplat / .rad.`
   );
 }
+
+// ── controls:'page' — the page drives the camera (docs/playcanvas-adapter.md §controls:'page') ──
+
+/** Who owns the camera: the SDK's viewer (orbit, idle, fit, focus gestures) or the page. */
+export const SPLAT_CONTROLS = Object.freeze(['viewer', 'page']);
+
+/**
+ * `comfortDepth` default — the auto-3D shim's `depth`, so a game on `controls:'page'` gets the
+ * same stereo as the same game under the shim. It is the runtime's comfort number
+ * `ipd × metersToVirtual × convergenceDiopters × 0.5`, which the rig below makes equal to it by
+ * construction (`metersToVirtual = comfortDepth · d / 0.5`, `convergenceDiopters = 1 / d`).
+ */
+export const PAGE_COMFORT_DEPTH = 0.3;
+
+/**
+ * Options that mean nothing when the page owns the camera. Passing one is not an error (a page
+ * switching an existing call site over should not have to prune it first); it is named ONCE in a
+ * console.info line and ignored.
+ */
+export const PAGE_IGNORED_OPTIONS = Object.freeze([
+  'fit',
+  'virtualDisplayHeight',
+  'orbit',
+  'idleSpin',
+  'focusInput',
+  'margin',
+  'fitSweep',
+  'depthLimit',
+  'orbitMaxDeg',
+  'orbitEase',
+  'captureFit',
+]);
+
+/**
+ * Validate the `controls` family at CALL time (both engines call this before anything loads).
+ *
+ * @returns {{page:boolean, comfortDepth:number, ignored:string[]}}
+ * @throws on an unknown `controls`, a `comfortDepth` outside (0, 1], or `rig:'display'` with
+ *         `controls:'page'` (the page's camera IS the rig; a display rig has no camera).
+ */
+export function resolveControls(opts = {}) {
+  const controls = opts.controls ?? 'viewer';
+  if (!SPLAT_CONTROLS.includes(controls)) {
+    throw new Error(
+      `@displayxr/inline3d/splat: controls "${controls}" — expected ` +
+        `${SPLAT_CONTROLS.map((c) => `'${c}'`).join(' or ')} (default 'viewer').`,
+    );
+  }
+  const page = controls === 'page';
+  let comfortDepth = PAGE_COMFORT_DEPTH;
+  if (opts.comfortDepth !== undefined) {
+    const c = opts.comfortDepth;
+    if (typeof c !== 'number' || !Number.isFinite(c) || c <= 0 || c > 1) {
+      throw new Error(
+        `@displayxr/inline3d/splat: comfortDepth ${c} — expected a number in (0, 1] ` +
+          `(the runtime's comfort rule caps it at 1; the default is ${PAGE_COMFORT_DEPTH}).`,
+      );
+    }
+    comfortDepth = c;
+  }
+  if (page && opts.rig === 'display') {
+    throw new Error(
+      "@displayxr/inline3d/splat: controls:'page' with rig:'display' — the page's camera IS the " +
+        "rig, so it is always a camera rig. Drop `rig`, or use the default controls for a display rig.",
+    );
+  }
+  if (opts.onBeforeFrame !== undefined) {
+    if (typeof opts.onBeforeFrame !== 'function') {
+      throw new Error('@displayxr/inline3d/splat: onBeforeFrame must be a function (frame) => void.');
+    }
+    if (!page) {
+      throw new Error(
+        "@displayxr/inline3d/splat: onBeforeFrame needs controls:'page' — with the default controls " +
+          'the SDK owns the camera and there is no page pose to set before the draw.',
+      );
+    }
+  }
+  const ignored = page ? PAGE_IGNORED_OPTIONS.filter((k) => opts[k] !== undefined) : [];
+  return { page, comfortDepth, ignored };
+}
+
+/**
+ * Validate one `setCameraPose(matrixWorld, o)` call and return a private copy (the page may
+ * reuse its arrays). Throws synchronously on a malformed call: a NaN in a camera matrix is a page
+ * bug that would otherwise render nothing, silently.
+ *
+ * @returns {{matrixWorld:Float64Array, verticalFovDeg:number, near:number, far:number,
+ *            convergence:number|null}}
+ */
+export function normalizeCameraPose(matrixWorld, o = {}) {
+  const bad = (why) => new Error(`@displayxr/inline3d/splat: setCameraPose — ${why}`);
+  if (!matrixWorld || typeof matrixWorld.length !== 'number' || matrixWorld.length !== 16) {
+    throw bad('matrixWorld must be 16 numbers, column-major (a Float32Array(16) or an array).');
+  }
+  const m = new Float64Array(16);
+  for (let i = 0; i < 16; i++) {
+    const v = matrixWorld[i];
+    if (typeof v !== 'number' || !Number.isFinite(v)) throw bad(`matrixWorld[${i}] is ${v}, not a finite number.`);
+    m[i] = v;
+  }
+  const det =
+    m[0] * (m[5] * m[10] - m[9] * m[6]) - m[4] * (m[1] * m[10] - m[9] * m[2]) + m[8] * (m[1] * m[6] - m[5] * m[2]);
+  if (!(det > 1e-12)) {
+    throw bad(`matrixWorld is singular or mirrored (det ${det.toPrecision(3)}); a camera pose is a rotation, a translation and at most a uniform scale.`);
+  }
+  const fov = o.verticalFovDeg;
+  if (typeof fov !== 'number' || !(fov > 0 && fov < 180)) {
+    throw bad(`verticalFovDeg ${fov} — the FULL vertical angle in degrees, in (0, 180).`);
+  }
+  const near = o.near === undefined ? MONO_NEAR : o.near;
+  const far = o.far === undefined ? CAPTURE_FAR : o.far;
+  if (typeof near !== 'number' || !(near > 0) || !Number.isFinite(near)) throw bad(`near ${near} — expected a finite number > 0.`);
+  if (typeof far !== 'number' || !(far > near) || !Number.isFinite(far)) throw bad(`far ${far} — expected a finite number > near.`);
+  let convergence = null;
+  if (o.convergence !== undefined && o.convergence !== null) {
+    const c = o.convergence;
+    if (typeof c !== 'number' || !(c > 0) || !Number.isFinite(c)) throw bad(`convergence ${c} — metres along the view axis, > 0 (omit it for the adapter's own).`);
+    convergence = c;
+  }
+  return { matrixWorld: m, verticalFovDeg: fov, near, far, convergence };
+}

package/js/inline3d-splat.js

@@ -34,6 +34,8 @@ import {
   playcanvasCannotRead,
   isStreamedUrl,
   STREAMED_NEEDS_PLAYCANVAS,
+  resolveControls,
+  normalizeCameraPose,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -163,6 +165,9 @@ export function addSplat(wall, canvas, src, opts = {}) {
         `${CAPTURE_FITS.map((f) => `'${f}'`).join(' or ')}.`,
     );
   }
+  // WHO OWNS THE CAMERA. Validated here, synchronously, for both engines (an unknown `controls`
+  // or a comfortDepth out of range is a page bug true of every call).
+  const { page: pageControls } = resolveControls(opts);
   // WHICH ENGINE. Unset (or 'spark') is everything below, untouched. 'playcanvas' goes to
   // ./inline3d-splat-playcanvas.js, imported DYNAMICALLY so a page that never asks for it never
   // resolves `playcanvas` — see addSplatDeferred.
@@ -174,6 +179,16 @@ export function addSplat(wall, canvas, src, opts = {}) {
     return addSplatDeferred(wall, canvas, src, opts);
   }
 
+  // controls:'page' is a PlayCanvas-backend feature (docs/playcanvas-adapter.md §controls:'page'):
+  // on Spark it would need SceneViewer — which ./viewer and ./model share — to take an external
+  // camera in both its mono and eye paths. Refused by name rather than half-supported.
+  if (pageControls) {
+    throw new Error(
+      "@displayxr/inline3d/splat: controls:'page' is not supported on Spark (the default engine) — " +
+        "pass engine:'playcanvas'. Spark's viewer owns its camera; see docs/playcanvas-adapter.md.",
+    );
+  }
+
   // A Streamed SOG on Spark is a page bug (Spark has no lod-meta.json reader): say so now, by
   // name, rather than let Spark fail on an "unknown file type" that reads like a corrupt asset.
   if (isStreamedUrl(src)) throw new Error(`@displayxr/inline3d/splat: ${STREAMED_NEEDS_PLAYCANVAS}`);
@@ -336,6 +351,13 @@ export function addSplat(wall, canvas, src, opts = {}) {
     },
     /** Called with the live focus, in the splat's own space, whenever it moves. */
     onFocusChange: null,
+    /** Not on this backend: controls:'page' is a PlayCanvas-backend feature. */
+    setCameraPose() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { engine:'playcanvas', controls:'page' }).",
+      );
+    },
+    getCameraPose: () => null,
     /** Not on this backend: the crossfading asset swap is a PlayCanvas-backend feature. */
     setSource() {
       throw new Error(
@@ -622,6 +644,16 @@ function addSplatDeferred(wall, canvas, src, opts) {
     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,
@@ -631,8 +663,30 @@ function addSplatDeferred(wall, canvas, src, opts) {
     camera: null,
     rig: null,
     perf: null,
-    setPose: queue('setPose'),
-    resetPose: queue('resetPose'),
+    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).

package/model.d.ts

@@ -1,13 +1,25 @@
-// Type definitions for @displayxr/inline3d/model.
+// Type definitions for @displayxr/inline3d/model (and ./model/three).
 // EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
 import type { FirstWovenResult } from './index.js';
+import type { PlayCanvasSplatViewer, SplatCameraPose, SplatFrameInfo } from './splat.js';
 
 export interface ModelOptions {
+  /**
+   * Which engine renders the model (1.12). `'playcanvas'` is the DEFAULT (optional peer
+   * `playcanvas >=2.22.3 <3`); `'three'` is the 1.11 renderer, byte for byte (optional peer
+   * `three`). Both are imported dynamically, so a page loads only the engine it renders with.
+   *
+   * With no `engine`: a three.js object in `GLTFLoader` / `DRACOLoader` / `KTX2Loader` / `envMap`
+   * selects three; otherwise PlayCanvas, falling back to three (one console warning) when
+   * `playcanvas` cannot be imported, and rejecting `ready` naming both when neither can. An
+   * explicit `engine` never falls back. Anything else throws at call time.
+   */
+  engine?: 'playcanvas' | 'three';
   /** Metres of world the tile's height spans (default 0.24). */
   virtualDisplayHeight?: number;
-  /** Precomputed subject bounds. Rarely needed for a mesh — Box3 is exact. */
+  /** Precomputed subject bounds. Rarely needed for a mesh — its bounds are exact. */
   frame?: SubjectBounds;
   /** Degrees/second of turntable once idle (default 8). */
   idleSpin?: number;
@@ -25,26 +37,42 @@ export interface ModelOptions {
   /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
   renderScale?: number;
   feather?: number;
-  /** Built-in three-point lighting. Meshes arrive unlit; splats do not need this. */
   /**
-   * How the mesh is lit. `room` (default) bakes IBL from three's procedural RoomEnvironment —
-   * metal and glass need it, because a punctual rig leaves a `metalness: 1` surface with nothing
-   * to reflect and it renders black. `studio` is the older three-point punctual rig.
+   * How the mesh is lit.
+   *
+   * PlayCanvas (default engine): `room` (default; `neutral` is an alias) is image-based lighting
+   * from an in-memory neutral photo studio fitted to the Khronos glTF Sample Viewer's "Studio
+   * Neutral", with Khronos PBR Neutral tone mapping and exposure 1 — the Sample Viewer's look.
+   * three: `room` bakes three's procedural RoomEnvironment, untonemapped (unchanged since 1.11).
+   *
+   * Both: `studio` is the three-point punctual rig (metal renders dark under it — nothing to
+   * reflect); `none` adds no light at all. Anything else throws on PlayCanvas.
    */
-  environment?: 'room' | 'studio' | 'none';
-  /** A PMREM-processed environment texture. Better than `environment` for metal; overrides it. */
-  envMap?: object;
-  /** Hand in the GLTFLoader class instead of resolving it from `three/addons/`. */
+  environment?: 'room' | 'neutral' | 'studio' | 'none';
+  /**
+   * PlayCanvas only: yaw of the environment about +Y, degrees (default 0 = the Sample Viewer's
+   * default orientation).
+   */
+  environmentRotation?: number;
+  /**
+   * Your own environment; overrides `environment`.
+   * three: a PMREM-processed texture. PlayCanvas: a URL of an equirect image (.hdr/.png/.jpg) or
+   * a `pc.Texture` (equirect or cubemap), prefiltered for you. A three texture on
+   * `engine: 'playcanvas'` throws; with no `engine` it selects three.
+   */
+  envMap?: object | string;
+  /** three only: hand in the GLTFLoader class instead of resolving it from `three/addons/`. */
   GLTFLoader?: unknown;
 
   /**
-   * Where **your page** serves three's Draco decoder and Basis (KTX2) transcoder.
+   * Where **your page** serves the Draco decoder and Basis (KTX2) transcoder — the SAME files on
+   * both engines: three's `libs/draco/` (`draco_wasm_wrapper.js` + `draco_decoder.wasm`) and
+   * `libs/basis/` (`basis_transcoder.js` + `.wasm`). The PlayCanvas engine's own Draco and Basis
+   * workers load them.
    *
-   * `addModel` reads the asset's `extensionsUsed` before parsing and attaches only the decoders it
-   * declares, so an uncompressed model never touches any of this. But a decoder that IS needed has
-   * to come from somewhere, and the default is deliberately **not a CDN** — a page shipping an
-   * offline build must not acquire a network dependency by loading a compressed file. Copy the
-   * files out of `three` and serve them yourself:
+   * The asset's `extensionsUsed` decides which decoders are wired, so an uncompressed model never
+   * touches any of this. The default is deliberately **not a CDN** — a page shipping an offline
+   * build must not acquire a network dependency by loading a compressed file:
    *
    * ```sh
    * cp -r node_modules/three/examples/jsm/libs/draco/ public/draco/
@@ -52,25 +80,48 @@ export interface ModelOptions {
    * ```
    *
    * A string is a parent directory holding `draco/` and `basis/`; an object overrides either key.
-   * `EXT_meshopt_compression` needs nothing served — its decoder is pure JS.
+   * On PlayCanvas the engine keeps ONE Draco and ONE Basis worker pool per page: the first tile
+   * that needs one sets its path, and a later tile asking for another path is warned.
    *
    * @default {draco:'/draco/', basis:'/basis/'}
    */
   decoderPath?: string | { draco?: string; basis?: string };
-  /**
-   * DRACOLoader class **or** a ready instance, instead of resolving `three/addons/`. A class is
-   * constructed and pointed at `decoderPath`; an instance is used exactly as you configured it.
-   */
+  /** three only: DRACOLoader class **or** a ready instance, instead of resolving `three/addons/`. */
   DRACOLoader?: unknown;
+  /** three only: KTX2Loader class or instance. */
+  KTX2Loader?: unknown;
   /**
-   * KTX2Loader class or instance. `detectSupport()` is called for you with this tile's renderer,
-   * and the transcoder is loaded eagerly so a mis-served path throws instead of silently
-   * resolving a model with no textures.
+   * The `MeshoptDecoder` for `EXT_meshopt_compression`. Nothing to serve (pure JS). Default: three
+   * resolves `three/addons/libs/meshopt_decoder.module.js`; PlayCanvas resolves
+   * `meshoptimizer/decoder` (optional peer `meshoptimizer >=1`), only for an asset that declares it.
    */
-  KTX2Loader?: unknown;
-  /** The `MeshoptDecoder` namespace, instead of resolving `three/addons/`. Nothing to serve. */
   meshoptDecoder?: unknown;
 
+  /** PlayCanvas only: the `playcanvas` module (or a namespace with the same members) to use. */
+  playcanvas?: object;
+  /** PlayCanvas only: MSAA on the tile's WebGL context (default true, as three's renderer). */
+  antialias?: boolean;
+  /** PlayCanvas only: the context's `preserveDrawingBuffer` (default false). */
+  preserveDrawingBuffer?: boolean;
+  /** PlayCanvas only: raise every projection's near plane to at least this (depth mapping only). */
+  nearClip?: number;
+  /** PlayCanvas only: lower every projection's far plane to at most this. */
+  farClip?: number;
+  /** PlayCanvas only: the drag's tilt cap in degrees (default 15, tilt-and-relax). */
+  orbitMaxDeg?: number;
+  /** PlayCanvas only: the orbit's easing time constants, seconds. */
+  orbitEase?: { drag?: number; rest?: number };
+  /**
+   * PlayCanvas only: who owns the camera — the SDK's viewer (default) or the page, through
+   * {@link ModelHandle.setCameraPose} every frame (the attach rig; converges on the model's bounds
+   * centre unless the pose gives a `convergence`).
+   */
+  controls?: 'viewer' | 'page';
+  /** `controls: 'page'`: the comfort depth of the declared rig, in (0, 1] (default 0.3). */
+  comfortDepth?: number;
+  /** `controls: 'page'` only: runs inside the adapter's frame, before the draw. */
+  onBeforeFrame?: (frame: SplatFrameInfo) => void;
+
   /** Element whose visibility gates the lazy create/close lifecycle. */
   observe?: Element;
   /** Forwarded to the core window: see `TileOptions.firstWovenHoldMs`. */
@@ -79,16 +130,43 @@ export interface ModelOptions {
 
 /** What {@link addModel} returns — the same shape as addSplat's handle. */
 export interface ModelHandle {
-  readonly viewer: SceneViewer;
-  /** The loaded glTF scene root; null until `ready` resolves. */
+  /** Which engine renders this tile. Can change from `'playcanvas'` to `'three'` on the fallback. */
+  readonly backend: 'playcanvas' | 'three';
+  /**
+   * three: the SceneViewer. PlayCanvas: the backend's viewer (the SceneViewer pose surface
+   * without three). Null until the backend module has loaded — one module fetch after addModel
+   * returns (1.11 returned it synchronously; `@displayxr/inline3d/model/three` still does).
+   */
+  readonly viewer: SceneViewer | PlayCanvasSplatViewer | null;
+  /**
+   * The loaded glTF root — a three `Object3D`, or on PlayCanvas the render `pc.Entity`
+   * (`instantiateRenderEntity()`). Null until `ready` resolves.
+   */
   model: object | null;
+  /** PlayCanvas only: the container resource (animations, materials, textures). */
+  readonly container?: unknown;
+  /**
+   * PlayCanvas only (ADVANCED, not covered by the semver promise): `app` is the tile's AppBase,
+   * `root` the content root (the model's parent — add entities, lights or an `anim` component
+   * under it), `camera` the eye camera. Null on three and until the engine has booted.
+   */
+  readonly engine: { readonly app: unknown; readonly root: unknown; readonly camera: unknown } | null;
   /** Bounds used for framing; null until `ready` resolves. */
   frame: SubjectBounds | null;
   /** Resolves once the model has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<ModelHandle>;
 
+  /** Throws on `controls: 'page'`. */
   setPose(pose?: OrbitPose): void;
+  /** Throws on `controls: 'page'`. */
   resetPose(): void;
+  /** `controls: 'page'` only (throws otherwise): the camera for the next frame, model space. */
+  setCameraPose(
+    matrixWorld: ArrayLike<number>,
+    opts: { verticalFovDeg: number; near?: number; far?: number; convergence?: number | null },
+  ): ModelHandle;
+  /** The last pose the page set (a copy), or null. */
+  getCameraPose(): SplatCameraPose | null;
 
   remove(): void;
   exclude(el: Element): void;
@@ -102,10 +180,11 @@ export interface ModelHandle {
 
 /**
  * Load a glTF/GLB into an inline-3D window. Safe to call with an unsupported wall — it renders a
- * flat, orbitable view instead, so pages need no branch.
+ * flat, orbitable view instead, so pages need no branch. Renders with PlayCanvas by default
+ * (1.12); pass `engine: 'three'` for the 1.11 renderer.
  *
  * Compressed assets (Draco, meshopt, KTX2/Basis) load too: the asset's declared extensions decide
- * which decoders are imported, and nothing is imported for an asset that declares none. Draco and
+ * which decoders are wired, and nothing is wired for an asset that declares none. Draco and
  * KTX2 additionally need their runtime files served by your page — see {@link ModelOptions.decoderPath}.
  * When a decoder is needed and unavailable, `ready` rejects with an Error naming the glTF
  * extension, the option that fixes it and the path it looked in; the extension is also on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.10.1",
+  "version": "1.12.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",
@@ -24,6 +24,10 @@
       "import": "./js/inline3d-splat.js"
     },
     "./model": {
+      "types": "./model.d.ts",
+      "import": "./js/inline3d-model-entry.js"
+    },
+    "./model/three": {
       "types": "./model.d.ts",
       "import": "./js/inline3d-model.js"
     },
@@ -47,6 +51,9 @@
     "js/inline3d-splat-playcanvas.js",
     "js/inline3d-splat-shared.js",
     "js/inline3d-model.js",
+    "js/inline3d-model-entry.js",
+    "js/inline3d-model-playcanvas.js",
+    "js/inline3d-playcanvas-engine.js",
     "index.d.ts",
     "three.d.ts",
     "viewer.d.ts",
@@ -64,7 +71,8 @@
     "stereo",
     "3d-display",
     "lightfield",
-    "three"
+    "three",
+    "playcanvas"
   ],
   "homepage": "https://displayxr.github.io/displayxr-web/",
   "repository": {
@@ -78,7 +86,8 @@
   "peerDependencies": {
     "three": ">=0.150.0",
     "@sparkjsdev/spark": ">=2.0.0",
-    "playcanvas": ">=2.22.3 <3"
+    "playcanvas": ">=2.22.3 <3",
+    "meshoptimizer": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "three": {
@@ -89,6 +98,9 @@
     },
     "playcanvas": {
       "optional": true
+    },
+    "meshoptimizer": {
+      "optional": true
     }
   },
   "publishConfig": {

package/splat.d.ts

@@ -304,6 +304,61 @@ export interface SplatOptions {
   observe?: Element;
   /** Forwarded to the core window: see `TileOptions.firstWovenHoldMs`. */
   firstWovenHoldMs?: number;
+  /**
+   * Who owns the camera. `'viewer'` (the default): the SDK's orbit, idle spin, auto-fit and focus
+   * gestures. `'page'` (`engine: 'playcanvas'` only; throws on Spark): the page drives the camera
+   * every frame through {@link SplatHandle.setCameraPose} and the adapter keeps only the eye math —
+   * the attach-pattern camera rig, the runtime's projections, the mono fallback. `fit`,
+   * `virtualDisplayHeight`, `orbit`, `idleSpin`, `focusInput` (and the other framing/orbit knobs)
+   * are ignored, named once in a `console.info`; `rig: 'display'` throws.
+   */
+  controls?: 'viewer' | 'page';
+  /**
+   * `controls: 'page'`: the comfort number `ipd × metersToVirtual × convergenceDiopters × 0.5` the
+   * rig is built to, in (0, 1]. Default 0.3, the auto-3D shim's. `metersToVirtual = comfortDepth ·
+   * d / 0.5`, so the depth budget is the same for a 10 cm subject and a 150 m castle.
+   */
+  comfortDepth?: number;
+  /**
+   * `controls: 'page'` only: called once per adapter frame — the wall's session frame in 3D, the
+   * mono rAF in 2D — BEFORE anything renders. Call `handle.setCameraPose(…)` synchronously in
+   * here and THIS frame renders that pose (zero lag, the attach pattern); a pose set from the
+   * page's own rAF may be one frame late, since the two rAFs have no guaranteed order. A throw is
+   * caught and warned once; frames keep rendering.
+   */
+  onBeforeFrame?: (frame: SplatFrameInfo) => void;
+}
+
+/** What `onBeforeFrame` receives. */
+export interface SplatFrameInfo {
+  /** `performance.now()` at the call. */
+  time: number;
+  /** The runtime's view list in 3D (valid only inside the call — copy what you keep); null in mono. */
+  views: readonly XRView[] | null;
+  /** Seconds since the previous call (0 on the first; capped at 0.1). */
+  dt: number;
+}
+
+/** A page camera, as `setCameraPose` takes it and `getCameraPose` returns it. */
+export interface SplatCameraPose {
+  /**
+   * Column-major world matrix of the page camera in the SPLAT's own space (the space of the camera
+   * block's `rest`), three.js convention: looks down −Z, +Y up. Rotation + translation + at most a
+   * UNIFORM scale (a page whose world scales the splat passes `inv(splatWorld) · camera.matrixWorld`;
+   * the scale is how page units reach the adapter). The adapter applies its own OpenCV → engine flip.
+   */
+  matrixWorld: Float32Array;
+  /** Full vertical field of view, degrees. */
+  verticalFovDeg: number;
+  /** Page units. Default 0.001. A floor on every projection's near (depth mapping only). */
+  near: number;
+  /** Page units. Default 5000. A cap on every projection's far. */
+  far: number;
+  /**
+   * Zero-disparity distance along the view axis, page units; null = the adapter's own (the focus
+   * waterfall's, fixed until `setFocus` / `setSource`).
+   */
+  convergence: number | null;
 }
 
 /** `handle.stats()` on `engine: 'playcanvas'`. */
@@ -384,8 +439,21 @@ export interface SplatHandle {
   /** Resolves once the asset has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<SplatHandle>;
 
+  /** Throws on `controls: 'page'` (the page owns the camera). */
   setPose(pose?: OrbitPose): void;
+  /** Throws on `controls: 'page'`. */
   resetPose(): void;
+  /**
+   * `controls: 'page'` only (throws otherwise): the camera for the next frame drawn — call it every
+   * frame you render, ideally inside `onBeforeFrame`. Last call wins; a page that stops calling
+   * keeps its last pose. Throws synchronously on a malformed matrix or lens.
+   */
+  setCameraPose(
+    matrixWorld: ArrayLike<number>,
+    opts: { verticalFovDeg: number; near?: number; far?: number; convergence?: number },
+  ): SplatHandle;
+  /** The last pose the page set (a copy), or null before the first `setCameraPose`. */
+  getCameraPose(): SplatCameraPose | null;
   /**
    * Point the window at something, in the SPLAT's own space (the space the `camera` block's
    * `focus.point` is in). Null returns to whatever the waterfall resolved. Eased unless `snap`.