livekit-client 2.21.0 → 2.22.0

package/dist/livekit-client.esm.mjs

@@ -12160,7 +12160,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.21.0";const version = version$1;
+}var version$1 = "2.22.0";const version = version$1;
 const protocolVersion = 17;
 /** Initial client protocol. */
 const CLIENT_PROTOCOL_DEFAULT = 0;
@@ -13640,8 +13640,9 @@ class Track extends eventsExports.EventEmitter {
     if (this.monitorInterval) {
       clearInterval(this.monitorInterval);
     }
-    if (this.timeSyncHandle) {
+    if (this.timeSyncHandle !== undefined) {
       cancelAnimationFrame(this.timeSyncHandle);
+      this.timeSyncHandle = undefined;
     }
   }
   /** @internal */
@@ -13929,6 +13930,45 @@ function supportsVP9() {
 function isSVCCodec(codec) {
   return codec === 'av1' || codec === 'vp9';
 }
+/**
+ * Opts `transceiver` into negotiating the AV1 dependency descriptor, reporting whether it will be.
+ *
+ * Chrome only offers the extension on transceivers that can send, so one we create to receive on
+ * never negotiates it — and Chrome 152 stopped decoding AV1 that arrives without it: frames get
+ * assembled, none ever decode, and the receiver asks for a keyframe forever. Asking through the
+ * transceiver rather than munging the extension into the SDP leaves the browser owning the
+ * extension id, which is what keeps that id consistent across the bundle and across
+ * renegotiations.
+ *
+ * A no-op where the browser offers no such control, or does not know the extension at all.
+ * @internal
+ */
+function negotiateDependencyDescriptor(transceiver) {
+  var _a;
+  const extensions = (_a = transceiver.getHeaderExtensionsToNegotiate) === null || _a === void 0 ? void 0 : _a.call(transceiver);
+  if (!extensions || !transceiver.setHeaderExtensionsToNegotiate) {
+    return false;
+  }
+  const dd = extensions.find(ext => ext.uri === ddExtensionURI);
+  if (!dd) {
+    return false;
+  }
+  if (dd.direction !== 'stopped') {
+    return true;
+  }
+  // sendrecv rather than recvonly, so that the extension is written as a plain `a=extmap` line —
+  // the form the server already emits where it is the one offering — rather than one carrying a
+  // `/recvonly` suffix that its parser may not expect
+  dd.direction = 'sendrecv';
+  try {
+    transceiver.setHeaderExtensionsToNegotiate(extensions);
+    return true;
+  } catch (e) {
+    // a rejected direction throws. Negotiating without the extension is what happened before this
+    // existed, so it is not worth failing the connection over
+    return false;
+  }
+}
 function supportsSetSinkId(elm) {
   if (!document || isSafariBased()) {
     return false;
@@ -14470,6 +14510,17 @@ function isCompressionStreamSupported() {
 function isPublisherOfferWithJoinSupported() {
   // we have connectivity issue about publisher offer with join on firefox #1919
   return isCompressionStreamSupported() && !isFireFox();
+}
+function extractTrackSid(mediaTrack, stream) {
+  const _unpackStreamId = unpackStreamId(stream.id),
+    _unpackStreamId2 = _slicedToArray(_unpackStreamId, 2),
+    streamId = _unpackStreamId2[1];
+  if (streamId === null || streamId === void 0 ? void 0 : streamId.startsWith('TR')) {
+    return streamId;
+  }
+  if (mediaTrack.id.startsWith('TR')) {
+    return mediaTrack.id;
+  }
 }function createRtcUrl(url, searchParams) {
   let useV0Path = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
   const v0Url = createV0RtcUrl(url, searchParams);
@@ -14968,6 +15019,34 @@ function computeBitrate(currentStats, prevStats) {
 }class RemoteTrack extends Track {
   constructor(mediaTrack, sid, kind, receiver, loggerOptions) {
     super(mediaTrack, kind, loggerOptions);
+    this.timeSyncLoop = () => {
+      var _a;
+      if (this.listenerCount(TrackEvent.TimeSyncUpdate) === 0) {
+        // nobody is listening anymore, pause the loop until a new listener subscribes
+        this.timeSyncHandle = undefined;
+        return;
+      }
+      this.timeSyncHandle = requestAnimationFrame(this.timeSyncLoop);
+      const sources = (_a = this.receiver) === null || _a === void 0 ? void 0 : _a.getSynchronizationSources()[0];
+      if (sources) {
+        const timestamp = sources.timestamp,
+          rtpTimestamp = sources.rtpTimestamp;
+        if (rtpTimestamp && this.rtpTimestamp !== rtpTimestamp) {
+          this.emit(TrackEvent.TimeSyncUpdate, {
+            timestamp,
+            rtpTimestamp
+          });
+          this.rtpTimestamp = rtpTimestamp;
+        }
+      }
+    };
+    this.onTimeSyncListenerAdded = event => {
+      if (event === TrackEvent.TimeSyncUpdate && this.timeSyncHandle === undefined) {
+        // `newListener` fires before the listener is registered, so schedule the
+        // next frame instead of entering the loop (which would see a count of 0)
+        this.timeSyncHandle = requestAnimationFrame(this.timeSyncLoop);
+      }
+    };
     this.sid = sid;
     this.receiver = receiver;
   }
@@ -15065,24 +15144,19 @@ function computeBitrate(currentStats, prevStats) {
       this.registerTimeSyncUpdate();
     }
   }
+  /* @internal */
+  stopMonitor() {
+    super.stopMonitor();
+    this.off('newListener', this.onTimeSyncListenerAdded);
+  }
   registerTimeSyncUpdate() {
-    const loop = () => {
-      var _a;
-      this.timeSyncHandle = requestAnimationFrame(() => loop());
-      const sources = (_a = this.receiver) === null || _a === void 0 ? void 0 : _a.getSynchronizationSources()[0];
-      if (sources) {
-        const timestamp = sources.timestamp,
-          rtpTimestamp = sources.rtpTimestamp;
-        if (rtpTimestamp && this.rtpTimestamp !== rtpTimestamp) {
-          this.emit(TrackEvent.TimeSyncUpdate, {
-            timestamp,
-            rtpTimestamp
-          });
-          this.rtpTimestamp = rtpTimestamp;
-        }
-      }
-    };
-    loop();
+    // `newListener` isn't part of the typed event map, hence the cast
+    const emitter = this;
+    emitter.off('newListener', this.onTimeSyncListenerAdded);
+    emitter.on('newListener', this.onTimeSyncListenerAdded);
+    if (this.timeSyncHandle === undefined) {
+      this.timeSyncLoop();
+    }
   }
 }const REACTION_DELAY = 100;
 class RemoteVideoTrack extends RemoteTrack {
@@ -18392,6 +18466,51 @@ const startBitrateMultiplier = 0.9;
 /** Maximum x-google-start-bitrate in kbps. 1 Mbps prevents BWE from starting too aggressively. */
 const maxStartBitrateKbps = 1000;
 const debounceInterval = 20;
+/**
+ * Applies the configured start bitrate when this media section belongs to `cid`.
+ * This SDP munging is used for a bitrate setting that cannot be applied through
+ * `RTCRtpEncodingParameters`.
+ *
+ * Returns `undefined` when the section does not belong to the track, `0` when
+ * it does but does not offer the requested codec, and the codec payload when the
+ * requested codec is present (whether the bitrate was added or already set).
+ *
+ * @internal
+ */
+function applyVideoStartBitrate(media, cid, codec, maxbr) {
+  let isScreenShare = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
+  var _a, _b, _c;
+  if (!((_a = media.msid) === null || _a === void 0 ? void 0 : _a.includes(cid))) {
+    return undefined;
+  }
+  const codecPayload = (_c = (_b = media.rtp.find(rtp => rtp.codec.toUpperCase() === codec.toUpperCase())) === null || _b === void 0 ? void 0 : _b.payload) !== null && _c !== void 0 ? _c : 0;
+  if (codecPayload === 0) {
+    return 0;
+  }
+  // Use 90% of target bitrate, capped at 1 Mbps for camera to prevent BWE
+  // from starting too aggressively. Screen share is not capped since text/UI
+  // clarity requires high bitrate from the start.
+  // TODO: dynamically adjust start bitrate based on network conditions (e.g., previous BWE estimate)
+  const calculatedStartBitrate = Math.round(maxbr * startBitrateMultiplier);
+  const startBitrate = isScreenShare ? calculatedStartBitrate : Math.min(calculatedStartBitrate, maxStartBitrateKbps);
+  const fmtp = media.fmtp.find(entry => entry.payload === codecPayload);
+  if (fmtp) {
+    // If another track's fmtp already has a start bitrate, it cannot be
+    // overridden here because the payload type is shared across the bundle.
+    // This forces every track sharing that payload to use the initial track's
+    // start bitrate.
+    if (!fmtp.config.includes('x-google-start-bitrate')) {
+      fmtp.config += ";x-google-start-bitrate=".concat(startBitrate);
+    }
+  } else {
+    // VP8 and some codecs may not have an existing fmtp line.
+    media.fmtp.push({
+      payload: codecPayload,
+      config: "x-google-start-bitrate=".concat(startBitrate)
+    });
+  }
+  return codecPayload;
+}
 const PCEvents = {
   NegotiationStarted: 'negotiationStarted',
   NegotiationComplete: 'negotiationComplete',
@@ -18693,9 +18812,13 @@ class PCTransport extends eventsExports.EventEmitter {
           // the only exception to this is when ICE restart is needed
           const currentSD = this._pc.remoteDescription;
           if ((options === null || options === void 0 ? void 0 : options.iceRestart) && currentSD) {
-            // TODO: handle when ICE restart is needed but we don't have a remote description
-            // the best thing to do is to recreate the peerconnection
+            // roll the remote description back in so createOffer produces a valid
+            // ICE-restart offer on top of the already-negotiated state
             yield this._pc.setRemoteDescription(currentSD);
+          } else if (options === null || options === void 0 ? void 0 : options.iceRestart) {
+            // ICE restart with no remote description to restart on: `renegotiate` would stall
+            // (the pending offer is never answered), so throw for the caller to recreate the PC.
+            throw new NegotiationError('ICE restart requested without a remote description, peer connection must be recreated');
           } else {
             this.renegotiate = true;
             this.log.debug('requesting renegotiation');
@@ -18721,48 +18844,15 @@ class PCTransport extends eventsExports.EventEmitter {
             ensureAudioNackAndStereo(media, ['all'], []);
           } else if (media.type === 'video') {
             this.trackBitrates.some(trackbr => {
-              if (!media.msid || !trackbr.cid || !media.msid.includes(trackbr.cid)) {
+              if (!trackbr.cid) {
                 return false;
               }
-              let codecPayload = 0;
-              media.rtp.some(rtp => {
-                if (rtp.codec.toUpperCase() === trackbr.codec.toUpperCase()) {
-                  codecPayload = rtp.payload;
-                  return true;
-                }
+              const codecPayload = applyVideoStartBitrate(media, trackbr.cid, trackbr.codec, trackbr.maxbr, trackbr.isScreenShare);
+              if (codecPayload === undefined) {
                 return false;
-              });
-              if (codecPayload === 0) {
-                return true;
-              }
-              if (isSVCCodec(trackbr.codec) && !isSafari()) {
-                this.ensureVideoDDExtensionForSVC(media, sdpParsed);
               }
-              // mung sdp for bitrate setting that can't apply by sendEncoding
-              // Use 90% of target bitrate, capped at 1 Mbps for camera to prevent BWE from starting too aggressively
-              // Screen share is not capped since text/UI clarity requires high bitrate from the start
-              // TODO: dynamically adjust start bitrate based on network conditions (e.g., use previous BWE estimate)
-              const calculatedStartBitrate = Math.round(trackbr.maxbr * startBitrateMultiplier);
-              const startBitrate = trackbr.isScreenShare ? calculatedStartBitrate : Math.min(calculatedStartBitrate, maxStartBitrateKbps);
-              let fmtpFound = false;
-              for (const fmtp of media.fmtp) {
-                if (fmtp.payload === codecPayload) {
-                  fmtpFound = true;
-                  // if another track's fmtp already is set, we cannot override the bitrate
-                  // this has the unfortunate consequence of being forced to use the
-                  // initial track's bitrate for all tracks
-                  if (!fmtp.config.includes('x-google-start-bitrate')) {
-                    fmtp.config += ";x-google-start-bitrate=".concat(startBitrate);
-                  }
-                  break;
-                }
-              }
-              // VP8 and some codecs may not have an existing fmtp line - create one
-              if (!fmtpFound) {
-                media.fmtp.push({
-                  payload: codecPayload,
-                  config: "x-google-start-bitrate=".concat(startBitrate)
-                });
+              if (codecPayload > 0 && isSVCCodec(trackbr.codec) && !isSafari()) {
+                this.ddExtID = ensureVideoDDExtension(media, sdpParsed, this.ddExtID);
               }
               return true;
             });
@@ -18975,41 +19065,106 @@ class PCTransport extends eventsExports.EventEmitter {
       }
     });
   }
-  ensureVideoDDExtensionForSVC(media, sdp) {
-    var _a, _b;
-    const ddFound = (_a = media.ext) === null || _a === void 0 ? void 0 : _a.some(ext => {
-      if (ext.uri === ddExtensionURI) {
-        return true;
-      }
-      return false;
+}
+/**
+ * Adds the AV1 dependency descriptor extension to `media` unless it is already there, and
+ * returns the id it is mapped to so callers can pass it back in as `ddExtID` (0 when no id has
+ * been chosen yet).
+ *
+ * A bundle has to map one URI to one id, so an id already in use for the extension anywhere in
+ * `sdp` wins over both the cached one and a fresh one: Chrome advertises the extension itself on
+ * sections it can send on, and an earlier offer may have munged it into others.
+ * @internal
+ */
+function ensureVideoDDExtension(media, sdp, ddExtID) {
+  var _a, _b;
+  const id = ddExtensionIDFor(sdp, ddExtID);
+  if (id === undefined) {
+    return ddExtID;
+  }
+  if (!((_a = media.ext) === null || _a === void 0 ? void 0 : _a.some(ext => ext.uri === ddExtensionURI))) {
+    (_b = media.ext) !== null && _b !== void 0 ? _b : media.ext = [];
+    media.ext.push({
+      value: id,
+      uri: ddExtensionURI
     });
-    if (!ddFound) {
-      if (this.ddExtID === 0) {
-        let maxID = 0;
-        sdp.media.forEach(m => {
-          var _a;
-          (_a = m.ext) === null || _a === void 0 ? void 0 : _a.forEach(ext => {
-            if (ext.value > maxID) {
-              maxID = ext.value;
-            }
-          });
-        });
-        this.ddExtID = maxID + 1;
-      }
-      (_b = media.ext) === null || _b === void 0 ? void 0 : _b.push({
-        value: this.ddExtID,
-        uri: ddExtensionURI
-      });
+  }
+  return id;
+}
+/**
+ * The id to map the dependency descriptor to throughout `sdp`, or undefined when no id would be
+ * consistent for the whole bundle and the extension therefore has to be left out.
+ */
+function ddExtensionIDFor(sdp, cachedID) {
+  const mapped = mappedExtensionID(sdp, ddExtensionURI);
+  if (mapped !== undefined) {
+    // Adopting an id that also stands for another URI is what the browser rejects the bundle
+    // over, and its own half of the map is not ours to renumber, so give up on this offer.
+    return usedForOtherURI(sdp, mapped, ddExtensionURI) ? undefined : mapped;
+  }
+  // Reusing the id from the last offer keeps the mapping stable across renegotiations, but only
+  // while nothing else has taken it: the browser assigns ids to its own extensions without
+  // knowing about ours, so an id that was free when we picked it can since have been claimed —
+  // typically by the fuller extension set that arrives with the first section we send on.
+  if (cachedID !== 0 && !usedForOtherURI(sdp, cachedID, ddExtensionURI)) {
+    return cachedID;
+  }
+  return unusedExtensionID(sdp);
+}
+/** The id `uri` is mapped to in `sdp`, if any section maps it. */
+function mappedExtensionID(sdp, uri) {
+  var _a;
+  for (const media of sdp.media) {
+    const ext = (_a = media.ext) === null || _a === void 0 ? void 0 : _a.find(candidate => candidate.uri === uri);
+    if (ext) {
+      return ext.value;
     }
   }
+  return undefined;
+}
+/** Whether `id` stands for anything in `sdp` other than `uri`. */
+function usedForOtherURI(sdp, id, uri) {
+  return sdp.media.some(media => {
+    var _a;
+    return (_a = media.ext) === null || _a === void 0 ? void 0 : _a.some(ext => ext.value === id && ext.uri !== uri);
+  });
 }
+/**
+ * An id no extension in `sdp` uses. Stays above every id in use rather than filling gaps, so it
+ * is less likely to be an id the browser goes on to allocate to another extension, and steps
+ * over 15, which RFC 8285 reserves.
+ */
+function unusedExtensionID(sdp) {
+  let maxID = 0;
+  sdp.media.forEach(media => {
+    var _a;
+    (_a = media.ext) === null || _a === void 0 ? void 0 : _a.forEach(ext => {
+      if (ext.value > maxID) {
+        maxID = ext.value;
+      }
+    });
+  });
+  return maxID + 1 === 15 ? 16 : maxID + 1;
+}
+/**
+ * Checks whether an fmtp config declares `param` as an exact, `;`-delimited
+ * token. A plain substring check conflates distinct opus parameters — e.g.
+ * `stereo=1` is a substring of `sprop-stereo=1` — so `param` must match a whole
+ * parameter, not appear anywhere within the config string.
+ * @internal
+ */
+function fmtpConfigHasParam(config, param) {
+  return config.split(';').some(entry => entry.trim() === param);
+}
+/** @internal */
 function ensureAudioNackAndStereo(media, stereoMids, nackMids) {
   // sdp-transform types don't include number however the parser outputs mids as numbers in some cases
   const mid = getMidString(media.mid);
   // found opus codec to add nack fb
   let opusPayload = 0;
   media.rtp.some(rtp => {
-    if (rtp.codec === 'opus') {
+    // rtpmap encoding names are case-insensitive (RFC 4855)
+    if (rtp.codec.toLowerCase() === 'opus') {
       opusPayload = rtp.payload;
       return true;
     }
@@ -19029,7 +19184,7 @@ function ensureAudioNackAndStereo(media, stereoMids, nackMids) {
     if (stereoMids.includes(mid) || stereoMids.length === 1 && stereoMids[0] === 'all') {
       media.fmtp.some(fmtp => {
         if (fmtp.payload === opusPayload) {
-          if (!fmtp.config.includes('stereo=1')) {
+          if (!fmtpConfigHasParam(fmtp.config, 'stereo=1')) {
             fmtp.config += ';stereo=1';
           }
           return true;
@@ -19112,6 +19267,7 @@ function conformBundledCodecFmtp(media, isPlaceholder) {
     }
   }
 }
+/** @internal */
 function extractStereoAndNackAudioFromOffer(offer) {
   var _a;
   const stereoMids = [];
@@ -19123,7 +19279,8 @@ function extractStereoAndNackAudioFromOffer(offer) {
     const mid = getMidString(media.mid);
     if (media.type === 'audio') {
       media.rtp.some(rtp => {
-        if (rtp.codec === 'opus') {
+        // rtpmap encoding names are case-insensitive (RFC 4855)
+        if (rtp.codec.toLowerCase() === 'opus') {
           opusPayload = rtp.payload;
           return true;
         }
@@ -19134,7 +19291,7 @@ function extractStereoAndNackAudioFromOffer(offer) {
       }
       media.fmtp.some(fmtp => {
         if (fmtp.payload === opusPayload) {
-          if (fmtp.config.includes('sprop-stereo=1')) {
+          if (fmtpConfigHasParam(fmtp.config, 'sprop-stereo=1')) {
             stereoMids.push(mid);
           }
           return true;
@@ -21927,17 +22084,37 @@ class LocalVideoTrack extends LocalTrack {
   setDegradationPreference(preference) {
     return __awaiter(this, void 0, void 0, function* () {
       this.degradationPreference = preference;
-      if (this.sender) {
-        try {
-          this.log.debug("setting degradationPreference to ".concat(preference), this.logContext);
-          const params = this.sender.getParameters();
-          params.degradationPreference = preference;
-          this.sender.setParameters(params);
-        } catch (e) {
-          this.log.warn("failed to set degradationPreference", Object.assign({
-            error: e
-          }, this.logContext));
-        }
+      // applied one sender at a time on purpose, see applyDegradationPreference
+      yield this.applyDegradationPreference(this.sender);
+      for (const sc of this.simulcastCodecs.values()) {
+        yield this.applyDegradationPreference(sc.sender);
+      }
+    });
+  }
+  /**
+   * Degradation preference is a property of the sender, not of the track, so every sender
+   * publishing this track needs it applied separately. A backup codec publishes over its
+   * own sender, which would otherwise let the browser resolve a preference implicitly and
+   * diverge from the primary encoder.
+   *
+   * Callers apply this sequentially rather than concurrently: `setParameters` is only valid
+   * against the parameters most recently returned by `getParameters`, which is why this file
+   * serializes other sender parameter updates through `senderLock`.
+   */
+  applyDegradationPreference(sender) {
+    return __awaiter(this, void 0, void 0, function* () {
+      if (!sender) {
+        return;
+      }
+      try {
+        this.log.debug("setting degradationPreference to ".concat(this.degradationPreference), this.logContext);
+        const params = sender.getParameters();
+        params.degradationPreference = this.degradationPreference;
+        yield sender.setParameters(params);
+      } catch (e) {
+        this.log.warn("failed to set degradationPreference", Object.assign({
+          error: e
+        }, this.logContext));
       }
     });
   }
@@ -21956,18 +22133,23 @@ class LocalVideoTrack extends LocalTrack {
     return simulcastCodecInfo;
   }
   setSimulcastTrackSender(codec, sender) {
-    const simulcastCodecInfo = this.simulcastCodecs.get(codec);
-    if (!simulcastCodecInfo) {
-      return;
-    }
-    simulcastCodecInfo.sender = sender;
-    // browser will reenable disabled codec/layers after new codec has been published,
-    // so refresh subscribedCodecs after publish a new codec
-    setTimeout(() => {
-      if (this.subscribedCodecs) {
-        this.setPublishingCodecs(this.subscribedCodecs);
+    return __awaiter(this, void 0, void 0, function* () {
+      const simulcastCodecInfo = this.simulcastCodecs.get(codec);
+      if (!simulcastCodecInfo) {
+        return;
       }
-    }, refreshSubscribedCodecAfterNewCodec);
+      simulcastCodecInfo.sender = sender;
+      // the backup codec publishes over its own sender, so it needs the same degradation
+      // preference the primary sender resolved to.
+      yield this.applyDegradationPreference(sender);
+      // browser will reenable disabled codec/layers after new codec has been published,
+      // so refresh subscribedCodecs after publish a new codec
+      setTimeout(() => {
+        if (this.subscribedCodecs) {
+          this.setPublishingCodecs(this.subscribedCodecs);
+        }
+      }, refreshSubscribedCodecAfterNewCodec);
+    });
   }
   /**
    * @internal
@@ -22239,6 +22421,11 @@ function videoLayersFromEncodings(width, height, encodings, svc) {
   });
 }const minReconnectWait = 2 * 1000;
 const leaveReconnect = 'leave-reconnect';
+/**
+ * How long local connection quality must stay `LOST` while connected and publishing before we
+ * force a full reconnect — `LOST` is the server's verdict that it isn't receiving our media.
+ */
+const connectionQualityLostTimeout = 10 * 1000;
 const reliabeReceiveStateTTL = 30000;
 const initialMediaSectionsAudio = 3;
 const initialMediaSectionsVideo = 3;
@@ -22528,7 +22715,10 @@ class RTCEngine extends eventsExports.EventEmitter {
       onBufferStatusChanged: (kind, isLow) => this.emit(EngineEvent.DCBufferStatusChanged, isLow, kind)
     });
     this.client.onParticipantUpdate = updates => this.emit(EngineEvent.ParticipantUpdate, updates);
-    this.client.onConnectionQuality = update => this.emit(EngineEvent.ConnectionQualityUpdate, update);
+    this.client.onConnectionQuality = update => {
+      this.handleLocalConnectionQuality(update);
+      this.emit(EngineEvent.ConnectionQualityUpdate, update);
+    };
     this.client.onRoomUpdate = update => this.emit(EngineEvent.RoomUpdate, update);
     this.client.onSubscriptionError = resp => this.emit(EngineEvent.SubscriptionError, resp);
     this.client.onSubscriptionPermissionUpdate = update => this.emit(EngineEvent.SubscriptionPermissionUpdate, update);
@@ -22671,6 +22861,7 @@ class RTCEngine extends eventsExports.EventEmitter {
         this.removeAllListeners();
         this.deregisterOnLineListener();
         this.clearPendingReconnect();
+        this.clearLostQualityTimeout();
         this.cleanupLossyDataStats();
         yield this.cleanupPeerConnections();
         yield this.cleanupClient();
@@ -22685,6 +22876,8 @@ class RTCEngine extends eventsExports.EventEmitter {
       this.dataChannels.teardown();
       yield (_a = this.pcManager) === null || _a === void 0 ? void 0 : _a.close();
       this.pcManager = undefined;
+      // the connecting timestamp belongs to the transports we just tore down
+      this.transportConnectingSince = undefined;
       this.reliableReceivedState.clear();
     });
   }
@@ -22710,17 +22903,17 @@ class RTCEngine extends eventsExports.EventEmitter {
       throw new TrackInvalidError('a track with the same ID has already been published');
     }
     return new Promise((resolve, reject) => {
-      const publicationTimeout = setTimeout(() => {
+      const publicationTimeout = CriticalTimers.setTimeout(() => {
         delete this.pendingTrackResolvers[req.cid];
         reject(ConnectionError.timeout('publication of local track timed out, no response from server'));
       }, 10000);
       this.pendingTrackResolvers[req.cid] = {
         resolve: info => {
-          clearTimeout(publicationTimeout);
+          CriticalTimers.clearTimeout(publicationTimeout);
           resolve(info);
         },
         reject: () => {
-          clearTimeout(publicationTimeout);
+          CriticalTimers.clearTimeout(publicationTimeout);
           reject(new Error('Cancelled publication by calling unpublish'));
         }
       };
@@ -22793,6 +22986,15 @@ class RTCEngine extends eventsExports.EventEmitter {
       this.pcManager.onDataChannel = this.handleDataChannel;
       this.pcManager.onStateChange = (connectionState, publisherState, subscriberState) => __awaiter(this, void 0, void 0, function* () {
         this.log.debug("primary PC state changed ".concat(connectionState));
+        // Record when the primary transport actually entered CONNECTING so
+        // verifyTransport() can bound how long we tolerate it. Deriving it from the
+        // real transition (this handler only fires on state changes) rather than from
+        // observation time keeps it from going stale across peer-connection rebuilds.
+        if (connectionState === PCTransportState.CONNECTING) {
+          this.transportConnectingSince = Date.now();
+        } else {
+          this.transportConnectingSince = undefined;
+        }
         if (['closed', 'disconnected', 'failed'].includes(publisherState)) {
           // reset publisher connection promise
           this.publisherConnectionPromise = undefined;
@@ -23001,15 +23203,23 @@ class RTCEngine extends eventsExports.EventEmitter {
     }
   }
   addMediaSections(numAudios, numVideos) {
-    var _a, _b;
+    var _a, _b, _c;
     const transceiverInit = {
       direction: 'recvonly'
     };
     for (let i = 0; i < numAudios; i++) {
       (_a = this.pcManager) === null || _a === void 0 ? void 0 : _a.addPublisherTransceiverOfKind('audio', transceiverInit);
     }
+    // media only arrives on these sections when there is no subscriber connection to arrive on
+    const receivesMedia = ((_b = this.pcManager) === null || _b === void 0 ? void 0 : _b.mode) === 'publisher-only';
     for (let i = 0; i < numVideos; i++) {
-      (_b = this.pcManager) === null || _b === void 0 ? void 0 : _b.addPublisherTransceiverOfKind('video', transceiverInit);
+      const transceiver = (_c = this.pcManager) === null || _c === void 0 ? void 0 : _c.addPublisherTransceiverOfKind('video', transceiverInit);
+      if (receivesMedia && transceiver) {
+        const negotiated = negotiateDependencyDescriptor(transceiver);
+        this.log.debug('dependency descriptor negotiated for received video', {
+          negotiated
+        });
+      }
     }
   }
   createDataChannels() {
@@ -23151,7 +23361,7 @@ class RTCEngine extends eventsExports.EventEmitter {
       if (!opts.videoCodec) {
         return;
       }
-      track.setSimulcastTrackSender(opts.videoCodec, transceiver.sender);
+      yield track.setSimulcastTrackSender(opts.videoCodec, transceiver.sender);
       return transceiver.sender;
     });
   }
@@ -23163,6 +23373,63 @@ class RTCEngine extends eventsExports.EventEmitter {
       return this.pcManager.addPublisherTrack(track);
     });
   }
+  /**
+   * A sustained local `LOST` while connected and publishing means the server isn't receiving
+   * our media, so force a full reconnect; any non-`LOST` value cancels a pending trigger.
+   */
+  handleLocalConnectionQuality(update) {
+    if (!this.participantSid) {
+      return;
+    }
+    const localUpdate = update.updates.find(u => u.participantSid === this.participantSid);
+    if (!localUpdate) {
+      return;
+    }
+    if (localUpdate.quality === ConnectionQuality$1.LOST) {
+      this.scheduleLostQualityReconnect();
+    } else {
+      this.clearLostQualityTimeout();
+    }
+  }
+  scheduleLostQualityReconnect() {
+    if (this.lostQualityTimeout) {
+      // already counting down towards a reconnect
+      return;
+    }
+    this.lostQualityTimeout = CriticalTimers.setTimeout(() => {
+      this.lostQualityTimeout = undefined;
+      if (this._isClosed || this.pcState !== PCState.Connected || this.attemptingReconnect) {
+        return;
+      }
+      if (!this.hasActivePublisherSenders()) {
+        return;
+      }
+      this.log.warn('local connection quality lost while publishing, triggering full reconnect', this.logContext);
+      this.fullReconnectOnNext = true;
+      this.handleDisconnect('connection quality lost', ReconnectReason.RR_PUBLISHER_FAILED);
+    }, connectionQualityLostTimeout);
+  }
+  clearLostQualityTimeout() {
+    if (this.lostQualityTimeout) {
+      CriticalTimers.clearTimeout(this.lostQualityTimeout);
+      this.lostQualityTimeout = undefined;
+    }
+  }
+  /** Whether the publisher currently has any sender with a live track. */
+  hasActivePublisherSenders() {
+    var _a, _b;
+    return (_b = (_a = this.pcManager) === null || _a === void 0 ? void 0 : _a.publisher.getSenders().some(sender => !!sender.track && sender.track.readyState === 'live')) !== null && _b !== void 0 ? _b : false;
+  }
+  /**
+   * Forces a full reconnect while keeping the engine (and its saved credentials) alive. Used by
+   * Room's connection-reconcile safety net when the transport silently died but we looked connected.
+   * @internal
+   */
+  reconnect() {
+    let reason = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ReconnectReason.RR_UNKNOWN;
+    this.fullReconnectOnNext = true;
+    this.handleDisconnect('reconcile', reason);
+  }
   attemptReconnect(reason) {
     return __awaiter(this, void 0, void 0, function* () {
       var _a, _b, _c;
@@ -23174,21 +23441,32 @@ class RTCEngine extends eventsExports.EventEmitter {
         this.log.warn('already attempting reconnect, returning early');
         return;
       }
+      // A pending Lost-quality countdown belongs to the session we're now leaving; cancel it so
+      // it can't fire against the reconnected session before the server has evaluated it. (A resume
+      // keeps the peer connections, so cleanupPeerConnections wouldn't cover this path.)
+      this.clearLostQualityTimeout();
       if (((_a = this.clientConfiguration) === null || _a === void 0 ? void 0 : _a.resumeConnection) === ClientConfigSetting.DISABLED ||
       // signaling state could change to closed due to hardware sleep
       // those connections cannot be resumed
       ((_c = (_b = this.pcManager) === null || _b === void 0 ? void 0 : _b.currentState) !== null && _c !== void 0 ? _c : PCTransportState.NEW) === PCTransportState.NEW) {
         this.fullReconnectOnNext = true;
       }
+      // Consume the flag up front: capture whether this attempt is a full reconnect, then reset
+      // it. From here on a `true` value unambiguously represents a *new* full-reconnect request
+      // that arrived while this attempt was running (e.g. a server RECONNECT leave), which the
+      // finally block dispatches — for both the resume and full-reconnect paths.
+      const fullReconnect = this.fullReconnectOnNext;
+      this.fullReconnectOnNext = false;
+      let succeeded = false;
       try {
         this.attemptingReconnect = true;
-        if (this.fullReconnectOnNext) {
+        if (fullReconnect) {
           yield this.restartConnection();
         } else {
           yield this.resumeConnection(reason);
         }
         this.clearPendingReconnect();
-        this.fullReconnectOnNext = false;
+        succeeded = true;
       } catch (e) {
         this.reconnectAttempts += 1;
         let recoverable = true;
@@ -23198,8 +23476,9 @@ class RTCEngine extends eventsExports.EventEmitter {
           });
           // unrecoverable
           recoverable = false;
-        } else if (!(e instanceof SignalReconnectError)) {
-          // cannot resume
+        } else if (fullReconnect || !(e instanceof SignalReconnectError)) {
+          // a failed full reconnect stays a full reconnect; a failed resume can only be
+          // resumed again for a signal-level error, otherwise it escalates
           this.fullReconnectOnNext = true;
         }
         if (recoverable) {
@@ -23211,6 +23490,13 @@ class RTCEngine extends eventsExports.EventEmitter {
         }
       } finally {
         this.attemptingReconnect = false;
+        // A full reconnect requested while this attempt was running (e.g. a `RECONNECT` leave
+        // during a resume or a restart) that a successful attempt didn't act on; dispatch it now
+        // (the failure path already retries).
+        if (succeeded && this.fullReconnectOnNext && !this._isClosed) {
+          this.log.debug('full reconnect requested during in-progress attempt, dispatching');
+          this.handleDisconnect('reconnect');
+        }
       }
     });
   }
@@ -23529,14 +23815,23 @@ class RTCEngine extends eventsExports.EventEmitter {
     if (!this.pcManager) {
       return false;
     }
+    const state = this.pcManager.currentState;
     const allowedConnectionStates = [PCTransportState.CONNECTING, PCTransportState.CONNECTED];
-    if (!allowedConnectionStates.includes(this.pcManager.currentState)) {
+    if (!allowedConnectionStates.includes(state)) {
       return false;
     }
     // ensure signal is connected
     if (!this.client.ws || this.client.ws.readyState === WebSocket.CLOSED) {
       return false;
     }
+    // A transport stuck in CONNECTING never reaches CONNECTED nor reports FAILED, so it would
+    // otherwise look healthy forever; bound how long we tolerate it. The entry time is recorded
+    // in the pcManager state-change handler (see configure()), so this is a pure read — an
+    // unrecorded CONNECTING fails open rather than measuring against a stale timestamp.
+    if (state === PCTransportState.CONNECTING && this.transportConnectingSince !== undefined && Date.now() - this.transportConnectingSince > this.peerConnectionTimeout) {
+      this.log.warn('transport stuck in connecting state', this.logContext);
+      return false;
+    }
     return true;
   }
   /** @internal */
@@ -24178,9 +24473,7 @@ class TextStreamReader extends BaseStreamReader {
     // Suppress unhandled rejection on reader.closed — errors are
     // already propagated through reader.read() to the consumer.
     reader.closed.catch(() => {});
-    const decoder = new TextDecoder('utf-8', {
-      fatal: true
-    });
+    const decoder = new TextDecoder('utf-8');
     const signal = this.signal;
     const cleanup = () => {
       reader.releaseLock();
@@ -24658,9 +24951,7 @@ function bytesToChunks(streamId) {
  * synthesized text chunk decodes independently. The `flush` emits the decoder's trailing bytes.
  */
 function bytesToDecodedUtf8(streamId) {
-  const decoder = new TextDecoder('utf-8', {
-    fatal: true
-  });
+  const decoder = new TextDecoder('utf-8');
   const encoder = new TextEncoder();
   let outIndex = 0;
   const decodeOrThrow = bytes => {
@@ -31475,6 +31766,7 @@ class Room extends eventsExports.EventEmitter {
     this.log = livekitLogger;
     this.bufferedEvents = [];
     this.isResuming = false;
+    this.pendingTrackAddedCallbacks = new Map();
     this.connect = (url, token, opts) => __awaiter(this, void 0, void 0, function* () {
       var _a;
       if (!isBrowserSupported()) {
@@ -31990,8 +32282,9 @@ class Room extends eventsExports.EventEmitter {
           return;
         }
         const newStreamState = Track.streamStateFromProto(streamState.state);
+        const prevStreamState = pub.track.streamState;
         pub.track.setStreamState(newStreamState);
-        if (newStreamState !== pub.track.streamState) {
+        if (newStreamState !== prevStreamState) {
           participant.emit(ParticipantEvent.TrackStreamStateChanged, pub, pub.track.streamState);
           this.emitWhenConnected(RoomEvent.TrackStreamStateChanged, pub, pub.track.streamState, participant);
         }
@@ -32009,6 +32302,7 @@ class Room extends eventsExports.EventEmitter {
       pub.setAllowed(update.allowed);
     };
     this.handleSubscriptionError = update => {
+      this.cancelPendingTrackAdded(update.trackSid);
       const participant = Array.from(this.remoteParticipants.values()).find(p => p.trackPublications.has(update.trackSid));
       if (!participant) {
         return;
@@ -32521,10 +32815,10 @@ class Room extends eventsExports.EventEmitter {
       }
       this.emitBufferedEvents();
     }).on(EngineEvent.SignalResumed, () => {
-      this.bufferedEvents = [];
       if (this.state === ConnectionState.Reconnecting || this.isResuming) {
         this.sendSyncState();
       }
+      this.emitBufferedEvents();
     }).on(EngineEvent.Restarting, this.handleRestarting).on(EngineEvent.Restarted, this.handleRestarted).on(EngineEvent.SignalRestarted, this.handleSignalRestarted).on(EngineEvent.Offline, () => {
       if (this.setAndEmitConnectionState(ConnectionState.Reconnecting)) {
         this.emit(RoomEvent.Reconnecting);
@@ -32941,29 +33235,43 @@ class Room extends eventsExports.EventEmitter {
     this.maybeCreateEngine();
   }
   onTrackAdded(mediaTrack, stream, receiver) {
+    var _a, _b;
     // don't fire onSubscribed when connecting
     // WebRTC fires onTrack as soon as setRemoteDescription is called on the offer
     // at that time, ICE connectivity has not been established so the track is not
     // technically subscribed.
     // We'll defer these events until when the room is connected or eventually disconnected.
-    if (this.state === ConnectionState.Connecting || this.state === ConnectionState.Reconnecting) {
+    if ([ConnectionState.Connecting, ConnectionState.Reconnecting].includes(this.state)) {
+      const pendingTrackSid = extractTrackSid(mediaTrack, stream);
+      this.log.debug('deferring on track for later', {
+        mediaTrackId: mediaTrack.id,
+        mediaStreamId: stream.id,
+        tracksInStream: stream.getTracks().map(track => track.id)
+      });
       const reconnectedHandler = () => {
-        this.log.debug('deferring on track for later', {
-          mediaTrackId: mediaTrack.id,
-          mediaStreamId: stream.id,
-          tracksInStream: stream.getTracks().map(track => track.id)
-        });
-        this.onTrackAdded(mediaTrack, stream, receiver);
         cleanup();
+        this.onTrackAdded(mediaTrack, stream, receiver);
       };
       const cleanup = () => {
         this.off(RoomEvent.Reconnected, reconnectedHandler);
         this.off(RoomEvent.Connected, reconnectedHandler);
         this.off(RoomEvent.Disconnected, cleanup);
+        if (pendingTrackSid) {
+          const pendingCallbacks = this.pendingTrackAddedCallbacks.get(pendingTrackSid);
+          pendingCallbacks === null || pendingCallbacks === void 0 ? void 0 : pendingCallbacks.delete(cleanup);
+          if ((pendingCallbacks === null || pendingCallbacks === void 0 ? void 0 : pendingCallbacks.size) === 0) {
+            this.pendingTrackAddedCallbacks.delete(pendingTrackSid);
+          }
+        }
       };
       this.once(RoomEvent.Reconnected, reconnectedHandler);
       this.once(RoomEvent.Connected, reconnectedHandler);
       this.once(RoomEvent.Disconnected, cleanup);
+      if (pendingTrackSid) {
+        const pendingCallbacks = (_a = this.pendingTrackAddedCallbacks.get(pendingTrackSid)) !== null && _a !== void 0 ? _a : new Set();
+        pendingCallbacks.add(cleanup);
+        this.pendingTrackAddedCallbacks.set(pendingTrackSid, pendingCallbacks);
+      }
       return;
     }
     if (this.state === ConnectionState.Disconnected) {
@@ -32976,11 +33284,10 @@ class Room extends eventsExports.EventEmitter {
     }
     const parts = unpackStreamId(stream.id);
     const participantSid = parts[0];
-    let streamId = parts[1];
-    let trackId = mediaTrack.id;
+    const streamId = parts[1];
     // firefox will get streamId (pID|trackId) instead of (pID|streamId) as it doesn't support sync tracks by stream
     // and generates its own track id instead of infer from sdp track id.
-    if (streamId && streamId.startsWith('TR')) trackId = streamId;
+    let trackId = (_b = extractTrackSid(mediaTrack, stream)) !== null && _b !== void 0 ? _b : mediaTrack.id;
     if (participantSid === this.localParticipant.sid) {
       this.log.warn('tried to create RemoteParticipant for local participant');
       return;
@@ -33024,6 +33331,10 @@ class Room extends eventsExports.EventEmitter {
       this.emit(RoomEvent.EncryptionError, new Error("Encrypted ".concat(publication.source, " track received from participant ").concat(participant.sid, ", but room does not have encryption enabled!")));
     }
   }
+  cancelPendingTrackAdded(trackSid) {
+    var _a;
+    (_a = this.pendingTrackAddedCallbacks.get(trackSid)) === null || _a === void 0 ? void 0 : _a.forEach(cleanup => cleanup());
+  }
   handleLocalTrackSubscribed(subscribedSid) {
     const findPublication = () => this.localParticipant.getTrackPublications().find(_ref6 => {
       let trackSid = _ref6.trackSid;
@@ -33287,6 +33598,7 @@ class Room extends eventsExports.EventEmitter {
       }
       this.emitWhenConnected(RoomEvent.TrackSubscribed, track, publication, participant);
     }).on(ParticipantEvent.TrackUnpublished, publication => {
+      this.cancelPendingTrackAdded(publication.trackSid);
       this.emit(RoomEvent.TrackUnpublished, publication, participant);
     }).on(ParticipantEvent.TrackUnsubscribed, (track, publication) => {
       this.emit(RoomEvent.TrackUnsubscribed, track, publication, participant);
@@ -33404,8 +33716,17 @@ class Room extends eventsExports.EventEmitter {
           } : undefined
         });
         if (consecutiveFailures >= 3) {
-          this.recreateEngine();
-          this.handleDisconnect(this.options.stopLocalTrackOnUnpublish, DisconnectReason.STATE_MISMATCH);
+          this.clearConnectionReconcile();
+          if (this.engine && !this.engine.isClosed) {
+            // The transport silently died while we still looked connected. Try a full reconnect
+            // (keeps the room alive; the engine falls back to Disconnected if it ultimately fails).
+            this.log.warn('detected connection state mismatch, attempting full reconnect');
+            this.engine.reconnect();
+          } else {
+            // No usable engine to reconnect with; tear down.
+            this.recreateEngine();
+            this.handleDisconnect(this.options.stopLocalTrackOnUnpublish, DisconnectReason.STATE_MISMATCH);
+          }
         }
       } else {
         consecutiveFailures = 0;
@@ -34802,24 +35123,26 @@ class TokenSourceEndpoint extends TokenSourceCached {
       const body = yield response.json();
       return TokenSourceResponse.fromJson(body, {
         // NOTE: it could be possible that the response body could contain more fields than just
-        // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer)
+        // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer)
         ignoreUnknownFields: true
       });
     });
   }
 }
-class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-  constructor(sandboxId, options) {
+class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+  constructor(tokenServerId, options) {
     const _options$baseUrl = options.baseUrl,
       baseUrl = _options$baseUrl === void 0 ? 'https://cloud-api.livekit.io' : _options$baseUrl,
       rest = __rest(options, ["baseUrl"]);
     super("".concat(baseUrl, "/api/v2/sandbox/connection-details"), Object.assign(Object.assign({}, rest), {
       headers: {
-        'X-Sandbox-ID': sandboxId
+        'X-Sandbox-ID': tokenServerId
       }
     }));
   }
 }
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {}
 const TokenSource = {
   /** TokenSource.literal contains a single, literal set of {@link TokenSourceResponseObject}
    * credentials, either provided directly or returned from a provided function. */
@@ -34838,24 +35161,31 @@ const TokenSource = {
   /**
    * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
    * the standard endpoint format:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/endpoint/
    */
   endpoint(url) {
     let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     return new TokenSourceEndpoint(url, options);
   },
   /**
-   * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+   * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+   */
+  sandboxTokenServer(sandboxId) {
+    let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  },
+  /**
+   * TokenSource.developmentTokenServer queries a development token server for credentials,
    * which supports quick prototyping / getting started types of use cases.
    *
    * This token provider is INSECURE and should NOT be used in production.
    *
    * For more info:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/sandbox-token-server/
    */
-  sandboxTokenServer(sandboxId) {
+  developmentTokenServer(tokenServerId) {
     let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-    return new TokenSourceSandboxTokenServer(sandboxId, options);
+    return new TokenSourceDevelopmentTokenServer(tokenServerId, options);
   }
 };/**
  * Try to analyze the local track to determine the facing mode of a track.