@displayxr/inline3d 1.47.5 → 1.48.0

package/js/call/wire.js

@@ -26,6 +26,31 @@ export const MESH_HARD_CAP = 4;
 /** `hint` messages are rate-limited to this many per second, on the sender AND the receiver. */
 export const HINT_MAX_HZ = 5;
 
+/**
+ * `conv` (sender-measured auto-convergence, docs/call.md): a sender broadcasts at most this many
+ * per second; a receiver accepts at most `CONV_RECV_MAX_HZ`. A sender whose value has not changed
+ * still sends one every `CONV_HEARTBEAT_MS`; a receiver that has heard nothing for `CONV_FRESH_MS`
+ * goes back to measuring the received frames itself.
+ */
+export const CONV_MAX_HZ = 5;
+export const CONV_RECV_MAX_HZ = 10;
+export const CONV_HEARTBEAT_MS = 400;
+export const CONV_FRESH_MS = 1200;
+/** `conv.d` is a fraction of the per-eye width; anything beyond ±this is not a face's disparity. */
+export const CONV_MAX_FRAC = 0.5;
+
+/**
+ * App messages (`handle.send` / `handle.broadcast`, docs/call.md § Headless): `{ type: 'app', d }`
+ * on the call's data channel. The serialised message is at most `APP_MAX_BYTES` (UTF-8), and a
+ * sender sends at most `APP_MAX_PER_SEC` to one peer in any second (a receiver drops anything
+ * beyond `APP_RECV_MAX_PER_SEC`: network jitter can bunch a legal burst).
+ */
+export const APP_MAX_BYTES = 16 * 1024;
+export const APP_MAX_PER_SEC = 20;
+export const APP_RECV_MAX_PER_SEC = 40;
+/** A display name (`hello.name`, the `name` option) is at most this many characters. */
+export const NAME_MAX_CHARS = 64;
+
 /** Plausible subject distances, mm. A hint outside this is ignored as noise. */
 export const SUBJECT_Z_MIN_MM = 150;
 export const SUBJECT_Z_MAX_MM = 5000;
@@ -116,7 +141,7 @@ export function buildInviteLink(base, room) {
   return `${b}#room=${room}`;
 }
 
-// ── hello / hint / state ───────────────────────────────────────────────────────────────────
+// ── hello / hint / state / conv ────────────────────────────────────────────────────────────
 
 /**
  * Validate an incoming `hello`, filling the defaults a receiver may assume. Returns null for
@@ -138,11 +163,36 @@ export function normalizeHello(msg) {
     hfovDeg: num(msg.hfovDeg, 5, 170),
     rectified: msg.rectified === true,
     sdk: typeof msg.sdk === 'string' ? msg.sdk.slice(0, 64) : null,
+    // The sender measures its own convergence and sends `conv` messages. Absent (an older sender) =
+    // false: the receiver measures the decoded frames itself, as before.
+    conv: msg.conv === true,
+    // The sender's display name (`name` option, 1.48+), sanitised; null when absent or empty.
+    name: sanitizeName(msg.name),
   };
 }
 
-/** Build the `hello` this side sends. */
-export function makeHello({ format, width, height, baselineMm, hfovDeg, rectified } = {}) {
+/**
+ * A display name as it may travel and be shown: a string, control characters removed (C0, DEL,
+ * C1, and the bidi / zero-width format controls that can disguise a name), whitespace collapsed
+ * and trimmed, at most `NAME_MAX_CHARS` characters (code points). Null for anything else or an
+ * empty result. Never throws: this reads data from another browser. Pure.
+ * @param {unknown} v
+ * @returns {string|null}
+ */
+export function sanitizeName(v) {
+  if (typeof v !== 'string') return null;
+  // eslint-disable-next-line no-control-regex
+  const clean = v.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!clean) return null;
+  const cps = Array.from(clean);
+  return cps.length > NAME_MAX_CHARS ? cps.slice(0, NAME_MAX_CHARS).join('').trim() : clean;
+}
+
+/**
+ * Build the `hello` this side sends. `conv: true` (advertised for a side-by-side sender only)
+ * says this side sends `conv` messages.
+ */
+export function makeHello({ format, width, height, baselineMm, hfovDeg, rectified, conv, name } = {}) {
   const h = {
     type: 'hello',
     v: WIRE_VERSION,
@@ -154,9 +204,90 @@ export function makeHello({ format, width, height, baselineMm, hfovDeg, rectifie
   };
   if (Number.isFinite(baselineMm)) h.baselineMm = baselineMm;
   if (Number.isFinite(hfovDeg)) h.hfovDeg = hfovDeg;
+  if (h.format === 'sbs' && conv) h.conv = true;
+  const n = sanitizeName(name);
+  if (n) h.name = n;
   return h;
 }
 
+/**
+ * Wrap a page's app payload: `{ type: 'app', d: data }` serialised, or null when `data` cannot be
+ * serialised (undefined, a function, a cycle, a BigInt) or the message is over `APP_MAX_BYTES`
+ * (UTF-8). Returns the JSON string the data channel carries. Pure.
+ * @param {unknown} data
+ * @returns {{ json: string, bytes: number } | null}
+ */
+export function makeAppMessage(data) {
+  if (data === undefined || typeof data === 'function') return null;
+  let json;
+  try {
+    json = JSON.stringify({ type: 'app', d: data });
+  } catch {
+    return null;
+  }
+  if (typeof json !== 'string') return null;
+  const bytes = utf8Length(json);
+  return bytes > APP_MAX_BYTES ? null : { json, bytes };
+}
+
+/** An incoming `app` message: `{ data }`, or null when it is not one. Only this type reaches a page. */
+export function normalizeApp(msg) {
+  if (!msg || typeof msg !== 'object' || msg.type !== 'app' || !('d' in msg)) return null;
+  return { data: msg.d };
+}
+
+function utf8Length(s) {
+  if (typeof TextEncoder === 'function') return new TextEncoder().encode(s).length;
+  let n = 0;
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    n += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
+  }
+  return n;
+}
+
+/**
+ * A sliding-window counter: `gate(nowMs)` is true at most `max` times in any `windowMs`. The app
+ * channel's per-peer cap (a burst of `max` is fine; the next one waits for the window). Pure.
+ */
+export function windowGate(max, windowMs = 1000) {
+  const at = [];
+  return (now) => {
+    while (at.length && now - at[0] >= windowMs) at.shift();
+    if (at.length >= max) return false;
+    at.push(now);
+    return true;
+  };
+}
+
+/**
+ * `conv {d, c?}`: the sender's measured disparity of the point between its subject's eyes, as a
+ * FRACTION of its per-eye width (resolution-free: a receiver multiplies by the width of the frame it
+ * decodes), `null` = nothing measured yet (the receiver holds what it had). `c` = the match
+ * confidence (NCC, 0..1), informational.
+ * @param {number|null} frac
+ * @param {number|null} [ncc]
+ */
+export function makeConv(frac, ncc) {
+  const m = { type: 'conv', d: typeof frac === 'number' && Number.isFinite(frac) ? Math.max(-CONV_MAX_FRAC, Math.min(CONV_MAX_FRAC, frac)) : null };
+  if (typeof ncc === 'number' && Number.isFinite(ncc)) m.c = Math.max(0, Math.min(1, ncc));
+  return m;
+}
+
+/**
+ * Validate an incoming `conv`. Null for anything that is not one, or whose `d` is neither null nor
+ * a finite number within ±CONV_MAX_FRAC. `c` is clamped to 0..1, or dropped. Never throws: this
+ * reads data from another browser.
+ */
+export function normalizeConv(msg) {
+  if (!msg || typeof msg !== 'object' || msg.type !== 'conv') return null;
+  const d = msg.d;
+  if (d !== null && !(typeof d === 'number' && Number.isFinite(d) && Math.abs(d) <= CONV_MAX_FRAC)) return null;
+  const out = { type: 'conv', d };
+  if (typeof msg.c === 'number' && Number.isFinite(msg.c)) out.c = Math.max(0, Math.min(1, msg.c));
+  return out;
+}
+
 /** `hint {subjectZmm}`: a number in range, or null (ignored). */
 export function normalizeHint(msg) {
   if (!msg || msg.type !== 'hint') return null;
@@ -173,11 +304,14 @@ export function normalizeState(msg) {
 }
 
 /**
- * A minimum-interval gate: `gate(nowMs)` is true at most `hz` times a second. Used on both ends
+ * A minimum-interval gate: `gate(nowMs)` is true at most `hz` times a second (`slackMs` shortens
+ * the interval by that much). Used on both ends
  * of `hint` so a chatty (or hostile) sender cannot drive the receiver's convergence at frame rate.
  */
-export function rateGate(hz) {
-  const minMs = 1000 / hz;
+export function rateGate(hz, slackMs = 0) {
+  // `slackMs`: a timer-paced caller at exactly `hz` (the sender's `conv` tick) lands a few ms early
+  // now and then; without slack every such tick is refused and the rate halves.
+  const minMs = 1000 / hz - Math.max(0, slackMs);
   let last = -Infinity;
   return (now) => {
     if (now - last < minMs) return false;
@@ -186,6 +320,29 @@ export function rateGate(hz) {
   };
 }
 
+// ── connection quality ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The selected ICE candidate pair of one getStats() report: `{ path, rttMs }`. `path` is
+ * `'relay'` when either end is relayed (TURN), else the local candidate's type (`'host'` /
+ * `'srflx'` / `'prflx'`); null when no pair is selected yet. Chrome names the pair on the
+ * `transport` stats; Firefox flags it `selected`. Pure: reads an RTCStatsReport (maplike).
+ */
+export function selectedPath(report) {
+  const all = [];
+  report.forEach((s) => all.push(s));
+  const byId = (id) => (id && typeof report.get === 'function' ? report.get(id) : all.find((s) => s.id === id)) || null;
+  const tr = all.find((s) => s.type === 'transport' && s.selectedCandidatePairId);
+  const pair = (tr && byId(tr.selectedCandidatePairId)) || all.find((s) => s.type === 'candidate-pair' && s.selected) || all.find((s) => s.type === 'candidate-pair' && s.nominated && s.state === 'succeeded');
+  if (!pair) return { path: null, rttMs: null };
+  const lc = byId(pair.localCandidateId);
+  const rc = byId(pair.remoteCandidateId);
+  const lt = lc ? lc.candidateType : null;
+  const path = lt === 'relay' || (rc && rc.candidateType === 'relay') ? 'relay' : ['host', 'srflx', 'prflx'].includes(lt) ? lt : null;
+  const rtt = typeof pair.currentRoundTripTime === 'number' ? Math.round(pair.currentRoundTripTime * 1000) : null;
+  return { path, rttMs: rtt };
+}
+
 // ── routing (RFC §3) ───────────────────────────────────────────────────────────────────────
 
 /**

package/js/camera/capture.js

@@ -5,16 +5,25 @@
 // 1280x480, i.e. 640x480 per eye, grayscale and UNRECTIFIED). Found → sent as `sbs`. Otherwise the
 // default webcam, sent as `mono`. Per-eye width is whatever the camera gives; nothing is upscaled.
 //
-// Two field facts shape the probing:
+// Three field facts shape the probing:
 //  - On some laptops the stereo camera is held EXCLUSIVELY by the eye tracker, so opening it
 //    fails with NotReadableError ("Device in use"). That device is skipped silently — a call must
 //    never fail because an optional camera is busy.
+//  - Not every `videoinput` is a camera a person should be seen through. A hand-tracking camera
+//    (and an eye tracker's or a depth sensor's IR stream) enumerates as an ordinary video input
+//    and can even look like a pair by shape; on a Windows box with no stereo camera open, the
+//    last-resort "try every device" loop opened one and sent it as the call's 3D picture. Labels
+//    matching CAMERA_EXCLUDE_BUILTIN, plus the page's `exclude` list, are never opened by any probe
+//    path (an excluded default is closed again), and are reported in `skipped` as `excluded`.
 //  - Labels are empty until one getUserMedia has succeeded. Without them, permission is primed on
-//    the DEFAULT camera with no constraints: in the DisplayXR Browser the runtime's 3D camera is
-//    listed first, so the prime opens the pair itself and no phone lens is opened at all (a plain
-//    open of one lens of the pair, or its teardown, crashes some phones' camera HAL; any facing or
-//    size constraint lets the engine pick a lens instead). Then the list is read again and a
-//    stereo device is opened by id BEFORE falling back. The primed default is the fallback.
+//    the DEFAULT camera with no constraints (a plain open of one lens of a phone's pair, or its
+//    teardown, crashes some phones' camera HAL; any facing or size constraint lets the engine pick
+//    a lens instead). Where the runtime's 3D camera is the default, the prime opens the pair
+//    itself. NOTHING here assumes a list position: on Windows the DisplayXR Browser lists its
+//    "3D Camera (DisplayXR)" LAST. A pair is recognised by the track's own `displayxrStereo`
+//    description or by its label (stereoLabelHint), and after the prime the list is read again and
+//    a named pair is opened by id BEFORE a default that is a pair only by its shape is kept. The
+//    primed default is the fallback.
 //
 // RECTIFICATION is not done here (P2): it needs the camera's calibration (intrinsics/extrinsics
 // for the ACTIVE device), which comes from a plug-in or the runtime. P1 sends the raw pair with
@@ -48,11 +57,44 @@ export function isDeniedError(err) {
  * @param {Array<{error: string, busy?: boolean, denied?: boolean}>} skipped
  */
 export function noCameraCode(skipped) {
-  if (skipped.length && skipped.every((s) => s.busy)) return 'camera-busy';
-  if (skipped.some((s) => s.denied)) return 'permission-denied';
+  // A device left out on purpose (`excluded`) says nothing about why the others failed.
+  const tried = skipped.filter((s) => !s.excluded);
+  if (tried.length && tried.every((s) => s.busy)) return 'camera-busy';
+  if (tried.some((s) => s.denied)) return 'permission-denied';
   return 'no-camera';
 }
 
+/**
+ * Labels of video inputs that are sensors, not cameras to be seen through: hand tracking, an eye
+ * tracker's or a "tracking camera"'s IR stream, a depth camera. Generic words only. Applied on
+ * every probe path unless `exclude: false`.
+ */
+export const CAMERA_EXCLUDE_BUILTIN = /\b(hand[- ]?track|tracking camera|eye[- ]?track|depth camera)/i;
+
+/**
+ * The exclusion list in force: the built-in pattern plus `exclude` (strings match a label
+ * case-insensitively as a substring, or a deviceId exactly; RegExps test the label), or nothing at
+ * all for `exclude: false`. Returns a predicate `(label, deviceId) => boolean`. Pure.
+ * @param {false|null|undefined|ReadonlyArray<string|RegExp>|string|RegExp} exclude
+ */
+export function cameraExcluder(exclude) {
+  if (exclude === false) return () => false;
+  const list = [CAMERA_EXCLUDE_BUILTIN];
+  for (const x of exclude == null ? [] : Array.isArray(exclude) ? exclude : [exclude]) {
+    if (x instanceof RegExp || (typeof x === 'string' && x)) list.push(x);
+  }
+  return (label, deviceId) => {
+    const l = String(label || '');
+    for (const x of list) {
+      if (x instanceof RegExp) {
+        x.lastIndex = 0; // a /g or /y pattern is stateful
+        if (l && x.test(l)) return true;
+      } else if ((l && l.toLowerCase().includes(x.toLowerCase())) || (deviceId && deviceId === x)) return true;
+    }
+    return false;
+  };
+}
+
 /** A label that names a stereo camera, tried first when probing. Pure. */
 export function stereoLabelHint(label) {
   return /stereo|\b3d\b|\bsbs\b|dual/i.test(label || '');
@@ -65,7 +107,9 @@ export function stereoLabelHint(label) {
  * @param {'auto'|'stereo'|'mono'|string|MediaStream} want  'auto' | 'stereo' | 'mono' | a
  *        deviceId | a page-supplied MediaStream
  * @param {{ format?: 'sbs'|'mono', calibration?: {baselineMm?: number, hfovDeg?: number, rectified?: boolean},
- *           mediaDevices?: MediaDevices, log?: Function }} [o]
+ *           mediaDevices?: MediaDevices, log?: Function, exclude?: false|Array<string|RegExp> }} [o]
+ *        `exclude`: devices no probe may open (see cameraExcluder); an explicit deviceId is the
+ *        page's own choice and is opened regardless.
  * @returns {Promise<{ stream: MediaStream, format: 'sbs'|'mono', width: number, height: number,
  *           deviceId: string|null, label: string, owned: boolean, skipped: Array<{label: string, error: string}>,
  *           calibration: object }>}
@@ -75,6 +119,7 @@ export async function openCamera(want = 'auto', o = {}) {
   const log = o.log || (() => {});
   const skipped = [];
   const cal = o.calibration || {};
+  const isExcluded = cameraExcluder(o.exclude);
 
   if (want && typeof want === 'object' && typeof want.getVideoTracks === 'function') {
     const t = want.getVideoTracks()[0];
@@ -105,6 +150,32 @@ export async function openCamera(want = 'auto', o = {}) {
     log('camera-skip', { label, error: err.name });
   };
   const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
+  // Excluded devices: never opened by id; a default that turns out to be one is closed again.
+  const excludedIds = new Set();
+  const exclude = (label, deviceId) => {
+    if (deviceId && excludedIds.has(deviceId)) return;
+    if (deviceId) excludedIds.add(deviceId);
+    skipped.push({ label, error: 'excluded', excluded: true });
+    log('camera-skip', { label, error: 'excluded' });
+  };
+  const listedExcluded = (d) => {
+    if (!d.label || !isExcluded(d.label, d.deviceId)) return false;
+    exclude(d.label, d.deviceId);
+    return true;
+  };
+  // An open of the DEFAULT (no id): only after it opened is its label known. An excluded default
+  // is closed and never opened again in this probe.
+  let defaultExcluded = false;
+  const openDefault = async (constraints) => {
+    const r = await open(constraints);
+    if (isExcluded(r.label, r.deviceId)) {
+      stop(r);
+      exclude(r.label, r.deviceId);
+      defaultExcluded = true;
+      return null;
+    }
+    return r;
+  };
   // Ask an open camera for another mode without a second start; keep it as it is if it refuses.
   const withMode = async (r, constraints) => {
     try {
@@ -165,6 +236,7 @@ export async function openCamera(want = 'auto', o = {}) {
     for (const d of list) {
       if (!d.deviceId || !stereoLabelHint(d.label) || tried.has(d.deviceId)) continue;
       tried.add(d.deviceId);
+      if (listedExcluded(d)) continue;
       let r = null;
       try {
         r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
@@ -192,31 +264,35 @@ export async function openCamera(want = 'auto', o = {}) {
       pair = await tryNamedPairs(listed);
       if (pair) return result(pair, 'sbs');
     }
-    // No labels yet (no permission). Prime it on the default camera with NO constraints: in the
-    // DisplayXR Browser that is the 3D camera (listed first), so no phone lens is opened; a facing
-    // or size constraint would let the engine pick a lens instead. Then open a pair by id.
+    // No labels yet (no permission). Prime it on the default camera with NO constraints (a facing
+    // or size constraint would let the engine pick a phone lens instead). Where the runtime's 3D
+    // camera is the default this opens the pair itself; elsewhere (Windows lists it LAST) the list
+    // is read again and a NAMED pair is opened by id. A default that is a pair only by its SHAPE is
+    // kept as the pair only when no named one opens (it could be any wide sensor).
     if (listed.length && listed.every((d) => !d.label)) {
       let primed = null;
       try {
-        primed = await open(true);
+        primed = await openDefault(true);
       } catch (err) {
         skip('default', err);
       }
-      if (primed && isPair(primed)) return result(primed, 'sbs');
+      if (primed && primed.stereo) return result(primed, 'sbs'); // the device says it is the pair
+      if (primed && primed.deviceId) tried.add(primed.deviceId);
       const named = await tryNamedPairs(await listCameras());
       if (named) {
         stop(primed);
         return result(named, 'sbs');
       }
+      if (primed && isPair(primed)) return result(primed, 'sbs');
       // The primed default is the fallback as is (one camera start); ask it for the usual mode.
       if (primed) mono = await withMode(primed, MONO_CONSTRAINTS);
     }
   }
 
   // The default camera: the fallback (and, with labels already visible, also the probe base).
-  if (!mono) {
+  if (!mono && !defaultExcluded) {
     try {
-      mono = await open(MONO_CONSTRAINTS);
+      mono = await openDefault(MONO_CONSTRAINTS);
     } catch (err) {
       skip('default', err);
     }
@@ -230,11 +306,13 @@ export async function openCamera(want = 'auto', o = {}) {
   } catch {
     /* no enumeration: keep the default */
   }
+  // A label that names a pair first; never by list position (see the header).
   devices.sort((a, b) => Number(stereoLabelHint(b.label)) - Number(stereoLabelHint(a.label)));
   for (const d of devices) {
     if (!d.deviceId) continue; // no permission yet: an anonymous entry cannot be opened by id
     if (mono && d.deviceId === mono.deviceId) continue;
-    if (tried.has(d.deviceId)) continue; // the fast path already opened it (not a pair, or busy)
+    if (tried.has(d.deviceId) || excludedIds.has(d.deviceId)) continue; // already opened (not a pair, or busy) or left out
+    if (listedExcluded(d)) continue; // the last resort never opens a sensor (a hand-tracking camera)
     let r = null;
     try {
       r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
@@ -243,11 +321,17 @@ export async function openCamera(want = 'auto', o = {}) {
       skip(d.label, err);
       continue;
     }
-    if (isPair(r)) {
+    if (isPair(r) && want !== 'mono') {
       stop(mono);
       log('camera-sbs', { label: r.label, width: r.width, height: r.height });
       return result(r, 'sbs');
     }
+    // No default could be used (excluded, busy): the first plain camera found is the fallback.
+    if (!mono && !isPair(r)) {
+      mono = await withMode(r, MONO_CONSTRAINTS);
+      if (want === 'mono') return result(mono, 'mono');
+      continue;
+    }
     stop(r);
   }
   if (mono) {
@@ -261,11 +345,14 @@ export async function openCamera(want = 'auto', o = {}) {
   );
 }
 
-/** The microphone, with echo cancellation and noise suppression. Null if unavailable/denied. */
+/**
+ * The microphone, with echo cancellation and noise suppression. Null if unavailable/denied.
+ * `deviceId`: that input exactly (`handle.setMic`).
+ */
 export async function openMic(o = {}) {
   const md = o.mediaDevices || (globalThis.navigator && navigator.mediaDevices);
   try {
-    const s = await md.getUserMedia({ audio: { ...AUDIO_CONSTRAINTS }, video: false });
+    const s = await md.getUserMedia({ audio: { ...AUDIO_CONSTRAINTS, ...(o.deviceId ? { deviceId: { exact: o.deviceId } } : {}) }, video: false });
     return s.getAudioTracks()[0] || null;
   } catch (err) {
     (o.log || (() => {}))('mic-skip', { error: err && err.name });

package/js/camera/conv-meter.js

@@ -0,0 +1,152 @@
+// camera/conv-meter.js — the frame grab and the measuring loop behind auto-convergence, shared by
+// a call's SENDER (it measures its own raw, pre-encode frames and sends the result to every peer:
+// docs/call.md "Auto-convergence is measured by the sender") and a receiver's FALLBACK (an older
+// sender that sends nothing; the depth cursor's copy). Internal: importable by path, not part of
+// any entry. The measurement itself is camera/disparity.js.
+
+import { lumaFromRgba, createDisparityTrack, createFocusTracker, downsampleLuma } from './disparity.js';
+
+/** Sampling interval and the per-eye width of the measured copy: enough for sub-pixel disparity on a face, a few ms per measurement. */
+export const CONV_METER_INTERVAL_MS = 200;
+export const CONV_METER_EYE_WIDTH = 240;
+
+/** WebCodecs pixel formats whose plane 0 is luma (Y): read directly, no colour conversion. */
+export const Y_PLANE_FORMATS = new Set(['I420', 'I420A', 'I422', 'I444', 'NV12']);
+
+const nowMs = () => (globalThis.performance ? performance.now() : Date.now());
+
+/**
+ * A small grayscale copy of `video`'s current frame, per-eye width at most `eyeMax`.
+ *
+ * Preferred: WebCodecs. `new VideoFrame(video)` + an ASYNC `copyTo()`, reading the luma (Y) plane
+ * directly: no synchronous GPU->CPU canvas readback on the paint path (that readback, not the
+ * matching, was ~25 ms of a ~30 ms measurement). Otherwise a small canvas (`scratch`, reused) +
+ * `getImageData`. Resolves null for a frame that cannot be read (not decoded yet, tainted, a
+ * failed copy). Never rejects.
+ *
+ * `scale` = copy px per source px; `readMs` = main-thread time spent getting the pixels.
+ *
+ * @param {HTMLVideoElement} video
+ * @param {{eyeMax?: number, scratch?: HTMLCanvasElement|null}} [o]
+ * @returns {Promise<{img: Uint8Array, w: number, h: number, scale: number, via: 'videoframe'|'canvas', readMs: number}|null>}
+ */
+export async function grabLumaFrame(video, { eyeMax = CONV_METER_EYE_WIDTH, scratch = null } = {}) {
+  const W = video ? video.videoWidth : 0;
+  const H = video ? video.videoHeight : 0;
+  if (!W || !H || (video.readyState || 0) < 2) return null;
+  if (typeof VideoFrame === 'function') {
+    let frame = null;
+    try {
+      frame = new VideoFrame(video);
+    } catch {
+      frame = null;
+    }
+    if (frame && Y_PLANE_FORMATS.has(frame.format)) {
+      try {
+        const fw = frame.visibleRect ? frame.visibleRect.width : frame.displayWidth;
+        const fh = frame.visibleRect ? frame.visibleRect.height : frame.displayHeight;
+        const buf = new Uint8Array(frame.allocationSize());
+        const layout = await frame.copyTo(buf);
+        const t0 = nowMs();
+        const f = Math.max(1, Math.ceil(fw / 2 / eyeMax));
+        const ds = downsampleLuma(buf, layout[0].offset, layout[0].stride, fw, fh, f);
+        return { img: ds.img, w: ds.w, h: ds.h, scale: ds.w / fw, via: 'videoframe', readMs: nowMs() - t0 };
+      } catch {
+        return null;
+      } finally {
+        frame.close();
+      }
+    }
+    if (frame) frame.close();
+  }
+  // Fallback: a small canvas + getImageData (synchronous readback).
+  const t0 = nowMs();
+  const s = Math.min(1, eyeMax / (W / 2));
+  const w = Math.max(2, Math.round((W * s) / 2) * 2);
+  const h = Math.max(2, Math.round(H * s));
+  const c = scratch || (globalThis.document ? document.createElement('canvas') : null);
+  if (!c) return null;
+  if (c.width !== w || c.height !== h) {
+    c.width = w;
+    c.height = h;
+  }
+  try {
+    const g = c.getContext('2d', { willReadFrequently: true });
+    g.drawImage(video, 0, 0, w, h);
+    const img = lumaFromRgba(g.getImageData(0, 0, w, h).data, w * h);
+    return { img, w, h, scale: w / W, via: 'canvas', readMs: nowMs() - t0 };
+  } catch {
+    return null; // a frame that cannot be read (tainted, not decoded yet): skip it
+  }
+}
+
+/**
+ * The measuring loop: grab a copy at most every `intervalMs`, find the disparity of the point
+ * between the subject's eyes (camera/disparity.js focus tracker), median-of-3 it. A failed grab or
+ * measurement HOLDS the last value (a blink, a hand over the face). `reset()` forgets everything,
+ * including a grab still in flight.
+ *
+ * `sample(video, at)` resolves null when it did not sample (too soon, still busy, or reset while
+ * in flight), else `{ d, frac, luma, ncc, method, via, ms }`: `d` the held disparity in SOURCE px
+ * (left x − right x; null until a first lock), `frac = d / (videoWidth / 2)` (resolution-free, what
+ * goes on the wire), `luma` the copy (null if the grab failed), `ncc`/`method` of THIS measurement
+ * (null when it failed), `ms` = read + match time.
+ *
+ * @param {{intervalMs?: number, eyeMax?: number, grab?: typeof grabLumaFrame, now?: () => number}} [o]
+ */
+export function createConvergenceMeter({ intervalMs = CONV_METER_INTERVAL_MS, eyeMax = CONV_METER_EYE_WIDTH, grab = grabLumaFrame, now = nowMs } = {}) {
+  const focus = createFocusTracker();
+  const track = createDisparityTrack();
+  let lastAt = -Infinity;
+  let busy = false;
+  let gen = 0;
+  let scratch = null;
+  const meter = {
+    get busy() {
+      return busy;
+    },
+    /** The held disparity (source px), null until a first lock. */
+    get d() {
+      return track.value;
+    },
+    async sample(video, at = now()) {
+      if (busy || at - lastAt < intervalMs) return null;
+      lastAt = at;
+      busy = true;
+      const g0 = gen;
+      try {
+        if (!scratch && globalThis.document && typeof document.createElement === 'function') scratch = document.createElement('canvas');
+        let got = null;
+        try {
+          got = await grab(video, { eyeMax, scratch });
+        } catch {
+          got = null;
+        }
+        if (g0 !== gen) return null; // reset() while the grab was in flight: a stale frame
+        const t = now();
+        const m = got ? focus.measure(got.img, got.w, got.h, at) : null;
+        const d = track.push(m ? m.d / got.scale : null);
+        const W = video && video.videoWidth;
+        return {
+          d,
+          frac: d !== null && W > 0 ? d / (W / 2) : null,
+          luma: got ? { img: got.img, w: got.w, h: got.h, scale: got.scale } : null,
+          ncc: m ? m.c : null,
+          method: m ? m.method : null,
+          via: got ? got.via : null,
+          ms: (got ? got.readMs : 0) + (now() - t),
+        };
+      } finally {
+        if (g0 === gen) busy = false;
+      }
+    },
+    reset() {
+      gen++;
+      busy = false;
+      lastAt = -Infinity;
+      focus.reset();
+      track.reset();
+    },
+  };
+  return meter;
+}