livekit-client 2.20.1 → 2.20.2

package/src/room/PCTransport.ts

@@ -15,15 +15,24 @@ interface TrackBitrateInfo {
   transceiver?: RTCRtpTransceiver;
   codec: string;
   maxbr: number;
+  isScreenShare?: boolean;
 }
 
-/* The svc codec (av1/vp9) would use a very low bitrate at the begining and
-increase slowly by the bandwidth estimator until it reach the target bitrate. The
-process commonly cost more than 10 seconds cause subscriber will get blur video at
-the first few seconds. So we use a 70% of target bitrate here as the start bitrate to
-eliminate this issue.
-*/
-const startBitrateForSVC = 0.7;
+/*
+ * Video codecs use a very low bitrate at the beginning and increase slowly by
+ * the bandwidth estimator until they reach the target bitrate. The process commonly
+ * costs more than 10 seconds causing subscribers to get blurry video at the first
+ * few seconds. We use x-google-start-bitrate to hint the BWE to start higher.
+ *
+ * Why 90%: Gives ~10% headroom for bandwidth estimation while starting close to target.
+ * Why same for all codecs: Target bitrate already accounts for codec efficiency
+ * (e.g., users set lower targets for VP9/AV1 knowing they're more efficient).
+ * Why cap at 1 Mbps: Prevents BWE from starting too aggressively on high bitrate tracks.
+ */
+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;
 
@@ -53,6 +62,8 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
 
   private log = log;
 
+  private iceLog = log;
+
   private loggerOptions: LoggerOptions;
 
   private ddExtID = 0;
@@ -95,8 +106,12 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
 
   constructor(config?: RTCConfiguration, loggerOptions: LoggerOptions = {}) {
     super();
-    this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.PCTransport);
     this.loggerOptions = loggerOptions;
+    this.log = getLogger(
+      loggerOptions.loggerName ?? LoggerNames.PCTransport,
+      () => this.logContext,
+    );
+    this.iceLog = getLogger(LoggerNames.ICE, () => this.logContext);
     this.config = config;
     this._pc = this.createPC();
     this.offerLock = new Mutex();
@@ -107,24 +122,33 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
 
     pc.onicecandidate = (ev) => {
       if (!ev.candidate) return;
+      this.iceLog.debug('local ICE candidate gathered', { candidate: ev.candidate.candidate });
       this.onIceCandidate?.(ev.candidate);
     };
     pc.onicecandidateerror = (ev) => {
+      this.iceLog.debug('ICE candidate error', { event: ev });
       this.onIceCandidateError?.(ev);
     };
 
     pc.oniceconnectionstatechange = () => {
+      this.iceLog.debug(`ICE connection state: ${pc.iceConnectionState}`);
       this.onIceConnectionStateChange?.(pc.iceConnectionState);
     };
 
     pc.onsignalingstatechange = () => {
+      this.log.debug(`signaling state: ${pc.signalingState}`);
       this.onSignalingStatechange?.(pc.signalingState);
     };
 
     pc.onconnectionstatechange = () => {
+      this.log.debug(`connection state: ${pc.connectionState}`);
       this.onConnectionStateChange?.(pc.connectionState);
     };
     pc.ondatachannel = (ev) => {
+      this.log.debug('data channel opened by peer', {
+        label: ev.channel.label,
+        id: ev.channel.id,
+      });
       this.onDataChannel?.(ev);
     };
     pc.ontrack = (ev) => {
@@ -150,6 +174,9 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     if (this.pc.remoteDescription && !this.restartingIce) {
       return this.pc.addIceCandidate(candidate);
     }
+    this.iceLog.debug('queuing remote ICE candidate until remote description applied', {
+      pendingCount: this.pendingCandidates.length + 1,
+    });
     this.pendingCandidates.push(candidate);
   }
 
@@ -161,7 +188,6 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       offerId !== this.latestOfferId
     ) {
       this.log.warn('ignoring answer for old offer', {
-        ...this.logContext,
         offerId,
         latestOfferId: this.latestOfferId,
       });
@@ -180,7 +206,7 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
         sdpParsed.media.forEach((media) => {
           ensureIPAddrMatchVersion(media);
         });
-        this.log.debug('setting pending initial offer before processing answer', this.logContext);
+        this.log.debug('setting pending initial offer before processing answer');
         await this.setMungedSDP(initialOffer, write(sdpParsed));
       }
       const sdpParsed = parse(sd.sdp ?? '');
@@ -249,6 +275,11 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     }
     await this.setMungedSDP(sd, mungedSDP, true);
 
+    if (this.pendingCandidates.length > 0) {
+      this.iceLog.debug('flushing queued ICE candidates', {
+        count: this.pendingCandidates.length,
+      });
+    }
     this.pendingCandidates.forEach((candidate) => {
       this.pc.addIceCandidate(candidate);
     });
@@ -298,10 +329,7 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     const unlock = await this.offerLock.lock();
     try {
       if (this.pc.signalingState !== 'stable') {
-        this.log.warn(
-          'signaling state is not stable, cannot create initial offer',
-          this.logContext,
-        );
+        this.log.warn('signaling state is not stable, cannot create initial offer');
         return;
       }
       const offerId = this.latestOfferId + 1;
@@ -328,7 +356,7 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       }
 
       if (options?.iceRestart) {
-        this.log.debug('restarting ICE', this.logContext);
+        this.iceLog.debug('restarting ICE');
         this.restartingIce = true;
       }
 
@@ -345,21 +373,21 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
           await this._pc.setRemoteDescription(currentSD);
         } else {
           this.renegotiate = true;
-          this.log.debug('requesting renegotiation', { ...this.logContext });
+          this.log.debug('requesting renegotiation');
           return;
         }
       } else if (!this._pc || this._pc.signalingState === 'closed') {
-        this.log.warn('could not createOffer with closed peer connection', this.logContext);
+        this.log.warn('could not createOffer with closed peer connection');
         return;
       }
 
       // actually negotiate
-      this.log.debug('starting to negotiate', this.logContext);
+      this.log.debug('starting to negotiate');
       // increase the offer id at the start to ensure the offer is always > 0 so that we can use 0 as a default value for legacy behavior
       const offerId = this.latestOfferId + 1;
       this.latestOfferId = offerId;
       const offer = await this.pc.createOffer(options);
-      this.log.debug('original offer', { sdp: offer.sdp, ...this.logContext });
+      this.log.debug('original offer', { sdp: offer.sdp });
 
       const sdpParsed = parse(offer.sdp ?? '');
       sdpParsed.media.forEach((media) => {
@@ -390,14 +418,18 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
             }
 
             // mung sdp for bitrate setting that can't apply by sendEncoding
-            if (!isSVCCodec(trackbr.codec)) {
-              return true;
-            }
-
-            const startBitrate = Math.round(trackbr.maxbr * startBitrateForSVC);
+            // 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
@@ -407,6 +439,13 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
                 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=${startBitrate}`,
+              });
+            }
             return true;
           });
         }
@@ -424,7 +463,6 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       }
       if (this.latestOfferId > offerId) {
         this.log.warn('latestOfferId mismatch', {
-          ...this.logContext,
           latestOfferId: this.latestOfferId,
           offerId,
         });
@@ -576,6 +614,7 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     if (!this._pc) {
       return;
     }
+    this.log.debug('closing peer connection');
     this.pendingInitialOffer = undefined;
     this._pc.close();
     this._pc.onconnectionstatechange = null;
@@ -597,10 +636,7 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     if (munged) {
       sd.sdp = munged;
       try {
-        this.log.debug(
-          `setting munged ${remote ? 'remote' : 'local'} description`,
-          this.logContext,
-        );
+        this.log.debug(`setting munged ${remote ? 'remote' : 'local'} description`);
         if (remote) {
           await this.pc.setRemoteDescription(sd);
         } else {
@@ -609,7 +645,6 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
         return;
       } catch (e) {
         this.log.warn(`not able to set ${sd.type}, falling back to unmodified sdp`, {
-          ...this.logContext,
           error: e,
           mungedSdp: munged,
           originalSdp,
@@ -642,7 +677,7 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       if (!remote && this.pc.remoteDescription) {
         fields.remoteSdp = this.pc.remoteDescription;
       }
-      this.log.error(`unable to set ${sd.type}`, { ...this.logContext, fields });
+      this.log.error(`unable to set ${sd.type}`, { fields });
       throw new NegotiationError(msg);
     }
   }

package/src/room/PCTransportManager.ts

@@ -65,6 +65,8 @@ export class PCTransportManager {
 
   private log = log;
 
+  private iceLog = log;
+
   private loggerOptions: LoggerOptions;
 
   private _mode: PCMode;
@@ -74,8 +76,9 @@ export class PCTransportManager {
   }
 
   constructor(mode: PCMode, loggerOptions: LoggerOptions, rtcConfig?: RTCConfiguration) {
-    this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.PCManager);
     this.loggerOptions = loggerOptions;
+    this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.PCManager, () => this.logContext);
+    this.iceLog = getLogger(LoggerNames.ICE, () => this.logContext);
 
     this.isPublisherConnectionRequired = mode !== 'subscriber-primary';
     this.isSubscriberConnectionRequired = mode === 'subscriber-primary';
@@ -151,7 +154,7 @@ export class PCTransportManager {
             publisher.removeTrack(sender);
           }
         } catch (e) {
-          this.log.warn('could not removeTrack', { ...this.logContext, error: e });
+          this.log.warn('could not removeTrack', { error: e });
         }
       }
     }
@@ -160,6 +163,7 @@ export class PCTransportManager {
   }
 
   async triggerIceRestart() {
+    this.iceLog.warn('triggering ICE restart');
     if (this.subscriber) {
       this.subscriber.restartingIce = true;
     }
@@ -170,6 +174,7 @@ export class PCTransportManager {
   }
 
   async addIceCandidate(candidate: RTCIceCandidateInit, target: SignalTarget) {
+    this.iceLog.debug('adding remote ICE candidate', { target, candidate });
     if (target === SignalTarget.PUBLISHER) {
       await this.publisher.addIceCandidate(candidate);
     } else {
@@ -179,7 +184,6 @@ export class PCTransportManager {
 
   async createSubscriberAnswerFromOffer(sd: RTCSessionDescriptionInit, offerId: number) {
     this.log.debug('received server offer', {
-      ...this.logContext,
       RTCSdpType: sd.type,
       sdp: sd.sdp,
       signalingState: this.subscriber?.getSignallingState().toString(),
@@ -200,6 +204,7 @@ export class PCTransportManager {
   }
 
   updateConfiguration(config: RTCConfiguration, iceRestart?: boolean) {
+    this.log.debug('updating rtc configuration', { iceRestart });
     this.publisher.setConfiguration(config);
     this.subscriber?.setConfiguration(config);
     if (iceRestart) {
@@ -215,7 +220,7 @@ export class PCTransportManager {
         this.publisher.getConnectionState() !== 'connected' &&
         this.publisher.getConnectionState() !== 'connecting'
       ) {
-        this.log.debug('negotiation required, start negotiating', this.logContext);
+        this.log.debug('negotiation required, start negotiating');
         this.publisher.negotiate();
       }
       await Promise.all(
@@ -368,7 +373,6 @@ export class PCTransportManager {
         `pc state change: from ${PCTransportState[previousState]} to ${
           PCTransportState[this.state]
         }`,
-        this.logContext,
       );
       this.onStateChange?.(
         this.state,
@@ -390,7 +394,7 @@ export class PCTransportManager {
 
     return new Promise<void>(async (resolve, reject) => {
       const abortHandler = () => {
-        this.log.warn('abort transport connection', this.logContext);
+        this.log.warn('abort transport connection');
         CriticalTimers.clearTimeout(connectTimeout);
 
         reject(ConnectionError.cancelled('room connection has been cancelled'));

package/src/room/RTCEngine.test.ts

@@ -1,8 +1,9 @@
 import { DataPacket, DataPacket_Kind, UserPacket } from '@livekit/protocol';
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { DataPacketBuffer, DataPacketItem } from '../utils/dataPacketBuffer';
 import RTCEngine, { DataChannelKind } from './RTCEngine';
 import { roomOptionDefaults } from './defaults';
-import { PublishDataError } from './errors';
+import { PublishDataError, UnexpectedConnectionState } from './errors';
 
 describe('RTCEngine', () => {
   const originalRTCRtpSender = window.RTCRtpSender;
@@ -230,7 +231,7 @@ describe('RTCEngine', () => {
       const send = vi.fn();
       Object.assign(engine as unknown as Record<string, unknown>, {
         ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
-        waitForBufferStatusLow: vi.fn().mockResolvedValue(undefined),
+        waitForBufferHeadroomWithLock: vi.fn().mockResolvedValue(undefined),
         updateAndEmitDCBufferStatus: vi.fn(),
         dataChannelForKind: vi.fn(() => ({ send })),
         pcManager: {
@@ -298,6 +299,278 @@ describe('RTCEngine', () => {
     });
   });
 
+  class FakeDataChannel extends EventTarget {
+    bufferedAmount = 0;
+
+    bufferedAmountLowThreshold = 64 * 1024;
+
+    send = vi.fn();
+  }
+
+  const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+  describe('resendReliableMessagesForResume', () => {
+    it('does not let a concurrent reliable send interleave into the resume replay', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
+        dataChannelForKind: vi.fn(() => dc),
+        pcManager: {
+          getMaxPublisherMessageSize: vi.fn(() => 64 * 1024 - 1),
+        },
+      });
+
+      // Two messages queued for replay, and a full buffer so the XX its first send.
+      const replayed1 = new Uint8Array([1]);
+      const replayed2 = new Uint8Array([2]);
+      const buffer = (
+        engine as unknown as { reliableMessageBuffer: { push: (item: DataPacketItem) => void } }
+      ).reliableMessageBuffer;
+      buffer.push({ data: replayed1, sequence: 1, sent: true });
+      buffer.push({ data: replayed2, sequence: 2, sent: true });
+      dc.bufferedAmount = 2 * 1024 * 1024; // above the reliable high-water mark
+
+      const replay = (
+        engine as unknown as { resendReliableMessagesForResume: (seq: number) => Promise<void> }
+      ).resendReliableMessagesForResume(0);
+      await tick();
+
+      // A send racing the replay: its sequence is assigned immediately, but it must not hit the
+      // wire before the replayed (lower-sequence) messages, or receivers discard those as dupes.
+      const concurrentSend = engine.sendDataPacket(
+        new DataPacket({
+          kind: DataPacket_Kind.RELIABLE,
+          value: { case: 'user', value: new UserPacket({ payload: new Uint8Array([3]) }) },
+        }),
+        DataChannelKind.RELIABLE,
+      );
+      await tick();
+
+      // Buffer drains: the replay must finish its whole batch before the concurrent send.
+      dc.bufferedAmount = 0;
+      dc.dispatchEvent(new Event('bufferedamountlow'));
+      await Promise.all([replay, concurrentSend]);
+
+      expect(dc.send).toHaveBeenCalledTimes(3);
+      expect(dc.send.mock.calls[0][0]).toBe(replayed1);
+      expect(dc.send.mock.calls[1][0]).toBe(replayed2);
+      expect(dc.send.mock.calls[2][0]).not.toBe(replayed1);
+      expect(dc.send.mock.calls[2][0]).not.toBe(replayed2);
+    });
+
+    it('transmits a packet deferred mid-replay instead of marking it sent without sending', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        // Reconnect still active: a send arriving during replay takes the deferral path.
+        attemptingReconnect: true,
+        ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
+        dataChannelForKind: vi.fn(() => dc),
+        pcManager: {
+          getMaxPublisherMessageSize: vi.fn(() => 64 * 1024 - 1),
+        },
+      });
+
+      const buffer = (engine as unknown as { reliableMessageBuffer: DataPacketBuffer })
+        .reliableMessageBuffer;
+      const replayed = new Uint8Array([1]);
+      buffer.push({ data: replayed, sequence: 1, sent: true });
+      // Full buffer so replay parks on waitForBufferHeadroomWithLock before its first send.
+      dc.bufferedAmount = 2 * 1024 * 1024;
+
+      const replay = (
+        engine as unknown as { resendReliableMessagesForResume: (seq: number) => Promise<void> }
+      ).resendReliableMessagesForResume(0);
+      await tick();
+
+      // A reliable send arrives while replay is parked; attemptingReconnect defers it into the
+      // buffer as sent:false, after the replay's first drain pass already started.
+      const deferred = new Uint8Array([2]);
+      const deferredSend = engine.sendDataPacket(
+        new DataPacket({
+          kind: DataPacket_Kind.RELIABLE,
+          value: { case: 'user', value: new UserPacket({ payload: deferred }) },
+        }),
+        DataChannelKind.RELIABLE,
+      );
+      await tick();
+
+      dc.bufferedAmount = 0;
+      dc.dispatchEvent(new Event('bufferedamountlow'));
+      await Promise.all([replay, deferredSend]);
+
+      // Pre-fix, replay sends only its snapshot ([replayed]) and blanket-marks the deferred packet
+      // sent without ever transmitting it — one send. The drain loop must transmit both (the
+      // deferred packet is serialized through sendDataPacket, so it's distinct from `replayed`),
+      // leaving nothing unsent for a later align to strand.
+      const sent = dc.send.mock.calls.map(([d]) => d);
+      expect(sent).toHaveLength(2);
+      expect(sent[0]).toBe(replayed);
+      expect(sent[1]).not.toBe(replayed);
+      expect(buffer.getUnsent()).toHaveLength(0);
+    });
+  });
+
+  describe('reliable sends during teardown windows', () => {
+    const makePacket = (byte: number) =>
+      new DataPacket({
+        kind: DataPacket_Kind.RELIABLE,
+        value: { case: 'user', value: new UserPacket({ payload: new Uint8Array([byte]) }) },
+      });
+
+    function stubEngine(engine: RTCEngine, dc: FakeDataChannel) {
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
+        dataChannelForKind: vi.fn(() => dc),
+        pcManager: {
+          getMaxPublisherMessageSize: vi.fn(() => 64 * 1024 - 1),
+        },
+      });
+      return (engine as unknown as { reliableMessageBuffer: DataPacketBuffer })
+        .reliableMessageBuffer;
+    }
+
+    it('resolves and queues the packet for replay when the wait is torn down transiently', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      const buffer = stubEngine(engine, dc);
+
+      // Park the send on a full buffer, then invalidate the channel (reconnect/replacement).
+      dc.bufferedAmount = 2 * 1024 * 1024;
+      const send = engine.sendDataPacket(makePacket(1), DataChannelKind.RELIABLE);
+      await tick();
+      (
+        engine as unknown as { invalidateDataChannelWaiters: (reason: string) => void }
+      ).invalidateDataChannelWaiters('data channels recreated');
+
+      // The send must not surface the teardown — the packet is queued for the resume replay.
+      await expect(send).resolves.toBeUndefined();
+      expect(dc.send).not.toHaveBeenCalled();
+      expect(buffer.length).toBe(1);
+      expect(buffer.getAll()[0].sent).toBe(false);
+
+      // The replay then delivers it.
+      dc.bufferedAmount = 0;
+      await (
+        engine as unknown as { resendReliableMessagesForResume: (seq: number) => Promise<void> }
+      ).resendReliableMessagesForResume(0);
+      expect(dc.send).toHaveBeenCalledTimes(1);
+      expect(buffer.getAll()[0].sent).toBe(true);
+    });
+
+    it('still rejects when the engine is closed while waiting', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      stubEngine(engine, dc);
+
+      dc.bufferedAmount = 2 * 1024 * 1024;
+      const send = engine.sendDataPacket(makePacket(1), DataChannelKind.RELIABLE);
+      await tick();
+      Object.assign(engine as unknown as Record<string, unknown>, { _isClosed: true });
+      (
+        engine as unknown as { invalidateDataChannelWaiters: (reason: string) => void }
+      ).invalidateDataChannelWaiters('engine closed');
+
+      await expect(send).rejects.toBeInstanceOf(UnexpectedConnectionState);
+      expect(dc.send).not.toHaveBeenCalled();
+    });
+
+    it('queues without waiting while a reconnect attempt is in progress', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      const buffer = stubEngine(engine, dc);
+      Object.assign(engine as unknown as Record<string, unknown>, { attemptingReconnect: true });
+
+      // Even with a full buffer, the send resolves immediately instead of parking.
+      dc.bufferedAmount = 2 * 1024 * 1024;
+      await expect(
+        engine.sendDataPacket(makePacket(1), DataChannelKind.RELIABLE),
+      ).resolves.toBeUndefined();
+      expect(dc.send).not.toHaveBeenCalled();
+      expect(buffer.length).toBe(1);
+      expect(buffer.getAll()[0].sent).toBe(false);
+    });
+  });
+
+  describe('sendLossyBytes', () => {
+    it('ensures the publisher is connected before sending (direct data-track path)', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      // The channel only becomes available once the publisher connection has been established —
+      // mirroring the lazily negotiated publisher case that Room's packetAvailable path hits.
+      let connected = false;
+      const ensurePublisherConnected = vi.fn(async () => {
+        connected = true;
+      });
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        ensurePublisherConnected,
+        dataChannelForKind: vi.fn(() => (connected ? dc : undefined)),
+      });
+
+      await engine.sendLossyBytes(new Uint8Array([1]), DataChannelKind.DATA_TRACK_LOSSY, 'wait');
+
+      expect(ensurePublisherConnected).toHaveBeenCalledWith(DataChannelKind.DATA_TRACK_LOSSY);
+      expect(dc.send).toHaveBeenCalledTimes(1);
+    });
+
+    it('only counts LOSSY bytes into the byterate stat that tunes the lossy drop threshold', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
+        dataChannelForKind: vi.fn(() => dc),
+      });
+      const stat = () =>
+        (engine as unknown as { lossyDataStatCurrentBytes: number }).lossyDataStatCurrentBytes;
+
+      // Data-track traffic must not move the stat — it would inflate the LOSSY channel's
+      // dynamically tuned drop threshold with traffic that channel never carries.
+      await engine.sendLossyBytes(new Uint8Array(1000), DataChannelKind.DATA_TRACK_LOSSY, 'wait');
+      expect(stat()).toBe(0);
+
+      await engine.sendLossyBytes(new Uint8Array(100), DataChannelKind.LOSSY, 'drop');
+      expect(stat()).toBe(100);
+    });
+  });
+
+  describe('waitForBufferHeadroomWithLock', () => {
+    it('rejects parked waiters and releases the lock when the data channels are invalidated', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const dc = new FakeDataChannel();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        dataChannelForKind: vi.fn(() => dc),
+      });
+
+      // Park a waiter: buffer above the reliable high-water mark, holding the headroom lock.
+      dc.bufferedAmount = 2 * 1024 * 1024;
+      const parked = engine.waitForBufferHeadroomWithLock(DataChannelKind.RELIABLE);
+      // Swallow the expected rejection so it can't surface as unhandled before we assert on it.
+      parked.catch(() => {});
+      await tick();
+
+      // The channel object gets abandoned (e.g. createDataChannels on the Safari resume path).
+      (
+        engine as unknown as { invalidateDataChannelWaiters: (reason: string) => void }
+      ).invalidateDataChannelWaiters('data channels recreated');
+
+      await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+
+      // The lock must be free again: a wait against the fresh, drained channel resolves instead
+      // of queueing forever behind the stranded waiter.
+      dc.bufferedAmount = 0;
+      await expect(
+        engine.waitForBufferHeadroomWithLock(DataChannelKind.RELIABLE),
+      ).resolves.toBeUndefined();
+    });
+  });
+
   describe('handleDataChannelClose', () => {
     function stubCloseEnv(
       engine: RTCEngine,