livekit-client 2.22.4 → 2.23.0

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

@@ -7,8 +7,17 @@ class FakeDataChannel extends EventTarget {
   bufferedAmount = 0;
 
   bufferedAmountLowThreshold = 64;
+
+  readyState: RTCDataChannelState = 'open';
+
+  // Like the real thing, close() moves to 'closing' synchronously.
+  close = vi.fn(() => {
+    this.readyState = 'closing';
+  });
 }
 
+const handle = (dc: FakeDataChannel) => dc as unknown as RTCDataChannel;
+
 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`)
@@ -62,37 +71,54 @@ describe('FlowControlledDataChannel', () => {
 
   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);
+    expect(channel.isBelowHighWaterMark(handle(dc))).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle(dc))).toBe(true);
 
     dc.bufferedAmount = 512; // between low (64) and high (1024)
-    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
-    expect(channel.isBelowLowWaterMark(handle)).toBe(false);
+    expect(channel.isBelowHighWaterMark(handle(dc))).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle(dc))).toBe(false);
 
     dc.bufferedAmount = 2048;
-    expect(channel.isBelowHighWaterMark(handle)).toBe(false);
+    expect(channel.isBelowHighWaterMark(handle(dc))).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(
+  it('rejects a wait on a handle that is not open', async () => {
+    const { channel, dc } = makeChannel();
+    dc.readyState = 'connecting';
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).rejects.toBeInstanceOf(
       UnexpectedConnectionState,
     );
   });
 
+  it('rejects a wait queued on the lock once its handle is replaced', async () => {
+    const { channel, dc: oldDc } = makeChannel();
+    oldDc.bufferedAmount = 2048;
+    const parked = channel.waitForHeadroomWithLock(handle(oldDc));
+    parked.catch(() => {});
+    // Queued behind the parked waiter, so the abort on replacement doesn't reach it — the closed
+    // handle does, once it gets the lock.
+    const queued = channel.waitForHeadroomWithLock(handle(oldDc));
+    queued.catch(() => {});
+    await tick();
+
+    channel.attach(handle(new FakeDataChannel()));
+
+    await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    await expect(queued).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();
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).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);
+    const wait = channel.waitForHeadroomWithLock(handle(dc)).then(resolved);
     await tick();
     expect(resolved).not.toHaveBeenCalled();
 
@@ -105,7 +131,7 @@ describe('FlowControlledDataChannel', () => {
   it('rejects a parked waiter when the channel closes', async () => {
     const { channel, dc } = makeChannel();
     dc.bufferedAmount = 2048;
-    const wait = channel.waitForHeadroomWithLock();
+    const wait = channel.waitForHeadroomWithLock(handle(dc));
     wait.catch(() => {});
     await tick();
 
@@ -116,7 +142,7 @@ describe('FlowControlledDataChannel', () => {
   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();
+    const wait = channel.waitForHeadroomWithLock(handle(dc));
     wait.catch(() => {});
     await tick();
 
@@ -125,13 +151,29 @@ describe('FlowControlledDataChannel', () => {
 
     // Fresh controller: the gate is usable again and the lock was released.
     dc.bufferedAmount = 0;
-    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).resolves.toBeUndefined();
+  });
+
+  it('closes the handle it lets go of, on replacement and on detach', () => {
+    const { channel, dc: first } = makeChannel();
+    const second = new FakeDataChannel();
+
+    channel.attach(first as unknown as RTCDataChannel); // re-attaching the same handle is a no-op
+    expect(first.close).not.toHaveBeenCalled();
+
+    channel.attach(second as unknown as RTCDataChannel);
+    expect(first.close).toHaveBeenCalledTimes(1);
+    expect(second.close).not.toHaveBeenCalled();
+
+    channel.detach();
+    expect(second.close).toHaveBeenCalledTimes(1);
+    expect(channel.channelHandle).toBeUndefined();
   });
 
   it('rejects immediately when the engine is closed', async () => {
-    const { channel, state } = makeChannel();
+    const { channel, dc, state } = makeChannel();
     state.engineClosed = true;
-    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).rejects.toBeInstanceOf(
       UnexpectedConnectionState,
     );
   });
@@ -140,8 +182,8 @@ describe('FlowControlledDataChannel', () => {
     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));
+    const first = channel.waitForHeadroomWithLock(handle(dc)).then(() => order.push(1));
+    const second = channel.waitForHeadroomWithLock(handle(dc)).then(() => order.push(2));
     await tick();
 
     // One drain event wakes the head waiter; the second re-checks under the lock and, with the

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

@@ -30,7 +30,8 @@ export interface FlowControlledDataChannelOptions {
  * Waiters are parked on the channel object captured at wait entry. If that object stops being
  * current — replaced or torn down — its events may never fire again, so the owner must call
  * {@link invalidateWaiters}, which aborts parked waiters (releasing the gate); the next waiter
- * gets a fresh controller.
+ * gets a fresh controller. {@link attach} and {@link detach} do this, and close the released
+ * handle, as part of handle turnover.
  */
 export class FlowControlledDataChannel {
   readonly kind: DataChannelKind;
@@ -67,25 +68,39 @@ export class FlowControlledDataChannel {
   }
 
   /**
-   * Attaches the channel handle this wrapper controls. Replacing an existing handle rejects
-   * parked waiters — their events would never fire again on the abandoned object — and installs a
-   * fresh controller, so queued senders re-check against the new channel. Wrappers outlive their
-   * handles: this is the one place handle turnover happens, which is what makes stranding a
-   * waiter structurally impossible.
+   * Attaches the channel handle this wrapper controls. Replacing an existing handle closes it and
+   * rejects parked waiters — their events would never fire again on the abandoned object — and
+   * installs a fresh controller. Wrappers outlive their handles: this is the one place handle
+   * turnover happens, so a handle the wrapper lets go of is never left open, and stranding a
+   * waiter is structurally impossible.
    */
   attach(dc: RTCDataChannel) {
-    if (this.handle && this.handle !== dc) {
-      this.invalidateWaiters('data channel replaced');
-    }
+    const old = this.handle;
     this.handle = dc;
+    if (old && old !== dc) {
+      this.release(old, 'data channel replaced');
+    }
   }
 
-  /** Detaches the handle on teardown, rejecting parked waiters. */
+  /** Detaches and closes the handle on teardown, rejecting parked waiters. */
   detach(reason: string = 'data channel torn down') {
-    if (this.handle) {
-      this.invalidateWaiters(reason);
-    }
+    const old = this.handle;
     this.handle = undefined;
+    if (old) {
+      this.release(old, reason);
+    }
+  }
+
+  /**
+   * Closes a handle the wrapper no longer controls. `close()` moves it to `closing` synchronously,
+   * so senders still holding it (queued on the headroom lock) fail the open check once they get
+   * the lock. Parked waiters are aborted directly instead of relying on the `close` event, which
+   * fires asynchronously, if at all (the spec lets `pc.close()` skip it). Strip any handlers that
+   * must not observe the close before calling this.
+   */
+  private release(dc: RTCDataChannel, reason: string) {
+    this.invalidateWaiters(reason);
+    dc.close();
   }
 
   protected getChannel(): RTCDataChannel | undefined {
@@ -121,30 +136,33 @@ export class FlowControlledDataChannel {
   }
 
   /**
-   * Resolves once the caller may send on this channel: immediately while the send buffer is at or
-   * below its high-water mark, otherwise once the buffer has drained to the low-water mark (the
+   * Resolves once the caller may send on `dc`: immediately while its send buffer is at or below
+   * the high-water mark, otherwise once the buffer has drained to the low-water mark (the
    * `bufferedamountlow` event). Callers are serialized through the headroom lock so that, when
    * the buffer drains, they refill it one at a time (up to the high-water mark) rather than all
    * sending at once and overflowing the SCTP send buffer (see livekit/client-sdk-js#1995). The
-   * closed/buffer checks run inside the lock so queued callers proceed in FIFO order.
+   * checks run inside the lock so queued callers proceed in FIFO order.
+   *
+   * The caller passes the handle it resolved before queueing, and the wait is against that one
+   * handle throughout: if it was replaced meanwhile, it has been closed, so the wait rejects
+   * rather than letting the caller send on the replacement out of turn.
    */
-  async waitForHeadroomWithLock() {
+  async waitForHeadroomWithLock(dc: RTCDataChannel) {
     const unlock = await this.lockHeadroom();
     try {
-      await this.waitForHeadroomWithoutLock();
+      await this.waitForHeadroomWithoutLock(dc);
     } finally {
       unlock();
     }
   }
 
   /** Core wait of {@link waitForHeadroomWithLock}. The caller must hold the headroom lock. */
-  async waitForHeadroomWithoutLock() {
+  async waitForHeadroomWithoutLock(dc: RTCDataChannel) {
     if (this.isEngineClosed()) {
       throw new UnexpectedConnectionState('engine closed');
     }
-    const dc = this.getChannel();
-    if (!dc) {
-      throw new UnexpectedConnectionState(`DataChannel not found, kind: ${this.kind}`);
+    if (dc.readyState !== 'open') {
+      throw new UnexpectedConnectionState(`DataChannel ${this.kind} is ${dc.readyState}`);
     }
     if (this.isBelowHighWaterMark(dc)) {
       return;

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

@@ -8,6 +8,13 @@ class FakeDataChannel extends EventTarget {
   bufferedAmountLowThreshold = 64;
 
   send = vi.fn();
+
+  readyState: RTCDataChannelState = 'open';
+
+  // Like the real thing, close() moves to 'closing' synchronously.
+  close = vi.fn(() => {
+    this.readyState = 'closing';
+  });
 }
 
 // Pass `dc: null` for a handle-less channel; omit it to get a fresh one. `null` (not `undefined`)
@@ -76,6 +83,37 @@ describe('LossyDataChannel', () => {
     expect(dc.send).toHaveBeenCalledTimes(1);
   });
 
+  it('wait policy: drops waiting sends when the channel is replaced', async () => {
+    const { channel, dc: oldDc } = makeChannel('wait');
+    oldDc.bufferedAmount = 2048;
+    const parked = channel.send(new Uint8Array([1]));
+    const queued = channel.send(new Uint8Array([2]));
+    await vi.advanceTimersByTimeAsync(0);
+
+    const newDc = new FakeDataChannel();
+    channel.attach(newDc as unknown as RTCDataChannel);
+
+    // Both resolve: a dropped frame mustn't reject (the room doesn't handle frame send failures).
+    await expect(parked).resolves.toBeUndefined();
+    await expect(queued).resolves.toBeUndefined();
+    // Not on the abandoned channel, and not on the replacement, which may still be connecting.
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(newDc.send).not.toHaveBeenCalled();
+  });
+
+  it('wait policy: rejects a waiting send when the engine closes', async () => {
+    const { channel, dc, state } = makeChannel('wait');
+    dc.bufferedAmount = 2048;
+    const send = channel.send(new Uint8Array([1]));
+    send.catch(() => {});
+    await vi.advanceTimersByTimeAsync(0);
+
+    state.engineClosed = true;
+    channel.detach();
+
+    await expect(send).rejects.toThrow();
+  });
+
   it('skips sends while a reconnect is underway', async () => {
     const { channel, dc, state } = makeChannel('drop');
     state.skipSends = true;

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

@@ -55,7 +55,16 @@ export class LossyDataChannel extends FlowControlledDataChannel {
     switch (this.bufferFullBehavior) {
       case 'wait':
         if (!this.isBelowHighWaterMark(dc)) {
-          await this.waitForHeadroomWithLock();
+          try {
+            await this.waitForHeadroomWithLock(dc);
+          } catch (error) {
+            if (this.isEngineClosed()) {
+              throw error;
+            }
+            // The channel closed or was replaced while this send waited. The replacement may
+            // still be connecting, so drop the packet, as sends during a reconnect are.
+            return;
+          }
         }
         break;
       case 'drop':

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

@@ -9,6 +9,13 @@ class FakeDataChannel extends EventTarget {
   bufferedAmountLowThreshold = 64;
 
   send = vi.fn();
+
+  readyState: RTCDataChannelState = 'open';
+
+  // Like the real thing, close() moves to 'closing' synchronously.
+  close = vi.fn(() => {
+    this.readyState = 'closing';
+  });
 }
 
 const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
@@ -77,6 +84,33 @@ describe('ReliableDataChannel', () => {
     expect(buffer.getAll()[0].sent).toBe(false);
   });
 
+  it('defers a send queued on the lock to the replay when the channel is replaced, preserving order', async () => {
+    const { channel, dc: oldDc, buffer } = makeChannel();
+    oldDc.bufferedAmount = 2048; // above high mark → the first send parks
+    const parked = channel.send(new Uint8Array([1]), channel.nextSequence());
+    // Queues behind the parked send on the headroom lock; replacing the handle rejects only the
+    // parked waiter, so this one gets the lock afterwards.
+    const queued = channel.send(new Uint8Array([2]), channel.nextSequence());
+    await tick();
+
+    const newDc = new FakeDataChannel();
+    channel.attach(newDc as unknown as RTCDataChannel);
+
+    await expect(parked).resolves.toBeUndefined();
+    await expect(queued).resolves.toBeUndefined();
+    // Neither goes out ahead of the replay: sending seq 2 now would make receivers discard seq 1
+    // once the replay delivers it.
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(newDc.send).not.toHaveBeenCalled();
+    expect(buffer.getAll().map(({ sequence, sent }) => ({ sequence, sent }))).toEqual([
+      { sequence: 1, sent: false },
+      { sequence: 2, sent: false },
+    ]);
+
+    await channel.replay(0);
+    expect(newDc.send.mock.calls.map(([data]) => data[0])).toEqual([1, 2]);
+  });
+
   it('rejects when the engine is closed while waiting', async () => {
     const { channel, dc, state } = makeChannel();
     dc.bufferedAmount = 2048;
@@ -135,6 +169,44 @@ describe('ReliableDataChannel', () => {
     expect(buffer.getAll().filter((i) => !i.sent)).toHaveLength(0);
   });
 
+  it('replays on the replacement handle when the channel is replaced while replay waits for the lock', async () => {
+    const { channel, dc: oldDc } = makeChannel();
+    await channel.send(new Uint8Array([1]), channel.nextSequence());
+    oldDc.send.mockClear();
+
+    const unlock = await channel.lockHeadroom();
+    const replay = channel.replay(0);
+    await tick();
+
+    const newDc = new FakeDataChannel();
+    channel.attach(newDc as unknown as RTCDataChannel);
+    unlock();
+    await replay;
+
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(newDc.send).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops the replay, keeping the rest unsent, when the channel is replaced mid-replay', async () => {
+    const { channel, dc: oldDc, state, buffer } = makeChannel();
+    state.deferring = true;
+    await channel.send(new Uint8Array([1]), channel.nextSequence());
+    await channel.send(new Uint8Array([2]), channel.nextSequence());
+    state.deferring = false;
+
+    oldDc.bufferedAmount = 2048; // the replay parks before its first send
+    const replay = channel.replay(0);
+    replay.catch(() => {});
+    await tick();
+
+    // A second replacement belongs to another resume, whose replay delivers the backlog.
+    channel.attach(new FakeDataChannel() as unknown as RTCDataChannel);
+
+    await expect(replay).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(buffer.getAll().every((item) => !item.sent)).toBe(true);
+  });
+
   it('holds the headroom lock across the whole replay so new sends cannot interleave', async () => {
     const { channel, dc } = makeChannel();
     (channel as unknown as { isDeferringSends: () => boolean }).isDeferringSends = () => true;

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

@@ -1,5 +1,6 @@
 import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { DataPacketBuffer } from '../../utils/dataPacketBuffer';
+import { UnexpectedConnectionState } from '../errors';
 import {
   FlowControlledDataChannel,
   type FlowControlledDataChannelOptions,
@@ -64,7 +65,7 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
     }
 
     try {
-      await this.waitForHeadroomWithLock();
+      await this.waitForHeadroomWithLock(dc);
     } catch (error) {
       if (this.isEngineClosed()) {
         // No replay is coming after an engine close — surface the failure.
@@ -72,7 +73,9 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
       }
       // Transient teardown (the channel closed or was replaced while we waited): the reliable
       // channel promises delivery across resume, so queue the packet for the replay instead of
-      // rejecting a send the app can't meaningfully retry.
+      // rejecting a send the app can't meaningfully retry. This also keeps the order: a send
+      // queued behind one aborted by a replacement fails the same way (the old handle is closed),
+      // so it can't reach the replacement ahead of the lower sequence the replay will deliver.
       this.messageBuffer.push({ data: msg, sequence, sent: false });
       return;
     }
@@ -96,13 +99,18 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
    * receivers would then discard the remaining lower-sequence resent messages as duplicates.
    */
   async replay(lastMessageSeq: number) {
-    const dc = this.getChannel();
-    if (!dc) {
+    if (!this.getChannel()) {
       return;
     }
     this.messageBuffer.popToSequence(lastMessageSeq);
     const unlock = await this.lockHeadroom();
     try {
+      // Resolved only once the lock is held: the handle can be replaced while the replay waits
+      // for it.
+      const dc = this.getChannel();
+      if (!dc) {
+        throw new UnexpectedConnectionState(`DataChannel not found, kind: ${this.kind}`);
+      }
       // Everything left after the ack cutoff must be re-handed to the current channel.
       this.messageBuffer.markAllUnsent();
       // Drain in passes, re-scanning the live buffer each time: a send that arrives (deferred,
@@ -118,7 +126,10 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
       ) {
         for (const item of batch) {
           // Respect flow control on resume too, so a large resend doesn't overflow the buffer.
-          await this.waitForHeadroomWithoutLock();
+          // Against the handle resolved under the lock: if it is replaced mid-replay (another
+          // resume), it has been closed, so this throws and that resume's replay picks up the
+          // entries still flagged unsent.
+          await this.waitForHeadroomWithoutLock(dc);
           dc.send(item.data);
           this.messageBuffer.markSent(item);
         }

package/src/room/data-stream/incoming/IncomingDataStreamManager.test.ts

@@ -679,6 +679,37 @@ describe('IncomingDataStreamManager', () => {
         'Participant alice unexpectedly disconnected in the middle of sending data',
       );
     });
+
+    it('should error in flight streams when the controllers are cleared on room disconnect', async () => {
+      const manager = new IncomingDataStreamManager();
+      manager.setConnected(true);
+
+      const textReaderPromise = new Promise<TextStreamReader>((resolve) => {
+        manager.registerTextStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+      const byteReaderPromise = new Promise<ByteStreamReader>((resolve) => {
+        manager.registerByteStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+
+      manager.handleDataStreamPacket(headerPacket('text-1', 'textHeader'), Encryption_Type.NONE);
+      manager.handleDataStreamPacket(
+        chunkPacket('text-1', 0, new Uint8Array([0x68, 0x69])),
+        Encryption_Type.NONE,
+      );
+      manager.handleDataStreamPacket(headerPacket('byte-1', 'byteHeader'), Encryption_Type.NONE);
+      manager.handleDataStreamPacket(
+        chunkPacket('byte-1', 0, new Uint8Array([0x01])),
+        Encryption_Type.NONE,
+      );
+
+      // Room#handleDisconnect calls this while the streams are still open
+      manager.clearControllers();
+
+      const textReader = await textReaderPromise;
+      const byteReader = await byteReaderPromise;
+      await expect(textReader.readAll()).rejects.toThrow('Room disconnected');
+      await expect(byteReader.readAll()).rejects.toThrow('Room disconnected');
+    });
   });
 
   describe('Receiving v2 data streams', () => {

package/src/room/data-stream/incoming/IncomingDataStreamManager.ts

@@ -87,6 +87,17 @@ export default class IncomingDataStreamManager {
   }
 
   clearControllers() {
+    // Error any in flight streams so readers do not wait forever for chunks that can no longer arrive.
+    const abnormalEndError = new DataStreamError(
+      'Room disconnected in the middle of receiving data',
+      DataStreamErrorReason.AbnormalEnd,
+    );
+    for (const { controller } of this.byteStreamControllers.values()) {
+      controller.error(abnormalEndError);
+    }
+    for (const { controller } of this.textStreamControllers.values()) {
+      controller.error(abnormalEndError);
+    }
     this.byteStreamControllers.clear();
     this.textStreamControllers.clear();
     this.bufferedPackets = [];

package/src/room/participant/LocalParticipant.test.ts

@@ -1,6 +1,12 @@
-import { PacketTrailerFeature } from '@livekit/protocol';
+import {
+  type AddTrackRequest,
+  Encryption_Type,
+  PacketTrailerFeature,
+  VideoQuality,
+} from '@livekit/protocol';
 import { describe, expect, it, vi } from 'vitest';
 import type LocalTrack from '../track/LocalTrack';
+import type LocalVideoTrack from '../track/LocalVideoTrack';
 import { Track } from '../track/Track';
 import type { TrackPublishOptions } from '../track/options';
 import LocalParticipant from './LocalParticipant';
@@ -79,3 +85,132 @@ describe('LocalParticipant frame metadata publish options', () => {
     expect(participant.log.warn).toHaveBeenCalledOnce();
   });
 });
+
+type BackupCodecTestParticipant = {
+  encryptionType: Encryption_Type;
+  trackPublications: Map<string, { track: LocalVideoTrack }>;
+  roomOptions: { publishDefaults: TrackPublishOptions };
+  engine: {
+    isClosed: boolean;
+    addTrack: ReturnType<typeof vi.fn>;
+    createSimulcastSender: ReturnType<typeof vi.fn>;
+    negotiate: ReturnType<typeof vi.fn>;
+  };
+  log: { warn: ReturnType<typeof vi.fn>; debug: ReturnType<typeof vi.fn> };
+  publishAdditionalCodecForTrack: LocalParticipant['publishAdditionalCodecForTrack'];
+};
+
+// a resizing processor makes mediaStreamTrack (processed) and dimensions (raw capture) differ
+function makeBackupCodecTrack(
+  settings: MediaTrackSettings,
+  source = Track.Source.Camera,
+  captureSettings = settings,
+) {
+  return {
+    isLocal: true,
+    kind: Track.Kind.Video,
+    sid: 'TR_video',
+    source,
+    isMuted: false,
+    mediaStreamID: 'stream-id',
+    mediaStreamTrack: { enabled: true, id: 'primary-cid', getSettings: () => settings },
+    get dimensions() {
+      const { width, height } = captureSettings;
+      return width && height ? { width, height } : undefined;
+    },
+    addSimulcastTrack: () => ({ mediaStreamTrack: { id: 'backup-cid' } }),
+  } as unknown as LocalVideoTrack;
+}
+
+function makeBackupCodecParticipant(track: LocalVideoTrack) {
+  const participant = Object.create(LocalParticipant.prototype) as BackupCodecTestParticipant;
+  // Object.create runs no field initializers, so without this the encryption guard sees
+  // undefined and the method returns before publishing anything.
+  participant.encryptionType = Encryption_Type.NONE;
+  participant.trackPublications = new Map([['TR_video', { track }]]);
+  participant.roomOptions = {
+    publishDefaults: { videoCodec: 'vp9', backupCodec: { codec: 'vp8' }, simulcast: true },
+  };
+  participant.engine = {
+    isClosed: false,
+    addTrack: vi.fn(async () => ({})),
+    createSimulcastSender: vi.fn(async () => {}),
+    negotiate: vi.fn(async () => {}),
+  };
+  participant.log = { warn: vi.fn(), debug: vi.fn() };
+  return participant;
+}
+
+function capturedRequest(participant: BackupCodecTestParticipant): AddTrackRequest {
+  expect(participant.engine.addTrack).toHaveBeenCalledOnce();
+  return participant.engine.addTrack.mock.calls[0][0] as AddTrackRequest;
+}
+
+describe('LocalParticipant.publishAdditionalCodecForTrack', () => {
+  it('sets the capture dimensions and the backup codec layers', async () => {
+    const track = makeBackupCodecTrack({ width: 1280, height: 720 });
+    const participant = makeBackupCodecParticipant(track);
+
+    await participant.publishAdditionalCodecForTrack(track, 'vp8');
+
+    const req = capturedRequest(participant);
+    expect(req.width).toBe(1280);
+    expect(req.height).toBe(720);
+    expect(req.layers.length).toBeGreaterThan(0);
+    for (const layer of req.layers) {
+      expect(layer.width).toBeGreaterThan(0);
+      expect(layer.height).toBeGreaterThan(0);
+    }
+    expect(Math.max(...req.layers.map((layer) => layer.width))).toBe(1280);
+    expect(req.simulcastCodecs[0].codec).toBe('vp8');
+    expect(req.simulcastCodecs[0].layers).toEqual(req.layers);
+    expect(participant.log.warn).not.toHaveBeenCalled();
+  });
+
+  // screenshare disables simulcast for the backup codec, which collapses the encodings to a
+  // single unconstrained one and so to a single full size layer
+  it('sends one full size layer for a screenshare track', async () => {
+    const track = makeBackupCodecTrack({ width: 1280, height: 720 }, Track.Source.ScreenShare);
+    const participant = makeBackupCodecParticipant(track);
+
+    await participant.publishAdditionalCodecForTrack(track, 'vp8');
+
+    const req = capturedRequest(participant);
+    expect(req.layers).toHaveLength(1);
+    expect(req.layers[0].width).toBe(1280);
+    expect(req.layers[0].height).toBe(720);
+    expect(req.layers[0].quality).toBe(VideoQuality.HIGH);
+    expect(req.simulcastCodecs[0].layers).toEqual(req.layers);
+    expect(participant.log.warn).not.toHaveBeenCalled();
+  });
+
+  it('sizes layers from the processed track when a processor resizes', async () => {
+    const track = makeBackupCodecTrack({ width: 640, height: 360 }, Track.Source.Camera, {
+      width: 1280,
+      height: 720,
+    });
+    const participant = makeBackupCodecParticipant(track);
+
+    await participant.publishAdditionalCodecForTrack(track, 'vp8');
+
+    const req = capturedRequest(participant);
+    expect(req.width).toBe(640);
+    expect(req.height).toBe(360);
+    expect(Math.max(...req.layers.map((layer) => layer.width))).toBe(640);
+    expect(req.simulcastCodecs[0].layers).toEqual(req.layers);
+  });
+
+  it('omits layers when the capture dimensions are unknown', async () => {
+    const track = makeBackupCodecTrack({});
+    const participant = makeBackupCodecParticipant(track);
+
+    await participant.publishAdditionalCodecForTrack(track, 'vp8');
+
+    const req = capturedRequest(participant);
+    expect(req.width).toBe(0);
+    expect(req.height).toBe(0);
+    expect(req.layers).toEqual([]);
+    expect(req.simulcastCodecs[0].layers).toEqual([]);
+    expect(participant.log.warn).toHaveBeenCalledOnce();
+  });
+});