livekit-client 2.20.2 → 2.21.0

package/src/room/Room.test.ts

@@ -81,7 +81,10 @@ describe('Room signaling options', () => {
       'wss://test.livekit.io',
       'test-token',
       expect.objectContaining({
-        clientInfoCapabilities: [ClientInfo_Capability.CAP_PACKET_TRAILER],
+        clientInfoCapabilities: [
+          ClientInfo_Capability.CAP_PACKET_TRAILER,
+          ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW,
+        ],
         e2eeEnabled: true,
       }),
       expect.any(AbortSignal),

package/src/room/Room.ts

@@ -118,6 +118,7 @@ import {
   getEmptyAudioStreamTrack,
   isBrowserSupported,
   isCloud,
+  isCompressionStreamSupported,
   isLocalAudioTrack,
   isLocalParticipant,
   isReactNative,
@@ -268,7 +269,13 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.maybeCreateEngine();
 
     this.incomingDataStreamManager = new IncomingDataStreamManager();
-    this.outgoingDataStreamManager = new OutgoingDataStreamManager(this.engine, this.log);
+    this.outgoingDataStreamManager = new OutgoingDataStreamManager(
+      this.engine,
+      this.log,
+      this.getRemoteParticipantClientProtocol,
+      this.getRemoteParticipantCapabilities,
+      this.getAllRemoteParticipantIdentities,
+    );
 
     this.incomingDataTrackManager = new IncomingDataTrackManager({ e2eeManager: this.e2eeManager });
     this.incomingDataTrackManager
@@ -308,7 +315,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       })
       .on('packetAvailable', ({ handle, bytes }) => {
         this.engine
-          .sendLossyBytes(bytes, DataChannelKind.DATA_TRACK_LOSSY, 'wait')
+          .sendDataTrackFrame(bytes)
           .finally(() => this.outgoingDataTrackManager.handlePacketSendComplete(handle));
       });
 
@@ -623,10 +630,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         this.isResuming = false;
         this.log.debug('Resumed signal connection');
         this.updateSubscriptions();
-        this.emitBufferedEvents();
         if (this.setAndEmitConnectionState(ConnectionState.Connected)) {
           this.emit(RoomEvent.Reconnected);
         }
+        this.emitBufferedEvents();
       })
       .on(EngineEvent.SignalResumed, () => {
         this.bufferedEvents = [];
@@ -971,11 +978,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         autoSubscribe: connectOptions.autoSubscribe,
         adaptiveStream:
           typeof roomOptions.adaptiveStream === 'object' ? true : roomOptions.adaptiveStream,
-        clientInfoCapabilities:
-          isFrameMetadataSupported(roomOptions.frameMetadata ?? roomOptions.packetTrailer) ||
-          !!this.e2eeManager
-            ? [ClientInfo_Capability.CAP_PACKET_TRAILER]
-            : undefined,
+        clientInfoCapabilities: this.getClientInfoCapabilities(roomOptions),
         maxRetries: connectOptions.maxRetries,
         e2eeEnabled: !!this.e2eeManager,
         websocketTimeout: connectOptions.websocketTimeout,
@@ -2505,10 +2508,39 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  /** The client capabilities this SDK advertises to other participants in its `ClientInfo`. */
+  private getClientInfoCapabilities(
+    roomOptions: InternalRoomOptions,
+  ): Array<ClientInfo_Capability> {
+    const capabilities: Array<ClientInfo_Capability> = [];
+    if (
+      isFrameMetadataSupported(roomOptions.frameMetadata ?? roomOptions.packetTrailer) ||
+      !!this.e2eeManager
+    ) {
+      capabilities.push(ClientInfo_Capability.CAP_PACKET_TRAILER);
+    }
+    // Advertise deflate-raw decompression support so peers know they can send us compressed data
+    // streams (gated separately from clientProtocol — see the data streams v2 spec).
+    if (isCompressionStreamSupported()) {
+      capabilities.push(ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW);
+    }
+    return capabilities;
+  }
+
   private getRemoteParticipantClientProtocol = (identity: Participant['identity']) => {
     return this.remoteParticipants.get(identity)?.clientProtocol ?? CLIENT_PROTOCOL_DEFAULT;
   };
 
+  private getRemoteParticipantCapabilities = (
+    identity: Participant['identity'],
+  ): Array<ClientInfo_Capability> => {
+    return this.remoteParticipants.get(identity)?.capabilities ?? [];
+  };
+
+  private getAllRemoteParticipantIdentities = () => {
+    return Array.from(this.remoteParticipants.keys());
+  };
+
   private registerRpcDataStreamHandler() {
     this.incomingDataStreamManager.registerTextStreamHandler(
       RPC_REQUEST_DATA_STREAM_TOPIC,

package/src/room/data-channel/DataChannelManager.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PCTransportManager } from '../PCTransportManager';
+import { UnexpectedConnectionState } from '../errors';
+import { DataChannelManager, type DataChannelManagerOptions } from './DataChannelManager';
+import { DataChannelKind } from './types';
+
+class FakeDataChannel extends EventTarget {
+  bufferedAmount = 0;
+
+  bufferedAmountLowThreshold = 0;
+
+  onmessage: ((message: MessageEvent) => void) | null = null;
+
+  onerror: ((event: Event) => void) | null = null;
+
+  onclose: (() => void) | null = null;
+
+  onbufferedamountlow: (() => void) | null = null;
+
+  send = vi.fn();
+
+  close = vi.fn();
+
+  constructor(public label: string) {
+    super();
+  }
+}
+
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+function makeManager(overrides?: Partial<DataChannelManagerOptions>) {
+  const opts = {
+    isEngineClosed: () => false,
+    isReconnecting: () => false,
+    onDataMessage: vi.fn(),
+    onDataTrackMessage: vi.fn(),
+    onDataError: vi.fn(),
+    onChannelClose: vi.fn(),
+    onBufferStatusChanged: vi.fn(),
+    ...overrides,
+  };
+  const manager = new DataChannelManager(opts);
+  const created: Record<string, FakeDataChannel> = {};
+  const pcManager = {
+    createPublisherDataChannel: vi.fn((label: string) => {
+      const dc = new FakeDataChannel(label);
+      created[label] = dc;
+      return dc as unknown as RTCDataChannel;
+    }),
+  } as unknown as PCTransportManager;
+  return { manager, opts, pcManager, created };
+}
+
+describe('DataChannelManager', () => {
+  it('creates and wires the three publisher channels', () => {
+    const { manager, opts, pcManager, created } = makeManager();
+
+    manager.createPublisherChannels(pcManager);
+
+    expect(Object.keys(created).sort()).toEqual(['_data_track', '_lossy', '_reliable']);
+    expect(manager.getHandle(DataChannelKind.RELIABLE)).toBe(created._reliable);
+    expect(manager.hasPublisherChannels).toBe(true);
+    for (const dc of Object.values(created)) {
+      expect(dc.onmessage).toBeTruthy();
+      expect(dc.onerror).toBeTruthy();
+      expect(dc.onclose).toBeTruthy();
+      expect(dc.onbufferedamountlow).toBeTruthy();
+      expect(dc.bufferedAmountLowThreshold).toBeGreaterThan(0);
+    }
+
+    // Close handler reports the right kind.
+    created._reliable.onclose!();
+    expect(opts.onChannelClose).toHaveBeenCalledWith(DataChannelKind.RELIABLE);
+
+    // A drain event on the data-track channel refreshes its status; since the buffer starts empty
+    // (below the low mark) and the wrapper's initial status is already "low", no change fires —
+    // fill it first so the drain is an observable not-low → low transition.
+    const dataTrackDc = created._data_track;
+    dataTrackDc.bufferedAmount = 10 * 1024 * 1024;
+    dataTrackDc.onbufferedamountlow!(); // refresh: now "not low"
+    dataTrackDc.bufferedAmount = 0;
+    dataTrackDc.onbufferedamountlow!(); // refresh: back to "low"
+    expect(opts.onBufferStatusChanged).toHaveBeenCalledWith(
+      DataChannelKind.DATA_TRACK_LOSSY,
+      false,
+    );
+    expect(opts.onBufferStatusChanged).toHaveBeenCalledWith(DataChannelKind.DATA_TRACK_LOSSY, true);
+
+    manager.lossy.stopThresholdTuning();
+  });
+
+  it('recreating channels rejects waiters parked on the replaced handles', async () => {
+    const { manager, pcManager, created } = makeManager();
+    manager.createPublisherChannels(pcManager);
+
+    // Park a reliable sender on the first-generation channel.
+    created._reliable.bufferedAmount = 2 * 1024 * 1024;
+    const parked = manager.reliable.waitForHeadroomWithLock();
+    parked.catch(() => {});
+    await tick();
+
+    // Safari null-id path: channels recreated without closing the old ones.
+    manager.createPublisherChannels(pcManager);
+
+    await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    // The gate recovers against the fresh (empty) channel.
+    await expect(manager.reliable.waitForHeadroomWithLock()).resolves.toBeUndefined();
+
+    manager.lossy.stopThresholdTuning();
+  });
+
+  it('adopts subscriber channels by label and rejects unknown labels', () => {
+    const { manager, opts } = makeManager();
+
+    const sub = new FakeDataChannel('_reliable');
+    expect(manager.adoptSubscriberChannel(sub as unknown as RTCDataChannel)).toBe(true);
+    expect(manager.getHandle(DataChannelKind.RELIABLE, true)).toBe(sub);
+    expect(sub.onmessage).toBe(opts.onDataMessage);
+
+    const dataTrackSub = new FakeDataChannel('_data_track');
+    expect(manager.adoptSubscriberChannel(dataTrackSub as unknown as RTCDataChannel)).toBe(true);
+    expect(dataTrackSub.onmessage).toBe(opts.onDataTrackMessage);
+
+    expect(
+      manager.adoptSubscriberChannel(new FakeDataChannel('_other') as unknown as RTCDataChannel),
+    ).toBe(false);
+  });
+
+  it('teardown rejects parked waiters, closes all handles, and detaches', async () => {
+    const { manager, pcManager, created } = makeManager();
+    manager.createPublisherChannels(pcManager);
+    const sub = new FakeDataChannel('_lossy');
+    manager.adoptSubscriberChannel(sub as unknown as RTCDataChannel);
+
+    created._reliable.bufferedAmount = 2 * 1024 * 1024;
+    const parked = manager.reliable.waitForHeadroomWithLock();
+    parked.catch(() => {});
+    await tick();
+
+    manager.teardown();
+
+    await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    for (const dc of [...Object.values(created), sub]) {
+      expect(dc.close).toHaveBeenCalled();
+      expect(dc.onmessage).toBeNull();
+    }
+    expect(manager.hasPublisherChannels).toBe(false);
+    expect(manager.getHandle(DataChannelKind.LOSSY, true)).toBeUndefined();
+
+    manager.lossy.stopThresholdTuning();
+  });
+});

package/src/room/data-channel/DataChannelManager.ts

@@ -0,0 +1,237 @@
+import type { PCTransportManager } from '../PCTransportManager';
+import { FlowControlledDataChannel } from './FlowControlledDataChannel';
+import { LossyDataChannel } from './LossyDataChannel';
+import { ReliableDataChannel } from './ReliableDataChannel';
+import { DataChannelKind, dataChannelHighWaterMark, dataChannelLowWaterMark } from './types';
+
+const lossyDataChannelLabel = '_lossy';
+const reliableDataChannelLabel = '_reliable';
+const dataTrackDataChannelLabel = '_data_track';
+
+export interface DataChannelManagerOptions {
+  /** Whether the owning engine has been closed — a closed engine rejects headroom waiters. */
+  isEngineClosed: () => boolean;
+  /**
+   * Whether a reconnect attempt is underway: reliable sends defer to the resume replay and lossy
+   * sends are skipped while this is true.
+   */
+  isReconnecting: () => boolean;
+  onDataMessage: (message: MessageEvent) => void;
+  onDataTrackMessage: (message: MessageEvent) => void;
+  onDataError: (event: Event) => void;
+  onChannelClose: (kind: DataChannelKind) => void;
+  /** A channel's buffer crossed its low-water mark (debounced). Drives DCBufferStatusChanged. */
+  onBufferStatusChanged: (kind: DataChannelKind, isLow: boolean) => void;
+}
+
+/**
+ * Owns the engine's data channels: the three flow-controlled publisher channel wrappers (which
+ * live for the engine's lifetime and have RTCDataChannel handles attached/detached as peer
+ * connections come and go) plus the subscriber-side receive handles adopted by label.
+ *
+ * Handle turnover goes through {@link FlowControlledDataChannel.attach}/`detach`, which reject
+ * parked headroom waiters as a built-in — there is no separate invalidation step to forget.
+ */
+export class DataChannelManager {
+  readonly reliable: ReliableDataChannel;
+
+  readonly lossy: LossyDataChannel;
+
+  readonly dataTrack: LossyDataChannel;
+
+  private reliableSub?: RTCDataChannel;
+
+  private lossySub?: RTCDataChannel;
+
+  private dataTrackSub?: RTCDataChannel;
+
+  private opts: DataChannelManagerOptions;
+
+  constructor(opts: DataChannelManagerOptions) {
+    this.opts = opts;
+    const flowControlOptions = (kind: DataChannelKind) => ({
+      kind,
+      lowWaterMark: dataChannelLowWaterMark(kind),
+      highWaterMark: dataChannelHighWaterMark(kind),
+      isEngineClosed: opts.isEngineClosed,
+      onBufferStatusChanged: (isLow: boolean) => opts.onBufferStatusChanged(kind, isLow),
+    });
+    this.reliable = new ReliableDataChannel({
+      ...flowControlOptions(DataChannelKind.RELIABLE),
+      isDeferringSends: opts.isReconnecting,
+    });
+    this.lossy = new LossyDataChannel({
+      ...flowControlOptions(DataChannelKind.LOSSY),
+      // Classic lossy user data: a stale packet is worthless, so drop instead of queueing.
+      bufferFullBehavior: 'drop',
+      shouldSkipSends: opts.isReconnecting,
+    });
+    this.dataTrack = new LossyDataChannel({
+      ...flowControlOptions(DataChannelKind.DATA_TRACK_LOSSY),
+      // Data tracks backpressure the producer instead — it decides what to skip at frame
+      // granularity rather than the engine dropping arbitrary chunks out of frames.
+      bufferFullBehavior: 'wait',
+      shouldSkipSends: opts.isReconnecting,
+    });
+  }
+
+  /** The flow-control wrapper for `kind`. */
+  channelFor(kind: DataChannelKind): FlowControlledDataChannel {
+    switch (kind) {
+      case DataChannelKind.RELIABLE:
+        return this.reliable;
+      case DataChannelKind.LOSSY:
+        return this.lossy;
+      case DataChannelKind.DATA_TRACK_LOSSY:
+        return this.dataTrack;
+    }
+  }
+
+  /** The raw RTCDataChannel handle for `kind`, publisher side by default. */
+  getHandle(kind: DataChannelKind, subscriber: boolean = false): RTCDataChannel | undefined {
+    if (!subscriber) {
+      return this.channelFor(kind).channelHandle;
+    }
+    switch (kind) {
+      case DataChannelKind.RELIABLE:
+        return this.reliableSub;
+      case DataChannelKind.LOSSY:
+        return this.lossySub;
+      case DataChannelKind.DATA_TRACK_LOSSY:
+        return this.dataTrackSub;
+    }
+  }
+
+  get hasPublisherChannels(): boolean {
+    return Boolean(
+      this.reliable.channelHandle || this.lossy.channelHandle || this.dataTrack.channelHandle,
+    );
+  }
+
+  /**
+   * Creates the three publisher data channels on the given transport, wires their handlers, and
+   * attaches them to the wrappers — attaching rejects any waiters still parked on replaced
+   * channel objects.
+   */
+  createPublisherChannels(pcManager: PCTransportManager) {
+    // clear old data channel callbacks if recreate
+    for (const channel of [this.lossy, this.reliable, this.dataTrack]) {
+      const old = channel.channelHandle;
+      if (old) {
+        old.onmessage = null;
+        old.onerror = null;
+        old.onclose = null;
+      }
+    }
+
+    const wire = (
+      channel: FlowControlledDataChannel,
+      dc: RTCDataChannel,
+      onMessage: (message: MessageEvent) => void,
+    ) => {
+      // also handle messages over the pub channel, for backwards compatibility
+      dc.onmessage = onMessage;
+      // handle datachannel errors
+      dc.onerror = this.opts.onDataError;
+      // detect unexpected publisher data channel closes
+      dc.onclose = () => this.opts.onChannelClose(channel.kind);
+      // set up dc buffer threshold - if this is not set, it will default to 0
+      dc.bufferedAmountLowThreshold = channel.lowWaterMark;
+      // handle buffer amount low events
+      dc.onbufferedamountlow = () => channel.refreshBufferStatus();
+      channel.attach(dc);
+    };
+
+    wire(
+      this.lossy,
+      pcManager.createPublisherDataChannel(lossyDataChannelLabel, {
+        ordered: false,
+        maxRetransmits: 0,
+      }),
+      this.opts.onDataMessage,
+    );
+    wire(
+      this.reliable,
+      pcManager.createPublisherDataChannel(reliableDataChannelLabel, {
+        ordered: true,
+      }),
+      this.opts.onDataMessage,
+    );
+    wire(
+      this.dataTrack,
+      pcManager.createPublisherDataChannel(dataTrackDataChannelLabel, {
+        ordered: false,
+        maxRetransmits: 0,
+      }),
+      this.opts.onDataTrackMessage,
+    );
+
+    this.lossy.startThresholdTuning();
+  }
+
+  /**
+   * Adopts a subscriber-side data channel by label, wiring the matching receive handler.
+   * Returns false for labels this manager doesn't own.
+   */
+  adoptSubscriberChannel(channel: RTCDataChannel): boolean {
+    let handler: (message: MessageEvent) => void;
+    if (channel.label === reliableDataChannelLabel) {
+      this.reliableSub = channel;
+      handler = this.opts.onDataMessage;
+    } else if (channel.label === lossyDataChannelLabel) {
+      this.lossySub = channel;
+      handler = this.opts.onDataMessage;
+    } else if (channel.label === dataTrackDataChannelLabel) {
+      this.dataTrackSub = channel;
+      handler = this.opts.onDataTrackMessage;
+    } else {
+      return false;
+    }
+    channel.onmessage = handler;
+    return true;
+  }
+
+  /**
+   * Tears down all channels for a peer-connection cleanup: rejects parked waiters (detach — the
+   * spec allows `pc.close()` to transition channels to 'closed' without firing events, so waiting
+   * for browser close events is not an option), strips handlers, closes the handles, and resets
+   * the reliable session state.
+   */
+  teardown() {
+    const dcCleanup = (dc: RTCDataChannel | undefined) => {
+      if (!dc) {
+        return;
+      }
+
+      // Detach the data channel handlers before closing anything. Closing a peer connection tears
+      // down the SCTP transport, which can dispatch `error`/`close` events on the still-open data
+      // channels; if our handlers are still attached at that point, handleDataError logs a spurious
+      // "Unknown DataChannel error" during an otherwise graceful disconnect. Removing the handlers
+      // before dc.close()/pcManager.close() makes this deterministic regardless of how/when the
+      // browser dispatches those teardown events. See livekit/client-sdk-js#1953.
+      dc.onbufferedamountlow = null;
+      dc.onclose = null;
+      dc.onclosing = null;
+      dc.onerror = null;
+      dc.onmessage = null;
+      dc.onopen = null;
+
+      dc.close();
+    };
+
+    for (const channel of [this.lossy, this.reliable, this.dataTrack]) {
+      const dc = channel.channelHandle;
+      channel.detach('peer connections cleaned up');
+      dcCleanup(dc);
+    }
+    dcCleanup(this.lossySub);
+    dcCleanup(this.reliableSub);
+    dcCleanup(this.dataTrackSub);
+    this.lossySub = undefined;
+    this.reliableSub = undefined;
+    this.dataTrackSub = undefined;
+
+    // Full teardown starts the session over: drop replay state and restart sequencing.
+    this.reliable.reset();
+  }
+}

package/src/room/data-channel/FlowControlledDataChannel.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from 'vitest';
+import { UnexpectedConnectionState } from '../errors';
+import { FlowControlledDataChannel } from './FlowControlledDataChannel';
+import { DataChannelKind } from './types';
+
+class FakeDataChannel extends EventTarget {
+  bufferedAmount = 0;
+
+  bufferedAmountLowThreshold = 64;
+}
+
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+// Pass `dc: null` for a handle-less channel; omit it to get a fresh one. `null` (not `undefined`)
+// is deliberate — a destructuring default fills in on `undefined`, so only `null` passes through.
+function makeChannel({
+  dc = new FakeDataChannel(),
+  engineClosed = false,
+}: { dc?: FakeDataChannel | null; engineClosed?: boolean } = {}) {
+  const state = { engineClosed };
+  const onBufferStatusChanged = vi.fn();
+  const channel = new FlowControlledDataChannel({
+    kind: DataChannelKind.RELIABLE,
+    lowWaterMark: 64,
+    highWaterMark: 1024,
+    isEngineClosed: () => state.engineClosed,
+    onBufferStatusChanged,
+  });
+  if (dc) {
+    channel.attach(dc as unknown as RTCDataChannel);
+  }
+  return { channel, dc: dc as FakeDataChannel, state, onBufferStatusChanged };
+}
+
+describe('FlowControlledDataChannel', () => {
+  describe('refreshBufferStatus', () => {
+    it('notifies only on a change and in both directions', () => {
+      const { channel, dc, onBufferStatusChanged } = makeChannel();
+
+      // Starts "low" (empty buffer); a refresh that stays low emits nothing.
+      channel.refreshBufferStatus();
+      expect(onBufferStatusChanged).not.toHaveBeenCalled();
+
+      // Cross above the low mark → one not-low notification.
+      dc.bufferedAmount = 512;
+      channel.refreshBufferStatus();
+      channel.refreshBufferStatus(); // debounced: no second fire
+      expect(onBufferStatusChanged.mock.calls).toEqual([[false]]);
+
+      // Drain back below → one low notification.
+      dc.bufferedAmount = 0;
+      channel.refreshBufferStatus();
+      expect(onBufferStatusChanged.mock.calls).toEqual([[false], [true]]);
+    });
+
+    it('is a no-op without a handle (no throw, no notification)', () => {
+      const { channel, onBufferStatusChanged } = makeChannel({ dc: null });
+      expect(() => channel.refreshBufferStatus()).not.toThrow();
+      expect(onBufferStatusChanged).not.toHaveBeenCalled();
+    });
+  });
+
+  it('reports watermark status against the given channel', () => {
+    const { channel, dc } = makeChannel();
+    const handle = dc as unknown as RTCDataChannel;
+    dc.bufferedAmount = 0;
+    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle)).toBe(true);
+
+    dc.bufferedAmount = 512; // between low (64) and high (1024)
+    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle)).toBe(false);
+
+    dc.bufferedAmount = 2048;
+    expect(channel.isBelowHighWaterMark(handle)).toBe(false);
+  });
+
+  it('waiting for headroom without a handle rejects with a connection error', async () => {
+    const { channel } = makeChannel({ dc: null });
+    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+      UnexpectedConnectionState,
+    );
+  });
+
+  it('resolves immediately while below the high-water mark', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 1024;
+    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+  });
+
+  it('parks above the high-water mark and resumes on bufferedamountlow', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const resolved = vi.fn();
+    const wait = channel.waitForHeadroomWithLock().then(resolved);
+    await tick();
+    expect(resolved).not.toHaveBeenCalled();
+
+    dc.bufferedAmount = 32;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await wait;
+    expect(resolved).toHaveBeenCalled();
+  });
+
+  it('rejects a parked waiter when the channel closes', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const wait = channel.waitForHeadroomWithLock();
+    wait.catch(() => {});
+    await tick();
+
+    dc.dispatchEvent(new Event('close'));
+    await expect(wait).rejects.toBeInstanceOf(UnexpectedConnectionState);
+  });
+
+  it('rejects a parked waiter on invalidateWaiters and recovers with a fresh controller', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const wait = channel.waitForHeadroomWithLock();
+    wait.catch(() => {});
+    await tick();
+
+    channel.invalidateWaiters('channel replaced');
+    await expect(wait).rejects.toBeInstanceOf(UnexpectedConnectionState);
+
+    // Fresh controller: the gate is usable again and the lock was released.
+    dc.bufferedAmount = 0;
+    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+  });
+
+  it('rejects immediately when the engine is closed', async () => {
+    const { channel, state } = makeChannel();
+    state.engineClosed = true;
+    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+      UnexpectedConnectionState,
+    );
+  });
+
+  it('serializes waiters FIFO through the headroom lock', async () => {
+    const { channel, dc } = makeChannel();
+    dc.bufferedAmount = 2048;
+    const order: number[] = [];
+    const first = channel.waitForHeadroomWithLock().then(() => order.push(1));
+    const second = channel.waitForHeadroomWithLock().then(() => order.push(2));
+    await tick();
+
+    // One drain event wakes the head waiter; the second re-checks under the lock and, with the
+    // buffer now low, proceeds right after — strictly in arrival order.
+    dc.bufferedAmount = 0;
+    dc.dispatchEvent(new Event('bufferedamountlow'));
+    await Promise.all([first, second]);
+    expect(order).toEqual([1, 2]);
+  });
+});