@displayxr/inline3d 1.29.0 → 1.31.0

package/CHANGELOG.md

@@ -5,6 +5,193 @@ 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.31.0 — 2026-10-05
+
+The 1.29 `./call` option spellings stay accepted (with their warning) for one more release; they go in 1.32.
+
+Touches the **preview tier** (`./viewer`, `./splat`, `./model`: the eye cameras they draw) and adds
+one **core** option and export. Pixels move only around a tracking acquisition or loss.
+
+### Added — the tracking ease (`viewerEase`, default on)
+
+- When a viewer is acquired (the views jump from the untracked fallback viewpoint to the tracked
+  eyes) or lost, the SDK's renderers now glide the eye cameras from where they were drawn to the
+  live views over 300 ms (smoothstep) instead of snapping in one frame. Triggered by a jump of more
+  than 0.15 eye separations in one frame within 600 ms of a `trackingState` edge (the state and the
+  jump need not land on the same frame; an edge with no jump changes nothing), or, where the browser
+  reports no state, by a one-frame jump of more than half an eye separation. The eye positions for that test are read off the projections,
+  so rig changes, scene scale and canvas size do not trigger it.
+- Exact, not approximate: every DisplayXR frustum is affine in the eye position, so offsetting the
+  pose (in the view's own frame) and the projection (element-wise) by the same weight gives the
+  frustum the runtime would report for the eased eye. The rig map and the layer rig see consistent
+  views throughout.
+- Left alone: ordinary head motion, a vendor-animated ramp, view-count changes (2D<->3D mode switch),
+  buffer resizes, replayed frames, mono.
+- `createInline3D({ viewerEase })` sets the session default; `viewerEase` on `SceneViewer`,
+  `addSplat` and `addModel` overrides it. `false` (or `{ durationMs: 0 }`) restores the snap;
+  `{ durationMs, easing }` tunes it. Core exports `ViewerEase`, `resolveViewerEaseOption`,
+  `frameTrackingState`, `VIEWER_EASE_DEFAULT_MS` for pages that render their own `addScene`.
+  `handle.viewer.viewerEase.last` reports the last frame's weight and trigger.
+
+## 1.30.0 — 2026-10-05
+
+Touches the **preview tier** only (`./call`, `./call/full`, the new `./camera` and `./splat/playcanvas`). RFC 0003
+**phase C2**: the `./call` public surface is trimmed to what a page needs (one warning release
+for the old names), options are regrouped, theming gets a real API, and the stereo camera
+becomes its own subpath. The core entry points are untouched.
+
+### `./splat/playcanvas` — new preview subpath: splats without Spark/three on the page
+
+- **`addSplat` from `@displayxr/inline3d/splat/playcanvas`** is `./splat`'s `addSplat` with the
+  engine fixed to `'playcanvas'`: same options, same synchronous handle. `./splat` imports `three`
+  and `@sparkjsdev/spark` statically (Spark is its default engine and its Spark path is
+  synchronous), so a page passing `engine: 'playcanvas'` there still downloaded both, measured at
+  ~1.7 MB gzipped on displayxr.org. This entry imports neither. `playcanvas` is still loaded on
+  demand, at the first `addSplat`. Passing any other `engine` throws at the call.
+- Internal: the deferred PlayCanvas handle moved from `inline3d-splat.js` to
+  `inline3d-splat-deferred.js`, shared by both entries. `./splat` behaves exactly as before.
+- `test/splat-pc-entry.test.mjs` walks the entry's static import graph and fails on any bare
+  package import, so the property can't silently regress.
+
+### `./camera` — new preview subpath (RFC 0003 §4)
+
+- **`openCamera(opts)`** → a `StereoCamera`: device selection (`prefer: 'auto' | 'stereo' | 'mono'
+  | deviceId | MediaStream`, the `displayxrStereo` hint, the > 2.5:1 pair heuristic, the
+  busy-device skip), `calibration` / `rectify` (moved here from `./call`), `format` / `stereo`
+  (`{ rectified, baselineMm, horizontalFovDeg }`) / `stream` / `video`, `on('ended')` (revoked,
+  unplugged, taken — never fired by `close()`), `close()`. Rejects only when no camera opens, with
+  `code` `'camera-busy'` | `'permission-denied'` (new: a refused prompt / policy / insecure
+  context) | `'no-camera'`.
+- **`addCameraView(wall, canvas, cam, { mirror, autoConverge, depth, aspect })`** — the self view:
+  woven on a 3D wall, flat elsewhere, mirrored **correctly** (each half mirrored AND the halves
+  swapped — pinned by a synthetic-pair test: a subject in front stays in front; the naive per-half
+  mirror is proven pseudoscopic). `autoConverge` runs the call's disparity tracker on the face.
+- **`cam.capturePhoto({ type, quality, name })`** → `{ blob, width, height, layout, convergencePx,
+  stereo, suggestedName: '<base>_2x1.jpg', xmp }`: the RAW pair, with the stereo record written
+  INTO the JPEG as XMP (`dxr:` namespace — layout, columns×rows, convergence, baseline, FOV,
+  rectified, eye size, software). **`cam.record({ mimeType, mono, audio })`** → `stop()` →
+  `{ blob, mono?, suggestedName: '<base>_2x1.webm', monoSuggestedName?, convergencePx, tagged }`,
+  the record as `DXR_*` Matroska tags; `mono: true` adds a left-eye copy (Decision 13). Readers:
+  `readJpegStereoMeta`, `readWebmStereoMeta`, `readJpegXmp`, `parseStereoXmp`. Decision 9: the
+  metadata lives in the file, no sidecar. `suggestedName`, `isStereoCamera`, `CAMERA_SDK`.
+- The call is built on it: `CallOptions.camera` accepts a `StereoCamera` (left open when the
+  call ends), `camera: 'auto'` opens one through `openCamera()`, and the call's self view IS an
+  `addCameraView` — one implementation of capture, mirroring and convergence. A camera that ends
+  under a call (`ended`) drops it to audio-only with "Retry camera".
+- Also in the CDN bundle `dist/call.js` (~153 KB min now, was ~124). `camera.d.ts`,
+  `docs/camera.md`, `samples/camera/`.
+
+### `./call` — the public surface (RFC 0003 §2)
+
+**Renamed / regrouped options** (the 1.29 spelling still works for this release with one
+`console.warn` per key; removed in 1.31):
+
+| 1.29 | 1.30 |
+|---|---|
+| `accent` | `theme.accent` |
+| `tileAspect` | `theme.tileAspect` |
+| `inviteBase`, `updateUrl` | `invite: { base, updateUrl }` |
+| `browserUrl` | `landing: { browserUrl, allow2D }` |
+| `maxLifted` | `liftOptions.max` |
+| `calibration`, `rectify` | `openCamera({ calibration, rectify })` of `./camera`, passed as `camera` |
+| `log` | `debug: true` + `diagnostics()` |
+| `recoverSession`, `wallOptions` | removed — a call always recovers the document's session (`sharedInline3D()`) |
+| `scrollIntoView` | removed — always on with `ui: true` |
+
+**New options:** `theme` (`accent`, `ink`, `shell`, `danger`, `radius`, `font`, `tileAspect`,
+`strings`) → CSS custom properties `--dxr-accent/-ink/-shell/-danger/-radius/-font` on the host
+and the string table; `ui: 'tiles'` (badges + plates only); `layout: 'none'` (tiles carry
+`data-dxr-peer`, `call.tile(id)` returns them, the grid box steps aside); `landing.allow2D`.
+`<dxr-call>` attributes are unchanged (`accent`, `tile-aspect`, `invite-base`, `browser-url` map
+to the new groups) plus `ui="tiles"`.
+
+**Handle renames:** `cameraOff(on)` → `setCameraOff(on)` with **`cameraOff` now the boolean
+getter**; `format` → `localFormat`; `join()` resolves `void`; **new** `tile(peerId)`,
+`diagnostics()` (explicitly unstable: the wall, the transport, per-peer `hello` / `route` /
+`convergencePx` / `autoConverge` / `lift` / `quality`, the lift pool). **Removed from the public
+handle** (kept as non-enumerable getters that warn once, gone in 1.31): `wall`, `format`,
+`sendHint`, `_debug`. `CallPeer` is trimmed to `id`, `format`, `display` (`'3D' | '2D→3D' |
+'2D'`), `state`, `muted`, `cameraOff`, `speaking`; the rest is in `diagnostics()`.
+`handle.state` no longer lists `'idle'`.
+
+**Events:** `format` → **`display`** `{ id, display }` (the old event still fires for a listener
+that subscribes to it, with a warning; gone in 1.31); `session` is internal (subscribing warns);
+`left` carries `reason`. New types `CallErrorCode` (adds `'permission-denied'`), `CallWarningCode`,
+`CallDisplay`, `CallTheme`, `CallStrings`, `LiftFunction`.
+
+**Removed from the `./call` entry — 38 internal helpers**, each kept for this release as a
+`@deprecated` wrapper that `console.warn`s once on first use (a primitive constant cannot warn)
+and removed in 1.31; all stay importable by file path from `js/call/*.js` / `js/camera/*.js`:
+`normalizeCallOptions`, `newRoomId`, `isValidRoomId`, `buildInviteLink`, `normalizeHello`,
+`makeHello`, `routeFor`, `badgeFor`, `createLiveGate`, `convergenceShiftPx`, `lowPass`,
+`clampShift`, `eyeCropRect`, `mirrorSwapOps`, `mirrorSwapPixels`, `maxBitrateKbps`,
+`measureFocusDisparity`, `preferVideoCodecs`, `sortCodecCapabilities`, `VIDEO_CODEC_ORDER`,
+`MeshTransport`, `clampMaxPeers`, `qrEncode`, `roomKey`, `SIGNAL_PROTOCOL`, `WIRE_VERSION`,
+`CALL_SDK`, `PLATE_TEXT` (→ `theme.strings`), `CALL_ACCENTS` (→ `theme.accent` takes the names),
+`normalizeMono3D`, `resolveLift`, `createLiftPool`, `createFrameWatch`, `liftConvergenceFor`,
+`liftPriorityFor`, `setLiftPriority`, `defaultLiftSpecifier`, `LIFT_PRIORITY`. Types gone with
+them: `CallHello`, `CallCalibration`, `CallRoute`, `Mono3DReason`, `CallMono3DInfo`,
+`CallLiftHandle`, `CallLiftFunction` (→ `LiftFunction`), `LiftStreamPriority`, `CallLiftPool`.
+**Stays public:** `mountCall`, `addCall`, `dxrSignaling`, `DXR_SIGNAL_DEFAULT`,
+`parseInviteLink` (Decision 7), `DxrCallElement`, `defineCallElement`, `attrsToOpts`,
+`CALL_EVENT_PREFIX` — 9 value exports (from 47).
+
+Internal moves (no API): `js/call/capture.js` → `js/camera/capture.js`, `js/call/disparity.js` →
+`js/camera/disparity.js`, the SBS geometry and convergence math → `js/camera/geometry.js` /
+`js/camera/converge.js`, option normalisation → `js/call/options.js`; the old paths re-export.
+
+### Gates (RFC 0003 §7, C2)
+
+- **API snapshot:** `tools/api-surface.mjs` pins the public surface of `call.d.ts`,
+  `call-full.d.ts` and `camera.d.ts` in `test/api-snapshot/*.api.txt`; `npm test` (and CI) fail
+  when the surface changes without `node tools/api-surface.mjs --update` in the same change. The
+  deprecated set is part of the record, so 1.31's removal is a visible diff.
+- **Snippets:** `tools/check-snippets.mjs` compiles every fenced `js`/`ts`/`jsx` block of
+  `docs/call.md` + `docs/camera.md` and every call/camera sample against the public `.d.ts` only
+  (and fails on a deprecated import); run by `npm test` where `typescript` is installed and by
+  CI's typecheck job.
+- **Tests:** camera unit tests (the mirror-and-swap proof, XMP/WebM round-trips, error codes,
+  view routes), the surface tests (deprecation wrappers, legacy options, handle renames, theme /
+  strings / parts / `ui: 'tiles'` / `layout: 'none'`), and a headless Chrome e2e
+  (`npm run test:e2e:camera`: the mirrored pair's pixels on a mock woven wall, a JPEG whose XMP
+  parses, a WebM whose tags parse). Panel runs still required: the mirrored self view on glass,
+  an SBS photo opened in `/player`.
+
+### `./call` + the hosted service (RFC 0003 §5, phase C3)
+
+Also in this release: the hosted signalling service productised, with the **reference server**
+(`signaling/`). Additive for pages; `dxr-signal/1` gains optional fields and new error codes only.
+
+- **Publishable keys.** `mountCall(el, { key: 'pk_…' })` / `<dxr-call key="pk_…">` now mean
+  something: the hosted server validates the key against its origin list on connect, applies the
+  keyed tier's limits (10× anonymous), and attributes every session to the key id (billing
+  identity from day one; billing is off). Issued by hand: `tools/signal-keys.mjs`. No key = the
+  anonymous tier, as before, with tighter limits.
+- **Limits** (RFC §5b): joins per address per minute, concurrent rooms per address / per key, room
+  lifetime (2 h / 8 h → `expired`), TURN mints per address per hour. A refused join is an `error`
+  with `rate-limited` (+ `error.retryMs`) / `quota` / `bad-key` / `origin-not-allowed` / `blocked`
+  — never a silent hang; reconnects honour `retryMs`.
+- **TURN metering and the monthly cap** (RFC §5c, Decision 2): the service meters minted
+  credentials (and, when configured, Cloudflare's real per-key relay bytes) against the free
+  1000 GB + a $100 hard cap. At 70 % anonymous credentials shorten, at 90 % anonymous sessions
+  get none (`warning` **`turn-shed`**), at 100 % nobody does (`error` **`turn-cap`**) — the call
+  still joins and direct P2P keeps working. `welcome.turn` / `SignalingSession.turn` carry the
+  decision (`SignalingTurnStatus`).
+- **Domain move prepared, not cut over** (RFC §5g): the hosted server answers on every host of
+  `DXR_SIGNAL_ALIASES` (`dxr-signal.displayxr.workers.dev`, `signal.displayxr.org`) and
+  `dxrSignaling()` fails over between them on connect and reconnect. `DXR_SIGNAL_DEFAULT` is
+  unchanged; the alias list is internal (`js/call/signaling.js`, importable by path — the
+  `./call` entry keeps its 9 exports). `dxrSignaling(url, { aliases })` adds fallbacks for a
+  self-hosted URL. Options and the recommendation: `docs/signaling-domain.md`.
+- **Docs:** `docs/privacy-call.md` (what the server sees, retention, the E2E caveat),
+  `signaling/README.md` (keys, limits, budget, self-host vars, a coturn recipe, staging),
+  `docs/call.md` troubleshooting rows for the new codes.
+- **Server:** `signaling/gate.mjs` + `limits.mjs` + `keys.mjs` + `turn-budget.mjs`, shared by
+  the Worker (Durable Objects per subject + one budget, a KV namespace for keys, an hourly
+  analytics cron, `/admin/*` behind `ADMIN_TOKEN`) and the Node dev server (same admission in
+  memory). Staging twin `signaling/deploy/staging.toml`; the C3 gate
+  `test/e2e/signal-staging.e2e.mjs`.
+
 ## 1.29.0 — 2026-09-30
 
 Touches the **core** (additive: `sharedInline3D()`, `handle.rewoven()`) and the **preview tier**

package/README.md

@@ -3,12 +3,12 @@
 Inline-3D **web samples** and a small JS SDK for the
 [DisplayXR Browser](https://github.com/DisplayXR/displayxr-browser) — the DisplayXR analog of
 [`immersive-web/webxr-samples`](https://github.com/immersive-web/webxr-samples). This is the canonical
-repo web developers clone to build glasses-free 3D pages, and the site the browser navigates to for the
+repo web developers clone to build 3D pages for spatial displays, and the site the browser navigates to for the
 live demos.
 
 **▶ See it live:** <https://displayxr.github.io/displayxr-web/> — open in the
-[DisplayXR Browser](https://github.com/DisplayXR/displayxr-browser/releases) on DisplayXR hardware for
-glasses-free 3D; in any other browser the pages render as a normal 2D fallback, so they're safe to view
+[DisplayXR Browser](https://github.com/DisplayXR/displayxr-browser/releases) on a spatial display to see
+them in 3D; in any other browser the pages render as a normal 2D fallback, so they're safe to view
 anywhere.
 
 ## Install
@@ -24,6 +24,8 @@ npm install @displayxr/inline3d
 import { createInline3D } from '@displayxr/inline3d';
 import { EyeCamera, EdgeFeather } from '@displayxr/inline3d/three'; // optional three.js glue
 import { addSplat } from '@displayxr/inline3d/splat';               // experimental: 3DGS in a tile
+//   …or '@displayxr/inline3d/splat/playcanvas': the same addSplat on PlayCanvas, without the
+//   three + Spark download (use it whenever you pass engine: 'playcanvas')
 import { addModel } from '@displayxr/inline3d/model';               // experimental: glTF/GLB in a tile
                                                                     //   (Draco / meshopt / KTX2 too —
                                                                     //    you serve the decoder files)
@@ -105,7 +107,7 @@ that is intentionally **not** in 1.0): [`docs/sdk-stability.md`](docs/sdk-stabil
 
 ## Quick start
 
-One SDK call turns a `<canvas>` into a glasses-free-3D window. Everything degrades to plain 2D on a
+One SDK call turns a `<canvas>` into a 3D window on a spatial display. Everything degrades to plain 2D on a
 non-DisplayXR browser, so a page is safe to ship anywhere.
 
 ```js
@@ -115,7 +117,7 @@ const wall = await createInline3D();       // opens an inline-3d session (detect
 if (!wall.supported) {
   // Not the DisplayXR Browser (or no 3D display) — your page's normal 2D content shows. Done.
 } else {
-  // Woven, glasses-free 3D. Add content — one call per element:
+  // Woven 3D. Add content — one call per element:
   wall.addImage(canvas, 'photo-sbs.png');                  // a still side-by-side 3D photo
   wall.addVideo(canvas, videoEl);                          // an SBS 3D video
   wall.addScene(canvas, (views, layer) => { /* render */ });// a live three.js / WebGL stereo scene
@@ -210,6 +212,8 @@ docs/
                            the WebXR→inline-3d mapping table and the whole render loop
   woven-canvas-rules.md    never show a raw side-by-side frame: the join, the rules,
                            handle.firstWoven / rewoven(), reading the browser's `withheld` log line
+  camera.md                The 3D camera primitive (/camera): openCamera, the mirrored self view,
+                           capturePhoto / record with the stereo record inside the file.
   call.md                  3D video calls: the <dxr-call> / mountCall() one-line embed, options,
                            events, headless, theming, React, self-hosting, troubleshooting
   proposals/               browser-side asks the SDK is waiting on