@displayxr/inline3d 1.37.1 → 1.39.0

package/index.d.ts

@@ -24,27 +24,93 @@ export interface TileOptions {
    * you know is not fresh; 0 means "the first stereo frame".
    */
   firstWovenHoldMs?: number;
+  /**
+   * Cover this canvas across a rect change, owned by the SDK. Default `'off'` on `addImage` /
+   * `addVideo` / `addScene` (frozen defaults); `'auto'` on `./splat` and `./model`.
+   *
+   * Once the window has woven, a change of the canvas's CSS size, devicePixelRatio or PAGE position
+   * (scrolling the document is not a move) raises a sibling element over the canvas on the frame
+   * the change is seen, and cuts it when {@link TileHandle.rewoven} settles; a further change
+   * while it is up restarts the wait. The cover is a 2D canvas, never a second woven canvas,
+   * placed as the canvas's next sibling (`pointer-events: none`, `data-inline3d-cover`). It is
+   * filled with `color` and, with `snapshot`, the last frame: the left eye, cover-fit to the new
+   * box, captured once at the change with one `drawImage` (never `toDataURL`).
+   *
+   * - `'auto'` — `{ color: '#000', snapshot: true }`.
+   * - `'off'` — nothing; a page that runs its own cover passes this.
+   * - `{ color?, snapshot? }` — `color` any CSS color (default `'#000'`); `snapshot` default true.
+   *
+   * Before the first join nothing is raised: cover a fresh canvas yourself until `firstWoven`
+   * (rule 5). A pure move is seen at the next session frame, so a move made after that frame's
+   * callback can show for one frame.
+   */
+  rectCover?: RectCoverOption;
 }
 
+/** See {@link TileOptions.rectCover}. */
+export type RectCoverOption = 'auto' | 'off' | { color?: string; snapshot?: boolean };
+
+/**
+ * The browser's per-frame report for one layer (`XRDisplayLayer.wovenState`, DisplayXR Browser
+ * builds that carry it; absent elsewhere). A level, never latched.
+ *
+ * - `'pending'` — no presented frame has reported this layer yet (from construction, again after
+ *   close(), and whenever the frame's reply does not list it).
+ * - `'woven'` — the latest swapped frame put this layer's rect into the weave.
+ * - `'withheld'` — it did not; {@link WovenWithheldReason} says why.
+ */
+export type WovenState = 'pending' | 'woven' | 'withheld';
+
+/**
+ * Why a layer reads `'withheld'` (`XRDisplayLayer.withheldReason`). The same tokens the browser
+ * logs; what each means and whose fix it is: `docs/woven-canvas-rules.md` §3. A future browser may
+ * add tokens, so treat an unknown string as "withheld, reason not listed".
+ */
+export type WovenWithheldReason =
+  | 'no-quad'
+  | 'no-identity'
+  | 'no-join'
+  | 'cross-pass:mono'
+  | 'cross-pass:mono(cover,2:1)'
+  | 'resolve-dropped'
+  | (string & {});
+
 /**
  * What {@link TileHandle.firstWoven} resolves to. Settles once and never rejects.
  *
- * - `woven: true, reason: 'hold-elapsed'` — a stereo frame is on a layer that has existed for
- *   `firstWovenHoldMs`. Drop the poster covering the canvas.
- * - `woven: true, reason: 'hold-capped'` — `rewoven()` only: the canvas kept resizing, so it
- *   stopped waiting four holds after the call. Drop the cover; the rect may still be settling.
- * - `woven: false` — the window will not weave (`'layer-failed'`, `'session-ended'`,
- *   `'removed'`; the subpaths add `'unsupported'`). The canvas is already flat (image/video) or
- *   its `onLayerLost` has run (scene). Drop the poster onto the 2D fallback.
+ * - `woven: true, reason: 'woven'` (`confirmed: true`) — the BROWSER reported the layer woven
+ *   (`XRDisplayLayer.wovenState`), after a stereo frame was drawn. No hold. Drop the poster.
+ * - `woven: true, reason: 'hold-elapsed'` (`confirmed: false`) — a browser without that report:
+ *   a stereo frame is on a layer that has existed for `firstWovenHoldMs`. Drop the poster.
+ * - `woven: true, reason: 'hold-capped'` — `rewoven()`: the canvas kept resizing or moving, so
+ *   it stopped waiting four holds after the call; with the report, also a 'woven' read that never
+ *   qualified (see {@link TileHandle.rewoven}). Drop the cover; the rect may still be settling.
+ * - `woven: false, confirmed: true`, `reason` a {@link WovenWithheldReason} or `'pending'` — the
+ *   browser kept reporting the layer withheld (or never listed it) for the whole cap: four holds,
+ *   at least 4.8 s. A safety release, not a loss: the canvas is NOT taken flat and `rewoven()`
+ *   keeps working. Drop the cover; what shows is what the browser draws for that reason
+ *   (`cross-pass:mono` is flat in place; `no-identity` can be the raw pair).
+ * - `woven: false, confirmed: false` — the window will not weave (`'layer-failed'`,
+ *   `'session-ended'`, `'removed'`; the subpaths add `'unsupported'`). The canvas is already flat
+ *   (image/video) or its `onLayerLost` has run (scene). Drop the poster onto the 2D fallback.
  */
 export interface FirstWovenResult {
   readonly woven: boolean;
   /**
-   * `true` only when the BROWSER reported the join. Always `false` today: no browser exposes
-   * that, so the result is the SDK's worst-case hold rather than a report.
+   * `true` only when the BROWSER reported the state (`XRDisplayLayer.wovenState`). `false` on a
+   * browser without that report: the result is then the SDK's worst-case hold.
    */
   readonly confirmed: boolean;
-  readonly reason: 'hold-elapsed' | 'hold-capped' | 'layer-failed' | 'session-ended' | 'removed' | 'unsupported';
+  readonly reason:
+    | 'woven'
+    | 'hold-elapsed'
+    | 'hold-capped'
+    | 'layer-failed'
+    | 'session-ended'
+    | 'removed'
+    | 'unsupported'
+    | 'pending'
+    | WovenWithheldReason;
   /** Milliseconds from the add*() call to settling. */
   readonly ms: number;
 }
@@ -289,6 +355,15 @@ export interface SceneOptions extends TileOptions {
    */
   bufferClamped?: boolean;
   onLayerLost?: () => void;
+  /**
+   * Called INSIDE the ResizeObserver callback when the canvas's CSS box or devicePixelRatio
+   * changes — after the frame's animation callbacks, before its paint. Resize your backing store
+   * and draw one frame here (replay your last views) and the old store is never shown stretched
+   * onto the new box, which is what waiting for the next frame shows. Called only on a real
+   * change, never re-entrantly; a throw is caught and warned about once. Default: none, and then
+   * no observer is attached to a scene canvas (unchanged).
+   */
+  onResize?: (box: { width: number; height: number; dpr: number }) => void;
 }
 
 /** The per-frame render callback passed to {@link Inline3D.addScene}. */
@@ -298,7 +373,14 @@ export type SceneFrameCallback = (
   frame: XRFrame,
 ) => void;
 
-/** The handle returned by every add*() call. */
+/**
+ * The handle returned by every add*() call.
+ *
+ * An add*() on a canvas that is still registered (not `remove()`d) on the same manager warns once
+ * per canvas (1.38) and then proceeds as it always has: the layer is closed and rebuilt (a fresh
+ * identity gap), or a subpath puts a second renderer on the context, and the call returns its own
+ * new handle. Change what is in the canvas instead, or `remove()` first.
+ */
 export interface TileHandle {
   /** Remove this window: close its weave layer and stop driving it. */
   remove(): void;
@@ -342,6 +424,19 @@ export interface TileHandle {
   /**
    * The panel this window weaves on, or `null` where there is no glasses-free display.
    *
+   * `null` is returned only once the layer has answered for real or the cap has passed, never for
+   * "not ready yet". Called before this window's layer has delivered its first frame (right after
+   * `add*()`, the natural place), the call waits for the release signal — where the browser
+   * reports {@link TileHandle.wovenState}, the first `'woven'` read (a `'withheld'` read right
+   * after the layer is built does not count: it comes before the weave session can answer);
+   * elsewhere, the layer's first stereo frame; no first-woven hold — and asks then. If the layer
+   * still answers `null` before the cap, that answer is not returned: the call is asked again on
+   * each later release signal (the next `'woven'` read, or the next session frame once a stereo
+   * frame has been drawn) and resolves with the first non-`null` answer. Once a read on this layer
+   * has answered for real, later calls go straight to the layer. The cap is the first-woven cap
+   * (four holds from the layer's construction, never under 4.8 s): past it the layer's `null` is
+   * returned as a real absence. Without a live layer it settles at once, as below.
+   *
    * Rejects with an `Error` on a browser without the display-mode API
    * ({@link inline3dDisplayModesSupported}) or while this window has no live layer (lazy mode,
    * tile off screen).
@@ -354,7 +449,14 @@ export interface TileHandle {
    * The canvas size is read at the call: call again after a resize.
    */
   displayMetrics(): Promise<DisplayMetrics>;
-  /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
+  /**
+   * Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}.
+   *
+   * An empty list is returned only once the cap has passed, never for "not ready yet": like
+   * {@link getDisplayInfo}, a call made before this window's layer has delivered its first frame
+   * waits for the same release signal, an empty answer before the cap is asked again on the next
+   * one, and the cap is the same. Rejects as {@link getDisplayInfo} does.
+   */
   getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
   /**
    * Ask the runtime to switch the display to `modeIndex`. A thin pass-through — it resolves and
@@ -368,6 +470,10 @@ export interface TileHandle {
    *
    * A `viewCount === 1` mode is requestable and is how a page goes flat.
    *
+   * Made before this window's layer has delivered its first frame, the request waits for it (the
+   * same release signal and cap as {@link getDisplayInfo}; forwarded once, not retried): before
+   * then the browser has no weave session to forward it to.
+   *
    * With the eased transition on (the default — see {@link ModeSwitchOptions}) a going-flat
    * request is HELD while the disparity ramps out, so the promise resolves when the request has
    * been forwarded rather than on the call; a request dropped by a reversal in that window
@@ -422,22 +528,45 @@ export interface TileHandle {
    * Scene windows only — image/video windows always report `{ frames: 0, monoFrames: 0 }`.
    */
   stats(): { frames: number; monoFrames: number };
+  /**
+   * The browser's report for this window's layer, read live ({@link WovenState}); `'pending'`
+   * while the window has no live layer; `null` on a browser that does not report it (the
+   * attribute is absent on mac, Linux, Android and Windows builds without it). Diagnostics:
+   * `firstWoven` / `rewoven()` already settle on it.
+   */
+  readonly wovenState: WovenState | null;
+  /** The why-token while {@link TileHandle.wovenState} is `'withheld'`, else `null`. */
+  readonly withheldReason: WovenWithheldReason | null;
   /**
    * Resolves once, when it is safe to reveal this canvas: see {@link FirstWovenResult}. THE way to
    * release a poster held over a woven canvas — `await Promise.all([ready, handle.firstWoven])`
-   * and cut, never fade. Approximate until a browser reports joins (`confirmed` stays `false`).
+   * and cut, never fade. On a browser that reports `wovenState` it settles on that report
+   * (`confirmed: true`, no hold); elsewhere it is the worst-case hold (`confirmed: false`).
    */
   readonly firstWoven: Promise<FirstWovenResult>;
   /** Callback form of {@link TileHandle.firstWoven}: called once, asynchronously. Returns an unsubscribe. */
   onFirstWoven(cb: (result: FirstWovenResult) => void): () => void;
   /**
    * {@link TileHandle.firstWoven}, measured from NOW. Cover an already-woven canvas across a rect
-   * change (fullscreen, a layout resize), then release on this. A change of the canvas's CSS size
-   * or devicePixelRatio while pending restarts the hold (checked every frame, any window kind; a
-   * move without a resize is not detected). It settles anyway, `woven: true, reason:
+   * change (fullscreen, a layout resize, a move), then release on this ({@link TileOptions.rectCover}
+   * does both for you). A change of the canvas's CSS size, devicePixelRatio or page position (since
+   * 1.38; document scroll excluded) while pending restarts the hold (checked every frame, any
+   * window kind). It settles anyway, `woven: true, reason:
    * 'hold-capped'`, four holds after the call, so a size that never stops animating cannot hold a
    * cover up for good. A second call while pending returns the same promise, restarted. Before the
    * first join it is `firstWoven`; on a window that will not weave it is that `woven: false` result.
+   *
+   * On a browser that reports `wovenState` it settles `confirmed: true, reason: 'woven'` on the
+   * first 'woven' read (with a stereo frame drawn since the call) that either follows a
+   * 'withheld'/'pending' read seen after the call, or comes three session frames after the last
+   * box change seen after the call, or — when no box change is seen after the call, the usual
+   * case of a page that moves the canvas and THEN calls this — comes three session frames after
+   * the call. The report is a live per-frame level trailing the join by 1–3 frames, so a read
+   * three frames on reflects the rect as it was at the call, and a 'woven' from the old rect
+   * never settles it; a read on the frame of the call never does. Expect ~50 ms instead of the
+   * 1.2 s hold.
+   * The cap stays: still 'withheld' four holds after the call (at least 4.8 s), it settles `woven:
+   * false, confirmed: true, reason: <withheldReason>`.
    */
   rewoven(): Promise<FirstWovenResult>;
 }
@@ -455,9 +584,17 @@ export interface Inline3D {
   // The panel is the DOCUMENT's, not a tile's, so the display API lives here; the same names are
   // on every tile handle, routed to whichever window currently holds a live layer.
 
-  /** The panel, or `null` where there is no glasses-free display. See {@link TileHandle.getDisplayInfo}. */
+  /**
+   * The panel, or `null` where there is no glasses-free display — `null` only once the cap has
+   * passed, never for "not ready yet" (a call before the live window has answered waits for its
+   * release signal and is asked again while it answers `null`, capped). See
+   * {@link TileHandle.getDisplayInfo}.
+   */
   getDisplayInfo(): Promise<XRDisplayInfo | null>;
-  /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
+  /**
+   * Every rendering mode the display can be put in; an empty list only once the cap has passed,
+   * never for "not ready yet". See {@link TileHandle.getRenderingModes}.
+   */
   getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
   /** Switch the display to `modeIndex`. See {@link TileHandle.requestRenderingMode}. */
   requestRenderingMode(modeIndex: number): Promise<void>;

package/js/inline3d-call.js

@@ -1873,7 +1873,7 @@ class SelfTile {
       // 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,
+        autoConverge: !!this.call.o.autoConverge, // the call option (default on) governs the self view too
         aspect: this.call.o.tileAspect,
         onRouteChange: (route, st) => {
           if (this.cam !== cam) return; // a view this tile already replaced

package/js/inline3d-model-entry.js

@@ -21,6 +21,7 @@
 // engine import fails, one warning names what to install, and the tile renders on three. With
 // neither, `ready` rejects naming both. An explicit `engine` never falls back.
 
+import { guardedAttach } from './inline3d-splat-shared.js';
 /** The engines `addModel` renders with; the first is the default. */
 export const MODEL_ENGINES = Object.freeze(['playcanvas', 'three']);
 
@@ -98,6 +99,12 @@ export function validateModelCall(canvas, src, opts, route) {
  *          fill in as the backend loads.
  */
 export function addModel(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addModel', opts, (o) => addModelUnguarded(wall, canvas, src, o));
+}
+
+function addModelUnguarded(wall, canvas, src, opts = {}) {
   const route = resolveModelEngine(opts);
   validateModelCall(canvas, src, opts, route);
   if (route.engine === 'playcanvas') {

package/js/inline3d-model-playcanvas.js

@@ -531,6 +531,11 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();

package/js/inline3d-model.js

@@ -38,6 +38,7 @@
 // your own origin (`/draco/`, `/basis/`) and `opts.decoderPath` moves that. See
 // docs/authoring-inline-3d.md#compressed-gltf.
 
+import { guardedAttach } from './inline3d-splat-shared.js';
 import * as THREE from 'three';
 import { EyeCamera, EdgeFeather, DepthCursor, raycastHitTest } from './inline3d-three.js';
 import { resolveCursorOption } from './inline3d-cursor-depth.js';
@@ -345,6 +346,12 @@ function kindFromMessage(msg) {
  *          `setPose`, `resetPose`, `frame`, and `ready`.
  */
 export function addModel(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addModel', opts, (o) => addModelUnguarded(wall, canvas, src, o));
+}
+
+function addModelUnguarded(wall, canvas, src, opts = {}) {
   const {
     virtualDisplayHeight = 0.24,
     frame = null,
@@ -426,6 +433,11 @@ export function addModel(wall, canvas, src, opts = {}) {
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();

package/js/inline3d-splat-deferred.js

@@ -83,6 +83,11 @@ export function addSplatDeferred(wall, canvas, src, opts) {
     // setSource replaces this stub on the same object by then).
     setSource: (...args) => out.ready.then(() => out.setSource(...args)),
     prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
+    // Nothing can be mid-transition before the adapter has loaded; the adapter replaces this.
+    finishSwap: () => out,
+    // `rewoven()` before the adapter: the core window's answer once it exists, `firstWoven`'s
+    // result if the engine never arrives (same shape, never rejects).
+    rewoven: () => out.ready.then(() => out.rewoven(), () => out.firstWoven),
     // A rig switch before the first asset has landed: validated now (controls:'page' and a bad
     // type throw at the call's own line), applied once it has.
     setRig: page

package/js/inline3d-splat-pc-entry.js

@@ -16,7 +16,7 @@
 // Not here: measureSplatBounds (it measures a Spark mesh — import it from ./splat).
 
 import { resolveRevealOption } from './inline3d-splat-effects.js';
-import { CAPTURE_FITS, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
+import { CAPTURE_FITS, guardedAttach, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
 import { addSplatDeferred } from './inline3d-splat-deferred.js';
 
 export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
@@ -25,6 +25,12 @@ export { resolveRig } from './inline3d-splat-rig.js';
 
 /** addSplat with `engine: 'playcanvas'`; the same validation, at the call, as ./splat's. */
 export function addSplat(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addSplat', opts, (o) => addSplatUnguarded(wall, canvas, src, o));
+}
+
+function addSplatUnguarded(wall, canvas, src, opts = {}) {
   if (opts.engine !== undefined && opts.engine !== 'playcanvas') {
     throw new Error(
       `@displayxr/inline3d/splat/playcanvas: engine "${opts.engine}" — this entry is PlayCanvas ` +

package/js/inline3d-splat-playcanvas.js

@@ -1002,7 +1002,11 @@ export class PlayCanvasSplatViewer {
     this._tileBudget = undefined; // undefined = the engine's own default
     this._budgetViews = 1;
 
-    this._onResize = () => this._scheduleResize();
+    // Resize AND draw inside the observer callback (it runs after the frame's animation callbacks
+    // and before the paint). Deferring to the next animation frame, as this used to, let one
+    // paint show the old backing store stretched onto the new box: a visible jolt on every
+    // CSS resize of a woven canvas. See _resizeNow for the two cases that still defer.
+    this._onResize = () => this._resizeNow();
     this._ro = typeof ResizeObserver === 'function' ? new ResizeObserver(this._onResize) : null;
     if (this._ro) this._ro.observe(canvas);
     else if (typeof addEventListener === 'function') addEventListener('resize', this._onResize);
@@ -1231,7 +1235,7 @@ export class PlayCanvasSplatViewer {
     this._beforeFrame?.(views || null);
     this._tick();
     if (!views || views.length < 2) {
-      this._replayLastGood();
+      this._replayOrFlat();
       return;
     }
     const vps = this._vps;
@@ -1239,7 +1243,7 @@ export class PlayCanvasSplatViewer {
     for (const view of views) {
       const vp = layer && typeof layer.getViewport === 'function' ? layer.getViewport(view) : null;
       if (!vp || !(vp.width > 0) || !(vp.height > 0)) {
-        this._replayLastGood();
+        this._replayOrFlat();
         return;
       }
       vps.push(vp);
@@ -2010,6 +2014,17 @@ export class PlayCanvasSplatViewer {
    * engine tick. Every entry is {proj, pose, x, y, width, height} in BUFFER pixels.
    */
   _drawEntries(entries, cache) {
+    // `_drawing` is what _resizeNow checks: never reallocate the buffer under a running render.
+    if (this._drawing) return this._drawEntriesInner(entries, cache);
+    this._drawing = true;
+    try {
+      return this._drawEntriesInner(entries, cache);
+    } finally {
+      this._drawing = false;
+    }
+  }
+
+  _drawEntriesInner(entries, cache) {
     const app = this.app;
     if (!app || !this.pc) return false;
     const pc = this.pc;
@@ -2139,6 +2154,7 @@ export class PlayCanvasSplatViewer {
     }
     g.bufW = el.width || 0;
     g.bufH = el.height || 0;
+    g.boxAspect = this.boxAspect || 0; // the CSS shape these views were located for (see _replayLastGood)
     g.rig = this._rigSnap ? { ...this._rigSnap } : null; // a replay re-uses the rig of its views
     g.rigAt = this._rigAtPull ?? null;
     for (let i = 0; i < views.length; i++) {
@@ -2153,10 +2169,90 @@ export class PlayCanvasSplatViewer {
     }
   }
 
+  /**
+   * A session frame that cannot draw its own views still PRESENTS: the last good frame, or —
+   * before there is one — the mono camera into both halves (flat, the subject if loaded, else
+   * the clear colour). A woven canvas that is not redrawn can drop out of the frame the
+   * compositor aggregates (woven-canvas-rules, "redraw every frame"), and a load-fallback frame
+   * before the first stereo one is exactly when no cache exists. The only frame this cannot
+   * cover is one before the engine has attached: there is no GL context yet, and creating one
+   * here would create it with the wrong attributes.
+   */
+  _replayOrFlat() {
+    return this._replayLastGood() || this._drawFlatPair();
+  }
+
+  _drawFlatPair() {
+    if (this._disposed || !this.app || !this.pc) return false;
+    const b = this._bufScale();
+    const W = b.w || this.canvas.width;
+    const H = b.h || this.canvas.height;
+    if (!(W > 1) || !(H > 0)) return false;
+    const half = Math.floor(W / 2);
+    const v = this._monoView();
+    const pair = (this._flatPair ||= [0, 1].map(() => ({ proj: null, pose: null, x: 0, y: 0, width: 0, height: 0 })));
+    for (let i = 0; i < 2; i++) {
+      const e = pair[i];
+      e.proj = v.proj;
+      e.pose = v.pose;
+      e.x = i * half;
+      e.y = 0;
+      e.width = half;
+      e.height = H;
+    }
+    return this._drawEntries(pair, null);
+  }
+
   _replayLastGood() {
     const g = this._lastGood;
     if (!g || this._disposed) return false;
-    return this._drawEntries(g.entries, g);
+    // A box whose aspect changed since the cache (a CSS resize replayed before the runtime has
+    // located views for the new rect): the cached frustum was built for the OLD shape, and the
+    // viewports map onto the new buffer proportionally, so the picture would be stretched by
+    // exactly the aspect ratio change. Widen (or narrow) the frustum by the same factor —
+    // dividing the projection's x row by it — so the replayed frame keeps its proportions. One
+    // frame's approximation: the next located views carry the true frustum for the new window.
+    const f = g.boxAspect > 0 && this.boxAspect > 0 ? this.boxAspect / g.boxAspect : 1;
+    if (Math.abs(f - 1) < 1e-6) return this._drawEntries(g.entries, g);
+    const fixed = (this._aspectFixed ||= []);
+    fixed.length = g.entries.length;
+    for (let i = 0; i < g.entries.length; i++) {
+      const e = g.entries[i];
+      const o = (fixed[i] ||= { proj: new Float32Array(16), pose: null, x: 0, y: 0, width: 0, height: 0 });
+      o.proj.set(e.proj);
+      o.proj[0] /= f;
+      o.proj[4] /= f;
+      o.proj[8] /= f;
+      o.proj[12] /= f;
+      o.pose = e.pose;
+      o.x = e.x;
+      o.y = e.y;
+      o.width = e.width;
+      o.height = e.height;
+    }
+    return this._drawEntries(fixed, g);
+  }
+
+  /**
+   * The observer's resize, synchronous. Two cases still take the debounced path instead: a call
+   * that arrives while this viewer is already resizing (re-entrancy: setting canvas.width can
+   * queue more observer work), and one that arrives while it is drawing (a nested dispatch from
+   * inside the engine's tick). Reallocating the drawing buffer under a running render would
+   * leave that render half on a cleared store.
+   */
+  _resizeNow() {
+    if (this._disposed) return;
+    if (this._inResize || this._drawing) {
+      this._scheduleResize();
+      return;
+    }
+    this._resizePending = false; // this run supersedes a debounced one already queued
+    this._inResize = true;
+    try {
+      this._resize();
+    } finally {
+      this._inResize = false;
+    }
   }
 
   _scheduleResize() {
@@ -3370,6 +3466,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       return pickModel(clientX, clientY);
     },
     setSource,
+    /**
+     * End a running setSource transition now (its end state at once); a no-op when none runs.
+     * The same thing a newer setSource does to an older one in flight (`pendingSwap.finish()`),
+     * exposed for a page that leaves the photo mid-crossfade and must not wait for it.
+     */
+    finishSwap() {
+      pendingSwap?.finish();
+      return out;
+    },
     prepareSource,
     setRig,
     setStereo,
@@ -3590,6 +3695,11 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();
@@ -3633,6 +3743,11 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     out._resolveFirstWoven(handle ? handle.firstWoven : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 })));
     delete out._resolveFirstWoven;
   }
+  // The core window's `rewoven()`, forwarded like `firstWoven`: a page covers the canvas across a
+  // rect change (a shared canvas moved into a box, fullscreen) and releases on this. Without a
+  // session it settles `woven: false, reason: 'unsupported'` at once, the same shape. Replaces the
+  // deferred stub's forwarder, as `setSource` does.
+  out.rewoven = () => (handle && typeof handle.rewoven === 'function' ? handle.rewoven() : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 })));
 
   // addSplat's `displayRigLayers` sugar: [layer, …] or { layers: [...], viewerDistance, gain }.
   if (opts.displayRigLayers !== undefined) {

package/js/inline3d-splat-shared.js

@@ -12,6 +12,23 @@
 // apart on how a drag, a wheel notch, an idle turntable or a focus change feels. Pinned by
 // test/splat-playcanvas.test.mjs (values, and a behavioural trace of both viewers side by side).
 
+/**
+ * Double-attach detection around a scene subpath's public entry (`addSplat`, `addModel`).
+ *
+ * The check has to run HERE, at the entry, and not only in the core's addScene: the subpaths build
+ * a renderer on the canvas BEFORE the core window exists (asynchronously, once the engine module
+ * has loaded), so a second `addSplat` during the first one's load would never reach the core's
+ * check in time. `wall._attachGuard` (the core manager) warns once per canvas and claims it; the
+ * call then proceeds exactly as before. A wall without it (no session, an older core) attaches as is.
+ */
+export function guardedAttach(wall, canvas, method, opts, attach) {
+  const g = wall && typeof wall._attachGuard === 'function' ? wall._attachGuard(canvas, method, opts) : null;
+  if (!g) return attach(opts);
+  const out = attach(g.opts);
+  g.own(out);
+  return out;
+}
+
 /**
  * Backstop on total subject depth, as a multiple of the display height. Generous on purpose:
  * depth placement is a z decision (see fitTo), not a scale one, so this only catches the

package/js/inline3d-splat.js

@@ -39,6 +39,7 @@ import {
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
   declareViewRig,
+  guardedAttach,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -162,6 +163,12 @@ function sniffFileType(bytes) {
  * good enough for a clean, isolated capture, weaker on a scene with a background wall.
  */
 export function addSplat(wall, canvas, src, opts = {}) {
+  // A second call on a canvas still registered on this wall warns once, then proceeds as before
+  // (see guardedAttach).
+  return guardedAttach(wall, canvas, 'addSplat', opts, (o) => addSplatUnguarded(wall, canvas, src, o));
+}
+
+function addSplatUnguarded(wall, canvas, src, opts = {}) {
   if (opts.captureFit !== undefined && !CAPTURE_FITS.includes(opts.captureFit)) {
     throw new Error(
       `@displayxr/inline3d/splat: captureFit "${opts.captureFit}" — expected ` +
@@ -487,6 +494,11 @@ export function addSplat(wall, canvas, src, opts = {}) {
       bufferClamped: true, // this viewer clamps its own buffer; the core must never touch its context
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
+      // The SDK covers this canvas across a move/resize (core rectCover): on by default here, the
+      // preview tier; 'off' for a page that runs its own cover.
+      rectCover: opts.rectCover === undefined ? 'auto' : opts.rectCover,
+      // The entry's double-attach claim (guardedAttach): lets THIS registration through.
+      _dxrClaim: opts._dxrClaim,
     });
   } else {
     viewer.startMono();