@displayxr/inline3d 1.47.6 → 1.48.0

package/docs/woven-canvas-rules.md

@@ -196,14 +196,23 @@ tile while its content keeps running (for a video: sound, no picture). To put bl
 tile, give it to an element **behind** the canvas. A cover you mean to hide the tile with (rule 5,
 rule 11) is the one deliberate exception, and it comes off on a signal.
 
-### 10. No `backdrop-filter` on anything drawn over the weave
-
-Rule 7 covers the canvas and its ancestors. This one covers the **siblings on top of it**: a
-control bar, a caption, a badge, a menu. `backdrop-filter` is defined as a function of what is
-behind the element, and behind it is the interlaced weave. A blur reads the interlaced pixels
-and smears them, and the 3D image is disturbed across the element's **whole box**, not only
-where the element is opaque (seen on the panel, 24 September). Use a plain translucent tint
-(`background: rgba(0, 0, 0, 0.55)`) instead. The SDK's own player chrome follows this rule.
+### 10. `backdrop-filter` over the weave: only on DisplayXR Browser 0.1.16+, never over a whole tile
+
+Rule 7 covers the canvas and its ancestors, and is unchanged. This one covers the **siblings on
+top of it**: a control bar, a caption, a badge, a menu. `backdrop-filter` is defined as a function
+of what is behind the element, and behind it is the interlaced weave. On browsers before
+DisplayXR Browser 0.1.16 the blur reads the interlaced pixels and smears them, and the 3D image is
+disturbed across the element's **whole box**, not only where it is opaque (seen on the panel, 24
+September). From 0.1.16 the compositor draws the tile **mono inside each frost rect**
+(displayxr-browser#120), so frosted chrome over a tile looks right: the frosted region is flat,
+the rest of the tile stays 3D. [`samples/composition`](../samples/composition/) (its sticky
+header) is the validated case.
+
+- Frost a **partial** region only (a bar, a pill). Never frost a whole tile while it is visible:
+  the whole tile goes mono under it.
+- If the page must also run on older browsers, use a plain translucent tint
+  (`background: rgba(0, 0, 0, 0.55)`) there. The SDK's own chrome (player, call) keeps its
+  near-solid tint so one build works on every generation.
 
 ### 11. Treat a resize as a fresh-canvas moment
 
@@ -331,11 +340,14 @@ for exactly that reason). It cannot check the join. On a DisplayXR display:
 Found on hardware in a production photo app after the rules above were written. Each one looked
 like a runtime or browser bug on the panel and turned out to be the page.
 
-- **No `backdrop-filter` on chrome that sits over the weave.** Rule 7 covers effects on the canvas
-  and its ancestors. A frosted bar or button placed *over* a woven tile is a different element, but
-  on a lenticular laptop panel it visibly disturbs the 3D image across that element's whole rect.
-  Use a plain translucent tint instead (a solid `rgba()` background). Keep an A/B switch for the
-  blurred variant if the design wants it back, and judge it on the panel, not on a 2D monitor.
+- **`backdrop-filter` on chrome that sits over the weave (superseded for 0.1.16+).** Rule 7 covers
+  effects on the canvas and its ancestors. A frosted bar or button placed *over* a woven tile is a
+  different element; on browsers before DisplayXR Browser 0.1.16 it visibly disturbed the 3D image
+  across that element's whole rect on a lenticular laptop panel, and the fix was a plain
+  translucent tint. Since 0.1.16 the compositor draws the tile mono inside each frost rect
+  (displayxr-browser#120), so partial frosted chrome is fine there (`samples/composition` is the
+  validated case); still never frost a whole visible tile ([rule 10](#10-backdrop-filter-over-the-weave-only-on-displayxr-browser-0116-never-over-a-whole-tile)).
+  Judge it on the panel, not on a 2D monitor.
 - **Nothing opaque above the woven canvas.** Stacking order still applies: an element with an
   opaque background painted *above* the canvas hides it, and on a draw-order browser that is
   exactly what you get. The classic case is a full-bleed video plane under a page `<main>` with

package/js/call/element.js

@@ -37,7 +37,7 @@ import { mountCall, dxrSignaling } from '../inline3d-call.js';
 
 /** Every call event is re-dispatched as `dxr-call:<type>`; `dxr-call:ready` carries the handle. */
 export const CALL_EVENT_PREFIX = 'dxr-call:';
-const CALL_EVENTS = ['joined', 'left', 'peer', 'peerleft', 'state', 'display', 'speaker', 'quality', 'error', 'warning'];
+const CALL_EVENTS = ['joined', 'left', 'peer', 'peerleft', 'state', 'display', 'speaker', 'quality', 'error', 'warning', 'name', 'message', 'signal', 'weave', 'speaking'];
 const TAG = '[inline3d/call] <dxr-call>';
 
 /** A boolean attribute: present is true, unless its value spells "false"/"0"/"off"/"no". */
@@ -71,8 +71,10 @@ const str = (v) => (v === null || v === undefined || String(v).trim() === '' ? u
  * | `no-audio`           | `audio: false`                           |
  * | `no-self-view`       | `selfView: false`                        |
  * | `no-auto-converge`   | `autoConverge: false`                    |
+ * | `no-send-convergence`| `sendConvergence: false`                 |
  * | `cursor="depth"`     | `cursor: 'depth'`                        |
- * | `tile-aspect`        | `theme.tileAspect` (a number, or `w/h`)  |
+ * | `tile-aspect`        | `theme.tileAspect` (a number, `w/h`, or `fill`) |
+ * | `name`               | `name` (your display name)               |
  * | `invite-base`        | `invite.base`                            |
  * | `browser-url`        | `landing.browserUrl`                     |
  * | `debug`              | `debug: true`                            |
@@ -102,9 +104,11 @@ export function attrsToOpts(source) {
   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;
+  if (isOn(get('no-send-convergence'))) o.sendConvergence = false;
   if (str(get('cursor')) === 'depth') o.cursor = 'depth';
   // 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')) };
+  put('name', str(get('name')));
+  const theme = { accent: str(get('accent')), tileAspect: str(get('tile-aspect')) === 'fill' ? 'fill' : 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')) };

package/js/call/options.js

@@ -3,7 +3,7 @@
 // 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 { isValidRoomId, parseInviteLink, DEFAULT_MAX_PEERS, sanitizeName } from './wire.js';
 import { clampMaxPeers } from './transport.js';
 import { normalizeMono3D } from './lift.js';
 import { dxrSignaling } from './signaling.js';
@@ -53,7 +53,10 @@ export function normalizeCallOptions(opts = {}) {
   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;
+  // 'fill': each tile's per-eye aspect is its own stage box (the page sizes the tiles).
+  const aspect = tileAspect === 'fill' ? 'fill' : typeof tileAspect === 'number' && tileAspect > 0.3 && tileAspect < 4 ? tileAspect : 16 / 9;
+  const layout = opts.layout === 'speaker' ? 'speaker' : opts.layout === 'none' ? 'none' : 'grid';
+  const tileCover = opts.tileCover === 'auto' || opts.tileCover === 'off' ? opts.tileCover : layout === 'none' ? 'auto' : 'off';
   let room = opts.room === undefined || opts.room === null ? 'auto' : opts.room;
   if (room !== 'auto' && !isValidRoomId(room)) {
     const fromLink = parseInviteLink(room);
@@ -90,6 +93,10 @@ export function normalizeCallOptions(opts = {}) {
     // 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,
+    // Sender side of auto-convergence (docs/call.md): with a stereo camera, measure that disparity
+    // on this side's own raw frames and send it to every peer (`conv` on the data channel), so
+    // receivers apply it instead of measuring the compressed frames. Off = receivers measure.
+    sendConvergence: opts.sendConvergence === undefined ? true : !!opts.sendConvergence,
     // `cursor: 'depth'` (runtime ADR-046 on a pair): the arrow comes in front of a person who pops
     // out of the screen under it, measured off each stereo tile's two halves; else the plain OS
     // arrow on the plane. Off by default (zero cost).
@@ -102,7 +109,15 @@ export function normalizeCallOptions(opts = {}) {
     // 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',
+    layout,
+    // The core's rect cover on every woven tile (and a stereo self view): 'auto' covers a tile
+    // across a resize or move until it is woven again. Default 'auto' with layout: 'none' (the
+    // page moves and resizes the tiles), 'off' otherwise (the module's own layout).
+    tileCover,
+    // This side's display name (hello.name), sanitised; null = none.
+    name: sanitizeName(opts.name),
+    // Devices no camera probe opens (openCamera's `exclude`); false = not even the built-in list.
+    cameraExclude: opts.cameraExclude === false ? false : Array.isArray(opts.cameraExclude) ? [...opts.cameraExclude] : undefined,
     // true: full chrome | 'tiles': badges + plates only | false: nothing. `chrome` = the full set.
     ui,
     chrome,
@@ -124,6 +139,8 @@ export function normalizeCallOptions(opts = {}) {
     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,
+    // Internal (tests): replaces the sender's frame grab (camera/conv-meter.js grabLumaFrame).
+    _convGrab: typeof opts._convGrab === 'function' ? opts._convGrab : undefined,
   };
 }
 

package/js/call/transport.js

@@ -6,7 +6,7 @@
 //
 //   transport.start({ room, localStream, onPeer, onPeerLeft, onStream, onMessage, onPeerState })
 //   transport.send(peerId, msg) / broadcast(msg)
-//   transport.replaceVideoTrack(track) / setSendFormat(format)
+//   transport.replaceTrack(kind, track, stream) / setSendFormat(format)
 //   transport.peerConnection(peerId)   // for getStats (null on an SFU)
 //   transport.stop()
 //
@@ -501,6 +501,16 @@ export class MeshTransport {
     for (const pid of this.peers.keys()) this.send(pid, msg);
   }
 
+  /** An already-serialised message (the app channel: sized before it is sent). */
+  sendRaw(pid, json) {
+    const rec = this.peers.get(pid);
+    if (rec && rec.dc && rec.dc.readyState === 'open') {
+      rec.dc.send(json);
+      return true;
+    }
+    return false;
+  }
+
   peerConnection(pid) {
     const rec = this.peers.get(pid);
     return rec ? rec.pc : null;

package/js/call/ui.js

@@ -8,7 +8,12 @@
 //     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.
+//  2. NO `backdrop-filter` in the SDK's own chrome. The near-solid `--dxr-shell`
+//     (rgba(16,17,22,.92)) is its choice, and it stays. A frosted element OVER a tile is no longer
+//     a defect on DisplayXR Browser 0.1.16+ (browser#120: the compositor draws the tile mono
+//     inside each frost rect; samples/composition is the validated case) — a page's own chrome may
+//     use it. Never frost a WHOLE visible tile, and rule 3 (effects on the canvas or an ancestor)
+//     is unchanged.
 //  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.
@@ -147,6 +152,8 @@ const CSS = `
    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;}
+/* …and so do the footer and the self slot, so the page places the self tile ([data-dxr-peer="self"]). */
+.dxr-call-host--none .dxr-call-foot,.dxr-call-host--none .dxr-call-self{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%;}

package/js/call/wire.js

@@ -26,6 +26,31 @@ 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;
 
+/**
+ * `conv` (sender-measured auto-convergence, docs/call.md): a sender broadcasts at most this many
+ * per second; a receiver accepts at most `CONV_RECV_MAX_HZ`. A sender whose value has not changed
+ * still sends one every `CONV_HEARTBEAT_MS`; a receiver that has heard nothing for `CONV_FRESH_MS`
+ * goes back to measuring the received frames itself.
+ */
+export const CONV_MAX_HZ = 5;
+export const CONV_RECV_MAX_HZ = 10;
+export const CONV_HEARTBEAT_MS = 400;
+export const CONV_FRESH_MS = 1200;
+/** `conv.d` is a fraction of the per-eye width; anything beyond ±this is not a face's disparity. */
+export const CONV_MAX_FRAC = 0.5;
+
+/**
+ * App messages (`handle.send` / `handle.broadcast`, docs/call.md § Headless): `{ type: 'app', d }`
+ * on the call's data channel. The serialised message is at most `APP_MAX_BYTES` (UTF-8), and a
+ * sender sends at most `APP_MAX_PER_SEC` to one peer in any second (a receiver drops anything
+ * beyond `APP_RECV_MAX_PER_SEC`: network jitter can bunch a legal burst).
+ */
+export const APP_MAX_BYTES = 16 * 1024;
+export const APP_MAX_PER_SEC = 20;
+export const APP_RECV_MAX_PER_SEC = 40;
+/** A display name (`hello.name`, the `name` option) is at most this many characters. */
+export const NAME_MAX_CHARS = 64;
+
 /** 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;
@@ -116,7 +141,7 @@ export function buildInviteLink(base, room) {
   return `${b}#room=${room}`;
 }
 
-// ── hello / hint / state ───────────────────────────────────────────────────────────────────
+// ── hello / hint / state / conv ────────────────────────────────────────────────────────────
 
 /**
  * Validate an incoming `hello`, filling the defaults a receiver may assume. Returns null for
@@ -138,11 +163,36 @@ export function normalizeHello(msg) {
     hfovDeg: num(msg.hfovDeg, 5, 170),
     rectified: msg.rectified === true,
     sdk: typeof msg.sdk === 'string' ? msg.sdk.slice(0, 64) : null,
+    // The sender measures its own convergence and sends `conv` messages. Absent (an older sender) =
+    // false: the receiver measures the decoded frames itself, as before.
+    conv: msg.conv === true,
+    // The sender's display name (`name` option, 1.48+), sanitised; null when absent or empty.
+    name: sanitizeName(msg.name),
   };
 }
 
-/** Build the `hello` this side sends. */
-export function makeHello({ format, width, height, baselineMm, hfovDeg, rectified } = {}) {
+/**
+ * A display name as it may travel and be shown: a string, control characters removed (C0, DEL,
+ * C1, and the bidi / zero-width format controls that can disguise a name), whitespace collapsed
+ * and trimmed, at most `NAME_MAX_CHARS` characters (code points). Null for anything else or an
+ * empty result. Never throws: this reads data from another browser. Pure.
+ * @param {unknown} v
+ * @returns {string|null}
+ */
+export function sanitizeName(v) {
+  if (typeof v !== 'string') return null;
+  // eslint-disable-next-line no-control-regex
+  const clean = v.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!clean) return null;
+  const cps = Array.from(clean);
+  return cps.length > NAME_MAX_CHARS ? cps.slice(0, NAME_MAX_CHARS).join('').trim() : clean;
+}
+
+/**
+ * Build the `hello` this side sends. `conv: true` (advertised for a side-by-side sender only)
+ * says this side sends `conv` messages.
+ */
+export function makeHello({ format, width, height, baselineMm, hfovDeg, rectified, conv, name } = {}) {
   const h = {
     type: 'hello',
     v: WIRE_VERSION,
@@ -154,9 +204,90 @@ export function makeHello({ format, width, height, baselineMm, hfovDeg, rectifie
   };
   if (Number.isFinite(baselineMm)) h.baselineMm = baselineMm;
   if (Number.isFinite(hfovDeg)) h.hfovDeg = hfovDeg;
+  if (h.format === 'sbs' && conv) h.conv = true;
+  const n = sanitizeName(name);
+  if (n) h.name = n;
   return h;
 }
 
+/**
+ * Wrap a page's app payload: `{ type: 'app', d: data }` serialised, or null when `data` cannot be
+ * serialised (undefined, a function, a cycle, a BigInt) or the message is over `APP_MAX_BYTES`
+ * (UTF-8). Returns the JSON string the data channel carries. Pure.
+ * @param {unknown} data
+ * @returns {{ json: string, bytes: number } | null}
+ */
+export function makeAppMessage(data) {
+  if (data === undefined || typeof data === 'function') return null;
+  let json;
+  try {
+    json = JSON.stringify({ type: 'app', d: data });
+  } catch {
+    return null;
+  }
+  if (typeof json !== 'string') return null;
+  const bytes = utf8Length(json);
+  return bytes > APP_MAX_BYTES ? null : { json, bytes };
+}
+
+/** An incoming `app` message: `{ data }`, or null when it is not one. Only this type reaches a page. */
+export function normalizeApp(msg) {
+  if (!msg || typeof msg !== 'object' || msg.type !== 'app' || !('d' in msg)) return null;
+  return { data: msg.d };
+}
+
+function utf8Length(s) {
+  if (typeof TextEncoder === 'function') return new TextEncoder().encode(s).length;
+  let n = 0;
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    n += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
+  }
+  return n;
+}
+
+/**
+ * A sliding-window counter: `gate(nowMs)` is true at most `max` times in any `windowMs`. The app
+ * channel's per-peer cap (a burst of `max` is fine; the next one waits for the window). Pure.
+ */
+export function windowGate(max, windowMs = 1000) {
+  const at = [];
+  return (now) => {
+    while (at.length && now - at[0] >= windowMs) at.shift();
+    if (at.length >= max) return false;
+    at.push(now);
+    return true;
+  };
+}
+
+/**
+ * `conv {d, c?}`: the sender's measured disparity of the point between its subject's eyes, as a
+ * FRACTION of its per-eye width (resolution-free: a receiver multiplies by the width of the frame it
+ * decodes), `null` = nothing measured yet (the receiver holds what it had). `c` = the match
+ * confidence (NCC, 0..1), informational.
+ * @param {number|null} frac
+ * @param {number|null} [ncc]
+ */
+export function makeConv(frac, ncc) {
+  const m = { type: 'conv', d: typeof frac === 'number' && Number.isFinite(frac) ? Math.max(-CONV_MAX_FRAC, Math.min(CONV_MAX_FRAC, frac)) : null };
+  if (typeof ncc === 'number' && Number.isFinite(ncc)) m.c = Math.max(0, Math.min(1, ncc));
+  return m;
+}
+
+/**
+ * Validate an incoming `conv`. Null for anything that is not one, or whose `d` is neither null nor
+ * a finite number within ±CONV_MAX_FRAC. `c` is clamped to 0..1, or dropped. Never throws: this
+ * reads data from another browser.
+ */
+export function normalizeConv(msg) {
+  if (!msg || typeof msg !== 'object' || msg.type !== 'conv') return null;
+  const d = msg.d;
+  if (d !== null && !(typeof d === 'number' && Number.isFinite(d) && Math.abs(d) <= CONV_MAX_FRAC)) return null;
+  const out = { type: 'conv', d };
+  if (typeof msg.c === 'number' && Number.isFinite(msg.c)) out.c = Math.max(0, Math.min(1, msg.c));
+  return out;
+}
+
 /** `hint {subjectZmm}`: a number in range, or null (ignored). */
 export function normalizeHint(msg) {
   if (!msg || msg.type !== 'hint') return null;
@@ -173,11 +304,14 @@ export function normalizeState(msg) {
 }
 
 /**
- * A minimum-interval gate: `gate(nowMs)` is true at most `hz` times a second. Used on both ends
+ * A minimum-interval gate: `gate(nowMs)` is true at most `hz` times a second (`slackMs` shortens
+ * the interval by that much). 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;
+export function rateGate(hz, slackMs = 0) {
+  // `slackMs`: a timer-paced caller at exactly `hz` (the sender's `conv` tick) lands a few ms early
+  // now and then; without slack every such tick is refused and the rate halves.
+  const minMs = 1000 / hz - Math.max(0, slackMs);
   let last = -Infinity;
   return (now) => {
     if (now - last < minMs) return false;
@@ -186,6 +320,29 @@ export function rateGate(hz) {
   };
 }
 
+// ── connection quality ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The selected ICE candidate pair of one getStats() report: `{ path, rttMs }`. `path` is
+ * `'relay'` when either end is relayed (TURN), else the local candidate's type (`'host'` /
+ * `'srflx'` / `'prflx'`); null when no pair is selected yet. Chrome names the pair on the
+ * `transport` stats; Firefox flags it `selected`. Pure: reads an RTCStatsReport (maplike).
+ */
+export function selectedPath(report) {
+  const all = [];
+  report.forEach((s) => all.push(s));
+  const byId = (id) => (id && typeof report.get === 'function' ? report.get(id) : all.find((s) => s.id === id)) || null;
+  const tr = all.find((s) => s.type === 'transport' && s.selectedCandidatePairId);
+  const pair = (tr && byId(tr.selectedCandidatePairId)) || all.find((s) => s.type === 'candidate-pair' && s.selected) || all.find((s) => s.type === 'candidate-pair' && s.nominated && s.state === 'succeeded');
+  if (!pair) return { path: null, rttMs: null };
+  const lc = byId(pair.localCandidateId);
+  const rc = byId(pair.remoteCandidateId);
+  const lt = lc ? lc.candidateType : null;
+  const path = lt === 'relay' || (rc && rc.candidateType === 'relay') ? 'relay' : ['host', 'srflx', 'prflx'].includes(lt) ? lt : null;
+  const rtt = typeof pair.currentRoundTripTime === 'number' ? Math.round(pair.currentRoundTripTime * 1000) : null;
+  return { path, rttMs: rtt };
+}
+
 // ── routing (RFC §3) ───────────────────────────────────────────────────────────────────────
 
 /**

package/js/camera/capture.js

@@ -5,16 +5,25 @@
 // 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:
+// Three 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.
+//  - Not every `videoinput` is a camera a person should be seen through. A hand-tracking camera
+//    (and an eye tracker's or a depth sensor's IR stream) enumerates as an ordinary video input
+//    and can even look like a pair by shape; on a Windows box with no stereo camera open, the
+//    last-resort "try every device" loop opened one and sent it as the call's 3D picture. Labels
+//    matching CAMERA_EXCLUDE_BUILTIN, plus the page's `exclude` list, are never opened by any probe
+//    path (an excluded default is closed again), and are reported in `skipped` as `excluded`.
 //  - Labels are empty until one getUserMedia has succeeded. Without them, permission is primed on
-//    the DEFAULT camera with no constraints: in the DisplayXR Browser the runtime's 3D camera is
-//    listed first, so the prime opens the pair itself and no phone lens is opened at all (a plain
-//    open of one lens of the pair, or its teardown, crashes some phones' camera HAL; any facing or
-//    size constraint lets the engine pick a lens instead). Then the list is read again and a
-//    stereo device is opened by id BEFORE falling back. The primed default is the fallback.
+//    the DEFAULT camera with no constraints (a plain open of one lens of a phone's pair, or its
+//    teardown, crashes some phones' camera HAL; any facing or size constraint lets the engine pick
+//    a lens instead). Where the runtime's 3D camera is the default, the prime opens the pair
+//    itself. NOTHING here assumes a list position: on Windows the DisplayXR Browser lists its
+//    "3D Camera (DisplayXR)" LAST. A pair is recognised by the track's own `displayxrStereo`
+//    description or by its label (stereoLabelHint), and after the prime the list is read again and
+//    a named pair is opened by id BEFORE a default that is a pair only by its shape is kept. The
+//    primed default is the fallback.
 //
 // 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
@@ -48,11 +57,44 @@ export function isDeniedError(err) {
  * @param {Array<{error: string, busy?: boolean, denied?: boolean}>} skipped
  */
 export function noCameraCode(skipped) {
-  if (skipped.length && skipped.every((s) => s.busy)) return 'camera-busy';
-  if (skipped.some((s) => s.denied)) return 'permission-denied';
+  // A device left out on purpose (`excluded`) says nothing about why the others failed.
+  const tried = skipped.filter((s) => !s.excluded);
+  if (tried.length && tried.every((s) => s.busy)) return 'camera-busy';
+  if (tried.some((s) => s.denied)) return 'permission-denied';
   return 'no-camera';
 }
 
+/**
+ * Labels of video inputs that are sensors, not cameras to be seen through: hand tracking, an eye
+ * tracker's or a "tracking camera"'s IR stream, a depth camera. Generic words only. Applied on
+ * every probe path unless `exclude: false`.
+ */
+export const CAMERA_EXCLUDE_BUILTIN = /\b(hand[- ]?track|tracking camera|eye[- ]?track|depth camera)/i;
+
+/**
+ * The exclusion list in force: the built-in pattern plus `exclude` (strings match a label
+ * case-insensitively as a substring, or a deviceId exactly; RegExps test the label), or nothing at
+ * all for `exclude: false`. Returns a predicate `(label, deviceId) => boolean`. Pure.
+ * @param {false|null|undefined|ReadonlyArray<string|RegExp>|string|RegExp} exclude
+ */
+export function cameraExcluder(exclude) {
+  if (exclude === false) return () => false;
+  const list = [CAMERA_EXCLUDE_BUILTIN];
+  for (const x of exclude == null ? [] : Array.isArray(exclude) ? exclude : [exclude]) {
+    if (x instanceof RegExp || (typeof x === 'string' && x)) list.push(x);
+  }
+  return (label, deviceId) => {
+    const l = String(label || '');
+    for (const x of list) {
+      if (x instanceof RegExp) {
+        x.lastIndex = 0; // a /g or /y pattern is stateful
+        if (l && x.test(l)) return true;
+      } else if ((l && l.toLowerCase().includes(x.toLowerCase())) || (deviceId && deviceId === x)) return true;
+    }
+    return false;
+  };
+}
+
 /** 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 || '');
@@ -65,7 +107,9 @@ export function stereoLabelHint(label) {
  * @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]
+ *           mediaDevices?: MediaDevices, log?: Function, exclude?: false|Array<string|RegExp> }} [o]
+ *        `exclude`: devices no probe may open (see cameraExcluder); an explicit deviceId is the
+ *        page's own choice and is opened regardless.
  * @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 }>}
@@ -75,6 +119,7 @@ export async function openCamera(want = 'auto', o = {}) {
   const log = o.log || (() => {});
   const skipped = [];
   const cal = o.calibration || {};
+  const isExcluded = cameraExcluder(o.exclude);
 
   if (want && typeof want === 'object' && typeof want.getVideoTracks === 'function') {
     const t = want.getVideoTracks()[0];
@@ -105,6 +150,32 @@ export async function openCamera(want = 'auto', o = {}) {
     log('camera-skip', { label, error: err.name });
   };
   const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
+  // Excluded devices: never opened by id; a default that turns out to be one is closed again.
+  const excludedIds = new Set();
+  const exclude = (label, deviceId) => {
+    if (deviceId && excludedIds.has(deviceId)) return;
+    if (deviceId) excludedIds.add(deviceId);
+    skipped.push({ label, error: 'excluded', excluded: true });
+    log('camera-skip', { label, error: 'excluded' });
+  };
+  const listedExcluded = (d) => {
+    if (!d.label || !isExcluded(d.label, d.deviceId)) return false;
+    exclude(d.label, d.deviceId);
+    return true;
+  };
+  // An open of the DEFAULT (no id): only after it opened is its label known. An excluded default
+  // is closed and never opened again in this probe.
+  let defaultExcluded = false;
+  const openDefault = async (constraints) => {
+    const r = await open(constraints);
+    if (isExcluded(r.label, r.deviceId)) {
+      stop(r);
+      exclude(r.label, r.deviceId);
+      defaultExcluded = true;
+      return null;
+    }
+    return r;
+  };
   // Ask an open camera for another mode without a second start; keep it as it is if it refuses.
   const withMode = async (r, constraints) => {
     try {
@@ -165,6 +236,7 @@ export async function openCamera(want = 'auto', o = {}) {
     for (const d of list) {
       if (!d.deviceId || !stereoLabelHint(d.label) || tried.has(d.deviceId)) continue;
       tried.add(d.deviceId);
+      if (listedExcluded(d)) continue;
       let r = null;
       try {
         r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
@@ -192,31 +264,35 @@ export async function openCamera(want = 'auto', o = {}) {
       pair = await tryNamedPairs(listed);
       if (pair) return result(pair, 'sbs');
     }
-    // No labels yet (no permission). Prime it on the default camera with NO constraints: in the
-    // DisplayXR Browser that is the 3D camera (listed first), so no phone lens is opened; a facing
-    // or size constraint would let the engine pick a lens instead. Then open a pair by id.
+    // No labels yet (no permission). Prime it on the default camera with NO constraints (a facing
+    // or size constraint would let the engine pick a phone lens instead). Where the runtime's 3D
+    // camera is the default this opens the pair itself; elsewhere (Windows lists it LAST) the list
+    // is read again and a NAMED pair is opened by id. A default that is a pair only by its SHAPE is
+    // kept as the pair only when no named one opens (it could be any wide sensor).
     if (listed.length && listed.every((d) => !d.label)) {
       let primed = null;
       try {
-        primed = await open(true);
+        primed = await openDefault(true);
       } catch (err) {
         skip('default', err);
       }
-      if (primed && isPair(primed)) return result(primed, 'sbs');
+      if (primed && primed.stereo) return result(primed, 'sbs'); // the device says it is the pair
+      if (primed && primed.deviceId) tried.add(primed.deviceId);
       const named = await tryNamedPairs(await listCameras());
       if (named) {
         stop(primed);
         return result(named, 'sbs');
       }
+      if (primed && isPair(primed)) return result(primed, 'sbs');
       // The primed default is the fallback as is (one camera start); ask it for the usual mode.
       if (primed) mono = await withMode(primed, MONO_CONSTRAINTS);
     }
   }
 
   // The default camera: the fallback (and, with labels already visible, also the probe base).
-  if (!mono) {
+  if (!mono && !defaultExcluded) {
     try {
-      mono = await open(MONO_CONSTRAINTS);
+      mono = await openDefault(MONO_CONSTRAINTS);
     } catch (err) {
       skip('default', err);
     }
@@ -230,11 +306,13 @@ export async function openCamera(want = 'auto', o = {}) {
   } catch {
     /* no enumeration: keep the default */
   }
+  // A label that names a pair first; never by list position (see the header).
   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;
-    if (tried.has(d.deviceId)) continue; // the fast path already opened it (not a pair, or busy)
+    if (tried.has(d.deviceId) || excludedIds.has(d.deviceId)) continue; // already opened (not a pair, or busy) or left out
+    if (listedExcluded(d)) continue; // the last resort never opens a sensor (a hand-tracking camera)
     let r = null;
     try {
       r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
@@ -243,11 +321,17 @@ export async function openCamera(want = 'auto', o = {}) {
       skip(d.label, err);
       continue;
     }
-    if (isPair(r)) {
+    if (isPair(r) && want !== 'mono') {
       stop(mono);
       log('camera-sbs', { label: r.label, width: r.width, height: r.height });
       return result(r, 'sbs');
     }
+    // No default could be used (excluded, busy): the first plain camera found is the fallback.
+    if (!mono && !isPair(r)) {
+      mono = await withMode(r, MONO_CONSTRAINTS);
+      if (want === 'mono') return result(mono, 'mono');
+      continue;
+    }
     stop(r);
   }
   if (mono) {
@@ -261,11 +345,14 @@ export async function openCamera(want = 'auto', o = {}) {
   );
 }
 
-/** The microphone, with echo cancellation and noise suppression. Null if unavailable/denied. */
+/**
+ * The microphone, with echo cancellation and noise suppression. Null if unavailable/denied.
+ * `deviceId`: that input exactly (`handle.setMic`).
+ */
 export async function openMic(o = {}) {
   const md = o.mediaDevices || (globalThis.navigator && navigator.mediaDevices);
   try {
-    const s = await md.getUserMedia({ audio: { ...AUDIO_CONSTRAINTS }, video: false });
+    const s = await md.getUserMedia({ audio: { ...AUDIO_CONSTRAINTS, ...(o.deviceId ? { deviceId: { exact: o.deviceId } } : {}) }, video: false });
     return s.getAudioTracks()[0] || null;
   } catch (err) {
     (o.log || (() => {}))('mic-skip', { error: err && err.name });