@displayxr/inline3d 1.47.6 → 1.49.0

package/js/camera/capture.js

@@ -5,16 +5,30 @@
 // 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.
+//  - A DisplayXR Browser also lists every shareable running DisplayXR APP as a side-by-side
+//    `videoinput` ("DisplayXR: <app> (3D)", id `dxr-app:…`, runtime ADR-061) — 3D screen share.
+//    It is a pair, it names itself "3D", and it is NOT a camera: no probe path opens one, whatever
+//    `exclude` says (`exclude: false` included). Each is reported in `skipped` as `excluded` with
+//    `reason: 'app-share'`. `/call`'s `listShareableApps()` / `openAppShare()` are how a page uses them.
 //
 // 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
@@ -22,6 +36,7 @@
 // `(stream, info) => MediaStream | Promise<MediaStream>`, returning a rectified SBS stream.
 
 import { looksSbs } from './geometry.js';
+import { isAppShareDevice } from './app-share.js';
 
 const MONO_CONSTRAINTS = { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } };
 // Ask a candidate stereo device for its widest mode; a 2560x720 or 3840x1080 pair comes back as
@@ -48,13 +63,57 @@ 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';
 }
 
-/** A label that names a stereo camera, tried first when probing. Pure. */
+/**
+ * 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`.
+ */
+// Generic words, plus the one hand tracker that enumerates under its bare brand name: on Windows
+// an Ultraleap (Leap 2 / Leap Motion Controller) is a UVC "Ultraleap", nothing else in the label —
+// the generic words alone let it through (win box, 2026-11-04: it was the browser's default camera).
+export const CAMERA_EXCLUDE_BUILTIN = /\b(hand[- ]?track|tracking camera|eye[- ]?track|depth camera|ultraleap|leap motion|infrared|ir 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 only the
+ * app-share rule for `exclude: false`. Returns a predicate `(label, deviceId) => boolean`. An
+ * app-share device (camera/app-share.js: a running app's views, not a camera) is ALWAYS excluded —
+ * `exclude: false` turns the sensor list off, never that. Pure.
+ * @param {false|null|undefined|ReadonlyArray<string|RegExp>|string|RegExp} exclude
+ */
+export function cameraExcluder(exclude) {
+  const app = (label, deviceId) => isAppShareDevice({ label: String(label || ''), deviceId: typeof deviceId === 'string' ? deviceId : '' });
+  if (exclude === false) return app;
+  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) => {
+    if (app(label, deviceId)) return true;
+    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. Never an app-share device's
+ * ("DisplayXR: <app> (3D)" says "3D" but is a running app, not a camera). Pure.
+ */
 export function stereoLabelHint(label) {
+  if (isAppShareDevice(String(label || ''))) return false;
   return /stereo|\b3d\b|\bsbs\b|dual/i.test(label || '');
 }
 
@@ -65,7 +124,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 +136,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];
@@ -98,13 +160,66 @@ export async function openCamera(want = 'auto', o = {}) {
     // eye-tracking camera shared without stealing it) describes itself on the opened track:
     // `displayxrStereo: {layout, rectified, baselineMm, horizontalFovDeg}`.
     const stereo = st.displayxrStereo && st.displayxrStereo.layout === 'side-by-side' ? st.displayxrStereo : null;
-    return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '', stereo };
+    // A running app's views (3D screen share, ADR-061) describe themselves too: `source: 'app'`.
+    const appShare = isAppShareDevice({ label: t.label || '', deviceId: st.deviceId || '' }) || !!(st.displayxrStereo && st.displayxrStereo.source === 'app');
+    return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '', stereo, appShare };
   };
   const skip = (label, err) => {
     skipped.push({ label, error: `${err.name}: ${err.message}`, busy: isBusyError(err), denied: isDeniedError(err) });
     log('camera-skip', { label, error: err.name });
   };
   const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
+  const listCameras = async () => {
+    try {
+      return (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput');
+    } catch {
+      return []; // no enumeration: the paths below still work
+    }
+  };
+  // Excluded devices: never opened by id; a default that turns out to be one is closed again.
+  const excludedIds = new Set();
+  // `reason`: 'app-share' for a running app's views (never a camera), else 'excluded'.
+  const exclude = (label, deviceId, reason = 'excluded') => {
+    if (deviceId && excludedIds.has(deviceId)) return;
+    if (deviceId) excludedIds.add(deviceId);
+    skipped.push({ label, error: 'excluded', excluded: true, reason });
+    log('camera-skip', { label, error: 'excluded', reason });
+  };
+  const isApp = (d) => isAppShareDevice({ label: d.label || '', deviceId: d.deviceId || '' });
+  const listedExcluded = (d) => {
+    if (isApp(d)) {
+      exclude(d.label || '', d.deviceId, 'app-share');
+      return true;
+    }
+    if (!d.label || !isExcluded(d.label, d.deviceId)) return false;
+    exclude(d.label, d.deviceId);
+    return true;
+  };
+  /** An opened device that must not be used: an app share (by its own hint too) or an excluded label. Closes it. */
+  const rejectOpened = (r) => {
+    if (r.appShare) {
+      stop(r);
+      exclude(r.label, r.deviceId, 'app-share');
+      return true;
+    }
+    if (isExcluded(r.label, r.deviceId)) {
+      stop(r);
+      exclude(r.label, r.deviceId);
+      return true;
+    }
+    return false;
+  };
+  // 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 (rejectOpened(r)) {
+      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 {
@@ -135,6 +250,28 @@ export async function openCamera(want = 'auto', o = {}) {
     },
   });
 
+  // `label:<text>`: the first camera whose label contains the text (case-insensitive) — a way to
+  // force a device from a URL or a config, where a per-origin deviceId is useless. Labels need
+  // permission: with none visible yet, the default camera is primed once and let go. Explicit like
+  // a deviceId, so it opens an excluded device too.
+  if (typeof want === 'string' && want.startsWith('label:')) {
+    const needle = want.slice('label:'.length).trim().toLowerCase();
+    let list = await listCameras();
+    if (needle && list.length && list.every((d) => !d.label)) {
+      try {
+        stop(await open(true));
+      } catch (err) {
+        skip('default', err);
+      }
+      list = await listCameras();
+    }
+    // Never a running app's views: `label:3d` means a camera (open an app with openAppShare()).
+    const d = needle ? list.find((x) => x.deviceId && !isApp(x) && (x.label || '').toLowerCase().includes(needle)) : null;
+    if (!d) throw Object.assign(new Error(`camera unavailable: no camera labelled "${needle}"`), { code: noCameraCode(skipped), skipped });
+    log('camera-label', { label: d.label, needle });
+    want = d.deviceId;
+  }
+
   // An explicit device id.
   if (typeof want === 'string' && !['auto', 'stereo', 'mono'].includes(want)) {
     let r;
@@ -154,17 +291,11 @@ export async function openCamera(want = 'auto', o = {}) {
   // camera start can take seconds (a busy capture stack took 7-20 s per start on a field box), and
   // the default-first probe below costs two or three of them before it reaches the pair.
   const tried = new Set();
-  const listCameras = async () => {
-    try {
-      return (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput');
-    } catch {
-      return []; // no enumeration: the paths below still work
-    }
-  };
   const tryNamedPairs = async (list) => {
     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 });
@@ -172,6 +303,7 @@ export async function openCamera(want = 'auto', o = {}) {
         skip(d.label, err);
         continue;
       }
+      if (rejectOpened(r)) continue; // an app that described itself only on its track
       if (isPair(r)) {
         log('camera-sbs', { label: r.label, width: r.width, height: r.height, direct: true });
         return r;
@@ -192,33 +324,53 @@ 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) {
-    try {
-      mono = await open(MONO_CONSTRAINTS);
-    } catch (err) {
-      skip('default', err);
+  // With labels visible and an excluded device listed, the default is not opened blind — it may BE
+  // the sensor (an idle Ultraleap is the default camera on some Windows boxes, and an eye tracker's
+  // camera should not be started at all) — the first camera that is not excluded is opened by id.
+  if (!mono && !defaultExcluded) {
+    const listed = await listCameras();
+    const anyExcluded = listed.filter(listedExcluded).length > 0; // every excluded device is noted, not just the first
+    const first = anyExcluded ? listed.find((d) => d.deviceId && !excludedIds.has(d.deviceId)) || null : null;
+    if (first) {
+      if (first.deviceId) tried.add(first.deviceId);
+      try {
+        mono = await open({ deviceId: { exact: first.deviceId }, ...MONO_CONSTRAINTS });
+        if (rejectOpened(mono)) mono = null;
+      } catch (err) {
+        skip(first.label, err);
+      }
+    } else {
+      try {
+        mono = await openDefault(MONO_CONSTRAINTS);
+      } catch (err) {
+        skip('default', err);
+      }
     }
   }
   if (want === 'mono' && mono) return result(mono, 'mono');
@@ -230,11 +382,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 +397,18 @@ export async function openCamera(want = 'auto', o = {}) {
       skip(d.label, err);
       continue;
     }
-    if (isPair(r)) {
+    if (rejectOpened(r)) continue;
+    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 +422,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;
+}