@displayxr/inline3d 1.28.0 → 1.29.0

package/js/inline3d.js

@@ -593,6 +593,39 @@ export async function createInline3D(opts = {}) {
   return new Inline3D(session, refSpace, { lazy, rootMargin, autoChrome, modeSwitch, untrackedFallback });
 }
 
+// The one shared creation in flight, so two callers racing before the first session resolves
+// (a <dxr-call> and a player both mounting on load) share ONE createInline3D() rather than
+// opening two sessions. Cleared once it settles: from then on `liveManager` is the answer.
+let sharedPending = null;
+
+/**
+ * The document's shared manager: the live `createInline3D()` result if one exists, else a new one
+ * (registered as the shared one by construction, since every manager is). Woven-canvas rule 1 —
+ * one inline-3D session per document — is what this exists for: a module that needs a wall it
+ * did not create (`mountCall`, `<dxr-call>`) must not open a second session next to the page's
+ * own, and a page that made its wall first and then adds such a module gets that same wall back.
+ *
+ * `opts` are `createInline3D`'s and apply only when this call creates the manager; a manager
+ * that already exists is returned as it was configured. An unsupported browser resolves to the
+ * same `{ supported: false }` shape as `createInline3D`, and it is NOT cached: nothing was
+ * created, and a later call re-probes (the weave service can bind after page load).
+ *
+ * Closing: whoever `close()`s the shared manager ends the document's session for everyone using
+ * it; the next `sharedInline3D()` opens a fresh one. Modules that borrow the wall must not close
+ * it (the call module never does; it only closes a wall it created — which it no longer does).
+ *
+ * @param {object} [opts]  see {@link createInline3D}
+ * @returns {Promise<Inline3D | {supported:false, trackingState:'unknown', error?:Error}>}
+ */
+export function sharedInline3D(opts = {}) {
+  if (liveManager && liveManager._running) return Promise.resolve(liveManager);
+  if (sharedPending) return sharedPending;
+  sharedPending = createInline3D(opts).finally(() => {
+    sharedPending = null;
+  });
+  return sharedPending;
+}
+
 /**
  * Back-compatible single-scene helper: open a session, weave one canvas, drive a render
  * callback with the two eye views each frame. Equivalent to
@@ -641,6 +674,15 @@ function chromeTextPlates(root) {
   return plates;
 }
 
+/** A pending rewoven() settles anyway ('hold-capped') after this many holds from the call. */
+const REWOVEN_MAX_HOLDS = 4;
+
+/** The CSS size + dpr of a window's canvas: what a pending rewoven() restarts on. */
+function boxKeyOf(canvas) {
+  const dpr = (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
+  return `${canvas.clientWidth}x${canvas.clientHeight}@${dpr}`;
+}
+
 class Inline3D {
   constructor(
     session,
@@ -1179,6 +1221,20 @@ class Inline3D {
           live = false;
         };
       },
+      /**
+       * {@link firstWoven}, measured from NOW: resolves once this canvas, as it is at the call,
+       * has drawn a stereo frame and then held for `firstWovenHoldMs`. For a canvas that is
+       * already woven but whose rect is about to change (fullscreen, a layout resize): the
+       * browser re-registers the moved rect and the same identity gap as a fresh canvas
+       * applies, so cover the canvas across the change and release on this. A change of the
+       * canvas's CSS size or devicePixelRatio while it is pending restarts the hold (checked every
+       * frame, for every window kind; a move without a resize is not detected), and it settles
+       * anyway with `reason: 'hold-capped'` four holds after the call, so a size that never stops
+       * animating cannot keep a cover up. Calling it again while pending returns the same
+       * promise, restarted. Before the first join it IS `firstWoven`; on a window that will not
+       * weave it resolves that `woven: false` result. Same shape, never rejects.
+       */
+      rewoven: () => this._rewoven(win),
     };
   }
 
@@ -1957,6 +2013,10 @@ class Inline3D {
       fwRegAt: nowMs(),
       fwLayerAt: null,
       fwStereo: false,
+      // handle.rewoven(): null, or the pending { promise, resolve, calledAt, at, stereo, box } —
+      // firstWoven's two halves again, counted from the call (and from each later box change).
+      rw: null,
+      rwGone: null, // the reason this window will never weave again, once one arrived
     };
     win.fwPromise = new Promise((resolve) => {
       win.fwResolve = resolve;
@@ -2051,6 +2111,7 @@ class Inline3D {
       win.fwLayerAt = nowMs();
       win.fwStereo = false;
     }
+    this._restartRewoven(win);
     win.layerLostSent = false; // a live layer again: a future loss is worth reporting again
     // Nothing about the hardware state is re-asserted here, and that is the point: the panel's
     // mode is the DISPLAY's, it survives a tile scrolling away, and this SDK never requests it
@@ -2492,8 +2553,12 @@ class Inline3D {
       if (!win.resizePending) return;
       win.resizePending = false;
       if (!win.layer || !win.ownsBuffer) return;
+      // The on-screen box and the buffer are separate questions since the source cap (#88): a
+      // box that moves (fullscreen) re-joins the weave at a new rect even when a capped buffer
+      // stays the same size, so a pending rewoven() restarts on the BOX, not on the buffer.
+      this._noteRewovenBox(win);
       const { w, h } = this._eyeSize(win);
-      if (w === win.eyeW && h === win.eyeH) return; // observer fired, geometry didn't move
+      if (w === win.eyeW && h === win.eyeH) return; // observer fired, the buffer didn't move
       this._sizeBuffer(win, /*sbs*/ true);
       this._paint(win, null); // repaint NOW: setting canvas.width cleared the buffer
     };
@@ -2769,6 +2834,7 @@ class Inline3D {
             if (views.length >= 2) {
               win.fwStereo = true;
               if (!win.warnedBufMismatch) this._checkSceneBuffer(win);
+              if (win.rw) win.rw.stereo = true;
             }
           } catch (err) {
             if (!win.frameThrewWarned) {
@@ -2792,6 +2858,7 @@ class Inline3D {
         // video has never had a frame) the tile holds nothing worth revealing yet.
         if (win.sbs && (win.kind === 'video' ? ((win.video && win.video.readyState) || 0) >= 2 : !!win.img)) {
           win.fwStereo = true;
+          if (win.rw) win.rw.stereo = true;
         }
       }
       this._tickFirstWoven(win);
@@ -2809,6 +2876,20 @@ class Inline3D {
    * which knows nothing about whether the compositor has matched this canvas yet.
    */
   _tickFirstWoven(win) {
+    if (win.rw) {
+      // Every frame, for every window kind: the ResizeObserver only watches SDK-sized buffers, and
+      // no observer sees a dpr-only change.
+      this._noteRewovenBox(win);
+      const rw = win.rw;
+      const t = nowMs();
+      if (rw.stereo && t - rw.at >= win.fwHoldMs) this._settleRewoven(win, true, 'hold-elapsed');
+      // A box that never stops changing (a long CSS transition on width) would restart the hold
+      // forever and leave a cover up for good: once it has restarted, give up waiting
+      // REWOVEN_MAX_HOLDS holds after the call.
+      else if (rw.at > rw.calledAt && t - rw.calledAt >= REWOVEN_MAX_HOLDS * win.fwHoldMs) {
+        this._settleRewoven(win, true, 'hold-capped');
+      }
+    }
     if (win.fwResult || !win.fwStereo || win.fwLayerAt === null) return;
     if (nowMs() - win.fwLayerAt < win.fwHoldMs) return;
     this._settleFirstWoven(win, true, 'hold-elapsed');
@@ -2816,12 +2897,60 @@ class Inline3D {
 
   /** One-shot: the first call wins, later ones are ignored. */
   _settleFirstWoven(win, woven, reason) {
+    // Every "will not weave" path lands here, so a pending rewoven() is released with it, and a
+    // later one answers at once (firstWoven may have settled woven:true long before).
+    if (!woven) {
+      if (!win.rwGone) win.rwGone = reason;
+      this._settleRewoven(win, false, reason);
+    }
     if (win.fwResult) return;
     win.fwResult = Object.freeze({ woven, confirmed: false, reason, ms: Math.round(nowMs() - win.fwRegAt) });
     win.fwResolve(win.fwResult);
     win.fwResolve = null;
   }
 
+  /** handle.rewoven(): see the handle's doc comment. */
+  _rewoven(win) {
+    if (!win.fwResult) return win.fwPromise; // still on the first join: the same question
+    if (!win.fwResult.woven) return Promise.resolve(win.fwResult);
+    if (win.rwGone) return Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: win.rwGone, ms: 0 }));
+    if (win.rw) {
+      this._restartRewoven(win);
+      return win.rw.promise;
+    }
+    let resolve;
+    const promise = new Promise((r) => {
+      resolve = r;
+    });
+    const t = nowMs();
+    win.rw = { promise, resolve, calledAt: t, at: t, stereo: false, box: boxKeyOf(win.canvas) };
+    return promise;
+  }
+
+  /** A pending rewoven() restarts when the canvas's CSS size or dpr differs from the last look. */
+  _noteRewovenBox(win) {
+    const rw = win.rw;
+    if (!rw) return;
+    const box = boxKeyOf(win.canvas);
+    if (box === rw.box) return;
+    rw.box = box;
+    this._restartRewoven(win);
+  }
+
+  /** The canvas moved again (a box change, a new layer): the hold starts over from here. */
+  _restartRewoven(win) {
+    if (!win.rw) return;
+    win.rw.at = nowMs();
+    win.rw.stereo = false;
+  }
+
+  _settleRewoven(win, woven, reason) {
+    const rw = win.rw;
+    if (!rw) return;
+    win.rw = null;
+    rw.resolve(Object.freeze({ woven, confirmed: false, reason, ms: Math.round(nowMs() - rw.calledAt) }));
+  }
+
   // ── page lifecycle: bfcache, freeze, restore (browser#87) ───────────────────────────
   //
   // A weaved window's rect reaches the compositor from the session's own rAF: every frame the

package/js/lift/index.js

@@ -0,0 +1,15 @@
+// js/lift/index.js — PLACEHOLDER for the lift module (`@displayxr/inline3d/lift`), which is on
+// the `feat/lift` branch and not yet on main. That branch replaces this file wholesale (resolve
+// any add/add conflict by taking feat/lift's file).
+//
+// It exists so `./call/full` (js/inline3d-call-full.js) can import lift STATICALLY today — the
+// one shape a bundler can follow — and so the `./call` entry's computed import of this path
+// resolves to "a lift module with no `lift` export" (reason `no-lift-export`) rather than a
+// network 404. Either way the call raises `warning { code: 'lift-not-bundled' }` when a 2D
+// participant would have been lifted, and the lobby reads "2D→3D unavailable in this build".
+//
+// `lift` is exported as null (not omitted): webpack turns a namespace access to a MISSING export
+// into a build error, and the point of this file is that `/call/full` builds everywhere today.
+
+export const LIFT_PLACEHOLDER = true;
+export const lift = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -40,12 +40,20 @@
       "types": "./call.d.ts",
       "import": "./js/inline3d-call.js"
     },
+    "./call/full": {
+      "types": "./call-full.d.ts",
+      "import": "./js/inline3d-call-full.js"
+    },
     "./undock": {
       "types": "./index.d.ts",
       "import": "./js/inline3d-undock.js"
     }
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./js/inline3d-call.js",
+    "./js/inline3d-call-full.js",
+    "./dist/*.js"
+  ],
   "files": [
     "js/inline3d.js",
     "js/inline3d-undock.js",
@@ -72,7 +80,10 @@
     "js/inline3d-playcanvas-engine.js",
     "js/inline3d-player.js",
     "js/inline3d-call.js",
+    "js/inline3d-call-full.js",
     "js/call/",
+    "js/lift/",
+    "dist/",
     "index.d.ts",
     "three.d.ts",
     "viewer.d.ts",
@@ -80,6 +91,7 @@
     "model.d.ts",
     "player.d.ts",
     "call.d.ts",
+    "call-full.d.ts",
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
@@ -133,10 +145,15 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "tsc --noEmit -p tsconfig.json && node --test \"test/*.test.mjs\""
+    "test": "tsc --noEmit -p tsconfig.json && node --test \"test/*.test.mjs\"",
+    "build:dist": "node tools/dist/build.mjs",
+    "prepack": "node tools/dist/build.mjs",
+    "test:e2e": "node test/e2e/call-element.e2e.mjs",
+    "test:bundlers": "node test/bundlers/run.mjs"
   },
   "devDependencies": {
     "typescript": "^5.4.0",
-    "@types/webxr": "^0.5.0"
+    "@types/webxr": "^0.5.0",
+    "esbuild": "^0.25.0"
   }
 }

package/player.d.ts

@@ -91,7 +91,7 @@ export interface PlayerOptions {
    * tile (e.g. `2.39` or `'2.39:1'` for a scope band in a 16:9 tile); the rest stays clear.
    * Implies `fit: 'contain'` unless `fit` says otherwise.
    */
-  band?: number | string;
+  band?: number | string | null;
   /**
    * What the poster image is: `'mono'` (one image for both eyes, the default), or a stereo still
    * laid out like the video (`'sbs'` / `'tb'`), painted eye by eye so it is 3D before the first frame.
@@ -123,6 +123,12 @@ export interface PlayerOptions {
    * Fullscreen API.
    */
   fullscreen?: boolean;
+  /**
+   * Cover the canvas with black across a fullscreen change until `handle.rewoven()` settles
+   * (woven-canvas rule 11). Default false: on the Leia panel fullscreen showed no raw side-by-side
+   * pair without it, and the cover costs ~1.2 s with no picture.
+   */
+  fullscreenCover?: boolean;
   /** Default: `'anonymous'` iff `src` is a cross-origin URL; unset (browser default) otherwise. */
   crossOrigin?: 'anonymous' | 'use-credentials';
   /** Per-eye buffer resolution in px. `'sbs'` + supported wall only — see {@link TileOptions}. */
@@ -135,7 +141,7 @@ export interface PlayerOptions {
   observe?: Element;
 }
 
-export type PlayerEvent = 'play' | 'pause' | 'ended' | 'timeupdate' | 'ready' | 'error' | 'titlechange';
+export type PlayerEvent = 'play' | 'pause' | 'ended' | 'timeupdate' | 'ready' | 'error' | 'titlechange' | 'detached';
 
 /** One playlist entry (RFC 0001 Addendum A4). */
 export interface PlayerTitle {
@@ -224,6 +230,44 @@ export function addPlayer(
   opts?: PlayerOptions,
 ): PlayerHandle;
 
+/** {@link attachPlayer}'s options: the player's, plus where its controls go. */
+export interface AttachPlayerOptions extends PlayerOptions {
+  /** Where the SDK controls go. Default: the handle's canvas's parent element. */
+  chromeContainer?: Element;
+}
+
+/** `'detached'`'s payload: something else took (`'superseded'`) or emptied (`'released'`) the slot. */
+export interface PlayerDetachedEvent {
+  reason: 'superseded' | 'released';
+}
+
+/** What {@link attachPlayer} returns: a {@link PlayerHandle} that can give its slot back. */
+export interface AttachedPlayerHandle extends PlayerHandle {
+  /**
+   * Give the slot back: `setVideo(null)`, so the splat, pose, lens and declared rig are exactly as
+   * they were, then tear down the controls and release the elements. Resolves once restored. Leave
+   * a Watch screen with `await player.detach()` before the handle's own `setSource`.
+   */
+  detach(): Promise<void>;
+}
+
+/**
+ * PREVIEW. Surface mode (RFC 0001 Addendum A): the same transport, playlist and events as
+ * {@link addPlayer}, drawn through an EXISTING `addSplat(…, { engine: 'playcanvas' })` handle's
+ * `setVideo` — no canvas, layer or session of its own. The scene stays on screen until the first
+ * frame (it is the poster); a source swap lands at the next title's first frame, as a cut or, with
+ * `transition: 'crossfade'`, `./splat` setVideo's GPU crossfade. Differences from `addPlayer`:
+ * `fullscreen` defaults to false; `band` goes to setVideo's letterbox slot; `poster`, `posterFormat` and the tile options are ignored
+ * (warns once). If another `setVideo` takes the slot, the player stops and emits `'detached'`
+ * ({@link PlayerDetachedEvent}); it never fights for it.
+ */
+export function attachPlayer(
+  splat: { setVideo: (...args: any[]) => Promise<unknown>; canvas?: HTMLCanvasElement; videoElement?: HTMLVideoElement | null },
+  /** `null` with `opts.titles` loads the first title. */
+  src: PlayerSource | null,
+  opts?: AttachPlayerOptions,
+): AttachedPlayerHandle;
+
 /** The `setSource()` transitions a video can mean. */
 export type PlayerTransition = 'cut' | 'crossfade';
 

package/splat.d.ts

@@ -271,6 +271,25 @@ export interface SplatVideoOptions {
   muted?: boolean;
   /** Default true for a URL (the SDK's own element), false for an element you pass. */
   autoplay?: boolean;
+  /**
+   * `'cut'` (default) or `'crossfade'`: a GPU dissolve from the video already on the plane (its
+   * last frame, frozen) to this one. From the splat, and on `setVideo(null)`, it is always a cut.
+   * The same vocabulary as `./player`'s `setSource`; `./splat`'s gaussian transitions throw here.
+   */
+  transition?: 'cut' | 'crossfade';
+  /** Crossfade length. Default 600 (the player's). 0 = a cut. */
+  durationMs?: number;
+  /** A named easing ({@link SplatEasing}) or `(x) => y` on [0, 1]. Default `'easeInOutSine'`. */
+  easing?: SplatEasing | ((x: number) => number);
+  /** Only `'frozen'`: the outgoing video dissolves from its last frame. */
+  outgoing?: 'frozen';
+  /**
+   * A letterbox slot: the picture is fitted into a centred band of this aspect inside the tile
+   * (`2.39` or `'2.39:1'` for a scope band in a 16:9 tile), the rest of the element left clear —
+   * `./player`'s `band`, on the plane. `fit: 'cover'` fills the band and crops the eye image about
+   * its centre.
+   */
+  band?: number | string | null;
 }
 
 /** What `handle.setVideo(src)` resolves to. */
@@ -279,6 +298,18 @@ export interface SplatVideo {
   readonly video: HTMLVideoElement;
   readonly format: 'sbs' | 'tb' | 'mono';
   readonly fit: 'contain' | 'cover';
+  /** The band's aspect, or null. */
+  readonly band: number | null;
+  /**
+   * Where the picture is on screen, in CSS px from the canvas's top-left, clipped to the canvas;
+   * the letterbox bars are the canvas minus this. Null before the first drawn frame and once
+   * another `setVideo` replaced this one. Place controls against the picture with it.
+   */
+  readonly rect: { readonly x: number; readonly y: number; readonly width: number; readonly height: number } | null;
+  /** `cb(rect)` whenever the rect changes (a resize, a new size, a band): a microtask right after the draw, same frame, before paint. Returns an unsubscribe. */
+  onRectChange(cb: (rect: { x: number; y: number; width: number; height: number }) => void): () => void;
+  /** What the swap did: `'crossfade'` only when it replaced a video on screen and asked to. Resolved at the swap, before the fade ends. */
+  readonly transition: 'cut' | 'crossfade';
   /** `handle.setVideo(null)`, or a no-op if another setVideo has replaced this one. */
   remove(): Promise<null>;
   /** Frames drawn with the plane up, and texture uploads (new video frames). */
@@ -1024,6 +1055,13 @@ export interface SplatHandle {
   readonly renderScale: number;
   /** The per-eye buffer scale as requested (the option, or the last `setRenderScale`). Both engines. */
   readonly renderScaleRequested: number;
+  /**
+   * `engine: 'playcanvas'` only. The `<video>` `setVideo`'s plane is showing now, or null (none, or
+   * one still waiting for its first frame). Read-only; no event reports it changing.
+   */
+  readonly videoElement?: HTMLVideoElement | null;
+  /** `engine: 'playcanvas'` only. The tile's canvas (page chrome sits beside it). */
+  readonly canvas?: HTMLCanvasElement;
   /**
    * `engine: 'playcanvas'` only. The 2D tier's EYE offset — a head-parallax analogue for a flat
    * screen with no tracked eyes (e.g. a phone's tilt). `{x, y}` is normalised in the mono camera's