@displayxr/inline3d 1.30.0 → 1.31.0

package/index.d.ts

@@ -555,7 +555,63 @@ export interface CreateInline3DOptions {
    * `trackingstatechange` and do the same for a scene.
    */
   untrackedFallback?: 'none' | 'mono';
+  /**
+   * The TRACKING EASE, as the default for every SDK renderer drawing through this session
+   * (`./viewer`'s SceneViewer, `./splat` and `./model` on both engines). When a viewer is
+   * acquired — the views jump from the runtime's nominal viewer to the tracked eyes — or lost,
+   * the eye cameras glide from where they were drawn to the new views over `durationMs` instead
+   * of snapping in one frame; everything parented to the views (parallax, display-rig layers)
+   * follows. Triggered by a jump in the views around a `trackingState` edge (or, where the browser
+   * reports no state, by a large one-frame jump); a no-op when the vendor already animates the eyes. On by default; `false` restores
+   * the snap; a renderer's own `viewerEase` option overrides this. A page rendering its own
+   * `addScene` can use the exported {@link ViewerEase}.
+   */
+  viewerEase?: ViewerEaseOption;
+}
+
+/** `true`/unset = on with defaults, `false` = off, or tune it. */
+export type ViewerEaseOption =
+  | boolean
+  | {
+      /** Default true. */
+      enabled?: boolean;
+      /** The glide, in ms (default 300). 0 disables. */
+      durationMs?: number;
+      /** 'smoothstep' (default) | 'linear' | 'easeOutCubic'. */
+      easing?: 'smoothstep' | 'linear' | 'easeOutCubic' | string;
+    };
+
+/** One frame's matrices as an SDK renderer copies them out of an XRView (column-major). */
+export interface ViewerEaseEntry {
+  proj: Float32Array | Float64Array | number[];
+  pose: Float32Array | Float64Array | number[];
+}
+
+/**
+ * The tracking ease on its own, for a page that renders its own `addScene`: copy each view's
+ * `projectionMatrix` and `transform.matrix` into an entry, call `apply(entries,
+ * frame.session.trackingState)` once per LIVE frame, and render from the entries (keep using the
+ * real XRView for `layer.getViewport`). It rewrites the entries only while an ease is running.
+ */
+export declare class ViewerEase {
+  constructor(opts?: ViewerEaseOption & object);
+  readonly enabled: boolean;
+  readonly durationMs: number;
+  readonly easing: string;
+  /** Is an ease running right now? */
+  readonly active: boolean;
+  /** What the last apply() did: the weight of the old views (0 = passed through), the trigger, the jump (eye separations). */
+  readonly last: { weight: number; reason: null | 'armed-jump' | 'jump' | 'easing'; jump: number };
+  apply(entries: ViewerEaseEntry[], trackingState?: XRTrackingState | string | null, timeMs?: number): number;
+  configure(opts?: ViewerEaseOption): void;
+  /** Forget the previous frame (call after a resize or a view-count change you handle yourself). */
+  reset(): void;
 }
+export function resolveViewerEaseOption(opt?: ViewerEaseOption): { enabled: boolean; durationMs: number; easing: string };
+/** `frame.session.trackingState`, or null when the browser does not report one. */
+export function frameTrackingState(frame: unknown): XRTrackingState | null;
+/** 300. */
+export const VIEWER_EASE_DEFAULT_MS: number;
 
 /**
  * The eased 2D<->3D transition — on by default, and the same sequencer (and the same defaults)

package/js/call/signaling.js

@@ -53,6 +53,18 @@ export async function roomKey(room) {
  */
 export const DXR_SIGNAL_DEFAULT = 'wss://dxr-signal.displayxr.workers.dev';
 
+/**
+ * Every host the hosted server answers on. The SAME Worker serves all of them (rooms are shared),
+ * so the adapter fails over between them when one cannot be reached: the first entry is tried
+ * first. `signal.displayxr.org` is the target of the domain move (RFC 0003 §5g); the workers.dev
+ * host stays an alias through the transition. Only applies to the hosted default — a self-hosted
+ * URL is tried as given (pass `aliases` to add your own fallbacks).
+ */
+export const DXR_SIGNAL_ALIASES = Object.freeze([DXR_SIGNAL_DEFAULT, 'wss://signal.displayxr.org']);
+
+/** Join-time error codes from the server that mean "do not retry with the same inputs". */
+const FATAL_JOIN_CODES = ['bad-room', 'bad-id', 'bad-version', 'bad-key', 'origin-not-allowed', 'blocked'];
+
 export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
   if (!url || typeof url !== 'string') {
     throw codedError(
@@ -60,16 +72,21 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
       'dxrSignaling(url): url must be a ws:// or wss:// string (omit it for the hosted DisplayXR server)'
     );
   }
-  const base = url.replace(/\/+$/, '');
+  const strip = (u) => String(u).replace(/\/+$/, '');
+  const base = strip(url);
   const WS = opts.WebSocket || globalThis.WebSocket;
   const pingMs = opts.pingMs || 20000;
+  const extra = Array.isArray(opts.aliases) ? opts.aliases.filter((a) => typeof a === 'string' && a).map(strip) : DXR_SIGNAL_ALIASES.includes(base) ? [...DXR_SIGNAL_ALIASES] : [];
+  const bases = [base, ...extra.filter((b) => b !== base)];
+  let baseIdx = 0;
 
   return {
     name: 'dxr',
     url: base,
     async join(room, hooks) {
       const key = await roomKey(room);
-      const endpoint = `${base}/v1/connect?k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
+      const query = `k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
+      const endpointAt = (i) => `${bases[i]}/v1/connect?${query}`;
       let ws = null;
       let left = false;
       let attempt = 0;
@@ -77,11 +94,15 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
       let known = new Set();
       let queue = [];
 
-      const open = (isReconnect) =>
+      // One open() tries every alias once (in order from the last one that worked) before it
+      // reports `signaling-unreachable`; a host that cannot be reached is skipped, not waited on.
+      const open = (isReconnect) => openAt(isReconnect, bases.length);
+      const openAt = (isReconnect, triesLeft) =>
         new Promise((resolve, reject) => {
           let settled = false;
           let joined = false;
-          const sock = new WS(endpoint);
+          let opened = false;
+          const sock = new WS(endpointAt(baseIdx));
           ws = sock;
           const fail = (err) => {
             if (!settled) {
@@ -95,6 +116,7 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
             }
           };
           sock.onopen = () => {
+            opened = true;
             sock.send(JSON.stringify({ t: 'join', v: 1, room, id: hooks.id, max: hooks.maxPeers }));
           };
           sock.onmessage = (ev) => {
@@ -121,17 +143,42 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
                 } else known = new Set(peers);
                 settled = true;
                 joined = true;
-                resolve({ id: msg.id, peers, iceServers: Array.isArray(msg.iceServers) ? msg.iceServers : undefined, max: msg.max });
+                resolve({
+                  id: msg.id,
+                  peers,
+                  iceServers: Array.isArray(msg.iceServers) ? msg.iceServers : undefined,
+                  max: msg.max,
+                  // Hosted-service fields (RFC 0003 §5): the tier this session was admitted as,
+                  // its key id, and the TURN decision — `turn.reason === 'cap'` is the SDK's
+                  // `turn-cap`. A server that predates them sends none; nothing here is required.
+                  tier: msg.tier === 'key' ? 'key' : 'anon',
+                  key: typeof msg.key === 'string' ? msg.key : undefined,
+                  turn: msg.turn && typeof msg.turn === 'object' ? msg.turn : undefined,
+                });
                 break;
               }
               case 'full':
                 left = true;
                 fail(codedError('room-full', `this call is full (${msg.max} participants)`));
                 break;
+              case 'expired': {
+                // The room's lifetime is up (hosted limits): no reconnect — the call reports it.
+                left = true;
+                clearInterval(pingTimer);
+                const e = codedError('expired', 'this room has reached its lifetime on the signalling server');
+                if (!settled) fail(e);
+                else hooks.onDisconnect?.(e);
+                break;
+              }
               case 'error':
-                if (!settled && ['bad-room', 'bad-id', 'bad-version'].includes(msg.code)) {
+                if (!settled && FATAL_JOIN_CODES.includes(msg.code)) {
                   left = true;
                   fail(codedError(msg.code, msg.message || msg.code));
+                } else if (!settled && (msg.code === 'rate-limited' || msg.code === 'quota')) {
+                  // Refused by a limit, not by the inputs: a reconnect may retry after `retryMs`.
+                  const e = codedError(msg.code, msg.message || msg.code);
+                  /** @type {any} */ (e).retryMs = msg.retryMs > 0 ? msg.retryMs : 0;
+                  fail(e);
                 } else if (!settled && msg.code === 'id-taken') {
                   // A reconnect raced the server noticing the old socket close: retry shortly.
                   fail(codedError('id-taken', 'peer id still held; retrying'));
@@ -154,7 +201,16 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
                 break;
             }
           };
-          sock.onerror = () => fail(codedError('signaling-unreachable', `cannot reach ${base}`));
+          sock.onerror = () => {
+            if (!opened && !settled && triesLeft > 1) {
+              // This host is unreachable: fail over to the next alias right away.
+              settled = true;
+              baseIdx = (baseIdx + 1) % bases.length;
+              openAt(isReconnect, triesLeft - 1).then(resolve, reject);
+              return;
+            }
+            fail(codedError('signaling-unreachable', `cannot reach ${bases[baseIdx]}`));
+          };
           sock.onclose = () => {
             clearInterval(pingTimer);
             fail(codedError('signaling-closed', 'signalling closed before joining'));
@@ -172,11 +228,12 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
         const tryAgain = () => {
           if (left) return;
           open(true).catch((err) => {
-            if (left || (err && err.code === 'room-full')) {
+            if (left || (err && (err.code === 'room-full' || FATAL_JOIN_CODES.includes(err.code)))) {
               hooks.onDisconnect?.(err);
               return;
             }
-            setTimeout(tryAgain, backoffMs(attempt++, { baseMs: 500, maxMs: 15000 }));
+            // A `rate-limited` / `quota` refusal says when to come back; never sooner.
+            setTimeout(tryAgain, Math.max(backoffMs(attempt++, { baseMs: 500, maxMs: 15000 }), (err && err.retryMs) || 0));
           });
         };
         setTimeout(tryAgain, backoffMs(attempt++, { baseMs: 300, maxMs: 15000 }));

package/js/inline3d-call.js

@@ -362,8 +362,9 @@ class Call {
       log: (tag, obj) => this.log(tag, obj),
     });
     this.transport = t;
+    let session = null;
     try {
-      await t.start({
+      session = await t.start({
         room: this.room,
         localStream: this.local.stream,
         sendFormat: this.local.format,
@@ -410,9 +411,38 @@ class Call {
     globalThis.addEventListener?.('pagehide', this._pagehide);
     this.log('joined', { id: this.id, peers: this.tiles.size });
     this.emit('joined', { room: this.room, id: this.id });
+    // The TURN decision is reported on the next task, after join() / mountCall() have resolved:
+    // a page (or <dxr-call>) subscribes once it has the handle, and an event raised mid-join
+    // would reach nobody.
+    setTimeout(() => {
+      if (this.transport === t) this._reportTurn(session);
+    }, 0);
     return this.handle;
   }
 
+  /**
+   * The signalling server's TURN decision for this session (hosted service, RFC 0003 §5c), once
+   * per join. `turn-cap` (an `error`): the service's monthly relay budget is spent, nobody gets
+   * TURN — direct connections still work. `turn-shed` (a `warning`): only THIS session has no
+   * TURN (an anonymous session near the budget, or too many credential requests from this
+   * address). A server with no TURN at all (self-hosted) says nothing here: that is a setup
+   * choice, documented in docs/call.md.
+   */
+  _reportTurn(session) {
+    const turn = session && session.turn;
+    if (!turn || typeof turn !== 'object') return;
+    if (turn.status === 'off' && turn.reason === 'cap') {
+      this.error('turn-cap', 'relay (TURN) capacity for this month is used up; direct connections still work, but a participant behind a strict NAT may be unreachable', null);
+    } else if (turn.reason === 'budget' || turn.reason === 'rate') {
+      this.warning(
+        'turn-shed',
+        turn.reason === 'rate'
+          ? 'no relay (TURN) for this session: too many credential requests from this address this hour'
+          : 'no relay (TURN) for this anonymous session: the hosted service is near its monthly relay budget (a publishable key keeps TURN)'
+      );
+    }
+  }
+
   _onPeer(id) {
     if (this.tiles.has(id)) return;
     const tile = new Tile(this, id);

package/js/inline3d-model-playcanvas.js

@@ -464,6 +464,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     nearClip: opts.nearClip,
     farClip: opts.farClip,
     sky: false,
+    viewerEase: opts.viewerEase,
     // Each environment's own look: 'room' is three's (untonemapped), the rest the Sample Viewer's.
     toneMapping: envMap ? 'neutral' : ENVIRONMENT_TONE_MAPPING[environment] || 'neutral',
   });

package/js/inline3d-model.js

@@ -380,6 +380,7 @@ export function addModel(wall, canvas, src, opts = {}) {
     renderScale,
     feather,
     logTag: '[inline3d/model]',
+    viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   if (envMap) viewer.scene.environment = envMap;

package/js/inline3d-splat-playcanvas.js

@@ -67,6 +67,7 @@ import {
   sequenceSpans,
 } from './inline3d-splat-effects.js';
 import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
+import { viewerEaseFor, frameTrackingState } from './inline3d-viewer-ease.js';
 import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR, eyeSplit, EYE_SPLIT_UNIFORM, makeSbsMaterial } from './inline3d-splat-video.js';
 import { LayerRigCameras, validateLayerRig, validateLayerRigOptions, DEFAULT_VIEWER_DISTANCE_M } from './inline3d-splat-layer-rig.js';
 import { RigTracker, remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
@@ -817,8 +818,13 @@ export class PlayCanvasSplatViewer {
       sky = false,
       pageCamera = false,
       toneMapping = 'none',
+      viewerEase,
     } = opts;
     this.canvas = canvas;
+    // The tracking-acquisition ease (./inline3d-viewer-ease.js): undefined = the session's
+    // createInline3D({ viewerEase }) default. Built on the first 3D frame, which knows the session.
+    this._viewerEaseOpt = viewerEase;
+    this.viewerEase = null;
     // controls:'page': the PAGE owns the camera (setPageCamera). No orbit, no idle, no fit; the
     // rig node carries the page's matrix instead of the inverse pivot.
     this.pageCamera = pageCamera === true;
@@ -1194,7 +1200,7 @@ export class PlayCanvasSplatViewer {
   }
 
   /** wall.addScene's frame callback. Validate BEFORE drawing; replay the last good frame else. */
-  onFrame(views, layer) {
+  onFrame(views, layer, frame) {
     if (this._disposed) return;
     if (this._mode !== '3d') this.stopMono();
     // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
@@ -1224,6 +1230,9 @@ export class PlayCanvasSplatViewer {
       vps.push(vp);
     }
     this._cacheGood(views, vps);
+    // Ease a tracking acquisition/loss on the copies (never the XRViews), before anything —
+    // the rig map, the layer rig, the live outgoing photo — reads them.
+    (this.viewerEase ||= viewerEaseFor(frame, this._viewerEaseOpt)).apply(this._lastGood.entries, frameTrackingState(frame));
     this._drawEntries(this._lastGood.entries, this._lastGood);
   }
 
@@ -2139,6 +2148,7 @@ export class PlayCanvasSplatViewer {
     if (this._disposed) return;
     const box = this.canvas.getBoundingClientRect();
     if (box.width < 1 || box.height < 1) return;
+    this.viewerEase?.reset(); // a new window size moves every projection: not a viewer jump
     const dpr = Math.min((typeof window !== 'undefined' && window.devicePixelRatio) || 1, 2) * this.renderScale;
     // Clamp to the device's GL limits BEFORE sizing (./inline3d-buffer-limit.js). Measured on an
     // Adreno 740 tablet: MAX_TEXTURE_SIZE 4096, a 5120-wide request silently became a 4096-wide
@@ -3072,6 +3082,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     nearClip: opts.nearClip,
     farClip: opts.farClip,
     sky: opts.sky,
+    viewerEase: opts.viewerEase,
   });
 
   let handle = null;
@@ -3394,9 +3405,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let initialViewRig = null; // the rig addScene is created with (controls:'page'), else the shorthand
   if (wall && wall.supported) {
     const onFrame = diag
-      ? (views, layer) => {
+      ? (views, layer, frame) => {
           const t = performance.now();
-          viewer.onFrame(views, layer);
+          viewer.onFrame(views, layer, frame);
           diag.frame(views, t); // after the draw: the overlay state is what this frame showed
         }
       : viewer.onFrame;

package/js/inline3d-splat.js

@@ -246,6 +246,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
     renderScale,
     feather,
     logTag: '[inline3d/splat]',
+    viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   // Spark renders through the ordinary three.js pipeline, so splats and meshes co-exist and