@displayxr/inline3d 1.9.1 → 1.10.1

package/CHANGELOG.md

@@ -5,6 +5,70 @@ 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.1 — 2026-09-23
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), and `boundsFromPositions` in
+`./viewer` (same results, less time). Nothing changes for Spark callers' pixels.
+
+### Fixed
+
+- **No grey sky box behind the splat.** The engine draws a sky whenever the scene has something to
+  draw it from, and `scene.envAtlas` counts. A page that set one to light its meshes under
+  `handle.engine.root` got a grey gradient box the instant the splat was hidden (mid-`setSource`,
+  or a page showing only its own meshes). The eye camera now renders without the Skybox layer, so
+  the canvas stays transparent. Image-based lighting still lights the meshes. The new **`sky: true`**
+  brings the engine's sky back.
+  - Verified headless with `envAtlas` set and the splat hidden: the corner pixel reads
+    `[140,140,140,255]` in 1.10.0 and `[0,0,0,0]` now (and `[140,140,140,255]` again with
+    `sky: true`).
+- **`setSource` no longer blocks input for its cloud passes.** The SDK's framing, rest-space sample
+  and pick-set passes ran in one main-thread task stacked on the engine's end-of-load work. Now
+  each runs in its own task (with `scheduler.yield()` where available).
+  - `boundsFromPositions` takes its percentiles with a linear-time select instead of full sorts.
+    The values are bit-identical, pinned by a test.
+  - On a 1.18M-gaussian swap (headless, M1 Pro), the longest main-thread task went from
+    **60–64 ms to under 50 ms** (none reported), and the longest frame gap from 65–77 to
+    35–44 ms. At 4× CPU throttling it went from 218–238 ms to 60–65 ms, which is the engine's own
+    remainder, documented per 1M gaussians with the recommended pre-load pattern.
+  - The load stages are visible as `performance.measure` entries named `inline3d:*`.
+
+## 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

@@ -535,8 +535,15 @@ export class PlayCanvasSplatViewer {
       captureFit = 'height',
       nearClip,
       farClip,
+      sky = false,
     } = opts;
     this.canvas = canvas;
+    // The engine draws a sky box whenever the scene has something to draw it from — and
+    // `scene.envAtlas` counts: a page that sets one to light its own meshes under
+    // handle.engine.root got a grey gradient box behind the splat the instant the splat was
+    // hidden (mid-setSource, or a page showing only its meshes). The SDK's contract is a
+    // transparent canvas the page shows through, so the sky layer is off unless asked for.
+    this.sky = sky === true;
     // 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.
@@ -1044,6 +1051,11 @@ export class PlayCanvasSplatViewer {
       fov: MONO_FOV,
       ...(rect ? { rect } : {}),
     });
+    // No sky unless the page asked (see the constructor): the image-based lighting a page sets
+    // still lights its meshes — only the BACKGROUND the sky layer would draw is dropped.
+    if (!this.sky && Array.isArray(e.camera.layers)) {
+      e.camera.layers = e.camera.layers.filter((id) => id !== pc.LAYERID_SKYBOX);
+    }
     // The engine's default camera tonemap is LINEAR, which routes every splat colour through
     // decodeGamma → toneMap → gammaCorrectOutput. Spark writes the stored colour straight out;
     // NONE is the same thing here (GAMMA_SRGB alone leaves a gamma-space colour untouched).
@@ -1456,6 +1468,28 @@ function placeNode(node, m) {
  * @returns {Promise<{xyz:Float32Array, opacity:Float32Array|null, total:number, stride:number,
  *          sourceTotal:number}|null>} `total` is the number of splats IN the sample.
  */
+/**
+ * A `performance.measure` named `inline3d:<name>` from `t0` to now — so a load's stages show up in
+ * DevTools' Performance panel and in `performance.getEntriesByType('measure')`. Never throws.
+ */
+/**
+ * Give the main thread back for one turn — input, rAF, the engine's own tick — before the next
+ * chunk of cloud work. `scheduler.yield()` where the browser has it (keeps our task's priority),
+ * else a macrotask.
+ */
+function yieldToMain() {
+  if (typeof scheduler !== 'undefined' && typeof scheduler.yield === 'function') return scheduler.yield();
+  return new Promise((r) => setTimeout(r, 0));
+}
+
+function perfSpan(name, t0) {
+  try {
+    performance.measure?.(`inline3d:${name}`, { start: t0, end: performance.now() });
+  } catch {
+    /* no User Timing L3 here */
+  }
+}
+
 export async function readCloud(resource) {
   if (!resource) return null;
   const centers = resource.centers;
@@ -1464,19 +1498,29 @@ export async function readCloud(resource) {
   if (!centers || !sourceTotal) return null;
   const stride = Math.max(1, Math.ceil(sourceTotal / FRAME_SAMPLE_CAP));
   const total = Math.ceil(sourceTotal / stride);
+  // Not in the task that delivered the asset: the engine's own end-of-load work (its centre
+  // readback unpack) runs there, and stacking ours on it made one long task.
+  await yieldToMain();
+  let t0 = performance.now();
   const xyz = new Float32Array(total * 3);
   for (let j = 0, i = 0; j < total; j++, i += stride) {
     xyz[j * 3] = centers[i * 3];
     xyz[j * 3 + 1] = centers[i * 3 + 1];
     xyz[j * 3 + 2] = centers[i * 3 + 2];
   }
+  perfSpan('readCloud:copy', t0);
+  await yieldToMain();
   let opacity = null;
   // Full-resolution peak opacity, ONE BYTE per splat, kept for the exact pick (which walks the
   // engine's own full centre set at pick time): 1.18 MB on the 1.18M bench asset.
   let alpha8 = null;
   try {
     if (data?.isSog && data.sh0?.read) {
+      t0 = performance.now();
       const px = await data.sh0.read(0, 0, data.sh0.width, data.sh0.height, { mipLevel: 0, face: 0, immediate: true });
+      perfSpan('readCloud:sh0-readback(async)', t0);
+      await yieldToMain();
+      t0 = performance.now();
       if (px && px.length >= sourceTotal * 4) {
         const v2 = data.meta?.version === 2;
         const mn = data.meta?.sh0?.mins?.[3];
@@ -1491,6 +1535,7 @@ export async function readCloud(resource) {
         if (v2 || mn === undefined) for (let i = 0; i < sourceTotal; i++) alpha8[i] = px[i * 4 + 3];
         else for (let i = 0; i < sourceTotal; i++) alpha8[i] = Math.round(op(i) * 255);
       }
+      perfSpan('readCloud:opacity', t0);
     } else if (typeof data?.getProp === 'function') {
       const o = data.getProp('opacity');
       if (o && o.length >= sourceTotal) {
@@ -1685,6 +1730,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
@@ -1707,6 +1753,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     captureFit,
     nearClip: opts.nearClip,
     farClip: opts.farClip,
+    sky: opts.sky,
   });
 
   let handle = null;
@@ -1773,10 +1820,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.
@@ -1939,7 +1992,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     }
     // The camera block off the SAME bytes, before the engine takes them (as the Spark path).
     let camera = null;
+    let t0 = performance.now();
     if (bytes && rig !== 'display') camera = sogCameraFromMeta(await readSogMeta(bytes));
+    perfSpan('readSogMeta(async)', t0);
 
     const url = bytes
       ? `inline3d-bytes-${++byteSeq}-${++byteSeqLocal}.${fmt.ext}`
@@ -1951,18 +2006,42 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       : { url, filename: pathOf(url).split('/').pop() || url };
     const asset = new pc.Asset(url, 'gsplat', file);
     app.assets.add(asset);
+    t0 = performance.now();
     await new Promise((resolve, reject) => {
       asset.ready(resolve);
       asset.once('error', (err) => reject(err instanceof Error ? err : new Error(String(err))));
       app.assets.load(asset);
     });
+    perfSpan('engine-load(async)', t0);
     const res = asset.resource;
     const desc = describeResource(res);
     // A URL `.sog` carries its meta in the resource (the engine keeps unknown keys); a Streamed
     // SOG carries it at the top level of lod-meta.json. Both validated by the same reader.
     if (!bytes && rig !== 'display') camera = sogCameraFromMeta(desc.meta);
     const cloud = desc.kind === 'flat' ? await readCloud(res) : null;
-    return { asset, res, desc, camera, cloud };
+    // The cloud passes, each in its OWN task: framing, the rest-space sample and the pick set
+    // were one ~60 ms main-thread block on a 1.18M-gaussian swap — pointer input waited on it.
+    // Split with a yield between them (and a linear-time percentile in boundsFromPositions),
+    // no single step is a long task any more. Same numbers, same order.
+    const pre = { local: null, rest: null, pickCentres: null };
+    if (cloud) {
+      const walk = centresVisitor(cloud.xyz, cloud.opacity, cloud.total);
+      await yieldToMain();
+      let t = performance.now();
+      pre.local = boundsFromPositions(sampleCloudCentres(cloud.total, walk) || []);
+      perfSpan('cloud:bounds', t);
+      await yieldToMain();
+      t = performance.now();
+      if (rigNeedsCloud(camera)) pre.rest = sampleCloudRestSpace(cloud.total, walk, camera?.rest);
+      perfSpan('cloud:rest-sample', t);
+      await yieldToMain();
+      t = performance.now();
+      const s = sampleCloudCentres(cloud.total, walk, { cap: RIG_SAMPLE_CAP });
+      pre.pickCentres = s ? s.slice() : null;
+      perfSpan('cloud:pick-set', t);
+      await yieldToMain();
+    }
+    return { asset, res, desc, camera, cloud, pre };
   }
 
   /**
@@ -1971,8 +2050,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    */
   function applyLoaded(loaded) {
     const { cloud, desc } = loaded;
-    const walk = cloud ? centresVisitor(cloud.xyz, cloud.opacity, cloud.total) : null;
-    const local = walk ? boundsFromPositions(sampleCloudCentres(cloud.total, walk) || []) : null;
+    const tB = performance.now();
+    const local = loaded.pre?.local || null;
     const lift = (b) => ({ center: modelToContent(b.center), extent: b.extent.slice(0, 3) });
     // Measured first — the Spark path's order (a supplied frame is only a fallback there too).
     // A Streamed SOG has no cloud: there a caller's `frame` beats the octree-derived bounds
@@ -1988,12 +2067,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
             ? lift(frame)
             : null;
 
-    const sample =
-      !rigNeedsCloud(loaded.camera)
-        ? null
-        : walk
-          ? sampleCloudRestSpace(cloud.total, walk, loaded.camera?.rest)
-          : null;
+    const sample = loaded.pre?.rest || null;
     const box = canvas.getBoundingClientRect();
     const resolved = resolveRig({
       camera: loaded.camera,
@@ -2003,6 +2077,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     });
     resolved.focusDefault = resolved.focus.slice();
     resolved.focusDefaultSource = resolved.focusSource;
+    perfSpan('applyLoaded:rig', tB);
     out.camera = loaded.camera;
     out.rig = resolved;
     out.frame = bounds;
@@ -2015,11 +2090,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     }
 
     // The strided pick fallback (used only if the engine releases its full centre set).
-    let pickCentres = null;
-    if (walk) {
-      const s = sampleCloudCentres(cloud.total, walk, { cap: RIG_SAMPLE_CAP });
-      pickCentres = s ? s.slice() : null;
-    }
+    const pickCentres = loaded.pre?.pickCentres || null;
 
     if (resolved.type === 'camera') {
       if (!('idleSpin' in opts)) viewer.idleSpin = 0;

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-viewer.js

@@ -70,6 +70,56 @@ const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // matrix and every vertex lands undefined. Reject at the setter instead.
 const finite = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
 
+/**
+ * The k-th smallest of the first `n` entries of `a` — exactly what `a.subarray(0, n).sort()[k]`
+ * returns, NaN placement included (a TypedArray sort puts NaN last) — by quickselect, reordering
+ * `a` in place. O(n) on average.
+ */
+export function selectKth(a, n, k) {
+  // NaN to the end first, as the numeric TypedArray sort does; select among the rest.
+  let m = n;
+  for (let i = 0; i < m; ) {
+    if (a[i] !== a[i]) {
+      m--;
+      const t = a[i];
+      a[i] = a[m];
+      a[m] = t;
+    } else i++;
+  }
+  if (k >= m) return NaN;
+  let left = 0;
+  let right = m - 1;
+  while (right > left) {
+    // Median-of-three pivot keeps sorted / reverse-sorted input O(n).
+    const mid = (left + right) >> 1;
+    if (a[mid] < a[left]) swap(a, mid, left);
+    if (a[right] < a[left]) swap(a, right, left);
+    if (a[right] < a[mid]) swap(a, right, mid);
+    const pivot = a[mid];
+    let i = left;
+    let j = right;
+    while (i <= j) {
+      while (a[i] < pivot) i++;
+      while (a[j] > pivot) j--;
+      if (i <= j) {
+        swap(a, i, j);
+        i++;
+        j--;
+      }
+    }
+    if (k <= j) right = j;
+    else if (k >= i) left = i;
+    else return a[k];
+  }
+  return a[k];
+}
+
+function swap(a, i, j) {
+  const t = a[i];
+  a[i] = a[j];
+  a[j] = t;
+}
+
 /**
  * Robust model-space bounds from a flat array of splat/vertex centres.
  *
@@ -110,14 +160,15 @@ export function boundsFromPositions(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 }
   const center = [0, 0, 0];
   const extent = [0, 0, 0];
   const axisVals = new Float64Array(n);
+  const kLo = trim ? Math.floor(lo * (n - 1)) : 0;
+  const kHi = trim ? Math.floor(hi * (n - 1)) : n - 1;
   for (let axis = 0; axis < 3; axis++) {
     for (let i = 0; i < n; i++) axisVals[i] = xyz[i * 3 + axis];
-    // TypedArray sort is numeric and in-place — no comparator, no copy. That matters here:
-    // this runs over every splat centre, and a boxed Array round-trip on a 500k-splat model
-    // is the difference between a hitch and an imperceptible pause.
-    const sorted = axisVals.sort();
-    const loV = trim ? sorted[Math.floor(lo * (n - 1))] : sorted[0];
-    const hiV = trim ? sorted[Math.floor(hi * (n - 1))] : sorted[n - 1];
+    // Only two ORDER STATISTICS are needed, not a sorted array: selecting them is O(n) where the
+    // sort was O(n log n) — the same two values, bit for bit (a sort's k-th element IS the k-th
+    // order statistic), at a fraction of the main-thread time on a 200k-point sample (1.10.1).
+    const loV = selectKth(axisVals, n, kLo);
+    const hiV = selectKth(axisVals, n, kHi);
     center[axis] = 0.5 * (loV + hiV);
     extent[axis] = Math.max(hiV - loV, 1e-6);
   }

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.1",
   "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`,
@@ -265,6 +266,11 @@ export interface SplatOptions {
    * `handle.engine.root`). Anything nearer is clipped, splats included. Unset: untouched.
    */
   nearClip?: number;
+  /**
+   * PlayCanvas: draw the engine's sky box (default false). Off, nothing is drawn behind the splat
+   * even when a page sets `scene.envAtlas` to light its own meshes; the canvas stays transparent.
+   */
+  sky?: boolean;
   /** 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. */
@@ -296,6 +302,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 +430,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>;
 }
 
 /**