livekit-client 2.21.0 → 2.22.0

package/src/room/PCTransport.ts

@@ -36,6 +36,63 @@ const maxStartBitrateKbps = 1000;
 
 const debounceInterval = 20;
 
+/**
+ * Applies the configured start bitrate when this media section belongs to `cid`.
+ * This SDP munging is used for a bitrate setting that cannot be applied through
+ * `RTCRtpEncodingParameters`.
+ *
+ * Returns `undefined` when the section does not belong to the track, `0` when
+ * it does but does not offer the requested codec, and the codec payload when the
+ * requested codec is present (whether the bitrate was added or already set).
+ *
+ * @internal
+ */
+export function applyVideoStartBitrate(
+  media: MediaDescription,
+  cid: string,
+  codec: string,
+  maxbr: number,
+  isScreenShare = false,
+): number | undefined {
+  if (!media.msid?.includes(cid)) {
+    return undefined;
+  }
+
+  const codecPayload =
+    media.rtp.find((rtp) => rtp.codec.toUpperCase() === codec.toUpperCase())?.payload ?? 0;
+  if (codecPayload === 0) {
+    return 0;
+  }
+
+  // Use 90% of target bitrate, capped at 1 Mbps for camera to prevent BWE
+  // from starting too aggressively. Screen share is not capped since text/UI
+  // clarity requires high bitrate from the start.
+  // TODO: dynamically adjust start bitrate based on network conditions (e.g., previous BWE estimate)
+  const calculatedStartBitrate = Math.round(maxbr * startBitrateMultiplier);
+  const startBitrate = isScreenShare
+    ? calculatedStartBitrate
+    : Math.min(calculatedStartBitrate, maxStartBitrateKbps);
+
+  const fmtp = media.fmtp.find((entry) => entry.payload === codecPayload);
+  if (fmtp) {
+    // If another track's fmtp already has a start bitrate, it cannot be
+    // overridden here because the payload type is shared across the bundle.
+    // This forces every track sharing that payload to use the initial track's
+    // start bitrate.
+    if (!fmtp.config.includes('x-google-start-bitrate')) {
+      fmtp.config += `;x-google-start-bitrate=${startBitrate}`;
+    }
+  } else {
+    // VP8 and some codecs may not have an existing fmtp line.
+    media.fmtp.push({
+      payload: codecPayload,
+      config: `x-google-start-bitrate=${startBitrate}`,
+    });
+  }
+
+  return codecPayload;
+}
+
 export const PCEvents = {
   NegotiationStarted: 'negotiationStarted',
   NegotiationComplete: 'negotiationComplete',
@@ -368,9 +425,15 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
         // the only exception to this is when ICE restart is needed
         const currentSD = this._pc.remoteDescription;
         if (options?.iceRestart && currentSD) {
-          // TODO: handle when ICE restart is needed but we don't have a remote description
-          // the best thing to do is to recreate the peerconnection
+          // roll the remote description back in so createOffer produces a valid
+          // ICE-restart offer on top of the already-negotiated state
           await this._pc.setRemoteDescription(currentSD);
+        } else if (options?.iceRestart) {
+          // ICE restart with no remote description to restart on: `renegotiate` would stall
+          // (the pending offer is never answered), so throw for the caller to recreate the PC.
+          throw new NegotiationError(
+            'ICE restart requested without a remote description, peer connection must be recreated',
+          );
         } else {
           this.renegotiate = true;
           this.log.debug('requesting renegotiation');
@@ -396,56 +459,25 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
           ensureAudioNackAndStereo(media, ['all'], []);
         } else if (media.type === 'video') {
           this.trackBitrates.some((trackbr): boolean => {
-            if (!media.msid || !trackbr.cid || !media.msid.includes(trackbr.cid)) {
+            if (!trackbr.cid) {
               return false;
             }
 
-            let codecPayload = 0;
-            media.rtp.some((rtp): boolean => {
-              if (rtp.codec.toUpperCase() === trackbr.codec.toUpperCase()) {
-                codecPayload = rtp.payload;
-                return true;
-              }
+            const codecPayload = applyVideoStartBitrate(
+              media,
+              trackbr.cid,
+              trackbr.codec,
+              trackbr.maxbr,
+              trackbr.isScreenShare,
+            );
+            if (codecPayload === undefined) {
               return false;
-            });
-
-            if (codecPayload === 0) {
-              return true;
             }
 
-            if (isSVCCodec(trackbr.codec) && !isSafari()) {
-              this.ensureVideoDDExtensionForSVC(media, sdpParsed);
+            if (codecPayload > 0 && isSVCCodec(trackbr.codec) && !isSafari()) {
+              this.ddExtID = ensureVideoDDExtension(media, sdpParsed, this.ddExtID);
             }
 
-            // mung sdp for bitrate setting that can't apply by sendEncoding
-            // Use 90% of target bitrate, capped at 1 Mbps for camera to prevent BWE from starting too aggressively
-            // Screen share is not capped since text/UI clarity requires high bitrate from the start
-            // TODO: dynamically adjust start bitrate based on network conditions (e.g., use previous BWE estimate)
-            const calculatedStartBitrate = Math.round(trackbr.maxbr * startBitrateMultiplier);
-            const startBitrate = trackbr.isScreenShare
-              ? calculatedStartBitrate
-              : Math.min(calculatedStartBitrate, maxStartBitrateKbps);
-
-            let fmtpFound = false;
-            for (const fmtp of media.fmtp) {
-              if (fmtp.payload === codecPayload) {
-                fmtpFound = true;
-                // if another track's fmtp already is set, we cannot override the bitrate
-                // this has the unfortunate consequence of being forced to use the
-                // initial track's bitrate for all tracks
-                if (!fmtp.config.includes('x-google-start-bitrate')) {
-                  fmtp.config += `;x-google-start-bitrate=${startBitrate}`;
-                }
-                break;
-              }
-            }
-            // VP8 and some codecs may not have an existing fmtp line - create one
-            if (!fmtpFound) {
-              media.fmtp.push({
-                payload: codecPayload,
-                config: `x-google-start-bitrate=${startBitrate}`,
-              });
-            }
             return true;
           });
         }
@@ -681,44 +713,110 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       throw new NegotiationError(msg);
     }
   }
+}
 
-  private ensureVideoDDExtensionForSVC(
-    media: {
-      type: string;
-      port: number;
-      protocol: string;
-      payloads?: string | undefined;
-    } & MediaDescription,
-    sdp: SessionDescription,
-  ) {
-    const ddFound = media.ext?.some((ext): boolean => {
-      if (ext.uri === ddExtensionURI) {
-        return true;
-      }
-      return false;
+/**
+ * Adds the AV1 dependency descriptor extension to `media` unless it is already there, and
+ * returns the id it is mapped to so callers can pass it back in as `ddExtID` (0 when no id has
+ * been chosen yet).
+ *
+ * A bundle has to map one URI to one id, so an id already in use for the extension anywhere in
+ * `sdp` wins over both the cached one and a fresh one: Chrome advertises the extension itself on
+ * sections it can send on, and an earlier offer may have munged it into others.
+ * @internal
+ */
+export function ensureVideoDDExtension(
+  media: {
+    type: string;
+    port: number;
+    protocol: string;
+    payloads?: string | undefined;
+  } & MediaDescription,
+  sdp: SessionDescription,
+  ddExtID: number,
+): number {
+  const id = ddExtensionIDFor(sdp, ddExtID);
+  if (id === undefined) {
+    return ddExtID;
+  }
+
+  if (!media.ext?.some((ext) => ext.uri === ddExtensionURI)) {
+    media.ext ??= [];
+    media.ext.push({
+      value: id,
+      uri: ddExtensionURI,
     });
+  }
+  return id;
+}
 
-    if (!ddFound) {
-      if (this.ddExtID === 0) {
-        let maxID = 0;
-        sdp.media.forEach((m) => {
-          m.ext?.forEach((ext) => {
-            if (ext.value > maxID) {
-              maxID = ext.value;
-            }
-          });
-        });
-        this.ddExtID = maxID + 1;
-      }
-      media.ext?.push({
-        value: this.ddExtID,
-        uri: ddExtensionURI,
-      });
+/**
+ * The id to map the dependency descriptor to throughout `sdp`, or undefined when no id would be
+ * consistent for the whole bundle and the extension therefore has to be left out.
+ */
+function ddExtensionIDFor(sdp: SessionDescription, cachedID: number): number | undefined {
+  const mapped = mappedExtensionID(sdp, ddExtensionURI);
+  if (mapped !== undefined) {
+    // Adopting an id that also stands for another URI is what the browser rejects the bundle
+    // over, and its own half of the map is not ours to renumber, so give up on this offer.
+    return usedForOtherURI(sdp, mapped, ddExtensionURI) ? undefined : mapped;
+  }
+  // Reusing the id from the last offer keeps the mapping stable across renegotiations, but only
+  // while nothing else has taken it: the browser assigns ids to its own extensions without
+  // knowing about ours, so an id that was free when we picked it can since have been claimed —
+  // typically by the fuller extension set that arrives with the first section we send on.
+  if (cachedID !== 0 && !usedForOtherURI(sdp, cachedID, ddExtensionURI)) {
+    return cachedID;
+  }
+  return unusedExtensionID(sdp);
+}
+
+/** The id `uri` is mapped to in `sdp`, if any section maps it. */
+function mappedExtensionID(sdp: SessionDescription, uri: string): number | undefined {
+  for (const media of sdp.media) {
+    const ext = media.ext?.find((candidate) => candidate.uri === uri);
+    if (ext) {
+      return ext.value;
     }
   }
+  return undefined;
+}
+
+/** Whether `id` stands for anything in `sdp` other than `uri`. */
+function usedForOtherURI(sdp: SessionDescription, id: number, uri: string): boolean {
+  return sdp.media.some((media) => media.ext?.some((ext) => ext.value === id && ext.uri !== uri));
+}
+
+/**
+ * An id no extension in `sdp` uses. Stays above every id in use rather than filling gaps, so it
+ * is less likely to be an id the browser goes on to allocate to another extension, and steps
+ * over 15, which RFC 8285 reserves.
+ */
+function unusedExtensionID(sdp: SessionDescription): number {
+  let maxID = 0;
+  sdp.media.forEach((media) => {
+    media.ext?.forEach((ext) => {
+      if (ext.value > maxID) {
+        maxID = ext.value;
+      }
+    });
+  });
+  return maxID + 1 === 15 ? 16 : maxID + 1;
 }
 
-function ensureAudioNackAndStereo(
+/**
+ * Checks whether an fmtp config declares `param` as an exact, `;`-delimited
+ * token. A plain substring check conflates distinct opus parameters — e.g.
+ * `stereo=1` is a substring of `sprop-stereo=1` — so `param` must match a whole
+ * parameter, not appear anywhere within the config string.
+ * @internal
+ */
+export function fmtpConfigHasParam(config: string, param: string): boolean {
+  return config.split(';').some((entry) => entry.trim() === param);
+}
+
+/** @internal */
+export function ensureAudioNackAndStereo(
   media: {
     type: string;
     port: number;
@@ -734,7 +832,8 @@ function ensureAudioNackAndStereo(
   // found opus codec to add nack fb
   let opusPayload = 0;
   media.rtp.some((rtp): boolean => {
-    if (rtp.codec === 'opus') {
+    // rtpmap encoding names are case-insensitive (RFC 4855)
+    if (rtp.codec.toLowerCase() === 'opus') {
       opusPayload = rtp.payload;
       return true;
     }
@@ -760,7 +859,7 @@ function ensureAudioNackAndStereo(
     if (stereoMids.includes(mid) || (stereoMids.length === 1 && stereoMids[0] === 'all')) {
       media.fmtp.some((fmtp): boolean => {
         if (fmtp.payload === opusPayload) {
-          if (!fmtp.config.includes('stereo=1')) {
+          if (!fmtpConfigHasParam(fmtp.config, 'stereo=1')) {
             fmtp.config += ';stereo=1';
           }
           return true;
@@ -851,7 +950,8 @@ export function conformBundledCodecFmtp(
   }
 }
 
-function extractStereoAndNackAudioFromOffer(offer: RTCSessionDescriptionInit): {
+/** @internal */
+export function extractStereoAndNackAudioFromOffer(offer: RTCSessionDescriptionInit): {
   stereoMids: string[];
   nackMids: string[];
 } {
@@ -863,7 +963,8 @@ function extractStereoAndNackAudioFromOffer(offer: RTCSessionDescriptionInit): {
     const mid = getMidString(media.mid!);
     if (media.type === 'audio') {
       media.rtp.some((rtp): boolean => {
-        if (rtp.codec === 'opus') {
+        // rtpmap encoding names are case-insensitive (RFC 4855)
+        if (rtp.codec.toLowerCase() === 'opus') {
           opusPayload = rtp.payload;
           return true;
         }
@@ -876,7 +977,7 @@ function extractStereoAndNackAudioFromOffer(offer: RTCSessionDescriptionInit): {
 
       media.fmtp.some((fmtp): boolean => {
         if (fmtp.payload === opusPayload) {
-          if (fmtp.config.includes('sprop-stereo=1')) {
+          if (fmtpConfigHasParam(fmtp.config, 'sprop-stereo=1')) {
             stereoMids.push(mid);
           }
           return true;

package/src/room/RTCEngine.test.ts

@@ -1,6 +1,12 @@
-import { DataPacket, DataPacket_Kind, UserPacket } from '@livekit/protocol';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  DataPacket,
+  DataPacket_Kind,
+  ConnectionQuality as ProtoConnectionQuality,
+  UserPacket,
+} from '@livekit/protocol';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { DataPacketBuffer } from '../utils/dataPacketBuffer';
+import { PCTransportState } from './PCTransportManager';
 import RTCEngine, { DataChannelKind } from './RTCEngine';
 import { roomOptionDefaults } from './defaults';
 import { PublishDataError, UnexpectedConnectionState } from './errors';
@@ -582,4 +588,335 @@ describe('RTCEngine', () => {
       expect(error).not.toHaveBeenCalled();
     });
   });
+
+  describe('local connection quality Lost handling', () => {
+    // The engine reacts to the server's own verdict: a sustained local `LOST` while
+    // connected and publishing means our media isn't reaching the server, so it forces
+    // a full reconnect. (A genuine `LOST` can't be produced from a browser page — any
+    // live sender keeps RTCP flowing — so the behavior is unit tested here rather than
+    // in the e2e suite.) `connectionQualityLostTimeout` in RTCEngine.ts is 5s.
+    const LOST_TIMEOUT_MS = 10_000;
+    const LOCAL_SID = 'PA_local';
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    /** An engine primed to satisfy the reconnect guard: connected, publishing, not closed. */
+    function primeEngine(overrides: { activeSenders?: boolean; pcState?: number } = {}) {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const internals = engine as unknown as {
+        _isClosed: boolean;
+        participantSid: string;
+        // PCState is a private enum; Connected is 1, Reconnecting is 3.
+        pcState: number;
+        attemptingReconnect: boolean;
+        pcManager: unknown;
+        handleDisconnect: (connection: string, reason?: number) => void;
+        handleLocalConnectionQuality: (update: unknown) => void;
+      };
+      internals._isClosed = false;
+      internals.participantSid = LOCAL_SID;
+      internals.pcState = overrides.pcState ?? 1; // PCState.Connected
+      internals.attemptingReconnect = false;
+      internals.pcManager = {
+        publisher: {
+          getSenders: () =>
+            overrides.activeSenders === false ? [] : [{ track: { readyState: 'live' } }],
+        },
+      };
+      const handleDisconnect = vi.fn();
+      internals.handleDisconnect = handleDisconnect;
+      return { engine, internals, handleDisconnect };
+    }
+
+    function qualityUpdate(sid: string, quality: ProtoConnectionQuality) {
+      return { updates: [{ participantSid: sid, quality }] };
+    }
+
+    it('forces a full reconnect after a sustained local Lost while publishing', () => {
+      const { engine, internals, handleDisconnect } = primeEngine();
+
+      internals.handleLocalConnectionQuality(qualityUpdate(LOCAL_SID, ProtoConnectionQuality.LOST));
+
+      // still pending — the reconnect only fires once the timeout elapses
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS);
+
+      expect(engine.fullReconnectOnNext).toBe(true);
+      expect(handleDisconnect).toHaveBeenCalledTimes(1);
+    });
+
+    it('cancels the pending reconnect when quality recovers before the timeout', () => {
+      const { engine, internals, handleDisconnect } = primeEngine();
+
+      internals.handleLocalConnectionQuality(qualityUpdate(LOCAL_SID, ProtoConnectionQuality.LOST));
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS / 2);
+      internals.handleLocalConnectionQuality(
+        qualityUpdate(LOCAL_SID, ProtoConnectionQuality.EXCELLENT),
+      );
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS);
+
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+
+    it('does not reconnect on Lost when there are no active publisher senders', () => {
+      const { engine, internals, handleDisconnect } = primeEngine({ activeSenders: false });
+
+      internals.handleLocalConnectionQuality(qualityUpdate(LOCAL_SID, ProtoConnectionQuality.LOST));
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS);
+
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+
+    it('does not reconnect on Lost when the pc is not connected', () => {
+      const { engine, internals, handleDisconnect } = primeEngine({ pcState: 3 }); // Reconnecting
+
+      internals.handleLocalConnectionQuality(qualityUpdate(LOCAL_SID, ProtoConnectionQuality.LOST));
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS);
+
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+
+    it('ignores Lost quality reported for other participants', () => {
+      const { engine, internals, handleDisconnect } = primeEngine();
+
+      internals.handleLocalConnectionQuality(
+        qualityUpdate('PA_other', ProtoConnectionQuality.LOST),
+      );
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS);
+
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('reconnect requested mid-attempt', () => {
+    // A full reconnect requested while a resume is already in flight (e.g. a server
+    // RECONNECT leave racing the resume) sets `fullReconnectOnNext` mid-attempt. A
+    // successful resume must not swallow it: it survives and is dispatched afterwards.
+    interface ReconnectInternals {
+      _isClosed: boolean;
+      attemptingReconnect: boolean;
+      clientConfiguration: unknown;
+      pcManager: unknown;
+      resumeConnection: (reason?: number) => Promise<void>;
+      restartConnection: (regionUrl?: string) => Promise<void>;
+      clearPendingReconnect: () => void;
+      handleDisconnect: (connection: string, reason?: number) => void;
+      attemptReconnect: (reason?: number) => Promise<void>;
+    }
+
+    function primeEngine() {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const internals = engine as unknown as ReconnectInternals;
+      internals._isClosed = false;
+      internals.attemptingReconnect = false;
+      // avoid the "resume disabled / pcManager is NEW -> force full reconnect" escalation
+      internals.clientConfiguration = undefined;
+      internals.pcManager = { currentState: PCTransportState.CONNECTED };
+      internals.clearPendingReconnect = vi.fn();
+      const handleDisconnect = vi.fn();
+      internals.handleDisconnect = handleDisconnect;
+      const restartConnection = vi.fn(async () => {});
+      internals.restartConnection = restartConnection;
+      return { engine, internals, handleDisconnect, restartConnection };
+    }
+
+    it('dispatches a full reconnect when a resume succeeds but one was requested mid-attempt', async () => {
+      const { engine, internals, handleDisconnect, restartConnection } = primeEngine();
+      engine.fullReconnectOnNext = false;
+      // the resume succeeds, but a RECONNECT leave arrives while it is in flight
+      internals.resumeConnection = vi.fn(async () => {
+        engine.fullReconnectOnNext = true;
+      });
+
+      await internals.attemptReconnect();
+
+      expect(internals.resumeConnection).toHaveBeenCalledTimes(1);
+      expect(restartConnection).not.toHaveBeenCalled();
+      // the mid-attempt request survived the successful resume and was dispatched
+      expect(engine.fullReconnectOnNext).toBe(true);
+      expect(handleDisconnect).toHaveBeenCalledTimes(1);
+      expect(handleDisconnect).toHaveBeenCalledWith('reconnect');
+    });
+
+    it('does not dispatch a follow-up after an ordinary successful resume', async () => {
+      const { engine, internals, handleDisconnect, restartConnection } = primeEngine();
+      engine.fullReconnectOnNext = false;
+      internals.resumeConnection = vi.fn(async () => {});
+
+      await internals.attemptReconnect();
+
+      expect(internals.resumeConnection).toHaveBeenCalledTimes(1);
+      expect(restartConnection).not.toHaveBeenCalled();
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+
+    it('clears the flag and does not re-dispatch after a successful full reconnect', async () => {
+      const { engine, internals, handleDisconnect, restartConnection } = primeEngine();
+      engine.fullReconnectOnNext = true; // enters as a full reconnect
+      internals.resumeConnection = vi.fn(async () => {});
+
+      await internals.attemptReconnect();
+
+      expect(restartConnection).toHaveBeenCalledTimes(1);
+      expect(internals.resumeConnection).not.toHaveBeenCalled();
+      expect(engine.fullReconnectOnNext).toBe(false);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+
+    it('dispatches a follow-up when a full reconnect succeeds but one was requested mid-attempt', async () => {
+      const { engine, internals, handleDisconnect, restartConnection } = primeEngine();
+      engine.fullReconnectOnNext = true; // enters as a full reconnect
+      // a new RECONNECT request arrives while restartConnection is running
+      restartConnection.mockImplementationOnce(async () => {
+        engine.fullReconnectOnNext = true;
+      });
+
+      await internals.attemptReconnect();
+
+      expect(restartConnection).toHaveBeenCalledTimes(1);
+      // the mid-restart request survived the successful full reconnect and was dispatched
+      expect(engine.fullReconnectOnNext).toBe(true);
+      expect(handleDisconnect).toHaveBeenCalledTimes(1);
+      expect(handleDisconnect).toHaveBeenCalledWith('reconnect');
+    });
+
+    it('does not add a dispatch on top of the failure path retry', async () => {
+      const { engine, internals, handleDisconnect } = primeEngine();
+      engine.fullReconnectOnNext = false;
+      // resume fails after a mid-attempt request; the catch path schedules the retry
+      internals.resumeConnection = vi.fn(async () => {
+        engine.fullReconnectOnNext = true;
+        throw new Error('resume failed');
+      });
+
+      await internals.attemptReconnect();
+
+      // exactly one dispatch (from the catch), not a second one from the finally
+      expect(handleDisconnect).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('verifyTransport stuck-connecting bound', () => {
+    interface VerifyInternals {
+      pcManager: unknown;
+      client: unknown;
+      transportConnectingSince?: number;
+    }
+
+    function primeEngine(currentState: PCTransportState) {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const internals = engine as unknown as VerifyInternals;
+      internals.pcManager = { currentState };
+      internals.client = { ws: { readyState: WebSocket.OPEN } };
+      return { engine, internals };
+    }
+
+    it('reports the transport stuck when connecting longer than peerConnectionTimeout', () => {
+      const { engine, internals } = primeEngine(PCTransportState.CONNECTING);
+      internals.transportConnectingSince = Date.now() - (engine.peerConnectionTimeout + 1_000);
+
+      expect(engine.verifyTransport()).toBe(false);
+    });
+
+    it('tolerates a transport still within the connecting window', () => {
+      const { engine, internals } = primeEngine(PCTransportState.CONNECTING);
+      internals.transportConnectingSince = Date.now();
+
+      expect(engine.verifyTransport()).toBe(true);
+    });
+
+    it('fails open (and does not record a timestamp) when connecting is untracked', () => {
+      // verifyTransport is a pure read now: an unrecorded CONNECTING must not be treated as
+      // stuck, and the method must not seed a timestamp that could later leak across teardown.
+      const { engine, internals } = primeEngine(PCTransportState.CONNECTING);
+      internals.transportConnectingSince = undefined;
+
+      expect(engine.verifyTransport()).toBe(true);
+      expect(internals.transportConnectingSince).toBeUndefined();
+    });
+
+    it('does not measure a stale connecting timestamp while connected', () => {
+      const { engine, internals } = primeEngine(PCTransportState.CONNECTED);
+      // a leftover timestamp must not affect the CONNECTED verdict, and stays for the
+      // state-change handler to clear rather than being mutated here
+      internals.transportConnectingSince = Date.now() - 10 * engine.peerConnectionTimeout;
+
+      expect(engine.verifyTransport()).toBe(true);
+    });
+  });
+
+  describe('Lost-quality countdown across reconnects', () => {
+    // A Lost-quality countdown armed by the previous session must not survive a reconnect
+    // and fire against the new session before the server has re-evaluated it.
+    const LOST_TIMEOUT_MS = 5_000;
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('cancels a pending Lost countdown when a reconnect attempt begins', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const internals = engine as unknown as {
+        _isClosed: boolean;
+        participantSid: string;
+        pcState: number;
+        attemptingReconnect: boolean;
+        clientConfiguration: unknown;
+        pcManager: unknown;
+        lostQualityTimeout?: ReturnType<typeof setTimeout>;
+        resumeConnection: (reason?: number) => Promise<void>;
+        restartConnection: () => Promise<void>;
+        clearPendingReconnect: () => void;
+        handleDisconnect: (connection: string, reason?: number) => void;
+        handleLocalConnectionQuality: (update: unknown) => void;
+        attemptReconnect: (reason?: number) => Promise<void>;
+      };
+      internals._isClosed = false;
+      internals.participantSid = 'PA_local';
+      internals.pcState = 1; // PCState.Connected — the guards the countdown checks would pass
+      internals.attemptingReconnect = false;
+      internals.clientConfiguration = undefined;
+      internals.pcManager = {
+        currentState: PCTransportState.CONNECTED,
+        publisher: { getSenders: () => [{ track: { readyState: 'live' } }] },
+      };
+      internals.clearPendingReconnect = vi.fn();
+      const handleDisconnect = vi.fn();
+      internals.handleDisconnect = handleDisconnect;
+      internals.resumeConnection = vi.fn(async () => {});
+      internals.restartConnection = vi.fn(async () => {});
+
+      // a LOST verdict from the (soon-to-be-previous) session arms the countdown
+      internals.handleLocalConnectionQuality({
+        updates: [{ participantSid: 'PA_local', quality: ProtoConnectionQuality.LOST }],
+      });
+      expect(internals.lostQualityTimeout).toBeDefined();
+
+      // a reconnect begins and completes (resume) before the countdown elapses
+      engine.fullReconnectOnNext = false;
+      await internals.attemptReconnect();
+
+      // the stale countdown was cancelled and cannot fire against the reconnected session
+      expect(internals.lostQualityTimeout).toBeUndefined();
+      vi.advanceTimersByTime(LOST_TIMEOUT_MS);
+      expect(handleDisconnect).not.toHaveBeenCalled();
+    });
+  });
 });