@displayxr/inline3d 1.28.0 → 1.29.0

package/js/call/signaling.js

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

package/js/call/wire.js

@@ -273,18 +273,24 @@ export function createConvergence() {
   const s = {
     hello: null,
     subjectZmm: null,
+    // Auto-convergence (call/disparity.js): the MEASURED disparity of the point between the remote
+    // person's eyes, in source eye pixels (left x − right x). When set it wins over the hint: it is
+    // read off the frames, so it needs no calibration and cannot disagree with them.
+    measuredPx: 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;
+        s.measuredPx !== null
+          ? s.measuredPx / 2 // half the disparity comes off each eye: the eyes land at zero parallax
+          : 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) {

package/js/inline3d-call-full.js

@@ -0,0 +1,48 @@
+// inline3d-call-full.js — `@displayxr/inline3d/call/full`: the call entry with 2D→3D bundled.
+//
+// PREVIEW tier (docs/sdk-stability.md). RFC 0003 §1 "Lift under bundlers", mechanism 2.
+//
+//   import { mountCall } from '@displayxr/inline3d/call/full';
+//   const call = await mountCall(el);        // 2D participants are lifted to 3D on a 3D display
+//
+// The plain `./call` entry finds the lift module through a COMPUTED import, which a bundler cannot
+// follow: a Vite/webpack/esbuild build of it resolves the specifier against the chunk URL, 404s,
+// and — since 1.29 — says so (`warning { code: 'lift-not-bundled' }`) rather than staying flat in
+// silence. This entry is the fix for the common case: it imports lift STATICALLY, so a bundler
+// sees it, code-splits it, and ships it; `mono3D` defaults to that `lift`. Pages that do not want
+// the depth-model plumbing keep importing `./call`. A page with its own `mono3D` (a function, or
+// `'off'`) is left alone.
+//
+// Everything else — `addCall`, `dxrSignaling`, the types, the `<dxr-call>` registration — is the
+// `./call` entry re-exported, and `<dxr-call>` is pointed at THIS `mountCall`, so importing this
+// entry makes every element on the page lift too.
+//
+// Until `./lift` (js/lift/) lands on main, that path holds a PLACEHOLDER exporting no `lift`;
+// this entry then behaves exactly like `./call` (`liftBundled === false`, and the same warning
+// fires). The import is `* as`, so the day the real module replaces the placeholder nothing here
+// changes.
+
+import * as liftMod from './lift/index.js';
+import { mountCall as mountCallBase, addCall as addCallBase, DxrCallElement } from './inline3d-call.js';
+
+export * from './inline3d-call.js';
+
+const lift = typeof liftMod.lift === 'function' ? liftMod.lift : null;
+
+/** True when this copy of the SDK carries the lift module (false on a build before `./lift` landed). */
+export const liftBundled = lift !== null;
+
+const withLift = (opts) => (lift && (!opts || opts.mono3D === undefined) ? { ...(opts || {}), mono3D: lift } : opts || {});
+
+/** `mountCall` of `./call`, with `mono3D` defaulted to the statically imported `lift`. */
+export function mountCall(el, opts) {
+  return mountCallBase(el, withLift(opts));
+}
+
+/** `addCall` of `./call`, with `mono3D` defaulted to the statically imported `lift`. */
+export function addCall(wall, container, opts) {
+  return addCallBase(wall, container, withLift(opts));
+}
+
+// `<dxr-call>` on a page that imported this entry lifts too (the element's mount seam).
+DxrCallElement.mount = mountCall;