livekit-client 2.22.0 → 2.22.2

package/src/room/PCTransportManager.test.ts

@@ -279,3 +279,38 @@ describe('PCTransportManager.negotiate', () => {
     await expect(p).resolves.toBeUndefined();
   });
 });
+
+describe('PCTransportManager.triggerIceRestart', () => {
+  let originalRTCPeerConnection: unknown;
+
+  beforeEach(() => {
+    originalRTCPeerConnection = (globalThis as unknown as { RTCPeerConnection?: unknown })
+      .RTCPeerConnection;
+    (globalThis as unknown as { RTCPeerConnection: unknown }).RTCPeerConnection = StubPC;
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { RTCPeerConnection: unknown }).RTCPeerConnection =
+      originalRTCPeerConnection;
+  });
+
+  /**
+   * The subscriber must keep applying remote candidates across a reconnect.
+   *
+   * Putting it into `restartingIce` would queue them until a new remote description arrives —
+   * but the server only re-offers the subscriber when the reconnect moved us to another node,
+   * so on an ordinary signal-only resume nothing would ever flush that queue, and the
+   * transport would stop adopting new network paths for the rest of the session. The server
+   * also never sends candidates ahead of the offer that introduces them, so queueing buys
+   * nothing in exchange.
+   */
+  it('does not stop the subscriber applying remote candidates', async () => {
+    const manager = new PCTransportManager('subscriber-primary', {});
+    const publisher = new FakePublisher();
+    (manager as unknown as { publisher: FakePublisher }).publisher = publisher;
+
+    await manager.triggerIceRestart();
+
+    expect(manager.subscriber?.restartingIce).toBe(false);
+  });
+});

package/src/room/PCTransportManager.ts

@@ -162,12 +162,20 @@ export class PCTransportManager {
     this.updateState();
   }
 
+  /**
+   * Restarts ICE on the transports that need it. Only the publisher: the server restarts the
+   * subscriber's ICE itself and follows with a fresh offer.
+   *
+   * The subscriber deliberately does NOT enter `restartingIce` here. Queueing its remote
+   * candidates would guard against candidates for a new generation arriving before the offer
+   * that introduces it, but the server does not send them in that order -- on a same-node
+   * resume it buffers them until the offer has gone out, and on a reconnect that lands on
+   * another node it withholds subscriber candidates until immediately before creating the
+   * offer. Setting the flag only risks withholding candidates during the window that decides
+   * whether the reconnect succeeded.
+   */
   async triggerIceRestart() {
     this.iceLog.warn('triggering ICE restart');
-    if (this.subscriber) {
-      this.subscriber.restartingIce = true;
-    }
-    // only restart publisher if it's needed
     if (this.needsPublisher) {
       await this.createAndSendPublisherOffer({ iceRestart: true });
     }

package/src/room/RTCEngine.ts

@@ -432,7 +432,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     }
   }
 
-  async close() {
+  /**
+   * @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.
+   */
+  async close(reason?: string) {
     const unlock = await this.closingLock.lock();
     if (this.isClosed) {
       unlock();
@@ -448,7 +453,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.clearLostQualityTimeout();
       this.cleanupLossyDataStats();
       await this.cleanupPeerConnections();
-      await this.cleanupClient();
+      await this.cleanupClient(reason);
     } finally {
       unlock();
     }
@@ -469,8 +474,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.lossyChannel.stopThresholdTuning();
   }
 
-  async cleanupClient() {
-    await this.client.close();
+  async cleanupClient(reason?: string) {
+    await this.client.close(true, reason);
     this.client.resetCallbacks();
     // Any in-flight addTrack requests are orphaned by the signal reconnect — the new session
     // won't deliver `trackPublishedResponse` for them, so reject the pending resolvers and
@@ -751,7 +756,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       switch (leave.action) {
         case LeaveRequest_Action.DISCONNECT:
           this.emit(EngineEvent.Disconnected, leave?.reason);
-          this.close();
+          this.close(`server leave: ${DisconnectReason[leave.reason] ?? leave.reason}`);
           break;
         case LeaveRequest_Action.RECONNECT:
           this.fullReconnectOnNext = true;
@@ -1161,7 +1166,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         `could not recover connection after ${this.reconnectAttempts} attempts, ${duration}ms. giving up`,
       );
       this.emit(EngineEvent.Disconnected);
-      this.close();
+      this.close(`gave up reconnecting after ${this.reconnectAttempts} attempts, ${duration}ms`);
     };
 
     const duration = Date.now() - this.reconnectStart;
@@ -1323,7 +1328,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
           }ms. giving up`,
         );
         this.emit(EngineEvent.Disconnected);
-        await this.close();
+        await this.close(
+          `gave up reconnecting after ${this.reconnectAttempts} attempts, ${
+            Date.now() - this.reconnectStart
+          }ms`,
+        );
       }
     } finally {
       this.attemptingReconnect = false;

package/src/room/Room.ts

@@ -91,6 +91,7 @@ import {
   type RpcInvocationData,
   RpcServerManager,
 } from './rpc';
+import { summarizeStatsReport } from './statsSummary';
 import CriticalTimers from './timers';
 import LocalAudioTrack from './track/LocalAudioTrack';
 import type LocalTrack from './track/LocalTrack';
@@ -143,6 +144,7 @@ export enum ConnectionState {
 }
 
 const CONNECTION_RECONCILE_FREQUENCY_MS = 4 * 1000;
+const STATS_LOG_FREQUENCY_MS = 30 * 1000;
 
 /**
  * In LiveKit, a room is the logical grouping for a list of participants.
@@ -207,6 +209,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private connectionReconcileInterval?: ReturnType<typeof setInterval>;
 
+  private statsLogInterval?: ReturnType<typeof setInterval>;
+
   private regionUrlProvider?: RegionUrlProvider;
 
   private regionUrl?: string;
@@ -215,6 +219,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private log = log;
 
+  private statsLog = log;
+
   private bufferedEvents: Array<any> = [];
 
   private isResuming: boolean = false;
@@ -254,6 +260,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.options = { ...roomOptionDefaults, ...options };
 
     this.log = getLogger(this.options.loggerName ?? LoggerNames.Room, () => this.logContext);
+    // its own logger name, so the stats dumps can be silenced or routed
+    // separately from the rest of the room's logs
+    this.statsLog = getLogger(LoggerNames.Stats, () => this.logContext);
     this.transcriptionReceivedTimes = new Map();
 
     this.options.audioCaptureDefaults = {
@@ -271,7 +280,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
     this.maybeCreateEngine();
 
-    this.incomingDataStreamManager = new IncomingDataStreamManager();
+    this.incomingDataStreamManager = new IncomingDataStreamManager(
+      this.options.dataStream?.maxPayloadByteLength,
+    );
     this.outgoingDataStreamManager = new OutgoingDataStreamManager(
       this.engine,
       this.log,
@@ -1913,7 +1924,13 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
       // when it's disconnected, send updates
       if (info.state === ParticipantInfo_State.DISCONNECTED) {
-        this.handleParticipantDisconnected(info.identity, remoteParticipant);
+        this.handleParticipantDisconnected(
+          info.identity,
+          remoteParticipant,
+          info.disconnectReason === DisconnectReason.UNKNOWN_REASON
+            ? undefined
+            : info.disconnectReason,
+        );
       } else {
         // create participant if doesn't exist
         this.getOrCreateParticipant(info.identity, info);
@@ -1931,7 +1948,11 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.incomingDataTrackManager.receiveSfuPublicationUpdates(mapped);
   };
 
-  private handleParticipantDisconnected(identity: string, participant?: RemoteParticipant) {
+  private handleParticipantDisconnected(
+    identity: string,
+    participant?: RemoteParticipant,
+    disconnectReason?: DisconnectReason,
+  ) {
     // remove and send event
     this.remoteParticipants.delete(identity);
     if (!participant) {
@@ -1944,7 +1965,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     participant.trackPublications.forEach((publication) => {
       participant.unpublishTrack(publication.trackSid, true);
     });
-    this.emit(RoomEvent.ParticipantDisconnected, participant);
+    this.emit(RoomEvent.ParticipantDisconnected, participant, disconnectReason);
     participant.setDisconnected();
     this.rpcClientManager.handleParticipantDisconnected(participant.identity);
   }
@@ -2582,6 +2603,46 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     );
   }
 
+  private setStatsLogging(enabled: boolean) {
+    if (enabled) {
+      if (!this.statsLogInterval) {
+        this.statsLogInterval = CriticalTimers.setInterval(() => {
+          // logWebRTCStats handles its own errors, nothing to await here
+          this.logWebRTCStats();
+        }, STATS_LOG_FREQUENCY_MS);
+      }
+    } else if (this.statsLogInterval) {
+      CriticalTimers.clearInterval(this.statsLogInterval);
+      this.statsLogInterval = undefined;
+    }
+  }
+
+  /**
+   * Dumps stats of both peer connections.
+   */
+  private logWebRTCStats = async () => {
+    const pcManager = this.engine?.pcManager;
+    if (!pcManager) {
+      return;
+    }
+    try {
+      const [publisher, subscriber] = await Promise.all([
+        pcManager.publisher.getStats(),
+        pcManager.subscriber?.getStats(),
+      ]);
+      const publisherStats = publisher && summarizeStatsReport(publisher);
+      const subscriberStats = subscriber && summarizeStatsReport(subscriber);
+      this.statsLog.info(`webrtc stats`, {
+        publisher: publisherStats?.connection,
+        subscriber: subscriberStats?.connection,
+        inbound: [...(publisherStats?.inbound ?? []), ...(subscriberStats?.inbound ?? [])],
+        outbound: publisherStats?.outbound,
+      });
+    } catch (error) {
+      this.statsLog.debug('could not collect webrtc stats', { error });
+    }
+  };
+
   private registerConnectionReconcile() {
     this.clearConnectionReconcile();
     let consecutiveFailures = 0;
@@ -2640,6 +2701,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.log.info(`connection state changed: ${this.state} -> ${state}`);
     this.state = state;
     this.incomingDataStreamManager.setConnected(state === ConnectionState.Connected);
+    this.setStatsLogging(state === ConnectionState.Connected);
 
     this.emit(RoomEvent.ConnectionStateChanged, this.state);
 
@@ -2948,7 +3010,10 @@ 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,

package/src/room/data-stream/incoming/IncomingDataStreamManager.test.ts

@@ -1237,6 +1237,177 @@ describe('IncomingDataStreamManager', () => {
       await expect(reader.readAll()).rejects.toThrow('Missing chunk(s)');
     });
 
+    it('should error on a gap in chunk indices on an uncompressed text stream', async () => {
+      const manager = new IncomingDataStreamManager();
+      manager.setConnected(true);
+
+      const readerPromise = new Promise<TextStreamReader>((resolve) => {
+        manager.registerTextStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+
+      const streamId = crypto.randomUUID();
+      const text = randomText(3_000);
+      const textBytes = new TextEncoder().encode(text);
+      const split = Math.floor(textBytes.length / 3);
+
+      manager.handleDataStreamPacket(
+        headerPacket(streamId, 'textHeader', {
+          totalLength: BigInt(textBytes.length),
+          compression: DataStream_CompressionType.NONE,
+        }),
+        Encryption_Type.NONE,
+      );
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 0, textBytes.slice(0, split)),
+        Encryption_Type.NONE,
+      );
+      // Skip chunk index 1 entirely — a gap means the payload cannot be reassembled in order.
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 2, textBytes.slice(split)),
+        Encryption_Type.NONE,
+      );
+
+      const reader = await readerPromise;
+      await expect(reader.readAll()).rejects.toThrow('Missing chunk(s)');
+    });
+
+    it('should error on a gap in chunk indices on an uncompressed byte stream', async () => {
+      const manager = new IncomingDataStreamManager();
+      manager.setConnected(true);
+
+      const readerPromise = new Promise<ByteStreamReader>((resolve) => {
+        manager.registerByteStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+
+      const streamId = crypto.randomUUID();
+      const bytes = randomBytes(3_000);
+      const split = Math.floor(bytes.length / 3);
+
+      manager.handleDataStreamPacket(
+        headerPacket(streamId, 'byteHeader', {
+          totalLength: BigInt(bytes.length),
+          compression: DataStream_CompressionType.NONE,
+        }),
+        Encryption_Type.NONE,
+      );
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 0, bytes.slice(0, split)),
+        Encryption_Type.NONE,
+      );
+      // Skip chunk index 1 entirely.
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 2, bytes.slice(split)),
+        Encryption_Type.NONE,
+      );
+
+      const reader = await readerPromise;
+      await expect(reader.readAll()).rejects.toThrow('Missing chunk(s)');
+    });
+
+    it('should drop a duplicate chunk index on an uncompressed text stream and still decode', async () => {
+      const manager = new IncomingDataStreamManager();
+      manager.setConnected(true);
+
+      const readerPromise = new Promise<TextStreamReader>((resolve) => {
+        manager.registerTextStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+
+      const streamId = crypto.randomUUID();
+      const text = randomText(3_000);
+      const textBytes = new TextEncoder().encode(text);
+      const split = Math.floor(textBytes.length / 2);
+
+      manager.handleDataStreamPacket(
+        headerPacket(streamId, 'textHeader', {
+          totalLength: BigInt(textBytes.length),
+          compression: DataStream_CompressionType.NONE,
+        }),
+        Encryption_Type.NONE,
+      );
+      const chunk0 = chunkPacket(streamId, 0, textBytes.slice(0, split));
+      manager.handleDataStreamPacket(chunk0, Encryption_Type.NONE);
+      // A replayed chunk (e.g. reconnect logic) must be dropped with a warning, not appended a
+      // second time — otherwise the payload is corrupted and exceeds `totalLength`.
+      manager.handleDataStreamPacket(chunk0, Encryption_Type.NONE);
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 1, textBytes.slice(split)),
+        Encryption_Type.NONE,
+      );
+      manager.handleDataStreamPacket(trailerPacket(streamId), Encryption_Type.NONE);
+
+      const reader = await readerPromise;
+      expect(await reader.readAll()).toStrictEqual(text);
+    });
+
+    it('should drop a duplicate chunk index on an uncompressed byte stream and still decode', async () => {
+      const manager = new IncomingDataStreamManager();
+      manager.setConnected(true);
+
+      const readerPromise = new Promise<ByteStreamReader>((resolve) => {
+        manager.registerByteStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+
+      const streamId = crypto.randomUUID();
+      const bytes = randomBytes(3_000);
+      const split = Math.floor(bytes.length / 2);
+
+      manager.handleDataStreamPacket(
+        headerPacket(streamId, 'byteHeader', {
+          totalLength: BigInt(bytes.length),
+          compression: DataStream_CompressionType.NONE,
+        }),
+        Encryption_Type.NONE,
+      );
+      const chunk0 = chunkPacket(streamId, 0, bytes.slice(0, split));
+      manager.handleDataStreamPacket(chunk0, Encryption_Type.NONE);
+      manager.handleDataStreamPacket(chunk0, Encryption_Type.NONE);
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 1, bytes.slice(split)),
+        Encryption_Type.NONE,
+      );
+      manager.handleDataStreamPacket(trailerPacket(streamId), Encryption_Type.NONE);
+
+      const reader = await readerPromise;
+      expect(concatChunks(await reader.readAll())).toStrictEqual(bytes);
+    });
+
+    it('should drop chunks resent at an already-received index', async () => {
+      const manager = new IncomingDataStreamManager();
+      manager.setConnected(true);
+
+      const readerPromise = new Promise<TextStreamReader>((resolve) => {
+        manager.registerTextStreamHandler('my-topic', (reader) => resolve(reader));
+      });
+
+      const streamId = crypto.randomUUID();
+      const text = 'hello world';
+      const textBytes = new TextEncoder().encode(text);
+
+      manager.handleDataStreamPacket(
+        headerPacket(streamId, 'textHeader', { totalLength: BigInt(textBytes.length) }),
+        Encryption_Type.NONE,
+      );
+      // first assuring a version going from 1 -> 2 works as expected
+      manager.handleDataStreamPacket(chunkPacket(streamId, 0, textBytes, 1), Encryption_Type.NONE);
+      // Chunk-level `version` retcon is not supported: a reader that has already yielded chunk 0 to
+      // its consumer cannot retract it, so a resend at the same index is dropped like any other
+      // duplicate rather than superseding the original. See the note on
+      // `TextStreamReader.handleChunkReceived`.
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 0, new TextEncoder().encode('goodbye world'), 2),
+        Encryption_Type.NONE,
+      );
+      // sending a lower version number again to ensure this one also gets dropped
+      manager.handleDataStreamPacket(
+        chunkPacket(streamId, 0, new TextEncoder().encode('goodbye world'), 0),
+        Encryption_Type.NONE,
+      );
+      manager.handleDataStreamPacket(trailerPacket(streamId), Encryption_Type.NONE);
+
+      const reader = await readerPromise;
+      expect(await reader.readAll()).toStrictEqual(text);
+    });
+
     it('should reframe multibyte UTF-8 on chunk boundaries when decompressing a text stream', async () => {
       const manager = new IncomingDataStreamManager();
       manager.setConnected(true);

package/src/room/data-stream/incoming/IncomingDataStreamManager.ts

@@ -241,7 +241,7 @@ export default class IncomingDataStreamManager {
             info,
             compressed
               ? inflateRawByteChunkStream(stream, streamHeader.streamId, this.maxPayloadByteLength)
-              : stream,
+              : stream.pipeThrough(ensureOrderedChunks(streamHeader.streamId)),
             // `totalLength` is the pre-compression size, and the reader counts decompressed bytes,
             // so it applies to both paths (mirrors text).
             bigIntToNumber(streamHeader.totalLength),
@@ -344,7 +344,7 @@ export default class IncomingDataStreamManager {
             info,
             compressed
               ? inflateRawChunkStream(stream, streamHeader.streamId, this.maxPayloadByteLength)
-              : stream,
+              : stream.pipeThrough(ensureOrderedChunks(streamHeader.streamId)),
             // `totalLength` is the pre-compression size, and the reader sees decompressed bytes, so
             // it applies to both paths.
             bigIntToNumber(streamHeader.totalLength),
@@ -367,7 +367,7 @@ export default class IncomingDataStreamManager {
           ),
         );
         this.byteStreamControllers.delete(chunk.streamId);
-      } else if (chunk.content.length > 0) {
+      } else {
         fileBuffer.controller.enqueue(chunk);
       }
     }
@@ -381,7 +381,7 @@ export default class IncomingDataStreamManager {
           ),
         );
         this.textStreamControllers.delete(chunk.streamId);
-      } else if (chunk.content.length > 0) {
+      } else {
         textBuffer.controller.enqueue(chunk);
       }
     }
@@ -455,15 +455,9 @@ function createInlineStream(
 ): ReadableStream<DataStream_Chunk> {
   return new ReadableStream<DataStream_Chunk>({
     start: async (controller) => {
-      try {
-        const bytes = await content;
-        controller.enqueue(
-          new DataStream_Chunk({ streamId, chunkIndex: BigInt(0), content: bytes }),
-        );
-        controller.close();
-      } catch (err) {
-        controller.error(err);
-      }
+      const bytes = await content;
+      controller.enqueue(new DataStream_Chunk({ streamId, chunkIndex: BigInt(0), content: bytes }));
+      controller.close();
     },
   });
 }
@@ -471,9 +465,11 @@ function createInlineStream(
 /**
  * Validates that chunks are received in order, dropping duplicates and throwing if gaps are found.
  *
- * A stateful decompressor silently corrupts on duplicated or out-of-order input, so duplicates are
- * dropped (with a warning - in-order delivery is expected on the reliable channel, but reconnect
- * handling may replay) and a gap is a hard error. Shared by the text and byte deflate-raw decoders.
+ * Reassembly (and, for compressed streams, a stateful decompressor) silently corrupts on duplicated
+ * or out-of-order input, so duplicates are dropped (with a warning - in-order delivery is expected
+ * on the reliable channel, but reconnect handling may replay) and a gap is a hard error. Empty
+ * chunks consume their index and are then dropped, so they never reach the reader. Applied to every
+ * chunked stream, compressed or not.
  */
 function ensureOrderedChunks(
   streamId: string,
@@ -484,17 +480,20 @@ function ensureOrderedChunks(
       const index = bigIntToNumber(value.chunkIndex);
       if (index <= lastChunkIndex) {
         log.warn(
-          `ignoring duplicate chunk ${index} for compressed data stream ${streamId} (last processed: ${lastChunkIndex})`,
+          `ignoring duplicate chunk ${index} ${value.version > 0 ? `(version ${value.version})` : ''} for data stream ${streamId} (last processed: ${lastChunkIndex})`,
         );
         return;
       }
       if (index > lastChunkIndex + 1) {
         throw new DataStreamError(
-          `Missing chunk(s) ${lastChunkIndex + 1}..${index - 1} for compressed data stream ${streamId} - cannot continue decompressing`,
+          `Missing chunk(s) ${lastChunkIndex + 1}..${index - 1} for data stream ${streamId} - cannot reassemble payload`,
           DataStreamErrorReason.Incomplete,
         );
       }
       lastChunkIndex = index;
+      if (value.content.length === 0) {
+        return;
+      }
       controller.enqueue(value);
     },
   });

package/src/room/data-stream/incoming/StreamReader.ts

@@ -1,7 +1,6 @@
 import type { DataStream_Chunk } from '@livekit/protocol';
 import { DataStreamError, DataStreamErrorReason } from '../../errors';
 import type { BaseStreamInfo, ByteStreamInfo, TextStreamInfo } from '../../types';
-import { bigIntToNumber } from '../../utils';
 
 export type BaseStreamReaderReadAllOpts = {
   /** An AbortSignal can be used to terminate reads early. */
@@ -47,14 +46,11 @@ abstract class BaseStreamReader<T extends BaseStreamInfo> {
     this.bytesReceived = 0;
   }
 
-  protected abstract handleChunkReceived(chunk: DataStream_Chunk): void;
-
-  onProgress?: (progress: number | undefined) => void;
-
-  abstract readAll(opts?: BaseStreamReaderReadAllOpts): Promise<string | Array<Uint8Array>>;
-}
-
-export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
+  /**
+   * Counts a chunk's bytes against `totalByteSize` and reports progress. Chunk ordering and
+   * de-duplication happen upstream in the manager's `ensureOrderedChunks`, so every chunk reaching
+   * here is new and in order.
+   */
   protected handleChunkReceived(chunk: DataStream_Chunk) {
     this.bytesReceived += chunk.content.byteLength;
     this.validateBytesReceived();
@@ -65,8 +61,15 @@ export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
     this.onProgress?.(currentProgress);
   }
 
+  /**
+   * @param progress - progress of the stream between 0 and 1. Undefined for streams of unknown size
+   */
   onProgress?: (progress: number | undefined) => void;
 
+  abstract readAll(opts?: BaseStreamReaderReadAllOpts): Promise<string | Array<Uint8Array>>;
+}
+
+export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
   signal?: AbortSignal;
 
   [Symbol.asyncIterator]() {
@@ -151,53 +154,20 @@ export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
 }
 
 /**
- * A class to read chunks from a ReadableStream and provide them in a structured format.
+ * A class to read chunks from a ReadableStream and decode them as UTF-8 text.
+ *
+ * NOTE: chunk-level `version` (resending a chunk at an already-received `chunkIndex` to supersede
+ * it) is not supported. The reader used to rebuild the whole string from a per-index chunk map and
+ * yield it as `TextStreamChunk.collected`, which made superseding work; 5d4a6346 (#1410, text auto
+ * chunking) changed the iterator to yield each chunk's text as it arrives, and a streaming reader
+ * cannot retract text it has already handed to the consumer. No sender emits a versioned chunk.
  */
 export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
-  private receivedChunks: Map<number /* chunk index */, DataStream_Chunk>;
-
   signal?: AbortSignal;
 
-  /**
-   * A TextStreamReader instance can be used as an AsyncIterator that returns the entire string
-   * that has been received up to the current point in time.
-   */
-  constructor(
-    info: TextStreamInfo,
-    stream: ReadableStream<DataStream_Chunk>,
-    totalChunkCount?: number,
-  ) {
-    super(info, stream, totalChunkCount);
-    this.receivedChunks = new Map();
-  }
-
-  protected handleChunkReceived(chunk: DataStream_Chunk) {
-    const index = bigIntToNumber(chunk.chunkIndex);
-    const previousChunkAtIndex = this.receivedChunks.get(index);
-    if (previousChunkAtIndex && previousChunkAtIndex.version > chunk.version) {
-      // we have a newer version already, dropping the old one
-      return;
-    }
-    this.receivedChunks.set(index, chunk);
-
-    this.bytesReceived += chunk.content.byteLength;
-    this.validateBytesReceived();
-
-    const currentProgress = this.totalByteSize
-      ? this.bytesReceived / this.totalByteSize
-      : undefined;
-    this.onProgress?.(currentProgress);
-  }
-
-  /**
-   * @param progress - progress of the stream between 0 and 1. Undefined for streams of unknown size
-   */
-  onProgress?: (progress: number | undefined) => void;
-
   /**
    * Async iterator implementation to allow usage of `for await...of` syntax.
-   * Yields structured chunks from the stream.
-   *
+   * Yields each chunk's decoded text as it arrives - a delta, not the string accumulated so far.
    */
   [Symbol.asyncIterator]() {
     const reader = this.reader.getReader();

package/src/room/events.ts

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