@displayxr/inline3d 1.27.0 → 1.29.0

package/js/call/element.js

@@ -0,0 +1,217 @@
+// call/element.js — `<dxr-call>`: the one-line path as markup (RFC 0003 §1, C1).
+//
+//   <script type="module" src="https://cdn.jsdelivr.net/npm/@displayxr/inline3d@1/dist/call.js"></script>
+//   <dxr-call accent="violet"></dxr-call>
+//
+// REGISTRATION. Importing `@displayxr/inline3d/call` (or `/call/full`, or the CDN bundle) defines
+// the element — the entry calls `defineCallElement()` at the bottom of inline3d-call.js, which is
+// why that file is listed in package.json `sideEffects`. This file itself defines nothing on
+// import; it is the class, importable by path for tests.
+//
+// The element is SUGAR over `mountCall(this, attrsToOpts(this))`: it mounts on connect, `leave()`s
+// on disconnect, re-dispatches every call event as a DOM `CustomEvent` (`dxr-call:peer`,
+// `dxr-call:joined`, …, `detail` = the call's payload, bubbling and composed) and exposes the handle
+// as `el.call`. It is the element's LIGHT DOM that hosts the tiles — no shadow root: woven canvases
+// live in the document's own tree, and the SDK's chrome stylesheet is document-level.
+//
+// Attributes are the string-typed subset of `CallOptions` (attrsToOpts below). Anything else — a
+// `MediaStream` camera, a custom `SignalingAdapter`, a `lift` function, a `wall` — is a JS
+// property set BEFORE the element connects: `el.options = { … }`. Options win over attributes.
+// Attributes are read once, at connect: this element is not reactive to later attribute changes
+// (change them, then re-append it — which is a new call; see below).
+//
+// DISCONNECT = LEAVE. Removing the element ends the call, deliberately: a woven canvas must never
+// be remounted mid-call (woven-canvas rule 2), so a DOM move IS a teardown. SPA routers: mount
+// `<dxr-call>` in a layout that survives navigation. Re-appending a disconnected element starts a
+// fresh call (a new mount; the old handle is gone).
+//
+// NO GLOBALS (Decision 11): nothing here touches `globalThis` beyond `customElements.define`,
+// which `defineCallElement()` does exactly once and only when a registry exists. The class is
+// usable — and unit-testable — without a DOM: the base class falls back to a plain class when
+// `HTMLElement` is absent, and the mount seam (`DxrCallElement.mount`) is overridable.
+//
+// The import below is CIRCULAR (inline3d-call.js imports this file to register the element), so
+// nothing from it may be read while this module evaluates: `mount` defaults lazily, at connect.
+
+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', 'format', 'speaker', 'quality', 'error', 'warning', 'session'];
+const TAG = '[inline3d/call] <dxr-call>';
+
+/** A boolean attribute: present is true, unless its value spells "false"/"0"/"off"/"no". */
+const isOn = (v) => v !== null && v !== undefined && !/^(false|0|off|no)$/i.test(String(v).trim());
+const num = (v) => {
+  if (v === null || v === undefined || String(v).trim() === '') return undefined;
+  const m = /^\s*([0-9.]+)\s*\/\s*([0-9.]+)\s*$/.exec(String(v)); // "16/9"
+  const n = m ? +m[1] / +m[2] : +v;
+  return Number.isFinite(n) ? n : undefined;
+};
+const str = (v) => (v === null || v === undefined || String(v).trim() === '' ? undefined : String(v).trim());
+
+/**
+ * Attribute → option mapping, pure. `source` is an element (or anything with `getAttribute`) or a
+ * `(name) => value | null` function. Unset attributes contribute nothing (the call's own defaults
+ * apply), so the result can be spread under `el.options`.
+ *
+ * | attribute            | option                                   |
+ * |----------------------|------------------------------------------|
+ * | `room`               | `room` (an id or an invite link)         |
+ * | `signaling`          | `signaling: dxrSignaling(url)`           |
+ * | `key`                | `key`                                    |
+ * | `camera`             | `camera` (`auto`/`stereo`/`mono`/deviceId)|
+ * | `layout`             | `layout` (`grid`/`speaker`)              |
+ * | `accent`             | `accent`                                 |
+ * | `max-peers`          | `maxPeers`                               |
+ * | `no-ui`              | `ui: false`                              |
+ * | `auto-join`          | `autoJoin: true`                         |
+ * | `mono3d="off"`       | `mono3D: 'off'`                          |
+ * | `no-audio`           | `audio: false`                           |
+ * | `no-self-view`       | `selfView: false`                        |
+ * | `no-auto-converge`   | `autoConverge: false`                    |
+ * | `tile-aspect`        | `tileAspect` (a number, or `w/h`)        |
+ * | `invite-base`        | `inviteBase`                             |
+ * | `browser-url`        | `browserUrl`                             |
+ * | `debug`              | `debug: true`                            |
+ *
+ * @param {{ getAttribute(name: string): string | null } | ((name: string) => string | null)} source
+ * @returns {object} a partial `CallOptions`
+ */
+export function attrsToOpts(source) {
+  const get = typeof source === 'function' ? source : (n) => (source && typeof source.getAttribute === 'function' ? source.getAttribute(n) : null);
+  const o = {};
+  const put = (k, v) => {
+    if (v !== undefined) o[k] = v;
+  };
+  put('room', str(get('room')));
+  const signaling = str(get('signaling'));
+  if (signaling) o.signaling = dxrSignaling(signaling, str(get('key')) ? { key: str(get('key')) } : {});
+  put('key', str(get('key')));
+  put('camera', str(get('camera')));
+  put('layout', str(get('layout')));
+  put('accent', str(get('accent')));
+  put('maxPeers', num(get('max-peers')));
+  if (isOn(get('no-ui'))) o.ui = false;
+  if (isOn(get('auto-join'))) o.autoJoin = true;
+  const m3 = str(get('mono3d'));
+  if (m3 && /^(off|false|0|no)$/i.test(m3)) o.mono3D = 'off';
+  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;
+  put('tileAspect', num(get('tile-aspect')));
+  put('inviteBase', str(get('invite-base')));
+  put('browserUrl', str(get('browser-url')));
+  if (isOn(get('debug'))) o.debug = true;
+  return o;
+}
+
+// Usable without a DOM (unit tests, SSR imports): a plain base class where HTMLElement is absent.
+const Base = typeof HTMLElement === 'function' ? HTMLElement : class {};
+
+export class DxrCallElement extends Base {
+  /**
+   * The mount seam: null = `mountCall` of `./call`. `./call/full` points it at its lift-wired
+   * `mountCall`, so importing that entry makes every `<dxr-call>` lift 2D participants; tests
+   * inject a fake. Resolved at connect, never at import (the circular import above).
+   */
+  static mount = null;
+
+  constructor() {
+    super();
+    /** Options that are not strings — set BEFORE connect; win over attributes. */
+    this.options = null;
+    /** The `CallHandle` once mounted; null before, and again after disconnect. */
+    this.call = null;
+    /** Resolves with the handle when the mount lands (null if the element left first); rejects if it failed. */
+    this.ready = null;
+    this._gen = 0;
+    this._off = [];
+    this._pending = null;
+  }
+
+  connectedCallback() {
+    if (this.call || this._pending) return; // already mounted, or mounting
+    const gen = ++this._gen;
+    const opts = { ...attrsToOpts(this), ...(this.options && typeof this.options === 'object' ? this.options : {}) };
+    const mount = this.constructor.mount || DxrCallElement.mount || mountCall;
+    // Synchronous call (a throw becomes a rejection): the container's chrome exists on return.
+    this._pending = new Promise((res) => res(mount(this, opts)))
+      .then(
+        (handle) => {
+          this._pending = null;
+          if (gen !== this._gen) {
+            // Disconnected while the camera/lobby was coming up: the mount landed on a dead element.
+            handle.leave();
+            return null;
+          }
+          this.call = handle;
+          this._off = CALL_EVENTS.map((t) => handle.on(t, (detail) => this._dispatch(t, detail)));
+          // The call module only console.warns an error when NOBODY listens; the element always
+          // does, so it says it here — a drop-in widget's page usually has no JS listening at all.
+          this._off.push(handle.on('error', (e) => console.warn(`${TAG} ${e.code}: ${e.message}`)));
+          this._dispatch('ready', { call: handle });
+          // `auto-join` (and `no-ui`) join DURING the mount, before anything could subscribe —
+          // and a room that already had people reports them during the join too. Replay what a
+          // listener would have seen, from the handle's state: 'joined', then one 'peer' per
+          // participant already there. (Errors raised while mounting — 'camera-busy' — were
+          // console.warned by the call itself, since nothing was listening yet.)
+          if (handle.state === 'in-call') {
+            this._dispatch('joined', { room: handle.room, id: handle.id });
+            for (const p of handle.peers) this._dispatch('peer', { id: p.id });
+          }
+          return handle;
+        },
+        (err) => {
+          this._pending = null;
+          this._dispatch('error', { code: 'mount-failed', message: String((err && err.message) || err), error: err || null });
+          console.warn(`${TAG} mount failed: ${String((err && err.message) || err)}`);
+          throw err;
+        }
+      );
+    this.ready = this._pending;
+    // A rejected `ready` nobody awaits must not be an unhandled rejection in a plain page.
+    this.ready.catch(() => {});
+  }
+
+  disconnectedCallback() {
+    this._gen++; // a mount still in flight lands on a dead element (see above)
+    const call = this.call;
+    this.call = null;
+    // leave() FIRST, so the call's 'left' still reaches listeners on the element as
+    // `dxr-call:left` (it no longer bubbles anywhere: the element is out of the tree); THEN unhook.
+    if (call) call.leave();
+    for (const off of this._off) {
+      try {
+        off();
+      } catch {
+        /* ignore */
+      }
+    }
+    this._off = [];
+  }
+
+  _dispatch(type, detail) {
+    if (typeof CustomEvent !== 'function' || typeof this.dispatchEvent !== 'function') return;
+    this.dispatchEvent(new CustomEvent(CALL_EVENT_PREFIX + type, { detail, bubbles: true, composed: true }));
+  }
+}
+
+/**
+ * Register `<dxr-call>` (or another tag name) once. Returns true when this call registered it,
+ * false when the name was already taken (by this class: fine; by another: a warning) or when there
+ * is no `customElements` registry (Node, a worker).
+ *
+ * @param {string} [name='dxr-call']
+ * @param {CustomElementRegistry} [registry=globalThis.customElements]
+ */
+export function defineCallElement(name = 'dxr-call', registry = globalThis.customElements) {
+  if (!registry || typeof registry.define !== 'function') return false;
+  const existing = registry.get(name);
+  if (existing) {
+    if (existing !== DxrCallElement) console.warn(`${TAG} <${name}> is already defined by another class; leaving it`);
+    return false;
+  }
+  registry.define(name, DxrCallElement);
+  return true;
+}

package/js/call/lift.js

@@ -0,0 +1,323 @@
+// call/lift.js — mono→3D for mono peers, through the SDK's lift() provider chain (RFC 0002 §5).
+//
+// This module never contains a depth model or vendor code. It decides WHETHER a mono peer is
+// lifted, hands its <video> to `lift()` (`@displayxr/inline3d/lift`), and steers the lifted
+// streams: priority from the active speaker and tile visibility, convergence from the call's one
+// depth control, a cap on concurrent lifts, and a frame-time watch for the web provider.
+//
+// `lift` is NEVER a hard dependency. `mono3D: 'auto'` imports it lazily at runtime; a missing
+// module (not installed, not built into this copy of the SDK), a failed import, or a device that
+// can do neither native nor WebGPU lifting resolves to FLAT with one log line. A page can inject
+// its own `lift` function (`mono3D: lift`) — that is how tests, bundled apps and pre-merge demos
+// work.
+//
+// Pure except for `resolveLift`'s default importer — see test/call.test.mjs.
+
+/** How a mono peer's lifted stream is scheduled. Mirrors lift()'s `LiftPriority`. */
+export const LIFT_PRIORITY = Object.freeze({ speaker: 'high', other: 'normal', hidden: 'paused' });
+const PRIORITIES = ['high', 'normal', 'low', 'paused'];
+
+/** Convergence dead band: a depth slider this close to 0 hands lift 'auto'. */
+const DEPTH_AUTO_BAND = 0.02;
+
+/** Web-provider frame-time watch: warn when frames average slower than this for this long. */
+const DEGRADED_FRAME_MS = 1000 / 20;
+const DEGRADED_HOLD_MS = 3000;
+const RECOVERED_FRAME_MS = 1000 / 28;
+
+/**
+ * `mono3D` option → `'auto' | 'off' | Function`. `false`/`'off'` → 'off'; a function is an
+ * injected `lift`; anything else → 'auto'.
+ */
+export function normalizeMono3D(v) {
+  if (typeof v === 'function') return v;
+  if (v === false || v === 'off') return 'off';
+  return 'auto';
+}
+
+/**
+ * Where `mono3D: 'auto'` looks for the lift module: the `./lift` subpath of THIS copy of the SDK,
+ * resolved relative to this file (js/call/ → js/lift/index.js), exactly as the package maps
+ * `@displayxr/inline3d/lift`. The specifier is computed, so a bundler neither fails on a copy of
+ * the SDK without lift nor pulls lift into every call bundle; a bundled app that wants lifting
+ * passes `mono3D: lift` (imported itself) instead.
+ */
+export function defaultLiftSpecifier(base = import.meta.url) {
+  if (liftSpecifier) return typeof liftSpecifier === 'function' ? liftSpecifier() : liftSpecifier;
+  return new URL('../lift/index.js', base).href;
+}
+
+// The pre-bundled CDN build (dist/call.js) has no js/call/ directory to resolve against: it points
+// this at its own sibling chunk (`dist/lift.js`) instead. A URL string, or a function returning
+// one (evaluated at import time, so `import.meta.url` of the caller can be used). Null = default.
+let liftSpecifier = null;
+export function setLiftSpecifier(spec) {
+  liftSpecifier = spec || null;
+}
+
+function defaultImporter() {
+  return import(/* @vite-ignore */ /* webpackIgnore: true */ defaultLiftSpecifier());
+}
+
+/**
+ * Resolve the `mono3D` option to a usable lift function, or to null (flat) with a reason.
+ *
+ *   'off'      → { lift: null, reason: 'off' }
+ *   function   → { lift: fn, capabilities: fn.liftCapabilities || null, source: 'injected' }
+ *   'auto'     → import the lift module; then, when it has `liftCapabilities()`, require a native
+ *                provider OR a WebGPU adapter for the web fallback (without it, the module has no
+ *                live video path). Without `liftCapabilities`, a missing `navigator.gpu` is the
+ *                same verdict. Any failure → { lift: null, reason }, never a throw.
+ *
+ * @param {'auto'|'off'|Function} mono3D
+ * @param {{ importer?: () => Promise<any>, nav?: any, log?: (tag: string, o: object) => void, capsOpts?: object }} [o]
+ * @returns {Promise<{ lift: Function|null, capabilities: Function|null, caps: object|null, source: string, reason: string|null }>}
+ */
+export async function resolveLift(mono3D, { importer = defaultImporter, nav = globalThis.navigator, log = null, capsOpts = { webFallback: true } } = {}) {
+  const say = (tag, x) => log && log(tag, x);
+  const flat = (reason, extra = {}) => {
+    say('lift-unavailable', { reason, ...extra });
+    return { lift: null, capabilities: null, caps: null, source: 'none', reason };
+  };
+  const m = normalizeMono3D(mono3D);
+  if (m === 'off') return { lift: null, capabilities: null, caps: null, source: 'none', reason: 'off' };
+  if (typeof m === 'function') {
+    const capabilities = typeof m.liftCapabilities === 'function' ? m.liftCapabilities : null;
+    return { lift: m, capabilities, caps: null, source: 'injected', reason: null };
+  }
+  let mod;
+  try {
+    mod = await importer();
+  } catch (err) {
+    return flat('import-failed', { message: String((err && err.message) || err).slice(0, 200) });
+  }
+  const lift = mod && typeof mod.lift === 'function' ? mod.lift : null;
+  if (!lift) return flat('no-lift-export');
+  const capabilities = typeof mod.liftCapabilities === 'function' ? mod.liftCapabilities : null;
+  let caps = null;
+  if (capabilities) {
+    try {
+      caps = await capabilities(capsOpts);
+    } catch {
+      caps = null;
+    }
+    const web = !!(caps && caps.webFallback && caps.webFallback.webgpu);
+    if (caps && !caps.native && !web) return flat('no-provider', { native: false, webgpu: false });
+  } else if (!(nav && nav.gpu)) return flat('no-webgpu');
+  say('lift-ready', { native: !!(caps && caps.native), provider: (caps && caps.provider) || null });
+  return { lift, capabilities, caps, source: 'module', reason: null };
+}
+
+/**
+ * The call's ONE depth control ([-1, 1], + = push the picture back) as lift's convergence.
+ * lift's `convergence` is the normalised disparity (0 = far, 1 = near) placed on the glass, so a
+ * larger value puts more of the picture behind it. 0 (± a small band) = 'auto' (lift centres its
+ * own subject); otherwise 0.5 + 0.5·depth, clamped to [0, 1].
+ */
+export function liftConvergenceFor(depth) {
+  const d = Number.isFinite(+depth) && depth !== null ? Math.max(-1, Math.min(1, +depth)) : 0;
+  if (Math.abs(d) < DEPTH_AUTO_BAND) return 'auto';
+  return Math.round((0.5 + 0.5 * d) * 1000) / 1000;
+}
+
+/** A lifted tile's priority: hidden/offscreen → paused, the active speaker → high, else normal. */
+export function liftPriorityFor({ id, speakerId, visible = true }) {
+  if (!visible) return LIFT_PRIORITY.hidden;
+  return id !== null && id !== undefined && id === speakerId ? LIFT_PRIORITY.speaker : LIFT_PRIORITY.other;
+}
+
+/**
+ * THE HOOK FOR THE NATIVE PROVIDER'S PER-STREAM PRIORITY (`xrSetLiftStreamPriorityDXR`: HIGH =
+ * every round, NORMAL = round-robin, LOW = every Nth, PAUSED = keep the last frame).
+ *
+ * Today it forwards to the lift handle's `setPriority()` when it has one: in native mode that is
+ * the element's `dxr-lift-priority` attribute, which the browser maps onto the runtime's stream
+ * priority; on the web path lift runs one stream per element and it is a no-op. A handle without
+ * `setPriority` (an injected lift, an older lift build) is a no-op here — the call still works,
+ * every stream is just scheduled equally. Nothing else in the call module talks priority, so this
+ * one function is what changes if the native provider grows a different surface.
+ *
+ * @returns {boolean} true when the handle accepted it
+ */
+export function setLiftPriority(handle, level) {
+  if (!handle || !PRIORITIES.includes(level)) return false;
+  if (typeof handle.setPriority !== 'function') return false;
+  try {
+    return handle.setPriority(level) !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Frame-time watch for lifted tiles on the WEB provider (the native one runs in the display
+ * service, off the page's frame budget). Feed it the page's frame intervals; it reports
+ * `'degraded'` once when the smoothed interval stays above ~20 fps for 3 s, and `'recovered'`
+ * once it is back above ~28 fps. Pure.
+ */
+export function createFrameWatch({ degradedMs = DEGRADED_FRAME_MS, recoveredMs = RECOVERED_FRAME_MS, holdMs = DEGRADED_HOLD_MS, alpha = 0.1 } = {}) {
+  let ema = null;
+  let slowFor = 0;
+  let degraded = false;
+  return {
+    /** @param {number} dtMs  one frame interval @returns {'degraded'|'recovered'|null} */
+    feed(dtMs) {
+      if (!(dtMs > 0) || dtMs > 1000) return null; // a tab switch, not a frame
+      ema = ema === null ? dtMs : ema + alpha * (dtMs - ema);
+      if (!degraded) {
+        slowFor = ema > degradedMs ? slowFor + dtMs : 0;
+        if (slowFor >= holdMs) {
+          degraded = true;
+          return 'degraded';
+        }
+      } else if (ema < recoveredMs) {
+        degraded = false;
+        slowFor = 0;
+        return 'recovered';
+      }
+      return null;
+    },
+    reset() {
+      ema = null;
+      slowFor = 0;
+      degraded = false;
+    },
+    get frameMs() {
+      return ema;
+    },
+    get degraded() {
+      return degraded;
+    },
+  };
+}
+
+/**
+ * The call's lifted streams: at most `max` at once, each one lift() handle per peer, steered as a
+ * group (speaker → priority, depth → convergence). Pure apart from the `lift` it is given.
+ *
+ * @param {{ lift: Function, max?: number, log?: (tag: string, o: object) => void, options?: object }} o
+ */
+export function createLiftPool({ lift, max = 4, log = null, options = null } = {}) {
+  // Page-supplied lift options (models, ort, quality, providers, …). The call owns the keys that
+  // make it a call tile — mode, wall, ui, convergence, priority — so those always win.
+  const extra = options && typeof options === 'object' ? options : {};
+  const entries = new Map(); // id → { gen, handle|null, visible, priority, pending }
+  let speakerId = null;
+  let depth = 0;
+  let gen = 0;
+  const say = (tag, x) => log && log(tag, x);
+
+  const apply = (id, e) => {
+    if (!e.handle) return;
+    const p = liftPriorityFor({ id, speakerId, visible: e.visible });
+    if (p === e.priority) return;
+    e.priority = p;
+    const ok = setLiftPriority(e.handle, p);
+    say('lift-priority', { peer: id, priority: p, applied: ok });
+  };
+
+  const pool = {
+    get size() {
+      return entries.size;
+    },
+    get max() {
+      return max;
+    },
+    set max(n) {
+      max = Math.max(0, n | 0);
+    },
+    has: (id) => entries.has(id),
+    handle: (id) => (entries.get(id) && entries.get(id).handle) || null,
+    priority: (id) => (entries.get(id) && entries.get(id).priority) || null,
+    /** Is there a slot for `id` (it already holds one, or fewer than `max` are taken)? */
+    canAcquire: (id) => entries.has(id) || entries.size < max,
+    /**
+     * Lift `element` for peer `id`. Resolves with the handle, or null when there is no slot, when
+     * `release(id)` ran meanwhile (the late handle is removed), or when lift() rejects (`onError`
+     * gets it). One pending/live stream per id: a second acquire returns the first.
+     */
+    acquire(id, element, { wall, visible = true, onError } = {}) {
+      const cur = entries.get(id);
+      if (cur) return cur.pending || Promise.resolve(cur.handle);
+      if (entries.size >= max) return Promise.resolve(null);
+      const my = ++gen;
+      const priority = liftPriorityFor({ id, speakerId, visible });
+      const e = { gen: my, handle: null, visible, priority, pending: null };
+      entries.set(id, e);
+      const opts = { quality: 'auto', ...extra, mode: 'live', wall, ui: 'none', convergence: liftConvergenceFor(depth), priority };
+      say('lift-acquire', { peer: id, priority, convergence: opts.convergence });
+      e.pending = Promise.resolve()
+        .then(() => lift(element, opts))
+        .then(
+          (h) => {
+            if (entries.get(id) !== e || e.gen !== my) {
+              try {
+                h && h.remove && h.remove();
+              } catch {
+                /* ignore */
+              }
+              return null;
+            }
+            e.pending = null;
+            e.handle = h || null;
+            // Converge on the CURRENT state (speaker/depth/visibility may have moved meanwhile).
+            e.priority = null;
+            apply(id, e);
+            if (h && typeof h.setConvergence === 'function') h.setConvergence(liftConvergenceFor(depth));
+            return e.handle;
+          },
+          (err) => {
+            if (entries.get(id) === e) entries.delete(id);
+            say('lift-failed', { peer: id, message: String((err && err.message) || err).slice(0, 200) });
+            if (onError) onError(err);
+            return null;
+          }
+        );
+      return e.pending;
+    },
+    /** Remove peer `id`'s lift (a pending one is removed when it lands). */
+    release(id) {
+      const e = entries.get(id);
+      if (!e) return;
+      entries.delete(id);
+      if (e.handle) {
+        try {
+          e.handle.remove();
+        } catch {
+          /* the session may be gone */
+        }
+      }
+      say('lift-release', { peer: id });
+    },
+    releaseAll() {
+      for (const id of [...entries.keys()]) pool.release(id);
+    },
+    setSpeaker(id) {
+      speakerId = id === undefined ? null : id;
+      for (const [pid, e] of entries) apply(pid, e);
+    },
+    setVisible(id, visible) {
+      const e = entries.get(id);
+      if (!e || e.visible === !!visible) return;
+      e.visible = !!visible;
+      apply(id, e);
+    },
+    /** The call's depth control → every lifted stream's convergence. */
+    setDepth(v) {
+      depth = v;
+      const c = liftConvergenceFor(v);
+      for (const e of entries.values()) if (e.handle && typeof e.handle.setConvergence === 'function') e.handle.setConvergence(c);
+      return c;
+    },
+    /** True when any live lifted stream runs on the page (the web provider), not in the service. */
+    get anyWeb() {
+      for (const e of entries.values()) if (e.handle && !e.handle.native) return true;
+      return false;
+    },
+    /** Snapshot for info()/tests. */
+    list() {
+      return [...entries].map(([id, e]) => ({ id, priority: e.priority, pending: !!e.pending, native: !!(e.handle && e.handle.native) }));
+    },
+  };
+  return pool;
+}