@displayxr/inline3d 1.29.0 → 1.31.0

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';

package/js/call/element.js

@@ -37,7 +37,7 @@ import { mountCall, dxrSignaling } from '../inline3d-call.js';
 
 /** Every call event is re-dispatched as `dxr-call:<type>`; `dxr-call:ready` carries the handle. */
 export const CALL_EVENT_PREFIX = 'dxr-call:';
-const CALL_EVENTS = ['joined', 'left', 'peer', 'peerleft', 'state', 'format', 'speaker', 'quality', 'error', 'warning', 'session'];
+const CALL_EVENTS = ['joined', 'left', 'peer', 'peerleft', 'state', 'display', 'speaker', 'quality', 'error', 'warning'];
 const TAG = '[inline3d/call] <dxr-call>';
 
 /** A boolean attribute: present is true, unless its value spells "false"/"0"/"off"/"no". */
@@ -61,18 +61,19 @@ const str = (v) => (v === null || v === undefined || String(v).trim() === '' ? u
  * | `signaling`          | `signaling: dxrSignaling(url)`           |
  * | `key`                | `key`                                    |
  * | `camera`             | `camera` (`auto`/`stereo`/`mono`/deviceId)|
- * | `layout`             | `layout` (`grid`/`speaker`)              |
- * | `accent`             | `accent`                                 |
+ * | `layout`             | `layout` (`grid`/`speaker`/`none`)       |
+ * | `accent`             | `theme.accent`                           |
  * | `max-peers`          | `maxPeers`                               |
  * | `no-ui`              | `ui: false`                              |
+ * | `ui="tiles"`         | `ui: 'tiles'`                            |
  * | `auto-join`          | `autoJoin: true`                         |
  * | `mono3d="off"`       | `mono3D: 'off'`                          |
  * | `no-audio`           | `audio: false`                           |
  * | `no-self-view`       | `selfView: false`                        |
  * | `no-auto-converge`   | `autoConverge: false`                    |
- * | `tile-aspect`        | `tileAspect` (a number, or `w/h`)        |
- * | `invite-base`        | `inviteBase`                             |
- * | `browser-url`        | `browserUrl`                             |
+ * | `tile-aspect`        | `theme.tileAspect` (a number, or `w/h`)  |
+ * | `invite-base`        | `invite.base`                            |
+ * | `browser-url`        | `landing.browserUrl`                     |
  * | `debug`              | `debug: true`                            |
  *
  * @param {{ getAttribute(name: string): string | null } | ((name: string) => string | null)} source
@@ -90,18 +91,21 @@ export function attrsToOpts(source) {
   put('key', str(get('key')));
   put('camera', str(get('camera')));
   put('layout', str(get('layout')));
-  put('accent', str(get('accent')));
   put('maxPeers', num(get('max-peers')));
+  const ui = str(get('ui'));
   if (isOn(get('no-ui'))) o.ui = false;
+  else if (ui === 'tiles') o.ui = 'tiles';
   if (isOn(get('auto-join'))) o.autoJoin = true;
   const m3 = str(get('mono3d'));
   if (m3 && /^(off|false|0|no)$/i.test(m3)) o.mono3D = 'off';
   if (isOn(get('no-audio'))) o.audio = false;
   if (isOn(get('no-self-view'))) o.selfView = false;
   if (isOn(get('no-auto-converge'))) o.autoConverge = false;
-  put('tileAspect', num(get('tile-aspect')));
-  put('inviteBase', str(get('invite-base')));
-  put('browserUrl', str(get('browser-url')));
+  // The C2 groups (RFC 0003 §2): the attribute names are the C1 ones, the option shapes are new.
+  const theme = { accent: str(get('accent')), tileAspect: num(get('tile-aspect')) };
+  if (theme.accent !== undefined || theme.tileAspect !== undefined) o.theme = Object.fromEntries(Object.entries(theme).filter(([, v]) => v !== undefined));
+  if (str(get('invite-base'))) o.invite = { base: str(get('invite-base')) };
+  if (str(get('browser-url'))) o.landing = { browserUrl: str(get('browser-url')) };
   if (isOn(get('debug'))) o.debug = true;
   return o;
 }

package/js/call/options.js

@@ -0,0 +1,132 @@
+// call/options.js — `CallOptions` → the module's internal shape (RFC 0003 §2): defaults,
+// validation, the C2 groups (`theme`, `invite`, `landing`, `liftOptions.max`) folded flat, and the
+// 1.29 spellings accepted for one release with a warning. Pure (no DOM, no network) — see
+// test/call.test.mjs. Internal: importable by path, not part of the `./call` entry.
+
+import { isValidRoomId, parseInviteLink, DEFAULT_MAX_PEERS } from './wire.js';
+import { clampMaxPeers } from './transport.js';
+import { normalizeMono3D } from './lift.js';
+import { dxrSignaling } from './signaling.js';
+import { resolveCallAccent, THEME_VARS } from './ui.js';
+
+const TAG = '[inline3d/call]';
+const DEFAULT_BROWSER_URL = 'https://github.com/DisplayXR/displayxr-browser';
+
+/**
+ * The 1.29 option spellings and where they went (RFC 0003 §2). Accepted for one release with a
+ * single console.warn per key; `normalizeCallOptions` folds them into the C2 shape. 1.31 drops
+ * them. The `<dxr-call>` ATTRIBUTES keep their names — the element maps them to the new shapes.
+ */
+export const LEGACY_OPTIONS = Object.freeze({
+  accent: 'theme.accent',
+  tileAspect: 'theme.tileAspect',
+  inviteBase: 'invite.base',
+  updateUrl: 'invite.updateUrl',
+  browserUrl: 'landing.browserUrl',
+  maxLifted: 'liftOptions.max',
+  calibration: "openCamera({ calibration }) of '@displayxr/inline3d/camera' (pass the camera as `camera`)",
+  rectify: "openCamera({ rectify }) of '@displayxr/inline3d/camera'",
+  log: 'debug: true (and diagnostics())',
+  recoverSession: "nothing — a call always recovers the document's session (sharedInline3D())",
+  wallOptions: "sharedInline3D(opts) — the document's wall is configured by the page",
+  scrollIntoView: 'nothing — always on with ui: true',
+});
+const legacyWarned = new Set();
+function warnLegacy(key) {
+  if (legacyWarned.has(key)) return;
+  legacyWarned.add(key);
+  console.warn(`${TAG} option \`${key}\` is deprecated (removed in 1.31) — use ${LEGACY_OPTIONS[key]}`);
+}
+
+/**
+ * Apply defaults and validate. Pure (no DOM, no network) — see test/call.test.mjs. The result is
+ * the module's INTERNAL shape (flat), with the public groups (`theme`, `invite`, `landing`,
+ * `liftOptions`) folded in and the 1.29 spellings accepted with a warning (LEGACY_OPTIONS).
+ * @param {object} [opts]
+ */
+export function normalizeCallOptions(opts = {}) {
+  for (const k of Object.keys(LEGACY_OPTIONS)) if (opts[k] !== undefined) warnLegacy(k);
+  const theme = opts.theme && typeof opts.theme === 'object' ? opts.theme : {};
+  const invite = opts.invite && typeof opts.invite === 'object' ? opts.invite : {};
+  const landing = opts.landing && typeof opts.landing === 'object' ? opts.landing : {};
+  const ui = opts.ui === undefined ? true : opts.ui === 'tiles' ? 'tiles' : !!opts.ui;
+  const chrome = ui === true;
+  const tileAspect = theme.tileAspect !== undefined ? theme.tileAspect : opts.tileAspect;
+  const aspect = typeof tileAspect === 'number' && tileAspect > 0.3 && tileAspect < 4 ? tileAspect : 16 / 9;
+  let room = opts.room === undefined || opts.room === null ? 'auto' : opts.room;
+  if (room !== 'auto' && !isValidRoomId(room)) {
+    const fromLink = parseInviteLink(room);
+    if (!fromLink) throw new Error(`@displayxr/inline3d/call: room "${room}" is not a valid room id (16-64 base64url chars) or invite link`);
+    room = fromLink;
+  }
+  const liftOptions = opts.liftOptions && typeof opts.liftOptions === 'object' ? { ...opts.liftOptions } : null;
+  const maxLiftedRaw = liftOptions && liftOptions.max !== undefined ? liftOptions.max : opts.maxLifted;
+  if (liftOptions) delete liftOptions.max;
+  const accent = theme.accent !== undefined ? theme.accent : opts.accent;
+  const cssVars = {};
+  for (const [k, prop] of Object.entries(THEME_VARS)) {
+    const v = k === 'accent' ? accent : theme[k];
+    if (typeof v === 'string' && v) cssVars[prop] = k === 'accent' ? resolveCallAccent(v) : v;
+    else if (typeof v === 'number' && k === 'radius') cssVars[prop] = `${v}px`;
+  }
+  const inviteBase = invite.base !== undefined ? invite.base : opts.inviteBase;
+  const updateUrl = invite.updateUrl !== undefined ? invite.updateUrl : opts.updateUrl;
+  const browserUrl = landing.browserUrl !== undefined ? landing.browserUrl : opts.browserUrl;
+  return {
+    room,
+    // Default: the hosted DisplayXR signalling server (which also mints TURN credentials). A
+    // publishable key (RFC 0003 §5a) rides along on connect; the server may ignore it today.
+    signaling: opts.signaling || dxrSignaling(undefined, typeof opts.key === 'string' && opts.key ? { key: opts.key } : {}),
+    iceServers: Array.isArray(opts.iceServers) ? opts.iceServers : undefined,
+    // 'auto' | 'stereo' | 'mono' | deviceId | MediaStream | a StereoCamera from /camera.
+    camera: opts.camera === undefined ? 'auto' : opts.camera,
+    format: opts.format === 'sbs' ? 'sbs' : opts.format === 'mono' ? 'mono' : undefined,
+    // Camera-side knobs (moved to /camera in C2; still forwarded to openCamera() for one release).
+    calibration: opts.calibration && typeof opts.calibration === 'object' ? { ...opts.calibration } : {},
+    rectify: typeof opts.rectify === 'function' ? opts.rectify : null,
+    audio: opts.audio === undefined ? true : !!opts.audio,
+    // Auto-convergence (camera/disparity.js): measure the disparity of the point between each SBS
+    // peer's eyes and shift the eyes so it sits at the display plane. The depth slider stays an
+    // offset on top. Off = the pair as sent (plus any `hint`).
+    autoConverge: opts.autoConverge === undefined ? true : !!opts.autoConverge,
+    mono3D: normalizeMono3D(opts.mono3D),
+    maxPeers: clampMaxPeers(opts.maxPeers === undefined ? DEFAULT_MAX_PEERS : opts.maxPeers),
+    // Extra lift() options for lifted tiles (models, ort, quality, providers). The call's own
+    // keys (mode, wall, ui, convergence, priority) always win; `max` is the call's cap (below).
+    liftOptions: liftOptions && Object.keys(liftOptions).length ? liftOptions : null,
+    // Concurrent lifted tiles (`liftOptions.max`). Default = maxPeers (4): every mono peer can be lifted.
+    maxLifted: Number.isFinite(+maxLiftedRaw) && maxLiftedRaw !== null && maxLiftedRaw !== undefined ? Math.max(0, Math.min(DEFAULT_MAX_PEERS, Math.floor(+maxLiftedRaw))) : DEFAULT_MAX_PEERS,
+    // 'grid' | 'speaker' | 'none' (the page lays the tiles out; handle.tile(id) finds them).
+    layout: opts.layout === 'speaker' ? 'speaker' : opts.layout === 'none' ? 'none' : 'grid',
+    // true: full chrome | 'tiles': badges + plates only | false: nothing. `chrome` = the full set.
+    ui,
+    chrome,
+    autoJoin: opts.autoJoin === undefined ? !chrome : !!opts.autoJoin,
+    selfView: opts.selfView === undefined ? true : !!opts.selfView,
+    tileAspect: aspect,
+    // theme → the CSS custom properties written on the host, and the string table.
+    cssVars,
+    strings: theme.strings && typeof theme.strings === 'object' ? { ...theme.strings } : null,
+    invite: {
+      base: typeof inviteBase === 'string' ? inviteBase : null,
+      updateUrl: updateUrl === undefined ? chrome : !!updateUrl,
+    },
+    landing: {
+      browserUrl: typeof browserUrl === 'string' ? browserUrl : DEFAULT_BROWSER_URL,
+      allow2D: landing.allow2D === undefined ? true : !!landing.allow2D,
+    },
+    debug: !!opts.debug,
+    log: typeof opts.log === 'function' ? opts.log : opts.debug ? (tag, obj) => console.log(`${TAG} ${tag} ${JSON.stringify(obj)}`) : null,
+    // Internal (tests): replaces the lift module importer behind `mono3D: 'auto'`.
+    _liftImporter: typeof opts._liftImporter === 'function' ? opts._liftImporter : undefined,
+  };
+}
+
+/** The 1.29 `./call` exports kept as deprecated wrappers for one release (removed in 1.31). */
+export const DEPRECATED_CALL_EXPORTS = Object.freeze([
+  'normalizeCallOptions', 'newRoomId', 'isValidRoomId', 'buildInviteLink', 'normalizeHello', 'makeHello', 'routeFor', 'badgeFor', 'createLiveGate',
+  'convergenceShiftPx', 'lowPass', 'clampShift', 'eyeCropRect', 'mirrorSwapOps', 'mirrorSwapPixels', 'maxBitrateKbps', 'measureFocusDisparity',
+  'preferVideoCodecs', 'sortCodecCapabilities', 'VIDEO_CODEC_ORDER', 'MeshTransport', 'clampMaxPeers', 'qrEncode', 'roomKey', 'SIGNAL_PROTOCOL',
+  'WIRE_VERSION', 'CALL_SDK', 'PLATE_TEXT', 'CALL_ACCENTS', 'normalizeMono3D', 'resolveLift', 'createLiftPool', 'createFrameWatch',
+  'liftConvergenceFor', 'liftPriorityFor', 'setLiftPriority', 'defaultLiftSpecifier', 'LIFT_PRIORITY',
+]);