@displayxr/inline3d 1.41.0 → 1.42.1

package/js/camera/converge.js

@@ -7,8 +7,12 @@
 /** Low-pass factor for the convergence shift (RFC §3): next = prev + α·(target − prev). */
 export const CONVERGENCE_ALPHA = 0.2;
 
-/** The convergence shift never exceeds this fraction of the per-eye width, either way. */
-export const CONVERGENCE_MAX_FRACTION = 0.12;
+/**
+ * The convergence shift never exceeds this fraction of the per-eye width, either way. 0.2: a
+ * 120 mm-baseline camera (the SR laptop's) sees a face at 0.6 m at ~22% of the eye width, so it
+ * needs ~11% per eye — 0.12 left no room to lean in.
+ */
+export const CONVERGENCE_MAX_FRACTION = 0.2;
 
 /** `setDepth(v)`: v in [-1, 1] adds v times this fraction of the per-eye width to the shift. */
 export const DEPTH_RANGE_FRACTION = 0.05;

package/js/camera/disparity.js

@@ -144,7 +144,11 @@ export function matchBlock(img, W, H, x0, y0, bw, bh, { dMin, dMax, dyMax = 2, u
 export function blockDisparities(img, W, H, o = {}) {
   const E = W / 2;
   const b = o.block || Math.max(8, Math.round(E / 20));
-  const step = o.step || Math.round(b * 1.5); // sparse grid: half the blocks, same modes
+  // One block per block width. A sparser grid (1.5 b) left a dim, grayscale SR-camera frame with
+  // ~9 matched blocks, 3-4 of them on the face — too few to form a mode — so the background won
+  // and auto-convergence flipped between the two. At 1 b: ~36 blocks, the face every frame, and a
+  // steadier value (±1 px instead of ±4); ~13 ms per full search at 240 px per eye.
+  const step = o.step || b;
   const dMax = o.dMax ?? Math.round(E * 0.3);
   const dMin = o.dMin ?? -Math.round(E * 0.05);
   const x0 = Math.round(E * (o.roiX0 ?? 0.15));
@@ -165,12 +169,17 @@ export function blockDisparities(img, W, H, o = {}) {
  * The subject = the NEAREST strong disparity mode: the largest `d` whose ±`tol` bin holds at least
  * `minFrac` of the matched blocks (and `minBlocks`). Returns its members, or null.
  */
-export function nearestMode(blocks, { tol = 2, minFrac = 0.12, minBlocks = 3 } = {}) {
+export function nearestMode(blocks, { tol = 2, relTol = 0.1, minFrac = 0.12, minBlocks = 3 } = {}) {
   if (!blocks.length) return null;
   const need = Math.max(minBlocks, Math.ceil(blocks.length * minFrac));
   const ds = blocks.map((b) => b.d).sort((a, b) => b - a); // descending: nearest first
   for (const d of ds) {
-    const members = blocks.filter((b) => Math.abs(b.d - d) <= tol);
+    // The bin widens with the disparity: a near subject's own relief spreads its blocks over
+    // ~relTol of its disparity (the spread scales with baseline / distance, as d does), so a
+    // fixed +-2 px split a face from a wide-baseline (120 mm) camera into groups too small to
+    // count, and the flat background won.
+    const t = Math.max(tol, relTol * Math.abs(d));
+    const members = blocks.filter((b) => Math.abs(b.d - d) <= t);
     if (members.length >= need) {
       const md = members.map((b) => b.d).sort((a, b) => a - b);
       return { d: md[md.length >> 1], members };

package/js/camera/pair-cursor.js

@@ -10,7 +10,7 @@
 // The policy is the one every DisplayXR depth cursor follows (runtime ADR-046 Amendment 2), taken
 // from the shared core (../inline3d-cursor-depth.js), not re-implemented here:
 //  - never behind the glass: only content that comes OUT of the screen moves it, to the margin
-//    (0.03 eye baselines, ~2 mm) in front of that content (cursorTarget);
+//    (0.015 eye baselines, ~1 mm) in front of that content (cursorTarget);
 //  - on the plane it IS the OS cursor: the arrow is drawn into both halves only while the filtered
 //    disparity is past the draw threshold (-0.005 baselines, and >= 0.5 px; cursorShouldDraw), the
 //    OS cursor hidden exactly then;
@@ -72,21 +72,116 @@ export function pairFootprintDisparity(luma, geo, u, v, height, aspect) {
   const dMin = -Math.round(E * 0.05);
   const { rL, rR } = geo;
   const k = geo.outW / rL.sw; // output px per source px
-  let best = null;
-  // The tip, then a ring centred on the arrow's body: that is what content must not overlap.
+  const swp = swappedHalves(luma);
+  const found = []; // { d, x, y, eye }: a consistent match and WHERE it was taken
+  const seen = new Set();
+  const sample = (su, pv) => {
+    const y = Math.round((rL.sy + pv * rL.sh) * scale - b / 2);
+    if (y < 0 || y + b > h) return;
+    const xl = Math.round((rL.sx + su * rL.sw) * scale - b / 2);
+    const xr = Math.round((rR.sx + su * rR.sw) * scale - b / 2);
+    // The arrow is far smaller than a block (~6 vs 12 copy px at the OS arrow's size), so
+    // neighbouring footprint points land on the SAME block: match each block once.
+    if (!seen.has(`L${xl},${y}`)) {
+      seen.add(`L${xl},${y}`);
+      const dl = consistentMatch(img, swp, w, h, xl, y, b, dMin, dMax);
+      if (dl !== null) found.push({ d: dl, x: xl, y, eye: 0 });
+    }
+    if (!seen.has(`R${xr},${y}`)) {
+      seen.add(`R${xr},${y}`);
+      const dr = consistentMatch(swp, img, w, h, xr, y, b, -dMax, -dMin); // right-anchored: d' = -d
+      if (dr !== null) found.push({ d: -dr, x: xr, y, eye: 1 });
+    }
+  };
+  // The tip, then a ring centred on the arrow's body: that is what content must not overlap. Each
+  // point is sampled from BOTH eyes' images (the pointer's spot in the left eye matched into the
+  // right, and the same spot in the right eye matched into the left), so neither eye is favoured:
+  // at a foreground edge one eye's block can sit on the subject and the other's on the background.
+  // Every match must also pass the left-right consistency check (consistentMatch).
+  let cu = 0, cv = 0, n = 0;
   for (const [pu, pv] of cursorArrowFootprint(u, v, height, aspect)) {
     if (!(pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1)) continue;
-    const su = geo.mirror ? 1 - pu : pu;
-    const x = Math.round((rL.sx + su * rL.sw) * scale - b / 2);
-    const y = Math.round((rL.sy + pv * rL.sh) * scale - b / 2);
-    if (x < 0 || x + b > E || y < 0 || y + b > h) continue;
-    const m = matchBlock(img, w, h, x, y, b, b, { dMin, dMax, dyMax: 2 });
-    if (!m || m.c < MIN_NCC) continue;
-    // Source disparity → displayed: each eye's crop moved its half by its own offset.
-    const d = (m.d / scale - (rL.sx - rR.sx)) * k;
-    if (best === null || d > best) best = d;
+    sample(geo.mirror ? 1 - pu : pu, pv);
+    cu += pu; cv += pv; n++;
+  }
+  if (!n) return null;
+  // ...plus four blocks half a block around the footprint's centre, so that real content under
+  // the arrow is seen by more than one distinct block (pairNearestSupported needs that).
+  const du = (b / 2 / scale) / rL.sw, dv = (b / 2 / scale) / rL.sh;
+  for (const [ou, ov] of [[-du, 0], [du, 0], [0, -dv], [0, dv]]) {
+    const pu = cu / n + ou, pv = cv / n + ov;
+    if (pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1) sample(geo.mirror ? 1 - pu : pu, pv);
+  }
+  // Source disparity → displayed: each eye's crop moved its half by its own offset.
+  for (const f of found) f.d = (f.d / scale - (rL.sx - rR.sx)) * k;
+  return pairNearestSupported(found, (PAIR_SUPPORT_COPY_PX / scale) * k, b / 2);
+}
+
+/**
+ * Two consistent footprint matches must agree (within this many px of the grayscale copy) before
+ * the nearest is believed: content that comes out of the screen covers several blocks, a lone
+ * block claiming something nearer than the rest is noise.
+ */
+export const PAIR_SUPPORT_COPY_PX = 1.5;
+
+/** The SBS copy with its halves swapped (cached per copy): matching it is matching right → left. */
+const _swapped = new WeakMap();
+function swappedHalves(luma) {
+  let s = _swapped.get(luma);
+  if (s) return s;
+  const { img, w, h } = luma;
+  const E = w / 2;
+  s = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    const o = y * w;
+    for (let x = 0; x < E; x++) {
+      s[o + x] = img[o + E + x];
+      s[o + E + x] = img[o + x];
+    }
+  }
+  _swapped.set(luma, s);
+  return s;
+}
+
+/**
+ * A block of image A's left half matched into its right half, kept only if the matched block,
+ * matched BACK (in B = A with its halves swapped), lands within 1 px of where it started — the
+ * classic left-right consistency check. A block straddling a depth edge (half subject, half
+ * background, each eye seeing a different half) fails it instead of returning a random depth.
+ * @returns {number|null} disparity in A's convention (left x − right x), copy px
+ */
+export function consistentMatch(A, B, w, h, x, y, b, dMin, dMax) {
+  const E = w / 2;
+  if (x < 0 || x + b > E) return null;
+  const m = matchBlock(A, w, h, x, y, b, b, { dMin, dMax, dyMax: 2 });
+  if (!m || m.c < MIN_NCC) return null;
+  const xb = Math.round(x - m.d);
+  const yb = y + m.dy;
+  if (xb < 0 || xb + b > E || yb < 0 || yb + b > h) return null;
+  const back = matchBlock(B, w, h, xb, yb, b, b, { dMin: -Math.ceil(m.d) - 2, dMax: -Math.floor(m.d) + 2, dyMax: 1 });
+  if (!back || back.c < MIN_NCC || Math.abs(-back.d - m.d) > 1) return null;
+  return m.d;
+}
+
+/**
+ * The nearest disparity that an INDEPENDENT second sample corroborates (within `tol`), else null.
+ * Independent = taken from the other eye's image, or from a block at least `minSep` copy px away:
+ * two footprint points inside one block are one witness, not two. (A block straddling a face edge
+ * and a bright window matched at a bogus +49 px, consistently, and its twin counted as support.)
+ * @param {Array<{d:number, x?:number, y?:number, eye?:number}|number>} samples  output px, + = in front
+ * @returns {number|null}
+ */
+export function pairNearestSupported(samples, tol, minSep = 0) {
+  const S = samples.map((s) => (typeof s === 'number' ? { d: s, x: 0, y: 0, eye: -1 } : s));
+  if (S.length < 2) return null;
+  const sorted = [...S].sort((p, q) => q.d - p.d); // nearest first
+  const independent = (p, q) => p.eye === -1 || p.eye !== q.eye || Math.abs(p.x - q.x) + Math.abs(p.y - q.y) >= minSep;
+  for (const p of sorted) {
+    for (const q of sorted) {
+      if (q !== p && Math.abs(p.d - q.d) <= tol && independent(p, q)) return p.d;
+    }
   }
-  return best;
+  return null;
 }
 
 /**
@@ -109,7 +204,7 @@ export function pairPxPerBaseline(outW, tileCssWidth, metersPerCssPx, eyeSeparat
 /**
  * The arrow's target disparity in output px (+ = in front): the core's policy (cursorTarget) on
  * the content's disparity, converted through `pxPerBaseline`. In front of content that comes OUT
- * of the screen by the margin (0.03 baselines), else the glass — never behind it.
+ * of the screen by the margin (0.015 baselines), else the glass — never behind it.
  */
 export function pairCursorTarget(contentPx, pxPerBaseline, tuning = CURSOR_DEFAULT_TUNING) {
   if (contentPx === null || !Number.isFinite(contentPx) || !(pxPerBaseline > 0)) return 0;

package/js/inline3d-cursor-depth.js

@@ -46,7 +46,7 @@
 // ./camera, which calls the pieces exported here):
 //  - never behind the glass: target = d < 0 ? max(d - margin, dMin) : 0 — it only comes forward,
 //    to stay ahead of content that comes OUT of the screen (cursorTarget);
-//  - margin 0.03 eye baselines (~2 mm of crossed on-screen disparity at a 65 mm IPD);
+//  - margin 0.015 eye baselines (~1 mm of crossed on-screen disparity at a 63-65 mm IPD);
 //  - on the plane it IS the OS cursor: nothing is drawn while the filtered disparity is above
 //    CURSOR_DRAW_THRESHOLD (-0.005, ~0.3 mm) or under CURSOR_DRAW_MIN_PX on the panel
 //    (cursorShouldDraw), and the CSS cursor is left alone;
@@ -99,10 +99,11 @@ export function cursorShouldDraw(disparity, pxPerBaseline) {
  */
 export const CURSOR_DEFAULT_TUNING = Object.freeze({
   /**
-   * How far in front of out-of-screen content the cursor floats: 0.03 eye baselines, ~2 mm of
-   * crossed on-screen disparity at a 65 mm IPD (ADR-046 Amendment 2; the reference app's value).
+   * How far in front of out-of-screen content the cursor floats: 0.015 eye baselines, ~1 mm of
+   * crossed on-screen disparity at a 63-65 mm IPD (ADR-046 Amendment 2 A.2; halved from 0.03 on
+   * 2026-10-11 after a Windows panel check: 0.03 floated visibly off the content).
    */
-  margin: 0.03,
+  margin: 0.015,
   /** Comfort clamp: t >= 0.625, never more than ~3/8 of the way to the eye. */
   minDisparity: -0.6,
   /** Never behind the glass: 0, and cursorTarget never goes above 0 whatever this says. */

package/js/inline3d-three.js

@@ -489,8 +489,8 @@ export class DepthCursor {
    * @param {number} [opts.height]  sprite height as a fraction of the canvas height. Default: the
    *        OS arrow's size, 19 CSS px of the canvas's on-page height (re-read every frame).
    * @param {number} [opts.color=0xffffff]  the arrow's fill colour (the outline is always dark).
-   * @param {number} [opts.margin=0.03]  how far in front of out-of-screen content it floats, in
-   *        eye-baseline units (0.03 ≈ 2 mm of on-screen disparity at a 65 mm IPD).
+   * @param {number} [opts.margin=0.015]  how far in front of out-of-screen content it floats, in
+   *        eye-baseline units (0.015 ≈ 1 mm of on-screen disparity at a 63-65 mm IPD).
    * @param {'hybrid'|'screen'|'world'} [opts.anchor='hybrid']  where along that depth: 'hybrid'
    *        follows the pointer exactly while it moves and stays world-fixed (parallaxes with the
    *        content) while it is still; 'screen' never parallaxes; 'world' always does.

package/model.d.ts

@@ -53,7 +53,7 @@ export interface ModelOptions {
    * `'depth'`: a cursor that is never drawn on the glass behind content that pops out (ADR-046 +
    * Amendment 2, the same policy as native `XR_DXR_cursor_depth`). While the subject under the
    * pointer's footprint comes OUT of the screen, the classic arrow (the OS cursor's size, tip on
-   * the hotspot) is drawn the margin (0.03 eye baselines, ~2 mm) in front of it and the CSS cursor
+   * the hotspot) is drawn the margin (0.015 eye baselines, ~1 mm) in front of it and the CSS cursor
    * is hidden; over anything on or behind the glass nothing is drawn and the CSS cursor is the
    * cursor, untouched. Never behind the glass. OPT-IN: without it nothing
    * is loaded or run. PlayCanvas: hit-tested with the engine's depth picker (meshes and splats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.41.0",
+  "version": "1.42.1",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",

package/splat.d.ts

@@ -477,7 +477,7 @@ export interface SplatOptions {
    * `'depth'`: a cursor that is never drawn on the glass behind content that pops out (ADR-046 +
    * Amendment 2, the same policy as native `XR_DXR_cursor_depth`). While the subject under the
    * pointer's footprint comes OUT of the screen, the classic arrow (the OS cursor's size, tip on
-   * the hotspot) is drawn the margin (0.03 eye baselines, ~2 mm) in front of it and the CSS cursor
+   * the hotspot) is drawn the margin (0.015 eye baselines, ~1 mm) in front of it and the CSS cursor
    * is hidden; over anything on or behind the glass nothing is drawn and the CSS cursor is the
    * cursor, untouched. Never behind the glass. OPT-IN: without it nothing
    * is loaded or run. PlayCanvas: hit-tested with the engine's depth picker (meshes and splats,