@displayxr/inline3d 1.33.1 → 1.35.0

package/js/inline3d-call.js

@@ -1127,6 +1127,9 @@ class Call {
       hello: this.hello(),
       transport: this.transport,
       peers: [...this.tiles.values()].map((tile) => tile.diag()),
+      // The self view's ACTUAL weave state (web#131): route, woven, the fallback reason and the
+      // tile's firstWoven result — null without a self view.
+      self: this.self ? this.self.diag() : null,
       mono3D: { ...this._mono3DInfo(), lift: this.liftApi, pool: this.liftPool ? this.liftPool.list() : [] },
       speaker: this.speakerId,
       depth: this.depth,
@@ -1866,14 +1869,34 @@ class SelfTile {
     else {
       this.detach();
       this.cam = cam;
-      this.view = addCameraView(wall, this.canvas, cam, { mirror: true, autoConverge: false, aspect: this.call.o.tileAspect });
+      // onRouteChange: the view drops to its flat left eye by itself when the wall says the tile
+      // will not weave (firstWoven → woven:false, web#131), and the badge must follow it.
+      this.view = addCameraView(wall, this.canvas, cam, {
+        mirror: true,
+        autoConverge: false,
+        aspect: this.call.o.tileAspect,
+        onRouteChange: (route, st) => {
+          if (this.cam !== cam) return; // a view this tile already replaced
+          this.call.log('self-route', { route, woven: st.woven, reason: st.reason });
+          this._badge();
+        },
+      });
     }
     this._badge();
   }
 
+  /** 3D only while the view is on the woven route — a layer the wall failed has already taken it flat. */
   _badge() {
     const t = this.call.t;
-    this.badge.replaceChildren(el('b', { text: `${t('you')} · ${this.route === 'woven-sbs' ? t('badge3D') : t('badge2D')}` }));
+    const woven = !!(this.view && this.view.woven);
+    this.badge.replaceChildren(el('b', { text: `${t('you')} · ${woven ? t('badge3D') : t('badge2D')}` }));
+    this.badge.dataset.route = this.route || '';
+  }
+
+  /** For `call.diagnostics().self`: what the self view actually shows. */
+  diag() {
+    if (!this.view) return { route: null, woven: false, reason: 'no-camera', firstWoven: null, layerRetries: 0 };
+    return this.view.weaveState();
   }
 
   onWallLost() {

package/js/inline3d-camera.js

@@ -51,6 +51,11 @@ export const CAMERA_SDK = 'inline3d-camera/1';
 const AUTO_CONV_INTERVAL_MS = 200;
 const AUTO_CONV_EYE_WIDTH = 240;
 const FRAME_WAIT_MS = 4000;
+// A self view whose layer the wall could not build (`firstWoven` → `woven:false, 'layer-failed'`)
+// goes flat and re-registers a few times with backoff — the remote tile's rule (web#131).
+const LAYER_RETRIES = 4;
+const LAYER_RETRY_BASE_MS = 1500;
+const LAYER_RETRY_MAX_MS = 20000;
 const RECORD_MIME_CANDIDATES = ['video/webm;codecs=vp9', 'video/webm;codecs=vp8', 'video/webm', 'video/mp4'];
 
 const hasDoc = () => typeof document !== 'undefined' && document && typeof document.createElement === 'function';
@@ -471,7 +476,12 @@ function sizeFlat(canvas) {
  * @param {object|null} wall  a `createInline3D()` / `sharedInline3D()` result (may be unsupported) or null
  * @param {HTMLCanvasElement} canvas  the tile — its CSS box is the shape the viewer sees
  * @param {StereoCamera} cam
- * @param {{ mirror?: boolean, autoConverge?: boolean, depth?: number, aspect?: number }} [opts]
+ * On a 3D wall the view follows its tile's `firstWoven`: a window the wall will not weave
+ * (`'layer-failed'`, `'session-ended'`) drops the view to the flat left eye — never the packed
+ * pair — with `fallbackReason` saying why, and `onRouteChange(route, state)` tells the page (a
+ * badge reads `route`). A refused layer is retried a few times; `_reroute(true, wall)` recovers.
+ *
+ * @param {{ mirror?: boolean, autoConverge?: boolean, depth?: number, aspect?: number, onRouteChange?: Function }} [opts]
  */
 export function addCameraView(wall, canvas, cam, opts = {}) {
   if (!canvas || typeof canvas.getContext !== 'function') throw new TypeError(`${TAG} addCameraView(wall, canvas, cam, opts) needs a canvas`);
@@ -494,6 +504,15 @@ class CameraView {
     this.setDepth(o.depth);
     this.route = null;
     this.handle = null;
+    // Why a pair on a 3D-capable wall is shown FLAT (web#131): the wall said this tile's window
+    // will not weave (`firstWoven` → woven:false — 'layer-failed', 'session-ended'). Null while
+    // nothing has failed. A packed pair is never the visible fallback: the view paints one eye.
+    this.fallbackReason = null;
+    // The current registration's settled `firstWoven`, null while pending / not registered.
+    this._fw = null;
+    this._onRouteChange = typeof o.onRouteChange === 'function' ? o.onRouteChange : null;
+    this._layerFails = 0;
+    this._layerTimer = 0;
     this.buffer = null; // the SBS canvas the wall repaints the tile from (woven route)
     this.removed = false;
     this._raf = 0;
@@ -507,11 +526,30 @@ class CameraView {
     if (this._loop) this._start();
   }
 
-  /** `'woven-sbs'` (3D on the panel) | `'flat-left'` (a pair, shown flat) | `'flat'` (mono). */
+  /**
+   * True while the view is on the woven route: registered on a 3D wall, and the wall has not said
+   * the tile will not weave (a failed layer drops the view to `'flat-left'`). Route is
+   * `'woven-sbs'` (3D on the panel) | `'flat-left'` (a pair, shown flat) | `'flat'` (mono).
+   */
   get woven() {
     return this.route === 'woven-sbs';
   }
 
+  /**
+   * What is actually on the panel, for diagnostics: `{ route, woven, reason, firstWoven,
+   * layerRetries }`. `firstWoven` is the current registration's settled result, `'pending'`
+   * before it settles, null off the woven route.
+   */
+  weaveState() {
+    return {
+      route: this.route,
+      woven: this.woven,
+      reason: this.fallbackReason,
+      firstWoven: this.route === 'woven-sbs' ? (this._fw ? { ...this._fw } : 'pending') : null,
+      layerRetries: this._layerFails,
+    };
+  }
+
   /** The per-eye convergence shift currently painted, source px. */
   get convergencePx() {
     return this.conv.current;
@@ -543,20 +581,77 @@ class CameraView {
     return this.autoConverge;
   }
 
-  /** Re-register on the wall (the call does this when the weave goes live, #172, or a session is recovered). */
+  /**
+   * Re-register on the wall (the call does this when the weave goes live, #172, or a session is
+   * recovered). A FORCED reroute also clears a layer fallback (web#131): a wall that came back
+   * gets a fresh registration. An unforced one keeps the view flat while a fallback stands.
+   */
   _reroute(force, wall) {
     if (wall !== undefined) this.wall = wall;
     if (this.removed) return;
+    if (force && this.fallbackReason) {
+      this.fallbackReason = null;
+      clearTimeout(this._layerTimer);
+      this._layerTimer = 0;
+    }
     const cam = this.cam;
     const live = cam.state === 'live' && cam.video;
-    const route = cam.format === 'sbs' && live && this.wall && this.wall.supported ? 'woven-sbs' : cam.format === 'sbs' ? 'flat-left' : 'flat';
+    const wovenOk = cam.format === 'sbs' && live && this.wall && this.wall.supported && !this.fallbackReason;
+    const route = wovenOk ? 'woven-sbs' : cam.format === 'sbs' ? 'flat-left' : 'flat';
     if (!force && route === this.route) return;
+    const prev = this.route;
     this._unregister();
     this.route = route;
-    if (route === 'woven-sbs') {
-      if (!this.buffer) this.buffer = document.createElement('canvas');
-      this._paintWoven(); // the first frame exists before the layer does
-      this.handle = this.wall.addImage(this.canvas, this.buffer);
+    if (route === 'woven-sbs') this._registerWoven();
+    if (route !== prev) this._routeChanged();
+  }
+
+  _registerWoven() {
+    if (!this.buffer) this.buffer = document.createElement('canvas');
+    this._paintWoven(); // the first frame exists before the layer does
+    const handle = this.wall.addImage(this.canvas, this.buffer);
+    this.handle = handle;
+    this._fw = null;
+    const fw = handle && handle.firstWoven;
+    if (!fw || typeof fw.then !== 'function') return;
+    fw.then((res) => {
+      // A result for a registration we already left (removed, re-registered) says nothing now.
+      if (this.handle !== handle || this.removed || !res) return;
+      this._fw = { woven: !!res.woven, confirmed: !!res.confirmed, reason: res.reason || null, ms: res.ms };
+      this.cam.log?.('view-first-woven', { woven: !!res.woven, reason: res.reason || null });
+      if (res.woven) {
+        this._layerFails = 0;
+        this._routeChanged(); // the state settled; the route did not move
+      } else if (res.reason !== 'removed') this._layerLost(res.reason || 'layer-failed');
+    });
+  }
+
+  /**
+   * The wall said this window will not weave (web#131): the canvas must never be left showing the
+   * packed pair under a 3D badge. Go flat (one eye, mirrored) and say why. A layer the browser
+   * refused is retried a few times with backoff while the wall stays up (the remote tile's rule);
+   * a session that ended waits for `_reroute(true, wall)` with the new wall.
+   */
+  _layerLost(reason) {
+    this.fallbackReason = reason;
+    this._reroute(false);
+    if (reason !== 'layer-failed' || this._layerFails >= LAYER_RETRIES) return;
+    const delay = Math.min(LAYER_RETRY_MAX_MS, LAYER_RETRY_BASE_MS * Math.pow(2, this._layerFails++));
+    this.cam.log?.('view-layer-retry', { attempt: this._layerFails, inMs: delay });
+    clearTimeout(this._layerTimer);
+    this._layerTimer = setTimeout(() => {
+      this._layerTimer = 0;
+      if (this.removed || this.fallbackReason !== reason) return;
+      this._reroute(true);
+    }, delay);
+  }
+
+  _routeChanged() {
+    if (!this._onRouteChange) return;
+    try {
+      this._onRouteChange(this.route, this.weaveState());
+    } catch (err) {
+      console.error(`${TAG} onRouteChange threw`, err);
     }
   }
 
@@ -672,6 +767,8 @@ class CameraView {
     this.removed = true;
     if (this._raf) cancelAnimationFrame(this._raf);
     this._raf = 0;
+    clearTimeout(this._layerTimer);
+    this._layerTimer = 0;
     this._unregister();
     this.cam._views?.delete(this);
   }

package/js/inline3d-model-entry.js

@@ -54,7 +54,7 @@ export function resolveModelEngine(opts = {}) {
 }
 
 /** 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', 'zoom'];
+const PLAYCANVAS_ONLY = ['playcanvas', 'environmentRotation', 'controls', 'comfortDepth', 'onBeforeFrame', 'antialias', 'preserveDrawingBuffer', 'nearClip', 'farClip', 'orbitMaxDeg', 'orbitEase', 'orbitStyle', 'zoom'];
 
 /**
  * Everything that can be checked before a module loads. Throws at CALL time — a page bug is true
@@ -67,6 +67,9 @@ export function validateModelCall(canvas, src, opts, route) {
   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 (opts.orbitStyle !== undefined && opts.orbitStyle !== 'turntable' && opts.orbitStyle !== 'tilt') {
+    throw new Error(`@displayxr/inline3d/model: orbitStyle must be 'turntable' or 'tilt' (got ${String(opts.orbitStyle)}).`);
+  }
   if (route.engine === 'three' && route.explicit) {
     const bad = PLAYCANVAS_ONLY.filter((k) => opts[k] !== undefined && !(k === 'controls' && opts[k] === 'viewer'));
     if (bad.length) {

package/js/inline3d-model-playcanvas.js

@@ -459,6 +459,8 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     flipY: false, // glTF is already Y-up
     orbitMaxDeg: opts.orbitMaxDeg,
     orbitEase: opts.orbitEase,
+    // A mesh turns all the way round, like the three path's SceneViewer: not the photo tilt.
+    orbitStyle: opts.orbitStyle ?? 'turntable',
     zoom: opts.zoom,
     feather,
     nearClip: opts.nearClip,

package/js/inline3d-splat-playcanvas.js

@@ -98,6 +98,7 @@ import {
   ORBIT_MAX_DEG,
   ORBIT_TAU_DRAG_S,
   ORBIT_TAU_REST_S,
+  DRAG_DEG_PER_TILE,
   WHEEL_LINE_PX,
   WHEEL_PAGE_PX,
   WHEEL_MAX_PX,
@@ -812,6 +813,7 @@ export class PlayCanvasSplatViewer {
       pitchLimit = PITCH_LIMIT,
       orbitMaxDeg = ORBIT_MAX_DEG,
       orbitEase = {},
+      orbitStyle = 'tilt',
       zoom,
       feather = 0,
       captureFit = 'height',
@@ -853,6 +855,10 @@ export class PlayCanvasSplatViewer {
     // from where the press started, easing with τ = orbitEase.drag; release relaxes back with
     // τ = orbitEase.rest. `_orbitMode` is 'drag' | 'rest' | null (null = ordinary damping).
     this.orbitMaxDeg = orbitMaxDeg;
+    // 'tilt' (the default; photo splats: a capped tilt that relaxes) or 'turntable' (./model: an
+    // object you turn all the way round — SceneViewer's cumulative drag, DRAG_DEG_PER_TILE per
+    // tile width, no relax).
+    this.orbitStyle = orbitStyle === 'turntable' ? 'turntable' : 'tilt';
     this.orbitEase = { drag: orbitEase.drag ?? ORBIT_TAU_DRAG_S, rest: orbitEase.rest ?? ORBIT_TAU_REST_S };
     this._orbitMode = null;
     // Zoom bounds + relax (./inline3d-splat-shared.js §ZOOM). Wheel and pinch clamp to
@@ -2414,6 +2420,7 @@ export class PlayCanvasSplatViewer {
     };
     const endDrag = () => {
       dragging = false;
+      if (this.orbitStyle === 'turntable') return; // stays where it was turned
       this._targetYaw = restYaw;
       this._targetPitch = clamp(restPitch, this.pitchLimit[0], this.pitchLimit[1]);
       this._orbitMode = 'rest';
@@ -2443,7 +2450,8 @@ export class PlayCanvasSplatViewer {
       // Rest = where the pose was heading when pressed (an idle turntable's yaw included).
       restYaw = this._orbitMode ? restYaw : this._targetYaw;
       restPitch = this._orbitMode ? restPitch : this._targetPitch;
-      this._orbitMode = 'drag';
+      // turntable: the ordinary damping (no drag ease, no relax), as SceneViewer
+      this._orbitMode = this.orbitStyle === 'turntable' ? null : 'drag';
       this._lastInput = now();
     };
     this._onMove = (ev) => {
@@ -2457,6 +2465,20 @@ export class PlayCanvasSplatViewer {
       }
       if (!dragging) return;
       const box = el.getBoundingClientRect();
+      if (this.orbitStyle === 'turntable') {
+        // SceneViewer's drag (./inline3d-viewer.js): a full drag across the tile is a half turn,
+        // accumulated from the last move, near face following the pointer on both axes.
+        this._targetYaw += ((ev.clientX - startX) / Math.max(box.width, 1)) * DRAG_DEG_PER_TILE;
+        this._targetPitch = clamp(
+          this._targetPitch + ((ev.clientY - startY) / Math.max(box.height, 1)) * DRAG_DEG_PER_TILE,
+          this.pitchLimit[0],
+          this.pitchLimit[1],
+        );
+        startX = ev.clientX;
+        startY = ev.clientY;
+        this._lastInput = now();
+        return;
+      }
       const dx = (ev.clientX - startX) / Math.max(box.width, 1);
       const dy = (ev.clientY - startY) / Math.max(box.height, 1);
       const max = this.orbitMaxDeg;

package/model.d.ts

@@ -126,6 +126,13 @@ export interface ModelOptions {
   farClip?: number;
   /** PlayCanvas only: the drag's tilt cap in degrees (default 15, tilt-and-relax). */
   orbitMaxDeg?: number;
+  /**
+   * PlayCanvas only: how a drag turns the model. `'turntable'` (the default for addModel, as on the
+   * three path): cumulative, a full drag across the tile is a half turn, and it stays where you
+   * leave it. `'tilt'` (addSplat's mapping for photo splats): capped at ±`orbitMaxDeg` from the
+   * press and relaxing back to rest on release.
+   */
+  orbitStyle?: 'turntable' | 'tilt';
   /** PlayCanvas only: the orbit's easing time constants, seconds. */
   orbitEase?: { drag?: number; rest?: number };
   /** PlayCanvas only: zoom bounds + relax (wheel, pinch, setPose) — see the splat option. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.33.1",
+  "version": "1.35.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",