@displayxr/inline3d 1.29.0 → 1.31.0

package/js/call/signaling.js

@@ -53,6 +53,18 @@ export async function roomKey(room) {
  */
 export const DXR_SIGNAL_DEFAULT = 'wss://dxr-signal.displayxr.workers.dev';
 
+/**
+ * Every host the hosted server answers on. The SAME Worker serves all of them (rooms are shared),
+ * so the adapter fails over between them when one cannot be reached: the first entry is tried
+ * first. `signal.displayxr.org` is the target of the domain move (RFC 0003 §5g); the workers.dev
+ * host stays an alias through the transition. Only applies to the hosted default — a self-hosted
+ * URL is tried as given (pass `aliases` to add your own fallbacks).
+ */
+export const DXR_SIGNAL_ALIASES = Object.freeze([DXR_SIGNAL_DEFAULT, 'wss://signal.displayxr.org']);
+
+/** Join-time error codes from the server that mean "do not retry with the same inputs". */
+const FATAL_JOIN_CODES = ['bad-room', 'bad-id', 'bad-version', 'bad-key', 'origin-not-allowed', 'blocked'];
+
 export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
   if (!url || typeof url !== 'string') {
     throw codedError(
@@ -60,16 +72,21 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
       'dxrSignaling(url): url must be a ws:// or wss:// string (omit it for the hosted DisplayXR server)'
     );
   }
-  const base = url.replace(/\/+$/, '');
+  const strip = (u) => String(u).replace(/\/+$/, '');
+  const base = strip(url);
   const WS = opts.WebSocket || globalThis.WebSocket;
   const pingMs = opts.pingMs || 20000;
+  const extra = Array.isArray(opts.aliases) ? opts.aliases.filter((a) => typeof a === 'string' && a).map(strip) : DXR_SIGNAL_ALIASES.includes(base) ? [...DXR_SIGNAL_ALIASES] : [];
+  const bases = [base, ...extra.filter((b) => b !== base)];
+  let baseIdx = 0;
 
   return {
     name: 'dxr',
     url: base,
     async join(room, hooks) {
       const key = await roomKey(room);
-      const endpoint = `${base}/v1/connect?k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
+      const query = `k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
+      const endpointAt = (i) => `${bases[i]}/v1/connect?${query}`;
       let ws = null;
       let left = false;
       let attempt = 0;
@@ -77,11 +94,15 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
       let known = new Set();
       let queue = [];
 
-      const open = (isReconnect) =>
+      // One open() tries every alias once (in order from the last one that worked) before it
+      // reports `signaling-unreachable`; a host that cannot be reached is skipped, not waited on.
+      const open = (isReconnect) => openAt(isReconnect, bases.length);
+      const openAt = (isReconnect, triesLeft) =>
         new Promise((resolve, reject) => {
           let settled = false;
           let joined = false;
-          const sock = new WS(endpoint);
+          let opened = false;
+          const sock = new WS(endpointAt(baseIdx));
           ws = sock;
           const fail = (err) => {
             if (!settled) {
@@ -95,6 +116,7 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
             }
           };
           sock.onopen = () => {
+            opened = true;
             sock.send(JSON.stringify({ t: 'join', v: 1, room, id: hooks.id, max: hooks.maxPeers }));
           };
           sock.onmessage = (ev) => {
@@ -121,17 +143,42 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
                 } else known = new Set(peers);
                 settled = true;
                 joined = true;
-                resolve({ id: msg.id, peers, iceServers: Array.isArray(msg.iceServers) ? msg.iceServers : undefined, max: msg.max });
+                resolve({
+                  id: msg.id,
+                  peers,
+                  iceServers: Array.isArray(msg.iceServers) ? msg.iceServers : undefined,
+                  max: msg.max,
+                  // Hosted-service fields (RFC 0003 §5): the tier this session was admitted as,
+                  // its key id, and the TURN decision — `turn.reason === 'cap'` is the SDK's
+                  // `turn-cap`. A server that predates them sends none; nothing here is required.
+                  tier: msg.tier === 'key' ? 'key' : 'anon',
+                  key: typeof msg.key === 'string' ? msg.key : undefined,
+                  turn: msg.turn && typeof msg.turn === 'object' ? msg.turn : undefined,
+                });
                 break;
               }
               case 'full':
                 left = true;
                 fail(codedError('room-full', `this call is full (${msg.max} participants)`));
                 break;
+              case 'expired': {
+                // The room's lifetime is up (hosted limits): no reconnect — the call reports it.
+                left = true;
+                clearInterval(pingTimer);
+                const e = codedError('expired', 'this room has reached its lifetime on the signalling server');
+                if (!settled) fail(e);
+                else hooks.onDisconnect?.(e);
+                break;
+              }
               case 'error':
-                if (!settled && ['bad-room', 'bad-id', 'bad-version'].includes(msg.code)) {
+                if (!settled && FATAL_JOIN_CODES.includes(msg.code)) {
                   left = true;
                   fail(codedError(msg.code, msg.message || msg.code));
+                } else if (!settled && (msg.code === 'rate-limited' || msg.code === 'quota')) {
+                  // Refused by a limit, not by the inputs: a reconnect may retry after `retryMs`.
+                  const e = codedError(msg.code, msg.message || msg.code);
+                  /** @type {any} */ (e).retryMs = msg.retryMs > 0 ? msg.retryMs : 0;
+                  fail(e);
                 } else if (!settled && msg.code === 'id-taken') {
                   // A reconnect raced the server noticing the old socket close: retry shortly.
                   fail(codedError('id-taken', 'peer id still held; retrying'));
@@ -154,7 +201,16 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
                 break;
             }
           };
-          sock.onerror = () => fail(codedError('signaling-unreachable', `cannot reach ${base}`));
+          sock.onerror = () => {
+            if (!opened && !settled && triesLeft > 1) {
+              // This host is unreachable: fail over to the next alias right away.
+              settled = true;
+              baseIdx = (baseIdx + 1) % bases.length;
+              openAt(isReconnect, triesLeft - 1).then(resolve, reject);
+              return;
+            }
+            fail(codedError('signaling-unreachable', `cannot reach ${bases[baseIdx]}`));
+          };
           sock.onclose = () => {
             clearInterval(pingTimer);
             fail(codedError('signaling-closed', 'signalling closed before joining'));
@@ -172,11 +228,12 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
         const tryAgain = () => {
           if (left) return;
           open(true).catch((err) => {
-            if (left || (err && err.code === 'room-full')) {
+            if (left || (err && (err.code === 'room-full' || FATAL_JOIN_CODES.includes(err.code)))) {
               hooks.onDisconnect?.(err);
               return;
             }
-            setTimeout(tryAgain, backoffMs(attempt++, { baseMs: 500, maxMs: 15000 }));
+            // A `rate-limited` / `quota` refusal says when to come back; never sooner.
+            setTimeout(tryAgain, Math.max(backoffMs(attempt++, { baseMs: 500, maxMs: 15000 }), (err && err.retryMs) || 0));
           });
         };
         setTimeout(tryAgain, backoffMs(attempt++, { baseMs: 300, maxMs: 15000 }));

package/js/call/ui.js

@@ -15,6 +15,16 @@
 //  4. Hidden chrome is `display: none`, never `opacity: 0`.
 //  5. The one full-tile element is the opaque COVER held until `handle.firstWoven` (rule 5 of the
 //     woven-canvas rules), cut — never faded — when it resolves.
+//
+// THE THEMING API (RFC 0003 §2, C2) is three things, and the class names are none of them:
+//  - CSS custom properties on the host: --dxr-accent, --dxr-ink, --dxr-shell, --dxr-danger,
+//    --dxr-radius (chrome only, never a tile), --dxr-font. `theme` in JS sets the same ones.
+//  - `part` names on the chrome: bar, invite, badge, plate, lobby, banner, self, tile, grid.
+//    The chrome is LIGHT DOM (a woven canvas must live in the document's own tree), so they are
+//    reached as `dxr-call [part="bar"]` rather than `::part(bar)`; the names are the contract.
+//  - `theme.strings`: every string the chrome shows, by key (CALL_STRINGS) — also localisation.
+//  The woven-canvas constraints are enforced here, not documented: every variable styles chrome
+//  only, so no theme can reach a tile.
 
 /** Named accents, shared with ./player (same names, same colours). */
 export const CALL_ACCENTS = Object.freeze({
@@ -29,14 +39,97 @@ export const CALL_ACCENTS = Object.freeze({
 });
 export const resolveCallAccent = (a) => (typeof a === 'string' && CALL_ACCENTS[a.toLowerCase()]) || a;
 
+/** The CSS custom properties `theme` writes (key → property). `tileAspect` / `strings` are not CSS. */
+export const THEME_VARS = Object.freeze({ accent: '--dxr-accent', ink: '--dxr-ink', shell: '--dxr-shell', danger: '--dxr-danger', radius: '--dxr-radius', font: '--dxr-font' });
+
+/**
+ * Every string the chrome shows, by key. `theme.strings` overrides any subset (a flat map), which
+ * is also how the chrome is localised. `{n}`-style placeholders are filled by the module.
+ */
+export const CALL_STRINGS = Object.freeze({
+  // lobby
+  lobbyStartTitle: 'Start a 3D call',
+  lobbyJoinTitle: 'Join the 3D call',
+  lobbyFullTitle: 'This call is full',
+  lobbyLeftTitle: 'You left the call',
+  lobbyFullText: 'It already has {maxPeers} participants.',
+  lobbyText: 'Check your framing below. Camera: {camera} — {kind}.',
+  cameraDefault: 'default',
+  kindBusy: 'busy (joining audio-only)',
+  kindNone: 'none (joining audio-only)',
+  kindSbs: 'sending 3D (side-by-side, {width}×{height})',
+  kindMono: 'sending 2D ({width}×{height})',
+  liftOff: 'Mono cameras: 2D (2D→3D is off).',
+  liftChecking: 'Mono cameras: checking 2D→3D…',
+  liftMissing: 'Mono cameras: 2D→3D unavailable in this build.',
+  liftNoProvider: 'Mono cameras: 2D (no 2D→3D provider here).',
+  liftNative: 'Mono cameras: 2D→3D (native{provider}).',
+  liftWeb: 'Mono cameras: 2D→3D (in this page, WebGPU).',
+  liftProven: 'Mono cameras: 2D→3D.',
+  liftUnproven: 'Mono cameras: 2D→3D (confirmed on the first mono participant).',
+  start: 'Start 3D call',
+  join: 'Join call',
+  rejoin: 'Rejoin',
+  retryCamera: 'Retry camera',
+  cameraSelect: 'Camera',
+  joining: 'Joining…',
+  // invite
+  waitingTitle: 'Waiting for others',
+  waitingText: 'Share this link (or scan the code). Anyone who opens it joins — keep it private.',
+  inviteTitle: 'Invite',
+  inviteText: 'Anyone with this link can join.',
+  inviteLink: 'Invite link',
+  copyLink: 'Copy link',
+  copied: 'Copied',
+  pressCopy: 'Press Ctrl/Cmd+C',
+  qrLabel: 'QR code of the invite link',
+  // banner
+  banner2D: 'You are seeing this call in 2D.',
+  bannerLink: 'View in 3D with DisplayXR Browser',
+  // bar
+  mute: 'Mute microphone',
+  unmute: 'Unmute microphone',
+  cameraOn: 'Turn camera on',
+  cameraOff: 'Turn camera off',
+  cameraRetry: 'No camera — click to retry',
+  cameraBusyRetry: '{cameraBusy} — click to retry',
+  depth: 'Depth',
+  invite: 'Invite',
+  leave: 'Leave call',
+  // plates and badges
+  connecting: 'Connecting…',
+  reconnecting: 'Reconnecting…',
+  leftCall: 'Left the call',
+  cameraOffPlate: 'Camera off',
+  noCamera: 'No camera',
+  unreachable: "Can't reach this participant — the network needs a relay (TURN)",
+  cameraBusy: 'Camera busy — in use by another app (e.g. eye tracking)',
+  you: 'You',
+  badge3D: '3D',
+  badge2D3D: '2D→3D',
+  badge2D: '2D',
+  badgePending: '…',
+});
+
+/** A string table over CALL_STRINGS with `overrides`: `t(key, vars)` fills `{var}` placeholders. */
+export function createStrings(overrides) {
+  const table = { ...CALL_STRINGS, ...(overrides && typeof overrides === 'object' ? overrides : {}) };
+  return (key, vars) => {
+    let s = typeof table[key] === 'string' ? table[key] : CALL_STRINGS[key] || key;
+    if (vars) for (const [k, v] of Object.entries(vars)) s = s.split(`{${k}}`).join(String(v));
+    return s;
+  };
+}
+
 const STYLE_ID = 'dxr-call-style';
 const CSS = `
-.dxr-call-host{--dxr-accent:#4da3ff;--dxr-ink:#fff;--dxr-shell:rgba(16,17,22,.92);--dxr-danger:#ff5a5f;
+.dxr-call-host{--dxr-accent:#4da3ff;--dxr-ink:#fff;--dxr-shell:rgba(16,17,22,.92);--dxr-danger:#ff5a5f;--dxr-radius:12px;
+  --dxr-font:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
   display:flex;flex-direction:column;gap:12px;color:var(--dxr-ink);
-  font:14px/1.4 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;}
+  font:14px/1.4 var(--dxr-font);}
 .dxr-call-host *{box-sizing:border-box;}
 .dxr-call-hidden{display:none !important;}
-.dxr-call-banner{display:flex;align-items:center;gap:10px;flex-wrap:wrap;padding:9px 14px;border-radius:10px;
+.dxr-call-banner{display:flex;align-items:center;gap:10px;flex-wrap:wrap;padding:9px 14px;border-radius:var(--dxr-radius);
   background:var(--dxr-shell);border:1px solid rgba(255,255,255,.12);font-size:13px;}
 .dxr-call-banner a{color:var(--dxr-accent);font-weight:600;}
 /* ── grid: bare boxes, nothing that makes a render surface ── */
@@ -50,6 +143,10 @@ const CSS = `
 .dxr-call-grid[data-layout="speaker"]{grid-template-columns:repeat(3,1fr);}
 .dxr-call-grid[data-layout="speaker"] .dxr-call-tile--main{grid-column:1/-1;}
 .dxr-call-grid[data-layout="speaker"][data-n="1"]{grid-template-columns:1fr;}
+/* layout:'none' — the module creates the tiles but does not position them: the grid box steps
+   aside (display:contents) so each [data-dxr-peer] tile is laid out by the PAGE's own CSS on the
+   host. A tile is never moved; it is styled in place (woven-canvas rule 2). */
+.dxr-call-grid[data-layout="none"]{display:contents;}
 .dxr-call-tile{position:relative;min-width:0;}
 .dxr-call-stage{position:relative;background:#000;}
 .dxr-call-stage>canvas{display:block;width:100%;height:100%;}
@@ -70,29 +167,29 @@ const CSS = `
   will-change:transform;pointer-events:none;}
 .dxr-call-cover{position:absolute;inset:0;z-index:1;background:#000;}
 /* ── empty room / lobby ── */
-.dxr-call-panel{padding:18px;border-radius:12px;background:var(--dxr-shell);border:1px solid rgba(255,255,255,.1);}
+.dxr-call-panel{padding:18px;border-radius:var(--dxr-radius);background:var(--dxr-shell);border:1px solid rgba(255,255,255,.1);}
 .dxr-call-panel h3{margin:0 0 6px;font-size:17px;}
 .dxr-call-panel p{margin:0 0 12px;opacity:.75;}
 .dxr-call-row{display:flex;flex-wrap:wrap;align-items:center;gap:8px;}
 .dxr-call-btn{appearance:none;border:1px solid rgba(255,255,255,.18);background:rgba(255,255,255,.08);color:inherit;
-  font:600 13px/1 system-ui,-apple-system,"Segoe UI",sans-serif;padding:9px 14px;border-radius:9px;cursor:pointer;}
+  font:600 13px/1 var(--dxr-font);padding:9px 14px;border-radius:calc(var(--dxr-radius) * .75);cursor:pointer;}
 .dxr-call-btn:hover{background:rgba(255,255,255,.16);}
 .dxr-call-btn:focus-visible{outline:2px solid var(--dxr-accent);outline-offset:2px;}
 .dxr-call-btn--primary{background:var(--dxr-accent);border-color:var(--dxr-accent);color:#07111d;}
 .dxr-call-btn--primary:hover{background:var(--dxr-accent);}
 .dxr-call-btn--danger{background:var(--dxr-danger);border-color:var(--dxr-danger);color:#fff;}
 .dxr-call-select{font:inherit;color:inherit;background:rgba(255,255,255,.08);border:1px solid rgba(255,255,255,.18);
-  border-radius:8px;padding:7px 9px;max-width:260px;}
+  border-radius:calc(var(--dxr-radius) * .66);padding:7px 9px;max-width:260px;}
 .dxr-call-invite{display:flex;gap:14px;align-items:flex-start;flex-wrap:wrap;}
 .dxr-call-invite input{flex:1 1 240px;min-width:0;font:12px ui-monospace,Menlo,monospace;color:inherit;
-  background:rgba(0,0,0,.35);border:1px solid rgba(255,255,255,.14);border-radius:8px;padding:8px;}
+  background:rgba(0,0,0,.35);border:1px solid rgba(255,255,255,.14);border-radius:calc(var(--dxr-radius) * .66);padding:8px;}
 .dxr-call-invite canvas{width:132px;height:132px;image-rendering:pixelated;background:#fff;}
 /* ── footer: self view + bar, BELOW the grid (over no tile) ── */
 .dxr-call-foot{display:flex;align-items:flex-end;gap:12px;flex-wrap:wrap;}
 .dxr-call-self{width:200px;flex:none;}
 .dxr-call-host--lobby .dxr-call-self{width:min(560px,100%);}
 .dxr-call-self .dxr-call-badge b{color:var(--dxr-ink);}
-.dxr-call-bar{display:flex;align-items:center;gap:6px;flex-wrap:wrap;padding:8px 10px;border-radius:14px;
+.dxr-call-bar{display:flex;align-items:center;gap:6px;flex-wrap:wrap;padding:8px 10px;border-radius:calc(var(--dxr-radius) + 2px);
   background:var(--dxr-shell);border:1px solid rgba(255,255,255,.1);will-change:transform;}
 .dxr-call-host--lobby .dxr-call-bar{display:none;}
 .dxr-call-ib{appearance:none;border:0;width:40px;height:40px;border-radius:50%;padding:9px;cursor:pointer;
@@ -127,7 +224,7 @@ export const ICONS = {
   mutedSmall: P('M19 11h-2a5 5 0 0 1-.4 1.97l1.47 1.47A6.96 6.96 0 0 0 19 11zM15 11V5a3 3 0 0 0-5.94-.6L15 10.34zM4.27 3 3 4.27l6 6V11a3 3 0 0 0 4.52 2.59l1.46 1.46A5 5 0 0 1 7 11H5a7 7 0 0 0 6 6.92V21h2v-3.08a6.9 6.9 0 0 0 3.02-1.14L19.73 21 21 19.73z'),
 };
 
-/** `el('div', {class: 'x'}, [children])` — a tiny builder, attributes as properties or attrs. */
+/** `el('div', {class: 'x', part: 'bar'}, [children])` — a tiny builder, attributes as properties or attrs. */
 export function el(tag, props = {}, children = []) {
   const n = document.createElement(tag);
   for (const [k, v] of Object.entries(props)) {

package/js/call/wire.js

@@ -13,8 +13,11 @@ export const CALL_SDK = 'inline3d-call/1';
 /** Formats a sender may declare. Anything else — or no hello at all — is read as `'mono'`. */
 export const CALL_FORMATS = Object.freeze(['sbs', 'mono']);
 
-/** A delivered frame wider than this (w / h) is a side-by-side pair (e.g. 1280x480, 2560x720). */
-export const SBS_ASPECT_MIN = 2.5;
+// The side-by-side geometry (what counts as a pair, eye crops, the mirror-and-swap self view)
+// moved to js/camera/geometry.js in C2 — `/camera` owns it, `/call` consumes it. Re-exported here
+// so every in-tree import and test path keeps resolving.
+export { SBS_ASPECT_MIN, looksSbs, eyeCropRect, eyeOutputSize, mirrorSwapOps, mirrorSwapPixels } from '../camera/geometry.js';
+export { CONVERGENCE_ALPHA, CONVERGENCE_MAX_FRACTION, DEPTH_RANGE_FRACTION } from '../camera/converge.js';
 
 /** Default and hard cap of participants in a full-mesh call (including yourself). */
 export const DEFAULT_MAX_PEERS = 4;
@@ -23,15 +26,6 @@ export const MESH_HARD_CAP = 4;
 /** `hint` messages are rate-limited to this many per second, on the sender AND the receiver. */
 export const HINT_MAX_HZ = 5;
 
-/** Low-pass factor for the convergence shift (RFC §3): next = prev + α·(target − prev). */
-export const CONVERGENCE_ALPHA = 0.2;
-
-/** The convergence shift never exceeds this fraction of the per-eye width, either way. */
-export const CONVERGENCE_MAX_FRACTION = 0.12;
-
-/** `setDepth(v)`: v in [-1, 1] adds v times this fraction of the per-eye width to the shift. */
-export const DEPTH_RANGE_FRACTION = 0.05;
-
 /** Plausible subject distances, mm. A hint outside this is ignored as noise. */
 export const SUBJECT_Z_MIN_MM = 150;
 export const SUBJECT_Z_MAX_MM = 5000;
@@ -231,143 +225,9 @@ export function badgeFor(route) {
   return route === 'woven-sbs' ? '3D' : route === 'lifted' ? '2D→3D' : '2D';
 }
 
-// ── convergence (RFC §3) ───────────────────────────────────────────────────────────────────
-
-/** Focal length in px of an eye image `eyeWidthPx` wide with horizontal FOV `hfovDeg`. */
-export function focalPx(eyeWidthPx, hfovDeg) {
-  if (!(eyeWidthPx > 0) || !(hfovDeg > 0) || hfovDeg >= 180) return null;
-  return eyeWidthPx / 2 / Math.tan(((hfovDeg / 2) * Math.PI) / 180);
-}
-
-/**
- * Per-eye horizontal shift, in SOURCE eye pixels, that puts a subject at `subjectZmm` on the
- * display plane: `f_px · baseline / (2 · subjectZ)`. A parallel stereo camera gives everything a
- * crossed disparity of `f·B/Z` (full, between the eyes); half of it comes off each eye.
- *
- * Positive = the left eye's crop moves RIGHT and the right eye's LEFT (content pushed back).
- * Returns 0 when anything it needs is unknown — the receiver then shows the pair as sent.
- */
-export function convergenceShiftPx({ eyeWidthPx, hfovDeg, baselineMm, subjectZmm }) {
-  const f = focalPx(eyeWidthPx, hfovDeg);
-  if (f === null || !(baselineMm > 0) || !(subjectZmm > 0)) return 0;
-  return (f * baselineMm) / (2 * subjectZmm);
-}
-
-/** Clamp a shift to ±CONVERGENCE_MAX_FRACTION of the per-eye width. */
-export function clampShift(px, eyeWidthPx, maxFraction = CONVERGENCE_MAX_FRACTION) {
-  const lim = Math.max(0, eyeWidthPx * maxFraction);
-  return Math.max(-lim, Math.min(lim, px || 0));
-}
-
-/** One low-pass step: `prev + α(target − prev)`. Snaps when within 0.05 px so it can settle. */
-export function lowPass(prev, target, alpha = CONVERGENCE_ALPHA) {
-  const next = prev + alpha * (target - prev);
-  return Math.abs(target - next) < 0.05 ? target : next;
-}
-
-/**
- * A tile's convergence state: the target from hello+hint, the page's depth offset, and the
- * smoothed value actually painted. `step()` once per painted frame.
- */
-export function createConvergence() {
-  const s = {
-    hello: null,
-    subjectZmm: null,
-    // Auto-convergence (call/disparity.js): the MEASURED disparity of the point between the remote
-    // person's eyes, in source eye pixels (left x − right x). When set it wins over the hint: it is
-    // read off the frames, so it needs no calibration and cannot disagree with them.
-    measuredPx: null,
-    depth: 0, // setDepth(), [-1, 1]
-    current: 0,
-    target(eyeWidthPx) {
-      const auto =
-        s.measuredPx !== null
-          ? s.measuredPx / 2 // half the disparity comes off each eye: the eyes land at zero parallax
-          : s.hello && s.subjectZmm
-            ? convergenceShiftPx({
-                eyeWidthPx,
-                hfovDeg: s.hello.hfovDeg,
-                baselineMm: s.hello.baselineMm,
-                subjectZmm: s.subjectZmm,
-              })
-            : 0;
-      return clampShift(auto + s.depth * DEPTH_RANGE_FRACTION * eyeWidthPx, eyeWidthPx);
-    },
-    step(eyeWidthPx) {
-      s.current = lowPass(s.current, s.target(eyeWidthPx));
-      return s.current;
-    },
-  };
-  return s;
-}
-
-/**
- * The source rectangle of ONE eye, cropped to the tile's aspect and shifted by the convergence
- * offset. Never upscales past the source: a 640-wide eye (a real raw stereo camera) stays 640.
- *
- * @param {number} eyeW  source per-eye width (px)
- * @param {number} eyeH  source height
- * @param {number} aspect  the tile's (= the woven buffer's per-eye) aspect, w/h
- * @param {number} shift  per-eye shift in source px (see convergenceShiftPx); + = push back
- * @param {0|1} eye  0 = left, 1 = right
- * @returns {{sx:number, sy:number, sw:number, sh:number}} relative to that eye's half
- */
-export function eyeCropRect(eyeW, eyeH, aspect, shift, eye) {
-  const s = Math.abs(shift || 0);
-  let sw = Math.min(eyeW - 2 * s, eyeH * aspect);
-  sw = Math.max(1, sw);
-  const sh = Math.min(eyeH, sw / aspect);
-  sw = sh * aspect;
-  const cx = (eyeW - sw) / 2 + (eye === 0 ? shift : -shift);
-  return { sx: Math.max(0, Math.min(eyeW - sw, cx)), sy: (eyeH - sh) / 2, sw, sh };
-}
-
-/** The output per-eye size for a source eye and a tile aspect: no upscaling, even numbers. */
-export function eyeOutputSize(eyeW, eyeH, aspect) {
-  const w = Math.min(eyeW, eyeH * aspect);
-  const h = w / aspect;
-  return { w: Math.max(2, Math.round(w / 2) * 2), h: Math.max(2, Math.round(h / 2) * 2) };
-}
-
-// ── self view: the mirroring trap (RFC §3) ─────────────────────────────────────────────────
-
-/**
- * The draw operations for a MIRRORED stereo self-view: each half mirrored AND the halves swapped.
- *
- * Why both: mirroring a scene horizontally means the reflected left eye sees what the original
- * right eye saw (mirrored), and vice versa. Mirroring each half IN PLACE keeps the eyes where they
- * were and inverts every disparity — the face goes pseudoscopic (inside-out). Mirror + swap keeps
- * crossed disparity crossed. (It is the same pixels as flipping the whole SBS frame; spelled out
- * per half so the intent survives refactoring.) The WIRE is never mirrored — only this preview.
- *
- * @param {number} W  full SBS frame width
- * @param {number} H  height
- * @returns {Array<{src:'L'|'R', sx:number, sw:number, dx:number, dw:number, mirror:true}>}
- */
-export function mirrorSwapOps(W, H) {
-  const half = W / 2;
-  return [
-    { src: 'R', sx: half, sw: half, sy: 0, sh: H, dx: 0, dw: half, mirror: true },
-    { src: 'L', sx: 0, sw: half, sy: 0, sh: H, dx: half, dw: half, mirror: true },
-  ];
-}
-
-/**
- * Apply mirrorSwapOps to a row-major single-channel frame (tests, and a reference for the canvas
- * path). Returns a new array.
- */
-export function mirrorSwapPixels(px, W, H) {
-  const out = new px.constructor(px.length);
-  for (const op of mirrorSwapOps(W, H)) {
-    for (let y = 0; y < H; y++) {
-      for (let x = 0; x < op.dw; x++) {
-        const srcX = op.sx + (op.sw - 1 - x); // mirrored within the half
-        out[y * W + op.dx + x] = px[y * W + srcX];
-      }
-    }
-  }
-  return out;
-}
+// ── convergence (RFC 0002 §3) — moved to js/camera/converge.js in C2 (the self view and the remote
+// tiles share one convergence state); re-exported so in-tree imports and test paths keep resolving.
+export { focalPx, convergenceShiftPx, clampShift, lowPass, createConvergence } from '../camera/converge.js';
 
 // ── weave liveness (displayxr-browser-pvt#172) ─────────────────────────────────────────────
 
@@ -427,8 +287,3 @@ export function backoffMs(attempt, { baseMs = 1000, maxMs = 30000, rand = Math.r
   const raw = Math.min(maxMs, baseMs * Math.pow(2, Math.max(0, attempt)));
   return Math.round(raw * (0.8 + 0.4 * rand()));
 }
-
-/** Does a delivered frame look like a side-by-side pair? (capture 'auto' only) */
-export function looksSbs(width, height) {
-  return width > 0 && height > 0 && width / height > SBS_ASPECT_MIN;
-}