livekit-client 2.20.2 → 2.22.0

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 type { DataPacketBuffer, DataPacketItem } from '../utils/dataPacketBuffer';
+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';
@@ -228,17 +234,16 @@ describe('RTCEngine', () => {
       engine: RTCEngine,
       maxDataPacketSize: number = MAX_DATA_PACKET_SIZE,
     ) {
-      const send = vi.fn();
+      const dc = new FakeDataChannel();
       Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
         ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
-        waitForBufferHeadroomWithLock: vi.fn().mockResolvedValue(undefined),
-        updateAndEmitDCBufferStatus: vi.fn(),
-        dataChannelForKind: vi.fn(() => ({ send })),
         pcManager: {
           getMaxPublisherMessageSize: vi.fn(() => maxDataPacketSize),
         },
       });
-      return send;
+      attachFakeChannel(engine, 'reliableChannel', dc);
+      return dc.send;
     }
 
     it('rejects packets larger than the max data packet size', async () => {
@@ -309,6 +314,23 @@ describe('RTCEngine', () => {
 
   const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
 
+  /** The reliable channel's private replay buffer — reached through casts, as tests do for engine privates. */
+  const reliableBuffer = (engine: RTCEngine) =>
+    (engine as unknown as { reliableChannel: { messageBuffer: DataPacketBuffer } }).reliableChannel
+      .messageBuffer;
+
+  type ChannelField = 'reliableChannel' | 'lossyChannel' | 'dataTrackChannel';
+  const engineChannel = (engine: RTCEngine, field: ChannelField) =>
+    (
+      engine as unknown as Record<
+        ChannelField,
+        { attach(dc: RTCDataChannel): void; invalidateWaiters(reason: string): void }
+      >
+    )[field];
+  /** Attach a fake handle to one of the engine's flow-control wrappers. */
+  const attachFakeChannel = (engine: RTCEngine, field: ChannelField, dc: FakeDataChannel) =>
+    engineChannel(engine, field).attach(dc as unknown as RTCDataChannel);
+
   describe('resendReliableMessagesForResume', () => {
     it('does not let a concurrent reliable send interleave into the resume replay', async () => {
       const engine = new RTCEngine(roomOptionDefaults);
@@ -316,18 +338,17 @@ describe('RTCEngine', () => {
       Object.assign(engine as unknown as Record<string, unknown>, {
         _isClosed: false,
         ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
-        dataChannelForKind: vi.fn(() => dc),
         pcManager: {
           getMaxPublisherMessageSize: vi.fn(() => 64 * 1024 - 1),
         },
       });
+      attachFakeChannel(engine, 'reliableChannel', dc);
 
-      // Two messages queued for replay, and a full buffer so the XX its first send.
+      // Two messages queued for replay, and a full buffer so the replay parks on
+      // waitForBufferHeadroom before its first send.
       const replayed1 = new Uint8Array([1]);
       const replayed2 = new Uint8Array([2]);
-      const buffer = (
-        engine as unknown as { reliableMessageBuffer: { push: (item: DataPacketItem) => void } }
-      ).reliableMessageBuffer;
+      const buffer = reliableBuffer(engine);
       buffer.push({ data: replayed1, sequence: 1, sent: true });
       buffer.push({ data: replayed2, sequence: 2, sent: true });
       dc.bufferedAmount = 2 * 1024 * 1024; // above the reliable high-water mark
@@ -359,59 +380,6 @@ describe('RTCEngine', () => {
       expect(dc.send.mock.calls[2][0]).not.toBe(replayed1);
       expect(dc.send.mock.calls[2][0]).not.toBe(replayed2);
     });
-
-    it('transmits a packet deferred mid-replay instead of marking it sent without sending', async () => {
-      const engine = new RTCEngine(roomOptionDefaults);
-      const dc = new FakeDataChannel();
-      Object.assign(engine as unknown as Record<string, unknown>, {
-        _isClosed: false,
-        // Reconnect still active: a send arriving during replay takes the deferral path.
-        attemptingReconnect: true,
-        ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
-        dataChannelForKind: vi.fn(() => dc),
-        pcManager: {
-          getMaxPublisherMessageSize: vi.fn(() => 64 * 1024 - 1),
-        },
-      });
-
-      const buffer = (engine as unknown as { reliableMessageBuffer: DataPacketBuffer })
-        .reliableMessageBuffer;
-      const replayed = new Uint8Array([1]);
-      buffer.push({ data: replayed, sequence: 1, sent: true });
-      // Full buffer so replay parks on waitForBufferHeadroomWithLock before its first send.
-      dc.bufferedAmount = 2 * 1024 * 1024;
-
-      const replay = (
-        engine as unknown as { resendReliableMessagesForResume: (seq: number) => Promise<void> }
-      ).resendReliableMessagesForResume(0);
-      await tick();
-
-      // A reliable send arrives while replay is parked; attemptingReconnect defers it into the
-      // buffer as sent:false, after the replay's first drain pass already started.
-      const deferred = new Uint8Array([2]);
-      const deferredSend = engine.sendDataPacket(
-        new DataPacket({
-          kind: DataPacket_Kind.RELIABLE,
-          value: { case: 'user', value: new UserPacket({ payload: deferred }) },
-        }),
-        DataChannelKind.RELIABLE,
-      );
-      await tick();
-
-      dc.bufferedAmount = 0;
-      dc.dispatchEvent(new Event('bufferedamountlow'));
-      await Promise.all([replay, deferredSend]);
-
-      // Pre-fix, replay sends only its snapshot ([replayed]) and blanket-marks the deferred packet
-      // sent without ever transmitting it — one send. The drain loop must transmit both (the
-      // deferred packet is serialized through sendDataPacket, so it's distinct from `replayed`),
-      // leaving nothing unsent for a later align to strand.
-      const sent = dc.send.mock.calls.map(([d]) => d);
-      expect(sent).toHaveLength(2);
-      expect(sent[0]).toBe(replayed);
-      expect(sent[1]).not.toBe(replayed);
-      expect(buffer.getUnsent()).toHaveLength(0);
-    });
   });
 
   describe('reliable sends during teardown windows', () => {
@@ -425,13 +393,12 @@ describe('RTCEngine', () => {
       Object.assign(engine as unknown as Record<string, unknown>, {
         _isClosed: false,
         ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
-        dataChannelForKind: vi.fn(() => dc),
         pcManager: {
           getMaxPublisherMessageSize: vi.fn(() => 64 * 1024 - 1),
         },
       });
-      return (engine as unknown as { reliableMessageBuffer: DataPacketBuffer })
-        .reliableMessageBuffer;
+      attachFakeChannel(engine, 'reliableChannel', dc);
+      return reliableBuffer(engine);
     }
 
     it('resolves and queues the packet for replay when the wait is torn down transiently', async () => {
@@ -443,9 +410,7 @@ describe('RTCEngine', () => {
       dc.bufferedAmount = 2 * 1024 * 1024;
       const send = engine.sendDataPacket(makePacket(1), DataChannelKind.RELIABLE);
       await tick();
-      (
-        engine as unknown as { invalidateDataChannelWaiters: (reason: string) => void }
-      ).invalidateDataChannelWaiters('data channels recreated');
+      engineChannel(engine, 'reliableChannel').invalidateWaiters('data channels recreated');
 
       // The send must not surface the teardown — the packet is queued for the resume replay.
       await expect(send).resolves.toBeUndefined();
@@ -471,9 +436,7 @@ describe('RTCEngine', () => {
       const send = engine.sendDataPacket(makePacket(1), DataChannelKind.RELIABLE);
       await tick();
       Object.assign(engine as unknown as Record<string, unknown>, { _isClosed: true });
-      (
-        engine as unknown as { invalidateDataChannelWaiters: (reason: string) => void }
-      ).invalidateDataChannelWaiters('engine closed');
+      engineChannel(engine, 'reliableChannel').invalidateWaiters('engine closed');
 
       await expect(send).rejects.toBeInstanceOf(UnexpectedConnectionState);
       expect(dc.send).not.toHaveBeenCalled();
@@ -496,78 +459,80 @@ describe('RTCEngine', () => {
     });
   });
 
-  describe('sendLossyBytes', () => {
+  describe('sendDataTrackFrame', () => {
     it('ensures the publisher is connected before sending (direct data-track path)', async () => {
       const engine = new RTCEngine(roomOptionDefaults);
       const dc = new FakeDataChannel();
       // The channel only becomes available once the publisher connection has been established —
       // mirroring the lazily negotiated publisher case that Room's packetAvailable path hits.
-      let connected = false;
       const ensurePublisherConnected = vi.fn(async () => {
-        connected = true;
+        attachFakeChannel(engine, 'dataTrackChannel', dc);
       });
       Object.assign(engine as unknown as Record<string, unknown>, {
         _isClosed: false,
         ensurePublisherConnected,
-        dataChannelForKind: vi.fn(() => (connected ? dc : undefined)),
       });
 
-      await engine.sendLossyBytes(new Uint8Array([1]), DataChannelKind.DATA_TRACK_LOSSY, 'wait');
+      await engine.sendDataTrackFrame(new Uint8Array([1]));
 
       expect(ensurePublisherConnected).toHaveBeenCalledWith(DataChannelKind.DATA_TRACK_LOSSY);
       expect(dc.send).toHaveBeenCalledTimes(1);
     });
 
-    it('only counts LOSSY bytes into the byterate stat that tunes the lossy drop threshold', async () => {
+    it('keeps each channel’s byterate stat isolated from the other’s traffic', async () => {
       const engine = new RTCEngine(roomOptionDefaults);
       const dc = new FakeDataChannel();
       Object.assign(engine as unknown as Record<string, unknown>, {
         _isClosed: false,
         ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
-        dataChannelForKind: vi.fn(() => dc),
       });
-      const stat = () =>
-        (engine as unknown as { lossyDataStatCurrentBytes: number }).lossyDataStatCurrentBytes;
-
-      // Data-track traffic must not move the stat — it would inflate the LOSSY channel's
-      // dynamically tuned drop threshold with traffic that channel never carries.
-      await engine.sendLossyBytes(new Uint8Array(1000), DataChannelKind.DATA_TRACK_LOSSY, 'wait');
-      expect(stat()).toBe(0);
-
-      await engine.sendLossyBytes(new Uint8Array(100), DataChannelKind.LOSSY, 'drop');
-      expect(stat()).toBe(100);
+      attachFakeChannel(engine, 'lossyChannel', dc);
+      attachFakeChannel(engine, 'dataTrackChannel', dc);
+      const lossyStat = () =>
+        (engine as unknown as { lossyChannel: { statCurrentBytes: number } }).lossyChannel
+          .statCurrentBytes;
+
+      // Data-track traffic (sendDataTrackFrame → data-track channel) must not move the LOSSY channel's
+      // stat — it would inflate the lossy channel's dynamically tuned drop threshold with traffic
+      // that channel never carries.
+      await engine.sendDataTrackFrame(new Uint8Array(1000));
+      expect(lossyStat()).toBe(0);
+
+      // A plain lossy publishData packet goes through sendDataPacket → lossy channel.
+      const lossyPacket = new DataPacket({
+        kind: DataPacket_Kind.LOSSY,
+        value: { case: 'user', value: new UserPacket({ payload: new Uint8Array(100) }) },
+      });
+      await engine.sendDataPacket(lossyPacket, DataChannelKind.LOSSY);
+      expect(lossyStat()).toBeGreaterThan(0);
     });
   });
 
-  describe('waitForBufferHeadroomWithLock', () => {
+  describe('waitForBufferHeadroom', () => {
     it('rejects parked waiters and releases the lock when the data channels are invalidated', async () => {
       const engine = new RTCEngine(roomOptionDefaults);
       const dc = new FakeDataChannel();
       Object.assign(engine as unknown as Record<string, unknown>, {
         _isClosed: false,
-        dataChannelForKind: vi.fn(() => dc),
       });
+      attachFakeChannel(engine, 'reliableChannel', dc);
 
       // Park a waiter: buffer above the reliable high-water mark, holding the headroom lock.
       dc.bufferedAmount = 2 * 1024 * 1024;
-      const parked = engine.waitForBufferHeadroomWithLock(DataChannelKind.RELIABLE);
+      const parked = engine.waitForBufferHeadroom(DataChannelKind.RELIABLE);
       // Swallow the expected rejection so it can't surface as unhandled before we assert on it.
       parked.catch(() => {});
       await tick();
 
       // The channel object gets abandoned (e.g. createDataChannels on the Safari resume path).
-      (
-        engine as unknown as { invalidateDataChannelWaiters: (reason: string) => void }
-      ).invalidateDataChannelWaiters('data channels recreated');
+      engineChannel(engine, 'reliableChannel').invalidateWaiters('data channels recreated');
 
       await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
 
       // The lock must be free again: a wait against the fresh, drained channel resolves instead
       // of queueing forever behind the stranded waiter.
       dc.bufferedAmount = 0;
-      await expect(
-        engine.waitForBufferHeadroomWithLock(DataChannelKind.RELIABLE),
-      ).resolves.toBeUndefined();
+      await expect(engine.waitForBufferHeadroom(DataChannelKind.RELIABLE)).resolves.toBeUndefined();
     });
   });
 
@@ -623,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();
+    });
+  });
 });