@displayxr/inline3d 1.29.0 → 1.30.0

package/js/call/capture.js

@@ -1,212 +1,4 @@
-// call/capture.js — getting a camera (+ microphone) and knowing what it is (RFC §4).
-//
-// `camera: 'auto'` looks for a device that delivers a side-by-side PAIR — one device whose frame
-// is wider than 2.5:1 (a USB stereo camera enumerates as one wide device: field data has one at
-// 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:
-//  - 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.
-//  - Labels are empty until one getUserMedia has succeeded, so the default camera is opened first
-//    (which is also the fallback), then the others are probed one at a time.
-//
-// 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
-// `rectified: false`, and the `rectify` hook (addCall option) is where a calibrated step plugs in:
-// `(stream, info) => MediaStream | Promise<MediaStream>`, returning a rectified SBS stream.
-
-import { looksSbs } from './wire.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
-// itself, a 1280x480 one as 1280x480. `ideal`, never `min`: a smaller real pair is still a pair.
-const PROBE_CONSTRAINTS = { width: { ideal: 3840 }, height: { ideal: 1080 }, frameRate: { ideal: 30 } };
-export const AUDIO_CONSTRAINTS = Object.freeze({ echoCancellation: true, noiseSuppression: true, autoGainControl: true });
-
-/** Errors that mean "the device exists but another process holds it" (an eye tracker, say). */
-export function isBusyError(err) {
-  return !!err && (err.name === 'NotReadableError' || err.name === 'TrackStartError' || /in use|busy/i.test(err.message || ''));
-}
-
-/**
- * Why no camera could be opened, from the per-device failures. `'camera-busy'` when every device
- * that exists is held by another process — on a 3D laptop/monitor whose only camera is the eye
- * tracker's, that is the normal case while tracking, and the call should go audio-only and say so
- * rather than fail or send an empty picture. Pure.
- * @param {Array<{error: string, busy?: boolean}>} skipped
- */
-export function noCameraCode(skipped) {
-  return skipped.length && skipped.every((s) => s.busy) ? 'camera-busy' : 'no-camera';
-}
-
-/** 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 || '');
-}
-
-/**
- * Open the camera. Never rejects for a busy optional device; rejects only when NO camera can be
- * opened at all (the caller then runs audio-only or reports the error).
- *
- * @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]
- * @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 }>}
- */
-export async function openCamera(want = 'auto', o = {}) {
-  const md = o.mediaDevices || (globalThis.navigator && navigator.mediaDevices);
-  const log = o.log || (() => {});
-  const skipped = [];
-  const cal = o.calibration || {};
-
-  if (want && typeof want === 'object' && typeof want.getVideoTracks === 'function') {
-    const t = want.getVideoTracks()[0];
-    const st = t ? t.getSettings() : {};
-    // A page-supplied stream carries a DECLARED format; aspect is never used to guess 3D-ness here.
-    const format = o.format === 'sbs' ? 'sbs' : 'mono';
-    return { stream: want, format, width: st.width || 0, height: st.height || 0, deviceId: st.deviceId || null, label: t ? t.label : '', owned: false, skipped, calibration: cal };
-  }
-  if (!md || !md.getUserMedia) throw Object.assign(new Error('getUserMedia is not available (insecure context?)'), { code: 'no-camera' });
-
-  const open = async (constraints) => {
-    const s = await md.getUserMedia({ video: constraints, audio: false });
-    const t = s.getVideoTracks()[0];
-    const st = t ? t.getSettings() : {};
-    // Never hand back a 0x0 track: some engines open a device that then delivers nothing.
-    if (!t || t.readyState === 'ended' || !(st.width > 0) || !(st.height > 0)) {
-      s.getTracks().forEach((x) => x.stop());
-      throw Object.assign(new Error('the camera opened but delivers no picture (0x0)'), { name: 'NotReadableError' });
-    }
-    // The DisplayXR Browser's "3D Camera (DisplayXR)" (the runtime's stereo camera, e.g. an SR
-    // 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 };
-  };
-  const skip = (label, err) => {
-    skipped.push({ label, error: `${err.name}: ${err.message}`, busy: isBusyError(err) });
-    log('camera-skip', { label, error: err.name });
-  };
-  const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
-  const result = (r, format) => ({
-    stream: r.stream, format, width: r.width, height: r.height, deviceId: r.deviceId, label: r.label, owned: true, skipped,
-    calibration: {
-      rectified: false,
-      // A runtime stereo camera's own description, where the page gave none.
-      ...(format === 'sbs' && r.stereo
-        ? {
-            rectified: !!r.stereo.rectified,
-            ...(r.stereo.baselineMm > 0 ? { baselineMm: r.stereo.baselineMm } : {}),
-            ...(r.stereo.horizontalFovDeg > 0 ? { hfovDeg: r.stereo.horizontalFovDeg } : {}),
-          }
-        : {}),
-      ...cal,
-    },
-  });
-
-  // An explicit device id.
-  if (typeof want === 'string' && !['auto', 'stereo', 'mono'].includes(want)) {
-    let r;
-    try {
-      r = await open({ deviceId: { exact: want }, ...PROBE_CONSTRAINTS });
-    } catch (err) {
-      skip(want, err);
-      throw Object.assign(new Error(`camera unavailable: ${err.message}`), { code: noCameraCode(skipped), skipped });
-    }
-    if (looksSbs(r.width, r.height)) return result(r, 'sbs');
-    stop(r);
-    return result(await open({ deviceId: { exact: want }, ...MONO_CONSTRAINTS }), 'mono');
-  }
-
-  // Fast path: when labels are already visible (camera permission persisted), open a device that
-  // NAMES itself stereo — e.g. the DisplayXR Browser's "3D Camera (DisplayXR)" — directly. Every
-  // 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();
-  if (want !== 'mono') {
-    let early = [];
-    try {
-      early = (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput' && d.deviceId && stereoLabelHint(d.label));
-    } catch {
-      /* no enumeration yet: the normal path below */
-    }
-    for (const d of early) {
-      tried.add(d.deviceId);
-      let r = null;
-      try {
-        r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
-      } catch (err) {
-        skip(d.label, err);
-        continue;
-      }
-      if (looksSbs(r.width, r.height)) {
-        log('camera-sbs', { label: r.label, width: r.width, height: r.height, direct: true });
-        return result(r, 'sbs');
-      }
-      stop(r);
-    }
-  }
-
-  // The default camera first: permission, labels, and the fallback.
-  let mono = null;
-  try {
-    mono = await open(MONO_CONSTRAINTS);
-  } catch (err) {
-    skip('default', err);
-  }
-  if (want === 'mono' && mono) return result(mono, 'mono');
-  if (mono && looksSbs(mono.width, mono.height)) return result(mono, 'sbs'); // the default IS the pair
-
-  let devices = [];
-  try {
-    devices = (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput');
-  } catch {
-    /* no enumeration: keep the default */
-  }
-  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)
-    let r = null;
-    try {
-      r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
-    } catch (err) {
-      // NotReadableError = held by another process (e.g. an eye tracker). Skip, never fail.
-      skip(d.label, err);
-      continue;
-    }
-    if (looksSbs(r.width, r.height)) {
-      stop(mono);
-      log('camera-sbs', { label: r.label, width: r.width, height: r.height });
-      return result(r, 'sbs');
-    }
-    stop(r);
-  }
-  if (mono) {
-    if (want === 'stereo') log('camera-no-stereo', { fallback: mono.label });
-    return result(mono, 'mono');
-  }
-  const code = noCameraCode(skipped);
-  throw Object.assign(
-    new Error(code === 'camera-busy' ? 'every camera is in use by another app (e.g. eye tracking)' : 'no camera could be opened'),
-    { code, skipped }
-  );
-}
-
-/** The microphone, with echo cancellation and noise suppression. Null if unavailable/denied. */
-export async function openMic(o = {}) {
-  const md = o.mediaDevices || (globalThis.navigator && navigator.mediaDevices);
-  try {
-    const s = await md.getUserMedia({ audio: { ...AUDIO_CONSTRAINTS }, video: false });
-    return s.getAudioTracks()[0] || null;
-  } catch (err) {
-    (o.log || (() => {}))('mic-skip', { error: err && err.name });
-    return null;
-  }
-}
+// call/capture.js — moved to js/camera/capture.js in C2 (RFC 0003 §4: device selection,
+// calibration and the busy-device skip belong to `@displayxr/inline3d/camera`). This path
+// re-exports it so test imports and any in-tree reference keep resolving.
+export * from '../camera/capture.js';

package/js/call/disparity.js

@@ -1,432 +1,4 @@
-// Auto-convergence (RFC 0002 §3): MEASURE how far apart the remote person's eyes are between the two
-// halves of their side-by-side frame, so the receiver can shift each eye by d/2 in opposite
-// directions and put the point between the eyes at zero parallax (the display plane).
-//
-// No focal length, baseline or distance: those only PREDICT the disparity (f·B/Z); here it is read
-// off the pixels. Works for any SBS sender, calibrated or not, as long as the rows roughly align (a
-// small vertical search absorbs the residual of a raw, unrectified pair).
-//
-// The focus is ONE point, the midpoint between the eyes. It stays meaningful when the head turns (one
-// eye may be hidden), unlike "both eyes" or "the whole face". Without a face detector the module
-// finds the subject as the NEAREST strong disparity mode (in a call the person is in front of the
-// room) and takes the eye line from the top of that blob.
-//
-// Pure: a grayscale SBS image in, numbers out. No DOM, no WebRTC. Sizes are in the INPUT's pixels;
-// the caller scales back to source pixels.
-
-/** Blocks with a luma standard deviation below this are too flat to match. */
-const MIN_TEXTURE = 6;
-
-/** A block match must reach this normalised cross-correlation to count. */
-export const MIN_NCC = 0.8;
-
-/** ...and beat its best rival peak (>= 3 px away) by this much, or it is ambiguous (periodic). */
-export const UNIQUENESS = 0.08;
-
-/**
- * Normalised cross-correlation of a `bw`×`bh` block of the left eye at (lx, ly) against the right
- * eye at (rx, ry). `img` is the whole SBS image, `W` its full width, `E` the per-eye width.
- * Returns -1 when the right block would leave the right eye or is flat.
- */
-function ncc(img, W, E, lx, ly, rx, ry, bw, bh, lMean, lStd) {
-  if (rx < 0 || rx + bw > E || ry < 0) return -1;
-  let sum = 0;
-  let sum2 = 0;
-  let cross = 0;
-  const n = bw * bh;
-  for (let y = 0; y < bh; y++) {
-    const lo = (ly + y) * W + lx;
-    const ro = (ry + y) * W + E + rx;
-    for (let x = 0; x < bw; x++) {
-      const r = img[ro + x];
-      sum += r;
-      sum2 += r * r;
-      cross += img[lo + x] * r;
-    }
-  }
-  const rMean = sum / n;
-  const rVar = sum2 / n - rMean * rMean;
-  if (rVar < 1) return -1;
-  return (cross / n - lMean * rMean) / (lStd * Math.sqrt(rVar));
-}
-
-function blockStats(img, W, x0, y0, bw, bh) {
-  let sum = 0;
-  let sum2 = 0;
-  for (let y = 0; y < bh; y++) {
-    const o = (y0 + y) * W + x0;
-    for (let x = 0; x < bw; x++) {
-      const v = img[o + x];
-      sum += v;
-      sum2 += v * v;
-    }
-  }
-  const n = bw * bh;
-  const mean = sum / n;
-  return { mean, std: Math.sqrt(Math.max(0, sum2 / n - mean * mean)) };
-}
-
-/**
- * Best horizontal disparity of one left-eye block: `d = xLeft − xRight` (positive = crossed = in
- * front of the display plane), searched over [dMin, dMax] and ±dy rows. Sub-pixel by a parabola.
- * @returns {{d:number, dy:number, c:number}|null}
- */
-export function matchBlock(img, W, H, x0, y0, bw, bh, { dMin, dMax, dyMax = 2, uniq } = {}) {
-  const E = W / 2;
-  const { mean, std } = blockStats(img, W, x0, y0, bw, bh);
-  if (std < MIN_TEXTURE) return null;
-  let best = -2;
-  let bd = 0;
-  let bdy = 0;
-  const perD = new Map(); // best NCC seen at each disparity (any row), for the uniqueness test
-  const scan = (d0, d1, dStep, y0s, y1s) => {
-    for (let dy = y0s; dy <= y1s; dy++) {
-      const ry = y0 + dy;
-      if (ry < 0 || ry + bh > H) continue;
-      for (let d = d0; d <= d1; d += dStep) {
-        const c = ncc(img, W, E, x0, y0, x0 - d, ry, bw, bh, mean, std);
-        if (c > (perD.get(d) ?? -2)) perD.set(d, c);
-        if (c > best) {
-          best = c;
-          bd = d;
-          bdy = dy;
-        }
-      }
-    }
-  };
-  // Coarse (every 2nd disparity, rows every 2nd), then a full-resolution pass around the winner:
-  // ~1/4 of the exhaustive cost, and textures here are never finer than the downscaled 2-px step.
-  const coarse = dMax - dMin > 8;
-  scan(dMin, dMax, coarse ? 2 : 1, -dyMax, dyMax);
-  if (coarse && best > -1) {
-    const cd = bd;
-    const cy = bdy;
-    scan(Math.max(dMin, cd - 2), Math.min(dMax, cd + 2), 1, Math.max(-dyMax, cy - 1), Math.min(dyMax, cy + 1));
-  }
-  if (best < -1) return null;
-  // Uniqueness: a repeating texture (a checkerboard, a striped shirt, blinds) matches equally well
-  // one period away. Reject the block unless its best peak clearly beats every peak >= 3 px away.
-  // The coarse scan samples every 2nd disparity, so a rival peak between two samples is under-read
-  // while the winner has been refined to its top; refine each rival local maximum at +-1 as well, or
-  // an exactly periodic pattern slips through by a hair.
-  let second = -2;
-  const peakAt = (d) => {
-    let v = -2;
-    for (let dy = -dyMax; dy <= dyMax; dy++) {
-      const ry = y0 + dy;
-      if (ry < 0 || ry + bh > H) continue;
-      for (let k = d - 1; k <= d + 1; k++) v = Math.max(v, ncc(img, W, E, x0, y0, x0 - k, ry, bw, bh, mean, std));
-    }
-    return v;
-  };
-  for (const [d, c] of perD) {
-    if (Math.abs(d - bd) < 3 || c <= second) continue;
-    const isLocalMax = c >= (perD.get(d - 2) ?? -2) && c >= (perD.get(d + 2) ?? -2);
-    const v = isLocalMax && c > 0 ? peakAt(d) : c;
-    if (v > second) second = v;
-  }
-  // Only for WIDE searches: in a narrow (tracking/refine) window a smooth face legitimately scores
-  // high a few px off its peak, and a window anchored on a known disparity cannot alias anyway.
-  if (dMax - dMin > 12 && second > -2 && best - second < (uniq ?? UNIQUENESS)) return null;
-  // Sub-pixel along d at the best row.
-  const cm = ncc(img, W, E, x0, y0, x0 - (bd - 1), y0 + bdy, bw, bh, mean, std);
-  const cp = ncc(img, W, E, x0, y0, x0 - (bd + 1), y0 + bdy, bw, bh, mean, std);
-  let sub = 0;
-  const den = cm - 2 * best + cp;
-  if (cm > -1 && cp > -1 && den < 0) sub = Math.max(-0.5, Math.min(0.5, (0.5 * (cm - cp)) / den));
-  return { d: bd + sub, dy: bdy, c: best };
-}
-
-/**
- * Block disparities over the central region of the LEFT eye.
- * @returns {Array<{x:number,y:number,d:number,dy:number,c:number}>} block top-left corners
- */
-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
-  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));
-  const x1 = Math.round(E * (o.roiX1 ?? 0.85)) - b;
-  const y0 = Math.round(H * (o.roiY0 ?? 0.05));
-  const y1 = Math.round(H * (o.roiY1 ?? 0.85)) - b;
-  const out = [];
-  for (let y = y0; y <= y1; y += step) {
-    for (let x = x0; x <= x1; x += step) {
-      const m = matchBlock(img, W, H, x, y, b, b, { dMin, dMax, dyMax: o.dyMax ?? 2, uniq: o.uniq });
-      if (m && m.c >= (o.minNcc ?? MIN_NCC)) out.push({ x, y, ...m });
-    }
-  }
-  return out;
-}
-
-/**
- * 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 } = {}) {
-  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);
-    if (members.length >= need) {
-      const md = members.map((b) => b.d).sort((a, b) => a - b);
-      return { d: md[md.length >> 1], members };
-    }
-  }
-  return null;
-}
-
-/**
- * Where the eyes are in a subject blob: horizontally the centre of its TOP rows (the head, not the
- * shoulders), vertically ~40% down a head whose height ≈ 1.3 × its width.
- *
- * Measured on real SR-camera frames (grayscale, dim), only a handful of blocks match on a face, so
- * this lands on the upper face, often the forehead, a few cm above the eyes. That is the same depth
- * plane to within ~1 cm: at 0.6 m the disparity differs by ~1-2 source px, under 1 px of shift per
- * eye. A darkest-band eye-line search was tried and rejected: the darkest band is the hair. Pass
- * `focus` (a face detector's eye midpoint) for the exact point.
- */
-export function eyeMidpoint(members, block) {
-  const top = Math.min(...members.map((m) => m.y));
-  const headRows = members.filter((m) => m.y <= top + 2 * block);
-  const xs = headRows.map((m) => m.x);
-  const xMin = Math.min(...xs);
-  const xMax = Math.max(...xs) + block;
-  const headW = xMax - xMin;
-  return { x: (xMin + xMax) / 2, y: top + 0.4 * 1.3 * headW };
-}
-
-/**
- * The disparity of the point between the eyes, in input pixels.
- *
- * @param {Uint8Array|Uint8ClampedArray|number[]} img  grayscale SBS, row-major, `W`×`H`
- * @param {number} W  full SBS width (both eyes)
- * @param {number} H
- * @param {object} [o]
- * @param {{x:number,y:number}} [o.focus]  the eye midpoint in LEFT-eye pixels (e.g. from a face
- *        detector); skips the subject search
- * @returns {{d:number, x:number, y:number, c:number, method:'focus'|'mode', blocks:number}|null}
- */
-export function measureFocusDisparity(img, W, H, o = {}) {
-  const E = W / 2;
-  const b = o.block || Math.max(8, Math.round(E / 20));
-  const dMax = o.dMax ?? Math.round(E * 0.3);
-  const dMin = o.dMin ?? -Math.round(E * 0.05);
-  let focus = o.focus || null;
-  let method = 'focus';
-  let blocks = 0;
-  let d0 = null;
-  if (!focus) {
-    const all = blockDisparities(img, W, H, { ...o, block: b, dMax, dMin });
-    blocks = all.length;
-    const mode = nearestMode(all, o);
-    if (!mode) return null;
-    focus = eyeMidpoint(mode.members, b);
-    d0 = mode.d;
-    method = 'mode';
-  }
-  // Refine with one wider window centred on the focus point: eyes + brow + nose bridge carry
-  // plenty of texture even when one eye is turned away.
-  const ww = Math.round(b * (o.refineW ?? 3));
-  const wh = Math.round(b * (o.refineH ?? 1.5));
-  const rx = Math.round(Math.max(0, Math.min(E - ww, focus.x - ww / 2)));
-  const ry = Math.round(Math.max(0, Math.min(H - wh, focus.y - wh / 2)));
-  const lo = d0 === null ? dMin : Math.max(dMin, Math.floor(d0) - 4);
-  const hi = d0 === null ? dMax : Math.min(dMax, Math.ceil(d0) + 4);
-  const m = matchBlock(img, W, H, rx, ry, ww, wh, { dMin: lo, dMax: hi, dyMax: o.dyMax ?? 2 });
-  if (m && m.c >= (o.minNcc ?? MIN_NCC)) return { d: m.d, x: focus.x, y: focus.y, c: m.c, method, blocks };
-  // A flat or occluded focus window: fall back to the subject's mode.
-  if (d0 !== null) return { d: d0, x: focus.x, y: focus.y, c: 0, method, blocks };
-  return null;
-}
-
-/** RGBA pixels (ImageData.data) of a SBS frame → luma, same size. */
-export function lumaFromRgba(rgba, n) {
-  const out = new Uint8Array(n);
-  for (let i = 0, j = 0; i < n; i++, j += 4) out[i] = (rgba[j] * 77 + rgba[j + 1] * 150 + rgba[j + 2] * 29) >> 8;
-  return out;
-}
-
-/**
- * Temporal steadiness for measurements: the median of the last `n` accepted values, and a hold of
- * the last good value when a measurement fails (a blink, a hand over the face) rather than snapping
- * back to zero.
- */
-export function createDisparityTrack({ n = 3 } = {}) {
-  const hist = [];
-  const t = {
-    value: null,
-    push(d) {
-      if (d === null || !Number.isFinite(d)) return t.value;
-      hist.push(d);
-      if (hist.length > n) hist.shift();
-      const s = [...hist].sort((a, b) => a - b);
-      t.value = s[s.length >> 1];
-      return t.value;
-    },
-    reset() {
-      hist.length = 0;
-      t.value = null;
-    },
-  };
-  return t;
-}
-
-/** Copy a `w`×`h` patch of the LEFT eye at (x, y). */
-function copyPatch(img, W, x, y, w, h) {
-  const p = new Float32Array(w * h);
-  for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) p[r * w + c] = img[(y + r) * W + x + c];
-  return p;
-}
-
-/** Best NCC position of `tpl` (w×h) in the LEFT eye within ±rx/±ry of (x0, y0). */
-function findInLeft(img, W, H, tpl, w, h, x0, y0, rx, ry) {
-  const E = W / 2;
-  const n = w * h;
-  let tm = 0;
-  let t2 = 0;
-  for (let i = 0; i < n; i++) {
-    tm += tpl[i];
-    t2 += tpl[i] * tpl[i];
-  }
-  tm /= n;
-  const ts = Math.sqrt(Math.max(1e-6, t2 / n - tm * tm));
-  let best = -2;
-  let bx = x0;
-  let by = y0;
-  for (let y = Math.max(0, y0 - ry); y <= Math.min(H - h, y0 + ry); y++) {
-    for (let x = Math.max(0, x0 - rx); x <= Math.min(E - w, x0 + rx); x++) {
-      let s = 0;
-      let s2 = 0;
-      let cr = 0;
-      for (let r = 0; r < h; r++) {
-        const o = (y + r) * W + x;
-        for (let c = 0; c < w; c++) {
-          const v = img[o + c];
-          s += v;
-          s2 += v * v;
-          cr += v * tpl[r * w + c];
-        }
-      }
-      const m = s / n;
-      const vr = s2 / n - m * m;
-      if (vr < 1) continue;
-      const cc = (cr / n - m * tm) / (Math.sqrt(vr) * ts);
-      if (cc > best) {
-        best = cc;
-        bx = x;
-        by = y;
-      }
-    }
-  }
-  return { x: bx, y: by, c: best };
-}
-
-/**
- * Cheap frame-to-frame tracking of the focus point. A full subject search (measureFocusDisparity)
- * locks on; after that each call only re-finds a small left-eye template around the last position
- * (the head moved) and matches it to the right eye in a ±`dWin` disparity window. The full search
- * re-runs every `fullEveryMs`, or as soon as tracking loses the template.
- */
-export function createFocusTracker({ fullEveryMs = 2000, dWin = 4, rx = 12, ry = 8, minTrackNcc = 0.75, jump = 8 } = {}) {
-  let st = null; // { x, y, d, tpl, w, h, at }
-  let pending = null; // a re-search result that disagreed with a healthy track, awaiting confirmation
-  const t = {
-    /** @returns {{d:number,x:number,y:number,c:number,method:'mode'|'focus'|'track',blocks:number}|null} */
-    measure(img, W, H, now, o = {}) {
-      const E = W / 2;
-      const b = o.block || Math.max(8, Math.round(E / 20));
-      const w = Math.round(b * 3);
-      const h = Math.round(b * 1.5);
-      // Track first, whenever there is something to track.
-      let tracked = null;
-      if (st && st.w === w && st.h === h) {
-        const f = findInLeft(img, W, H, st.tpl, w, h, st.x, st.y, rx, ry);
-        if (f.c >= minTrackNcc) {
-          const m = matchBlock(img, W, H, f.x, f.y, w, h, { dMin: Math.floor(st.d) - dWin, dMax: Math.ceil(st.d) + dWin, dyMax: 2 });
-          if (m && m.c >= MIN_NCC) tracked = { m, f };
-        }
-      }
-      const accept = ({ m, f }) => {
-        st = { ...st, x: f.x, y: f.y, d: m.d, tpl: copyPatch(img, W, f.x, f.y, w, h) };
-        return { d: m.d, x: f.x + w / 2, y: f.y + h / 2, c: m.c, method: 'track', blocks: 0 };
-      };
-      if (tracked && now - st.at < fullEveryMs) return accept(tracked);
-      const m = measureFocusDisparity(img, W, H, o);
-      if (tracked && (!m || Math.abs(m.d - tracked.m.d) > jump)) {
-        // A periodic re-search that disagrees with a HEALTHY track is not trusted on its own (a
-        // repeating background can alias one period away): switch only when the next re-search
-        // confirms it (a new, nearer person really did step in).
-        const confirmed = m && pending && Math.abs(pending.d - m.d) <= 3;
-        pending = m && !confirmed ? { d: m.d } : null;
-        if (!confirmed) {
-          st.at = now;
-          return accept(tracked);
-        }
-      } else pending = null;
-      if (!m) {
-        st = null;
-        return null;
-      }
-      const x = Math.round(Math.max(0, Math.min(E - w, m.x - w / 2)));
-      const y = Math.round(Math.max(0, Math.min(H - h, m.y - h / 2)));
-      st = { x, y, d: m.d, tpl: copyPatch(img, W, x, y, w, h), w, h, at: now };
-      return m;
-    },
-    reset() {
-      st = null;
-      pending = null;
-    },
-  };
-  return t;
-}
-
-/**
- * Downsample a luma plane by an integer `factor` (the Y plane of a decoded frame, read straight from
- * WebCodecs: no RGBA conversion, no canvas). Averaging, not single-point sampling, so sensor noise
- * does not become false texture: the full box for factors <= 2, a 2x2 sample per cell above.
- * @param {Uint8Array} src  the plane
- * @param {number} offset  byte offset of the plane in `src`
- * @param {number} stride  bytes per source row
- * @returns {{img: Uint8Array, w: number, h: number}}
- */
-export function downsampleLuma(src, offset, stride, srcW, srcH, factor) {
-  const f = Math.max(1, factor | 0);
-  let w = Math.floor(srcW / f);
-  w -= w & 1; // even, so the SBS halves split cleanly
-  const h = Math.floor(srcH / f);
-  const out = new Uint8Array(w * h);
-  if (f <= 2) {
-    // Small factors: the full box.
-    const n = f * f;
-    for (let y = 0; y < h; y++) {
-      for (let x = 0; x < w; x++) {
-        let sum = 0;
-        for (let dy = 0; dy < f; dy++) {
-          const o = offset + (y * f + dy) * stride + x * f;
-          for (let dx = 0; dx < f; dx++) sum += src[o + dx];
-        }
-        out[y * w + x] = (sum / n) | 0;
-      }
-    }
-    return { img: out, w, h };
-  }
-  // Larger factors: a 2x2 sample at the quarter points of each cell. Enough averaging to keep sensor
-  // and codec noise from reading as texture, at ~1/9 of the full box's cost for f = 6 (the full box
-  // over a 2560x720 luma plane was ~8 ms of JS per measurement).
-  const a = f >> 2;
-  const c = (3 * f) >> 2;
-  for (let y = 0; y < h; y++) {
-    const r0 = offset + (y * f + a) * stride;
-    const r1 = offset + (y * f + c) * stride;
-    for (let x = 0; x < w; x++) {
-      const x0 = x * f + a;
-      const x1 = x * f + c;
-      out[y * w + x] = (src[r0 + x0] + src[r0 + x1] + src[r1 + x0] + src[r1 + x1]) >> 2;
-    }
-  }
-  return { img: out, w, h };
-}
+// call/disparity.js — moved to js/camera/disparity.js in C2 (RFC 0003 §4: auto-convergence is a
+// camera-side measurement that the call and `addCameraView` share). This path re-exports it so
+// test imports and any in-tree reference keep resolving; new code imports the camera module.
+export * from '../camera/disparity.js';