livekit-client 2.20.0 → 2.20.2

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

@@ -5,6 +5,7 @@ import type { SignalOptions } from '../api/SignalClient';
 import { SignalClient } from '../api/SignalClient';
 import type { BaseE2EEManager } from '../e2ee/E2eeManager';
 import type { InternalRoomOptions } from '../options';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import PCTransport from './PCTransport';
 import { PCTransportManager } from './PCTransportManager';
 import { DataTrackInfo } from './data-track/types';
@@ -86,7 +87,6 @@ export default class RTCEngine extends RTCEngine_base {
     private midToTrackId;
     /** used to indicate whether the browser is currently waiting to reconnect */
     private isWaitingForNetworkReconnect;
-    private bufferStatusLowClosingFuture;
     constructor(options: InternalRoomOptions);
     /** @internal */
     get logContext(): {
@@ -153,11 +153,53 @@ export default class RTCEngine extends RTCEngine_base {
     /** @internal */
     publishRpcAck(destinationIdentity: string, requestId: string): Promise<void>;
     sendDataPacket(packet: DataPacket, kind: DataChannelKind): Promise<void>;
-    sendLossyBytes(bytes: NonSharedUint8Array, kind: Exclude<DataChannelKind, DataChannelKind.RELIABLE>, bufferStatusLowBehavior?: 'drop' | 'wait'): Promise<void>;
+    sendLossyBytes(bytes: NonSharedUint8Array, kind: Exclude<DataChannelKind, DataChannelKind.RELIABLE>, bufferStatusFullBehavior?: 'drop' | 'wait'): Promise<void>;
     private resendReliableMessagesForResume;
     private updateAndEmitDCBufferStatus;
-    private isBufferStatusLow;
-    waitForBufferStatusLow(kind: DataChannelKind): Promise<void>;
+    /**
+     * Whether the send buffer has room to accept more data (the send gate). Senders proceed while
+     * this is true and block once it goes false.
+     */
+    private isBelowHighWaterMark;
+    /**
+     * Whether the send buffer has drained to its low-water mark. Drives the public
+     * {@link EngineEvent.DCBufferStatusChanged} event.
+     */
+    private isBelowLowWaterMark;
+    /** Per-kind lock serializing senders that have to wait for the buffer to drain. */
+    private waitForBufferHeadroomLocks;
+    /**
+     * Per-kind AbortController that cancels parked headroom waiters whenever a kind's channel object
+     * stops being current (replaced by createDataChannels or torn down by cleanupPeerConnections). A
+     * waiter is parked on the channel object it captured at wait entry; if that object is abandoned
+     * its events may never fire again, so the abort is what rejects the waiter and releases the
+     * headroom lock instead of stranding every future sender behind it.
+     */
+    private waiterAbortControllers;
+    private waiterAbortSignal;
+    /** Rejects all parked headroom waiters (all kinds); the next waiter gets a fresh controller. */
+    private invalidateDataChannelWaiters;
+    /** Acquires the per-kind headroom lock, resolving with the unlock function. */
+    private getBufferHeadroomLock;
+    /**
+     * Acquires the `kind` headroom lock, waits until the send buffer has room, then releases. The
+     * common single-send entry point. Callers that need to hold the lock across several sends (the
+     * resume replay) acquire it via {@link getBufferHeadroomLock} and call
+     * {@link waitForBufferHeadroomWithoutLock} per message instead.
+     */
+    waitForBufferHeadroomWithLock(kind: DataChannelKind): Promise<void>;
+    /**
+     * Waits until the send buffer for `kind` is at or below the high-water mark (draining, if
+     * needed, via the `bufferedamountlow` event). Does no locking of its own — the caller must
+     * already hold the kind's headroom lock (via {@link getBufferHeadroomLock}). The resume replay
+     * holds the lock across its whole batch and calls this per message so no other sender can
+     * interleave; the single-send path goes through {@link waitForBufferHeadroomWithLock}.
+     *
+     * Serializing through the per-kind lock means that, once the buffer drains, queued callers
+     * refill it one at a time (up to the high-water mark) rather than all at once and overflowing
+     * the SCTP send buffer (see livekit/client-sdk-js#1995).
+     */
+    private waitForBufferHeadroomWithoutLock;
     /**
      * @internal
      */

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

@@ -2,6 +2,7 @@ import { DataPacket_Kind, DisconnectReason, Encryption_Type, MetricsBatch, Parti
 import 'webrtc-adapter';
 import type TypedEmitter from 'typed-emitter';
 import type { InternalRoomOptions, RoomConnectOptions, RoomOptions } from '../options';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../utils/TypedPromise';
 import RTCEngine, { DataChannelKind } from './RTCEngine';
 import type { ByteStreamHandler, TextStreamHandler } from './data-stream/incoming/StreamReader';

package/dist/ts4.2/room/data-track/frame.d.ts

@@ -1,3 +1,4 @@
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackExtensions } from './packet/extensions';
 /** A pair of payload bytes and packet extensions which can be fed into a {@link DataTrackPacketizer}. */
 export type DataTrackFrame = {

package/dist/ts4.2/room/data-track/incoming/IncomingDataTrackManager.d.ts

@@ -91,6 +91,13 @@ export default class IncomingDataTrackManager extends IncomingDataTrackManager_b
      * @internal */
     queryPublications(): Promise<DataTrackInfo[]>;
     handleTrackPublished(publisherIdentity: Participant['identity'], info: DataTrackInfo): Promise<void>;
+    /**
+     * Detects and handles SID reassignment, which occurs when the publisher
+     * republishes its tracks after a full reconnect.
+     *
+     * Returns `true` if an SID reassignment occurred, `false` otherwise.
+     */
+    private handleSidReassigned;
     handleTrackUnpublished(sid: DataTrackSid): void;
     /** SFU notification that handles have been assigned for requested subscriptions. */
     receivedSfuSubscriberHandles(

package/dist/ts4.2/room/data-track/outgoing/types.d.ts

@@ -1,3 +1,4 @@
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import type LocalDataTrack from '../LocalDataTrack';
 import type { DataTrackHandle } from '../handle';
 import type { DataTrackInfo, DataTrackSid } from '../types';

package/dist/ts4.2/room/data-track/packet/extensions.d.ts

@@ -1,4 +1,5 @@
 import type { Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackDeserializeError, DataTrackDeserializeErrorReason } from './errors';
 import Serializable from './serializable';
 export declare enum DataTrackExtensionTag {

package/dist/ts4.2/room/data-track/packet/index.d.ts

@@ -1,4 +1,5 @@
 import type { Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackHandle } from '../handle';
 import { DataTrackTimestamp, U16_MAX_SIZE, WrapAroundUnsignedInt } from '../utils';
 import { DataTrackDeserializeError, DataTrackSerializeError, DataTrackSerializeErrorReason } from './errors';

package/dist/ts4.2/room/data-track/packet/serializable.d.ts

@@ -1,4 +1,5 @@
 import type { Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackSerializeError } from './errors';
 /** An abstract class implementing common behavior related to data track binary serialization. */
 export default abstract class Serializable {

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

@@ -1,5 +1,6 @@
 import { Codec, ParticipantInfo } from '@livekit/protocol';
 import type { InternalRoomOptions } from '../../options';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../../utils/TypedPromise';
 import type RTCEngine from '../RTCEngine';
 import type OutgoingDataStreamManager from '../data-stream/outgoing/OutgoingDataStreamManager';

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

@@ -2,6 +2,7 @@ import type { SipDTMF } from '@livekit/protocol';
 import { DataPacket_Kind, Encryption_Type, ParticipantInfo, ParticipantInfo_Kind as ParticipantKind, ParticipantPermission, ConnectionQuality as ProtoQuality, SubscriptionError } from '@livekit/protocol';
 import type TypedEmitter from 'typed-emitter';
 import type { StructuredLogger } from '../../logger';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import type LocalTrackPublication from '../track/LocalTrackPublication';
 import type LocalVideoTrack from '../track/LocalVideoTrack';
 import type RemoteTrack from '../track/RemoteTrack';

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

@@ -26,5 +26,12 @@ export declare class ScalabilityMode {
     constructor(scalabilityMode: string);
     toString(): string;
 }
+/**
+ * Returns the appropriate degradation preference for a video track based on its source.
+ *
+ * - Camera: 'maintain-framerate' (smoother video for real-time communication)
+ * - Screen share: 'maintain-resolution' (clarity is critical for reading text/UI)
+ * - Other/unknown: 'balanced'
+ */
 export declare function getDefaultDegradationPreference(track: LocalVideoTrack): RTCDegradationPreference;
 //# sourceMappingURL=publishUtils.d.ts.map

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

@@ -24,6 +24,7 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     mute(): Promise<typeof this>;
     unmute(): Promise<typeof this>;
     restartTrack(options?: AudioCaptureOptions): Promise<void>;
+    applyConstraints(constraints: Pick<AudioCaptureOptions, 'autoGainControl' | 'noiseSuppression' | 'echoCancellation' | 'voiceIsolation'>): Promise<void>;
     protected restart(constraints?: MediaTrackConstraints, isUnmuting?: boolean): Promise<typeof this>;
     startMonitor(): void;
     protected monitorSender: () => Promise<void>;

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

@@ -2,6 +2,7 @@ import { AudioTrackFeature, StreamState as ProtoStreamState, TrackSource, TrackT
 import type TypedEventEmitter from 'typed-emitter';
 import type { SignalClient } from '../../api/SignalClient';
 import type { StructuredLogger } from '../../logger';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import type { LoggerOptions } from '../types';
 import type { TrackProcessor } from './processor/types';
 export declare enum VideoQuality {

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

@@ -71,7 +71,17 @@ export interface TrackPublishDefaults {
      */
     scalabilityMode?: ScalabilityMode;
     /**
-     * degradation preference
+     * Controls how the encoder trades off between resolution and framerate
+     * when bandwidth is constrained.
+     *
+     * - 'maintain-framerate': Prioritizes framerate, reduces resolution if needed
+     * - 'maintain-resolution': Prioritizes resolution, drops frames if needed
+     * - 'balanced': Balances between both
+     *
+     * If not set, the SDK uses defaults based on track source:
+     * - Camera: 'maintain-framerate' (smoother video for real-time communication)
+     * - Screen share: 'maintain-resolution' (clarity is critical for text/UI)
+     * - Other/unknown: 'balanced'
      */
     degradationPreference?: RTCDegradationPreference;
     /**

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

@@ -1,5 +1,6 @@
 import { ChatMessage as ChatMessageModel, ClientInfo, ClientInfo_Capability, DisconnectReason, Transcription as TranscriptionModel } from '@livekit/protocol';
 import type { Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../utils/TypedPromise';
 import type { BrowserDetails } from '../utils/browserParser';
 import type { ConnectionError } from './errors';

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

@@ -0,0 +1,26 @@
+/**
+ * Mint a LiveKit access token for the mock test-server (HS256, dev secret).
+ *
+ * The mock's signal behavior mode is selected via a participant attribute
+ * under the reserved key `lk.mock` (dot notation, matching LiveKit's internal
+ * attribute convention), whose value is the JSON control object
+ * `{"signal":"<mode>"}` — mirroring the X-Lk-Mock header protocol. Attributes
+ * are a standard AccessToken field (a string map), so a dedicated `lk-mock`
+ * key coexists with any real metadata/attributes and needs no bespoke token
+ * construction. The room name is just a room; it no longer encodes behavior.
+ */
+export interface TokenOptions {
+    /** Mock behavior mode (e.g. 'no_pong'); omitted → the mock defaults to 'happy'. */
+    signal?: string;
+    /** LeaveRequest action the leave modes should send (0=DISCONNECT,1=RESUME,2=RECONNECT). */
+    leaveAction?: number;
+    room?: string;
+    identity?: string;
+    apiKey?: string;
+    secret?: string;
+    ttlSeconds?: number;
+}
+export declare function createToken(opts?: TokenOptions): Promise<string>;
+/** A syntactically-valid token signed with the WRONG secret — for 401 tests. */
+export declare function createInvalidToken(): Promise<string>;
+//# sourceMappingURL=signalToken.d.ts.map

package/dist/ts4.2/type-polyfills/non-shared-typed-arrays.d.ts

@@ -0,0 +1,2 @@
+export type NonSharedUint8Array = ReturnType<typeof Uint8Array.from>;
+//# sourceMappingURL=non-shared-typed-arrays.d.ts.map

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

@@ -1,13 +1,32 @@
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 export interface DataPacketItem {
     data: NonSharedUint8Array;
     sequence: number;
+    /**
+     * Whether the packet has been handed to the data channel. Unsent packets are queued for the
+     * resume replay (e.g. sends that landed in a reconnect window) and must never be trimmed by
+     * {@link DataPacketBuffer.alignBufferedAmount}, which reasons about the channel's buffered
+     * bytes — those only ever contain sent packets.
+     */
+    sent: boolean;
 }
 export declare class DataPacketBuffer {
     private buffer;
     private _totalSize;
+    private _sentSize;
     push(item: DataPacketItem): void;
     pop(): DataPacketItem | undefined;
     getAll(): DataPacketItem[];
+    /** Every queued packet not yet handed to the channel, in sequence order. */
+    getUnsent(): DataPacketItem[];
+    /** Marks a single queued packet as handed to the channel. */
+    markSent(item: DataPacketItem): void;
+    /**
+     * Marks every queued packet as not-yet-sent. Used at the start of a resume replay: whatever is
+     * still buffered was sent on the previous channel (or deferred) and must be re-handed to the
+     * current one, so none of it counts as sent until the replay actually transmits it.
+     */
+    markAllUnsent(): void;
     popToSequence(sequence: number): void;
     alignBufferedAmount(bufferedAmount: number): void;
     get length(): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.20.0",
+  "version": "2.20.2",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -57,7 +57,7 @@
     "sdp-transform": "^2.15.0",
     "tslib": "2.8.1",
     "typed-emitter": "^2.1.0",
-    "webrtc-adapter": "9.0.5"
+    "webrtc-adapter": "9.0.6"
   },
   "peerDependencies": {
     "@types/dom-mediacapture-record": "^1"
@@ -84,6 +84,8 @@
     "@types/ua-parser-js": "0.7.39",
     "@typescript-eslint/eslint-plugin": "8.59.4",
     "@typescript-eslint/parser": "8.59.4",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
     "downlevel-dts": "^0.11.0",
     "eslint": "10.4.0",
     "eslint-config-airbnb-extended": "^2.3.2",
@@ -95,6 +97,7 @@
     "glob": "^13.0.6",
     "happy-dom": "^20.0.0",
     "jsdom": "^26.1.0",
+    "playwright": "^1.61.1",
     "prettier": "^3.4.2",
     "publint": "^0.3.21",
     "rollup": "4.60.4",
@@ -107,7 +110,7 @@
     "typescript": "5.9.3",
     "typescript-eslint": "^8.47.0",
     "vite": "7.3.5",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "rollup --config --bundleConfigAsCjs && rollup --config rollup.config.worker.js --bundleConfigAsCjs && rollup --config rollup.config.fm-worker.js --bundleConfigAsCjs && pnpm downlevel-dts",
@@ -120,10 +123,11 @@
     "dev": "pnpm examples:demo",
     "lint": "eslint src",
     "test": "vitest run src",
+    "test:e2e": "vitest run --config vitest.e2e.config.mts",
     "deploy": "gh-pages -d examples/demo/dist",
     "format": "prettier --write src examples/**/*.ts",
     "format:check": "prettier --check src examples/**/*.ts",
-    "throws:check": "pnpm --package=@livekit/throws-transformer dlx throws-check 'src/!(*.test).ts' 'src/**/!(*.test).ts'",
+    "throws:check": "pnpm throws-check 'src/!(*.test).ts' 'src/**/!(*.test).ts'",
     "type:check": "tsc --noEmit",
     "ci:publish": "pnpm type:check && pnpm build && pnpm compat && changeset publish",
     "downlevel-dts": "downlevel-dts ./dist/src ./dist/ts4.2 --to=4.2",

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

@@ -0,0 +1,264 @@
+import { type LeaveRequest, LeaveRequest_Action } from '@livekit/protocol';
+import { afterEach, beforeEach, describe, expect, inject, it, vi } from 'vitest';
+import { ConnectionErrorReason } from '../room/errors';
+import { createInvalidToken, createToken } from '../test/signalToken';
+import { SignalClient, SignalConnectionState, type SignalOptions } from './SignalClient';
+
+// Provided by src/test/signalServerSetup.ts (spawns the livekit-server test-server).
+const serverUrl = inject('serverUrl');
+const unavailable = inject('e2eUnavailable');
+
+const defaultOpts = (): SignalOptions => ({
+  autoSubscribe: true,
+  maxRetries: 0,
+  e2eeEnabled: false,
+  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,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error(`timed out waiting for ${label}`)), ms),
+    ),
+  ]);
+}
+
+/** Resolves with the reason passed to onClose (register before the event can fire). */
+function captureClose(client: SignalClient): Promise<string> {
+  return new Promise((resolve) => {
+    client.onClose = (reason) => resolve(reason);
+  });
+}
+
+/** Resolves with the LeaveRequest passed to onLeave. */
+function captureLeave(client: SignalClient): Promise<LeaveRequest> {
+  return new Promise((resolve) => {
+    client.onLeave = (leave) => resolve(leave);
+  });
+}
+
+describe.skipIf(!!unavailable)('SignalClient e2e', () => {
+  // Behaviors that depend on the signal path (v0 legacy vs v1).
+  describe.each([
+    { label: 'v0', useV0: true },
+    { label: 'v1', useV0: false },
+  ])('$label path', ({ useV0 }) => {
+    let client: SignalClient;
+
+    beforeEach(() => {
+      client = new SignalClient(false);
+    });
+
+    afterEach(async () => {
+      await client.close().catch(() => {});
+    });
+
+    /** Mint a token whose metadata selects the server behavior mode, then join. */
+    const join = (mode: string, opts: SignalOptions = defaultOpts(), abortSignal?: AbortSignal) =>
+      createToken({ signal: mode }).then((token) =>
+        client.join(serverUrl, token, opts, abortSignal, useV0),
+      );
+
+    it('connects and reports CONNECTED with a join response', async () => {
+      const res = await join('happy');
+      expect(res).toBeTruthy();
+      expect(res.pingInterval).toBeGreaterThan(0);
+      expect(client.currentState).toBe(SignalConnectionState.CONNECTED);
+    });
+
+    it('stays connected past the ping timeout while the server pongs', async () => {
+      const onClose = vi.fn();
+      await join('happy');
+      client.onClose = onClose;
+      // Server ping timeout is 3s; a healthy pong loop must keep us alive.
+      await sleep(4_000);
+      expect(onClose).not.toHaveBeenCalled();
+      expect(client.currentState).toBe(SignalConnectionState.CONNECTED);
+    });
+
+    it('closes with a ping timeout when the server stops ponging', async () => {
+      const closed = captureClose(client);
+      await join('no_pong');
+      expect(client.currentState).toBe(SignalConnectionState.CONNECTED);
+      const reason = await withTimeout(closed, 8_000, 'onClose (ping timeout)');
+      expect(reason).toContain('ping timeout');
+      expect(client.currentState).toBe(SignalConnectionState.DISCONNECTED);
+    });
+
+    it('surfaces an unexpected transport close while connected', async () => {
+      const closed = captureClose(client);
+      await join('close_when_connected');
+      const reason = await withTimeout(closed, 5_000, 'onClose (transport closed)');
+      expect(reason).toBeTruthy();
+      expect(client.currentState).toBe(SignalConnectionState.DISCONNECTED);
+    });
+
+    it('surfaces an abnormal socket drop (1006) while connected', async () => {
+      // Server sends the join, then drops the TCP connection with no close
+      // handshake -> the browser reports an abnormal 1006 closure, exercising
+      // WebSocketStream's error->close path (distinct from the clean 1011 above).
+      const closed = captureClose(client);
+      await join('drop_when_connected');
+      expect(client.currentState).toBe(SignalConnectionState.CONNECTED);
+      const reason = await withTimeout(closed, 5_000, 'onClose (abnormal drop)');
+
+      expect(reason).toBe('Unexpected WS error');
+      expect(client.currentState).toBe(SignalConnectionState.DISCONNECTED);
+    });
+
+    it('rejects the join when the socket closes before the first message', async () => {
+      // Upgrade succeeds, then the server closes the WS before sending a join.
+      // The client is still establishing, so it rejects rather than hanging.
+      const err = await join('close_before_join').then(
+        () => undefined,
+        (e) => e as Error,
+      );
+      expect(err).toBeInstanceOf(Error);
+      expect((err as { reason?: ConnectionErrorReason }).reason).toBe(
+        ConnectionErrorReason.InternalError,
+      );
+    });
+
+    it('delivers a server-initiated leave while connected', async () => {
+      const left = captureLeave(client);
+      await join('leave_when_connected');
+      const leave = await withTimeout(left, 5_000, 'onLeave');
+      expect(leave).toBeTruthy();
+      expect(leave.action).toBe(LeaveRequest_Action.DISCONNECT);
+    });
+
+    it('forwards a non-DISCONNECT leave action verbatim', async () => {
+      // SignalClient does not branch on the leave action (RTCEngine does); it
+      // must pass it through unchanged. Guards the FSM swap's leave_received
+      // effect, which carries leaveAction. Uses RECONNECT to prove it's not
+      // defaulted to DISCONNECT.
+      const left = captureLeave(client);
+      const token = await createToken({
+        signal: 'leave_when_connected',
+        leaveAction: LeaveRequest_Action.RECONNECT,
+      });
+      await client.join(serverUrl, token, defaultOpts(), undefined, useV0);
+      const leave = await withTimeout(left, 5_000, 'onLeave');
+      expect(leave.action).toBe(LeaveRequest_Action.RECONNECT);
+    });
+
+    it('rejects the join when a leave arrives as the first message', async () => {
+      const err = await join('leave_first_message').then(
+        () => undefined,
+        (e) => e as Error,
+      );
+      expect(err).toBeInstanceOf(Error);
+    });
+
+    it('closes gracefully via close() without firing onClose', async () => {
+      const onClose = vi.fn();
+      await join('happy');
+      client.onClose = onClose;
+      await client.close();
+      expect(client.isDisconnected).toBe(true);
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it('reconnects (resume) back to CONNECTED', async () => {
+      await join('happy');
+      const token = await createToken({ signal: 'happy' });
+      await client.reconnect(serverUrl, token, 'RM_session');
+      expect(client.currentState).toBe(SignalConnectionState.CONNECTED);
+    });
+
+    it('rejects a reconnect when a leave arrives as the first message', async () => {
+      // Reconnecting into a room that sends leave-first exercises the client's
+      // first-message validation while in RECONNECTING (path-independent: it
+      // doesn't rely on the mock detecting reconnect, which v1 hides inside the
+      // gzipped join_request the mock ignores).
+      await join('happy');
+      const token = await createToken({ signal: 'leave_first_message' });
+      const err = await client.reconnect(serverUrl, token, 'RM_session').then(
+        () => undefined,
+        (e) => e as Error,
+      );
+      expect(err).toBeInstanceOf(Error);
+    });
+
+    // --- validate-endpoint classification -------------------------------
+    it('classifies an invalid token as NotAllowed', async () => {
+      const token = await createInvalidToken();
+      const err = await client
+        .join(serverUrl, token, defaultOpts(), undefined, useV0)
+        .catch((e) => e);
+      expect(err.reason).toBe(ConnectionErrorReason.NotAllowed);
+    });
+
+    it('classifies room-not-found as NotAllowed', async () => {
+      const err = await join('room_not_found').catch((e) => e);
+      expect(err.reason).toBe(ConnectionErrorReason.NotAllowed);
+    });
+
+    it('classifies a wrong-path 404 as ServiceNotFound', async () => {
+      const err = await join('validate_service_not_found').catch((e) => e);
+      expect(err.reason).toBe(ConnectionErrorReason.ServiceNotFound);
+    });
+
+    it('surfaces a 5xx validate as a WebSocket error (ws error shadows 5xx→internal)', async () => {
+      // Current behavior: handleConnectionError only maps a 5xx to InternalError
+      // when the ws rejection is NOT a ConnectionError. WebSocketStream always
+      // rejects with one, so for a refused upgrade the WS error wins. Only
+      // 401/403/404 (handled before that check) override it.
+      const err = await join('validate_500').catch((e) => e);
+      expect(err.reason).toBe(ConnectionErrorReason.WebSocket);
+    });
+  });
+
+  // Path-independent transport-level failures (run once, via v0).
+  describe('transport failures', () => {
+    let client: SignalClient;
+
+    beforeEach(() => {
+      client = new SignalClient(false);
+    });
+
+    afterEach(async () => {
+      await client.close().catch(() => {});
+    });
+
+    it('classifies an unreachable server as ServerUnreachable', async () => {
+      const token = await createToken({ signal: 'happy' });
+      // Nothing listening on this port -> ws fails, validate fetch fails.
+      const err = await client
+        .join('ws://127.0.0.1:59999', token, defaultOpts(), undefined, true)
+        .catch((e) => e);
+      expect(err.reason).toBe(ConnectionErrorReason.ServerUnreachable);
+    });
+
+    it('cancels the connect when the AbortSignal fires mid-connection', async () => {
+      const controller = new AbortController();
+      const token = await createToken({ signal: 'no_first_message' });
+      const p = client.join(serverUrl, token, defaultOpts(), controller.signal, true);
+      setTimeout(() => controller.abort('user requested abort'), 300);
+      const err = await p.catch((e) => e);
+      expect(err.reason).toBe(ConnectionErrorReason.Cancelled);
+    });
+
+    it('times out when the socket opens but no first message arrives', async () => {
+      // wsTimeout only guards the WebSocket upgrade and is cleared once ws.opened
+      // resolves. If the server accepts the socket then stays silent, the wait for
+      // the first message is guarded by its own JOIN_RESPONSE_TIMEOUT (5s), so
+      // join() rejects with Timeout instead of hanging.
+      const token = await createToken({ signal: 'no_first_message' });
+      const joinPromise = client.join(serverUrl, token, defaultOpts(), undefined, true);
+
+      const err = await withTimeout(
+        joinPromise.then(
+          () => undefined,
+          (e) => e,
+        ),
+        8_000,
+        'join to time out',
+      );
+      expect(err.reason).toBe(ConnectionErrorReason.Timeout);
+    });
+  });
+});

package/src/api/SignalClient.ts

@@ -61,6 +61,7 @@ import { ConnectionError } from '../room/errors';
 import CriticalTimers from '../room/timers';
 import type { LoggerOptions } from '../room/types';
 import { getClientInfo, isCompressionStreamSupported, isReactNative, sleep } from '../room/utils';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import { AsyncQueue } from '../utils/AsyncQueue';
 import { type WebSocketConnection, WebSocketStream } from './WebSocketStream';
 import {
@@ -120,6 +121,11 @@ export enum SignalConnectionState {
 /** specifies how much time (in ms) we allow for the ws to close its connection gracefully before continuing */
 const MAX_WS_CLOSE_TIME = 250;
 
+/**
+ * How long (in ms) to wait for the first message after the WebSocket upgrade.
+ */
+const JOIN_RESPONSE_TIMEOUT = 5_000;
+
 /** @internal */
 export class SignalClient {
   requestQueue: AsyncQueue;
@@ -407,7 +413,7 @@ export class SignalClient {
                   state: this.state,
                 });
                 if (this.state === SignalConnectionState.CONNECTED) {
-                  this.handleOnClose(closeInfo.reason ?? 'Unexpected WS error');
+                  this.handleOnClose(closeInfo.reason || 'Unexpected WS error');
                 }
               }
               return;
@@ -440,7 +446,34 @@ export class SignalClient {
           }
           const signalReader = connection.readable.getReader();
           this.streamWriter = connection.writable.getWriter();
-          const firstMessage = await signalReader.read();
+
+          // wsTimeout only guarded the upgrade; guard the first-message read with
+          // its own timeout so a silent server can't hang join() forever.
+          let firstMessage: ReadableStreamReadResult<string | ArrayBuffer>;
+          let firstMessageTimeout: ReturnType<typeof setTimeout> | undefined;
+          try {
+            firstMessage = await Promise.race([
+              signalReader.read(),
+              new Promise<never>((_, rejectRead) => {
+                firstMessageTimeout = setTimeout(() => {
+                  rejectRead(
+                    ConnectionError.timeout(
+                      'signal connection timed out while waiting for the first message',
+                    ),
+                  );
+                }, JOIN_RESPONSE_TIMEOUT);
+              }),
+            ]);
+          } catch (e) {
+            // No first message in time: release the reader and tear down the ws
+            // so we surface the timeout instead of leaking an open connection.
+            signalReader.releaseLock();
+            reject(e);
+            this.close();
+            return;
+          } finally {
+            clearTimeout(firstMessageTimeout);
+          }
           signalReader.releaseLock();
           if (!firstMessage.value) {
             throw ConnectionError.internal('no message received as first message');