@displayxr/inline3d 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.12.0 — 2026-09-24
+
+Touches the **preview tier** (`./model`, and `./splat`'s `engine: 'playcanvas'` import path). A
+page that calls `addModel` without `engine` now renders with PlayCanvas and **looks different**:
+it is lit to match the Khronos glTF Sample Viewer instead of three's RoomEnvironment. Pass
+`engine: 'three'` to keep 1.11 exactly. Epic [#36](https://github.com/DisplayXR/displayxr-web/issues/36);
+design and measurements: [`docs/playcanvas-model-backend.md`](docs/playcanvas-model-backend.md).
+
+### Changed
+
+- **`addModel` defaults to PlayCanvas** (optional peer `playcanvas >=2.22.3 <3`). The handle is
+  the same: `ready`, `firstWoven`, `setPose`, `resetPose`, `exclude`, `unexclude`, `remove`,
+  `frame`, `model`, `viewer`. On PlayCanvas `model` is the render `pc.Entity`, and the handle also
+  carries `backend`, `engine` (`{ app, root, camera }`) and `container`.
+- **Both engines are imported dynamically** by `./model` (now `js/inline3d-model-entry.js`): a
+  default page loads no three, an `engine: 'three'` page loads no PlayCanvas.
+- **`handle.viewer` is null until the backend module has loaded**, on both engines (1.11 set it
+  synchronously). Read it after `ready`, or import **`@displayxr/inline3d/model/three`**: the 1.11
+  module, byte for byte, synchronous `viewer` included.
+- **No `engine` and no `playcanvas` installed:** the tile renders on three with one console
+  warning. Neither installed: `ready` rejects naming both. With no `engine`, a three.js object in
+  `GLTFLoader` / `DRACOLoader` / `KTX2Loader` / `envMap` selects three (a 1.11 page that injects
+  loaders keeps working unchanged).
+- **The PlayCanvas adapters import `playcanvas` by name** (`js/inline3d-playcanvas-engine.js`), not
+  as a namespace, so bundlers tree-shake the engine: 2,434,536 → 1,499,851 bytes minified,
+  **626 → 397 KB gzip** (esbuild 0.28.2), for `addModel` and for `addSplat(…, {engine:'playcanvas'})`.
+
+### Added (PlayCanvas backend)
+
+- **Lighting matched to the Khronos glTF Sample Viewer** (not to three.js): an in-memory neutral
+  studio fitted to the Sample Viewer's "Studio Neutral" (no asset, no licence), Khronos PBR Neutral
+  tone mapping, exposure 1, sRGB output, MSAA on. On-object MAE vs the Sample Viewer (/255):
+  DamagedHelmet 16.7 (three 36.2), Fox 6.4 (19.5), BrainStem 2.7 (26.7), MetalRoughSpheres 9.4 (26.4).
+- `environment: 'neutral'` (alias of the default `'room'`), `environmentRotation` (degrees),
+  `envMap` as a URL (equirect .hdr/.png/.jpg) or a `pc.Texture`; `'studio'` and `'none'` as on three.
+- Compressed glTF with the **same served files as three**: Draco and KTX2/Basis through the
+  engine's own workers, fed three's `libs/draco/` and `libs/basis/`; `decoderPath` unchanged; a
+  mis-served folder rejects `ready` naming the extension, the file and the option.
+  `EXT_meshopt_compression` via meshoptimizer's `MeshoptDecoder` (new optional peer
+  `meshoptimizer >=1`, loaded only for an asset that declares it; `meshoptDecoder` injects it).
+- `controls: 'page'` + `setCameraPose` / `getCameraPose` / `onBeforeFrame` / `comfortDepth` on
+  models, as on splats (the rig converges on the model's bounds centre unless the pose says).
+- `antialias`, `preserveDrawingBuffer`, `nearClip`, `farClip`, `orbitMaxDeg`, `orbitEase`, `playcanvas`.
+
+### Throws at call time
+
+- An unknown `engine` or `environment`; a PlayCanvas-only option with `engine: 'three'`; a three.js
+  loader or texture with `engine: 'playcanvas'`; a `meshoptDecoder` without `decodeGltfBuffer`;
+  `setCameraPose` without `controls: 'page'`; `setPose` / `resetPose` with it.
+
+### Samples
+
+- `samples/model/` (tiles A and C) and `samples/shopify/` render on the new default;
+  `?engine=three` switches back. Tile B stays on three (it composes a Spark splat into a three scene).
+
 ## 1.11.0 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), additively. Nothing changes

package/README.md

@@ -34,8 +34,9 @@ No build step or bundler required — it's plain ES modules. You can also import
 URL from a CDN (jsDelivr / unpkg) without npm. The samples in this repo import the SDK by relative
 path (`./js/inline3d.js`) so they run straight off GitHub Pages; in your own app prefer the package.
 
-`three` and `@sparkjsdev/spark` are **optional peer dependencies** — the core is dependency-free
-and only the `/three`, `/viewer` and `/splat` subpaths need them. The two viewer subpaths are
+`three`, `@sparkjsdev/spark`, `playcanvas` and `meshoptimizer` are **optional peer dependencies**
+— the core is dependency-free and only the scene subpaths need them (`/model` needs `playcanvas`,
+or `three` with `engine: 'three'`). The two viewer subpaths are
 **experimental**: they turn "one object in a tile, look around it, drag to spin" into a single
 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.
@@ -48,9 +49,18 @@ tilt-and-relax orbit and `handle.engine` (the engine objects, for advanced pages
 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
+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.
 
+**Models render with PlayCanvas by default (1.12).** `addModel(wall, canvas, 'chair.glb')` loads
+the glTF with the PlayCanvas engine (optional peer `playcanvas`), lit to match the Khronos glTF
+Sample Viewer: an in-memory neutral studio environment, Khronos PBR Neutral tone mapping,
+exposure 1. `engine: 'three'` is the 1.11 three.js renderer, unchanged (also importable as
+`@displayxr/inline3d/model/three`). Each engine is imported only when a tile asks for it. Draco
+and KTX2 use the same served decoder folders on both engines. Design, the Sample-Viewer MAE table
+and what throws: [`docs/playcanvas-model-backend.md`](docs/playcanvas-model-backend.md).
+
 **Large scenes stream (preview).** On `engine: 'playcanvas'`, a Streamed SOG streams: pass the URL
 of its `lod-meta.json` (or of its directory), not its bytes. The engine fetches only the chunks
 the view needs and draws at most `perf.splatBudget` of them. That budget is per tile and shared
@@ -134,7 +144,7 @@ samples/
   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
-  model/              a glTF mesh, a mesh+splat scene, and a Draco-COMPRESSED glTF in three tiles
+  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)
 vendor/draco/         three's Draco decoder, served for samples/model (compressed glTF needs it)
@@ -148,7 +158,10 @@ js/
                       (`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
+  inline3d-model-entry.js       experimental: addModel() — picks the engine (PlayCanvas default)
+  inline3d-model-playcanvas.js  the PlayCanvas model backend (Sample-Viewer lighting, engine decoders)
+  inline3d-model.js             the three.js model backend (engine:'three'; ./model/three)
+  inline3d-playcanvas-engine.js named playcanvas imports for both PlayCanvas adapters (tree-shaking)
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/
   authoring-inline-3d.md   the authoring guide

package/js/inline3d-model-entry.js

@@ -0,0 +1,242 @@
+// inline3d-model-entry.js — `@displayxr/inline3d/model`: a glTF/GLB model as an inline-3D window.
+//
+// EXPERIMENTAL. Not covered by the SDK's 1.x semver promise — see docs/sdk-stability.md.
+//
+//   import { createInline3D } from '@displayxr/inline3d';
+//   import { addModel } from '@displayxr/inline3d/model';
+//
+//   const wall = await createInline3D();
+//   const lamp = addModel(wall, canvas, 'lamp.glb', { virtualDisplayHeight: 0.3 });
+//   lamp.exclude(document.getElementById('buy'));
+//
+// WHICH ENGINE (1.12). PlayCanvas by default; `engine: 'three'` is the 1.11 renderer, unchanged
+// (./inline3d-model.js, byte for byte — also importable directly as `@displayxr/inline3d/model/three`).
+// BOTH are imported DYNAMICALLY from here, so a default page never resolves `three` and a
+// three page never resolves `playcanvas`. The handle is returned synchronously on either engine;
+// calls made before the backend has loaded (exclude() on the next line, above all) are queued
+// and replayed, and `viewer` appears one module-load later — the same contract as
+// `addSplat(…, { engine: 'playcanvas' })`.
+//
+// FALLBACK. With no `engine` given, a page that has three but not playcanvas keeps working: the
+// engine import fails, one warning names what to install, and the tile renders on three. With
+// neither, `ready` rejects naming both. An explicit `engine` never falls back.
+
+/** The engines `addModel` renders with; the first is the default. */
+export const MODEL_ENGINES = Object.freeze(['playcanvas', 'three']);
+
+/**
+ * Options whose VALUE is a three.js object. With no explicit `engine` they select three (the page
+ * plainly has it, and handing a three loader to PlayCanvas can only be a mistake); with
+ * `engine: 'playcanvas'` they throw.
+ */
+const THREE_ONLY = ['GLTFLoader', 'DRACOLoader', 'KTX2Loader'];
+const isThreeTexture = (t) => !!t && typeof t === 'object' && (t.isTexture === true || t.isRenderTargetTexture === true);
+
+/**
+ * Which backend a call gets. Pure, synchronous.
+ *
+ * @returns {{engine:'playcanvas'|'three', explicit:boolean, reason:string}}
+ */
+export function resolveModelEngine(opts = {}) {
+  const e = opts.engine;
+  if (e !== undefined && e !== null) {
+    if (!MODEL_ENGINES.includes(e)) {
+      throw new Error(
+        `@displayxr/inline3d/model: unknown engine "${e}" — expected ${MODEL_ENGINES.map((n) => `'${n}'`).join(' or ')} ` +
+          `(default 'playcanvas').`,
+      );
+    }
+    return { engine: e, explicit: true, reason: 'option' };
+  }
+  const threeOpt = THREE_ONLY.find((k) => opts[k]) || (isThreeTexture(opts.envMap) ? 'envMap' : null);
+  if (threeOpt) return { engine: 'three', explicit: false, reason: `three.js object in \`${threeOpt}\`` };
+  return { engine: 'playcanvas', explicit: false, reason: 'default' };
+}
+
+/** Options that exist only on the PlayCanvas backend: an error on an explicit engine:'three'. */
+const PLAYCANVAS_ONLY = ['playcanvas', 'environmentRotation', 'controls', 'comfortDepth', 'onBeforeFrame', 'antialias', 'preserveDrawingBuffer', 'nearClip', 'farClip', 'orbitMaxDeg', 'orbitEase'];
+
+/**
+ * Everything that can be checked before a module loads. Throws at CALL time — a page bug is true
+ * of every call and must not surface as an "asset failed" rejection.
+ */
+export function validateModelCall(canvas, src, opts, route) {
+  if (!canvas || typeof canvas.getBoundingClientRect !== 'function') {
+    throw new Error('@displayxr/inline3d/model: addModel(wall, canvas, src) — `canvas` must be an HTMLCanvasElement.');
+  }
+  if (typeof src !== 'string' || !src) {
+    throw new Error('@displayxr/inline3d/model: addModel(wall, canvas, src) — `src` must be the URL of a .glb or .gltf.');
+  }
+  if (route.engine === 'three' && route.explicit) {
+    const bad = PLAYCANVAS_ONLY.filter((k) => opts[k] !== undefined && !(k === 'controls' && opts[k] === 'viewer'));
+    if (bad.length) {
+      throw new Error(
+        `@displayxr/inline3d/model: ${bad.map((k) => `\`${k}\``).join(', ')} ${bad.length === 1 ? 'is' : 'are'} PlayCanvas-backend ` +
+          "options and do nothing on engine:'three'. Drop them, or drop engine:'three'.",
+      );
+    }
+  }
+  if (route.engine === 'playcanvas' && route.explicit) {
+    const bad = THREE_ONLY.find((k) => opts[k]) || (isThreeTexture(opts.envMap) ? 'envMap' : null);
+    if (bad) {
+      throw new Error(
+        `@displayxr/inline3d/model: \`${bad}\` is a three.js object and engine:'playcanvas' cannot use it. ` +
+          "Drop it (the engine decodes with its own readers; serve the files at `decoderPath`), or pass engine:'three'.",
+      );
+    }
+  }
+}
+
+/**
+ * Load a glTF/GLB into an inline-3D window. See model.d.ts for every option.
+ *
+ * @returns {object} the handle, synchronously: `ready`, `firstWoven`, `setPose`, `resetPose`,
+ *          `exclude`, `unexclude`, `remove` work at once; `viewer`, `model`, `frame`, `engine`
+ *          fill in as the backend loads.
+ */
+export function addModel(wall, canvas, src, opts = {}) {
+  const route = resolveModelEngine(opts);
+  validateModelCall(canvas, src, opts, route);
+  if (route.engine === 'playcanvas') {
+    // The backend's own call-time checks (environment, envMap, controls, three loaders). Imported
+    // lazily below, so this is the cheap pure copy that lives there — see validatePlayCanvasModelOptions.
+    preValidatePlayCanvas(opts);
+  } else if (route.reason !== 'option' && route.reason !== 'default') {
+    console.info(`[inline3d/model] rendering ${src} with three.js: ${route.reason} (pass engine:'three' to say so explicitly).`);
+  }
+
+  const pending = [];
+  const queue = (name) => (...args) => {
+    pending.push([name, args]);
+  };
+  const page = opts.controls === 'page';
+  let pendingPose = null;
+  const out = {
+    backend: route.engine,
+    engine: null,
+    viewer: null,
+    model: null,
+    frame: null,
+    setPose: queue('setPose'),
+    resetPose: queue('resetPose'),
+    setCameraPose(matrixWorld, o) {
+      if (!page) {
+        throw new Error("@displayxr/inline3d/model: setCameraPose() needs addModel(…, { controls:'page' }) — with the default controls the SDK owns the camera (use setPose).");
+      }
+      if (pendingPose) pendingPose[1] = [matrixWorld, o];
+      else pending.push((pendingPose = ['setCameraPose', [matrixWorld, o]]));
+      return out;
+    },
+    getCameraPose: () => null,
+    remove: queue('remove'),
+    exclude: queue('exclude'),
+    unexclude: queue('unexclude'),
+  };
+  out.firstWoven = new Promise((resolve) => {
+    out._resolveFirstWoven = resolve;
+  });
+  const settleFirstWoven = (reason) => {
+    if (typeof out._resolveFirstWoven === 'function') {
+      out._resolveFirstWoven(Object.freeze({ woven: false, confirmed: false, reason, ms: 0 }));
+      delete out._resolveFirstWoven;
+    }
+  };
+
+  out.ready = (async () => {
+    if (route.engine === 'three') return attachThree(out, wall, canvas, src, opts, pending);
+    const mod = await import('./inline3d-model-playcanvas.js');
+    let pc = opts.playcanvas || null;
+    if (!pc) {
+      try {
+        pc = await import('./inline3d-playcanvas-engine.js');
+      } catch (err) {
+        if (route.explicit) throw playcanvasMissing(err, false);
+        let three;
+        try {
+          three = await import('./inline3d-model.js');
+        } catch (err3) {
+          throw playcanvasMissing(err, err3);
+        }
+        console.warn(
+          `[inline3d/model] \`playcanvas\` could not be loaded (${err?.message || err}); rendering ${src} with three.js instead. ` +
+            "npm i playcanvas for the default renderer, or pass engine:'three' to silence this.",
+        );
+        out.backend = 'three';
+        return attachThree(out, wall, canvas, src, opts, pending, three);
+      }
+    }
+    return mod.attachPlayCanvasModel(out, wall, canvas, src, opts, pending, pc);
+  })().catch((err) => {
+    settleFirstWoven('layer-failed');
+    throw err;
+  });
+  return out;
+}
+
+function playcanvasMissing(err, err3) {
+  const e = new Error(
+    '@displayxr/inline3d/model: addModel renders with PlayCanvas by default and `playcanvas` could not be loaded' +
+      (err3 ? ' — and neither could `three` for the fallback' : '') +
+      ". Install one: `npm i playcanvas` (default), or `npm i three` and pass engine:'three'. On a bare importmap, map " +
+      '"playcanvas" (or "three" + "three/addons/"). ' +
+      `Underlying error: ${err?.message || err}` +
+      (err3 ? ` / ${err3?.message || err3}` : ''),
+  );
+  e.cause = err;
+  return e;
+}
+
+/** Call-time checks for the PlayCanvas backend that need no module (mirrors the backend's own). */
+function preValidatePlayCanvas(opts) {
+  const env = opts.environment;
+  if (env !== undefined && !['room', 'neutral', 'studio', 'none'].includes(env)) {
+    throw new Error(`@displayxr/inline3d/model: environment "${env}" — expected 'room', 'neutral', 'studio' or 'none'.`);
+  }
+  if (opts.envMap !== undefined && opts.envMap !== null && typeof opts.envMap !== 'string' && typeof opts.envMap !== 'object') {
+    throw new Error('@displayxr/inline3d/model: `envMap` must be a URL string or a pc.Texture.');
+  }
+  const c = opts.controls;
+  if (c !== undefined && c !== 'viewer' && c !== 'page') {
+    throw new Error(`@displayxr/inline3d/model: controls "${c}" — expected 'viewer' or 'page' (default 'viewer').`);
+  }
+  if (opts.onBeforeFrame !== undefined && (typeof opts.onBeforeFrame !== 'function' || c !== 'page')) {
+    throw new Error("@displayxr/inline3d/model: onBeforeFrame must be a function, and needs controls:'page'.");
+  }
+  if (opts.meshoptDecoder && typeof opts.meshoptDecoder.decodeGltfBuffer !== 'function') {
+    throw new Error("@displayxr/inline3d/model: `meshoptDecoder` must be meshoptimizer's MeshoptDecoder (it has decodeGltfBuffer()).");
+  }
+}
+
+/**
+ * engine:'three' — today's addModel (./inline3d-model.js), unchanged, behind this handle: its own
+ * handle's fields are forwarded (getters, since it fills them as it loads) and the queued calls
+ * are replayed into it.
+ */
+async function attachThree(out, wall, canvas, src, opts, pending, mod) {
+  const m = mod || (await import('./inline3d-model.js'));
+  const inner = m.addModel(wall, canvas, src, opts);
+  for (const k of ['viewer', 'model', 'frame']) {
+    Object.defineProperty(out, k, { get: () => inner[k], set: (v) => (inner[k] = v), enumerable: true, configurable: true });
+  }
+  out.backend = 'three';
+  out.engine = null;
+  out.setPose = inner.setPose;
+  out.resetPose = inner.resetPose;
+  out.remove = inner.remove;
+  out.exclude = inner.exclude;
+  out.unexclude = inner.unexclude;
+  out.inner = inner;
+  if (typeof out._resolveFirstWoven === 'function') {
+    out._resolveFirstWoven(inner.firstWoven);
+    delete out._resolveFirstWoven;
+  }
+  for (const [name, args] of pending) {
+    if (name === 'remove') {
+      inner.remove();
+      break;
+    }
+    inner[name]?.(...args);
+  }
+  await inner.ready;
+  return out;
+}