livekit-client 2.21.0 → 2.22.1

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

@@ -1,4 +1,4 @@
-import type { MediaAttributes, MediaDescription } from 'sdp-transform';
+import type { MediaAttributes, MediaDescription, SessionDescription } from 'sdp-transform';
 import type TypedEmitter from 'typed-emitter';
 import type { LoggerOptions } from './types';
 /** @internal */
@@ -9,6 +9,18 @@ interface TrackBitrateInfo {
     maxbr: number;
     isScreenShare?: boolean;
 }
+/**
+ * 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 declare function applyVideoStartBitrate(media: MediaDescription, cid: string, codec: string, maxbr: number, isScreenShare?: boolean): number | undefined;
 export declare const PCEvents: {
     readonly NegotiationStarted: "negotiationStarted";
     readonly NegotiationComplete: "negotiationComplete";
@@ -79,13 +91,44 @@ export default class PCTransport extends PCTransport_base {
     getSenders(): RTCRtpSender[];
     getLocalDescription(): RTCSessionDescription | null | undefined;
     getRemoteDescription(): RTCSessionDescription | null;
-    getStats(): Promise<RTCStatsReport>;
+    /** stats of the underlying connection, `undefined` when there is none */
+    getStats(): Promise<RTCStatsReport> | undefined;
     getMaxMessageSize(): number | undefined;
     getConnectedAddress(): Promise<string | undefined>;
     close: () => void;
     private setMungedSDP;
-    private ensureVideoDDExtensionForSVC;
 }
+/**
+ * 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 declare function ensureVideoDDExtension(media: {
+    type: string;
+    port: number;
+    protocol: string;
+    payloads?: string | undefined;
+} & MediaDescription, sdp: SessionDescription, ddExtID: number): number;
+/**
+ * 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 declare function fmtpConfigHasParam(config: string, param: string): boolean;
+/** @internal */
+export declare function ensureAudioNackAndStereo(media: {
+    type: string;
+    port: number;
+    protocol: string;
+    payloads?: string | undefined;
+} & MediaDescription, stereoMids: string[], nackMids: string[]): void;
 /**
  * Returns the mids of transceivers that carry no outgoing track: the
  * pre-populated placeholders added by `RTCEngine.applyInitialPublisherLayout`,
@@ -117,6 +160,11 @@ export declare function placeholderMidsFromTransceivers(transceivers: readonly R
  * @internal
  */
 export declare function conformBundledCodecFmtp(media: MediaDescription[], isPlaceholder: (media: MediaDescription) => boolean): void;
+/** @internal */
+export declare function extractStereoAndNackAudioFromOffer(offer: RTCSessionDescriptionInit): {
+    stereoMids: string[];
+    nackMids: string[];
+};
 type PCTransportEventCallbacks = {
     negotiationStarted: () => void;
     negotiationComplete: () => void;

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

@@ -1,5 +1,5 @@
 import type { AddTrackRequest, ConnectionQualityUpdate, JoinResponse, RegionSettings, StreamStateUpdate, SubscriptionPermissionUpdate, SubscriptionResponse } from '@livekit/protocol';
-import { DataPacket, DataTrackSubscriberHandles, DisconnectReason, Encryption_Type, ParticipantInfo, PublishDataTrackResponse, RequestResponse, Room as RoomModel, RoomMovedResponse, ServerInfo, SpeakerInfo, SubscribedQualityUpdate, TrackInfo, TrackUnpublishedResponse, Transcription, UnpublishDataTrackResponse } from '@livekit/protocol';
+import { DataPacket, DataTrackSubscriberHandles, DisconnectReason, Encryption_Type, ParticipantInfo, PublishDataTrackResponse, ReconnectReason, RequestResponse, Room as RoomModel, RoomMovedResponse, ServerInfo, SpeakerInfo, SubscribedQualityUpdate, TrackInfo, TrackUnpublishedResponse, Transcription, UnpublishDataTrackResponse } from '@livekit/protocol';
 import type TypedEventEmitter from 'typed-emitter';
 import type { SignalOptions } from '../api/SignalClient';
 import { SignalClient } from '../api/SignalClient';
@@ -80,6 +80,10 @@ export default class RTCEngine extends RTCEngine_base {
     private midToTrackId;
     /** used to indicate whether the browser is currently waiting to reconnect */
     private isWaitingForNetworkReconnect;
+    /** set while the local participant's connection quality is `LOST`; forces a full reconnect on timeout */
+    private lostQualityTimeout?;
+    /** timestamp (ms) the primary transport entered `CONNECTING`, used to bound how long we tolerate it */
+    private transportConnectingSince?;
     constructor(options: InternalRoomOptions);
     /** @internal */
     get logContext(): {
@@ -94,10 +98,15 @@ export default class RTCEngine extends RTCEngine_base {
         joinResponse: JoinResponse;
         serverInfo: Partial<ServerInfo>;
     }>;
-    close(): Promise<void>;
+    /**
+     * @param reason why the session is ending, recorded by the signal lifecycle. Worth passing
+     * wherever the caller knows more than "someone called close" — the server's leave reason, or
+     * having given up on reconnecting.
+     */
+    close(reason?: string): Promise<void>;
     cleanupPeerConnections(): Promise<void>;
     cleanupLossyDataStats(): void;
-    cleanupClient(): Promise<void>;
+    cleanupClient(reason?: string): Promise<void>;
     addTrack(req: AddTrackRequest): Promise<TrackInfo>;
     /**
      * Removes sender from PeerConnection, returning true if it was removed successfully
@@ -137,6 +146,21 @@ export default class RTCEngine extends RTCEngine_base {
     private createSimulcastTransceiverSender;
     private createRTCRtpSender;
     private handleDisconnect;
+    /**
+     * A sustained local `LOST` while connected and publishing means the server isn't receiving
+     * our media, so force a full reconnect; any non-`LOST` value cancels a pending trigger.
+     */
+    private handleLocalConnectionQuality;
+    private scheduleLostQualityReconnect;
+    private clearLostQualityTimeout;
+    /** Whether the publisher currently has any sender with a live track. */
+    private hasActivePublisherSenders;
+    /**
+     * Forces a full reconnect while keeping the engine (and its saved credentials) alive. Used by
+     * Room's connection-reconcile safety net when the transport silently died but we looked connected.
+     * @internal
+     */
+    reconnect(reason?: ReconnectReason): void;
     private attemptReconnect;
     private getNextRetryDelay;
     private restartConnection;

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

@@ -72,12 +72,15 @@ declare class Room extends Room_base {
     private frameMetadataManager;
     private e2eeStateMutex;
     private connectionReconcileInterval?;
+    private statsLogInterval?;
     private regionUrlProvider?;
     private regionUrl?;
     private isVideoPlaybackBlocked;
     private log;
+    private statsLog;
     private bufferedEvents;
     private isResuming;
+    private pendingTrackAddedCallbacks;
     /**
      * map to store first point in time when a particular transcription segment was received
      */
@@ -226,6 +229,7 @@ declare class Room extends Room_base {
     private setupLocalParticipantEvents;
     private recreateEngine;
     private onTrackAdded;
+    private cancelPendingTrackAdded;
     private handleLocalTrackSubscribed;
     private emitLocalTrackSubscribed;
     private handleRestarting;
@@ -274,6 +278,11 @@ declare class Room extends Room_base {
     private getRemoteParticipantCapabilities;
     private getAllRemoteParticipantIdentities;
     private registerRpcDataStreamHandler;
+    private setStatsLogging;
+    /**
+     * Dumps stats of both peer connections.
+     */
+    private logWebRTCStats;
     private registerConnectionReconcile;
     private clearConnectionReconcile;
     private setAndEmitConnectionState;
@@ -311,7 +320,7 @@ export type RoomEventCallbacks = {
     moved: (name: string) => void;
     mediaDevicesChanged: () => void;
     participantConnected: (participant: RemoteParticipant) => void;
-    participantDisconnected: (participant: RemoteParticipant) => void;
+    participantDisconnected: (participant: RemoteParticipant, disconnectReason?: DisconnectReason) => void;
     trackPublished: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
     trackSubscribed: (track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
     trackSubscriptionFailed: (trackSid: string, participant: RemoteParticipant, reason?: SubscriptionError) => void;

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

@@ -70,7 +70,7 @@ export declare enum RoomEvent {
      * When a [[RemoteParticipant]] leaves *after* the local
      * participant has joined.
      *
-     * args: ([[RemoteParticipant]])
+     * args: ([[RemoteParticipant]], [[DisconnectReason]] | undefined)
      */
     ParticipantDisconnected = "participantDisconnected",
     /**

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

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

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

@@ -0,0 +1,13 @@
+/** one summarised stats entry; keys without a value are dropped */
+type Summary = Record<string, unknown>;
+/**
+ * Picks the interesting fields out of a `getStats()` report and groups them by
+ * RTP stream, so a stats dump can be read without unfolding the raw report.
+ */
+export declare function summarizeStatsReport(report: RTCStatsReport): {
+    connection: Summary | undefined;
+    outbound: Summary[] | undefined;
+    inbound: Summary[] | undefined;
+};
+export {};
+//# sourceMappingURL=statsSummary.d.ts.map

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

@@ -34,13 +34,18 @@ declare class TokenSourceEndpoint extends TokenSourceCached {
     private createRequestFromOptions;
     protected update(options: TokenSourceFetchOptions): Promise<TokenSourceResponse>;
 }
-export type SandboxTokenServerOptions = {
+export type DevelopmentTokenServerOptions = {
     baseUrl?: string;
 };
-declare class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-    constructor(sandboxId: string, options: SandboxTokenServerOptions);
+declare class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+    constructor(tokenServerId: string, options: DevelopmentTokenServerOptions);
 }
-export type { TokenSourceLiteral, TokenSourceCustom, TokenSourceEndpoint, TokenSourceSandboxTokenServer };
+/** @deprecated use {@link DevelopmentTokenServerOptions} instead */
+export type SandboxTokenServerOptions = DevelopmentTokenServerOptions;
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+declare class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {
+}
+export type { TokenSourceLiteral, TokenSourceCustom, TokenSourceEndpoint, TokenSourceSandboxTokenServer, TokenSourceDevelopmentTokenServer };
 export { decodeTokenPayload, areTokenSourceFetchOptionsEqual };
 export declare const TokenSource: {
     /** TokenSource.literal contains a single, literal set of {@link TokenSourceResponseObject}
@@ -56,18 +61,22 @@ export declare const TokenSource: {
     /**
      * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
      * the standard endpoint format:
-     * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+     * @see https://docs.livekit.io/frontends/build/authentication/endpoint/
      */
     endpoint(url: string, options?: EndpointOptions): TokenSourceEndpoint;
     /**
-     * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+     * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+     */
+    sandboxTokenServer(sandboxId: string, options?: SandboxTokenServerOptions): TokenSourceSandboxTokenServer;
+    /**
+     * TokenSource.developmentTokenServer queries a development token server for credentials,
      * which supports quick prototyping / getting started types of use cases.
      *
      * This token provider is INSECURE and should NOT be used in production.
      *
      * For more info:
-     * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+     * @see https://docs.livekit.io/frontends/build/authentication/sandbox-token-server/
      */
-    sandboxTokenServer(sandboxId: string, options?: SandboxTokenServerOptions): TokenSourceSandboxTokenServer;
+    developmentTokenServer(tokenServerId: string, options?: DevelopmentTokenServerOptions): TokenSourceDevelopmentTokenServer;
 };
 //# sourceMappingURL=TokenSource.d.ts.map

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

@@ -56,8 +56,19 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
     private applyEncodingsToSender;
     setProcessor(processor: TrackProcessor<Track.Kind.Video>, showProcessedStreamLocally?: boolean): Promise<void>;
     setDegradationPreference(preference: RTCDegradationPreference): Promise<void>;
+    /**
+     * Degradation preference is a property of the sender, not of the track, so every sender
+     * publishing this track needs it applied separately. A backup codec publishes over its
+     * own sender, which would otherwise let the browser resolve a preference implicitly and
+     * diverge from the primary encoder.
+     *
+     * Callers apply this sequentially rather than concurrently: `setParameters` is only valid
+     * against the parameters most recently returned by `getParameters`, which is why this file
+     * serializes other sender parameter updates through `senderLock`.
+     */
+    private applyDegradationPreference;
     addSimulcastTrack(codec: VideoCodec, encodings?: RTCRtpEncodingParameters[]): SimulcastTrackInfo | undefined;
-    setSimulcastTrackSender(codec: VideoCodec, sender: RTCRtpSender): void;
+    setSimulcastTrackSender(codec: VideoCodec, sender: RTCRtpSender): Promise<void>;
     /**
      * @internal
      * Sets codecs that should be publishing, returns new codecs that have not yet

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

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

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

@@ -42,6 +42,7 @@ export declare abstract class Track<TrackKind extends Track.Kind = Track.Kind> e
     protected timeSyncHandle: number | undefined;
     protected _currentBitrate: number;
     protected monitorInterval?: ReturnType<typeof setInterval>;
+    private finalStatsLogged;
     protected log: StructuredLogger;
     protected constructor(mediaTrack: MediaStreamTrack, kind: TrackKind, loggerOptions?: LoggerOptions);
     protected get logContext(): {
@@ -78,7 +79,16 @@ export declare abstract class Track<TrackKind extends Track.Kind = Track.Kind> e
     protected enable(): void;
     protected disable(): void;
     abstract startMonitor(signalClient?: SignalClient): void;
+    /**
+     * Raw stats of the sender or receiver this track is attached to.
+     */
+    abstract getRTCStatsReport(): Promise<RTCStatsReport | undefined>;
     stopMonitor(): void;
+    /**
+     * Dumps the raw stats of the track as it ends, once: a track that stops
+     * between two of the room's stats dumps is gone by the time the next one runs.
+     */
+    private logFinalStats;
     /** @internal */
     updateLoggerOptions(loggerOptions: LoggerOptions): void;
     private recycleElement;

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

@@ -32,6 +32,20 @@ export declare function supportsAV1(): boolean;
 export declare function supportsVP9(): boolean;
 export declare function supportsH265(): boolean;
 export declare function isSVCCodec(codec?: string): boolean;
+/**
+ * Opts `transceiver` into negotiating the AV1 dependency descriptor, reporting whether it will be.
+ *
+ * Chrome only offers the extension on transceivers that can send, so one we create to receive on
+ * never negotiates it — and Chrome 152 stopped decoding AV1 that arrives without it: frames get
+ * assembled, none ever decode, and the receiver asks for a keyframe forever. Asking through the
+ * transceiver rather than munging the extension into the SDP leaves the browser owning the
+ * extension id, which is what keeps that id consistent across the bundle and across
+ * renegotiations.
+ *
+ * A no-op where the browser offers no such control, or does not know the extension at all.
+ * @internal
+ */
+export declare function negotiateDependencyDescriptor(transceiver: RTCRtpTransceiver): boolean;
 export declare function supportsSetSinkId(elm?: HTMLMediaElement): boolean;
 /**
  * Checks whether or not setting an audio output via {@link Room#setActiveDevice}
@@ -162,4 +176,5 @@ export declare function decodeBase64(base64: string): Uint8Array;
 export declare function extractMaxAgeFromRequestHeaders(headers: Headers): number | undefined;
 export declare function isCompressionStreamSupported(): boolean;
 export declare function isPublisherOfferWithJoinSupported(): boolean;
+export declare function extractTrackSid(mediaTrack: MediaStreamTrack, stream: MediaStream): Track.SID | undefined;
 //# sourceMappingURL=utils.d.ts.map

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

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

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * Opt-in registry that lets a development tool observe the state machines driving the connection
+ * layer.
+ *
+ * The machines are private to the objects that own them and, more importantly, do not outlive them:
+ * a full reconnect replaces the whole engine along with its `SignalClient`, so anything watching a
+ * single machine reference goes blind exactly when the interesting part starts. Machines therefore
+ * announce themselves here as they are constructed, and a subscriber sees the whole succession.
+ *
+ * Nothing is recorded until {@link enableMachineInspector} is called, which no shipping code does —
+ * with the registry off, announcing is a comparison and a return.
+ */
+/**
+ * The slice of machina's `Fsm` surface an inspector needs. Structural rather than machina's own
+ * type so that any machine satisfies it regardless of its state and input unions.
+ */
+export interface InspectableMachine {
+    readonly id: string;
+    readonly initialState: string;
+    readonly states: Record<string, Record<string, unknown>>;
+    readonly context?: unknown;
+    currentState(): string;
+    canHandle(input: string): boolean;
+    on(eventName: string, callback: (data: any) => void): {
+        off(): void;
+    };
+}
+export interface MachineAnnouncement {
+    /** What the machine drives, e.g. `signal`. Not unique: each new `SignalClient` announces one. */
+    label: string;
+    /** How many machines have been announced before this one, so successive instances are tellable apart. */
+    seq: number;
+    /**
+     * When the machine was constructed. Carried on the announcement because subscribers receive the
+     * recorded ones on subscribe, and stamping those at replay time would date them all to whenever
+     * the tool happened to open.
+     */
+    at: number;
+    machine: InspectableMachine;
+}
+/**
+ * Starts recording machine announcements. Call before the machines of interest are constructed —
+ * for the signal machine that means before the `Room` is created.
+ */
+export declare function enableMachineInspector(): void;
+export declare function isMachineInspectorEnabled(): boolean;
+/** Announces a machine to whatever is watching. A no-op unless the inspector was enabled. */
+export declare function announceMachine(label: string, machine: InspectableMachine): void;
+/**
+ * Subscribes to machine announcements, replaying the ones already recorded so that a panel opened
+ * after connecting still sees the machine currently in charge. Returns an unsubscribe function.
+ */
+export declare function onMachineAnnounced(callback: (announcement: MachineAnnouncement) => void): () => void;
+//# sourceMappingURL=machineInspector.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.21.0",
+  "version": "2.22.1",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -54,6 +54,7 @@
     "events": "^3.3.0",
     "jose": "^6.1.0",
     "loglevel": "^1.9.2",
+    "machina": "^7.0.0",
     "sdp-transform": "^2.15.0",
     "tslib": "2.8.1",
     "typed-emitter": "^2.1.0",
@@ -66,12 +67,12 @@
     "@babel/core": "7.29.7",
     "@babel/preset-env": "7.29.7",
     "@bufbuild/protoc-gen-es": "^1.10.0",
-    "@changesets/cli": "2.31.0",
+    "@changesets/cli": "2.31.1",
     "@eslint/js": "10.0.1",
-    "@livekit/changesets-changelog-github": "^0.0.4",
+    "@livekit/changesets-changelog-github": "^0.2.0",
     "@livekit/throws-transformer": "^0.1.3",
-    "@rollup/plugin-babel": "7.0.0",
-    "@rollup/plugin-commonjs": "29.0.2",
+    "@rollup/plugin-babel": "7.1.0",
+    "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-json": "6.1.0",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
@@ -82,34 +83,39 @@
     "@types/events": "^3.0.3",
     "@types/sdp-transform": "2.15.0",
     "@types/ua-parser-js": "0.7.39",
-    "@typescript-eslint/eslint-plugin": "8.59.4",
-    "@typescript-eslint/parser": "8.59.4",
+    "@typescript-eslint/eslint-plugin": "8.64.0",
+    "@typescript-eslint/parser": "8.64.0",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "downlevel-dts": "^0.11.0",
-    "eslint": "10.4.0",
+    "eslint": "10.7.0",
     "eslint-config-airbnb-extended": "^2.3.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-compat": "^6.0.2",
     "eslint-plugin-import-x": "^4.16.1",
+    "eslint-plugin-machina": "^0.1.4",
     "eslint-plugin-prettier": "^5.5.4",
     "gh-pages": "6.3.0",
     "glob": "^13.0.6",
     "happy-dom": "^20.0.0",
     "jsdom": "^26.1.0",
+    "livekit-server-sdk": "^2.17.0",
+    "machina-inspect": "^4.0.0",
+    "machina-test": "^3.0.0",
+    "mermaid": "^11.16.1",
     "playwright": "^1.61.1",
     "prettier": "^3.4.2",
     "publint": "^0.3.21",
-    "rollup": "4.60.4",
+    "rollup": "4.62.2",
     "rollup-plugin-delete": "^2.1.0",
     "rollup-plugin-typescript2": "0.37.0",
-    "size-limit": "^11.2.0",
+    "size-limit": "^12.0.0",
     "tsx": "^4.21.0",
-    "typedoc": "0.28.19",
+    "typedoc": "0.28.20",
     "typedoc-plugin-no-inherit": "1.6.1",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.47.0",
-    "vite": "7.3.5",
+    "vite": "8.1.5",
     "vitest": "^4.1.10"
   },
   "scripts": {
@@ -120,6 +126,7 @@
     "build-docs": "typedoc && mkdir -p docs/assets/github && cp .github/*.png docs/assets/github/ && find docs -name '*.html' -type f -exec sed -i.bak 's|=\"/.github/|=\"assets/github/|g' {} + && find docs -name '*.bak' -delete",
     "proto": "protoc --es_out src/proto --es_opt target=ts -I./protocol ./protocol/livekit_rtc.proto ./protocol/livekit_models.proto",
     "examples:demo": "vite examples/demo -c vite.config.mjs",
+    "examples:machine": "vite examples/state-machine -c vite.config.mjs",
     "dev": "pnpm examples:demo",
     "lint": "eslint src",
     "test": "vitest run src",

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

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