@displayxr/inline3d 1.30.0 → 1.32.0

package/CHANGELOG.md

@@ -5,6 +5,83 @@ 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.32.0 — 2026-10-06
+
+Touches the **core** additively (one new handle method, two new exports) and the **preview tier**
+(`./splat`, PlayCanvas backend).
+
+
+### Hosted signalling server (`signaling/`, not part of the npm package)
+
+- **`welcome` is now always the first message a joined peer receives.** With a real TURN key the
+  server awaits a credential mint between reserving a peer's slot and welcoming it; another peer
+  joining or signalling in that window used to reach the first peer *before* its own welcome, and
+  that welcome's `peers` then omitted the newcomer. Messages addressed to a not-yet-welcomed peer
+  are now held and flushed behind its welcome, and the roster is read when the welcome is sent. The
+  SDK was already tolerant of the old order (its transport replays early `peer-joined`s); raw
+  `dxr-signal/1` clients were not. No protocol field changed.
+
+### Core — `handle.displayMetrics()`
+
+- **`handle.displayMetrics()`** → `{ canvasSizeM, metersPerCssPx, displaySizeM, nominalViewerM,
+  eyeSeparationM, source }`: the tile in physical units, derived from `getDisplayInfo()` (panel
+  pitch × `devicePixelRatio` × the canvas's CSS box). Never rejects. Anything the display can't
+  report comes from `DISPLAY_METRICS_DEFAULTS` and is flagged in `source`. **Eye separation is
+  always the 63 mm default**, because no browser or runtime surface reports one. Also exported as
+  the pure `displayMetricsFrom(info, rect, dpr)`.
+
+### `./splat` (PlayCanvas backend)
+
+- **`handle.setStereo({ ipdFactor, parallaxFactor })`**: live stereo strength. It re-declares the
+  rig in force on the next frame with no cut (pose, focus and framing kept). Keys merge, a `null`
+  key returns to the asset's own value, and `setStereo(null)` clears both. Sticky across
+  `setSource` / `setRig`. `handle.rig.stereoDefault` holds the asset's own values.
+  docs/playcanvas-adapter.md §setStereo.
+- **`handle.setDepthEnvelope({ maxFrontM, edgeM, bandM, stage, rects, viewerM, canvasSizeM })`**:
+  the frame envelope. Content may come out of the glass only well inside the frame and away from 2D
+  elements. Gaussians past the cap slide back along their own rays from the declared camera rig,
+  so the picture, the sort order and the stereo rule all hold. It is tile-wide and keyed on the
+  live declared rig (convergence, lens, `ipdFactor × metersToVirtual`), so every asset is covered
+  from its first frame, through crossfades and through `setStereo`, with no per-asset install.
+  Camera rigs only. docs/splat-effects.md §Depth envelope.
+- `setStereo({ ipdScale, parallaxScale })`: the same scalars RELATIVE to each asset's own
+  (`rig.stereoDefault`), re-applied to every asset `setSource` brings in. Per scalar, the absolute
+  and relative keys are exclusive; the last one given wins.
+- **`splatHandle.displayMetrics()`**: the core tile's `displayMetrics()`, on the splat handle.
+- The deferred PlayCanvas handle (what `addSplat` returns before the engine module loads) now has
+  `setStereo`, `setDepthEnvelope` and `displayMetrics`. A call right after `addSplat` was
+  `not a function`. A test now pins this.
+- `STAGE_ORDER` gains `'envelope'` (between `custom` and `cull`), so a page's custom effect runs
+  before the cap.
+
+## 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
@@ -129,6 +206,41 @@ Internal moves (no API): `js/call/capture.js` → `js/camera/capture.js`, `js/ca
   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
@@ -107,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
@@ -117,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

package/call.d.ts

@@ -60,19 +60,51 @@ export interface SignalingSession {
   peers: string[];
   /** Short-lived TURN credentials minted by the server, if it has any. */
   iceServers?: RTCIceServer[];
+  /** Hosted service (RFC 0003 §5): the tier this session was admitted as. */
+  tier?: 'anon' | 'key';
+  /** Hosted service: the publishable key id this session is attributed to. */
+  key?: string;
+  /** Hosted service: why `iceServers` is (or is not) there — see {@link SignalingTurnStatus}. */
+  turn?: SignalingTurnStatus;
   send(to: string, data: unknown): void;
   leave(): void;
 }
 
 /** The hosted DisplayXR signalling server (`dxrSignaling()` with no URL). */
 export const DXR_SIGNAL_DEFAULT: string;
+/**
+ * The server's TURN decision for one session (`welcome.turn`, `dxr-signal/1`). `status` is the
+ * service-wide state of the monthly relay budget (`ok` / `degraded` / `off`); `reason` says why
+ * THIS session got no credentials: `unconfigured` (the server has no TURN — self-hosted), `budget`
+ * (anonymous session shed near the budget → `warning` `turn-shed`), `rate` (too many mints from
+ * this address → `turn-shed`), `cap` (the monthly cap → `error` `turn-cap`), `mint-failed`.
+ */
+export interface SignalingTurnStatus {
+  status: 'ok' | 'degraded' | 'off';
+  reason?: 'unconfigured' | 'budget' | 'cap' | 'rate' | 'mint-failed';
+  /** Credential lifetime, seconds, when minted. */
+  ttl?: number;
+}
+
 /**
  * The `dxr-signal/1` JSON-over-WebSocket client (protocol: signaling/README.md). `url` is your
  * server's base, e.g. `wss://signal.example.com` or `ws://localhost:8787` — the reference servers
  * are `signaling/worker.mjs` (Cloudflare) and `node signaling/dev-server.mjs`. No URL = the hosted
  * server. `key`: a publishable key for the hosted service (public by design; sent on connect).
+ * The hosted server answers on more than one host (RFC 0003 §5g) and the adapter fails over
+ * between them on connect and reconnect by itself; `aliases` adds fallbacks for a self-hosted URL.
  */
-export function dxrSignaling(url?: string, opts?: { WebSocket?: any; pingMs?: number; key?: string }): SignalingAdapter;
+export function dxrSignaling(
+  url?: string,
+  opts?: {
+    WebSocket?: any;
+    pingMs?: number;
+    /** A publishable key for the hosted service (public by design; sent on connect). */
+    key?: string;
+    /** Extra base URLs to fail over to when `url` is unreachable (the hosted default has its own). */
+    aliases?: string[];
+  }
+): SignalingAdapter;
 
 /** The eight named accents `theme.accent` takes (the same names `/player` uses). */
 export type CallAccent = 'azure' | 'violet' | 'magenta' | 'sunset' | 'amber' | 'lime' | 'mint' | 'ice';
@@ -248,7 +280,13 @@ export interface CallPeer {
  * `error` codes — fatal for a feature, never for the widget. `'camera-busy'` (held by another
  * app: audio-only until `retryCamera()`), `'no-camera'`, `'permission-denied'`, `'unreachable'`
  * (`error.peer` = the tile), `'room-full'`, `'session-ended'`, `'signaling-closed'`,
- * `'join-failed'`, `'camera-failed'`, `'rectify-failed'`, `'mount-failed'` (the element).
+ * `'signaling-unreachable'`, `'join-failed'`, `'camera-failed'`, `'rectify-failed'`,
+ * `'mount-failed'` (the element). From the hosted signalling service (RFC 0003 §5, C3):
+ * `'rate-limited'` / `'quota'` (a limit of the anonymous or keyed tier — the join is refused;
+ * `error.retryMs` says when a retry may work), `'bad-key'` / `'origin-not-allowed'` (the
+ * publishable key is unknown, revoked, or not allowed from this page's origin), `'blocked'`,
+ * `'expired'` (the room's lifetime is up), and `'turn-cap'` (the service's monthly relay budget
+ * is spent: the call still joins and direct connections work, but nobody gets TURN — not fatal).
  */
 export type CallErrorCode =
   | 'camera-busy'
@@ -262,11 +300,19 @@ export type CallErrorCode =
   | 'camera-failed'
   | 'rectify-failed'
   | 'mount-failed'
-  // Hosted-service codes (RFC 0003 §5, phase C3) are added here by the service work.
+  | 'signaling-unreachable'
+  // Hosted signalling service (RFC 0003 §5, C3).
+  | 'rate-limited'
+  | 'quota'
+  | 'bad-key'
+  | 'origin-not-allowed'
+  | 'blocked'
+  | 'expired'
+  | 'turn-cap'
   | (string & {});
 
 /** `warning` codes — degraded, not broken. */
-export type CallWarningCode = 'lift-not-bundled' | (string & {});
+export type CallWarningCode = 'lift-not-bundled' | 'turn-shed' | (string & {});
 
 export interface CallEvents {
   joined: { room: string; id: string };
@@ -289,6 +335,9 @@ export interface CallEvents {
    * module could not be imported from this build — they stay flat. Fix: `mono3D: lift` or
    * `./call/full`. Emitted once per call with one `console.warn`. A display that honestly cannot
    * lift is NOT this: that is `handle.mono3D.reason` (`'no-provider'` / `'no-webgpu'`).
+   * `'turn-shed'`: only THIS session got no TURN from the hosted service (an anonymous session
+   * while the monthly relay budget is nearly spent, or too many credential requests from this
+   * address this hour); the call runs STUN-only. A publishable key keeps TURN.
    */
   warning: { code: CallWarningCode; message: string };
 }