@displayxr/inline3d 1.9.1 → 1.10.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.10.0 — 2026-09-23
+
+Touches the **core tier** (`.`), additively. The frozen 1.x surface gains one handle member and
+one option, and nothing that exists changes behaviour. The preview subpaths (`./splat`,
+`./model`) forward the new member. No pixels move for any page that does not read it.
+
+### Added
+
+- **`handle.firstWoven`**: a promise that tells the page when it is safe to reveal a woven canvas
+  (core tier; web#36 follow-up).
+  - It resolves once and never rejects, with `{ woven, confirmed, reason, ms }`.
+  - `woven: true` means a real stereo frame is on a layer that has existed for
+    `firstWovenHoldMs`.
+  - `woven: false` (`'layer-failed'` / `'session-ended'` / `'removed'`) means the window will not
+    weave. The canvas is already flat, or the scene's `onLayerLost` has already run.
+  - `onFirstWoven(cb)` is the callback form.
+  - It replaces the worst-case `setTimeout` that pages kept to hide the raw side-by-side pair a
+    fresh canvas shows until the browser's compositor joins it.
+- **`firstWovenHoldMs`** on every `add*()` (default **1200**, the browser's measured worst case
+  for a canvas that is fresh to its compositor).
+- **It is approximate, by design, and says so.** No browser reports the join yet (checked
+  against the browser's JavaScript surface: the verdict exists only as a compositor log line). So
+  `confirmed` is always `false` and the result is the hold. When a browser reports joins it
+  becomes `confirmed: true` and earlier, with no change to the page. The browser ask is
+  [`docs/proposals/layer-joined-signal.md`](docs/proposals/layer-joined-signal.md).
+- `addSplat` (both engines) and `addModel` handles carry `firstWoven` and accept
+  `firstWovenHoldMs` (preview tier). With no inline-3D session they resolve
+  `{ woven: false, reason: 'unsupported' }` at once.
+- Docs: **[`docs/woven-canvas-rules.md`](docs/woven-canvas-rules.md)**: eight rules for never
+  showing a raw side-by-side frame. Each rule comes with its reason and the SDK call that
+  satisfies it, plus a hardware checklist keyed on the browser's
+  `withheld … ids=[<token>=<why>@<rect>]` log line. There is a summary section in the authoring
+  guide, and links from the porting guide and the README.
+  - It corrects two claims in circulation. **No shipping browser draws a flat frame instead of
+    the raw pair** for a fresh canvas: that fallback was measured and not shipped. And the
+    `withheld` line is logged at error level with throttling, so a missing line proves nothing.
+
 ## 1.9.1 — 2026-09-23
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), plus the package manifest.

package/README.md

@@ -110,6 +110,9 @@ No projection math lands in your page or in the SDK — the off-axis frustum sta
 > `createInline3D()` detects by actually acquiring a session, which is authoritative.
 
 Full API + authoring guidance: [`docs/authoring-inline-3d.md`](docs/authoring-inline-3d.md).
+Before you ship a page that navigates or remounts, read
+[`docs/woven-canvas-rules.md`](docs/woven-canvas-rules.md): how to avoid a raw side-by-side
+flash, and releasing a poster on `handle.firstWoven`.
 Three.js glue (an off-axis `EyeCamera`) in [`js/inline3d-three.js`](js/inline3d-three.js).
 
 ## What's here
@@ -145,6 +148,9 @@ docs/
                            that is not the API
   porting-three-js-apps.md porting an existing three.js app (WebXR or plain) to inline 3D —
                            the WebXR→inline-3d mapping table and the whole render loop
+  woven-canvas-rules.md    never show a raw side-by-side frame: the join, the eight rules,
+                           handle.firstWoven, reading the browser's `withheld` log line
+  proposals/               browser-side asks the SDK is waiting on
 ```
 
 ## The inline-3D model (under the SDK)

package/index.d.ts

@@ -11,6 +11,34 @@ export interface TileOptions {
   cornerRadius?: number;
   /** Fade each eye's outer edges to transparent over this many buffer px. */
   feather?: number;
+  /**
+   * How long, in ms, this window's layer must have existed (and carried a stereo frame) before
+   * {@link TileHandle.firstWoven} resolves `woven: true`. Default 1200 — the browser's measured
+   * worst case for joining a canvas that is fresh to its compositor. Lower it only for a canvas
+   * you know is not fresh; 0 means "the first stereo frame".
+   */
+  firstWovenHoldMs?: number;
+}
+
+/**
+ * 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: 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.
+   */
+  readonly confirmed: boolean;
+  readonly reason: 'hold-elapsed' | 'layer-failed' | 'session-ended' | 'removed' | 'unsupported';
+  /** Milliseconds from the add*() call to settling. */
+  readonly ms: number;
 }
 
 /**
@@ -306,6 +334,14 @@ export interface TileHandle {
    * Scene windows only — image/video windows always report `{ frames: 0, monoFrames: 0 }`.
    */
   stats(): { frames: number; monoFrames: number };
+  /**
+   * 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`).
+   */
+  readonly firstWoven: Promise<FirstWovenResult>;
+  /** Callback form of {@link TileHandle.firstWoven}: called once, asynchronously. Returns an unsubscribe. */
+  onFirstWoven(cb: (result: FirstWovenResult) => void): () => void;
 }
 
 /** An open inline-3D session you add weaved windows to. Returned by {@link createInline3D}. */

package/js/inline3d-model.js

@@ -363,6 +363,7 @@ export function addModel(wall, canvas, src, opts = {}) {
     KTX2Loader: injectedKtx2 = null,
     meshoptDecoder: injectedMeshopt = null,
     observe,
+    firstWovenHoldMs,
   } = opts;
 
   const paths = normalizeDecoderPath(decoderPath);
@@ -413,10 +414,13 @@ export function addModel(wall, canvas, src, opts = {}) {
       // canvas flat rather than leave its last side-by-side frame on the page (web#28).
       onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
+      ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
     });
   } else {
     viewer.startMono();
   }
+  // The core handle's `firstWoven`, forwarded; a page with no session is told so at once.
+  out.firstWoven = handle ? handle.firstWoven : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 }));
 
   out.ready = (async () => {
     const Loader = await resolveLoader(injectedLoader);

package/js/inline3d-splat-playcanvas.js

@@ -1685,6 +1685,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     captureFit = 'height',
     focusInput = true,
     observe,
+    firstWovenHoldMs,
     preserveDrawingBuffer = false,
   } = opts;
   // `sortIntervalMs` is accepted and has no effect here: the engine re-sorts when the camera
@@ -1773,10 +1774,16 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       virtualDisplayHeight,
       onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
+      ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
     });
   } else {
     viewer.startMono();
   }
+  // Settle the stub's `firstWoven` (addSplatDeferred) with the core handle's own.
+  if (typeof out._resolveFirstWoven === 'function') {
+    out._resolveFirstWoven(handle ? handle.firstWoven : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 })));
+    delete out._resolveFirstWoven;
+  }
 
   // Replay what the page did before this module arrived — exclude() above all, which a product
   // page calls on the very next line after addSplat.

package/js/inline3d-splat.js

@@ -212,6 +212,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
     fileName,
     fileType,
     observe,
+    firstWovenHoldMs,
   } = opts;
 
   const viewer = new SceneViewer(THREE, canvas, {
@@ -392,10 +393,13 @@ export function addSplat(wall, canvas, src, opts = {}) {
       // canvas flat rather than leave its last side-by-side frame on the page (web#28).
       onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
+      ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
     });
   } else {
     viewer.startMono();
   }
+  // The core handle's `firstWoven`, forwarded; a page with no session is told so at once.
+  out.firstWoven = handle ? handle.firstWoven : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 }));
 
 
   // ── focus: declaring it, and the two gestures that change it ──────────────────────────
@@ -644,12 +648,21 @@ function addSplatDeferred(wall, canvas, src, opts) {
     exclude: queue('exclude'),
     unexclude: queue('unexclude'),
   };
+  // `firstWoven` exists from the first line, like every other field a page reads right away; the
+  // adapter settles it with the core handle's own once the module has loaded.
+  out.firstWoven = new Promise((resolve) => {
+    out._resolveFirstWoven = resolve;
+  });
   // The ONE owner of `ready`: the adapter returns its load promise and never touches this field.
   out.ready = import('./inline3d-splat-playcanvas.js')
     .then((m) => m.attachPlayCanvasSplat(out, wall, canvas, src, opts, pending))
     .catch((err) => {
       // The adapter warns about its own load failures; this is for the module not arriving.
       if (!out.viewer) console.warn('[inline3d/splat] engine:playcanvas failed to start', err);
+      if (out._resolveFirstWoven) {
+        out._resolveFirstWoven(Object.freeze({ woven: false, confirmed: false, reason: 'layer-failed', ms: 0 }));
+        delete out._resolveFirstWoven;
+      }
       throw err;
     });
   return out;

package/js/inline3d.js

@@ -375,6 +375,15 @@ function nowMs() {
     : Date.now();
 }
 
+// First-woven hold (web#36 follow-up): how long after a window's layer is constructed the SDK
+// assumes the browser MAY still be failing to join the canvas, and therefore still showing the
+// page's own raster of it — the raw side-by-side pair. The browser measures that window at
+// 0.4–1.2 s for a canvas that is fresh to its compositor (a same-document navigation creates
+// one); this is its upper bound. Nothing the page can observe today says when the join actually
+// landed (docs/proposals/layer-joined-signal.md), so `handle.firstWoven` is this timer, not a
+// report. Per-window override: `firstWovenHoldMs` on any add*() call.
+const FIRST_WOVEN_HOLD_MS = 1200;
+
 // The easing option, validated here rather than in the state machine: the sequencer falls back
 // silently (it has no opinion about a caller's config), but a typo in `createInline3D` is worth
 // exactly one warning — a page that asked for 'ease-in-out' and got smoothstep should know.
@@ -1055,6 +1064,44 @@ class Inline3D {
       // Read-only counters, for pages that want to see the load-induced mono fallback rather
       // than wait for a bug report about "blinking". Scene windows only; 0/0 elsewhere.
       stats: () => ({ frames: win.frames, monoFrames: win.monoFrames }),
+      /**
+       * Resolves ONCE, never rejects: `{ woven, confirmed, reason, ms }`.
+       *
+       * `woven: true` — the window has drawn a stereo frame on a layer that has existed for
+       * `firstWovenHoldMs` (default 1200). That is the moment to drop a poster covering the
+       * canvas. `confirmed` is `false` today, always: no browser reports when its compositor
+       * actually joined a canvas, so this is the browser's worst case, measured by the SDK so
+       * pages stop measuring it themselves. It becomes a reported fact (`confirmed: true`, no
+       * hold) when a browser can say so, with no change to the page.
+       *
+       * `woven: false` — this window will not weave: `reason` is `'layer-failed'`,
+       * `'session-ended'` or `'removed'`. The SDK has already taken an image/video canvas flat,
+       * and a scene's `onLayerLost` has already run. Release the poster onto the 2D fallback.
+       *
+       * `ms` is the time from the add*() call to settling.
+       */
+      get firstWoven() {
+        return win.fwPromise;
+      },
+      /**
+       * Callback form of {@link firstWoven}: `cb(result)` once, asynchronously, even when it has
+       * already settled. Returns an unsubscribe function.
+       */
+      onFirstWoven: (cb) => {
+        if (typeof cb !== 'function') throw new TypeError('[inline3d] onFirstWoven() takes a function.');
+        let live = true;
+        win.fwPromise.then((r) => {
+          if (!live) return;
+          try {
+            cb(r);
+          } catch (err) {
+            console.error('[inline3d] onFirstWoven callback threw', err);
+          }
+        });
+        return () => {
+          live = false;
+        };
+      },
     };
   }
 
@@ -1793,7 +1840,23 @@ class Inline3D {
       // onFrame deliveries; monoFrames counts the ones that carried fewer than two views.
       frames: 0,
       monoFrames: 0,
+      // handle.firstWoven (web#36 follow-up). One-shot per window: `fwResult` is the settled
+      // value, null while pending. `fwLayerAt` is when the CURRENT layer was built (null = none);
+      // `fwStereo` whether that layer has since carried a real stereo frame. _activate resets both
+      // for every new layer of a pending window, so a lazy tile that scrolls away before settling
+      // earns it again on its next layer rather than inheriting time from the closed one (a
+      // window with no layer is skipped by _frame, so nothing ticks in between).
+      fwResult: null,
+      fwResolve: null,
+      fwPromise: null,
+      fwHoldMs: firstWovenHold(opts.firstWovenHoldMs),
+      fwRegAt: nowMs(),
+      fwLayerAt: null,
+      fwStereo: false,
     };
+    win.fwPromise = new Promise((resolve) => {
+      win.fwResolve = resolve;
+    });
     this._windows.set(canvas, win);
     if (this._lazy && this._observer) {
       this._observer.observe(win.observeEl);
@@ -1809,6 +1872,7 @@ class Inline3D {
     if (this._observer) this._observer.unobserve(win.observeEl);
     this._deactivate(win);
     this._windows.delete(canvas);
+    this._settleFirstWoven(win, false, 'removed');
   }
 
   _onIntersect(entries) {
@@ -1874,8 +1938,15 @@ class Inline3D {
       }
       this._paintMono(win);
       this._notifyLayerLost(win);
+      // After the mono paint and the scene's own notification, so a page that releases its
+      // poster on this finds the canvas already flat underneath it.
+      this._settleFirstWoven(win, false, 'layer-failed');
       return;
     }
+    if (!win.fwResult) {
+      win.fwLayerAt = nowMs();
+      win.fwStereo = false;
+    }
     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
@@ -2409,6 +2480,9 @@ class Inline3D {
           // (see the note below), so one broken tile took its neighbours' weave with it (web#28).
           try {
             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;
           } catch (err) {
             if (!win.frameThrewWarned) {
               win.frameThrewWarned = true;
@@ -2427,10 +2501,40 @@ class Inline3D {
         // sub-rect and the window flickers to a horizontal smear. A still image's
         // redraw is one cheap GPU drawImage — keep it live.
         this._paint(win, views);
+        // An SBS paint with a real source behind it. Before the image has loaded (or while a
+        // 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;
+        }
       }
+      this._tickFirstWoven(win);
     }
   }
 
+  /**
+   * Settle `firstWoven` as woven once BOTH halves hold: the current layer has carried a stereo
+   * frame, and it has existed for the hold. Per session frame, per live window — two compares
+   * while pending, one while settled.
+   *
+   * This is where a browser-reported join would plug in (a confirmed result, no hold). No
+   * browser exposes one today; see docs/proposals/layer-joined-signal.md. It is deliberately
+   * NOT inferred from anything the session does report: views arrive from the runtime's locate,
+   * which knows nothing about whether the compositor has matched this canvas yet.
+   */
+  _tickFirstWoven(win) {
+    if (win.fwResult || !win.fwStereo || win.fwLayerAt === null) return;
+    if (nowMs() - win.fwLayerAt < win.fwHoldMs) return;
+    this._settleFirstWoven(win, true, 'hold-elapsed');
+  }
+
+  /** One-shot: the first call wins, later ones are ignored. */
+  _settleFirstWoven(win, woven, 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;
+  }
+
   // ── page lifecycle: bfcache, freeze, restore (browser#87) ───────────────────────────
   //
   // A weaved window's rect reaches the compositor from the session's own rAF: every frame the
@@ -2562,6 +2666,7 @@ class Inline3D {
       // thing that must not be. AFTER the close, so the flat frame is the last thing committed.
       this._paintMono(win);
       this._notifyLayerLost(win);
+      this._settleFirstWoven(win, false, 'session-ended');
     }
     this._windows.clear();
     // Page listeners go with the session that fed them: a manager whose session has ended will
@@ -2572,6 +2677,11 @@ class Inline3D {
 
 // ── small helpers ─────────────────────────────────────────────────────────────────────
 
+/** `firstWovenHoldMs`, validated: a finite number >= 0, else the default. */
+function firstWovenHold(v) {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : FIRST_WOVEN_HOLD_MS;
+}
+
 function loadImage(source) {
   if (typeof source !== 'string') return Promise.resolve(source); // element/bitmap/canvas
   return new Promise((resolve, reject) => {

package/model.d.ts

@@ -2,6 +2,7 @@
 // EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
+import type { FirstWovenResult } from './index.js';
 
 export interface ModelOptions {
   /** Metres of world the tile's height spans (default 0.24). */
@@ -72,6 +73,8 @@ export interface ModelOptions {
 
   /** Element whose visibility gates the lazy create/close lifecycle. */
   observe?: Element;
+  /** Forwarded to the core window: see `TileOptions.firstWovenHoldMs`. */
+  firstWovenHoldMs?: number;
 }
 
 /** What {@link addModel} returns — the same shape as addSplat's handle. */
@@ -90,6 +93,11 @@ export interface ModelHandle {
   remove(): void;
   exclude(el: Element): void;
   unexclude(el: Element): void;
+  /**
+   * The core window's `TileHandle.firstWoven`: when it is safe to reveal the canvas. Resolves
+   * `{ woven: false, reason: 'unsupported' }` at once where there is no inline-3D session.
+   */
+  readonly firstWoven: Promise<FirstWovenResult>;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.9.1",
+  "version": "1.10.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",

package/splat.d.ts

@@ -2,6 +2,7 @@
 // EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
+import type { FirstWovenResult } from './index.js';
 
 /**
  * The knobs behind `SplatOptions.perf`. Every one is a Spark 2.1.0 setting except `alphaRadius`,
@@ -296,6 +297,8 @@ export interface SplatOptions {
   fileType?: 'ply' | 'spz' | 'splat' | 'ksplat' | 'pcsogs' | 'pcsogszip' | 'rad';
   /** Element whose visibility gates the lazy create/close lifecycle. */
   observe?: Element;
+  /** Forwarded to the core window: see `TileOptions.firstWovenHoldMs`. */
+  firstWovenHoldMs?: number;
 }
 
 /** `handle.stats()` on `engine: 'playcanvas'`. */
@@ -422,6 +425,11 @@ export interface SplatHandle {
   /** Mark a 2D element painted over this window so the weave leaves it crisp. */
   exclude(el: Element): void;
   unexclude(el: Element): void;
+  /**
+   * The core window's `TileHandle.firstWoven`: when it is safe to reveal the canvas. Resolves
+   * `{ woven: false, reason: 'unsupported' }` at once where there is no inline-3D session.
+   */
+  readonly firstWoven: Promise<FirstWovenResult>;
 }
 
 /**