@displayxr/inline3d 1.27.0 → 1.29.0

package/js/inline3d.js

@@ -35,6 +35,10 @@ export { undock, undockAvailable, undockUrl, tileScreenRect };
 // The eased 2D<->3D transition. A pure state machine (no DOM, no WebXR) ported from the native
 // `dxr::ModeSwitch`, so the browser eases the disparity around a mode switch the same way — and in
 // the same ORDER — as the native apps and the demos. See _requestRenderingModeEased.
+// The device-limit clamp on a backing store (MAX_TEXTURE_SIZE & co.), shared with ./viewer,
+// ./splat and ./model. Dependency-free.
+import { probeBufferLimits, clampEyeBuffer, clampWarning, bufferScale, mismatchWarning } from './inline3d-buffer-limit.js';
+
 import {
   ModeSwitch,
   MODE_SWITCH_DEFAULT_DURATION_MS,
@@ -589,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
@@ -637,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,
@@ -1175,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),
     };
   }
 
@@ -1953,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;
@@ -2047,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
@@ -2340,17 +2405,108 @@ class Inline3D {
     win.autoExcluded.clear();
   }
 
-  /** The per-eye buffer size this window should have right now (explicit, or box × dpr). */
-  _eyeSize(win) {
+  /**
+   * The per-eye buffer size this window should have right now: explicit, or box × dpr — capped
+   * at the SOURCE's own per-eye resolution for image and video windows.
+   *
+   * WHY THE CAP (measured, NP02J tablet, DisplayXR Browser 1.0.6): the player sample's 90vw
+   * tile at dpr 2 asked for a 4608×1296 backing store for a 640×360-per-eye clip — 13× the
+   * source's pixels, re-drawn every frame. The page fell to 25 fps and dropped 47 of 97 video
+   * frames; the same clip in a 45vw tile (2304×648) ran at 57 fps with 0 dropped. Drawing a
+   * source into a buffer larger than itself adds no detail: the compositor scales the layer to
+   * the box either way, so upscaling here only spends GPU fill-rate. The cap keeps the BOX
+   * aspect (the eyes stay correctly shaped) and only shrinks, never grows past box × dpr.
+   * An explicit {width, height} is the page's call and is never capped by the source.
+   *
+   * THEN THE DEVICE LIMIT, on every window including an explicit size: the whole store (2 × eye
+   * wide in SBS) must fit min(MAX_TEXTURE_SIZE, MAX_RENDERBUFFER_SIZE, MAX_VIEWPORT_DIMS), or
+   * the weave cannot take it as one texture. An Android 3D tablet (Adreno 740) reports 4096 where
+   * desktops report 16384. Both axes shrink by one factor (./inline3d-buffer-limit.js), warned
+   * once per window. `win.bufScale` records the total shrink so buffer-px decoration
+   * (cornerRadius, feather) keeps its on-screen size.
+   */
+  _eyeSize(win, sbs = true) {
     const dpr = Math.min(window.devicePixelRatio || 1, 2);
-    return {
-      w: win.reqW || Math.round((win.canvas.clientWidth || 256) * dpr),
-      h: win.reqH || Math.round((win.canvas.clientHeight || 256) * dpr),
-    };
+    let w = win.reqW || Math.round((win.canvas.clientWidth || 256) * dpr);
+    let h = win.reqH || Math.round((win.canvas.clientHeight || 256) * dpr);
+    let scale = 1;
+    const eye = !win.reqW && !win.reqH && this._sourceEyeSize(win);
+    if (eye) {
+      // The smallest buffer that still holds every source pixel along the axis that fills the box.
+      const s = Math.max(eye.w / w, eye.h / h);
+      if (s < 1) {
+        scale = s;
+        w = Math.max(1, Math.round(w * s));
+        h = Math.max(1, Math.round(h * s));
+      }
+    }
+    const c = clampEyeBuffer(w, h, probeBufferLimits(), { cols: sbs ? 2 : 1 });
+    if (c.clamped) {
+      scale *= c.scale;
+      w = c.eyeW;
+      h = c.eyeH;
+      if (!win.warnedBufClamp) {
+        win.warnedBufClamp = true;
+        console.warn(clampWarning('[inline3d]', c));
+      }
+    }
+    win.bufScale = scale;
+    return { w, h };
+  }
+
+  /** One eye of an image/video window's source (an SBS pair: left eye = left half), or null. */
+  _sourceEyeSize(win) {
+    if (win.kind !== 'video' && win.kind !== 'image') return null;
+    const src = win.kind === 'video' ? win.video : win.img;
+    if (!src) return null;
+    const sw = src.videoWidth || src.naturalWidth || src.width;
+    const sh = src.videoHeight || src.naturalHeight || src.height;
+    if (!(sw > 1) || !(sh > 0)) return null;
+    return { w: sw / 2, h: sh };
+  }
+
+  /**
+   * A scene canvas is the app's to size, so the core cannot clamp it — but it can SEE the browser
+   * clamp it. Where the store exceeds the device's MAX_TEXTURE_SIZE (4096 on an Adreno 740 tablet)
+   * the drawing buffer silently comes out smaller than canvas.width, while getViewport() keeps
+   * splitting canvas.width: the eye boundary lands off-centre and the panel shows a double image.
+   * Say so once. ./viewer, ./splat and ./model clamp before sizing and never trip this.
+   *
+   * Only called after the app has drawn a stereo frame, so the canvas already HAS its context:
+   * getContext() of the same type returns it, of another type returns null — it never creates one.
+   */
+  _checkSceneBuffer(win) {
+    const c = win.canvas;
+    if (!c || typeof c.getContext !== 'function') return;
+    if (win.sceneGl === undefined) {
+      let gl = null;
+      try {
+        gl = c.getContext('webgl2') || c.getContext('webgl');
+      } catch {
+        gl = null;
+      }
+      win.sceneGl = gl && typeof gl.drawingBufferWidth === 'number' ? gl : null;
+    }
+    if (!win.sceneGl) return;
+    const b = bufferScale(c, win.sceneGl);
+    if (b.mismatch) {
+      win.warnedBufMismatch = true;
+      console.warn(
+        mismatchWarning(
+          '[inline3d]',
+          c,
+          b,
+          'getViewport() splits canvas.width, so the eyes are off-centre in the woven buffer. This ' +
+            'scene canvas is sized by the page: keep 2 × eye width and the height within ' +
+            'MAX_TEXTURE_SIZE / MAX_RENDERBUFFER_SIZE / MAX_VIEWPORT_DIMS, or map getViewport() onto ' +
+            'gl.drawingBufferWidth/Height.',
+        ),
+      );
+    }
   }
 
   _sizeBuffer(win, sbs) {
-    const { w: boxW, h: boxH } = this._eyeSize(win);
+    const { w: boxW, h: boxH } = this._eyeSize(win, sbs);
     win.eyeW = boxW;
     win.eyeH = boxH;
     win.canvas.width = sbs ? boxW * 2 : boxW; // SBS = two eye tiles wide
@@ -2397,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
     };
@@ -2473,10 +2633,25 @@ class Inline3D {
     const srcW = src.videoWidth || src.naturalWidth || src.width;
     const srcH = src.videoHeight || src.naturalHeight || src.height;
     if (!srcW || !srcH) return;
+    // The buffer is capped at the source's per-eye resolution (_eyeSize), and a source's size is
+    // only known once it has decoded — or changes on a new title. Re-derive on a change; the
+    // resize clears the buffer, and the paint right below refills it.
+    const srcKey = srcW + 'x' + srcH;
+    if (win.srcKey !== srcKey) {
+      win.srcKey = srcKey;
+      if (win.ownsBuffer && !(win.reqW && win.reqH)) {
+        const { w, h } = this._eyeSize(win, win.sbs);
+        if (w !== win.eyeW || h !== win.eyeH) this._sizeBuffer(win, win.sbs);
+      }
+    }
+    // cornerRadius / feather are buffer px at the UNCAPPED size; keep their on-screen size.
+    const k = win.bufScale || 1;
+    const radius = win.cornerRadius * k;
+    const feather = win.feather * k;
     ctx.clearRect(0, 0, c.width, c.height);
     if (!win.sbs) {
       // Flat fallback: left eye only, stretched to the square buffer.
-      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, c.width, c.height, win.cornerRadius, win.feather);
+      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, c.width, c.height, radius, feather);
       return;
     }
     const halfDst = c.width / 2;
@@ -2487,16 +2662,16 @@ class Inline3D {
     // as a squeezed pair). See _trackBakedStereo.
     const stereo = Math.min(this._stereoFactor, this._bakedStereo);
     if (stereo < 1) {
-      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, win.cornerRadius, win.feather); // L
-      drawEyeBlend(ctx, src, srcW / 2, srcH, halfDst, c.height, stereo, win.cornerRadius, win.feather); // L+R
+      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, radius, feather); // L
+      drawEyeBlend(ctx, src, srcW / 2, srcH, halfDst, c.height, stereo, radius, feather); // L+R
       return;
     }
     // A single stretched draw maps SBS source → SBS buffer (left→left, right→right); the
     // per-eye path is only needed to bake decoration (rounded corners / edge feather), which
     // MUST be applied to each eye separately — see drawEye/featherEye.
-    if (win.cornerRadius > 0 || win.feather > 0) {
-      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, win.cornerRadius, win.feather); // L
-      drawEye(ctx, src, srcW / 2, 0, srcW / 2, srcH, halfDst, 0, halfDst, c.height, win.cornerRadius, win.feather); // R
+    if (radius > 0 || feather > 0) {
+      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, radius, feather); // L
+      drawEye(ctx, src, srcW / 2, 0, srcW / 2, srcH, halfDst, 0, halfDst, c.height, radius, feather); // R
     } else {
       ctx.drawImage(src, 0, 0, srcW, srcH, 0, 0, c.width, c.height);
     }
@@ -2656,7 +2831,11 @@ class Inline3D {
             win.onFrame(views, win.layer, f);
             // A stereo frame the page drew without throwing. A short view list is the load
             // fallback (a mono frame), which is not what a poster is waiting for.
-            if (views.length >= 2) win.fwStereo = true;
+            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) {
               win.frameThrewWarned = true;
@@ -2679,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);
@@ -2696,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');
@@ -2703,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/model.d.ts

@@ -34,7 +34,11 @@ export interface ModelOptions {
    * so a long subject still fits once the turntable turns it (default true).
    */
   fitSweep?: boolean;
-  /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
+  /**
+   * Per-eye buffer scale; 0.5–0.7 is usually free (default 1). Clamped to the device's GL limits: the whole store (2 × eye wide in 3D) is kept within
+   * min(MAX_TEXTURE_SIZE, MAX_RENDERBUFFER_SIZE, MAX_VIEWPORT_DIMS), both axes shrunk by one factor,
+   * with a one-time console warning. The handle's `renderScale` reports the value in force.
+   */
   renderScale?: number;
   feather?: number;
   /**
@@ -176,6 +180,11 @@ export interface ModelHandle {
   /** The last pose the page set (a copy), or null. */
   getCameraPose(): SplatCameraPose | null;
 
+  /** The per-eye buffer scale in force: the `renderScale` option times the device-limit clamp. */
+  readonly renderScale: number;
+  /** The `renderScale` option as given. */
+  readonly renderScaleRequested: number;
+
   remove(): void;
   exclude(el: Element): void;
   unexclude(el: Element): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.27.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",
@@ -36,16 +36,29 @@
       "types": "./player.d.ts",
       "import": "./js/inline3d-player.js"
     },
+    "./call": {
+      "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",
     "js/inline3d-mode-switch.js",
+    "js/inline3d-buffer-limit.js",
     "js/inline3d-three.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
@@ -66,12 +79,19 @@
     "js/inline3d-pc-look.js",
     "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",
     "splat.d.ts",
     "model.d.ts",
     "player.d.ts",
+    "call.d.ts",
+    "call-full.d.ts",
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
@@ -125,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';
 
@@ -267,7 +311,8 @@ export type PlayerAccent = 'azure' | 'violet' | 'magenta' | 'sunset' | 'amber' |
 
 /**
  * Pick the first source this browser can play from candidates listed best first; each is a URL, or
- * `{ src, type }` with a FULL `canPlayType` string (`'video/webm; codecs="vp9, opus"'`). The
- * DisplayXR Browser has no H.264/AAC, and a codec-less `'video/mp4'` still answers 'maybe'.
+ * `{ src, type }` with a FULL `canPlayType` string (`'video/webm; codecs="vp9, opus"'`). Only
+ * DisplayXR Browser 1.0.6+ plays H.264/AAC (via the OS decoders), and a codec-less `'video/mp4'`
+ * still answers 'maybe' — so list a VP9 WebM first when you have one.
  */
 export function pickSource(candidates: PlayerSource, canPlayType?: (type: string) => string): string | Blob | undefined;