@displayxr/inline3d 1.28.0 → 1.30.0

package/js/call/capture.js

@@ -1,167 +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' });
-    }
-    return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '' };
-  };
-  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, ...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');
-  }
-
-  // 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;
-    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

@@ -0,0 +1,4 @@
+// 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

@@ -0,0 +1,221 @@
+// call/element.js — `<dxr-call>`: the one-line path as markup (RFC 0003 §1, C1).
+//
+//   <script type="module" src="https://cdn.jsdelivr.net/npm/@displayxr/inline3d@1/dist/call.js"></script>
+//   <dxr-call accent="violet"></dxr-call>
+//
+// REGISTRATION. Importing `@displayxr/inline3d/call` (or `/call/full`, or the CDN bundle) defines
+// the element — the entry calls `defineCallElement()` at the bottom of inline3d-call.js, which is
+// why that file is listed in package.json `sideEffects`. This file itself defines nothing on
+// import; it is the class, importable by path for tests.
+//
+// The element is SUGAR over `mountCall(this, attrsToOpts(this))`: it mounts on connect, `leave()`s
+// on disconnect, re-dispatches every call event as a DOM `CustomEvent` (`dxr-call:peer`,
+// `dxr-call:joined`, …, `detail` = the call's payload, bubbling and composed) and exposes the handle
+// as `el.call`. It is the element's LIGHT DOM that hosts the tiles — no shadow root: woven canvases
+// live in the document's own tree, and the SDK's chrome stylesheet is document-level.
+//
+// Attributes are the string-typed subset of `CallOptions` (attrsToOpts below). Anything else — a
+// `MediaStream` camera, a custom `SignalingAdapter`, a `lift` function, a `wall` — is a JS
+// property set BEFORE the element connects: `el.options = { … }`. Options win over attributes.
+// Attributes are read once, at connect: this element is not reactive to later attribute changes
+// (change them, then re-append it — which is a new call; see below).
+//
+// DISCONNECT = LEAVE. Removing the element ends the call, deliberately: a woven canvas must never
+// be remounted mid-call (woven-canvas rule 2), so a DOM move IS a teardown. SPA routers: mount
+// `<dxr-call>` in a layout that survives navigation. Re-appending a disconnected element starts a
+// fresh call (a new mount; the old handle is gone).
+//
+// NO GLOBALS (Decision 11): nothing here touches `globalThis` beyond `customElements.define`,
+// which `defineCallElement()` does exactly once and only when a registry exists. The class is
+// usable — and unit-testable — without a DOM: the base class falls back to a plain class when
+// `HTMLElement` is absent, and the mount seam (`DxrCallElement.mount`) is overridable.
+//
+// The import below is CIRCULAR (inline3d-call.js imports this file to register the element), so
+// nothing from it may be read while this module evaluates: `mount` defaults lazily, at connect.
+
+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', '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". */
+const isOn = (v) => v !== null && v !== undefined && !/^(false|0|off|no)$/i.test(String(v).trim());
+const num = (v) => {
+  if (v === null || v === undefined || String(v).trim() === '') return undefined;
+  const m = /^\s*([0-9.]+)\s*\/\s*([0-9.]+)\s*$/.exec(String(v)); // "16/9"
+  const n = m ? +m[1] / +m[2] : +v;
+  return Number.isFinite(n) ? n : undefined;
+};
+const str = (v) => (v === null || v === undefined || String(v).trim() === '' ? undefined : String(v).trim());
+
+/**
+ * Attribute → option mapping, pure. `source` is an element (or anything with `getAttribute`) or a
+ * `(name) => value | null` function. Unset attributes contribute nothing (the call's own defaults
+ * apply), so the result can be spread under `el.options`.
+ *
+ * | attribute            | option                                   |
+ * |----------------------|------------------------------------------|
+ * | `room`               | `room` (an id or an invite link)         |
+ * | `signaling`          | `signaling: dxrSignaling(url)`           |
+ * | `key`                | `key`                                    |
+ * | `camera`             | `camera` (`auto`/`stereo`/`mono`/deviceId)|
+ * | `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`        | `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
+ * @returns {object} a partial `CallOptions`
+ */
+export function attrsToOpts(source) {
+  const get = typeof source === 'function' ? source : (n) => (source && typeof source.getAttribute === 'function' ? source.getAttribute(n) : null);
+  const o = {};
+  const put = (k, v) => {
+    if (v !== undefined) o[k] = v;
+  };
+  put('room', str(get('room')));
+  const signaling = str(get('signaling'));
+  if (signaling) o.signaling = dxrSignaling(signaling, str(get('key')) ? { key: str(get('key')) } : {});
+  put('key', str(get('key')));
+  put('camera', str(get('camera')));
+  put('layout', str(get('layout')));
+  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;
+  // 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;
+}
+
+// Usable without a DOM (unit tests, SSR imports): a plain base class where HTMLElement is absent.
+const Base = typeof HTMLElement === 'function' ? HTMLElement : class {};
+
+export class DxrCallElement extends Base {
+  /**
+   * The mount seam: null = `mountCall` of `./call`. `./call/full` points it at its lift-wired
+   * `mountCall`, so importing that entry makes every `<dxr-call>` lift 2D participants; tests
+   * inject a fake. Resolved at connect, never at import (the circular import above).
+   */
+  static mount = null;
+
+  constructor() {
+    super();
+    /** Options that are not strings — set BEFORE connect; win over attributes. */
+    this.options = null;
+    /** The `CallHandle` once mounted; null before, and again after disconnect. */
+    this.call = null;
+    /** Resolves with the handle when the mount lands (null if the element left first); rejects if it failed. */
+    this.ready = null;
+    this._gen = 0;
+    this._off = [];
+    this._pending = null;
+  }
+
+  connectedCallback() {
+    if (this.call || this._pending) return; // already mounted, or mounting
+    const gen = ++this._gen;
+    const opts = { ...attrsToOpts(this), ...(this.options && typeof this.options === 'object' ? this.options : {}) };
+    const mount = this.constructor.mount || DxrCallElement.mount || mountCall;
+    // Synchronous call (a throw becomes a rejection): the container's chrome exists on return.
+    this._pending = new Promise((res) => res(mount(this, opts)))
+      .then(
+        (handle) => {
+          this._pending = null;
+          if (gen !== this._gen) {
+            // Disconnected while the camera/lobby was coming up: the mount landed on a dead element.
+            handle.leave();
+            return null;
+          }
+          this.call = handle;
+          this._off = CALL_EVENTS.map((t) => handle.on(t, (detail) => this._dispatch(t, detail)));
+          // The call module only console.warns an error when NOBODY listens; the element always
+          // does, so it says it here — a drop-in widget's page usually has no JS listening at all.
+          this._off.push(handle.on('error', (e) => console.warn(`${TAG} ${e.code}: ${e.message}`)));
+          this._dispatch('ready', { call: handle });
+          // `auto-join` (and `no-ui`) join DURING the mount, before anything could subscribe —
+          // and a room that already had people reports them during the join too. Replay what a
+          // listener would have seen, from the handle's state: 'joined', then one 'peer' per
+          // participant already there. (Errors raised while mounting — 'camera-busy' — were
+          // console.warned by the call itself, since nothing was listening yet.)
+          if (handle.state === 'in-call') {
+            this._dispatch('joined', { room: handle.room, id: handle.id });
+            for (const p of handle.peers) this._dispatch('peer', { id: p.id });
+          }
+          return handle;
+        },
+        (err) => {
+          this._pending = null;
+          this._dispatch('error', { code: 'mount-failed', message: String((err && err.message) || err), error: err || null });
+          console.warn(`${TAG} mount failed: ${String((err && err.message) || err)}`);
+          throw err;
+        }
+      );
+    this.ready = this._pending;
+    // A rejected `ready` nobody awaits must not be an unhandled rejection in a plain page.
+    this.ready.catch(() => {});
+  }
+
+  disconnectedCallback() {
+    this._gen++; // a mount still in flight lands on a dead element (see above)
+    const call = this.call;
+    this.call = null;
+    // leave() FIRST, so the call's 'left' still reaches listeners on the element as
+    // `dxr-call:left` (it no longer bubbles anywhere: the element is out of the tree); THEN unhook.
+    if (call) call.leave();
+    for (const off of this._off) {
+      try {
+        off();
+      } catch {
+        /* ignore */
+      }
+    }
+    this._off = [];
+  }
+
+  _dispatch(type, detail) {
+    if (typeof CustomEvent !== 'function' || typeof this.dispatchEvent !== 'function') return;
+    this.dispatchEvent(new CustomEvent(CALL_EVENT_PREFIX + type, { detail, bubbles: true, composed: true }));
+  }
+}
+
+/**
+ * Register `<dxr-call>` (or another tag name) once. Returns true when this call registered it,
+ * false when the name was already taken (by this class: fine; by another: a warning) or when there
+ * is no `customElements` registry (Node, a worker).
+ *
+ * @param {string} [name='dxr-call']
+ * @param {CustomElementRegistry} [registry=globalThis.customElements]
+ */
+export function defineCallElement(name = 'dxr-call', registry = globalThis.customElements) {
+  if (!registry || typeof registry.define !== 'function') return false;
+  const existing = registry.get(name);
+  if (existing) {
+    if (existing !== DxrCallElement) console.warn(`${TAG} <${name}> is already defined by another class; leaving it`);
+    return false;
+  }
+  registry.define(name, DxrCallElement);
+  return true;
+}

package/js/call/lift.js

@@ -43,9 +43,18 @@ export function normalizeMono3D(v) {
  * passes `mono3D: lift` (imported itself) instead.
  */
 export function defaultLiftSpecifier(base = import.meta.url) {
+  if (liftSpecifier) return typeof liftSpecifier === 'function' ? liftSpecifier() : liftSpecifier;
   return new URL('../lift/index.js', base).href;
 }
 
+// The pre-bundled CDN build (dist/call.js) has no js/call/ directory to resolve against: it points
+// this at its own sibling chunk (`dist/lift.js`) instead. A URL string, or a function returning
+// one (evaluated at import time, so `import.meta.url` of the caller can be used). Null = default.
+let liftSpecifier = null;
+export function setLiftSpecifier(spec) {
+  liftSpecifier = spec || null;
+}
+
 function defaultImporter() {
   return import(/* @vite-ignore */ /* webpackIgnore: true */ defaultLiftSpecifier());
 }

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',
+]);