@pollen-robotics/reachy-mini-sdk 1.8.0 → 1.8.1

package/dist/lib/reachy-mini.js

@@ -7,6 +7,39 @@ import { oauthHandleRedirectIfPresent, oauthLoginUrl, } from '@huggingface/hub';
 import { degToRad, rpyToMatrix } from './math.js';
 import { consumeFragmentCredentials, readPreselectedRobotIdFromUrl, sdpHasAudioSendRecv, } from './url-helpers.js';
 import { UPLOAD_CHUNK_SIZE, UPLOAD_BUFFERED_HIGH_WATER, UPLOAD_BUFFERED_LOW_WATER, hasCompressionStream, makeUploadId, bytesToBase64, gzipBase64, clampVolume, } from './upload-helpers.js';
+// ─── Internal constants ──────────────────────────────────────────────────────
+/**
+ * How long we tolerate `iceConnectionState === 'disconnected'` before
+ * surfacing it as an error. The spec defines this state as transient
+ * (browsers keep STUN keep-alives running and usually heal in 1-2 s
+ * on WiFi blips, AP roams, brief 4G dropouts). Consumers watching
+ * `iceStateChange` directly should outlive this window before
+ * showing any fatal UI.
+ */
+const ICE_DISCONNECT_GRACE_MS = 3000;
+/**
+ * Grace before treating `iceConnectionState === 'failed'` as terminal.
+ * The spec says `failed` IS terminal, but we've observed real
+ * `failed → connected` flips on rapid AP roams and iOS BT route
+ * changes — 1 s of debounce absorbs those without noticeably
+ * delaying a real failure.
+ */
+const ICE_FAILED_GRACE_MS = 1000;
+/**
+ * Ceiling on how long we'll keep `_armIceGraceOnVisibility` waiting
+ * for the tab to come back. The daemon's `webrtcsink` runs a STUN
+ * consent-freshness check (RFC 7675, ~30 s default) and unilaterally
+ * tears its side of the session down past that window, releasing the
+ * producer slot on central. If the user backgrounded the tab for
+ * longer than this, running another 3 s foreground grace is a lie —
+ * the underlying transport is gone, nothing can recover. Give up
+ * straight away so the host shows the real "session expired" UX
+ * instead of a fake "Reconnecting…" badge that's never going to
+ * heal. 60 s gives a 2× margin over the daemon-side timeout — long
+ * enough to absorb a "phone in pocket for 45 s" case, short enough
+ * to be honest with the user.
+ */
+const MAX_VISIBILITY_DEFER_MS = 60_000;
 export class ReachyMini extends EventTarget {
     // ─── Config ──────────────────────────────────────────────────────────
     _signalingUrl;
@@ -62,6 +95,19 @@ export class ReachyMini extends EventTarget {
     _sessionReject = null;
     _iceConnected = false;
     _dcOpen = false;
+    // ─── Resilience: ICE-blip debounce + network awareness ──────────────
+    // Backs `_scheduleIceGrace` / `_armIceGraceOnVisibility` and the
+    // `networkOnline` / `networkOffline` / `networkChange` forwarders.
+    // All three handler slots are scoped to the lifetime of a live
+    // session (installed in `startSession`, cleared in
+    // `stopSession` / `disconnect` / `_handleEndSession` /
+    // `_failSessionRejected`).
+    _iceGraceTimer = null;
+    _iceGraceReason = null;
+    _pendingVisibilityHandler = null;
+    _onlineHandler = null;
+    _offlineHandler = null;
+    _connectionChangeHandler = null;
     // ─── Motion completion plumbing (wake_up / goto_sleep) ───────────────
     _pendingMotionCompletions = {
         wake_up: [],
@@ -418,6 +464,9 @@ export class ReachyMini extends EventTarget {
         this._pc = new RTCPeerConnection({
             iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
         });
+        // Scope `networkOnline` / `networkOffline` / `networkChange`
+        // event forwarding to the lifetime of this session.
+        this._installNetworkListeners();
         return new Promise((resolve, reject) => {
             this._sessionResolve = resolve;
             this._sessionReject = reject;
@@ -454,21 +503,38 @@ export class ReachyMini extends EventTarget {
                 const s = this._pc?.iceConnectionState;
                 if (!s)
                     return;
+                // Public, granular event: every transition is visible to
+                // consumers so they can render finer UX (e.g. a transient
+                // "Reconnecting…" badge during `disconnected`) without
+                // having to attach their own handler to `_pc`.
+                this._emit('iceStateChange', { state: s });
                 if (s === 'connected' || s === 'completed') {
+                    // Healed — cancel any pending grace from a previous blip.
+                    this._clearIceGrace();
                     this._iceConnected = true;
                     this._checkSessionReady();
+                    return;
                 }
-                else if (s === 'failed') {
-                    const err = new Error('ICE connection failed');
-                    if (this._sessionReject) {
-                        this._sessionReject(err);
-                        this._sessionResolve = null;
-                        this._sessionReject = null;
+                if (s === 'disconnected') {
+                    // TRANSIENT per spec — debounce before escalating.
+                    // If the tab is hidden, JS timers are throttled and
+                    // would fire unpredictably late, so defer the grace
+                    // window to the next foreground frame.
+                    if (typeof document !== 'undefined' && document.hidden) {
+                        this._armIceGraceOnVisibility();
+                    }
+                    else {
+                        this._scheduleIceGrace(ICE_DISCONNECT_GRACE_MS, 'disconnected');
                     }
-                    this._emit('error', { source: 'webrtc', error: err });
+                    return;
                 }
-                else if (s === 'disconnected') {
-                    this._emit('error', { source: 'webrtc', error: new Error('ICE disconnected') });
+                if (s === 'failed') {
+                    // Terminal per spec, but in practice we've seen
+                    // `failed → connected` on rapid AP roams / BT route
+                    // changes on iOS. Give the ICE agent a short window
+                    // to surprise us before rejecting the session.
+                    this._scheduleIceGrace(ICE_FAILED_GRACE_MS, 'failed');
+                    return;
                 }
             };
             this._pc.ondatachannel = (e) => {
@@ -495,6 +561,10 @@ export class ReachyMini extends EventTarget {
             : `Session rejected: ${msg.reason || 'unknown reason'}`);
         err.reason = msg.reason ?? null;
         err.activeApp = msg.activeApp ?? null;
+        // Resilience teardown BEFORE closing `_pc` so a queued grace
+        // callback can't dereference a dead handle.
+        this._clearIceGrace();
+        this._uninstallNetworkListeners();
         if (this._pc) {
             this._pc.close();
             this._pc = null;
@@ -542,6 +612,10 @@ export class ReachyMini extends EventTarget {
         }
         this._logSubscribers.clear();
         this._rejectPendingMotionCompletions(new Error('Session stopped'));
+        // Tear down resilience plumbing BEFORE closing `_pc` so a
+        // queued grace callback can't dereference a dead handle.
+        this._clearIceGrace();
+        this._uninstallNetworkListeners();
         if (this._sessionReject) {
             this._sessionReject(new Error('Session stopped'));
             this._sessionResolve = null;
@@ -612,6 +686,9 @@ export class ReachyMini extends EventTarget {
         }
         this._logSubscribers.clear();
         this._rejectPendingMotionCompletions(new Error('Disconnected'));
+        // Mirrors the resilience teardown in `stopSession()`.
+        this._clearIceGrace();
+        this._uninstallNetworkListeners();
         if (this._sessionReject) {
             this._sessionReject(new Error('Disconnected'));
             this._sessionResolve = null;
@@ -649,7 +726,229 @@ export class ReachyMini extends EventTarget {
         this._state = 'disconnected';
         this._emit('disconnected', { reason: 'user' });
     }
+    // ─── Resilience: ICE-blip debounce + network awareness ───────────────
+    //
+    // Both halves below are intentionally generic (they don't know about
+    // motion, audio, or the FSM): they just smooth out browser-level
+    // events so the consumer's own state machine doesn't get torn down
+    // by routine WiFi/4G/screen-off noise.
+    /**
+     * Cancel any pending ICE grace timer and visibility handler. Called
+     * on a healed `connected`/`completed` transition AND from the
+     * lifecycle teardown paths so a callback can't fire after `_pc`
+     * is closed.
+     */
+    _clearIceGrace() {
+        if (this._iceGraceTimer !== null) {
+            clearTimeout(this._iceGraceTimer);
+            this._iceGraceTimer = null;
+        }
+        this._iceGraceReason = null;
+        if (this._pendingVisibilityHandler && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this._pendingVisibilityHandler);
+        }
+        this._pendingVisibilityHandler = null;
+    }
+    /**
+     * Start a grace window. After `ms`, re-check the live ICE state:
+     *   - If we healed back to `connected`/`completed`, the timer was
+     *     already cancelled in `oniceconnectionstatechange`, so we
+     *     never get here.
+     *   - If we're still in the originally-observed bad state (or
+     *     worse), surface the error and reject any pending session
+     *     promise. The original code path is preserved verbatim so
+     *     downstream consumers see the same `error` payload shape.
+     */
+    _scheduleIceGrace(ms, reason) {
+        // Coalesce: if a grace is already pending and the reason hasn't
+        // changed, keep the original timer so a flurry of identical
+        // transitions doesn't reset the clock. If the reason changed
+        // (typically `disconnected` → `failed`, but also the reverse on
+        // some Android WebViews), replace the timer with the new
+        // (reason, ms) pair — the latest signal wins.
+        if (this._iceGraceTimer !== null) {
+            if (this._iceGraceReason === reason)
+                return;
+            clearTimeout(this._iceGraceTimer);
+        }
+        this._iceGraceReason = reason;
+        this._iceGraceTimer = setTimeout(() => {
+            this._iceGraceTimer = null;
+            const r = this._iceGraceReason;
+            this._iceGraceReason = null;
+            const s = this._pc?.iceConnectionState;
+            if (s === 'connected' || s === 'completed')
+                return; // healed
+            if (r === 'disconnected' && s === 'disconnected') {
+                this._emit('error', {
+                    source: 'webrtc',
+                    error: new Error(`ICE stuck in 'disconnected' for > ${ms}ms`),
+                });
+                return;
+            }
+            if (r === 'failed' || s === 'failed') {
+                const err = new Error('ICE connection failed');
+                if (this._sessionReject) {
+                    this._sessionReject(err);
+                    this._sessionResolve = null;
+                    this._sessionReject = null;
+                }
+                this._emit('error', { source: 'webrtc', error: err });
+            }
+        }, ms);
+    }
+    /**
+     * `disconnected` while the tab is hidden. JS timers are throttled
+     * in background tabs (Chrome clamps to ~1 Hz, Safari can pause
+     * altogether), so a foreground grace timer would either miss the
+     * window or fire long after the connection healed. Wait for the
+     * tab to come back, then re-evaluate.
+     */
+    _armIceGraceOnVisibility() {
+        if (this._pendingVisibilityHandler)
+            return;
+        const deferredAt = Date.now();
+        const handler = () => {
+            if (typeof document !== 'undefined' && document.hidden)
+                return;
+            document.removeEventListener('visibilitychange', handler);
+            this._pendingVisibilityHandler = null;
+            if (!this._pc)
+                return;
+            const s = this._pc.iceConnectionState;
+            if (s === 'connected' || s === 'completed')
+                return; // healed in bg
+            // Ceiling: if the user backgrounded past the daemon's
+            // ICE-consent freshness window the session is gone from
+            // the daemon's side regardless of what `_pc` reports
+            // locally. Running another foreground grace would tell
+            // the user "Reconnecting…" for a recovery that can never
+            // happen. Escalate immediately so the host renders the
+            // real "session expired" UX. See MAX_VISIBILITY_DEFER_MS.
+            if (Date.now() - deferredAt > MAX_VISIBILITY_DEFER_MS) {
+                const err = new Error('Session expired while tab was backgrounded');
+                if (this._sessionReject) {
+                    this._sessionReject(err);
+                    this._sessionResolve = null;
+                    this._sessionReject = null;
+                }
+                this._emit('error', { source: 'webrtc', error: err });
+                return;
+            }
+            if (s === 'failed') {
+                this._scheduleIceGrace(ICE_FAILED_GRACE_MS, 'failed');
+                return;
+            }
+            // Still disconnected when we came back — give it a normal
+            // foreground grace window now that timers fire reliably.
+            this._scheduleIceGrace(ICE_DISCONNECT_GRACE_MS, 'disconnected');
+        };
+        document.addEventListener('visibilitychange', handler);
+        this._pendingVisibilityHandler = handler;
+    }
+    /**
+     * Install browser-level network listeners and forward them as
+     * public `networkOnline` / `networkOffline` / `networkChange`
+     * events on this instance. Idempotent: called from
+     * `startSession()`, removed by `_uninstallNetworkListeners` on
+     * teardown. Reachable only when there's a live `window`
+     * (defensive guard for SSR / test environments).
+     *
+     * `online` / `offline` are semantically about CONNECTIVITY:
+     * "does the OS think we can reach the internet". They flip
+     * symmetrically.
+     *
+     * `connection.change` (NetworkInformation API, Chrome / Android
+     * WebView only) is semantically about the TRANSPORT: it fires
+     * on Wi-Fi → 4G swaps, AP roams, etc. without necessarily going
+     * through `offline`. We forward it as its own `networkChange`
+     * event rather than aliasing it onto `networkOnline`, so
+     * consumers don't have to guess whether they're seeing a real
+     * connectivity recovery or a silent transport swap.
+     */
+    _installNetworkListeners() {
+        if (this._onlineHandler || typeof window === 'undefined')
+            return;
+        const onOnline = () => this._emit('networkOnline', {});
+        const onOffline = () => this._emit('networkOffline', {});
+        window.addEventListener('online', onOnline);
+        window.addEventListener('offline', onOffline);
+        this._onlineHandler = onOnline;
+        this._offlineHandler = onOffline;
+        const conn = navigator.connection;
+        if (conn && typeof conn.addEventListener === 'function') {
+            const onChange = () => this._emit('networkChange', {
+                effectiveType: conn.effectiveType,
+                downlink: conn.downlink,
+                rtt: conn.rtt,
+                saveData: conn.saveData,
+            });
+            conn.addEventListener('change', onChange);
+            this._connectionChangeHandler = onChange;
+        }
+    }
+    /** Counterpart to `_installNetworkListeners`. */
+    _uninstallNetworkListeners() {
+        if (typeof window !== 'undefined') {
+            if (this._onlineHandler) {
+                window.removeEventListener('online', this._onlineHandler);
+            }
+            if (this._offlineHandler) {
+                window.removeEventListener('offline', this._offlineHandler);
+            }
+        }
+        const conn = navigator.connection;
+        if (conn && this._connectionChangeHandler && typeof conn.removeEventListener === 'function') {
+            conn.removeEventListener('change', this._connectionChangeHandler);
+        }
+        this._onlineHandler = null;
+        this._offlineHandler = null;
+        this._connectionChangeHandler = null;
+    }
     // ─── Commands ────────────────────────────────────────────────────────
+    /**
+     * Atomic raw-units pose update over the data channel. Channels you
+     * omit are held at their last commanded value (per-axis, independent).
+     *
+     * **Head pose is in the WORLD frame.** The daemon's IK splits the
+     * requested head world-yaw between body rotation and the stewart
+     * platform, subject to the mechanical limit
+     * `|head_yaw_world − body_yaw| ≤ 65°`.
+     *
+     * **If you want the head to FOLLOW the body** (tank-style rotation):
+     * a `setTarget({ body_yaw })` on its own does NOT rotate the head —
+     * the head's commanded world yaw is unchanged, so its gaze stays
+     * pinned in world frame while the body turns under it. To make the
+     * head turn with the body, include a `head` matrix in the SAME call
+     * with the body-yaw delta added to the head RPY's yaw:
+     *
+     * ```ts
+     * // Body-yaw drag handler: tank-couple the head so it follows.
+     * const delta = newBodyDeg - lastCommandedBodyDeg;
+     * const nextHeadYaw = lastCommandedHeadYawDeg + delta;
+     * robot.setTarget({
+     *   head: rpyToMatrix(headRoll, headPitch, nextHeadYaw).flat(),
+     *   body_yaw: degToRad(newBodyDeg),
+     * });
+     * lastCommandedHeadYawDeg = nextHeadYaw;
+     * lastCommandedBodyDeg    = newBodyDeg;
+     * ```
+     *
+     * **Baseline must be the last COMMANDED value, not telemetry.** For
+     * continuous-input controllers (slider drag, joystick), do not use
+     * `state.head` from the `state` event as the baseline for incremental
+     * commands — telemetry lags one WebRTC round-trip, so cumulative
+     * deltas computed against it stall (every iteration in a rapid drag
+     * adds the same `delta` to the same stale baseline → the head fails
+     * to keep up). Track the last-commanded RPY in your own buffer.
+     *
+     * @param head      Flat row-major 4×4 matrix (16 finite numbers) in
+     *                  the world frame. Omit to hold the previous head target.
+     * @param antennas  `[rightRad, leftRad]` (radians). Omit to hold.
+     * @param body_yaw  Signed radians. Omit to hold.
+     * @returns `true` if the command was queued on the data channel,
+     *          `false` if the channel is not open.
+     */
     setTarget({ head, antennas, body_yaw } = {}) {
         const cmd = { type: 'set_full_target' };
         if (head !== undefined) {
@@ -718,6 +1017,9 @@ export class ReachyMini extends EventTarget {
     playSound(file) {
         return this._sendCommand({ type: 'play_sound', file });
     }
+    clearIncomingAudio() {
+        return this._sendCommand({ type: 'clear_incoming_audio' });
+    }
     setMotorMode(mode) {
         return this._sendCommand({ type: 'set_motor_mode', mode });
     }
@@ -1232,6 +1534,9 @@ export class ReachyMini extends EventTarget {
             const err = new Error(friendly || `Session ended before it could start: ${reason || 'unknown reason'}`);
             err.reason = reason ?? null;
             this._emit('sessionRejected', { reason, activeApp: null });
+            // Resilience teardown alongside the PC close path.
+            this._clearIceGrace();
+            this._uninstallNetworkListeners();
             if (this._pc) {
                 this._pc.close();
                 this._pc = null;