livekit-client 2.22.0 → 2.22.2

package/dist/livekit-client.esm.mjs

@@ -946,6 +946,9 @@ function _defineProperty(e, r, t) {
     writable: true
   }) : e[r] = t, e;
 }
+function _iterableToArray(r) {
+  if ("undefined" != typeof Symbol && null != r[Symbol.iterator] || null != r["@@iterator"]) return Array.from(r);
+}
 function _iterableToArrayLimit(r, l) {
   var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
   if (null != t) {
@@ -976,9 +979,53 @@ function _iterableToArrayLimit(r, l) {
 function _nonIterableRest() {
   throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
+function ownKeys(e, r) {
+  var t = Object.keys(e);
+  if (Object.getOwnPropertySymbols) {
+    var o = Object.getOwnPropertySymbols(e);
+    r && (o = o.filter(function (r) {
+      return Object.getOwnPropertyDescriptor(e, r).enumerable;
+    })), t.push.apply(t, o);
+  }
+  return t;
+}
+function _objectSpread2(e) {
+  for (var r = 1; r < arguments.length; r++) {
+    var t = null != arguments[r] ? arguments[r] : {};
+    r % 2 ? ownKeys(Object(t), true).forEach(function (r) {
+      _defineProperty(e, r, t[r]);
+    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
+      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
+    });
+  }
+  return e;
+}
+function _objectWithoutProperties(e, t) {
+  if (null == e) return {};
+  var o,
+    r,
+    i = _objectWithoutPropertiesLoose(e, t);
+  if (Object.getOwnPropertySymbols) {
+    var n = Object.getOwnPropertySymbols(e);
+    for (r = 0; r < n.length; r++) o = n[r], -1 === t.indexOf(o) && {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]);
+  }
+  return i;
+}
+function _objectWithoutPropertiesLoose(r, e) {
+  if (null == r) return {};
+  var t = {};
+  for (var n in r) if ({}.hasOwnProperty.call(r, n)) {
+    if (-1 !== e.indexOf(n)) continue;
+    t[n] = r[n];
+  }
+  return t;
+}
 function _slicedToArray(r, e) {
   return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest();
 }
+function _toArray(r) {
+  return _arrayWithHoles(r) || _iterableToArray(r) || _unsupportedIterableToArray(r) || _nonIterableRest();
+}
 function _toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -8505,6 +8552,7 @@ var LoggerNames;
   LoggerNames["DataTracks"] = "livekit-data-tracks";
   LoggerNames["Region"] = "livekit-region";
   LoggerNames["ICE"] = "livekit-ice";
+  LoggerNames["Stats"] = "livekit-stats";
 })(LoggerNames || (LoggerNames = {}));
 let livekitLogger = loglevelExports.getLogger(LoggerNames.Default);
 const livekitLoggers = Object.values(LoggerNames).map(name => loglevelExports.getLogger(name));
@@ -12160,7 +12208,7 @@ function getMatch(exp, ua) {
 }
 function getOSVersion(ua) {
   return ua.includes('mac os') ? getMatch(/\(.+?(\d+_\d+(:?_\d+)?)/, ua, 1).replace(/_/g, '.') : undefined;
-}var version$1 = "2.22.0";const version = version$1;
+}var version$1 = "2.22.2";const version = version$1;
 const protocolVersion = 17;
 /** Initial client protocol. */
 const CLIENT_PROTOCOL_DEFAULT = 0;
@@ -12446,7 +12494,7 @@ var RoomEvent;
    * When a [[RemoteParticipant]] leaves *after* the local
    * participant has joined.
    *
-   * args: ([[RemoteParticipant]])
+   * args: ([[RemoteParticipant]], [[DisconnectReason]] | undefined)
    */
   RoomEvent["ParticipantDisconnected"] = "participantDisconnected";
   /**
@@ -13014,7 +13062,171 @@ var TrackEvent;
    * @internal
    */
   TrackEvent["PreConnectBufferFlushed"] = "preConnectBufferFlushed";
-})(TrackEvent || (TrackEvent = {}));function cloneDeep(value) {
+})(TrackEvent || (TrackEvent = {}));function compact(summary) {
+  const compacted = {};
+  for (const _ref of Object.entries(summary)) {
+    var _ref2 = _slicedToArray(_ref, 2);
+    const key = _ref2[0];
+    const value = _ref2[1];
+    if (value !== undefined) {
+      compacted[key] = value;
+    }
+  }
+  return compacted;
+}
+function resolution(width, height) {
+  return width && height ? "".concat(width, "x").concat(height) : undefined;
+}
+/** keeps the derived durations readable; reported values are logged as they are */
+function round(seconds) {
+  return Math.round(seconds * 10000) / 10000;
+}
+/**
+ * Average time media spent in the jitter buffer, in s. Both counters are
+ * cumulative, so this is the average over the lifetime of the stream.
+ */
+function jitterBuffer(stat) {
+  const delay = stat.jitterBufferDelay;
+  const emitted = stat.jitterBufferEmittedCount;
+  return delay !== undefined && emitted ? round(delay / emitted) : undefined;
+}
+/**
+ * Playout delay in s. Video receive reports it directly, the audio path keeps it
+ * in the linked `media-playout` stats summed over the samples played out. Pairs
+ * with `RemoteTrack.setPlayoutDelay`.
+ */
+function playoutDelay(stat, playout) {
+  if (stat.playoutDelay !== undefined) {
+    return round(stat.playoutDelay);
+  }
+  const total = playout === null || playout === void 0 ? void 0 : playout.totalPlayoutDelay;
+  const samples = playout === null || playout === void 0 ? void 0 : playout.totalSamplesCount;
+  return total !== undefined && samples ? round(total / samples) : undefined;
+}
+/**
+ * Picks the interesting fields out of a `getStats()` report and groups them by
+ * RTP stream, so a stats dump can be read without unfolding the raw report.
+ */
+function summarizeStatsReport(report) {
+  var _a, _b;
+  const byId = new Map();
+  const candidatePairs = [];
+  const inbound = [];
+  const outbound = [];
+  let transport;
+  report.forEach(stat => byId.set(stat.id, stat));
+  const codecOf = stat => {
+    var _a;
+    return stat.codecId ? (_a = byId.get(stat.codecId)) === null || _a === void 0 ? void 0 : _a.mimeType : undefined;
+  };
+  const relatedOf = (stat, key) => stat[key] ? byId.get(stat[key]) : undefined;
+  report.forEach(stat => {
+    switch (stat.type) {
+      case 'inbound-rtp':
+        {
+          const playout = relatedOf(stat, 'playoutId');
+          inbound.push(compact({
+            kind: stat.kind,
+            ssrc: stat.ssrc,
+            mid: stat.mid,
+            // matches `streamTrackID` in the track's own log context
+            trackId: stat.trackIdentifier,
+            codec: codecOf(stat),
+            decoder: stat.decoderImplementation,
+            resolution: resolution(stat.frameWidth, stat.frameHeight),
+            fps: stat.framesPerSecond,
+            bytesReceived: stat.bytesReceived,
+            packetsReceived: stat.packetsReceived,
+            packetsLost: stat.packetsLost,
+            packetsDiscarded: stat.packetsDiscarded,
+            // frames received without frames decoded is a decode failure
+            framesReceived: stat.framesReceived,
+            framesDecoded: stat.framesDecoded,
+            framesDropped: stat.framesDropped,
+            keyFramesDecoded: stat.keyFramesDecoded,
+            freezeCount: stat.freezeCount,
+            totalFreezesDuration: stat.totalFreezesDuration,
+            pauseCount: stat.pauseCount,
+            nackCount: stat.nackCount,
+            pliCount: stat.pliCount,
+            firCount: stat.firCount,
+            jitter: stat.jitter,
+            jitterBuffer: jitterBuffer(stat),
+            playoutDelay: playoutDelay(stat, playout),
+            audioLevel: stat.audioLevel,
+            totalSamplesReceived: stat.totalSamplesReceived,
+            concealedSamples: stat.concealedSamples
+          }));
+          break;
+        }
+      case 'outbound-rtp':
+        {
+          const remote = relatedOf(stat, 'remoteId');
+          const source = relatedOf(stat, 'mediaSourceId');
+          outbound.push(compact({
+            kind: stat.kind,
+            ssrc: stat.ssrc,
+            mid: stat.mid,
+            rid: stat.rid,
+            trackId: source === null || source === void 0 ? void 0 : source.trackIdentifier,
+            active: stat.active,
+            codec: codecOf(stat),
+            encoder: stat.encoderImplementation,
+            resolution: resolution(stat.frameWidth, stat.frameHeight),
+            fps: stat.framesPerSecond,
+            // what the source produces, to tell a stalled capture from a stalled encoder
+            captureResolution: resolution(source === null || source === void 0 ? void 0 : source.width, source === null || source === void 0 ? void 0 : source.height),
+            captureFps: source === null || source === void 0 ? void 0 : source.framesPerSecond,
+            audioLevel: source === null || source === void 0 ? void 0 : source.audioLevel,
+            targetBitrate: stat.targetBitrate,
+            bytesSent: stat.bytesSent,
+            packetsSent: stat.packetsSent,
+            retransmittedPacketsSent: stat.retransmittedPacketsSent,
+            framesEncoded: stat.framesEncoded,
+            keyFramesEncoded: stat.keyFramesEncoded,
+            limitedBy: stat.qualityLimitationReason === 'none' ? undefined : stat.qualityLimitationReason,
+            nackCount: stat.nackCount,
+            pliCount: stat.pliCount,
+            firCount: stat.firCount,
+            // loss, jitter and RTT are only known from what the remote reports
+            remotePacketsLost: remote === null || remote === void 0 ? void 0 : remote.packetsLost,
+            remoteFractionLost: remote === null || remote === void 0 ? void 0 : remote.fractionLost,
+            remoteJitter: remote === null || remote === void 0 ? void 0 : remote.jitter,
+            remoteRoundTripTime: remote === null || remote === void 0 ? void 0 : remote.roundTripTime
+          }));
+          break;
+        }
+      case 'transport':
+        transport = stat;
+        break;
+      case 'candidate-pair':
+        candidatePairs.push(stat);
+        break;
+    }
+  });
+  const selectedPairId = transport === null || transport === void 0 ? void 0 : transport.selectedCandidatePairId;
+  const pair = (_b = (_a = selectedPairId ? byId.get(selectedPairId) : undefined) !== null && _a !== void 0 ? _a : candidatePairs.find(candidate => candidate.selected)) !== null && _b !== void 0 ? _b : candidatePairs.find(candidate => candidate.nominated);
+  const local = (pair === null || pair === void 0 ? void 0 : pair.localCandidateId) ? byId.get(pair.localCandidateId) : undefined;
+  const remote = (pair === null || pair === void 0 ? void 0 : pair.remoteCandidateId) ? byId.get(pair.remoteCandidateId) : undefined;
+  const connection = compact({
+    ice: transport === null || transport === void 0 ? void 0 : transport.iceState,
+    dtls: transport === null || transport === void 0 ? void 0 : transport.dtlsState,
+    route: local && remote ? "".concat(local.candidateType, "/").concat(local.protocol, " -> ").concat(remote.candidateType) : undefined,
+    network: local === null || local === void 0 ? void 0 : local.networkType,
+    currentRoundTripTime: pair === null || pair === void 0 ? void 0 : pair.currentRoundTripTime,
+    // the send bandwidth estimate; no RTP stream reports it
+    availableOutgoingBitrate: pair === null || pair === void 0 ? void 0 : pair.availableOutgoingBitrate,
+    availableIncomingBitrate: pair === null || pair === void 0 ? void 0 : pair.availableIncomingBitrate,
+    bytesSent: pair === null || pair === void 0 ? void 0 : pair.bytesSent,
+    bytesReceived: pair === null || pair === void 0 ? void 0 : pair.bytesReceived,
+    candidatePairChanges: transport === null || transport === void 0 ? void 0 : transport.selectedCandidatePairChanges
+  });
+  return {
+    connection: Object.keys(connection).length > 0 ? connection : undefined,
+    outbound: outbound.length > 0 ? outbound : undefined,
+    inbound: inbound.length > 0 ? inbound : undefined
+  };
+}function cloneDeep$1(value) {
   if (typeof value === 'undefined') {
     return value;
   }
@@ -13439,7 +13651,7 @@ function extractProcessorsFromOptions(options) {
   return {
     audioProcessor,
     videoProcessor,
-    optionsWithoutProcessor: cloneDeep(newOptions)
+    optionsWithoutProcessor: cloneDeep$1(newOptions)
   };
 }
 function getTrackSourceFromProto(source) {
@@ -13496,6 +13708,7 @@ class Track extends eventsExports.EventEmitter {
     this._streamState = Track.StreamState.Active;
     this.isInBackground = false;
     this._currentBitrate = 0;
+    this.finalStatsLogged = false;
     this.log = livekitLogger;
     this.appVisibilityChangedListener = () => {
       if (this.backgroundTimeout) {
@@ -13644,6 +13857,24 @@ class Track extends eventsExports.EventEmitter {
       cancelAnimationFrame(this.timeSyncHandle);
       this.timeSyncHandle = undefined;
     }
+    this.logFinalStats();
+  }
+  /**
+   * Dumps the raw stats of the track as it ends, once: a track that stops
+   * between two of the room's stats dumps is gone by the time the next one runs.
+   */
+  logFinalStats() {
+    if (this.finalStatsLogged) {
+      return;
+    }
+    this.finalStatsLogged = true;
+    this.getRTCStatsReport().then(report => {
+      if (report) {
+        this.log.info('final track stats', summarizeStatsReport(report));
+      }
+    }).catch(error => this.log.debug('could not collect final track stats', {
+      error
+    }));
   }
   /** @internal */
   updateLoggerOptions(loggerOptions) {
@@ -13869,7 +14100,7 @@ function supportsAddTrack() {
   return 'addTrack' in RTCPeerConnection.prototype;
 }
 function supportsAdaptiveStream() {
-  return typeof ResizeObserver !== undefined && typeof IntersectionObserver !== undefined;
+  return typeof ResizeObserver !== 'undefined' && typeof IntersectionObserver !== 'undefined';
 }
 function supportsDynacast() {
   return supportsTransceiver();
@@ -13927,6 +14158,22 @@ function supportsVP9() {
   }
   return hasVP9;
 }
+function supportsH265() {
+  if (!('getCapabilities' in RTCRtpSender)) {
+    return false;
+  }
+  const capabilities = RTCRtpSender.getCapabilities('video');
+  let hasH265 = false;
+  if (capabilities) {
+    for (const codec of capabilities.codecs) {
+      if (codec.mimeType.toLowerCase() === 'video/h265') {
+        hasH265 = true;
+        break;
+      }
+    }
+  }
+  return hasH265;
+}
 function isSVCCodec(codec) {
   return codec === 'av1' || codec === 'vp9';
 }
@@ -14560,6 +14807,11 @@ function parseSignalResponse(value) {
 }
 function getAbortReasonAsString(signal) {
   let defaultMessage = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'Unknown reason';
+  // the connect timeout hands this an Error rather than a signal, and its message is the only
+  // description of what went wrong — without this a timeout reports itself as a generic abort
+  if (signal instanceof Error) {
+    return signal.message;
+  }
   if (!(signal instanceof AbortSignal)) {
     return defaultMessage;
   }
@@ -14577,6 +14829,11 @@ function getAbortReasonAsString(signal) {
 const DECRYPTION_FAILURE_TOLERANCE = 10;
 // flag set to indicate that e2ee has been setup for sender/receiver;
 const E2EE_FLAG = 'lk_e2ee';
+/**
+ * trackId a receiver's/sender's encoded stream pipeline was last set up for.
+ * Needed to recover the right cryptor when a transceiver gets reused.
+ */
+const E2EE_TRACK_ID = 'lk_e2ee_track_id';
 const SALT = 'LKFrameEncryptionKey';
 const KEY_PROVIDER_DEFAULTS = {
   sharedKey: false,
@@ -15673,12 +15930,12 @@ class E2EEManager extends eventsExports.EventEmitter {
     });
   }
   setupEventListeners(room, keyProvider) {
-    room.on(RoomEvent.TrackPublished, (pub, participant) => this.setParticipantCryptorEnabled(pub.trackInfo.encryption !== Encryption_Type.NONE, participant.identity));
+    room.on(RoomEvent.TrackPublished, (pub, participant) => this.setParticipantCryptorEnabledForPublication(pub, participant.identity));
     room.on(RoomEvent.ConnectionStateChanged, state => {
       if (state === ConnectionState.Connected) {
         room.remoteParticipants.forEach(participant => {
           participant.trackPublications.forEach(pub => {
-            this.setParticipantCryptorEnabled(pub.trackInfo.encryption !== Encryption_Type.NONE, participant.identity);
+            this.setParticipantCryptorEnabledForPublication(pub, participant.identity);
           });
         });
       }
@@ -15848,6 +16105,22 @@ class E2EEManager extends eventsExports.EventEmitter {
     };
     this.worker.postMessage(msg);
   }
+  /**
+   * Derive the participant's encryption state from one of its publications.
+   * Publications without trackInfo are skipped rather than thrown on: throwing
+   * inside the forEach above would leave every remaining participant without an
+   * encryption state, and a cryptor with unknown state can no longer decrypt.
+   */
+  setParticipantCryptorEnabledForPublication(pub, participantIdentity) {
+    if (!pub.trackInfo) {
+      livekitLogger.warn('skipping e2ee enabled update for publication without trackInfo', {
+        participant: participantIdentity,
+        trackSid: pub.trackSid
+      });
+      return;
+    }
+    this.setParticipantCryptorEnabled(pub.trackInfo.encryption !== Encryption_Type.NONE, participantIdentity);
+  }
   setupE2EEReceiver(track, remoteId, trackInfo) {
     if (!track.receiver) {
       return;
@@ -15884,21 +16157,27 @@ class E2EEManager extends eventsExports.EventEmitter {
           codec,
           hasPacketTrailer
         };
-        // @ts-ignore
         receiver.transform = new RTCRtpScriptTransform(this.worker, options);
       } else {
-        if (E2EE_FLAG in receiver && codec) {
-          // update track-specific state when the transceiver is reused
+        if (E2EE_FLAG in receiver && E2EE_TRACK_ID in receiver) {
+          // The transceiver is being reused for a new track. We cannot set up a new
+          // pipeline from here: this receiver's encoded streams were transferred to
+          // the worker on first setup and a transferred stream can't be transferred
+          // again, while createEncodedStreams() may only be called once per receiver.
+          // So hand the worker the new track/participant and let it re-point (and if
+          // necessary rebuild) the cryptor that still owns those streams.
           const msg = {
             kind: 'updateCodec',
             data: {
               trackId,
+              previousTrackId: receiver[E2EE_TRACK_ID],
               codec,
               participantIdentity,
               hasPacketTrailer
             }
           };
           this.worker.postMessage(msg);
+          receiver[E2EE_TRACK_ID] = trackId;
           return;
         }
         // @ts-ignore
@@ -15923,7 +16202,6 @@ class E2EEManager extends eventsExports.EventEmitter {
             trackId: trackId,
             codec,
             participantIdentity: participantIdentity,
-            isReuse: E2EE_FLAG in receiver,
             hasPacketTrailer
           }
         };
@@ -15931,6 +16209,8 @@ class E2EEManager extends eventsExports.EventEmitter {
       }
       // @ts-ignore
       receiver[E2EE_FLAG] = true;
+      // @ts-ignore
+      receiver[E2EE_TRACK_ID] = trackId;
     });
   }
   /**
@@ -15970,7 +16250,6 @@ class E2EEManager extends eventsExports.EventEmitter {
           codec,
           trackId,
           participantIdentity: this.room.localParticipant.identity,
-          isReuse: false,
           hasPacketTrailer: hasFrameMetadataPublishOptions(frameMetadata),
           packetTrailer: frameMetadata
         }
@@ -16620,6 +16899,1140 @@ class AsyncQueue {
   snapshot() {
     return Array.from(this.pendingTasks.values());
   }
+}/**
+ * Opt-in registry that lets a development tool observe the state machines driving the connection
+ * layer.
+ *
+ * The machines are private to the objects that own them and, more importantly, do not outlive them:
+ * a full reconnect replaces the whole engine along with its `SignalClient`, so anything watching a
+ * single machine reference goes blind exactly when the interesting part starts. Machines therefore
+ * announce themselves here as they are constructed, and a subscriber sees the whole succession.
+ *
+ * Nothing is recorded until {@link enableMachineInspector} is called, which no shipping code does —
+ * with the registry off, announcing is a comparison and a return.
+ */
+/** Kept small: enough for a panel opened mid-session to see how the connection got where it is. */
+/** Announces a machine to whatever is watching. A no-op unless the inspector was enabled. */
+function announceMachine(label, machine) {
+  {
+    return;
+  }
+}const _excluded = ["client"];
+//#region src/emitter.ts
+/**
+* Minimal typed event emitter used internally by Fsm and BehavioralFsm.
+*
+* Two listener categories exist at runtime: named listeners (keyed by event
+* name) and wildcard listeners (keyed as `"*"`). The wildcard fires on EVERY
+* emit, regardless of event name, and its callback receives both the event
+* name and the data. Named listeners receive only the data.
+*
+* @typeParam TEventMap - Record mapping event names to their payload types.
+*   Constrains `on()` and `emit()` to matching event/payload pairs.
+*/
+var Emitter = class Emitter {
+  constructor() {
+    _defineProperty(this, "listeners", /* @__PURE__ */new Map());
+  }
+  on(event, cb) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(cb);
+    return {
+      off: () => {
+        set.delete(cb);
+      }
+    };
+  }
+  /**
+  * Emit a named event, notifying wildcard listeners first, then named listeners.
+  *
+  * Wildcard listeners receive `(eventName, data)`; named listeners receive
+  * only `data`. The firing order (wildcards before named) is intentional —
+  * it lets relay listeners (like Fsm's bfsm proxy) observe all events
+  * before specific subscribers react.
+  */
+  emit(event, data) {
+    const wildcards = this.listeners.get("*");
+    if (wildcards) for (const cb of wildcards) cb(event, data);
+    const named = this.listeners.get(event);
+    if (named) for (const cb of named) cb(data);
+  }
+  /**
+  * Remove all listeners (named and wildcard).
+  *
+  * Existing `Subscription` objects remain valid — their `off()` closures
+  * hold a reference to the now-empty Set, so calling them is harmless.
+  * Called by `dispose()` to prevent memory retention after an FSM shuts down.
+  */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+//#endregion
+//#region src/json-safe.ts
+/**
+* Thrown internally when the walk hits a value that can't survive a
+* serialization boundary. Callers catch this to attach FSM/input context
+* before re-throwing a fully descriptive error — see `path`/`label` below.
+*/
+var NonSerializableValueError = class extends Error {
+  constructor(path, label) {
+    super("non-serializable value at ".concat(path, " (").concat(label, ")"));
+    this.path = path;
+    this.label = label;
+  }
+};
+/**
+* Deep-clones `value`, throwing `NonSerializableValueError` the moment it
+* finds anything that isn't `null`, a boolean, a finite number, a string, a
+* plain array, or a plain object. `rootPath` seeds the path used in error
+* messages — e.g. `"args"` so a nested failure reads as `args[1].onComplete`.
+*
+* Cloning (rather than just validating) is what keeps a returned snapshot
+* from aliasing live FSM state: mutating the snapshot afterward — or the
+* original value passed into a deferred `handle()` call — can't reach back
+* into the FSM's internal deferred queue.
+*/
+const cloneJsonSafe = (value, rootPath) => {
+  return cloneNode(value, rootPath, /* @__PURE__ */new Set());
+};
+const cloneNode = (value, path, ancestors) => {
+  if (value === null) return null;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return value;
+    case "number":
+      if (!Number.isFinite(value)) throw new NonSerializableValueError(path, describeNonFiniteNumber(value));
+      return value;
+    case "object":
+      return cloneObject(value, path, ancestors);
+    default:
+      throw new NonSerializableValueError(path, typeof value);
+  }
+};
+const cloneObject = (obj, path, ancestors) => {
+  var _obj$constructor$name, _obj$constructor;
+  if (ancestors.has(obj)) throw new NonSerializableValueError(path, "circular reference");
+  if (Array.isArray(obj)) {
+    if (obj.length !== Object.keys(obj).length) throw new NonSerializableValueError(path, "sparse array or array with non-index properties");
+    ancestors.add(obj);
+    const cloned = obj.map((item, i) => cloneNode(item, "".concat(path, "[").concat(i, "]"), ancestors));
+    ancestors.delete(obj);
+    return cloned;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null) throw new NonSerializableValueError(path, (_obj$constructor$name = (_obj$constructor = obj.constructor) === null || _obj$constructor === void 0 ? void 0 : _obj$constructor.name) !== null && _obj$constructor$name !== void 0 ? _obj$constructor$name : "object");
+  ancestors.add(obj);
+  const cloned = {};
+  for (const key of Object.keys(obj)) {
+    const value = cloneNode(obj[key], "".concat(path, ".").concat(key), ancestors);
+    Object.defineProperty(cloned, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+  ancestors.delete(obj);
+  return cloned;
+};
+const describeNonFiniteNumber = n => {
+  if (Number.isNaN(n)) return "NaN";
+  return n > 0 ? "Infinity" : "-Infinity";
+};
+/**
+* Deep-clones `value` WITHOUT validating it — unlike `cloneJsonSafe`, this
+* never throws. Plain objects/arrays are cloned recursively (so a caller
+* can't alias state back into whatever holds the result); anything else
+* (functions, `Date`/`Map`/class instances, symbols, non-finite numbers,
+* etc.) is passed through by reference as-is.
+*
+* This is `rehydrate()`'s side of the aliasing guarantee: `dehydrate()`
+* validates-and-clones on the way OUT (via `cloneJsonSafe`), but `rehydrate()`
+* trusts the snapshot it's given is already valid data — re-validating on
+* the way IN would be a redundant, unwanted asymmetry (see the build plan's
+* disclosed known gaps). We still need the clone so mutating the caller's
+* snapshot object after `rehydrate()` returns can't reach into the live
+* FSM's internal deferred queue.
+*
+* Cycle-safe: a value that contains itself is returned as-is (by reference)
+* rather than cloned infinitely — there's no validation step here to make
+* that throw, so silently keeping the shared reference is the only option
+* that doesn't hang.
+*/
+const cloneDeep = function (value) {
+  let ancestors = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : /* @__PURE__ */new Set();
+  if (value === null || typeof value !== "object") return value;
+  if (ancestors.has(value)) return value;
+  if (Array.isArray(value)) {
+    ancestors.add(value);
+    const cloned = value.map(item => cloneDeep(item, ancestors));
+    ancestors.delete(value);
+    return cloned;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  ancestors.add(value);
+  const cloned = {};
+  for (const key of Object.keys(value)) {
+    const clonedValue = cloneDeep(value[key], ancestors);
+    Object.defineProperty(cloned, key, {
+      value: clonedValue,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+  ancestors.delete(value);
+  return cloned;
+};
+
+//#endregion
+//#region src/types.ts
+/**
+* Symbol used as a property key to identify machina FSM instances at runtime.
+* Each class stamps itself with a MachinaType value so the ChildLink adapter
+* can dispatch handle()/canHandle()/reset() correctly without circular imports.
+*/
+const MACHINA_TYPE = Symbol("machina.type");
+
+//#endregion
+//#region src/behavioral-fsm.ts
+const MAX_TRANSITION_DEPTH = 20;
+/**
+* Defines FSM behavior (states + transitions) while tracking per-client state
+* in a `WeakMap`. A single `BehavioralFsm` instance can drive any number of
+* independent client objects simultaneously — each gets its own state,
+* deferred queue, and lifecycle.
+*
+* Prefer `createBehavioralFsm()` over constructing this directly — the factory
+* infers all generic parameters from the config object.
+*
+* All public methods silently no-op after `dispose()` is called.
+*
+* @typeParam TClient - The client object type. Must be an object (non-primitive)
+*   so it can serve as a WeakMap key.
+* @typeParam TStateNames - String literal union of valid state names.
+* @typeParam TInputNames - String literal union of valid input names.
+* @typeParam TBubbles - String literal union of inputs this FSM declares via
+*   `bubbles`. Type-only — carried so `BubblesOfInstance` can extract it from
+*   a constructed instance; nothing at runtime reads this generic.
+*/
+var BehavioralFsm = class BehavioralFsm {
+  constructor(config) {
+    _defineProperty(this, "id", void 0);
+    _defineProperty(this, "initialState", void 0);
+    _defineProperty(this, MACHINA_TYPE, "BehavioralFsm");
+    _defineProperty(this, "states", void 0);
+    _defineProperty(this, "emitter", new Emitter());
+    _defineProperty(this, "clients", /* @__PURE__ */new WeakMap());
+    _defineProperty(this, "knownClients", /* @__PURE__ */new Set());
+    _defineProperty(this, "childSubscriptions", []);
+    _defineProperty(this, "disposed", false);
+    _defineProperty(this, "transitionDepth", 0);
+    this.id = config.id;
+    this.initialState = config.initialState;
+    this.states = config.states;
+    this.wrapChildLinks();
+    this.setupChildSubscriptions();
+  }
+  /**
+  * Dispatch an input to the given client's current state handler.
+  *
+  * Delegation order: if the current state has a `_child` FSM that can
+  * handle the input, it is dispatched there. If the child emits `nohandler`,
+  * the input bubbles up to this FSM's local handler. If no handler exists
+  * here either, `nohandler` is emitted on this FSM's emitter.
+  *
+  * No-ops silently when disposed.
+  */
+  handle(client, inputName) {
+    var _this$states$meta$sta;
+    if (this.disposed) return;
+    const meta = this.getOrCreateClientMeta(client);
+    for (var _len = arguments.length, args = new Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
+      args[_key - 2] = arguments[_key];
+    }
+    meta.currentActionArgs = args;
+    const childLink = (_this$states$meta$sta = this.states[meta.state]) === null || _this$states$meta$sta === void 0 ? void 0 : _this$states$meta$sta._child;
+    if (childLink) {
+      if (childLink.canHandle(client, inputName)) {
+        try {
+          childLink.handle(client, inputName, ...args);
+        } finally {
+          meta.currentActionArgs = void 0;
+        }
+        return;
+      }
+    }
+    this.handleLocally(client, inputName, args, meta);
+  }
+  /**
+  * Returns true if the client's current state has a handler for `inputName`
+  * (or a catch-all `"*"` handler), or if the current state's `_child` chain
+  * can handle it — the check recurses to the same depth `handle()`'s
+  * delegation can actually reach, so a grandchild-only input answers true
+  * from the root. Does NOT initialize the client — no `_onEnter`, no
+  * events, no side effects. Unseen clients are treated as if they were
+  * already in `initialState`. Returns false when disposed.
+  */
+  canHandle(client, inputName) {
+    var _this$clients$get$sta, _this$clients$get, _stateObj$inputName;
+    if (this.disposed) return false;
+    const state = (_this$clients$get$sta = (_this$clients$get = this.clients.get(client)) === null || _this$clients$get === void 0 ? void 0 : _this$clients$get.state) !== null && _this$clients$get$sta !== void 0 ? _this$clients$get$sta : this.initialState;
+    const stateObj = this.states[state];
+    if ((_stateObj$inputName = stateObj === null || stateObj === void 0 ? void 0 : stateObj[inputName]) !== null && _stateObj$inputName !== void 0 ? _stateObj$inputName : stateObj === null || stateObj === void 0 ? void 0 : stateObj["*"]) return true;
+    const childLink = stateObj === null || stateObj === void 0 ? void 0 : stateObj._child;
+    return childLink ? childLink.canHandle(client, inputName) : false;
+  }
+  /**
+  * Transition the client back to `initialState`, firing `_onEnter` and
+  * lifecycle events as if entering it fresh. No-ops when disposed.
+  */
+  reset(client) {
+    if (this.disposed) return;
+    this.transition(client, this.initialState);
+  }
+  /**
+  * Returns the client's current state, or `undefined` if the client has
+  * never been initialized (i.e. `handle()`, `transition()`, or `reset()`
+  * have never been called for it). Does NOT trigger initialization.
+  */
+  currentState(client) {
+    var _this$clients$get2;
+    return (_this$clients$get2 = this.clients.get(client)) === null || _this$clients$get2 === void 0 ? void 0 : _this$clients$get2.state;
+  }
+  /**
+  * Directly transition `client` to `toState`, running the full lifecycle:
+  * `_onExit` for the current state → `transitioning` event → update state →
+  * `_onEnter` for new state → `transitioned` event → child reset → deferred
+  * queue replay → bounce (if `_onEnter` returned a state name).
+  *
+  * Same-state transitions are silently ignored. Transitions to unknown state
+  * names emit `invalidstate` instead of throwing. Throws if the transition
+  * depth exceeds `MAX_TRANSITION_DEPTH` (likely an `_onEnter` → transition loop).
+  *
+  * No-ops when disposed.
+  */
+  transition(client, toState) {
+    if (this.disposed) return;
+    const meta = this.getOrCreateClientMeta(client);
+    const fromState = meta.state;
+    if (toState === fromState) return;
+    if (!Object.hasOwn(this.states, toState)) {
+      this.emitter.emit("invalidstate", {
+        stateName: toState,
+        client
+      });
+      return;
+    }
+    this.transitionDepth++;
+    if (this.transitionDepth > MAX_TRANSITION_DEPTH) {
+      this.transitionDepth = 0;
+      throw new Error("Max transition depth (".concat(MAX_TRANSITION_DEPTH, ") exceeded in FSM \"").concat(this.id, "\". Likely an infinite _onEnter \u2192 transition loop."));
+    }
+    try {
+      const curStateObj = this.states[fromState];
+      const newStateObj = this.states[toState];
+      if (curStateObj !== null && curStateObj !== void 0 && curStateObj._onExit && typeof curStateObj._onExit === "function") {
+        const exitArgs = this.buildHandlerArgs(client, "", meta);
+        curStateObj._onExit(exitArgs);
+      }
+      meta.state = toState;
+      const payload = {
+        fromState,
+        toState,
+        client
+      };
+      this.emitter.emit("transitioning", payload);
+      let bounceTarget = void 0;
+      if (newStateObj !== null && newStateObj !== void 0 && newStateObj._onEnter && typeof newStateObj._onEnter === "function") {
+        const enterArgs = this.buildHandlerArgs(client, "", meta);
+        bounceTarget = newStateObj._onEnter(enterArgs);
+      }
+      this.emitter.emit("transitioned", payload);
+      const childLink = newStateObj === null || newStateObj === void 0 ? void 0 : newStateObj._child;
+      if (childLink) childLink.reset(client);
+      this.processQueue(client, meta);
+      if (typeof bounceTarget === "string" && meta.state === toState) this.transition(client, bounceTarget);
+    } finally {
+      this.transitionDepth--;
+    }
+  }
+  /**
+  * Returns the client's state as a dot-delimited path including any active
+  * child FSM states (e.g. `"active.connecting.retrying"`). Returns just the
+  * current state name when no child is active. Returns `""` for clients that
+  * have never been initialized (unlike `currentState()` which returns `undefined`).
+  */
+  compositeState(client) {
+    var _this$states$meta$sta2;
+    const meta = this.clients.get(client);
+    if (!meta) return "";
+    const childLink = (_this$states$meta$sta2 = this.states[meta.state]) === null || _this$states$meta$sta2 === void 0 ? void 0 : _this$states$meta$sta2._child;
+    if (childLink) {
+      const childComposite = childLink.compositeState(client);
+      if (childComposite) return "".concat(meta.state, ".").concat(childComposite);
+    }
+    return meta.state;
+  }
+  rehydrate(client, input) {
+    if (this.disposed) return;
+    if (typeof input === "string") {
+      this.rehydrateCompositePath(client, input);
+      return;
+    }
+    const writes = this.planSnapshotWrites(client, input);
+    for (const write of writes) write();
+  }
+  /**
+  * Snapshot everything machina tracks for `client`: current state, pending
+  * deferred inputs, and — recursively — the same for every `_child` that has
+  * ever seen this client, active or not. Feed the result to the object form
+  * of `rehydrate()` to restore it later, deferrals included.
+  *
+  * Returns `undefined` for a client this FSM has never seen (mirrors
+  * `currentState()`) — the call does NOT trigger initialization.
+  *
+  * Throws if any deferred input's args contain a non-serializable value
+  * (function, undefined, symbol, bigint, non-finite number, Date/Map/class
+  * instance, or a circular reference) — naming the input, its `until` target
+  * if any, the FSM id, and the exact value path. Throws for an Fsm child
+  * that's on `client`'s active path *relative to the true root* (consistent
+  * with `rehydrate()`'s conditional throw) — an Fsm owns its own context, so
+  * there's nothing per-client to snapshot. An Fsm child declared at a state
+  * `client` never visited, OR nested under a `BehavioralFsm` child that is
+  * itself off-path from the root, is skipped rather than throwing — neither
+  * has any per-client state to lose, so one Fsm child anywhere in the
+  * hierarchy doesn't disable `dehydrate()` for clients that never reach that
+  * branch, no matter how deeply nested the Fsm child is.
+  *
+  * Meant for clients at rest between `handle()` calls — `currentActionArgs`
+  * (the in-flight args mid-handler) has no meaning here and is excluded.
+  *
+  * @param isOnActivePath - @internal Whether this FSM itself is currently
+  * reachable from the true root's active path. Defaults to `true` for the
+  * public entry point (this FSM IS the root from its own perspective); the
+  * `ChildLink` adapter passes `false` down when recursing into a nested
+  * `BehavioralFsm` child that is itself off-path, so that child's own
+  * Fsm-child checks don't recompute reachability from its dormant local
+  * state alone.
+  */
+  dehydrate(client) {
+    let isOnActivePath = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : true;
+    const meta = this.clients.get(client);
+    if (!meta) return;
+    const snapshot = {
+      state: meta.state,
+      deferred: meta.deferredQueue.map(item => this.snapshotDeferredInput(item))
+    };
+    const children = this.collectChildSnapshots(client, meta.state, isOnActivePath);
+    if (children) snapshot.children = children;
+    return snapshot;
+  }
+  /**
+  * @internal
+  * Validates `snapshot` against this level's state graph and recurses into
+  * every declared child, returning write thunks to run only once the WHOLE
+  * tree — every level — validates successfully. Nothing is written here.
+  * Called by the object-form of `rehydrate()` and, recursively, by ChildLink
+  * so a nested BehavioralFsm participates in the same validate-then-write
+  * pass. Not part of the public persistence API — call `rehydrate()` instead.
+  */
+  planSnapshotWrites(client, snapshot) {
+    if (this.disposed) return [];
+    const state = snapshot.state,
+      deferred = snapshot.deferred,
+      children = snapshot.children;
+    if (!Object.hasOwn(this.states, state)) throw new Error("rehydrate: unknown state \"".concat(state, "\" in FSM \"").concat(this.id, "\". Valid states: ").concat(Object.keys(this.states).join(", ")));
+    const writes = [];
+    if (children) for (const stateName of Object.keys(children)) {
+      var _this$states$stateNam;
+      if (!Object.hasOwn(this.states, stateName)) throw new Error("rehydrate: unknown state \"".concat(stateName, "\" in FSM \"").concat(this.id, "\" referenced by snapshot.children."));
+      const childLink = (_this$states$stateNam = this.states[stateName]) === null || _this$states$stateNam === void 0 ? void 0 : _this$states$stateNam._child;
+      if (!childLink) throw new Error("rehydrate: state \"".concat(stateName, "\" in FSM \"").concat(this.id, "\" has no _child, but the snapshot has a children[\"").concat(stateName, "\"] entry."));
+      writes.push(...childLink.planRehydrate(client, children[stateName]));
+    }
+    const deferredQueue = deferred.map(item => _objectSpread2({
+      inputName: item.inputName,
+      args: cloneDeep(item.args)
+    }, item.untilState !== void 0 ? {
+      untilState: item.untilState
+    } : {}));
+    writes.push(() => {
+      if (!this.clients.has(client)) this.knownClients.add(new WeakRef(client));
+      this.clients.set(client, {
+        state,
+        deferredQueue
+      });
+    });
+    return writes;
+  }
+  rehydrateCompositePath(client, compositeState) {
+    const _compositeState$split = compositeState.split("."),
+      _compositeState$split2 = _toArray(_compositeState$split),
+      state = _compositeState$split2[0],
+      rest = _arrayLikeToArray(_compositeState$split2).slice(1);
+    if (!Object.hasOwn(this.states, state)) throw new Error("rehydrate: unknown state \"".concat(state, "\" in FSM \"").concat(this.id, "\". Valid states: ").concat(Object.keys(this.states).join(", ")));
+    if (rest.length > 0) {
+      var _this$states$state;
+      const childPath = rest.join(".");
+      const childLink = (_this$states$state = this.states[state]) === null || _this$states$state === void 0 ? void 0 : _this$states$state._child;
+      if (!childLink) throw new Error("rehydrate: state \"".concat(state, "\" in FSM \"").concat(this.id, "\" has no _child, but composite path \"").concat(compositeState, "\" requires one."));
+      childLink.rehydrate(client, childPath);
+    }
+    if (!this.clients.has(client)) this.knownClients.add(new WeakRef(client));
+    this.clients.set(client, {
+      state,
+      deferredQueue: []
+    });
+  }
+  /**
+  * Walks every declared state's `_child`, dehydrating each one that has ever
+  * seen `client`. The same child instance can be declared under multiple
+  * state names (shared child) — it's dehydrated once and the result is
+  * reused under every declaring state name, matching how the engine already
+  * treats shared children elsewhere (dispose, event subscriptions).
+  *
+  * Declaring names are grouped by `childLink.instance` (the actual FSM
+  * instance, not the `ChildLink` wrapper — `wrapChildLinks()` mints a fresh
+  * wrapper per declaring state, so grouping by wrapper would never hit for a
+  * shared child) BEFORE any `onPath` is computed or any child is dehydrated.
+  * A shared child's `onPath` is the OR of `stateName === activeState` across
+  * every declaring name in its group: at most one declaring name can ever
+  * equal `activeState`, so this combined flag is correct and, critically,
+  * independent of `Object.keys(this.states)` iteration order — computing
+  * `onPath` per-declaring-name and caching whichever one happened to run
+  * first would silently launder an on-path client's Fsm-child throw through
+  * an unrelated off-path declaring name.
+  *
+  * An off-path Fsm child (declared only at states other than `activeState`,
+  * OR nested anywhere under a `BehavioralFsm` child that is itself off-path
+  * relative to the true root) is skipped entirely rather than dehydrated:
+  * Fsm state isn't tracked per-client to begin with, so an off-path Fsm
+  * child has nothing to lose by being skipped — unlike a BehavioralFsm
+  * child's off-path meta, which is real per-client data. `isOnActivePath`
+  * is the inherited "am I even reachable from the root" flag; combining it
+  * with the group's `stateNames.includes(activeState)` check (rather than
+  * using that check alone) is what keeps a nested Fsm grandchild from
+  * throwing when its immediate BehavioralFsm parent is itself off-path —
+  * the parent's own dormant `activeState` is irrelevant once the parent
+  * isn't reachable. This keeps one Fsm child anywhere in the hierarchy from
+  * disabling `dehydrate()` for every client, only for clients actually on
+  * that branch.
+  */
+  collectChildSnapshots(client, activeState, isOnActivePath) {
+    const declaringNamesByInstance = /* @__PURE__ */new Map();
+    for (const stateName of Object.keys(this.states)) {
+      var _this$states$stateNam2;
+      const childLink = (_this$states$stateNam2 = this.states[stateName]) === null || _this$states$stateNam2 === void 0 ? void 0 : _this$states$stateNam2._child;
+      if (!childLink) continue;
+      const entry = declaringNamesByInstance.get(childLink.instance);
+      if (entry) entry.stateNames.push(stateName);else declaringNamesByInstance.set(childLink.instance, {
+        childLink,
+        stateNames: [stateName]
+      });
+    }
+    let children;
+    for (const _ref of declaringNamesByInstance.values()) {
+      const childLink = _ref.childLink;
+      const stateNames = _ref.stateNames;
+      const onPath = isOnActivePath && stateNames.includes(activeState);
+      if (childLink.instance[MACHINA_TYPE] === "Fsm" && !onPath) continue;
+      const childSnapshot = childLink.dehydrate(client, onPath);
+      if (childSnapshot) {
+        children !== null && children !== void 0 ? children : children = {};
+        for (const stateName of stateNames) children[stateName] = childSnapshot;
+      }
+    }
+    return children;
+  }
+  snapshotDeferredInput(item) {
+    let clonedArgs;
+    try {
+      clonedArgs = cloneJsonSafe(item.args, "args");
+    } catch (err) {
+      if (!(err instanceof NonSerializableValueError)) throw err;
+      const untilPart = item.untilState ? " (until \"".concat(item.untilState, "\")") : "";
+      throw new Error("dehydrate: deferred input \"".concat(item.inputName, "\"").concat(untilPart, " in FSM \"").concat(this.id, "\" has a non-serializable value at ").concat(err.path, " (").concat(err.label, ")"));
+    }
+    const snapshot = {
+      inputName: item.inputName,
+      args: clonedArgs
+    };
+    if (item.untilState !== void 0) snapshot.untilState = item.untilState;
+    return snapshot;
+  }
+  on(eventName, callback) {
+    if (this.disposed) return {
+      off() {}
+    };
+    return this.emitter.on(eventName, callback);
+  }
+  /**
+  * Emit a custom event through the FSM. Built-in lifecycle events are
+  * emitted automatically — this is for user-defined events from handlers.
+  * No-ops when disposed.
+  */
+  emit(eventName, data) {
+    if (this.disposed) return;
+    this.emitter.emit(eventName, data);
+  }
+  /**
+  * Permanently shut down this FSM. Irreversible — all subsequent method
+  * calls become silent no-ops. Tears down child subscriptions, clears all
+  * listeners, and cascades disposal to child FSMs (unless `preserveChildren`
+  * is set). The same child appearing in multiple states is disposed once.
+  */
+  dispose(options) {
+    this.disposed = true;
+    for (const sub of this.childSubscriptions) sub.off();
+    if (!(options !== null && options !== void 0 && options.preserveChildren)) {
+      const seen = /* @__PURE__ */new Set();
+      for (const stateName of Object.keys(this.states)) {
+        var _this$states$stateNam3;
+        const childLink = (_this$states$stateNam3 = this.states[stateName]) === null || _this$states$stateNam3 === void 0 ? void 0 : _this$states$stateNam3._child;
+        if (childLink && !seen.has(childLink.instance)) {
+          seen.add(childLink.instance);
+          childLink.dispose();
+        }
+      }
+    }
+    this.emitter.clear();
+  }
+  /**
+  * Walks all states at construction time, detects raw FSM instances assigned
+  * to _child, and wraps them into ChildLink adapters via createChildLink().
+  * Must run BEFORE setupChildSubscriptions() so the subscriptions see
+  * ChildLink objects, not raw FSM instances.
+  */
+  wrapChildLinks() {
+    for (const stateName of Object.keys(this.states)) {
+      const stateObj = this.states[stateName];
+      const rawChild = stateObj === null || stateObj === void 0 ? void 0 : stateObj._child;
+      if (!rawChild) continue;
+      if (typeof rawChild !== "object") throw new Error("State \"".concat(stateName, "\"._child: expected an Fsm or BehavioralFsm instance, got ").concat(String(rawChild)));
+      if (!(MACHINA_TYPE in rawChild)) throw new Error("State \"".concat(stateName, "\"._child: expected an Fsm or BehavioralFsm instance, got a plain object"));
+      stateObj._child = createChildLink(rawChild);
+    }
+  }
+  /**
+  * Walks all states at construction time, finds states with _child, and
+  * subscribes once to each unique child's wildcard events. Subscriptions are
+  * stored for cleanup in dispose(). We deduplicate by `childLink.instance`
+  * (the underlying Fsm/BehavioralFsm instance), not the `ChildLink` wrapper —
+  * `wrapChildLinks()` mints a fresh wrapper per declaring state, so a child
+  * shared across states would otherwise get one subscription PER declaring
+  * state, each independently walking known clients and relaying events. That
+  * silently double-fires client-less relays (Fsm-child events, or a
+  * BehavioralFsm child's custom `emit()` with no `client` in the payload)
+  * whenever two different clients are active on two different declaring
+  * names at once — the same wrapper-vs-instance identity bug
+  * `collectChildSnapshots()` had before its #184 fix.
+  */
+  setupChildSubscriptions() {
+    const seenInstances = /* @__PURE__ */new Set();
+    for (const stateName of Object.keys(this.states)) {
+      var _this$states$stateNam4;
+      const childLink = (_this$states$stateNam4 = this.states[stateName]) === null || _this$states$stateNam4 === void 0 ? void 0 : _this$states$stateNam4._child;
+      if (!childLink || seenInstances.has(childLink.instance)) continue;
+      seenInstances.add(childLink.instance);
+      const sub = childLink.onAny((eventName, data) => {
+        if (eventName === "nohandler") {
+          var _payload$args;
+          const payload = data;
+          if (payload.client !== void 0) this.bubbleNohandler(payload.client, childLink, payload.inputName, (_payload$args = payload.args) !== null && _payload$args !== void 0 ? _payload$args : []);else for (const ref of this.knownClients) {
+            var _payload$args2;
+            const client = ref.deref();
+            if (client === void 0) {
+              this.knownClients.delete(ref);
+              continue;
+            }
+            this.bubbleNohandler(client, childLink, payload.inputName, (_payload$args2 = payload.args) !== null && _payload$args2 !== void 0 ? _payload$args2 : []);
+          }
+          return;
+        }
+        const payload = data;
+        if (payload && typeof payload === "object" && "client" in payload) {
+          if (this.isChildActiveForClient(payload.client, childLink)) this.emitter.emit(eventName, data);
+        } else for (const ref of this.knownClients) {
+          const client = ref.deref();
+          if (!client) {
+            this.knownClients.delete(ref);
+            continue;
+          }
+          if (this.isChildActiveForClient(client, childLink)) {
+            this.emitter.emit(eventName, data);
+            break;
+          }
+        }
+      });
+      this.childSubscriptions.push(sub);
+    }
+  }
+  /**
+  * Bubbles a child nohandler to the parent for the given client.
+  * Only fires if the client is currently in a state that has this childLink.
+  * Extracted from the lambda in setupChildSubscriptions to keep it readable.
+  */
+  bubbleNohandler(client, childLink, inputName, args) {
+    if (!this.isChildActiveForClient(client, childLink)) return;
+    const meta = this.clients.get(client);
+    meta.currentActionArgs = args;
+    this.handleLocally(client, inputName, args, meta);
+  }
+  /**
+  * Returns true if the given client is currently in a parent state whose
+  * _child resolves to the same underlying instance as childLink. Returns
+  * false if the client has no meta (never initialized) or is in a state
+  * with a different (or no) child.
+  *
+  * Compares `.instance`, not the `ChildLink` wrapper itself — setupChildSubscriptions()
+  * dedupes subscriptions by instance and keeps only ONE representative wrapper
+  * per shared child, so the client's actual active declaring state may hold a
+  * DIFFERENT wrapper for that same instance (wrapChildLinks() mints one per
+  * declaring state). Comparing wrappers directly would only ever match the one
+  * declaring state whose wrapper happened to be kept for the subscription,
+  * silently breaking relay for every other declaring name of a shared child.
+  */
+  isChildActiveForClient(client, childLink) {
+    var _this$states$meta$sta3;
+    const meta = this.clients.get(client);
+    if (!meta) return false;
+    return ((_this$states$meta$sta3 = this.states[meta.state]) === null || _this$states$meta$sta3 === void 0 || (_this$states$meta$sta3 = _this$states$meta$sta3._child) === null || _this$states$meta$sta3 === void 0 ? void 0 : _this$states$meta$sta3.instance) === childLink.instance;
+  }
+  /**
+  * The inner handler dispatch — no delegation, no initialization side effects
+  * beyond what getOrCreateClientMeta already did. Called by handle() after
+  * the delegation check, and by the nohandler child listener for bubbling.
+  */
+  handleLocally(client, inputName, args, meta) {
+    var _stateObj$inputName2;
+    const stateObj = this.states[meta.state];
+    const handler = (_stateObj$inputName2 = stateObj === null || stateObj === void 0 ? void 0 : stateObj[inputName]) !== null && _stateObj$inputName2 !== void 0 ? _stateObj$inputName2 : stateObj === null || stateObj === void 0 ? void 0 : stateObj["*"];
+    if (!handler) {
+      this.emitter.emit("nohandler", {
+        inputName,
+        args,
+        client
+      });
+      meta.currentActionArgs = void 0;
+      return;
+    }
+    try {
+      this.emitter.emit("handling", {
+        inputName,
+        client
+      });
+      const handlerArgs = this.buildHandlerArgs(client, inputName, meta);
+      let targetState = void 0;
+      if (typeof handler === "string") targetState = handler;else if (typeof handler === "function") targetState = handler(handlerArgs, ...args);
+      this.emitter.emit("handled", {
+        inputName,
+        client
+      });
+      if (typeof targetState === "string") this.transition(client, targetState);
+    } finally {
+      meta.currentActionArgs = void 0;
+    }
+  }
+  getOrCreateClientMeta(client) {
+    let meta = this.clients.get(client);
+    if (meta) return meta;
+    meta = {
+      state: void 0,
+      deferredQueue: []
+    };
+    this.clients.set(client, meta);
+    this.knownClients.add(new WeakRef(client));
+    this.transition(client, this.initialState);
+    return meta;
+  }
+  buildHandlerArgs(client, inputName, meta) {
+    return {
+      ctx: client,
+      inputName,
+      defer: opts => {
+        if (!meta.currentActionArgs) return;
+        const deferred = {
+          inputName,
+          args: [...meta.currentActionArgs],
+          untilState: opts === null || opts === void 0 ? void 0 : opts.until
+        };
+        meta.deferredQueue.push(deferred);
+        this.emitter.emit("deferred", {
+          inputName,
+          client
+        });
+      },
+      emit: (evtName, evtData) => {
+        this.emitter.emit(evtName, evtData);
+      }
+    };
+  }
+  processQueue(client, meta) {
+    const toReplay = [];
+    const remaining = [];
+    for (const item of meta.deferredQueue) if (item.untilState === void 0 || item.untilState === meta.state) toReplay.push(item);else remaining.push(item);
+    meta.deferredQueue = remaining;
+    for (const item of toReplay) this.handle(client, item.inputName, ...item.args);
+  }
+};
+/**
+* Internal factory called by `wrapChildLinks()` during construction.
+* Wraps a raw Fsm or BehavioralFsm instance in a uniform `ChildLink` adapter
+* so the parent engine doesn't need to know which type it's talking to.
+*
+* Users never call this directly — they assign an FSM instance to `_child`
+* in their state config and `wrapChildLinks()` handles the wrapping.
+*/
+function createChildLink(child) {
+  if (!child || typeof child !== "object") throw new Error("createChildLink: expected an Fsm or BehavioralFsm instance, got ".concat(String(child)));
+  const childType = child[MACHINA_TYPE];
+  if (childType === "BehavioralFsm") return {
+    instance: child,
+    canHandle(client, inputName) {
+      return child.canHandle(client, inputName);
+    },
+    handle(client, inputName) {
+      for (var _len2 = arguments.length, args = new Array(_len2 > 2 ? _len2 - 2 : 0), _key2 = 2; _key2 < _len2; _key2++) {
+        args[_key2 - 2] = arguments[_key2];
+      }
+      child.handle(client, inputName, ...args);
+    },
+    reset(client) {
+      child.transition(client, child.initialState);
+    },
+    onAny(callback) {
+      return child.on("*", callback);
+    },
+    compositeState(client) {
+      return child.compositeState(client);
+    },
+    rehydrate(client, compositeState) {
+      child.rehydrate(client, compositeState);
+    },
+    dehydrate(client, isOnActivePath) {
+      return child.dehydrate(client, isOnActivePath);
+    },
+    planRehydrate(client, snapshot) {
+      return child.planSnapshotWrites(client, snapshot);
+    },
+    dispose() {
+      child.dispose();
+    }
+  };
+  if (childType === "Fsm") return {
+    instance: child,
+    canHandle(_client, inputName) {
+      return child.canHandle(inputName);
+    },
+    handle(_client, inputName) {
+      for (var _len3 = arguments.length, args = new Array(_len3 > 2 ? _len3 - 2 : 0), _key3 = 2; _key3 < _len3; _key3++) {
+        args[_key3 - 2] = arguments[_key3];
+      }
+      child.handle(inputName, ...args);
+    },
+    reset(_client) {
+      child.reset();
+    },
+    onAny(callback) {
+      return child.on("*", callback);
+    },
+    compositeState(_client) {
+      return child.compositeState();
+    },
+    rehydrate(_client, _compositeState) {
+      throw new Error("rehydrate: cannot rehydrate an Fsm child. Fsm owns its own context; rehydrate is only valid for BehavioralFsm hierarchies.");
+    },
+    dehydrate(_client, _isOnActivePath) {
+      throw new Error("dehydrate: cannot dehydrate an Fsm child. Fsm owns its own context; dehydrate is only valid for BehavioralFsm hierarchies.");
+    },
+    planRehydrate(_client, _snapshot) {
+      throw new Error("rehydrate: cannot rehydrate an Fsm child. Fsm owns its own context; rehydrate is only valid for BehavioralFsm hierarchies.");
+    },
+    dispose() {
+      child.dispose();
+    }
+  };
+  throw new Error("createChildLink: expected an Fsm or BehavioralFsm instance, got [MACHINA_TYPE] = ".concat(String(childType !== null && childType !== void 0 ? childType : "undefined")));
+}
+
+//#endregion
+//#region src/fsm.ts
+/**
+* Single-client FSM. Wraps a BehavioralFsm and uses the config's `context`
+* object as the implicit client, so callers never pass a client argument.
+*
+* Prefer `createFsm()` over constructing this directly — the factory infers
+* all generic parameters from the config object.
+*
+* All public methods silently no-op after `dispose()` is called.
+*
+* @typeParam TCtx - The context type, inferred from `config.context`.
+* @typeParam TStateNames - String literal union of valid state names.
+* @typeParam TInputNames - String literal union of valid input names.
+* @typeParam TBubbles - String literal union of inputs this FSM declares via
+*   `bubbles`. Type-only — carried so `BubblesOfInstance` can extract it from
+*   a constructed instance; nothing at runtime reads this generic.
+*/
+var Fsm = class Fsm {
+  constructor(config) {
+    var _config$context;
+    _defineProperty(this, "id", void 0);
+    _defineProperty(this, "initialState", void 0);
+    _defineProperty(this, MACHINA_TYPE, "Fsm");
+    _defineProperty(this, "states", void 0);
+    _defineProperty(this, "bfsm", void 0);
+    _defineProperty(this, "context", void 0);
+    _defineProperty(this, "emitter", new Emitter());
+    _defineProperty(this, "disposed", false);
+    this.id = config.id;
+    this.initialState = config.initialState;
+    this.context = (_config$context = config.context) !== null && _config$context !== void 0 ? _config$context : {};
+    this.bfsm = new BehavioralFsm(config);
+    this.states = config.states;
+    this.bfsm.on("*", (eventName, data) => {
+      if (data && typeof data === "object" && "client" in data) {
+        data.client;
+          const payload = _objectWithoutProperties(data, _excluded);
+        this.emitter.emit(eventName, payload);
+      } else this.emitter.emit(eventName, data);
+    });
+    this.bfsm.transition(this.context, config.initialState);
+  }
+  /**
+  * Dispatch an input to the current state's handler.
+  * If a `_child` FSM in the current state can handle it, delegation occurs
+  * there first; unhandled inputs bubble up to the parent.
+  * No-ops silently when disposed.
+  */
+  handle(inputName) {
+    if (this.disposed) return;
+    for (var _len4 = arguments.length, args = new Array(_len4 > 1 ? _len4 - 1 : 0), _key4 = 1; _key4 < _len4; _key4++) {
+      args[_key4 - 1] = arguments[_key4];
+    }
+    this.bfsm.handle(this.context, inputName, ...args);
+  }
+  /**
+  * Returns true if the current state has a handler for `inputName`
+  * (or a catch-all `"*"` handler), or if the current state's `_child`
+  * chain can handle it (checked recursively, matching `handle()`'s
+  * delegation reach). Does not trigger initialization or any side
+  * effects. Returns false when disposed.
+  */
+  canHandle(inputName) {
+    if (this.disposed) return false;
+    return this.bfsm.canHandle(this.context, inputName);
+  }
+  /**
+  * Transition back to `initialState`, firing `_onEnter` and lifecycle
+  * events as if entering it fresh. No-ops silently when disposed.
+  */
+  reset() {
+    if (this.disposed) return;
+    this.bfsm.reset(this.context);
+  }
+  /**
+  * Returns the current state name. Always defined — Fsm eagerly
+  * initializes into `initialState` during construction.
+  */
+  currentState() {
+    return this.bfsm.currentState(this.context);
+  }
+  /**
+  * Directly transition to `toState`, firing `_onExit`, `_onEnter`, and
+  * lifecycle events. Same-state transitions are silently ignored.
+  * No-ops when disposed.
+  */
+  transition(toState) {
+    if (this.disposed) return;
+    this.bfsm.transition(this.context, toState);
+  }
+  /**
+  * Returns the current state as a dot-delimited path that includes
+  * any active child FSM states (e.g. `"active.connecting.retrying"`).
+  * Returns just the current state name when no child is active.
+  */
+  compositeState() {
+    return this.bfsm.compositeState(this.context);
+  }
+  on(eventName, callback) {
+    if (this.disposed) return {
+      off() {}
+    };
+    return this.emitter.on(eventName, callback);
+  }
+  /**
+  * Emit a custom event through the FSM. Built-in lifecycle events are
+  * emitted automatically — this is for user-defined events from handlers.
+  * Routes through the BehavioralFsm so all relay paths are consistent.
+  * No-ops when disposed.
+  */
+  emit(eventName, data) {
+    if (this.disposed) return;
+    this.bfsm.emit(eventName, data);
+  }
+  /**
+  * Permanently shut down this FSM. Irreversible — all subsequent method
+  * calls become silent no-ops. Clears all listeners and cascades disposal
+  * to child FSMs (unless `preserveChildren` is set).
+  */
+  dispose(options) {
+    this.disposed = true;
+    this.bfsm.dispose(options);
+    this.emitter.clear();
+  }
+};
+/**
+* Create a single-client FSM from a config object.
+*
+* Generic parameters are inferred automatically:
+* - `TCtx` comes from `config.context` (defaults to `{}` if omitted).
+* - `TStates` is captured with `const` inference to preserve string literal
+*   types, enabling compile-time validation of transition targets and `handle()`
+*   input names.
+*
+* State names, input names, and all handler signatures derive from `TStates`.
+*
+* @example
+* ```ts
+* const light = createFsm({
+*   id: "traffic-light",
+*   initialState: "green",
+*   context: { tickCount: 0 },
+*   states: {
+*     green:  { timeout: "yellow" },
+*     yellow: { timeout: "red" },
+*     red:    { timeout: "green" },
+*   },
+* });
+*
+* light.handle("timeout"); // transitions green → yellow
+* ```
+*/
+function createFsm(config) {
+  return new Fsm(config);
+}/**
+ * Declares a handler for one input, restoring the payload typing that machina's `...unknown[]`
+ * handler arguments give up.
+ */
+function on(handler) {
+  return handler;
+}
+/**
+ * Whether a transport-originated input belongs to the attempt that currently owns the session.
+ * Inputs from a superseded attempt are dropped: its transport is already being replaced, so it can
+ * neither declare the session live nor take it down.
+ */
+function isCurrentAttempt(ctx, event) {
+  return event.attemptId === ctx.attemptId;
+}
+const attemptEstablished = on((_ref, event) => {
+  let ctx = _ref.ctx;
+  if (!isCurrentAttempt(ctx, event)) {
+    return;
+  }
+  return 'connected';
+});
+const startConnect = on(_ref2 => {
+  let ctx = _ref2.ctx;
+  ctx.attemptId += 1;
+  ctx.lastError = undefined;
+  return 'connecting';
+});
+const startReconnect = on(_ref3 => {
+  let ctx = _ref3.ctx;
+  ctx.attemptId += 1;
+  ctx.lastError = undefined;
+  return 'reconnecting';
+});
+const requestClose = on((_ref4, event) => {
+  let ctx = _ref4.ctx;
+  ctx.closeReason = event.reason;
+  return 'disconnecting';
+});
+const signalStates = {
+  new: {
+    connect: startConnect,
+    close: requestClose
+  },
+  connecting: {
+    connectComplete: attemptEstablished,
+    // An initial connect has no session to fall back on, so failure is terminal.
+    connectFailed: on((_ref5, event) => {
+      let ctx = _ref5.ctx;
+      ctx.lastError = event.error;
+      return 'closed';
+    }),
+    close: requestClose
+  },
+  connected: {
+    reconnect: startReconnect,
+    transportFailed: on((_ref6, event) => {
+      let ctx = _ref6.ctx;
+      if (!isCurrentAttempt(ctx, event)) {
+        // a transport that has already been replaced, reporting its close late
+        return;
+      }
+      ctx.lastError = event.reason;
+      return 'offline';
+    }),
+    close: requestClose
+  },
+  offline: {
+    connect: startConnect,
+    reconnect: startReconnect,
+    close: requestClose
+  },
+  reconnecting: {
+    reconnectComplete: attemptEstablished,
+    reconnectFailed: on((_ref7, event) => {
+      let ctx = _ref7.ctx;
+      ctx.lastError = event.error;
+      return event.recoverable ? 'offline' : 'closed';
+    }),
+    close: requestClose
+  },
+  // Owns the transport until the close handshake settles. Every path into this state is followed
+  // by a `closeComplete`, so it cannot become a trap.
+  disconnecting: {
+    closeComplete: 'closed'
+  },
+  // No transport, but the session may still be resumable: the engine resumes after an unexpected
+  // close just as it does from `offline`.
+  closed: {
+    connect: startConnect,
+    reconnect: startReconnect
+  }
+};
+/**
+ * Lifecycle model of the signal connection.
+ *
+ * The machine deliberately does not own connection attempts: `SignalClient` performs the
+ * asynchronous work and reports the outcome. It also does not decide *whether* to reconnect —
+ * that policy (backoff, resume vs. full reconnect, region failover, giving up) belongs to
+ * `RTCEngine`, so transport loss lands in `offline` rather than starting a reconnect on its own.
+ *
+ * Each client gets its own instance: the context is mutable and per-connection.
+ */
+function createSignalMachine() {
+  let initialState = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'new';
+  const context = {
+    attemptId: 0
+  };
+  return createFsm({
+    id: 'signal',
+    initialState: initialState,
+    context,
+    states: signalStates
+  });
 }/**
  * [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) with [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)
  *
@@ -16657,7 +18070,14 @@ class WebSocketStream {
                 let data = _ref2.data;
                 return controller.enqueue(data);
               };
-              ws.onerror = e => controller.error(e);
+              ws.onerror = e => controller.error(ConnectionError.websocket(e instanceof Error ? "".concat(e.name, ": ").concat(e.message) : "Encountered unknown websocket error: ".concat(String(e))));
+              ws.onclose = ev => {
+                if (ev.wasClean) {
+                  controller.close();
+                } else {
+                  controller.error(ConnectionError.websocket("WS closed unexpectedly with code ".concat(ev.code)));
+                }
+              };
             },
             cancel: closeWithInfo
           }),
@@ -16696,7 +18116,7 @@ class WebSocketStream {
           resolve(reason);
         }
       });
-      ws.onclose = _ref3 => {
+      ws.addEventListener('close', _ref3 => {
         let code = _ref3.code,
           reason = _ref3.reason;
         resolve({
@@ -16704,7 +18124,7 @@ class WebSocketStream {
           reason
         });
         ws.removeEventListener('error', rejectHandler);
-      };
+      });
       ws.addEventListener('error', rejectHandler);
     });
     if (options.signal) {
@@ -16713,6 +18133,16 @@ class WebSocketStream {
     this.close = closeWithInfo;
   }
 }const passThroughQueueSignals = ['syncState', 'trickle', 'offer', 'answer', 'simulate', 'leave'];
+/**
+ * Whether a failed resume may be followed by another one. Mirrors how `RTCEngine` classifies these
+ * errors: a server leave ends the session, and an expired token cannot be recovered by retrying.
+ */
+function isRecoverableReconnectError(error) {
+  if (error instanceof ConnectionError) {
+    return error.reason !== ConnectionErrorReason.LeaveRequest && error.reason !== ConnectionErrorReason.NotAllowed;
+  }
+  return true;
+}
 function canPassThroughQueue(req) {
   const canPass = passThroughQueueSignals.indexOf(req.case) >= 0;
   livekitLogger.trace('request allowed to bypass queue:', {
@@ -16729,6 +18159,24 @@ var SignalConnectionState;
   SignalConnectionState[SignalConnectionState["DISCONNECTING"] = 3] = "DISCONNECTING";
   SignalConnectionState[SignalConnectionState["DISCONNECTED"] = 4] = "DISCONNECTED";
 })(SignalConnectionState || (SignalConnectionState = {}));
+/**
+ * Public projection of the lifecycle machine's states. `new`, `offline` and `closed` are all
+ * reported as `DISCONNECTED`: they differ in what may happen next
+ */
+function lifecycleToConnectionState(lifecycle) {
+  switch (lifecycle) {
+    case 'connected':
+      return SignalConnectionState.CONNECTED;
+    case 'connecting':
+      return SignalConnectionState.CONNECTING;
+    case 'reconnecting':
+      return SignalConnectionState.RECONNECTING;
+    case 'disconnecting':
+      return SignalConnectionState.DISCONNECTING;
+    default:
+      return SignalConnectionState.DISCONNECTED;
+  }
+}
 /** specifies how much time (in ms) we allow for the ws to close its connection gracefully before continuing */
 const MAX_WS_CLOSE_TIME = 250;
 /**
@@ -16738,13 +18186,41 @@ const JOIN_RESPONSE_TIMEOUT = 5000;
 /** @internal */
 class SignalClient {
   get currentState() {
-    return this.state;
+    return lifecycleToConnectionState(this.lifecycleState);
   }
   get isDisconnected() {
-    return this.state === SignalConnectionState.DISCONNECTING || this.state === SignalConnectionState.DISCONNECTED;
+    const state = this.currentState;
+    return state === SignalConnectionState.DISCONNECTING || state === SignalConnectionState.DISCONNECTED;
+  }
+  /** Runtime lifecycle state, finer grained than the public {@link currentState} projection. */
+  get lifecycleState() {
+    return this.machine.currentState();
+  }
+  /** Id of the current connection attempt and of the transport it owns. */
+  get attemptId() {
+    return this.machine.context.attemptId;
+  }
+  /**
+   * Applies a lifecycle input and reports whether it moved the machine
+   */
+  sendLifecycleInput(input) {
+    const before = this.lifecycleState;
+    this.machine.handle(input.type, input);
+    return this.lifecycleState !== before;
+  }
+  /**
+   * Waits out a close that is already in flight. Establishing a session while one is tearing down
+   * would race it for the transport — the teardown can close the socket the new attempt just
+   * opened.
+   */
+  settleInFlightClose() {
+    return __awaiter(this, void 0, void 0, function* () {
+      this.log.debug('waiting for an in-flight close to settle before establishing a session');
+      (yield this.closingLock.lock())();
+    });
   }
   get isEstablishingConnection() {
-    return this.state === SignalConnectionState.CONNECTING || this.state === SignalConnectionState.RECONNECTING;
+    return this.lifecycleState === 'connecting' || this.lifecycleState === 'reconnecting';
   }
   getNextRequestId() {
     this._requestId += 1;
@@ -16756,7 +18232,6 @@ class SignalClient {
     var _a;
     /** signal rtt in milliseconds */
     this.rtt = 0;
-    this.state = SignalConnectionState.DISCONNECTED;
     this.log = livekitLogger;
     this._requestId = 0;
     this.useV0SignalPath = false;
@@ -16782,7 +18257,18 @@ class SignalClient {
     this.queuedRequests = [];
     this.closingLock = new _();
     this.connectionLock = new _();
-    this.state = SignalConnectionState.DISCONNECTED;
+    this.machine = createSignalMachine();
+    this.machine.on('transitioned', _ref => {
+      let fromState = _ref.fromState,
+        toState = _ref.toState;
+      this.log.debug("signal lifecycle: ".concat(fromState, " -> ").concat(toState));
+    });
+    this.machine.on('nohandler', _ref2 => {
+      let inputName = _ref2.inputName;
+      this.log.debug("ignoring signal lifecycle input ".concat(inputName, " in state ").concat(this.lifecycleState));
+    });
+    // no-op unless a development tool asked for it; see utils/machineInspector
+    announceMachine('signal', this.machine);
   }
   get logContext() {
     var _a, _b;
@@ -16794,12 +18280,30 @@ class SignalClient {
       let useV0Path = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
       let publisherOffer = arguments.length > 5 ? arguments[5] : undefined;
       return function* () {
-        // during a full reconnect, we'd want to start the sequence even if currently
-        // connected
-        _this.state = SignalConnectionState.CONNECTING;
+        if (_this.lifecycleState === 'disconnecting') {
+          yield _this.settleInFlightClose();
+        }
+        if (!_this.sendLifecycleInput({
+          type: 'connect'
+        })) {
+          // Proceeding would open a transport the lifecycle does not own: its completion would be
+          // discarded and the session left claiming a transport that had been torn down. Every caller
+          // that restarts a session closes the previous one first (see RTCEngine.restartConnection).
+          throw ConnectionError.internal("cannot establish a signal session from '".concat(_this.lifecycleState, "', close the current one first"));
+        }
         _this.options = opts;
-        const res = yield _this.connect(url, token, opts, abortSignal, useV0Path, publisherOffer);
-        return res;
+        try {
+          const res = yield _this.connect(url, token, opts, abortSignal, useV0Path, publisherOffer);
+          return res;
+        } catch (e) {
+          // reported here rather than at each rejection site inside connect(), so that no failure
+          // path can leave the machine stuck in `connecting`
+          _this.sendLifecycleInput({
+            type: 'connectFailed',
+            error: e
+          });
+          throw e;
+        }
       }();
     });
   }
@@ -16809,15 +18313,31 @@ class SignalClient {
         this.log.warn('attempted to reconnect without signal options being set, ignoring');
         return;
       }
-      this.state = SignalConnectionState.RECONNECTING;
+      if (this.lifecycleState === 'disconnecting') {
+        yield this.settleInFlightClose();
+      }
+      if (!this.sendLifecycleInput({
+        type: 'reconnect'
+      })) {
+        throw ConnectionError.internal("cannot resume the signal session from '".concat(this.lifecycleState, "'"));
+      }
       // clear ping interval and restart it once reconnected
       this.clearPingInterval();
-      const res = yield this.connect(url, token, Object.assign(Object.assign({}, this.options), {
-        reconnect: true,
-        sid,
-        reconnectReason: reason
-      }), undefined, this.useV0SignalPath);
-      return res;
+      try {
+        const res = yield this.connect(url, token, Object.assign(Object.assign({}, this.options), {
+          reconnect: true,
+          sid,
+          reconnectReason: reason
+        }), undefined, this.useV0SignalPath);
+        return res;
+      } catch (e) {
+        this.sendLifecycleInput({
+          type: 'reconnectFailed',
+          error: e,
+          recoverable: isRecoverableReconnectError(e)
+        });
+        throw e;
+      }
     });
   }
   connect(url_1, token_1, opts_1, abortSignal_1) {
@@ -16854,7 +18374,11 @@ class SignalClient {
                 this.close();
               }
               cleanupAbortHandlers();
-              reject(ConnectionError.cancelled(reason));
+              // The caller may already have classified this failure: the connect timeout hands us a
+              // Timeout error. Only a genuine abort is a cancellation, and reporting a stalled connect as
+              // one makes the engine read it as user intent — skipping region failover and never
+              // recording the attempt against the backoff strategy (see Room.connect).
+              reject(eventOrError instanceof ConnectionError ? eventOrError : ConnectionError.cancelled(reason));
             });
             abortSignal === null || abortSignal === void 0 ? void 0 : abortSignal.addEventListener('abort', abortHandler);
             const cleanupAbortHandlers = () => {
@@ -16864,48 +18388,62 @@ class SignalClient {
             const wsTimeout = setTimeout(() => {
               abortHandler(ConnectionError.timeout('room connection has timed out (signal)'));
             }, opts.websocketTimeout);
-            const handleSignalConnected = (connection, firstMessage) => {
-              this.handleSignalConnected(connection, wsTimeout, firstMessage);
-            };
             const redactedUrl = new URL(rtcUrl);
             if (redactedUrl.searchParams.has('access_token')) {
               redactedUrl.searchParams.set('access_token', '<redacted>');
             }
             if (this.ws) {
               const startClose = performance.now();
-              yield this.close(false);
+              yield this.teardownTransport('replaced by a new connection attempt');
               this.log.debug("closed previous ws connection in ".concat(performance.now() - startClose, "ms"));
             }
+            // the transport created below belongs to this attempt; events arriving from it after a
+            // newer attempt has started are dropped by the machine
+            const attemptId = this.attemptId;
             this.log.info("signal connecting to ".concat(redactedUrl), {
               reconnect: opts.reconnect,
               reconnectReason: opts.reconnectReason
             });
             this.ws = new WebSocketStream(rtcUrl);
+            // A failed upgrade closes the socket, so `opened` and `closed` settle for the same cause — but
+            // only the `opened` path can classify it (a 401 is known after asking the validate endpoint).
+            // Noting the failure *before* the close handler is registered means it runs first, so a close
+            // that merely reflects a failed upgrade stands down and lets the classified error reach the
+            // caller. Any other close still fails the attempt straight away: after a successful upgrade
+            // nothing else would, short of the first-message timeout.
+            let upgradeFailed = false;
+            this.ws.opened.catch(() => {
+              upgradeFailed = true;
+            });
             try {
               this.ws.closed.then(closeInfo => {
-                if (this.isEstablishingConnection) {
+                if (this.isEstablishingConnection && !upgradeFailed) {
                   reject(ConnectionError.internal("Websocket got closed during a (re)connection attempt: ".concat(closeInfo.reason)));
                 }
-                if (closeInfo.closeCode !== 1000) {
-                  this.log.warn("websocket closed", {
-                    reason: closeInfo.reason,
-                    code: closeInfo.closeCode,
-                    wasClean: closeInfo.closeCode === 1000,
-                    state: this.state
-                  });
-                  if (this.state === SignalConnectionState.CONNECTED) {
-                    this.handleOnClose(closeInfo.reason || 'Unexpected WS error');
-                  }
-                }
+                this.log.debug('websocket closed', {
+                  reason: closeInfo.reason,
+                  code: closeInfo.closeCode,
+                  attemptId,
+                  state: this.lifecycleState
+                });
+                // Every close of the live transport is reported, including a clean 1000 one: a server
+                // that drops signalling closes cleanly — a migration that never sends its
+                // `Leave{action=RESUME}` does exactly that — and treating that as "nothing happened"
+                // leaves the client believing it is still connected until something else notices.
+                // Closes we caused ourselves, and closes from a transport that has since been
+                // replaced, are dropped by the machine's state and attempt guards below rather than by
+                // a close-code test.
+                this.handleOnClose(closeInfo.reason || (closeInfo.closeCode === 1000 ? 'server closed the signal connection' : 'Unexpected WS error'), attemptId);
                 return;
               }).catch(reason => {
-                if (this.isEstablishingConnection) {
+                if (this.isEstablishingConnection && !upgradeFailed) {
                   reject(ConnectionError.internal("Websocket error during a (re)connection attempt: ".concat(reason)));
                 }
               });
               const connection = yield this.ws.opened.catch(reason => __awaiter(this, void 0, void 0, function* () {
-                if (this.state !== SignalConnectionState.CONNECTED) {
-                  this.state = SignalConnectionState.DISCONNECTED;
+                if (this.lifecycleState !== 'connected') {
+                  // claimed synchronously, before the await below: the socket's close event is already
+                  // on its way and would otherwise reject first with a less useful error
                   clearTimeout(wsTimeout);
                   const error = yield this.handleConnectionError(reason, validateUrl);
                   reject(error);
@@ -16970,7 +18508,7 @@ class SignalClient {
               }
               // Handle successful connection
               const firstMessageToProcess = validation.shouldProcessFirstMessage ? firstSignalResponse : undefined;
-              handleSignalConnected(connection, firstMessageToProcess);
+              this.handleSignalConnected(connection, wsTimeout, attemptId, firstMessageToProcess);
               resolve(validation.response);
             } catch (e) {
               reject(e);
@@ -16989,18 +18527,27 @@ class SignalClient {
       if (firstMessage) {
         this.handleSignalResponse(firstMessage);
       }
+      const attemptId = this.attemptId;
       while (true) {
         if (this.signalLatency) {
           yield sleep(this.signalLatency);
         }
-        const _yield$signalReader$r = yield signalReader.read(),
-          done = _yield$signalReader$r.done,
-          value = _yield$signalReader$r.value;
-        if (done) {
+        try {
+          const _yield$signalReader$r = yield signalReader.read(),
+            done = _yield$signalReader$r.done,
+            value = _yield$signalReader$r.value;
+          if (done) {
+            break;
+          }
+          const resp = parseSignalResponse(value);
+          this.handleSignalResponse(resp);
+        } catch (e) {
+          this.log.error("error reading from signal stream", {
+            error: e
+          });
+          yield this.handleOnClose('error in reading loop', attemptId);
           break;
         }
-        const resp = parseSignalResponse(value);
-        this.handleSignalResponse(resp);
       }
     });
   }
@@ -17010,40 +18557,53 @@ class SignalClient {
       let updateState = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       let reason = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'Close method called on signal client';
       return function* () {
-        if ([SignalConnectionState.DISCONNECTING || SignalConnectionState.DISCONNECTED].includes(_this3.state)) {
-          _this3.log.debug("ignoring signal close as it's already in disconnecting state");
-          return;
-        }
+        // when the lifecycle is already shutting down (or another close owns it), only the transport
+        // teardown below still applies — it is idempotent, so callers can always await a close
+        const drivesLifecycle = updateState && _this3.sendLifecycleInput({
+          type: 'close',
+          reason
+        });
         const unlock = yield _this3.closingLock.lock();
         try {
-          _this3.clearPingInterval();
-          if (updateState) {
-            _this3.state = SignalConnectionState.DISCONNECTING;
-          }
-          if (_this3.ws) {
-            _this3.ws.close({
-              closeCode: 1000,
-              reason
-            });
-            // calling `ws.close()` only starts the closing handshake (CLOSING state), prefer to wait until state is actually CLOSED
-            const closePromise = _this3.ws.closed;
-            _this3.ws = undefined;
-            _this3.streamWriter = undefined;
-            yield Promise.race([closePromise, sleep(MAX_WS_CLOSE_TIME)]);
-          }
-        } catch (e) {
-          _this3.log.debug('websocket error while closing', {
-            error: e
-          });
+          yield _this3.teardownTransport(reason);
         } finally {
-          if (updateState) {
-            _this3.state = SignalConnectionState.DISCONNECTED;
+          if (drivesLifecycle) {
+            _this3.sendLifecycleInput({
+              type: 'closeComplete'
+            });
           }
           unlock();
         }
       }();
     });
   }
+  /**
+   * Releases the transport and everything tied to it, without touching the lifecycle state. Used
+   * both by {@link close} and by paths that replace the transport under a live lifecycle (a new
+   * attempt, or an unexpected close that leaves the client in `offline`).
+   */
+  teardownTransport(reason) {
+    return __awaiter(this, void 0, void 0, function* () {
+      try {
+        this.clearPingInterval();
+        if (this.ws) {
+          this.ws.close({
+            closeCode: 1000,
+            reason
+          });
+          // calling `ws.close()` only starts the closing handshake (CLOSING state), prefer to wait until state is actually CLOSED
+          const closePromise = this.ws.closed;
+          this.ws = undefined;
+          this.streamWriter = undefined;
+          yield Promise.race([closePromise, sleep(MAX_WS_CLOSE_TIME)]);
+        }
+      } catch (e) {
+        this.log.debug('websocket error while closing', {
+          error: e
+        });
+      }
+    });
+  }
   // initial offer after joining
   sendOffer(offer, offerId) {
     this.log.debug('sending offer', {
@@ -17222,7 +18782,8 @@ class SignalClient {
         // capture all requests while reconnecting and put them in a queue
         // unless the request originates from the queue, then don't enqueue again
         const canQueue = !fromQueue && !canPassThroughQueue(message);
-        if (canQueue && _this5.state === SignalConnectionState.RECONNECTING) {
+        const isHoldingRequests = _this5.lifecycleState === 'reconnecting' || _this5.queuedRequests.length > 0;
+        if (canQueue && isHoldingRequests) {
           _this5.queuedRequests.push(() => __awaiter(_this5, void 0, void 0, function* () {
             yield this.sendRequest(message, true);
           }));
@@ -17235,7 +18796,11 @@ class SignalClient {
         if (_this5.signalLatency) {
           yield sleep(_this5.signalLatency);
         }
-        if (_this5.isDisconnected) {
+        // `leave` is the one request whose purpose is to be sent on the way out (an aborted connect
+        // attempt tells the server before tearing down), so it is allowed through for as long as the
+        // transport is still there
+        const isLeaveOnShutdown = message.case === 'leave' && !!_this5.streamWriter;
+        if (_this5.isDisconnected && !isLeaveOnShutdown) {
           // Skip requests if the signal layer is disconnected
           // This can happen if an event is sent in the mist of room.connect() initializing
           _this5.log.debug("skipping signal request (type: ".concat(message.case, ") - SignalClient disconnected"));
@@ -17389,17 +18954,39 @@ class SignalClient {
       }
     }
   }
-  handleOnClose(reason) {
-    return __awaiter(this, void 0, void 0, function* () {
-      if (this.state === SignalConnectionState.DISCONNECTED) return;
-      const onCloseCallback = this.onClose;
-      yield this.close(undefined, reason);
-      this.log.info("websocket connection closed: ".concat(reason), {
-        reason
-      });
-      if (onCloseCallback) {
-        onCloseCallback(reason);
-      }
+  /**
+   * Handles a transport we lost without asking to. The client goes to `offline` rather than
+   * `closed`: whether this session gets resumed, restarted or given up on is the engine's call.
+   */
+  handleOnClose(reason_1) {
+    return __awaiter(this, arguments, void 0, function (reason) {
+      var _this6 = this;
+      let attemptId = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : this.attemptId;
+      return function* () {
+        const onCloseCallback = _this6.onClose;
+        if (!_this6.sendLifecycleInput({
+          type: 'transportFailed',
+          attemptId,
+          reason
+        })) {
+          // a close we caused ourselves, or one from a transport that has since been replaced: logged
+          // rather than dropped silently, because a close that goes unnoticed leaves the client writing
+          // to a dead socket
+          _this6.log.debug("ignoring transport close in state ".concat(_this6.lifecycleState), {
+            reason,
+            attemptId,
+            currentAttemptId: _this6.attemptId
+          });
+          return;
+        }
+        yield _this6.teardownTransport(reason);
+        _this6.log.info("websocket connection closed: ".concat(reason), {
+          reason
+        });
+        if (onCloseCallback) {
+          onCloseCallback(reason);
+        }
+      }();
     });
   }
   handleWSError(error) {
@@ -17456,10 +19043,27 @@ class SignalClient {
    * @param firstMessage Optional first message to process
    * @internal
    */
-  handleSignalConnected(connection, timeoutHandle, firstMessage) {
-    this.state = SignalConnectionState.CONNECTED;
-    this.log.info('signal connected');
+  handleSignalConnected(connection, timeoutHandle, attemptId, firstMessage) {
     clearTimeout(timeoutHandle);
+    const established = this.sendLifecycleInput(this.lifecycleState === 'reconnecting' ? {
+      type: 'reconnectComplete',
+      attemptId
+    } : {
+      type: 'connectComplete',
+      attemptId
+    });
+    if (!established) {
+      // The attempt was abandoned while we waited for the server's first message: it was closed, or
+      // a newer attempt superseded it. Arming the ping interval and the read loop here would outlive
+      // the session that owns them, so leave the transport to whoever holds the lifecycle now.
+      this.log.debug('discarding a connection whose attempt no longer owns the session', {
+        attemptId,
+        currentAttemptId: this.attemptId,
+        state: this.lifecycleState
+      });
+      return;
+    }
+    this.log.info('signal connected');
     this.startPingInterval();
     this.startReadingLoop(connection.readable.getReader(), firstMessage);
   }
@@ -17477,7 +19081,7 @@ class SignalClient {
         isValid: true,
         response: firstSignalResponse.message.value
       };
-    } else if (this.state === SignalConnectionState.RECONNECTING && ((_b = firstSignalResponse.message) === null || _b === void 0 ? void 0 : _b.case) !== 'leave') {
+    } else if (this.lifecycleState === 'reconnecting' && ((_b = firstSignalResponse.message) === null || _b === void 0 ? void 0 : _b.case) !== 'leave') {
       if (((_c = firstSignalResponse.message) === null || _c === void 0 ? void 0 : _c.case) === 'reconnect') {
         return {
           isValid: true,
@@ -18968,8 +20572,10 @@ class PCTransport extends eventsExports.EventEmitter {
     var _a;
     return (_a = this.pc) === null || _a === void 0 ? void 0 : _a.remoteDescription;
   }
+  /** stats of the underlying connection, `undefined` when there is none */
   getStats() {
-    return this.pc.getStats();
+    var _a;
+    return (_a = this._pc) === null || _a === void 0 ? void 0 : _a.getStats();
   }
   getMaxMessageSize() {
     var _a, _b;
@@ -19496,13 +21102,21 @@ class PCTransportManager {
       this.updateState();
     });
   }
+  /**
+   * Restarts ICE on the transports that need it. Only the publisher: the server restarts the
+   * subscriber's ICE itself and follows with a fresh offer.
+   *
+   * The subscriber deliberately does NOT enter `restartingIce` here. Queueing its remote
+   * candidates would guard against candidates for a new generation arriving before the offer
+   * that introduces it, but the server does not send them in that order -- on a same-node
+   * resume it buffers them until the offer has gone out, and on a reconnect that lands on
+   * another node it withholds subscriber candidates until immediately before creating the
+   * offer. Setting the flag only risks withholding candidates during the window that decides
+   * whether the reconnect succeeded.
+   */
   triggerIceRestart() {
     return __awaiter(this, void 0, void 0, function* () {
       this.iceLog.warn('triggering ICE restart');
-      if (this.subscriber) {
-        this.subscriber.restartingIce = true;
-      }
-      // only restart publisher if it's needed
       if (this.needsPublisher) {
         yield this.createAndSendPublisherOffer({
           iceRestart: true
@@ -21259,12 +22873,17 @@ class LocalTrack extends Track {
             type: 'audio',
             streamId: v.id,
             packetsSent: v.packetsSent,
-            packetsLost: v.packetsLost,
             bytesSent: v.bytesSent,
-            timestamp: v.timestamp,
-            roundTripTime: v.roundTripTime,
-            jitter: v.jitter
+            timestamp: v.timestamp
           };
+          // loss, jitter and RTT are only known from what the remote reports back,
+          // the same way the video sender picks them up
+          const remote = stats.get(v.remoteId);
+          if (remote) {
+            audioStats.packetsLost = remote.packetsLost;
+            audioStats.jitter = remote.jitter;
+            audioStats.roundTripTime = remote.roundTripTime;
+          }
         }
       });
       return audioStats;
@@ -22606,7 +24225,7 @@ class RTCEngine extends eventsExports.EventEmitter {
       const disconnect = duration => {
         this.log.warn("could not recover connection after ".concat(this.reconnectAttempts, " attempts, ").concat(duration, "ms. giving up"));
         this.emit(EngineEvent.Disconnected);
-        this.close();
+        this.close("gave up reconnecting after ".concat(this.reconnectAttempts, " attempts, ").concat(duration, "ms"));
       };
       const duration = Date.now() - this.reconnectStart;
       let delay = this.getNextRetryDelay({
@@ -22847,7 +24466,12 @@ class RTCEngine extends eventsExports.EventEmitter {
       }();
     });
   }
-  close() {
+  /**
+   * @param reason why the session is ending, recorded by the signal lifecycle. Worth passing
+   * wherever the caller knows more than "someone called close" — the server's leave reason, or
+   * having given up on reconnecting.
+   */
+  close(reason) {
     return __awaiter(this, void 0, void 0, function* () {
       const unlock = yield this.closingLock.lock();
       if (this.isClosed) {
@@ -22864,7 +24488,7 @@ class RTCEngine extends eventsExports.EventEmitter {
         this.clearLostQualityTimeout();
         this.cleanupLossyDataStats();
         yield this.cleanupPeerConnections();
-        yield this.cleanupClient();
+        yield this.cleanupClient(reason);
       } finally {
         unlock();
       }
@@ -22884,9 +24508,9 @@ class RTCEngine extends eventsExports.EventEmitter {
   cleanupLossyDataStats() {
     this.lossyChannel.stopThresholdTuning();
   }
-  cleanupClient() {
+  cleanupClient(reason) {
     return __awaiter(this, void 0, void 0, function* () {
-      yield this.client.close();
+      yield this.client.close(true, reason);
       this.client.resetCallbacks();
       // Any in-flight addTrack requests are orphaned by the signal reconnect — the new session
       // won't deliver `trackPublishedResponse` for them, so reject the pending resolvers and
@@ -23121,6 +24745,7 @@ class RTCEngine extends eventsExports.EventEmitter {
       this.handleDisconnect('signal', ReconnectReason.RR_SIGNAL_DISCONNECTED);
     };
     this.client.onLeave = leave => {
+      var _a;
       this.log.info("client leave request received (action=".concat(leave === null || leave === void 0 ? void 0 : leave.action, ")"), {
         reason: leave === null || leave === void 0 ? void 0 : leave.reason
       });
@@ -23131,7 +24756,7 @@ class RTCEngine extends eventsExports.EventEmitter {
       switch (leave.action) {
         case LeaveRequest_Action.DISCONNECT:
           this.emit(EngineEvent.Disconnected, leave === null || leave === void 0 ? void 0 : leave.reason);
-          this.close();
+          this.close("server leave: ".concat((_a = DisconnectReason[leave.reason]) !== null && _a !== void 0 ? _a : leave.reason));
           break;
         case LeaveRequest_Action.RECONNECT:
           this.fullReconnectOnNext = true;
@@ -23486,7 +25111,7 @@ class RTCEngine extends eventsExports.EventEmitter {
         } else {
           this.log.info("could not recover connection after ".concat(this.reconnectAttempts, " attempts, ").concat(Date.now() - this.reconnectStart, "ms. giving up"));
           this.emit(EngineEvent.Disconnected);
-          yield this.close();
+          yield this.close("gave up reconnecting after ".concat(this.reconnectAttempts, " attempts, ").concat(Date.now() - this.reconnectStart, "ms"));
         }
       } finally {
         this.attemptingReconnect = false;
@@ -24322,8 +25947,11 @@ const DEFAULT_MAX_PAYLOAD_BYTE_LENGTH = 5000000000;class BaseStreamReader {
     this._info = info;
     this.bytesReceived = 0;
   }
-}
-class ByteStreamReader extends BaseStreamReader {
+  /**
+   * Counts a chunk's bytes against `totalByteSize` and reports progress. Chunk ordering and
+   * de-duplication happen upstream in the manager's `ensureOrderedChunks`, so every chunk reaching
+   * here is new and in order.
+   */
   handleChunkReceived(chunk) {
     var _a;
     this.bytesReceived += chunk.content.byteLength;
@@ -24331,6 +25959,8 @@ class ByteStreamReader extends BaseStreamReader {
     const currentProgress = this.totalByteSize ? this.bytesReceived / this.totalByteSize : undefined;
     (_a = this.onProgress) === null || _a === void 0 ? void 0 : _a.call(this, currentProgress);
   }
+}
+class ByteStreamReader extends BaseStreamReader {
   [Symbol.asyncIterator]() {
     const reader = this.reader.getReader();
     // Suppress unhandled rejection on reader.closed — errors are
@@ -24438,35 +26068,18 @@ class ByteStreamReader extends BaseStreamReader {
   }
 }
 /**
- * A class to read chunks from a ReadableStream and provide them in a structured format.
+ * A class to read chunks from a ReadableStream and decode them as UTF-8 text.
+ *
+ * NOTE: chunk-level `version` (resending a chunk at an already-received `chunkIndex` to supersede
+ * it) is not supported. The reader used to rebuild the whole string from a per-index chunk map and
+ * yield it as `TextStreamChunk.collected`, which made superseding work; 5d4a6346 (#1410, text auto
+ * chunking) changed the iterator to yield each chunk's text as it arrives, and a streaming reader
+ * cannot retract text it has already handed to the consumer. No sender emits a versioned chunk.
  */
 class TextStreamReader extends BaseStreamReader {
-  /**
-   * A TextStreamReader instance can be used as an AsyncIterator that returns the entire string
-   * that has been received up to the current point in time.
-   */
-  constructor(info, stream, totalChunkCount) {
-    super(info, stream, totalChunkCount);
-    this.receivedChunks = new Map();
-  }
-  handleChunkReceived(chunk) {
-    var _a;
-    const index = bigIntToNumber(chunk.chunkIndex);
-    const previousChunkAtIndex = this.receivedChunks.get(index);
-    if (previousChunkAtIndex && previousChunkAtIndex.version > chunk.version) {
-      // we have a newer version already, dropping the old one
-      return;
-    }
-    this.receivedChunks.set(index, chunk);
-    this.bytesReceived += chunk.content.byteLength;
-    this.validateBytesReceived();
-    const currentProgress = this.totalByteSize ? this.bytesReceived / this.totalByteSize : undefined;
-    (_a = this.onProgress) === null || _a === void 0 ? void 0 : _a.call(this, currentProgress);
-  }
   /**
    * Async iterator implementation to allow usage of `for await...of` syntax.
-   * Yields structured chunks from the stream.
-   *
+   * Yields each chunk's decoded text as it arrives - a delta, not the string accumulated so far.
    */
   [Symbol.asyncIterator]() {
     const reader = this.reader.getReader();
@@ -24737,7 +26350,7 @@ class TextStreamReader extends BaseStreamReader {
               });
             }
           });
-          streamHandlerCallback(new ByteStreamReader(info, compressed ? inflateRawByteChunkStream(stream, streamHeader.streamId, this.maxPayloadByteLength) : stream,
+          streamHandlerCallback(new ByteStreamReader(info, compressed ? inflateRawByteChunkStream(stream, streamHeader.streamId, this.maxPayloadByteLength) : stream.pipeThrough(ensureOrderedChunks(streamHeader.streamId)),
           // `totalLength` is the pre-compression size, and the reader counts decompressed bytes,
           // so it applies to both paths (mirrors text).
           bigIntToNumber(streamHeader.totalLength)), {
@@ -24809,7 +26422,7 @@ class TextStreamReader extends BaseStreamReader {
               });
             }
           });
-          streamHandlerCallback(new TextStreamReader(info, compressed ? inflateRawChunkStream(stream, streamHeader.streamId, this.maxPayloadByteLength) : stream,
+          streamHandlerCallback(new TextStreamReader(info, compressed ? inflateRawChunkStream(stream, streamHeader.streamId, this.maxPayloadByteLength) : stream.pipeThrough(ensureOrderedChunks(streamHeader.streamId)),
           // `totalLength` is the pre-compression size, and the reader sees decompressed bytes, so
           // it applies to both paths.
           bigIntToNumber(streamHeader.totalLength)), {
@@ -24825,7 +26438,7 @@ class TextStreamReader extends BaseStreamReader {
       if (fileBuffer.info.encryptionType !== encryptionType) {
         fileBuffer.controller.error(new DataStreamError("Encryption type mismatch for stream ".concat(chunk.streamId, ". Expected ").concat(encryptionType, ", got ").concat(fileBuffer.info.encryptionType), DataStreamErrorReason.EncryptionTypeMismatch));
         this.byteStreamControllers.delete(chunk.streamId);
-      } else if (chunk.content.length > 0) {
+      } else {
         fileBuffer.controller.enqueue(chunk);
       }
     }
@@ -24834,7 +26447,7 @@ class TextStreamReader extends BaseStreamReader {
       if (textBuffer.info.encryptionType !== encryptionType) {
         textBuffer.controller.error(new DataStreamError("Encryption type mismatch for stream ".concat(chunk.streamId, ". Expected ").concat(encryptionType, ", got ").concat(textBuffer.info.encryptionType), DataStreamErrorReason.EncryptionTypeMismatch));
         this.textStreamControllers.delete(chunk.streamId);
-      } else if (chunk.content.length > 0) {
+      } else {
         textBuffer.controller.enqueue(chunk);
       }
     }
@@ -24882,26 +26495,24 @@ class TextStreamReader extends BaseStreamReader {
 function createInlineStream(streamId, content) {
   return new ReadableStream({
     start: controller => __awaiter(this, void 0, void 0, function* () {
-      try {
-        const bytes = yield content;
-        controller.enqueue(new DataStream_Chunk({
-          streamId,
-          chunkIndex: BigInt(0),
-          content: bytes
-        }));
-        controller.close();
-      } catch (err) {
-        controller.error(err);
-      }
+      const bytes = yield content;
+      controller.enqueue(new DataStream_Chunk({
+        streamId,
+        chunkIndex: BigInt(0),
+        content: bytes
+      }));
+      controller.close();
     })
   });
 }
 /**
  * Validates that chunks are received in order, dropping duplicates and throwing if gaps are found.
  *
- * A stateful decompressor silently corrupts on duplicated or out-of-order input, so duplicates are
- * dropped (with a warning - in-order delivery is expected on the reliable channel, but reconnect
- * handling may replay) and a gap is a hard error. Shared by the text and byte deflate-raw decoders.
+ * Reassembly (and, for compressed streams, a stateful decompressor) silently corrupts on duplicated
+ * or out-of-order input, so duplicates are dropped (with a warning - in-order delivery is expected
+ * on the reliable channel, but reconnect handling may replay) and a gap is a hard error. Empty
+ * chunks consume their index and are then dropped, so they never reach the reader. Applied to every
+ * chunked stream, compressed or not.
  */
 function ensureOrderedChunks(streamId) {
   let lastChunkIndex = -1;
@@ -24909,13 +26520,16 @@ function ensureOrderedChunks(streamId) {
     transform: (value, controller) => {
       const index = bigIntToNumber(value.chunkIndex);
       if (index <= lastChunkIndex) {
-        livekitLogger.warn("ignoring duplicate chunk ".concat(index, " for compressed data stream ").concat(streamId, " (last processed: ").concat(lastChunkIndex, ")"));
+        livekitLogger.warn("ignoring duplicate chunk ".concat(index, " ").concat(value.version > 0 ? "(version ".concat(value.version, ")") : '', " for data stream ").concat(streamId, " (last processed: ").concat(lastChunkIndex, ")"));
         return;
       }
       if (index > lastChunkIndex + 1) {
-        throw new DataStreamError("Missing chunk(s) ".concat(lastChunkIndex + 1, "..").concat(index - 1, " for compressed data stream ").concat(streamId, " - cannot continue decompressing"), DataStreamErrorReason.Incomplete);
+        throw new DataStreamError("Missing chunk(s) ".concat(lastChunkIndex + 1, "..").concat(index - 1, " for data stream ").concat(streamId, " - cannot reassemble payload"), DataStreamErrorReason.Incomplete);
       }
       lastChunkIndex = index;
+      if (value.content.length === 0) {
+        return;
+      }
       controller.enqueue(value);
     }
   });
@@ -31731,6 +33345,7 @@ class DeferrableMap extends Map {
   ConnectionState["SignalReconnecting"] = "signalReconnecting";
 })(ConnectionState || (ConnectionState = {}));
 const CONNECTION_RECONCILE_FREQUENCY_MS = 4 * 1000;
+const STATS_LOG_FREQUENCY_MS = 30 * 1000;
 /**
  * In LiveKit, a room is the logical grouping for a list of participants.
  * Participants in a room can publish tracks, and subscribe to others' tracks.
@@ -31749,7 +33364,7 @@ class Room extends eventsExports.EventEmitter {
    */
   constructor(options) {
     var _this;
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b, _c, _d, _e, _f, _g;
     super();
     _this = this;
     this.state = ConnectionState.Disconnected;
@@ -31764,6 +33379,7 @@ class Room extends eventsExports.EventEmitter {
     this.e2eeStateMutex = new _();
     this.isVideoPlaybackBlocked = false;
     this.log = livekitLogger;
+    this.statsLog = livekitLogger;
     this.bufferedEvents = [];
     this.isResuming = false;
     this.pendingTrackAddedCallbacks = new Map();
@@ -32196,7 +33812,7 @@ class Room extends eventsExports.EventEmitter {
         let remoteParticipant = this.remoteParticipants.get(info.identity);
         // when it's disconnected, send updates
         if (info.state === ParticipantInfo_State.DISCONNECTED) {
-          this.handleParticipantDisconnected(info.identity, remoteParticipant);
+          this.handleParticipantDisconnected(info.identity, remoteParticipant, info.disconnectReason === DisconnectReason.UNKNOWN_REASON ? undefined : info.disconnectReason);
         } else {
           // create participant if doesn't exist
           this.getOrCreateParticipant(info.identity, info);
@@ -32448,6 +34064,34 @@ class Room extends eventsExports.EventEmitter {
     this.getAllRemoteParticipantIdentities = () => {
       return Array.from(this.remoteParticipants.keys());
     };
+    /**
+     * Dumps stats of both peer connections.
+     */
+    this.logWebRTCStats = () => __awaiter(this, void 0, void 0, function* () {
+      var _a, _b, _c, _d;
+      const pcManager = (_a = this.engine) === null || _a === void 0 ? void 0 : _a.pcManager;
+      if (!pcManager) {
+        return;
+      }
+      try {
+        const _yield$Promise$all = yield Promise.all([pcManager.publisher.getStats(), (_b = pcManager.subscriber) === null || _b === void 0 ? void 0 : _b.getStats()]),
+          _yield$Promise$all2 = _slicedToArray(_yield$Promise$all, 2),
+          publisher = _yield$Promise$all2[0],
+          subscriber = _yield$Promise$all2[1];
+        const publisherStats = publisher && summarizeStatsReport(publisher);
+        const subscriberStats = subscriber && summarizeStatsReport(subscriber);
+        this.statsLog.info("webrtc stats", {
+          publisher: publisherStats === null || publisherStats === void 0 ? void 0 : publisherStats.connection,
+          subscriber: subscriberStats === null || subscriberStats === void 0 ? void 0 : subscriberStats.connection,
+          inbound: [...((_c = publisherStats === null || publisherStats === void 0 ? void 0 : publisherStats.inbound) !== null && _c !== void 0 ? _c : []), ...((_d = subscriberStats === null || subscriberStats === void 0 ? void 0 : subscriberStats.inbound) !== null && _d !== void 0 ? _d : [])],
+          outbound: publisherStats === null || publisherStats === void 0 ? void 0 : publisherStats.outbound
+        });
+      } catch (error) {
+        this.statsLog.debug('could not collect webrtc stats', {
+          error
+        });
+      }
+    });
     this.onLocalParticipantMetadataChanged = metadata => {
       this.emit(RoomEvent.ParticipantMetadataChanged, metadata, this.localParticipant);
     };
@@ -32518,12 +34162,15 @@ class Room extends eventsExports.EventEmitter {
     this.sidToIdentity = new Map();
     this.options = Object.assign(Object.assign({}, roomOptionDefaults), options);
     this.log = getLogger((_a = this.options.loggerName) !== null && _a !== void 0 ? _a : LoggerNames.Room, () => this.logContext);
+    // its own logger name, so the stats dumps can be silenced or routed
+    // separately from the rest of the room's logs
+    this.statsLog = getLogger(LoggerNames.Stats, () => this.logContext);
     this.transcriptionReceivedTimes = new Map();
     this.options.audioCaptureDefaults = Object.assign(Object.assign({}, audioDefaults), options === null || options === void 0 ? void 0 : options.audioCaptureDefaults);
     this.options.videoCaptureDefaults = Object.assign(Object.assign({}, videoDefaults), options === null || options === void 0 ? void 0 : options.videoCaptureDefaults);
     this.options.publishDefaults = Object.assign(Object.assign({}, publishDefaults), options === null || options === void 0 ? void 0 : options.publishDefaults);
     this.maybeCreateEngine();
-    this.incomingDataStreamManager = new IncomingDataStreamManager();
+    this.incomingDataStreamManager = new IncomingDataStreamManager((_b = this.options.dataStream) === null || _b === void 0 ? void 0 : _b.maxPayloadByteLength);
     this.outgoingDataStreamManager = new OutgoingDataStreamManager(this.engine, this.log, this.getRemoteParticipantClientProtocol, this.getRemoteParticipantCapabilities, this.getAllRemoteParticipantIdentities);
     this.incomingDataTrackManager = new IncomingDataTrackManager({
       e2eeManager: this.e2eeManager
@@ -32586,15 +34233,15 @@ class Room extends eventsExports.EventEmitter {
       this.setupE2EE();
     }
     this.engine.e2eeManager = this.e2eeManager;
-    this.incomingDataTrackManager.updateE2eeManager((_b = this.e2eeManager) !== null && _b !== void 0 ? _b : null);
-    this.outgoingDataTrackManager.updateE2eeManager((_c = this.e2eeManager) !== null && _c !== void 0 ? _c : null);
+    this.incomingDataTrackManager.updateE2eeManager((_c = this.e2eeManager) !== null && _c !== void 0 ? _c : null);
+    this.outgoingDataTrackManager.updateE2eeManager((_d = this.e2eeManager) !== null && _d !== void 0 ? _d : null);
     if (this.options.videoCaptureDefaults.deviceId) {
       this.localParticipant.activeDeviceMap.set('videoinput', unwrapConstraint(this.options.videoCaptureDefaults.deviceId));
     }
     if (this.options.audioCaptureDefaults.deviceId) {
       this.localParticipant.activeDeviceMap.set('audioinput', unwrapConstraint(this.options.audioCaptureDefaults.deviceId));
     }
-    if ((_d = this.options.audioOutput) === null || _d === void 0 ? void 0 : _d.deviceId) {
+    if ((_e = this.options.audioOutput) === null || _e === void 0 ? void 0 : _e.deviceId) {
       this.switchActiveDevice('audiooutput', unwrapConstraint(this.options.audioOutput.deviceId)).catch(e => this.log.warn("Could not set audio output: ".concat(e.message)));
     }
     if (isWeb()) {
@@ -32621,7 +34268,7 @@ class Room extends eventsExports.EventEmitter {
         onDeviceChange = this.handleDeviceChange;
       }
       // in order to catch device changes prior to room connection we need to register the event in the constructor
-      (_f = (_e = navigator.mediaDevices) === null || _e === void 0 ? void 0 : _e.addEventListener) === null || _f === void 0 ? void 0 : _f.call(_e, 'devicechange', onDeviceChange, {
+      (_g = (_f = navigator.mediaDevices) === null || _f === void 0 ? void 0 : _f.addEventListener) === null || _g === void 0 ? void 0 : _g.call(_f, 'devicechange', onDeviceChange, {
         signal: cleanupController.signal
       });
     }
@@ -33442,7 +35089,7 @@ class Room extends eventsExports.EventEmitter {
       this.emit(RoomEvent.Disconnected, reason);
     }
   }
-  handleParticipantDisconnected(identity, participant) {
+  handleParticipantDisconnected(identity, participant, disconnectReason) {
     // remove and send event
     this.remoteParticipants.delete(identity);
     if (!participant) {
@@ -33453,7 +35100,7 @@ class Room extends eventsExports.EventEmitter {
     participant.trackPublications.forEach(publication => {
       participant.unpublishTrack(publication.trackSid, true);
     });
-    this.emit(RoomEvent.ParticipantDisconnected, participant);
+    this.emit(RoomEvent.ParticipantDisconnected, participant, disconnectReason);
     participant.setDisconnected();
     this.rpcClientManager.handleParticipantDisconnected(participant.identity);
   }
@@ -33696,6 +35343,19 @@ class Room extends eventsExports.EventEmitter {
       }();
     }));
   }
+  setStatsLogging(enabled) {
+    if (enabled) {
+      if (!this.statsLogInterval) {
+        this.statsLogInterval = CriticalTimers.setInterval(() => {
+          // logWebRTCStats handles its own errors, nothing to await here
+          this.logWebRTCStats();
+        }, STATS_LOG_FREQUENCY_MS);
+      }
+    } else if (this.statsLogInterval) {
+      CriticalTimers.clearInterval(this.statsLogInterval);
+      this.statsLogInterval = undefined;
+    }
+  }
   registerConnectionReconcile() {
     this.clearConnectionReconcile();
     let consecutiveFailures = 0;
@@ -33746,6 +35406,7 @@ class Room extends eventsExports.EventEmitter {
     this.log.info("connection state changed: ".concat(this.state, " -> ").concat(state));
     this.state = state;
     this.incomingDataStreamManager.setConnected(state === ConnectionState.Connected);
+    this.setStatsLogging(state === ConnectionState.Connected);
     this.emit(RoomEvent.ConnectionStateChanged, this.state);
     return true;
   }
@@ -34918,15 +36579,22 @@ function isObject(input) {
 const ONE_MINUTE_IN_MILLISECONDS = 60 * ONE_SECOND_IN_MILLISECONDS;
 function isResponseTokenValid(response) {
   const jwtPayload = decodeTokenPayload(response.participantToken);
-  if (!(jwtPayload === null || jwtPayload === void 0 ? void 0 : jwtPayload.nbf) || !(jwtPayload === null || jwtPayload === void 0 ? void 0 : jwtPayload.exp)) {
-    return true;
+  // Missing exp: TokenSourceCached would otherwise return this response forever.
+  // nbf is optional (RFC 7519); do not skip the exp check when it is absent.
+  if (!(jwtPayload === null || jwtPayload === void 0 ? void 0 : jwtPayload.exp)) {
+    return false;
   }
   const now = new Date();
-  const nbfInMilliseconds = jwtPayload.nbf * ONE_SECOND_IN_MILLISECONDS;
-  const nbfDate = new Date(nbfInMilliseconds);
+  if (jwtPayload.nbf) {
+    const nbfInMilliseconds = jwtPayload.nbf * ONE_SECOND_IN_MILLISECONDS;
+    const nbfDate = new Date(nbfInMilliseconds);
+    if (nbfDate > now) {
+      return false;
+    }
+  }
   const expInMilliseconds = jwtPayload.exp * ONE_SECOND_IN_MILLISECONDS;
   const expDate = new Date(expInMilliseconds - ONE_MINUTE_IN_MILLISECONDS);
-  return nbfDate <= now && expDate > now;
+  return expDate > now;
 }
 /** Given a LiveKit generated participant token, decodes and returns the associated {@link TokenPayload} data. */
 function decodeTokenPayload(token) {
@@ -35313,4 +36981,4 @@ const serializers = {
   json,
   raw,
   custom
-};export{AudioPresets,BackupCodecPolicy,BaseKeyProvider,CLIENT_PROTOCOL_DATA_STREAM_RPC,CLIENT_PROTOCOL_DATA_STREAM_V2,CLIENT_PROTOCOL_DEFAULT,CheckStatus,Checker,ConnectionCheck,ConnectionError,ConnectionErrorReason,ConnectionQuality,ConnectionState,CriticalTimers,CryptorError,CryptorErrorReason,CryptorEvent,DataPacket_Kind,DataStreamError,DataStreamErrorReason,DataTrackPacket,DefaultReconnectPolicy,DeviceUnsupportedError,DisconnectReason,EncryptionEvent,Encryption_Type,EngineEvent,ExternalE2EEKeyProvider,FrameMetadataManager,KeyHandlerEvent,KeyProviderEvent,LivekitError,LivekitReasonedError,LocalAudioTrack,LocalDataTrack,LocalParticipant,LocalTrack,LocalTrackPublication,LocalTrackRecorder,LocalVideoTrack,LogLevel,LoggerNames,MediaDeviceFailure,_ as Mutex,NegotiationError,PacketTrailerManager,Participant,ParticipantEvent,ParticipantInfo_Kind as ParticipantKind,PublishDataError,PublishTrackError,RemoteAudioTrack,RemoteDataTrack,RemoteParticipant,RemoteTrack,RemoteTrackPublication,RemoteVideoTrack,Room,RoomEvent,RpcError,ScreenSharePresets,SignalReconnectError,SignalRequestError,SimulatedError,SubscriptionError,TokenSource,TokenSourceConfigurable,TokenSourceFixed,Track,TrackEvent,TrackInvalidError,TrackPublication,TrackType,UnexpectedConnectionState,UnsupportedServer,VideoPreset,VideoPresets,VideoPresets43,VideoQuality,areTokenSourceFetchOptionsEqual,asEncryptablePacket,attachToElement,attributeTypings as attributes,audioCodecs,clientProtocol,compareVersions,createAudioAnalyser,createE2EEKey,createKeyMaterialFromBuffer,createKeyMaterialFromString,createLocalAudioTrack,createLocalScreenTracks,createLocalTracks,createLocalVideoTrack,decodeTokenPayload,deriveKeys,detachTrack,facingModeFromDeviceLabel,facingModeFromLocalTrack,getBrowser,getEmptyAudioStreamTrack,getEmptyVideoStreamTrack,getLogger,importKey,isAudioCodec,isAudioTrack,isBackupCodec,isBackupVideoCodec,isBrowserSupported,isE2EESupported,isInsertableStreamSupported,isLocalParticipant,isLocalTrack,isRemoteParticipant,isRemoteTrack,isScriptTransformSupported,isSerializer,isVideoCodec,isVideoFrame,isVideoTrack,needsRbspUnescaping,parseRbsp,protocolVersion,ratchet,serializers,setLogExtension,setLogLevel,supportsAV1,supportsAdaptiveStream,supportsAudioOutputSelection,supportsDynacast,supportsVP9,version,videoCodecs,writeRbsp};//# sourceMappingURL=livekit-client.esm.mjs.map
+};export{AudioPresets,BackupCodecPolicy,BaseKeyProvider,CLIENT_PROTOCOL_DATA_STREAM_RPC,CLIENT_PROTOCOL_DATA_STREAM_V2,CLIENT_PROTOCOL_DEFAULT,CheckStatus,Checker,ConnectionCheck,ConnectionError,ConnectionErrorReason,ConnectionQuality,ConnectionState,CriticalTimers,CryptorError,CryptorErrorReason,CryptorEvent,DataPacket_Kind,DataStreamError,DataStreamErrorReason,DataTrackPacket,DefaultReconnectPolicy,DeviceUnsupportedError,DisconnectReason,EncryptionEvent,Encryption_Type,EngineEvent,ExternalE2EEKeyProvider,FrameMetadataManager,KeyHandlerEvent,KeyProviderEvent,LivekitError,LivekitReasonedError,LocalAudioTrack,LocalDataTrack,LocalParticipant,LocalTrack,LocalTrackPublication,LocalTrackRecorder,LocalVideoTrack,LogLevel,LoggerNames,MediaDeviceFailure,_ as Mutex,NegotiationError,PacketTrailerManager,Participant,ParticipantEvent,ParticipantInfo_Kind as ParticipantKind,PublishDataError,PublishTrackError,RemoteAudioTrack,RemoteDataTrack,RemoteParticipant,RemoteTrack,RemoteTrackPublication,RemoteVideoTrack,Room,RoomEvent,RpcError,ScreenSharePresets,SignalReconnectError,SignalRequestError,SimulatedError,SubscriptionError,TokenSource,TokenSourceConfigurable,TokenSourceFixed,Track,TrackEvent,TrackInvalidError,TrackPublication,TrackType,UnexpectedConnectionState,UnsupportedServer,VideoPreset,VideoPresets,VideoPresets43,VideoQuality,areTokenSourceFetchOptionsEqual,asEncryptablePacket,attachToElement,attributeTypings as attributes,audioCodecs,clientProtocol,compareVersions,createAudioAnalyser,createE2EEKey,createKeyMaterialFromBuffer,createKeyMaterialFromString,createLocalAudioTrack,createLocalScreenTracks,createLocalTracks,createLocalVideoTrack,decodeTokenPayload,deriveKeys,detachTrack,facingModeFromDeviceLabel,facingModeFromLocalTrack,getBrowser,getEmptyAudioStreamTrack,getEmptyVideoStreamTrack,getLogger,importKey,isAudioCodec,isAudioTrack,isBackupCodec,isBackupVideoCodec,isBrowserSupported,isE2EESupported,isInsertableStreamSupported,isLocalParticipant,isLocalTrack,isRemoteParticipant,isRemoteTrack,isSVCCodec,isScriptTransformSupported,isSerializer,isVideoCodec,isVideoFrame,isVideoTrack,needsRbspUnescaping,parseRbsp,protocolVersion,ratchet,serializers,setLogExtension,setLogLevel,supportsAV1,supportsAdaptiveStream,supportsAudioOutputSelection,supportsDynacast,supportsH265,supportsVP9,version,videoCodecs,writeRbsp};//# sourceMappingURL=livekit-client.esm.mjs.map