livekit-client 2.21.0 → 2.22.0

package/dist/ts4.2/room/RTCEngine.d.ts

@@ -1,5 +1,5 @@
 import type { AddTrackRequest, ConnectionQualityUpdate, JoinResponse, RegionSettings, StreamStateUpdate, SubscriptionPermissionUpdate, SubscriptionResponse } from '@livekit/protocol';
-import { DataPacket, DataTrackSubscriberHandles, DisconnectReason, Encryption_Type, ParticipantInfo, PublishDataTrackResponse, RequestResponse, Room as RoomModel, RoomMovedResponse, ServerInfo, SpeakerInfo, SubscribedQualityUpdate, TrackInfo, TrackUnpublishedResponse, Transcription, UnpublishDataTrackResponse } from '@livekit/protocol';
+import { DataPacket, DataTrackSubscriberHandles, DisconnectReason, Encryption_Type, ParticipantInfo, PublishDataTrackResponse, ReconnectReason, RequestResponse, Room as RoomModel, RoomMovedResponse, ServerInfo, SpeakerInfo, SubscribedQualityUpdate, TrackInfo, TrackUnpublishedResponse, Transcription, UnpublishDataTrackResponse } from '@livekit/protocol';
 import type TypedEventEmitter from 'typed-emitter';
 import type { SignalOptions } from '../api/SignalClient';
 import { SignalClient } from '../api/SignalClient';
@@ -80,6 +80,10 @@ export default class RTCEngine extends RTCEngine_base {
     private midToTrackId;
     /** used to indicate whether the browser is currently waiting to reconnect */
     private isWaitingForNetworkReconnect;
+    /** set while the local participant's connection quality is `LOST`; forces a full reconnect on timeout */
+    private lostQualityTimeout?;
+    /** timestamp (ms) the primary transport entered `CONNECTING`, used to bound how long we tolerate it */
+    private transportConnectingSince?;
     constructor(options: InternalRoomOptions);
     /** @internal */
     get logContext(): {
@@ -137,6 +141,21 @@ export default class RTCEngine extends RTCEngine_base {
     private createSimulcastTransceiverSender;
     private createRTCRtpSender;
     private handleDisconnect;
+    /**
+     * 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.
+     */
+    private handleLocalConnectionQuality;
+    private scheduleLostQualityReconnect;
+    private clearLostQualityTimeout;
+    /** Whether the publisher currently has any sender with a live track. */
+    private hasActivePublisherSenders;
+    /**
+     * 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(reason?: ReconnectReason): void;
     private attemptReconnect;
     private getNextRetryDelay;
     private restartConnection;

package/dist/ts4.2/room/Room.d.ts

@@ -78,6 +78,7 @@ declare class Room extends Room_base {
     private log;
     private bufferedEvents;
     private isResuming;
+    private pendingTrackAddedCallbacks;
     /**
      * map to store first point in time when a particular transcription segment was received
      */
@@ -226,6 +227,7 @@ declare class Room extends Room_base {
     private setupLocalParticipantEvents;
     private recreateEngine;
     private onTrackAdded;
+    private cancelPendingTrackAdded;
     private handleLocalTrackSubscribed;
     private emitLocalTrackSubscribed;
     private handleRestarting;

package/dist/ts4.2/room/participant/LocalParticipant.d.ts

@@ -222,7 +222,7 @@ export default class LocalParticipant extends Participant {
      *
      * @param options.topic Topic identifier used to route the stream to appropriate handlers.
      */
-    streamBytes(options?: StreamBytesOptions): Promise<import("../data-stream/outgoing/StreamWriter").ByteStreamWriter>;
+    streamBytes(options?: StreamBytesOptions): Promise<import("../..").ByteStreamWriter>;
     /**
      * Initiate an RPC call to a remote participant
      * @param params - Parameters for initiating the RPC call, see {@link PerformRpcParams}

package/dist/ts4.2/room/token-source/TokenSource.d.ts

@@ -34,13 +34,18 @@ declare class TokenSourceEndpoint extends TokenSourceCached {
     private createRequestFromOptions;
     protected update(options: TokenSourceFetchOptions): Promise<TokenSourceResponse>;
 }
-export type SandboxTokenServerOptions = {
+export type DevelopmentTokenServerOptions = {
     baseUrl?: string;
 };
-declare class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-    constructor(sandboxId: string, options: SandboxTokenServerOptions);
+declare class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+    constructor(tokenServerId: string, options: DevelopmentTokenServerOptions);
 }
-export type { TokenSourceLiteral, TokenSourceCustom, TokenSourceEndpoint, TokenSourceSandboxTokenServer };
+/** @deprecated use {@link DevelopmentTokenServerOptions} instead */
+export type SandboxTokenServerOptions = DevelopmentTokenServerOptions;
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+declare class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {
+}
+export type { TokenSourceLiteral, TokenSourceCustom, TokenSourceEndpoint, TokenSourceSandboxTokenServer, TokenSourceDevelopmentTokenServer };
 export { decodeTokenPayload, areTokenSourceFetchOptionsEqual };
 export declare const TokenSource: {
     /** TokenSource.literal contains a single, literal set of {@link TokenSourceResponseObject}
@@ -56,18 +61,22 @@ export declare 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: string, options?: EndpointOptions): TokenSourceEndpoint;
     /**
-     * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+     * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+     */
+    sandboxTokenServer(sandboxId: string, options?: SandboxTokenServerOptions): TokenSourceSandboxTokenServer;
+    /**
+     * 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: string, options?: SandboxTokenServerOptions): TokenSourceSandboxTokenServer;
+    developmentTokenServer(tokenServerId: string, options?: DevelopmentTokenServerOptions): TokenSourceDevelopmentTokenServer;
 };
 //# sourceMappingURL=TokenSource.d.ts.map

package/dist/ts4.2/room/track/LocalVideoTrack.d.ts

@@ -56,8 +56,19 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
     private applyEncodingsToSender;
     setProcessor(processor: TrackProcessor<Track.Kind.Video>, showProcessedStreamLocally?: boolean): Promise<void>;
     setDegradationPreference(preference: RTCDegradationPreference): Promise<void>;
+    /**
+     * 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`.
+     */
+    private applyDegradationPreference;
     addSimulcastTrack(codec: VideoCodec, encodings?: RTCRtpEncodingParameters[]): SimulcastTrackInfo | undefined;
-    setSimulcastTrackSender(codec: VideoCodec, sender: RTCRtpSender): void;
+    setSimulcastTrackSender(codec: VideoCodec, sender: RTCRtpSender): Promise<void>;
     /**
      * @internal
      * Sets codecs that should be publishing, returns new codecs that have not yet

package/dist/ts4.2/room/track/RemoteTrack.d.ts

@@ -29,7 +29,10 @@ export default abstract class RemoteTrack<TrackKind extends Track.Kind = Track.K
      */
     getPlayoutDelay(): number;
     startMonitor(): void;
+    stopMonitor(): void;
     protected abstract monitorReceiver(): void;
+    private timeSyncLoop;
+    private onTimeSyncListenerAdded;
     registerTimeSyncUpdate(): void;
 }
 //# sourceMappingURL=RemoteTrack.d.ts.map

package/dist/ts4.2/room/utils.d.ts

@@ -32,6 +32,20 @@ export declare function supportsAV1(): boolean;
 export declare function supportsVP9(): boolean;
 export declare function supportsH265(): boolean;
 export declare function isSVCCodec(codec?: string): boolean;
+/**
+ * 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
+ */
+export declare function negotiateDependencyDescriptor(transceiver: RTCRtpTransceiver): boolean;
 export declare function supportsSetSinkId(elm?: HTMLMediaElement): boolean;
 /**
  * Checks whether or not setting an audio output via {@link Room#setActiveDevice}
@@ -162,4 +176,5 @@ export declare function decodeBase64(base64: string): Uint8Array;
 export declare function extractMaxAgeFromRequestHeaders(headers: Headers): number | undefined;
 export declare function isCompressionStreamSupported(): boolean;
 export declare function isPublisherOfferWithJoinSupported(): boolean;
+export declare function extractTrackSid(mediaTrack: MediaStreamTrack, stream: MediaStream): Track.SID | undefined;
 //# sourceMappingURL=utils.d.ts.map

package/dist/ts4.2/test/promiseState.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Test helper: resolves `true` if `promise` is still pending after `ms`
+ * (default: one macrotask), `false` if it has already settled — regardless of
+ * whether it resolved or rejected.
+ *
+ * Use to assert that something has *not* happened yet (e.g. an onClose callback
+ * that must stay silent), optionally within a timeout window. Preferable to
+ * `Promise.race([p, Promise.resolve(sentinel)])` when the "not yet" needs to
+ * hold for a duration rather than just the current microtask.
+ */
+export declare function isPending(promise: Promise<unknown>, ms?: number): Promise<boolean>;
+//# sourceMappingURL=promiseState.d.ts.map

package/dist/ts4.2/utils/AsyncQueue.d.ts

@@ -1,8 +1,8 @@
 type QueueTask<T> = () => PromiseLike<T>;
 declare enum QueueTaskStatus {
-    'WAITING' = 0,
-    'RUNNING' = 1,
-    'COMPLETED' = 2
+    WAITING = 0,
+    RUNNING = 1,
+    COMPLETED = 2
 }
 type QueueTaskInfo = {
     id: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -66,12 +66,12 @@
     "@babel/core": "7.29.7",
     "@babel/preset-env": "7.29.7",
     "@bufbuild/protoc-gen-es": "^1.10.0",
-    "@changesets/cli": "2.31.0",
+    "@changesets/cli": "2.31.1",
     "@eslint/js": "10.0.1",
-    "@livekit/changesets-changelog-github": "^0.0.4",
+    "@livekit/changesets-changelog-github": "^0.2.0",
     "@livekit/throws-transformer": "^0.1.3",
-    "@rollup/plugin-babel": "7.0.0",
-    "@rollup/plugin-commonjs": "29.0.2",
+    "@rollup/plugin-babel": "7.1.0",
+    "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-json": "6.1.0",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
@@ -82,12 +82,12 @@
     "@types/events": "^3.0.3",
     "@types/sdp-transform": "2.15.0",
     "@types/ua-parser-js": "0.7.39",
-    "@typescript-eslint/eslint-plugin": "8.59.4",
-    "@typescript-eslint/parser": "8.59.4",
+    "@typescript-eslint/eslint-plugin": "8.64.0",
+    "@typescript-eslint/parser": "8.64.0",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "downlevel-dts": "^0.11.0",
-    "eslint": "10.4.0",
+    "eslint": "10.7.0",
     "eslint-config-airbnb-extended": "^2.3.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-compat": "^6.0.2",
@@ -97,19 +97,20 @@
     "glob": "^13.0.6",
     "happy-dom": "^20.0.0",
     "jsdom": "^26.1.0",
+    "livekit-server-sdk": "^2.17.0",
     "playwright": "^1.61.1",
     "prettier": "^3.4.2",
     "publint": "^0.3.21",
-    "rollup": "4.60.4",
+    "rollup": "4.62.2",
     "rollup-plugin-delete": "^2.1.0",
     "rollup-plugin-typescript2": "0.37.0",
-    "size-limit": "^11.2.0",
+    "size-limit": "^12.0.0",
     "tsx": "^4.21.0",
-    "typedoc": "0.28.19",
+    "typedoc": "0.28.20",
     "typedoc-plugin-no-inherit": "1.6.1",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.47.0",
-    "vite": "7.3.5",
+    "vite": "8.1.5",
     "vitest": "^4.1.10"
   },
   "scripts": {

package/src/api/SignalClient.e2e.test.ts

@@ -1,6 +1,8 @@
 import { type LeaveRequest, LeaveRequest_Action } from '@livekit/protocol';
-import { afterEach, beforeEach, describe, expect, inject, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, inject, it } from 'vitest';
 import { ConnectionErrorReason } from '../room/errors';
+import { sleep } from '../room/utils';
+import { isPending } from '../test/promiseState';
 import { createInvalidToken, createToken } from '../test/signalToken';
 import { SignalClient, SignalConnectionState, type SignalOptions } from './SignalClient';
 
@@ -15,8 +17,6 @@ const defaultOpts = (): SignalOptions => ({
   websocketTimeout: 5_000,
 });
 
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
 function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
   return Promise.race([
     p,
@@ -70,12 +70,11 @@ describe.skipIf(!!unavailable)('SignalClient e2e', () => {
     });
 
     it('stays connected past the ping timeout while the server pongs', async () => {
-      const onClose = vi.fn();
       await join('happy');
-      client.onClose = onClose;
+      const closed = captureClose(client);
       // Server ping timeout is 3s; a healthy pong loop must keep us alive.
       await sleep(4_000);
-      expect(onClose).not.toHaveBeenCalled();
+      expect(await isPending(closed)).toBe(true);
       expect(client.currentState).toBe(SignalConnectionState.CONNECTED);
     });
 
@@ -151,15 +150,19 @@ describe.skipIf(!!unavailable)('SignalClient e2e', () => {
         (e) => e as Error,
       );
       expect(err).toBeInstanceOf(Error);
+      expect((err as { reason?: ConnectionErrorReason }).reason).toBe(
+        ConnectionErrorReason.LeaveRequest,
+      );
+      expect((err as Error).message).toContain('Received leave request');
     });
 
     it('closes gracefully via close() without firing onClose', async () => {
-      const onClose = vi.fn();
       await join('happy');
-      client.onClose = onClose;
+      const closed = captureClose(client);
       await client.close();
       expect(client.isDisconnected).toBe(true);
-      expect(onClose).not.toHaveBeenCalled();
+      // Give any stray onClose a macrotask to land before asserting it stayed silent.
+      expect(await isPending(closed, 100)).toBe(true);
     });
 
     it('reconnects (resume) back to CONNECTED', async () => {
@@ -181,6 +184,10 @@ describe.skipIf(!!unavailable)('SignalClient e2e', () => {
         (e) => e as Error,
       );
       expect(err).toBeInstanceOf(Error);
+      expect((err as { reason?: ConnectionErrorReason }).reason).toBe(
+        ConnectionErrorReason.LeaveRequest,
+      );
+      expect((err as Error).message).toContain('Received leave request');
     });
 
     // --- validate-endpoint classification -------------------------------

package/src/e2ee/utils.ts

@@ -139,7 +139,7 @@ export function needsRbspUnescaping(frameData: NonSharedUint8Array) {
 export function parseRbsp(stream: NonSharedUint8Array): NonSharedUint8Array {
   const dataOut: number[] = [];
   var length = stream.length;
-  for (var i = 0; i < stream.length; ) {
+  for (var i = 0; i < stream.length;) {
     // Be careful about over/underflow here. byte_length_ - 3 can underflow, and
     // i + 3 can overflow, but byte_length_ - i can't, because i < byte_length_
     // above, and that expression will produce the number of bytes left in

package/src/room/PCTransport.test.ts

@@ -1,6 +1,15 @@
 import { type MediaDescription, parse } from 'sdp-transform';
 import { describe, expect, it } from 'vitest';
-import { conformBundledCodecFmtp, placeholderMidsFromTransceivers } from './PCTransport';
+import {
+  applyVideoStartBitrate,
+  conformBundledCodecFmtp,
+  ensureAudioNackAndStereo,
+  ensureVideoDDExtension,
+  extractStereoAndNackAudioFromOffer,
+  fmtpConfigHasParam,
+  placeholderMidsFromTransceivers,
+} from './PCTransport';
+import { ddExtensionURI } from './utils';
 
 /** Parse the `key[=value]` pairs of an fmtp config into a comparable set. */
 const paramSet = (config: string) => new Set(config.split(';').filter(Boolean));
@@ -52,6 +61,35 @@ a=recvonly
 a=rtpmap:49 H265/90000
 a=fmtp:49 level-id=180;profile-id=1;tier-flag=0;tx-mode=SRST`;
 
+describe('video start bitrate', () => {
+  it('applies the bitrate only to the section whose msid track ID matches the cid', () => {
+    const { media } = parse(`v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+a=group:BUNDLE 0 1
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:0
+a=sendonly
+a=msid:PA_remote|camera other-track
+a=rtpmap:96 VP8/90000
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:1
+a=sendonly
+a=msid:PA_remote|camera camera-cid
+a=rtpmap:96 VP8/90000`);
+
+    for (const section of media) {
+      applyVideoStartBitrate(section, 'camera-cid', 'VP8', 1_000);
+    }
+
+    expect(fmtpOf(media, '0', 96)).toBeUndefined();
+    expect(paramSet(fmtpOf(media, '1', 96)!)).toContain('x-google-start-bitrate=900');
+  });
+});
+
 describe('placeholderMidsFromTransceivers', () => {
   const tr = (mid: string | null, track: unknown) =>
     ({ mid, sender: { track } }) as unknown as RTCRtpTransceiver;
@@ -148,3 +186,207 @@ a=fmtp:49 level-id=180;profile-id=1;tier-flag=0;tx-mode=SRST`);
     expect(fmtpOf(media, '5', 49)).toBe(fmtpOf(media, '3', 49)); // placeholder conformed
   });
 });
+
+describe('fmtpConfigHasParam', () => {
+  it('matches a whole `;`-delimited parameter, not a substring', () => {
+    // `stereo=1` is a substring of `sprop-stereo=1` — an exact-token match must
+    // not treat the latter as declaring the former.
+    expect(fmtpConfigHasParam('minptime=10;stereo=1', 'stereo=1')).toBe(true);
+    expect(fmtpConfigHasParam('minptime=10;sprop-stereo=1', 'stereo=1')).toBe(false);
+    expect(fmtpConfigHasParam('minptime=10;sprop-stereo=1', 'sprop-stereo=1')).toBe(true);
+  });
+
+  it('tolerates surrounding whitespace between parameters', () => {
+    expect(fmtpConfigHasParam('minptime=10; stereo=1', 'stereo=1')).toBe(true);
+  });
+});
+
+/** Build a parsed audio media section from its `a=` lines for the munge helpers. */
+const audioSection = (rtpmap: string, fmtp: string, mid = '0') =>
+  parse(`v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+m=audio 9 UDP/TLS/RTP/SAVPF 111
+a=mid:${mid}
+${rtpmap}
+${fmtp}`).media[0];
+
+describe('ensureAudioNackAndStereo', () => {
+  it('adds stereo=1 even when sprop-stereo=1 is already present', () => {
+    const media = audioSection(
+      'a=rtpmap:111 opus/48000/2',
+      'a=fmtp:111 minptime=10;sprop-stereo=1',
+    );
+
+    ensureAudioNackAndStereo(media as any, ['all'], []);
+
+    const config = media.fmtp.find((f) => f.payload === 111)!.config;
+    expect(paramSet(config)).toContain('stereo=1');
+    expect(paramSet(config)).toContain('sprop-stereo=1');
+  });
+
+  it('does not add a duplicate stereo=1 when it is already present', () => {
+    const media = audioSection('a=rtpmap:111 opus/48000/2', 'a=fmtp:111 minptime=10;stereo=1');
+
+    ensureAudioNackAndStereo(media as any, ['all'], []);
+
+    const config = media.fmtp.find((f) => f.payload === 111)!.config;
+    expect(config.match(/(?:^|;)stereo=1(?:;|$)/g)).toHaveLength(1);
+  });
+
+  it('matches the opus codec case-insensitively (RFC 4855)', () => {
+    const media = audioSection('a=rtpmap:111 OPUS/48000/2', 'a=fmtp:111 minptime=10');
+
+    ensureAudioNackAndStereo(media as any, ['all'], []);
+
+    expect(paramSet(media.fmtp.find((f) => f.payload === 111)!.config)).toContain('stereo=1');
+  });
+});
+
+describe('extractStereoAndNackAudioFromOffer', () => {
+  const offerWith = (rtpmap: string, fmtp: string) => ({
+    type: 'offer' as const,
+    sdp: `v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+m=audio 9 UDP/TLS/RTP/SAVPF 111
+a=mid:0
+${rtpmap}
+${fmtp}`,
+  });
+
+  it('detects sprop-stereo=1 as a whole parameter', () => {
+    const { stereoMids } = extractStereoAndNackAudioFromOffer(
+      offerWith('a=rtpmap:111 opus/48000/2', 'a=fmtp:111 minptime=10;sprop-stereo=1'),
+    );
+    expect(stereoMids).toEqual(['0']);
+  });
+
+  it('does not treat plain stereo=1 as sprop-stereo=1', () => {
+    const { stereoMids } = extractStereoAndNackAudioFromOffer(
+      offerWith('a=rtpmap:111 opus/48000/2', 'a=fmtp:111 minptime=10;stereo=1'),
+    );
+    expect(stereoMids).toEqual([]);
+  });
+
+  it('matches the opus codec case-insensitively (RFC 4855)', () => {
+    const { stereoMids } = extractStereoAndNackAudioFromOffer(
+      offerWith('a=rtpmap:111 OPUS/48000/2', 'a=fmtp:111 minptime=10;sprop-stereo=1'),
+    );
+    expect(stereoMids).toEqual(['0']);
+  });
+});
+
+// A single peer connection bundle as Chrome offers it: the section our camera sends on, the
+// recvonly sections subscribed tracks arrive on, and one that lost AV1 in negotiation.
+const SINGLE_PC_OFFER = `v=0
+o=- 0 0 IN IP4 127.0.0.1
+s=-
+t=0 0
+a=group:BUNDLE 0 1 2
+m=video 9 UDP/TLS/RTP/SAVPF 96 45
+c=IN IP4 0.0.0.0
+a=mid:0
+a=sendonly
+a=msid:s cam
+a=rtpmap:96 VP8/90000
+a=rtpmap:45 AV1/90000
+a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time
+a=extmap:11 urn:ietf:params:rtp-hdrext:sdes:repaired-rtp-stream-id
+m=video 9 UDP/TLS/RTP/SAVPF 96 45
+c=IN IP4 0.0.0.0
+a=mid:1
+a=recvonly
+a=rtpmap:96 VP8/90000
+a=rtpmap:45 AV1/90000
+a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time
+m=video 9 UDP/TLS/RTP/SAVPF 96
+c=IN IP4 0.0.0.0
+a=mid:2
+a=recvonly
+a=rtpmap:96 VP8/90000
+a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time`;
+
+const sectionOf = (media: MediaDescription[], mid: string) =>
+  media.find((section) => `${section.mid}` === mid)!;
+
+const ddOf = (media: MediaDescription[], mid: string) =>
+  sectionOf(media, mid).ext?.find((ext) => ext.uri === ddExtensionURI)?.value;
+
+describe('ensureVideoDDExtension', () => {
+  it('assigns an id above every extension in the bundle', () => {
+    const sdp = parse(SINGLE_PC_OFFER);
+    // 11 is the highest in use, across all sections rather than just this one
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '1'), sdp, 0)).toBe(12);
+    expect(ddOf(sdp.media, '1')).toBe(12);
+  });
+
+  it('reuses the id already chosen for the connection', () => {
+    const sdp = parse(SINGLE_PC_OFFER);
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '1'), sdp, 7)).toBe(7);
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '2'), sdp, 7)).toBe(7);
+    expect(ddOf(sdp.media, '1')).toBe(7);
+    expect(ddOf(sdp.media, '2')).toBe(7);
+  });
+
+  it('leaves a section that already carries the extension alone, and reports its id', () => {
+    const sdp = parse(`${SINGLE_PC_OFFER}
+a=extmap:3 ${ddExtensionURI}`);
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '2'), sdp, 0)).toBe(3);
+    expect(sectionOf(sdp.media, '2').ext).toHaveLength(2);
+    expect(ddOf(sdp.media, '2')).toBe(3);
+  });
+
+  it('adopts the id the browser already advertises rather than inventing a second one', () => {
+    // Chrome maps the extension itself on the section it sends AV1 on, but not on recvonly
+    // ones. A bundle has to map the URI to one id, so the send section's id has to win over
+    // both a fresh id and the cached one.
+    const sdp = parse(SINGLE_PC_OFFER);
+    sectionOf(sdp.media, '0').ext!.push({ value: 13, uri: ddExtensionURI });
+
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '1'), sdp, 0)).toBe(13);
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '2'), sdp, 7)).toBe(13);
+    expect(ddOf(sdp.media, '1')).toBe(13);
+    expect(ddOf(sdp.media, '2')).toBe(13);
+  });
+
+  it('steps over the id RFC 8285 reserves', () => {
+    const sdp = parse(SINGLE_PC_OFFER);
+    sectionOf(sdp.media, '0').ext!.push({ value: 14, uri: 'urn:3gpp:video-orientation' });
+
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '1'), sdp, 0)).toBe(16);
+  });
+
+  it('abandons the cached id once something else stands for it', () => {
+    // The id was free when it was picked, then the first section we send on brought the fuller
+    // extension set along and claimed it. Reusing it anyway is what makes the browser reject
+    // the offer with "a BUNDLE group contains a codec collision for header extension id".
+    const sdp = parse(SINGLE_PC_OFFER);
+    sectionOf(sdp.media, '0').ext!.push({ value: 12, uri: 'urn:3gpp:video-orientation' });
+
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '1'), sdp, 12)).toBe(13);
+    expect(ddOf(sdp.media, '1')).toBe(13);
+  });
+
+  it('leaves the offer alone when the mapped id is contested', () => {
+    // Nothing consistent for the whole bundle is available: the extension is mapped to 12 on one
+    // section and 12 means something else on another, and the browser's half of the map is not
+    // ours to renumber. Losing AV1 beats an offer that cannot be applied at all.
+    const sdp = parse(SINGLE_PC_OFFER);
+    sectionOf(sdp.media, '0').ext!.push({ value: 12, uri: 'urn:3gpp:video-orientation' });
+    sectionOf(sdp.media, '2').ext!.push({ value: 12, uri: ddExtensionURI });
+
+    expect(ensureVideoDDExtension(sectionOf(sdp.media, '1'), sdp, 0)).toBe(0);
+    expect(ddOf(sdp.media, '1')).toBeUndefined();
+  });
+
+  it('adds the extension to a section that has none', () => {
+    const sdp = parse(SINGLE_PC_OFFER);
+    const section = sectionOf(sdp.media, '1');
+    delete section.ext;
+    expect(ensureVideoDDExtension(section, sdp, 0)).toBe(12);
+    expect(ddOf(sdp.media, '1')).toBe(12);
+  });
+});