@displayxr/inline3d 1.28.0 → 1.30.0

package/js/call/signaling.js

@@ -1,4 +1,4 @@
-// call/signaling.js — the SignalingAdapter seam, and the two adapters the SDK ships.
+// call/signaling.js — the SignalingAdapter seam, and the adapter the SDK ships.
 //
 // A SignalingAdapter is ANY object with `join(room, hooks) → Promise<SignalingSession>`:
 //
@@ -15,8 +15,8 @@
 //
 //   dxrSignaling(url)  the `dxr-signal/1` JSON-over-WebSocket protocol (signaling/README.md), served
 //                      by the reference Cloudflare Worker or `node signaling/dev-server.mjs`.
-//   peerjsCloud()      DEMO ONLY: the free public PeerJS broker. No uptime guarantee, not ours, and
-//                      every peer id it sees is derived from a hash of the room.
+//   (peerjsCloud, the demo adapter over the public PeerJS broker, left the package in 1.29 —
+//    RFC 0003 Decision 12 — and lives in samples/call/peerjs-cloud.js as a worked example.)
 
 import { backoffMs } from './wire.js';
 
@@ -42,7 +42,9 @@ export async function roomKey(room) {
  * peer-to-peer is not torn down by a signalling blip.
  *
  * @param {string} url
- * @param {{ WebSocket?: any, pingMs?: number }} [opts]
+ * @param {{ WebSocket?: any, pingMs?: number, key?: string }} [opts]  `key`: a publishable key for
+ *        the hosted service (RFC 0003 §5a), sent as a query parameter on connect. Public by design
+ *        (it sits in page source); a server that does not know keys ignores it.
  */
 /**
  * The hosted DisplayXR `dxr-signal/1` server (a Cloudflare Worker running `signaling/worker.mjs`,
@@ -67,7 +69,7 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
     url: base,
     async join(room, hooks) {
       const key = await roomKey(room);
-      const endpoint = `${base}/v1/connect?k=${key}`;
+      const endpoint = `${base}/v1/connect?k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
       let ws = null;
       let left = false;
       let attempt = 0;
@@ -199,200 +201,3 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
     },
   };
 }
-
-/**
- * DEMO ONLY — zero-setup signalling over the free public PeerJS broker (0.peerjs.com). It has no
- * uptime guarantee and is not operated by DisplayXR; use `dxrSignaling(url)` for anything real.
- *
- * PeerJS has no rooms, so this adapter makes one out of SLOTS: each peer registers the broker id
- * `dxrcall-<hash(room)>-<k>` for the first free k (a taken id is how "slot in use" is discovered),
- * opens a PeerJS data connection to every other slot, and relays our signalling over those.
- *
- * A taken slot is NOT the same as a live participant, and that is what the rest of this adapter
- * deals with:
- *  - A page that went away without its broker socket closing leaves a ZOMBIE slot. So there are
- *    twice as many slots as participants (a zombie never blocks a join), a slot counts as a
- *    participant only once it has said `hi`, and the room size is enforced on those. The page's own
- *    Peer is destroyed on `pagehide` / `beforeunload`, so a reload frees its slot at once.
- *  - A slot that exists but never says `hi` within `unreachableMs` is reported through
- *    `onPeerUnreachable('slot-<k>')`: the usual cause is a network where even the data
- *    connection's ICE never completes (it needs a relay). Silent slots are re-dialled every
- *    `retryMs` in the background; a `hi` (or the broker saying the slot is free) clears it again
- *    via `onPeerReachable`.
- *
- * @param {{ Peer?: any, peerOptions?: object, url?: string, helloMs?: number, unreachableMs?: number,
- *           retryMs?: number, heartbeatMs?: number, settleMs?: number }} [opts]
- *        `Peer`: the PeerJS constructor (default: `globalThis.Peer`, else the ESM build from jsDelivr).
- */
-export function peerjsCloud(opts = {}) {
-  const T = {
-    hello: opts.helloMs || 5000,
-    unreachable: opts.unreachableMs || 10000,
-    retry: opts.retryMs || 10000,
-    heartbeat: opts.heartbeatMs || 3000,
-    settle: opts.settleMs || 1500,
-  };
-  const loadPeer = async () => {
-    if (opts.Peer) return opts.Peer;
-    if (globalThis.Peer) return globalThis.Peer;
-    const mod = await import(/* @vite-ignore */ opts.url || 'https://cdn.jsdelivr.net/npm/peerjs@1.5.4/+esm');
-    return mod.Peer || mod.default;
-  };
-  return {
-    name: 'peerjs',
-    async join(room, hooks) {
-      const Peer = await loadPeer();
-      const tag = (await roomKey(room)).slice(0, 24);
-      const max = hooks.maxPeers || 4;
-      const nSlots = max * 2; // zombies must never make a room look full
-      const slotId = (k) => `dxrcall-${tag}-${k}`;
-
-      let peer = null;
-      let mySlot = -1;
-      for (let k = 0; k < nSlots && !peer; k++) {
-        peer = await new Promise((resolve) => {
-          const p = new Peer(slotId(k), opts.peerOptions || {});
-          const onErr = (e) => {
-            if (e && e.type === 'unavailable-id') {
-              p.destroy();
-              resolve(null);
-            }
-          };
-          p.on('error', onErr);
-          p.on('open', () => {
-            p.off?.('error', onErr);
-            mySlot = k;
-            resolve(p);
-          });
-        });
-      }
-      if (!peer) throw codedError('room-full', `every slot of this call is taken (${nSlots})`);
-
-      const byId = new Map(); // logical peer id -> { conn, seen }
-      const bySlot = new Map(); // broker id -> logical peer id
-      const silent = new Map(); // broker id -> { since, reported, conn }
-      let left = false;
-
-      const markReachable = (brokerId) => {
-        const s = silent.get(brokerId);
-        if (!s) return;
-        silent.delete(brokerId);
-        if (s.reported) hooks.onPeerReachable?.(`slot-${brokerId.split('-').pop()}`);
-      };
-      const wire = (conn) => {
-        conn.on('open', () => conn.send({ t: 'hi', id: hooks.id }));
-        conn.on('data', (msg) => {
-          if (!msg || typeof msg !== 'object') return;
-          const known = bySlot.get(conn.peer);
-          if (msg.t === 'hi' && typeof msg.id === 'string') {
-            markReachable(conn.peer);
-            if (!known) {
-              bySlot.set(conn.peer, msg.id);
-              const prev = byId.get(msg.id);
-              byId.set(msg.id, { conn, seen: Date.now() });
-              if (!prev) hooks.onPeerJoined?.(msg.id);
-              if (conn.open) conn.send({ t: 'hi', id: hooks.id });
-            }
-            return;
-          }
-          if (!known) return;
-          const rec = byId.get(known);
-          if (rec) rec.seen = Date.now();
-          if (msg.t === 'signal') hooks.onSignal?.(known, msg.data);
-          else if (msg.t === 'bye') drop(conn.peer);
-        });
-        conn.on('close', () => drop(conn.peer));
-        conn.on('error', () => {});
-      };
-      const drop = (brokerId) => {
-        const id = bySlot.get(brokerId);
-        if (!id) return;
-        bySlot.delete(brokerId);
-        byId.delete(id);
-        hooks.onPeerLeft?.(id);
-      };
-      const dial = (k) => {
-        const b = slotId(k);
-        if (!silent.has(b)) silent.set(b, { since: Date.now(), reported: false, conn: null });
-        const c = peer.connect(b, { reliable: true });
-        silent.get(b).conn = c;
-        wire(c);
-      };
-
-      peer.on('connection', wire);
-      peer.on('error', (e) => {
-        // 'peer-unavailable' names the broker id: that slot is FREE, so it is not a participant.
-        const m = e && e.type === 'peer-unavailable' && String(e.message || '').match(/(dxrcall-[0-9a-f]+-\d+)/);
-        if (m) markReachable(m[1]);
-      });
-      for (let k = 0; k < nSlots; k++) if (k !== mySlot) dial(k);
-
-      const hb = setInterval(() => {
-        const now = Date.now();
-        for (const [id, rec] of byId) {
-          if (now - rec.seen > 4 * T.heartbeat) {
-            for (const [b, pid] of bySlot) if (pid === id) drop(b);
-          } else if (rec.conn.open) rec.conn.send({ t: 'hb' });
-        }
-        for (const [b, st] of silent) {
-          // Silent past the hello window → not counted; past the unreachable window → reported.
-          if (!st.reported && now - st.since > T.unreachable) {
-            st.reported = true;
-            hooks.onPeerUnreachable?.(`slot-${b.split('-').pop()}`);
-          }
-          if (now - (st.lastDial || st.since) > T.retry) {
-            st.lastDial = now;
-            try {
-              if (st.conn && !st.conn.open) st.conn.close(); // one pending attempt per slot
-            } catch {
-              /* ignore */
-            }
-            st.conn = peer.connect(b, { reliable: true }); // background retry of a silent slot
-            wire(st.conn);
-          }
-        }
-      }, Math.min(T.heartbeat, 1000));
-
-      // Free this page's slot the moment it goes away — otherwise a reload leaves a zombie.
-      const unload = () => {
-        try {
-          for (const rec of byId.values()) if (rec.conn.open) rec.conn.send({ t: 'bye' });
-          peer.destroy();
-        } catch {
-          /* ignore */
-        }
-      };
-      globalThis.addEventListener?.('pagehide', unload);
-      globalThis.addEventListener?.('beforeunload', unload);
-
-      // Give the slot mesh a moment to say hello, so `peers` is useful. Only slots that said `hi`
-      // count (the transport enforces the room size on this list); late ones arrive through
-      // onPeerJoined like any other join.
-      await new Promise((r) => setTimeout(r, Math.min(T.settle, T.hello)));
-      // Hand the media connections the same relays PeerJS itself uses (its public TURN, or a
-      // page's `peerOptions.config`), so a demo call crosses the NATs a bare-PeerJS app crosses.
-      // Demo-grade: shared, no uptime guarantee — production TURN comes from dxrSignaling().
-      const relays = (peer.options?.config?.iceServers || []).filter((s) =>
-        [].concat(s.urls || s.url || []).some((u) => /^turns?:/.test(u)));
-      return {
-        id: hooks.id,
-        peers: [...byId.keys()],
-        iceServers: relays.length ? relays : undefined,
-        slot: mySlot,
-        send: (to, data) => {
-          const rec = byId.get(to);
-          if (rec && rec.conn.open) rec.conn.send({ t: 'signal', data });
-        },
-        leave: () => {
-          if (left) return;
-          left = true;
-          clearInterval(hb);
-          globalThis.removeEventListener?.('pagehide', unload);
-          globalThis.removeEventListener?.('beforeunload', unload);
-          for (const rec of byId.values()) if (rec.conn.open) rec.conn.send({ t: 'bye' });
-          setTimeout(() => peer.destroy(), 200);
-        },
-      };
-    },
-  };
-}

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,137 +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,
-    depth: 0, // setDepth(), [-1, 1]
-    current: 0,
-    target(eyeWidthPx) {
-      const auto =
-        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) ─────────────────────────────────────────────
 
@@ -421,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;
-}