@displayxr/inline3d 1.48.0 → 1.49.1

package/js/camera/app-share.js

@@ -0,0 +1,114 @@
+// camera/app-share.js — recognising a "3D screen share" device: a running DisplayXR app's
+// pre-weave side-by-side views, which the DisplayXR Browser lists as an ordinary `videoinput`
+// (runtime ADR-061, `XR_DXR_app_share`). Pure, no DOM.
+//
+// It lives under /camera, not /call, because the camera probe must know it too: such a device is
+// NOT a camera. Its label ("DisplayXR: <app> (3D)") matches stereoLabelHint's `\b3d\b`, so without
+// this rule `camera: 'auto'` would open somebody's running app and send it as their face. Every
+// probe path in capture.js leaves it out, whatever `exclude` says. `/call`'s share.js builds the
+// discovery API on top of it.
+//
+// The device contract (ADR-061 decision 13): label `DisplayXR: <app> (3D)`, device id prefix
+// `dxr-app:`, and on the opened track `getSettings().displayxrStereo.source === 'app'` (plus
+// `appName`, `zeroDisparityShiftFrac`). Browsers that predate the hint fields still use the label
+// and the id, so any ONE of the three is enough.
+//
+// Browsers WITHOUT the app-share device patch (DisplayXR Browser 1.9.x) list a development-gated
+// app source through their stereo-CAMERA device factory instead: label `3D Camera (DisplayXR) -
+// <app>`, id `dxr-stereo:…`, no `source` in the hint. That label shape proves nothing — such a
+// browser appends ` - <displayName>` to EVERY entry whenever the runtime lists more than one, so
+// the real camera next to the app reads `3D Camera (DisplayXR) - <camera>` too. What does tell
+// them apart is the opened track: an app source advertises `baselineMm: 0` and
+// `horizontalFovDeg: 0` (runtime ADR-061 decision 2); a real camera never has baseline 0. So
+// `isAppShareHint` checks the hint, and `legacyAppCandidate` only ever names a CANDIDATE, which
+// must be opened and verified before anything treats it as an app.
+
+/** `deviceId` prefix of an app-share device (cameras use `dxr-stereo:`). */
+export const APP_SHARE_ID_PREFIX = 'dxr-app:';
+
+/** The label of an app-share device; group 1 is the app's name. */
+export const APP_SHARE_LABEL_RE = /^DisplayXR: (.+) \(3D\)$/;
+
+/**
+ * The label a browser without the app-share device patch gives EVERY runtime stereo source when
+ * there is more than one (cameras and apps alike); group 1 is the source's display name. A shape,
+ * not an identity: see legacyAppCandidate.
+ */
+export const APP_SHARE_LEGACY_LABEL_RE = /^3D Camera \(DisplayXR\)\s+-\s+(.+)$/;
+
+/**
+ * Does a track's `displayxrStereo` hint describe a running app rather than a camera? True when
+ * `source === 'app'`; with no `source` (browsers without the app-share device patch), when the
+ * layout is side-by-side (or unstated) and BOTH `baselineMm` and `horizontalFovDeg` are exactly 0
+ * — what an app source advertises (ADR-061 decision 2) and no real camera does. A `source` that is
+ * anything else says "not an app". Never throws. Pure.
+ * @param {unknown} hint
+ * @returns {boolean}
+ */
+export function isAppShareHint(hint) {
+  if (!hint || typeof hint !== 'object') return false;
+  try {
+    const h = /** @type {any} */ (hint);
+    if (typeof h.source === 'string') return h.source === 'app';
+    if (h.layout != null && h.layout !== 'side-by-side') return false;
+    return h.baselineMm === 0 && h.horizontalFovDeg === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * On a browser WITHOUT the app-share device patch: is this listed device a CANDIDATE app source
+ * (`3D Camera (DisplayXR) - <name>`)? Returns `{ appName }` or null. A candidate is verified only
+ * after opening (`isAppShareHint` on the track's settings) — the same label shape is given to real
+ * cameras whenever the runtime lists more than one source. Never throws. Pure.
+ * @param {unknown} device  a `MediaDeviceInfo`, `{ label }`, or a label string
+ * @returns {{ appName: string } | null}
+ */
+export function legacyAppCandidate(device) {
+  let label = '';
+  try {
+    label = typeof device === 'string' ? device : device && typeof device === 'object' ? /** @type {any} */ (device).label : '';
+  } catch {
+    return null;
+  }
+  const m = typeof label === 'string' ? APP_SHARE_LEGACY_LABEL_RE.exec(label.trim()) : null;
+  const appName = m ? m[1].trim() : '';
+  return appName ? { appName } : null;
+}
+
+/** The app name an app-share label carries, or null. Pure. */
+export function appNameFromLabel(label) {
+  const m = typeof label === 'string' ? APP_SHARE_LABEL_RE.exec(label.trim()) : null;
+  return m ? m[1].trim() || null : null;
+}
+
+/**
+ * Is this an app-share device rather than a camera? Takes a `MediaDeviceInfo` (or any
+ * `{ label, deviceId }`), a label string, a track's settings (`{ displayxrStereo }`), or a
+ * `MediaStreamTrack` (its label and settings). True on ANY of: the label shape, the `dxr-app:` id
+ * prefix, or a `displayxrStereo` hint that `isAppShareHint` accepts (`source: 'app'`, or baseline
+ * and FOV both 0). The legacy `3D Camera (DisplayXR) - <name>` label alone is NOT enough (cameras
+ * get it too). Never throws. Pure.
+ * @param {unknown} x
+ * @returns {boolean}
+ */
+export function isAppShareDevice(x) {
+  if (!x) return false;
+  if (typeof x === 'string') return APP_SHARE_LABEL_RE.test(x.trim()) || x.startsWith(APP_SHARE_ID_PREFIX);
+  if (typeof x !== 'object') return false;
+  const o = /** @type {any} */ (x);
+  try {
+    if (typeof o.label === 'string' && APP_SHARE_LABEL_RE.test(o.label.trim())) return true;
+    if (typeof o.deviceId === 'string' && o.deviceId.startsWith(APP_SHARE_ID_PREFIX)) return true;
+    const hint = o.displayxrStereo || (typeof o.getSettings === 'function' ? (o.getSettings() || {}).displayxrStereo : null);
+    if (isAppShareHint(hint)) return true;
+    if (typeof o.getSettings === 'function') {
+      const id = (o.getSettings() || {}).deviceId;
+      if (typeof id === 'string' && id.startsWith(APP_SHARE_ID_PREFIX)) return true;
+    }
+  } catch {
+    /* a hostile getter: not an app */
+  }
+  return false;
+}

package/js/camera/capture.js

@@ -24,6 +24,16 @@
 //    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.
+//  - A DisplayXR Browser also lists every shareable running DisplayXR APP as a side-by-side
+//    `videoinput` ("DisplayXR: <app> (3D)", id `dxr-app:…`, runtime ADR-061) — 3D screen share.
+//    It is a pair, it names itself "3D", and it is NOT a camera: no probe path opens one, whatever
+//    `exclude` says (`exclude: false` included). Each is reported in `skipped` as `excluded` with
+//    `reason: 'app-share'`. `/call`'s `listShareableApps()` / `openAppShare()` are how a page uses them.
+//    A browser WITHOUT the app-share device patch lists such an app as a stereo camera instead
+//    ("3D Camera (DisplayXR) - <app>", no `source` in the hint) and gives the REAL camera the same
+//    label shape whenever there is more than one source — so the label cannot decide. Those are
+//    opened like any named pair, and the opened track's hint decides: baseline 0 and FOV 0 is an
+//    app (ADR-061 decision 2) → closed again, `reason: 'app-share'`, probing goes on.
 //
 // 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
@@ -31,6 +41,7 @@
 // `(stream, info) => MediaStream | Promise<MediaStream>`, returning a rectified SBS stream.
 
 import { looksSbs } from './geometry.js';
+import { isAppShareDevice, isAppShareHint } from './app-share.js';
 
 const MONO_CONSTRAINTS = { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } };
 // Ask a candidate stereo device for its widest mode; a 2560x720 or 3840x1080 pair comes back as
@@ -69,21 +80,28 @@ export function noCameraCode(skipped) {
  * 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;
+// Generic words, plus the one hand tracker that enumerates under its bare brand name: on Windows
+// an Ultraleap (Leap 2 / Leap Motion Controller) is a UVC "Ultraleap", nothing else in the label —
+// the generic words alone let it through (win box, 2026-11-04: it was the browser's default camera).
+export const CAMERA_EXCLUDE_BUILTIN = /\b(hand[- ]?track|tracking camera|eye[- ]?track|depth camera|ultraleap|leap motion|infrared|ir 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.
+ * case-insensitively as a substring, or a deviceId exactly; RegExps test the label), or only the
+ * app-share rule for `exclude: false`. Returns a predicate `(label, deviceId) => boolean`. An
+ * app-share device (camera/app-share.js: a running app's views, not a camera) is ALWAYS excluded —
+ * `exclude: false` turns the sensor list off, never that. Pure.
  * @param {false|null|undefined|ReadonlyArray<string|RegExp>|string|RegExp} exclude
  */
 export function cameraExcluder(exclude) {
-  if (exclude === false) return () => false;
+  const app = (label, deviceId) => isAppShareDevice({ label: String(label || ''), deviceId: typeof deviceId === 'string' ? deviceId : '' });
+  if (exclude === false) return app;
   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) => {
+    if (app(label, deviceId)) return true;
     const l = String(label || '');
     for (const x of list) {
       if (x instanceof RegExp) {
@@ -95,8 +113,12 @@ export function cameraExcluder(exclude) {
   };
 }
 
-/** A label that names a stereo camera, tried first when probing. Pure. */
+/**
+ * A label that names a stereo camera, tried first when probing. Never an app-share device's
+ * ("DisplayXR: <app> (3D)" says "3D" but is a running app, not a camera). Pure.
+ */
 export function stereoLabelHint(label) {
+  if (isAppShareDevice(String(label || ''))) return false;
   return /stereo|\b3d\b|\bsbs\b|dual/i.test(label || '');
 }
 
@@ -143,34 +165,64 @@ export async function openCamera(want = 'auto', o = {}) {
     // eye-tracking camera shared without stealing it) describes itself on the opened track:
     // `displayxrStereo: {layout, rectified, baselineMm, horizontalFovDeg}`.
     const stereo = st.displayxrStereo && st.displayxrStereo.layout === 'side-by-side' ? st.displayxrStereo : null;
-    return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '', stereo };
+    // A running app's views (3D screen share, ADR-061) describe themselves too: `source: 'app'`,
+    // or — on a browser without the app-share device patch, which lists the app as a "3D Camera
+    // (DisplayXR) - <app>" — baseline 0 and FOV 0, which no real camera advertises. Every probe
+    // path checks this on the OPENED track (rejectOpened), since the label cannot tell them apart.
+    const appShare = isAppShareDevice({ label: t.label || '', deviceId: st.deviceId || '' }) || isAppShareHint(st.displayxrStereo);
+    return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '', stereo, appShare };
   };
   const skip = (label, err) => {
     skipped.push({ label, error: `${err.name}: ${err.message}`, busy: isBusyError(err), denied: isDeniedError(err) });
     log('camera-skip', { label, error: err.name });
   };
   const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
+  const listCameras = async () => {
+    try {
+      return (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput');
+    } catch {
+      return []; // no enumeration: the paths below still work
+    }
+  };
   // 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) => {
+  // `reason`: 'app-share' for a running app's views (never a camera), else 'excluded'.
+  const exclude = (label, deviceId, reason = 'excluded') => {
     if (deviceId && excludedIds.has(deviceId)) return;
     if (deviceId) excludedIds.add(deviceId);
-    skipped.push({ label, error: 'excluded', excluded: true });
-    log('camera-skip', { label, error: 'excluded' });
+    skipped.push({ label, error: 'excluded', excluded: true, reason });
+    log('camera-skip', { label, error: 'excluded', reason });
   };
+  const isApp = (d) => isAppShareDevice({ label: d.label || '', deviceId: d.deviceId || '' });
   const listedExcluded = (d) => {
+    if (isApp(d)) {
+      exclude(d.label || '', d.deviceId, 'app-share');
+      return true;
+    }
     if (!d.label || !isExcluded(d.label, d.deviceId)) return false;
     exclude(d.label, d.deviceId);
     return true;
   };
+  /** An opened device that must not be used: an app share (by its own hint too) or an excluded label. Closes it. */
+  const rejectOpened = (r) => {
+    if (r.appShare) {
+      stop(r);
+      exclude(r.label, r.deviceId, 'app-share');
+      return true;
+    }
+    if (isExcluded(r.label, r.deviceId)) {
+      stop(r);
+      exclude(r.label, r.deviceId);
+      return true;
+    }
+    return false;
+  };
   // 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);
+    if (rejectOpened(r)) {
       defaultExcluded = true;
       return null;
     }
@@ -206,6 +258,28 @@ export async function openCamera(want = 'auto', o = {}) {
     },
   });
 
+  // `label:<text>`: the first camera whose label contains the text (case-insensitive) — a way to
+  // force a device from a URL or a config, where a per-origin deviceId is useless. Labels need
+  // permission: with none visible yet, the default camera is primed once and let go. Explicit like
+  // a deviceId, so it opens an excluded device too.
+  if (typeof want === 'string' && want.startsWith('label:')) {
+    const needle = want.slice('label:'.length).trim().toLowerCase();
+    let list = await listCameras();
+    if (needle && list.length && list.every((d) => !d.label)) {
+      try {
+        stop(await open(true));
+      } catch (err) {
+        skip('default', err);
+      }
+      list = await listCameras();
+    }
+    // Never a running app's views: `label:3d` means a camera (open an app with openAppShare()).
+    const d = needle ? list.find((x) => x.deviceId && !isApp(x) && (x.label || '').toLowerCase().includes(needle)) : null;
+    if (!d) throw Object.assign(new Error(`camera unavailable: no camera labelled "${needle}"`), { code: noCameraCode(skipped), skipped });
+    log('camera-label', { label: d.label, needle });
+    want = d.deviceId;
+  }
+
   // An explicit device id.
   if (typeof want === 'string' && !['auto', 'stereo', 'mono'].includes(want)) {
     let r;
@@ -225,13 +299,6 @@ export async function openCamera(want = 'auto', o = {}) {
   // camera start can take seconds (a busy capture stack took 7-20 s per start on a field box), and
   // the default-first probe below costs two or three of them before it reaches the pair.
   const tried = new Set();
-  const listCameras = async () => {
-    try {
-      return (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput');
-    } catch {
-      return []; // no enumeration: the paths below still work
-    }
-  };
   const tryNamedPairs = async (list) => {
     for (const d of list) {
       if (!d.deviceId || !stereoLabelHint(d.label) || tried.has(d.deviceId)) continue;
@@ -244,6 +311,7 @@ export async function openCamera(want = 'auto', o = {}) {
         skip(d.label, err);
         continue;
       }
+      if (rejectOpened(r)) continue; // an app that described itself only on its track
       if (isPair(r)) {
         log('camera-sbs', { label: r.label, width: r.width, height: r.height, direct: true });
         return r;
@@ -290,11 +358,27 @@ export async function openCamera(want = 'auto', o = {}) {
   }
 
   // The default camera: the fallback (and, with labels already visible, also the probe base).
+  // With labels visible and an excluded device listed, the default is not opened blind — it may BE
+  // the sensor (an idle Ultraleap is the default camera on some Windows boxes, and an eye tracker's
+  // camera should not be started at all) — the first camera that is not excluded is opened by id.
   if (!mono && !defaultExcluded) {
-    try {
-      mono = await openDefault(MONO_CONSTRAINTS);
-    } catch (err) {
-      skip('default', err);
+    const listed = await listCameras();
+    const anyExcluded = listed.filter(listedExcluded).length > 0; // every excluded device is noted, not just the first
+    const first = anyExcluded ? listed.find((d) => d.deviceId && !excludedIds.has(d.deviceId)) || null : null;
+    if (first) {
+      if (first.deviceId) tried.add(first.deviceId);
+      try {
+        mono = await open({ deviceId: { exact: first.deviceId }, ...MONO_CONSTRAINTS });
+        if (rejectOpened(mono)) mono = null;
+      } catch (err) {
+        skip(first.label, err);
+      }
+    } else {
+      try {
+        mono = await openDefault(MONO_CONSTRAINTS);
+      } catch (err) {
+        skip('default', err);
+      }
     }
   }
   if (want === 'mono' && mono) return result(mono, 'mono');
@@ -321,6 +405,7 @@ export async function openCamera(want = 'auto', o = {}) {
       skip(d.label, err);
       continue;
     }
+    if (rejectOpened(r)) continue;
     if (isPair(r) && want !== 'mono') {
       stop(mono);
       log('camera-sbs', { label: r.label, width: r.width, height: r.height });