@displayxr/inline3d 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ 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.
+Nothing changes for Spark callers or for splat-only pages. The fixes affect only what a page can
+do with `handle.engine`.
+
+### Fixed
+
+- **`handle.engine.root` is usable as documented.** The tile's `AppBase` now registers `Render`,
+  `Light` and `Anim` component systems and a `Container` resource handler, next to `Camera`,
+  `GSplat` and `Texture`/`GSplat`. That is exactly what a glTF needs, skinned and animated
+  included. Before, a page had to register them itself or `instantiateRenderEntity()` produced
+  nothing.
+  - A page that still registers them now gets the existing system back instead of an engine
+    "already registered" throw.
+  - Cost: +0.1 ms boot (`AppBase.init` 0.4 → 0.5 ms). +41.8 KB gzip only for a hand-tree-shaken
+    engine build; nothing for the SDK as shipped.
+  - Verified with a skinned, animated `.glb` over a splat: composited, depth-tested against nearer
+    splats, animation advancing.
+- **`"./package.json"` is exported**, so `import pkg from '@displayxr/inline3d/package.json'` and
+  `require.resolve('@displayxr/inline3d/package.json')` work instead of
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+### Added
+
+- **`nearClip` / `farClip`** (PlayCanvas): a floor on the projection's near plane and a cap on its
+  far plane, for depth precision in a mixed mesh + splat scene. The adapter still owns the
+  projections, and unset leaves them untouched.
+- Docs: `handle.engine` in [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md). Covers what
+  is registered, the cost, and two engine gotchas (lights shine along local −Y; use `AnimTrack.name`
+  with `assignAnimation`).
+
 ## 1.9.0 — 2026-09-23
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive: nothing changes for

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

@@ -84,6 +84,54 @@ import {
   streamedBytesError,
 } from './inline3d-splat-shared.js';
 
+/**
+ * The component systems the tile's `AppBase` registers. Camera + GSplat draw the splat; Render,
+ * Light and Anim are what a page needs to put a glTF — skinned and animated included — and its
+ * lights under `handle.engine.root` (1.9.1; before that the page had to register them itself).
+ * Nothing else from the engine's full `Application` list (physics, UI, audio, particles, scripts
+ * and so on are the page's own business if it wants them).
+ */
+export const PLAYCANVAS_SYSTEMS = Object.freeze([
+  'CameraComponentSystem',
+  'GSplatComponentSystem',
+  'RenderComponentSystem',
+  'LightComponentSystem',
+  'AnimComponentSystem',
+]);
+
+/**
+ * The resource handlers the tile's loader registers. Texture + GSplat load a splat (a bundled
+ * .sog is a zip of webp planes the loader registers as textures); Container loads a .glb/.gltf.
+ * The container's sub-assets (render, material, animation) arrive already loaded, so they need no
+ * handler of their own.
+ */
+export const PLAYCANVAS_HANDLERS = Object.freeze(['TextureHandler', 'GSplatHandler', 'ContainerHandler']);
+
+/**
+ * Registering a component system the app already has THROWS in the engine ("already
+ * registered"). Pages written before 1.9.1 add Render/Light/Anim themselves, so a second `add` of
+ * an id that exists is made a no-op that returns the registered system (the duplicate the page
+ * constructed is destroyed, so it leaves no listeners behind).
+ */
+function guardDuplicateSystems(app) {
+  const reg = app.systems;
+  if (!reg || typeof reg.add !== 'function' || reg._dxrGuarded) return;
+  const add = reg.add.bind(reg);
+  reg.add = (system) => {
+    const existing = system?.id ? reg[system.id] : null;
+    if (existing && existing !== system) {
+      try {
+        system.destroy?.();
+      } catch {
+        /* a half-built duplicate: nothing to release */
+      }
+      return existing;
+    }
+    return add(system);
+  };
+  reg._dxrGuarded = true;
+}
+
 /** The engine release this adapter was built and measured against (npm peer floor). */
 export const PLAYCANVAS_TESTED = '2.22.3';
 
@@ -138,6 +186,24 @@ export function frustumFromProjection(P) {
   };
 }
 
+/**
+ * Raise a perspective projection's near plane to at least `nearFloor` and lower its far plane to
+ * at most `farCap`, IN PLACE, leaving the frustum's shape (fov, skew, principal point) untouched —
+ * only the depth mapping (P[10], P[14]) is rewritten. Idempotent. A null bound is left alone.
+ */
+export function clampProjectionDepth(P, nearFloor, farCap) {
+  const f0 = frustumFromProjection(P);
+  let n = f0.nearClip;
+  let f = f0.farClip;
+  if (nearFloor !== null && nearFloor !== undefined && nearFloor > n) n = nearFloor;
+  if (farCap !== null && farCap !== undefined && farCap < f) f = farCap;
+  if (!(f > n)) f = n * 1.0001 + 1e-6;
+  if (n === f0.nearClip && f === f0.farClip) return P;
+  P[10] = -(f + n) / (f - n);
+  P[14] = (-2 * f * n) / (f - n);
+  return P;
+}
+
 /** Rigid pose (position + unit quaternion xyzw) as a column-major 4×4. */
 export function poseMatrix(p, q, out = new Float64Array(16)) {
   const [x, y, z, w] = q;
@@ -467,8 +533,15 @@ export class PlayCanvasSplatViewer {
       orbitEase = {},
       feather = 0,
       captureFit = 'height',
+      nearClip,
+      farClip,
     } = opts;
     this.canvas = canvas;
+    // Depth range for a MIXED scene (meshes under handle.engine.root depth-test against each
+    // other; splats only test against them). The projections' own near/far stay the adapter's —
+    // these only raise the near (floor) and lower the far (cap). Unset: untouched.
+    this.nearClip = Number.isFinite(nearClip) && nearClip > 0 ? nearClip : null;
+    this.farClip = Number.isFinite(farClip) && farClip > 0 ? farClip : null;
     // The tilt-and-relax orbit (./inline3d-splat-shared.js §ORBIT): drag tilts up to ±orbitMaxDeg
     // from where the press started, easing with τ = orbitEase.drag; release relaxes back with
     // τ = orbitEase.rest. `_orbitMode` is 'drag' | 'rest' | null (null = ordinary damping).
@@ -784,12 +857,14 @@ export class PlayCanvasSplatViewer {
     const opts = new pc.AppOptions();
     opts.graphicsDevice = device;
     // No xr (AppBase constructs XrManager only when asked, and XrManager is what probes and
-    // can request immersive sessions), no mouse/keyboard/touch: the SDK owns input.
-    opts.componentSystems = [pc.CameraComponentSystem, pc.GSplatComponentSystem];
-    // TextureHandler: a bundled .sog is a zip of webp planes the loader registers as textures.
-    opts.resourceHandlers = [pc.TextureHandler, pc.GSplatHandler];
+    // can request immersive sessions), no mouse/keyboard/touch: the SDK owns input. Beyond the
+    // splat itself, exactly what a glTF-with-animation under `handle.engine.root` needs — see
+    // PLAYCANVAS_SYSTEMS / PLAYCANVAS_HANDLERS.
+    opts.componentSystems = PLAYCANVAS_SYSTEMS.map((n) => pc[n]).filter(Boolean);
+    opts.resourceHandlers = PLAYCANVAS_HANDLERS.map((n) => pc[n]).filter(Boolean);
     const app = new pc.AppBase(this.canvas);
     app.init(opts);
+    guardDuplicateSystems(app);
     // The SDK sizes the buffer (double-width in 3D, 1:1 in mono), so the engine must never
     // resize it. RESOLUTION_FIXED is AppBase's DEFAULT, and with it `updateCanvasSize()` is a
     // no-op. Deliberately NOT calling setCanvasResolution/setCanvasFillMode: without explicit
@@ -1047,6 +1122,9 @@ export class PlayCanvasSplatViewer {
     const el = this.canvas;
     const sx = cache && cache.bufW > 0 && el.width ? el.width / cache.bufW : 1;
     const sy = cache && cache.bufH > 0 && el.height ? el.height / cache.bufH : 1;
+    if (this.nearClip !== null || this.farClip !== null) {
+      for (const e of entries) clampProjectionDepth(e.proj, this.nearClip, this.farClip);
+    }
     const rect = (e) =>
       sx !== 1 || sy !== 1
         ? [Math.round(e.x * sx), Math.round(e.y * sy), Math.max(1, Math.round(e.width * sx)), Math.max(1, Math.round(e.height * sy))]
@@ -1607,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
@@ -1627,6 +1706,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     orbitEase: opts.orbitEase,
     feather,
     captureFit,
+    nearClip: opts.nearClip,
+    farClip: opts.farClip,
   });
 
   let handle = null;
@@ -1693,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.0",
+  "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",
@@ -27,6 +27,7 @@
       "types": "./model.d.ts",
       "import": "./js/inline3d-model.js"
     },
+    "./package.json": "./package.json",
     "./undock": {
       "types": "./index.d.ts",
       "import": "./js/inline3d-undock.js"

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`,
@@ -259,6 +260,14 @@ export interface SplatOptions {
    * `'height'`. Both backends; the 3D rig's vertical FOV follows the crop. Anything else throws.
    */
   captureFit?: 'height' | 'cover';
+  /**
+   * PlayCanvas: a FLOOR on the projection's near plane, in world units (the adapter owns the
+   * projections; this only raises near, for depth precision when meshes share the scene under
+   * `handle.engine.root`). Anything nearer is clipped, splats included. Unset: untouched.
+   */
+  nearClip?: number;
+  /** PlayCanvas: a CAP on the projection's far plane (only ever lowers it). Unset: untouched. */
+  farClip?: number;
   /** Camera rig only: the distance in world metres that sits ON the glass. */
   convergence?: number;
   /**
@@ -288,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'`. */
@@ -414,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>;
 }
 
 /**