livekit-client 2.22.4 → 2.23.0

package/dist/ts4.2/room/data-channel/DataChannelManager.d.ts

@@ -23,8 +23,9 @@ export interface DataChannelManagerOptions {
  * live for the engine's lifetime and have RTCDataChannel handles attached/detached as peer
  * connections come and go) plus the subscriber-side receive handles adopted by label.
  *
- * Handle turnover goes through {@link FlowControlledDataChannel.attach}/`detach`, which reject
- * parked headroom waiters as a built-in — there is no separate invalidation step to forget.
+ * Handle turnover goes through {@link FlowControlledDataChannel.attach}/`detach`, which close the
+ * released handle and reject parked headroom waiters as a built-in — there is no separate
+ * invalidation step to forget.
  */
 export declare class DataChannelManager {
     readonly reliable: ReliableDataChannel;
@@ -42,8 +43,8 @@ export declare class DataChannelManager {
     get hasPublisherChannels(): boolean;
     /**
      * Creates the three publisher data channels on the given transport, wires their handlers, and
-     * attaches them to the wrappers — attaching rejects any waiters still parked on replaced
-     * channel objects.
+     * attaches them to the wrappers — attaching closes any replaced channel objects and rejects the
+     * waiters still parked on them.
      */
     createPublisherChannels(pcManager: PCTransportManager): void;
     /**
@@ -52,10 +53,10 @@ export declare class DataChannelManager {
      */
     adoptSubscriberChannel(channel: RTCDataChannel): boolean;
     /**
-     * Tears down all channels for a peer-connection cleanup: rejects parked waiters (detach — the
-     * spec allows `pc.close()` to transition channels to 'closed' without firing events, so waiting
-     * for browser close events is not an option), strips handlers, closes the handles, and resets
-     * the reliable session state.
+     * Tears down all channels for a peer-connection cleanup: strips handlers, closes the handles,
+     * and resets the reliable session state. Detaching the publisher handles closes them and
+     * rejects parked waiters (the spec allows `pc.close()` to transition channels to 'closed'
+     * without firing events, so waiting for browser close events is not an option).
      */
     teardown(): void;
 }

package/dist/ts4.2/room/data-channel/FlowControlledDataChannel.d.ts

@@ -25,7 +25,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 declare class FlowControlledDataChannel {
     readonly kind: DataChannelKind;
@@ -42,15 +43,23 @@ export declare class FlowControlledDataChannel {
     constructor(opts: FlowControlledDataChannelOptions);
     get channelHandle(): (RTCDataChannel | undefined);
     /**
-     * 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): void;
-    /** Detaches the handle on teardown, rejecting parked waiters. */
+    /** Detaches and closes the handle on teardown, rejecting parked waiters. */
     detach(reason?: string): void;
+    /**
+     * 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;
     protected getChannel(): RTCDataChannel | undefined;
     /**
      * Whether the send buffer has room to accept more data (the send gate). Senders proceed while
@@ -70,16 +79,20 @@ export declare class FlowControlledDataChannel {
      */
     lockHeadroom(): Promise<() => void>;
     /**
-     * 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.
      */
-    waitForHeadroomWithLock(): Promise<void>;
+    waitForHeadroomWithLock(dc: RTCDataChannel): Promise<void>;
     /** Core wait of {@link waitForHeadroomWithLock}. The caller must hold the headroom lock. */
-    waitForHeadroomWithoutLock(): Promise<void>;
+    waitForHeadroomWithoutLock(dc: RTCDataChannel): Promise<void>;
     /** Rejects all parked headroom waiters; the next waiter gets a fresh controller. */
     invalidateWaiters(reason: string): void;
     /**

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

@@ -275,6 +275,10 @@ export default class LocalParticipant extends Participant {
     private handleSubscribedQualityUpdate;
     private handleLocalTrackUnpublished;
     private handleTrackEnded;
+    /**
+     * @internal
+     */
+    private restartOnDefaultAudioDevice;
     private getPublicationForTrack;
     private waitForPendingPublicationOfSource;
     /** Publishes a data track.

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

@@ -106,7 +106,7 @@ export default class Participant extends Participant_base {
     /**
      * @internal
      */
-    setAudioContext(ctx: AudioContext | undefined): void;
+    setAudioContext(ctx: AudioContext | undefined): Promise<void>;
     protected addTrackPublication(publication: TrackPublication): void;
 }
 export type ParticipantEventCallbacks = {

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

@@ -9,6 +9,11 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     stopOnMute: boolean;
     private prevStats?;
     private isKrispNoiseFilterEnabled;
+    /**
+     * the processed track we currently have krisp feature listeners registered on. Tracked
+     * separately, as `processor.processedTrack` can be swapped out while we hold the listeners.
+     */
+    private observedProcessedTrack?;
     protected processor?: TrackProcessor<Track.Kind.Audio, AudioProcessorOptions> | undefined;
     get enhancedNoiseCancellation(): boolean;
     /**
@@ -27,12 +32,30 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     protected monitorSender: () => Promise<void>;
     private handleKrispNoiseFilterEnable;
     private handleKrispNoiseFilterDisable;
+    /**
+     * registers the krisp feature listeners on the given processed track, moving them over from
+     * a previously observed one. Passing `undefined` just removes the existing listeners.
+     */
+    private observeProcessedTrack;
+    /**
+     * Sets a processor on this track.
+     *
+     * The processor is destroyed when the track is stopped, and also when the audio context goes
+     * away, so a disconnect ends it on both counts and it has to be set again after reconnecting.
+     * See {@link TrackProcessor} for the full lifecycle.
+     */
     setProcessor(processor: TrackProcessor<Track.Kind.Audio, AudioProcessorOptions>): Promise<void>;
+    protected onMediaStreamTrackChanged(): Promise<void>;
+    protected internalStopProcessor(keepElement?: boolean): Promise<void>;
+    stop(): void;
     /**
      * @internal
      * @experimental
+     *
+     * A processor's nodes (`AudioWorkletNode`, ...) can't move between contexts, so the processor
+     * is rebuilt whenever the context changes and torn down when there is none left to run in.
      */
-    setAudioContext(audioContext: AudioContext | undefined): void;
+    setAudioContext(audioContext: AudioContext | undefined): Promise<void>;
     getSenderStats(): Promise<AudioSenderStats | undefined>;
     checkForSilence(): Promise<boolean>;
 }

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

@@ -41,6 +41,7 @@ export default abstract class LocalTrack<TrackKind extends Track.Kind = Track.Ki
     private _isUpstreamPaused;
     get isUpstreamPaused(): boolean;
     get isUserProvided(): boolean;
+    get isStopped(): boolean;
     get mediaStreamTrack(): MediaStreamTrack;
     get isLocal(): boolean;
     /**
@@ -49,6 +50,12 @@ export default abstract class LocalTrack<TrackKind extends Track.Kind = Track.Ki
      */
     getSourceTrackSettings(): MediaTrackSettings;
     private setMediaStreamTrack;
+    /**
+     * Hook invoked after the underlying MediaStreamTrack has been swapped and the processor has
+     * been restarted around it, so `processor.processedTrack` already holds the new track.
+     * Unlike `onSenderTrackSwapped` this also fires on the restart and unmute paths.
+     */
+    protected onMediaStreamTrackChanged(): Promise<void>;
     waitForDimensions(timeout?: number): Promise<Track.Dimensions>;
     setDeviceId(deviceId: ConstrainDOMString): Promise<boolean>;
     abstract restartTrack(constraints?: unknown): Promise<void>;
@@ -95,16 +102,27 @@ export default abstract class LocalTrack<TrackKind extends Track.Kind = Track.Ki
      * Sets a processor on this track.
      * See https://github.com/livekit/track-processors-js for example usage
      *
+     * The processor lives on the track, so stopping the track destroys it. Unpublishing and
+     * disconnecting both stop the track by default, which means a processor has to be set again on
+     * the track published after a reconnect. See {@link TrackProcessor} for the full lifecycle,
+     * including what `stopLocalTrackOnUnpublish: false` changes.
+     *
      * @param processor
      * @param showProcessedStreamLocally
      * @returns
      */
     setProcessor(processor: TrackProcessor<TrackKind>, showProcessedStreamLocally?: boolean): Promise<void>;
+    /**
+     * Returns the processor currently set on this track, or `undefined` if there is none. A track
+     * that was stopped by an unpublish or a disconnect has none. See {@link TrackProcessor}.
+     */
     getProcessor(): TrackProcessor<TrackKind, any> | undefined;
     /**
      * Stops the track processor
      * See https://github.com/livekit/track-processors-js for example usage
      *
+     * Only needed to remove a processor from a track that stays published. Unpublishing or
+     * disconnecting already destroys it. See {@link TrackProcessor}.
      */
     stopProcessor(keepElement?: boolean): Promise<void>;
     /**

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

@@ -61,6 +61,13 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
      */
     private refreshSenderEncodings;
     private applyEncodingsToSender;
+    /**
+     * Sets a processor on this track, and wires its processed track into the simulcast codecs.
+     *
+     * The processor is destroyed when the track is stopped, which unpublishing and disconnecting
+     * both do by default, so it has to be set again after reconnecting. See {@link TrackProcessor}
+     * for the full lifecycle.
+     */
     setProcessor(processor: TrackProcessor<Track.Kind.Video>, showProcessedStreamLocally?: boolean): Promise<void>;
     setDegradationPreference(preference: RTCDegradationPreference): Promise<void>;
     /**

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

@@ -10,6 +10,12 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
     private gainNode?;
     private sourceNode?;
     private webAudioPluginNodes;
+    /**
+     * the nodes of the graph currently wired up, in order, so teardown can undo exactly the edges
+     * `connectWebAudio` created. Reading `webAudioPluginNodes` instead would miss the old plugins
+     * once `setWebAudioPlugins` has replaced them.
+     */
+    private connectedNodes;
     private sinkId?;
     constructor(mediaTrack: MediaStreamTrack, sid: string, receiver: RTCRtpReceiver, audioContext?: AudioContext, audioOutput?: AudioOutputOptions, loggerOptions?: LoggerOptions);
     /**

package/dist/ts4.2/room/track/processor/types.d.ts

@@ -19,6 +19,17 @@ export interface AudioProcessorOptions extends ProcessorOptions<Track.Kind.Audio
  */
 export interface VideoProcessorOptions extends ProcessorOptions<Track.Kind.Video> {
 }
+/**
+ * A processor is bound to the track it was set on, not to the room, and it does not survive the
+ * track being stopped: unpublishing a track or disconnecting from a room destroys its processor.
+ * Both paths stop the track by default, so after reconnecting or republishing, call
+ * `setProcessor` again on the new track to put the processor back.
+ *
+ * The exception is `stopLocalTrackOnUnpublish: false`, which keeps the track alive across an
+ * unpublish or disconnect. A video processor then survives with it. An audio processor only
+ * survives if the audio context came from the application, because a context the SDK created is
+ * closed on disconnect and the processor goes with it.
+ */
 export interface TrackProcessor<T extends Track.Kind, U extends ProcessorOptions<T> = ProcessorOptions<T>> {
     name: string;
     init: (opts: U) => Promise<void>;

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

@@ -137,8 +137,19 @@ export interface ObservableMediaElement extends HTMLMediaElement {
 export declare function getClientInfo(capabilities?: ClientInfo_Capability[]): ClientInfo;
 export declare function getEmptyVideoStreamTrack(): MediaStreamTrack;
 export declare function createDummyVideoStreamTrack(width?: number, height?: number, enabled?: boolean, paintContent?: boolean): MediaStreamTrack;
+/**
+ * Returns a silent audio track, cloned off a shared `AudioContext` created on first use. Hand the
+ * clone back to `releaseEmptyAudioStreamTrack` rather than stopping it, so the context can close.
+ * A clone that is only stopped stays counted as outstanding, which holds the shared context open
+ * for the lifetime of the page.
+ */
 export declare function getEmptyAudioStreamTrack(): MediaStreamTrack;
-export declare function getStereoAudioStreamTrack(): MediaStreamTrack;
+/**
+ * Stops a track obtained from `getEmptyAudioStreamTrack` and closes the shared `AudioContext`
+ * backing it once every track it handed out has been released. Does nothing for a track this
+ * module never handed out, or one that has been released already.
+ */
+export declare function releaseEmptyAudioStreamTrack(track: MediaStreamTrack): Promise<void>;
 /** An object that represents a serialized version of a `new Promise((resolve, reject) => {})`
  * constructor. Wait for a promise resolution with `await future.promise` and explicitly resolve or
  * reject the inner promise with `future.resolve(...)` or `future.reject(...)`.
@@ -190,6 +201,22 @@ export declare function isAudioCodec(maybeCodec: string): maybeCodec is AudioCod
 export declare function isVideoCodec(maybeCodec: string): maybeCodec is VideoCodec;
 export declare function unwrapConstraint(constraint: ConstrainDOMString): string;
 export declare function unwrapConstraint(constraint: ConstrainULong): number;
+/**
+ * The getUserMedia rejections that no softer constraint can recover from, because the user or the
+ * document refused capture outright. Retrying one of these would put a second prompt in front of
+ * someone who already said no. The last two names are legacy spellings still reported by older
+ * engines. Matched by `name` rather than with `instanceof`, because these are not reliably distinct
+ * constructors across environments. happy-dom, which the tests run under, aliases them to `Event`.
+ */
+export declare function isPermissionDeniedError(e: unknown): boolean;
+/** Records that `e` is the rejection getUserMedia itself produced. */
+export declare function markDeviceAcquisitionFailure(e: unknown): void;
+/**
+ * Whether a track restart failed at getUserMedia rather than in the work that adopts the new track.
+ * Recorded on the side rather than by wrapping, because callers of `restartTrack` match on the
+ * rejection's own name.
+ */
+export declare function isDeviceAcquisitionFailure(e: unknown): boolean;
 export declare function toWebsocketUrl(url: string): string;
 export declare function toHttpUrl(url: string): string;
 export declare function extractTranscriptionSegments(transcription: TranscriptionModel, firstReceivedTimesMap: Map<string, number>): TranscriptionSegment[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.22.4",
+  "version": "2.23.0",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",

package/src/api/SignalClient.test.ts

@@ -11,8 +11,10 @@ import {
   WrappedJoinRequest_Compression,
 } from '@livekit/protocol';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Mutex } from '@livekit/mutex';
 import { ConnectionError, ConnectionErrorReason } from '../room/errors';
 import CriticalTimers from '../room/timers';
+import { Future } from '../room/utils';
 import { SignalClient, SignalConnectionState } from './SignalClient';
 import type { WebSocketCloseInfo, WebSocketConnection } from './WebSocketStream';
 import { WebSocketStream } from './WebSocketStream';
@@ -147,6 +149,167 @@ describe('SignalClient.connect', () => {
     return JoinRequest.fromBinary(bytes);
   }
 
+  describe('Cancelled connection attempts', () => {
+    it.each(['before join', 'while waiting for the connection lock'])(
+      'does not open a transport when aborted %s',
+      async (when) => {
+        const abortController = new AbortController();
+        const internals = signalClient as unknown as { connectionLock: Mutex };
+        const unlock = await internals.connectionLock.lock();
+        mockWebSocketStream({
+          connection: createMockConnection(
+            createMockReadableStream([createSignalResponse('join', createJoinResponse())]),
+          ),
+        });
+        if (when === 'before join') abortController.abort();
+        const joining = signalClient.join(
+          'wss://test.livekit.io',
+          'test-token',
+          defaultOptions,
+          abortController.signal,
+        );
+        abortController.abort();
+        unlock();
+
+        try {
+          await expect(joining).rejects.toMatchObject({ reason: ConnectionErrorReason.Cancelled });
+          expect(WebSocketStream).not.toHaveBeenCalled();
+        } finally {
+          await signalClient.close();
+          vi.mocked(WebSocketStream).mockReset();
+        }
+      },
+    );
+
+    it('does not replace a transport when aborted during its teardown', async () => {
+      const abortController = new AbortController();
+      const internals = signalClient as unknown as {
+        connectionLock: Mutex;
+        teardownTransport: (reason: string) => Promise<void>;
+      };
+      const teardownStarted = new Future<void, Error>();
+      const finishTeardown = new Future<void, Error>();
+      vi.spyOn(internals, 'teardownTransport').mockImplementationOnce(async () => {
+        teardownStarted.resolve?.();
+        await finishTeardown.promise;
+      });
+      signalClient.ws = {
+        close: () => {},
+        closed: Promise.resolve({ closeCode: 1000, reason: '' }),
+      } as WebSocketStream;
+      mockWebSocketStream({
+        connection: createMockConnection(
+          createMockReadableStream([createSignalResponse('join', createJoinResponse())]),
+        ),
+      });
+
+      const joining = signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        defaultOptions,
+        abortController.signal,
+      );
+      const cancelled = expect(joining).rejects.toMatchObject({
+        reason: ConnectionErrorReason.Cancelled,
+      });
+      await teardownStarted.promise;
+      abortController.abort();
+      finishTeardown.resolve?.();
+      await cancelled;
+      // The rejection can settle before the transport replacement resumes.
+      const unlock = await internals.connectionLock.lock();
+      unlock();
+
+      try {
+        expect(WebSocketStream).not.toHaveBeenCalled();
+      } finally {
+        await signalClient.close();
+        vi.mocked(WebSocketStream).mockReset();
+      }
+    });
+    it('does not validate the url when aborted while the websocket is opening', async () => {
+      const abortController = new AbortController();
+      const internals = signalClient as unknown as { connectionLock: Mutex };
+      const opened = new Future<WebSocketConnection, Error>();
+      opened.promise.catch(() => {});
+      mockWebSocketStream({ opened: opened.promise, readyState: 0 });
+      vi.mocked(global.fetch).mockClear();
+
+      const joining = signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        defaultOptions,
+        abortController.signal,
+      );
+      const cancelled = expect(joining).rejects.toMatchObject({
+        reason: ConnectionErrorReason.Cancelled,
+      });
+      await vi.waitFor(() => expect(WebSocketStream).toHaveBeenCalled());
+      abortController.abort();
+      opened.reject?.(new Error('closed by abort'));
+      await cancelled;
+      // let the attempt's continuation run to completion
+      const unlock = await internals.connectionLock.lock();
+      unlock();
+
+      try {
+        expect(global.fetch).not.toHaveBeenCalled();
+      } finally {
+        await signalClient.close();
+        vi.mocked(WebSocketStream).mockReset();
+      }
+    });
+
+    it('does not report a join that arrives after the attempt was aborted', async () => {
+      const abortController = new AbortController();
+      const internals = signalClient as unknown as { connectionLock: Mutex };
+      let enqueue: ((chunk: ArrayBuffer) => void) | undefined;
+      const readable = new ReadableStream<ArrayBuffer>({
+        start(controller) {
+          enqueue = (chunk) => controller.enqueue(chunk);
+        },
+      });
+      const writerReady = new Future<void, Error>();
+      const writable = new WritableStream();
+      const getWriter = writable.getWriter.bind(writable);
+      writable.getWriter = () => {
+        const writer = getWriter();
+        writerReady.resolve?.();
+        return writer;
+      };
+      mockWebSocketStream({
+        connection: { readable, writable, protocol: '', extensions: '' },
+      });
+      const onJoined = vi.fn();
+      signalClient.onJoined = onJoined;
+
+      const joining = signalClient.join(
+        'wss://test.livekit.io',
+        'test-token',
+        defaultOptions,
+        abortController.signal,
+      );
+      const cancelled = expect(joining).rejects.toMatchObject({
+        reason: ConnectionErrorReason.Cancelled,
+      });
+      await writerReady.promise;
+      abortController.abort();
+      enqueue?.(
+        createSignalResponse('join', createJoinResponse()).toBinary().buffer as ArrayBuffer,
+      );
+      await cancelled;
+      const unlock = await internals.connectionLock.lock();
+      unlock();
+
+      try {
+        expect(onJoined).not.toHaveBeenCalled();
+      } finally {
+        await signalClient.close();
+        vi.mocked(WebSocketStream).mockReset();
+      }
+    });
+  });
+
   describe('Happy Path - Initial Join', () => {
     it('should successfully connect and receive join response', async () => {
       const joinResponse = createJoinResponse();
@@ -162,6 +325,17 @@ describe('SignalClient.connect', () => {
       expect(signalClient.currentState).toBe(SignalConnectionState.CONNECTED);
     });
 
+    it('releases the connection lock when the url is malformed', async () => {
+      await expect(signalClient.join('not a url', 'test-token', defaultOptions)).rejects.toThrow();
+
+      const joinResponse = createJoinResponse();
+      const mockReadable = createMockReadableStream([createSignalResponse('join', joinResponse)]);
+      mockWebSocketStream({ connection: createMockConnection(mockReadable) });
+
+      const result = await signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions);
+      expect(result).toEqual(joinResponse);
+    });
+
     it('does not advertise packet trailer capability by default', async () => {
       const joinResponse = createJoinResponse();
       const signalResponse = createSignalResponse('join', joinResponse);
@@ -893,6 +1067,66 @@ describe('SignalClient.connect', () => {
     });
   });
 
+  describe('Failure Case - Validate Request Hangs', () => {
+    // A socket that never opens on its own (a lossy network) and whose `opened` rejects once the
+    // client closes it, like a real WebSocketStream aborted during the handshake.
+    function mockHangingWebSocket() {
+      vi.mocked(WebSocketStream).mockImplementationOnce(function () {
+        let rejectOpened!: (e: unknown) => void;
+        let resolveClosed!: (info: WebSocketCloseInfo) => void;
+        return {
+          url: 'wss://test.livekit.io',
+          opened: new Promise((_, reject) => (rejectOpened = reject)),
+          closed: new Promise((resolve) => (resolveClosed = resolve)),
+          close: vi.fn(() => {
+            rejectOpened(new Error('aborted during handshake'));
+            resolveClosed({ closeCode: 1006, reason: '' });
+          }),
+          readyState: 0,
+        } as any;
+      });
+    }
+
+    it('does not let a timed-out attempt block the next one', async () => {
+      // A validate request on a dead pooled connection only settles once its abort signal fires.
+      // Without a deadline it held the connection lock, so the next attempt never started. A
+      // timed-out attempt now skips validation entirely, since its caller has already been rejected.
+      vi.useFakeTimers();
+      try {
+        const hangingFetch = (_url: unknown, init?: RequestInit) =>
+          new Promise<Response>((_, reject) => {
+            init?.signal?.addEventListener('abort', () => reject(init.signal!.reason));
+          });
+        vi.mocked(fetch).mockImplementationOnce(hangingFetch).mockImplementationOnce(hangingFetch);
+        mockHangingWebSocket();
+        mockHangingWebSocket();
+
+        // building the join request finishes on real I/O, so wait for each socket before advancing
+        const first = expect(
+          signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions),
+        ).rejects.toMatchObject({ reason: ConnectionErrorReason.Timeout });
+        await vi.waitFor(() => expect(WebSocketStream).toHaveBeenCalledTimes(1));
+        await vi.advanceTimersByTimeAsync(defaultOptions.websocketTimeout);
+        await first;
+
+        const second = expect(
+          signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions),
+        ).rejects.toMatchObject({ reason: ConnectionErrorReason.Timeout });
+        // past the validate deadline, which is what releases the lock the first attempt holds
+        await vi.advanceTimersByTimeAsync(10_000);
+        await vi.waitFor(() => expect(WebSocketStream).toHaveBeenCalledTimes(2));
+        await vi.advanceTimersByTimeAsync(defaultOptions.websocketTimeout);
+        await second;
+
+        expect(fetch).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+        // drop the unused hanging fetches so they don't leak into later tests
+        vi.mocked(fetch).mockReset();
+      }
+    });
+  });
+
   describe('Establishing over an existing session', () => {
     async function joinSuccessfully() {
       mockWebSocketStream({