@displayxr/inline3d 1.27.0 → 1.28.0

package/js/call/ui.js

@@ -0,0 +1,146 @@
+// call/ui.js — the SDK-drawn call chrome: lobby, tiles' badges and state plates, the bottom bar,
+// the invite panel, the "View in 3D" banner. DOM + CSS only; the call module drives it.
+//
+// The overlay contract (docs/authoring-inline-3d.md, docs/woven-canvas-rules.md) is the same one
+// the player obeys, and it shapes every rule below:
+//
+//  1. Chrome ON a tile (the 3D/2D badge, the "Reconnecting…" plate) is a PARTIAL region — a small
+//     pill, never a plate congruent with the tile (it would match the canvas's own quad on a
+//     legacy browser and take the tile out of the weave). The bottom bar and self view live in a
+//     footer BELOW the grid, over no tile at all.
+//  2. NO `backdrop-filter`. The near-solid `--dxr-shell` (rgba(16,17,22,.92)) is the substitute.
+//  3. Promotion is `will-change: transform`. No CSS filter / opacity / border-radius / shadow on a
+//     woven canvas OR ANY ANCESTOR of one — the tile, the grid and the host stay visually bare.
+//     A speaking highlight is a separate bar UNDER the stage, not an outline around it.
+//  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.
+
+/** Named accents, shared with ./player (same names, same colours). */
+export const CALL_ACCENTS = Object.freeze({
+  azure: '#4da3ff',
+  violet: '#9b7bff',
+  magenta: '#ff4fa3',
+  sunset: '#ff7a45',
+  amber: '#ffc23d',
+  lime: '#9be15d',
+  mint: '#35e0b0',
+  ice: '#8fe3ff',
+});
+export const resolveCallAccent = (a) => (typeof a === 'string' && CALL_ACCENTS[a.toLowerCase()]) || a;
+
+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;
+  display:flex;flex-direction:column;gap:12px;color:var(--dxr-ink);
+  font:14px/1.4 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;}
+.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;
+  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 ── */
+.dxr-call-grid{display:grid;gap:10px;grid-template-columns:1fr;margin-inline:auto;width:100%;
+  /* Fit the tiles AND the footer (self view + bar) in one viewport: tiles are 16:9 per eye, so
+     the grid's width is capped by the height left after --dxr-call-reserve (the footer). */
+  --dxr-call-h:var(--dxr-call-fit,calc(100vh - var(--dxr-call-reserve,150px)));max-width:calc(var(--dxr-call-h)*16/9);}
+.dxr-call-grid[data-n="2"]{max-width:calc(var(--dxr-call-h)*32/9);}
+.dxr-call-grid[data-layout="speaker"]:not([data-n="1"]){max-width:calc(var(--dxr-call-h)*4/3);}
+.dxr-call-grid[data-n="2"],.dxr-call-grid[data-n="3"]{grid-template-columns:1fr 1fr;}
+.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;}
+.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%;}
+/* a LIFTED tile: its <video> is mounted in the stage for lift() (which floats its canvas over the
+   element's rect, z-index 1); the flat canvas sits above it until lift is live, then hides. */
+.dxr-call-stage>video.dxr-call-liftsrc{position:absolute;left:0;top:0;width:100%;height:100%;object-fit:cover;}
+.dxr-call-stage>canvas.dxr-call-liftflat{position:relative;z-index:1;}
+.dxr-call-talk{height:3px;margin-top:4px;background:transparent;}
+.dxr-call-tile--speaking .dxr-call-talk{background:var(--dxr-accent);}
+/* ── partial overlays on a tile ── */
+.dxr-call-badge{position:absolute;left:8px;top:8px;z-index:2;display:flex;align-items:center;gap:6px;
+  padding:3px 8px;border-radius:99px;background:var(--dxr-shell);font-size:11px;font-weight:600;
+  letter-spacing:.4px;will-change:transform;pointer-events:none;}
+.dxr-call-badge b{font-weight:800;color:var(--dxr-accent);}
+.dxr-call-badge svg{width:13px;height:13px;fill:var(--dxr-danger);}
+.dxr-call-state{position:absolute;left:50%;top:50%;z-index:2;transform:translate(-50%,-50%);max-width:70%;
+  padding:8px 14px;border-radius:99px;background:var(--dxr-shell);font-size:13px;text-align:center;
+  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 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;}
+.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;}
+.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;}
+.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;
+  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;
+  background:rgba(255,255,255,.1);color:var(--dxr-ink);}
+.dxr-call-ib:hover{background:rgba(255,255,255,.2);}
+.dxr-call-ib:focus-visible{outline:2px solid var(--dxr-accent);outline-offset:2px;}
+.dxr-call-ib svg{width:100%;height:100%;fill:currentColor;display:block;}
+.dxr-call-ib[aria-pressed="true"]{background:var(--dxr-ink);color:#111;}
+.dxr-call-ib--leave{background:var(--dxr-danger);width:52px;border-radius:20px;}
+.dxr-call-ib--leave:hover{background:var(--dxr-danger);}
+.dxr-call-depth{display:flex;align-items:center;gap:6px;padding:0 8px;font-size:12px;opacity:.9;}
+.dxr-call-depth input{width:110px;accent-color:var(--dxr-accent);}
+.dxr-call-note{font-size:12px;opacity:.65;}
+`;
+
+export function injectCallStyle(doc = document) {
+  if (doc.getElementById(STYLE_ID)) return;
+  const s = doc.createElement('style');
+  s.id = STYLE_ID;
+  s.textContent = CSS;
+  (doc.head || doc.documentElement).appendChild(s);
+}
+
+const P = (d) => `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="${d}"/></svg>`;
+export const ICONS = {
+  mic: P('M12 14a3 3 0 0 0 3-3V5a3 3 0 0 0-6 0v6a3 3 0 0 0 3 3zm5-3a5 5 0 0 1-10 0H5a7 7 0 0 0 6 6.92V21h2v-3.08A7 7 0 0 0 19 11z'),
+  micOff: 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'),
+  cam: P('M17 10.5V7a1 1 0 0 0-1-1H4a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-3.5l4 4v-11z'),
+  camOff: P('M21 6.5l-4 4V7a1 1 0 0 0-1-1H9.82L21 17.18zM3.27 2 2 3.27 4.73 6H4a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h12c.21 0 .39-.08.54-.18L19.73 21 21 19.73z'),
+  link: P('M3.9 12a3.1 3.1 0 0 1 3.1-3.1h4V7H7a5 5 0 0 0 0 10h4v-1.9H7A3.1 3.1 0 0 1 3.9 12zM8 13h8v-2H8zm9-6h-4v1.9h4a3.1 3.1 0 0 1 0 6.2h-4V17h4a5 5 0 0 0 0-10z'),
+  leave: P('M12 9c-1.6 0-3.15.25-4.6.72v3.1c0 .39-.23.74-.56.9-.98.49-1.87 1.12-2.66 1.85a1 1 0 0 1-1.41-.02L.29 13.08a1 1 0 0 1 0-1.41C3.34 8.78 7.46 7 12 7s8.66 1.78 11.71 4.67a1 1 0 0 1 0 1.41l-2.48 2.48a1 1 0 0 1-1.41.02 11.3 11.3 0 0 0-2.66-1.85 1 1 0 0 1-.56-.9v-3.1A15.3 15.3 0 0 0 12 9z'),
+  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. */
+export function el(tag, props = {}, children = []) {
+  const n = document.createElement(tag);
+  for (const [k, v] of Object.entries(props)) {
+    if (v === undefined || v === null) continue;
+    if (k === 'class') n.className = v;
+    else if (k === 'html') n.innerHTML = v;
+    else if (k === 'text') n.textContent = v;
+    else if (k.startsWith('on') && typeof v === 'function') n.addEventListener(k.slice(2), v);
+    else if (k in n && typeof v !== 'string') n[k] = v;
+    else n.setAttribute(k, v);
+  }
+  for (const c of [].concat(children)) if (c) n.appendChild(typeof c === 'string' ? document.createTextNode(c) : c);
+  return n;
+}
+
+export const show = (n, on) => n && n.classList.toggle('dxr-call-hidden', !on);

package/js/call/wire.js

@@ -0,0 +1,428 @@
+// call/wire.js — the pure half of @displayxr/inline3d/call: the wire format, the routing table,
+// the convergence math, room ids and invite links. No DOM, no WebRTC, so every rule the module
+// relies on is checkable under `node --test` (test/call.test.mjs).
+//
+// PREVIEW tier — see docs/sdk-stability.md and docs/rfcs/0002-video-call.md.
+
+/** Wire-format version carried in every `hello`. Bumped only for an incompatible change. */
+export const WIRE_VERSION = 1;
+
+/** The SDK version string a `hello` reports (informational; never used for routing). */
+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;
+
+/** Default and hard cap of participants in a full-mesh call (including yourself). */
+export const DEFAULT_MAX_PEERS = 4;
+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;
+
+// ── room ids and invite links ──────────────────────────────────────────────────────────────
+
+/** Room ids are base64url, at least 16 chars (96 bits). Generated ones are 22 chars (128 bits). */
+export const ROOM_ID_RE = /^[A-Za-z0-9_-]{16,64}$/;
+export const ROOM_ID_BYTES = 16;
+
+/**
+ * An unguessable, URL-safe room id: 128 random bits, base64url (22 chars). The id IS the only
+ * access control an anonymous call has, so it comes from `crypto.getRandomValues`, never
+ * `Math.random`.
+ * @param {(a: Uint8Array) => Uint8Array} [getRandomValues]  injectable for tests
+ */
+export function newRoomId(getRandomValues) {
+  const bytes = new Uint8Array(ROOM_ID_BYTES);
+  const fill = getRandomValues || ((a) => globalThis.crypto.getRandomValues(a));
+  fill(bytes);
+  return base64url(bytes);
+}
+
+/** A random peer id: 64 bits, base64url (11 chars). Unique within a room, not a secret. */
+export function newPeerId(getRandomValues) {
+  const bytes = new Uint8Array(8);
+  const fill = getRandomValues || ((a) => globalThis.crypto.getRandomValues(a));
+  fill(bytes);
+  return base64url(bytes);
+}
+
+export function base64url(bytes) {
+  const A = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+  let out = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+    out += A[(n >> 18) & 63] + A[(n >> 12) & 63] + A[(n >> 6) & 63] + A[n & 63];
+  }
+  const rest = bytes.length - i;
+  if (rest === 1) {
+    const n = bytes[i] << 16;
+    out += A[(n >> 18) & 63] + A[(n >> 12) & 63];
+  } else if (rest === 2) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+    out += A[(n >> 18) & 63] + A[(n >> 12) & 63] + A[(n >> 6) & 63];
+  }
+  return out;
+}
+
+export function isValidRoomId(room) {
+  return typeof room === 'string' && ROOM_ID_RE.test(room);
+}
+
+/**
+ * The room carried by an invite link, or null. Reads the URL FRAGMENT only (`#room=…`), which a
+ * browser never sends to a server, so the room never lands in an access log. Accepts a full URL,
+ * a bare fragment (`#room=…` / `room=…`), or a `Location`. Other fragment params are ignored.
+ * @param {string | {hash?: string, href?: string}} link
+ */
+export function parseInviteLink(link) {
+  if (!link) return null;
+  let hash = '';
+  if (typeof link === 'object') hash = link.hash || (link.href ? String(link.href).split('#')[1] || '' : '');
+  else {
+    const s = String(link);
+    const at = s.indexOf('#');
+    hash = at >= 0 ? s.slice(at + 1) : s.includes('=') && !s.includes('://') ? s : '';
+  }
+  hash = hash.replace(/^#/, '');
+  for (const part of hash.split('&')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    if (decodeURIComponent(part.slice(0, eq)) !== 'room') continue;
+    const room = decodeURIComponent(part.slice(eq + 1));
+    return isValidRoomId(room) ? room : null;
+  }
+  return null;
+}
+
+/**
+ * Build an invite link: `base` with its fragment replaced by `#room=<room>`. The query string is
+ * kept (a sample's `?signal=` must survive the hop); any existing fragment is dropped.
+ */
+export function buildInviteLink(base, room) {
+  if (!isValidRoomId(room)) throw new Error(`@displayxr/inline3d/call: invalid room id "${room}"`);
+  const b = String(base || '').split('#')[0];
+  return `${b}#room=${room}`;
+}
+
+// ── hello / hint / state ───────────────────────────────────────────────────────────────────
+
+/**
+ * Validate an incoming `hello`, filling the defaults a receiver may assume. Returns null for
+ * something that is not a hello at all. Never throws: this reads data from another browser.
+ *
+ * `rectified` defaults to FALSE — a raw stereo camera (unrectified, possibly grayscale) is the
+ * common case in the field, and a receiver must never assume more than it was told.
+ */
+export function normalizeHello(msg) {
+  if (!msg || typeof msg !== 'object' || msg.type !== 'hello') return null;
+  const num = (v, lo, hi) => (typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? v : null);
+  return {
+    type: 'hello',
+    v: typeof msg.v === 'number' ? msg.v : WIRE_VERSION,
+    format: CALL_FORMATS.includes(msg.format) ? msg.format : 'mono',
+    width: num(msg.width, 1, 16384),
+    height: num(msg.height, 1, 16384),
+    baselineMm: num(msg.baselineMm, 1, 1000),
+    hfovDeg: num(msg.hfovDeg, 5, 170),
+    rectified: msg.rectified === true,
+    sdk: typeof msg.sdk === 'string' ? msg.sdk.slice(0, 64) : null,
+  };
+}
+
+/** Build the `hello` this side sends. */
+export function makeHello({ format, width, height, baselineMm, hfovDeg, rectified } = {}) {
+  const h = {
+    type: 'hello',
+    v: WIRE_VERSION,
+    format: CALL_FORMATS.includes(format) ? format : 'mono',
+    width: width || 0,
+    height: height || 0,
+    rectified: !!rectified,
+    sdk: CALL_SDK,
+  };
+  if (Number.isFinite(baselineMm)) h.baselineMm = baselineMm;
+  if (Number.isFinite(hfovDeg)) h.hfovDeg = hfovDeg;
+  return h;
+}
+
+/** `hint {subjectZmm}`: a number in range, or null (ignored). */
+export function normalizeHint(msg) {
+  if (!msg || msg.type !== 'hint') return null;
+  const z = msg.subjectZmm;
+  return typeof z === 'number' && Number.isFinite(z) && z >= SUBJECT_Z_MIN_MM && z <= SUBJECT_Z_MAX_MM
+    ? { type: 'hint', subjectZmm: z }
+    : null;
+}
+
+/** `state {muted, cameraOff, speaking}` — booleans only. */
+export function normalizeState(msg) {
+  if (!msg || msg.type !== 'state') return null;
+  return { type: 'state', muted: msg.muted === true, cameraOff: msg.cameraOff === true, speaking: msg.speaking === true };
+}
+
+/**
+ * A minimum-interval gate: `gate(nowMs)` is true at most `hz` times a second. Used on both ends
+ * of `hint` so a chatty (or hostile) sender cannot drive the receiver's convergence at frame rate.
+ */
+export function rateGate(hz) {
+  const minMs = 1000 / hz;
+  let last = -Infinity;
+  return (now) => {
+    if (now - last < minMs) return false;
+    last = now;
+    return true;
+  };
+}
+
+// ── routing (RFC §3) ───────────────────────────────────────────────────────────────────────
+
+/**
+ * How a remote tile is drawn. The ONE table every tile goes through:
+ *
+ * | remote sends | local wall woven      | local wall 2D / absent |
+ * |--------------|-----------------------|------------------------|
+ * | `sbs`        | `woven-sbs`           | `flat-left`            |
+ * | `mono`       | `lifted` (or `flat`)  | `flat`                 |
+ * | no hello     | treated as `mono`     | `flat`                 |
+ *
+ * A mono peer on a woven wall is `lifted` — one lift() stream per peer (call/lift.js) — when the
+ * `mono3D` option is on, a lift function resolved (`lift: true`) and a lift slot is free. Otherwise
+ * it is `flat`, and `mono3d` says why: `'off'` (the page turned it off), `'unavailable'` (no lift
+ * module, no provider, or it is still loading), `'budget'` (every lift slot is taken), or
+ * `'failed'` (lift() failed for this tile).
+ *
+ * @param {{ format?: string|null, woven: boolean, mono3D?: 'auto'|'off'|Function, lift?: boolean, overBudget?: boolean, failed?: boolean }} p
+ * @returns {{ route: 'woven-sbs'|'flat-left'|'flat'|'lifted', mono3d?: 'unavailable'|'off'|'lifted'|'budget'|'failed' }}
+ */
+export function routeFor({ format, woven, mono3D = 'auto', lift = false, overBudget = false, failed = false }) {
+  const fmt = format === 'sbs' ? 'sbs' : 'mono';
+  if (fmt === 'sbs') return { route: woven ? 'woven-sbs' : 'flat-left' };
+  if (!woven) return { route: 'flat' };
+  if (mono3D === 'off' || mono3D === false) return { route: 'flat', mono3d: 'off' };
+  if (!lift) return { route: 'flat', mono3d: 'unavailable' };
+  if (failed) return { route: 'flat', mono3d: 'failed' };
+  if (overBudget) return { route: 'flat', mono3d: 'budget' };
+  return { route: 'lifted', mono3d: 'lifted' };
+}
+
+/**
+ * The badge a tile shows for a route, from THIS side's point of view: `3D` for a woven stereo
+ * pair, `2D→3D` for a mono peer this side lifts, `2D` for anything shown flat.
+ */
+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;
+}
+
+// ── weave liveness (displayxr-browser-pvt#172) ─────────────────────────────────────────────
+
+/**
+ * Is the inline-3D session actually LIVE — delivering stereo frames — yet?
+ *
+ * Browser bug displayxr-browser-pvt#172: a woven canvas registered BEFORE the browser's weave
+ * session is live gets the whole side-by-side frame in EACH eye (L|R|L|R, flat) until a reload.
+ * A call's self view is created at page load, exactly the case. The core exposes no "weave is
+ * live" signal, so the module watches the session's own frames (the frozen `wall.session` /
+ * `wall.refSpace` fields) and registers woven tiles only once `need` CONSECUTIVE frames have
+ * located two or more views — the runtime is up and locating eyes. A session with no reference
+ * space (views never readable) counts as live after `needNoPose` frames. Pure: feed it view counts.
+ *
+ * @param {{need?: number, needNoPose?: number}} [o]
+ */
+export function createLiveGate({ need = 10, needNoPose = 30 } = {}) {
+  let run = 0;
+  let frames = 0;
+  let live = false;
+  return {
+    /** @param {number|null} viewCount  views located this frame; null = no reference space */
+    feed(viewCount) {
+      if (live) return true;
+      frames++;
+      if (viewCount === null) live = frames >= needNoPose;
+      else {
+        // >= 1, not >= 2: the browser's inline session reports ONE view on the viewer pose
+        // (per-eye views live on each layer), verified on a real panel.
+        run = viewCount >= 1 ? run + 1 : 0;
+        live = run >= need;
+      }
+      return live;
+    },
+    get live() {
+      return live;
+    },
+  };
+}
+
+// ── sending ────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Video `maxBitrate` (kbps) for one outgoing stream in a mesh. Full mesh means one upload per
+ * remote peer, so the per-peer budget falls as the call grows. SBS carries two eyes, so it gets
+ * roughly twice mono's. Numbers from P0 (2560x720 VP9 30 fps at ~3-4 Mbps).
+ */
+export function maxBitrateKbps(format, remotePeers) {
+  const n = Math.max(1, remotePeers | 0);
+  const sbs = format === 'sbs';
+  const table = sbs ? [6000, 4000, 3000] : [2500, 1800, 1400];
+  return table[Math.min(n, table.length) - 1];
+}
+
+/** Exponential backoff with a cap, and ±20% jitter from `rand` (0..1). */
+export function backoffMs(attempt, { baseMs = 1000, maxMs = 30000, rand = Math.random } = {}) {
+  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;
+}