@marianmeres/webrtc 1.4.5 → 2.1.0

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 ```yaml
 name: "@marianmeres/webrtc"
-version: "1.0.2"
+version: "2.0.0"
 license: MIT
 author: Marian Meres
 repository: https://github.com/marianmeres/webrtc
@@ -27,12 +27,13 @@ A lightweight, framework-agnostic WebRTC manager providing:
 
 ```yaml
 production:
-  - "@marianmeres/fsm": "^2.11.0"
-  - "@marianmeres/pubsub": "^2.4.4"
+  - "@marianmeres/clog": "^3.15.2"
+  - "@marianmeres/fsm": "^2.16.4"
+  - "@marianmeres/pubsub": "^2.4.6"
 development:
-  - "@std/assert": "^1.0.16"
-  - "@std/fs": "^1.0.20"
-  - "@std/path": "^1.1.3"
+  - "@std/assert": "^1.0.18"
+  - "@std/fs": "^1.0.22"
+  - "@std/path": "^1.1.4"
 ```
 
 ## File Structure
@@ -93,15 +94,22 @@ scripts/
 
 ```
 IDLE          --INIT-->        INITIALIZING
+IDLE          --RESET-->       IDLE            (2.0)
 INITIALIZING  --CONNECT-->     CONNECTING
+INITIALIZING  --DISCONNECT-->  DISCONNECTED    (2.0, was silent no-op)
 INITIALIZING  --ERROR-->       ERROR
+INITIALIZING  --RESET-->       IDLE            (2.0, was silent no-op)
 CONNECTING    --CONNECTED-->   CONNECTED
 CONNECTING    --DISCONNECT-->  DISCONNECTED
 CONNECTING    --ERROR-->       ERROR
+CONNECTING    --RESET-->       IDLE            (2.0, was silent no-op)
 CONNECTED     --DISCONNECT-->  DISCONNECTED
 CONNECTED     --ERROR-->       ERROR
+CONNECTED     --RESET-->       IDLE            (2.0, was silent no-op)
 RECONNECTING  --CONNECT-->     CONNECTING
+RECONNECTING  --CONNECTED-->   CONNECTED       (2.0, fixes ICE-restart stuck-state bug)
 RECONNECTING  --DISCONNECT-->  DISCONNECTED
+RECONNECTING  --ERROR-->       ERROR           (2.0)
 RECONNECTING  --RESET-->       IDLE
 DISCONNECTED  --CONNECT-->     CONNECTING
 DISCONNECTED  --RECONNECTING-->RECONNECTING
@@ -150,10 +158,20 @@ interface WebRTCFactory {
 interface WebRTCManagerConfig {
   peerConfig?: RTCConfiguration;      // ICE servers, certificates
   enableMicrophone?: boolean;         // Default: false
+  audioDirection?: RTCRtpTransceiverDirection; // Default: "recvonly" (2.0)
+                                       // Direction for the audio transceiver added
+                                       // when enableMicrophone is false. Use "sendrecv"
+                                       // to avoid renegotiation when enabling mic later.
   dataChannelLabel?: string;          // Auto-create data channel
   autoReconnect?: boolean;            // Default: false
   maxReconnectAttempts?: number;      // Default: 5
   reconnectDelay?: number;            // Default: 1000ms
+  fullReconnectTimeout?: number;      // Timeout for full reconnect strategy (default: 30000ms)
+  shouldReconnect?: (context: {       // Callback to control reconnection
+    attempt: number;
+    maxAttempts: number;
+    strategy: "ice-restart" | "full";
+  }) => boolean;
   logger?: Logger;                    // Custom logger, falls back to console
 }
 ```
@@ -163,7 +181,9 @@ interface WebRTCManagerConfig {
 ```typescript
 interface GatherIceCandidatesOptions {
   timeout?: number;                                    // Timeout in ms (default: 10000)
-  onCandidate?: (candidate: RTCIceCandidate | null) => void;  // Called for each candidate
+  onCandidate?: (candidate: RTCIceCandidate) => void;  // Called for each REAL candidate
+                                                        // (2.0: null sentinel no longer forwarded)
+  resolveOnTimeout?: boolean;                          // (2.0) Resolve instead of reject on timeout
 }
 ```
 
@@ -173,7 +193,8 @@ interface GatherIceCandidatesOptions {
 |----------|------|-------------|
 | state | WebRTCState | Current FSM state |
 | localStream | MediaStream \| null | Local audio stream |
-| remoteStream | MediaStream \| null | Remote audio stream |
+| remoteStream | MediaStream \| null | First remote stream received (legacy single-stream accessor) |
+| remoteStreams | ReadonlyMap<string, MediaStream> | (2.0) All remote streams keyed by `stream.id` |
 | dataChannels | ReadonlyMap<string, RTCDataChannel> | Active data channels |
 | peerConnection | RTCPeerConnection \| null | Underlying connection |
 | context | TContext \| null | User-defined context for arbitrary data |
@@ -183,9 +204,10 @@ interface GatherIceCandidatesOptions {
 | Method | Signature | Description |
 |--------|-----------|-------------|
 | initialize | `(): Promise<void>` | Create peer connection, setup tracks |
-| connect | `(): Promise<void>` | Transition to CONNECTING (auto-initializes if IDLE) |
-| disconnect | `(): void` | Close connection, cleanup resources |
-| reset | `(): void` | Reset to IDLE from any state |
+| connect | `(): Promise<void>` | Transition to CONNECTING (auto-initializes if IDLE). (2.0) Resets `#reconnectAttempts` so a prior exhausted reconnect budget does not block new attempts. |
+| disconnect | `(): void` | Close connection, cleanup resources. (2.0) Also resets `#reconnectAttempts` and publishes `local_stream:null` / `remote_stream:null`. |
+| reset | `(): void` | Reset to IDLE from any state. (2.0) Now valid from every state (previously silently no-op'd from INITIALIZING/CONNECTING/CONNECTED). |
+| dispose | `(): void` | (2.0) Fully dispose: unsubscribes every listener registered via `on()`/`subscribe()`, cleans up the PC, transitions to IDLE. Idempotent. Manager should not be reused after dispose. |
 
 ### Audio Methods
 
@@ -212,7 +234,7 @@ interface GatherIceCandidatesOptions {
 | setLocalDescription | `(description: RTCSessionDescriptionInit): Promise<boolean>` | Set local SDP |
 | setRemoteDescription | `(description: RTCSessionDescriptionInit): Promise<boolean>` | Set remote SDP |
 | addIceCandidate | `(candidate: RTCIceCandidateInit \| null): Promise<boolean>` | Add ICE candidate |
-| iceRestart | `(): Promise<boolean>` | Perform ICE restart |
+| iceRestart | `(): Promise<boolean>` | Perform ICE restart. (2.0) Emits `ice_restart_offer` with the new local offer so the consumer can forward it via signaling. |
 | gatherIceCandidates | `(options?: GatherIceCandidatesOptions): Promise<void>` | Wait for ICE gathering to complete |
 | getLocalDescription | `(): RTCSessionDescription \| null` | Get local SDP |
 | getRemoteDescription | `(): RTCSessionDescription \| null` | Get remote SDP |
@@ -233,20 +255,22 @@ interface GatherIceCandidatesOptions {
 
 ## Event Constants
 
-| Constant | Value | Payload Type |
-|----------|-------|--------------|
-| EVENT_STATE_CHANGE | "state_change" | WebRTCState |
-| EVENT_LOCAL_STREAM | "local_stream" | MediaStream \| null |
-| EVENT_REMOTE_STREAM | "remote_stream" | MediaStream \| null |
-| EVENT_DATA_CHANNEL_OPEN | "data_channel_open" | RTCDataChannel |
-| EVENT_DATA_CHANNEL_MESSAGE | "data_channel_message" | { channel: RTCDataChannel; data: any } |
-| EVENT_DATA_CHANNEL_CLOSE | "data_channel_close" | RTCDataChannel |
-| EVENT_ICE_CANDIDATE | "ice_candidate" | RTCIceCandidate \| null |
-| EVENT_RECONNECTING | "reconnecting" | { attempt: number; strategy: "ice-restart" \| "full" } |
-| EVENT_RECONNECT_FAILED | "reconnect_failed" | { attempts: number } |
-| EVENT_DEVICE_CHANGED | "device_changed" | MediaDeviceInfo[] |
-| EVENT_MICROPHONE_FAILED | "microphone_failed" | { error?: any; reason?: string } |
-| EVENT_ERROR | "error" | Error |
+| Constant | Value | Payload Type | Notes |
+|----------|-------|--------------|-------|
+| EVENT_STATE_CHANGE | "state_change" | WebRTCState | |
+| EVENT_LOCAL_STREAM | "local_stream" | MediaStream \| null | (2.0) Also published as `null` on `disconnect()` / `cleanup()` |
+| EVENT_REMOTE_STREAM | "remote_stream" | MediaStream \| null | (2.0) Also published as `null` on `disconnect()` / `cleanup()` |
+| EVENT_DATA_CHANNEL_OPEN | "data_channel_open" | RTCDataChannel | |
+| EVENT_DATA_CHANNEL_MESSAGE | "data_channel_message" | { channel: RTCDataChannel; data: any } | |
+| EVENT_DATA_CHANNEL_CLOSE | "data_channel_close" | RTCDataChannel | |
+| EVENT_ICE_CANDIDATE | "ice_candidate" | RTCIceCandidate \| null | |
+| EVENT_RECONNECTING | "reconnecting" | { attempt: number; strategy: "ice-restart" \| "full" } | |
+| EVENT_RECONNECT_FAILED | "reconnect_failed" | { attempts: number } | |
+| EVENT_DEVICE_CHANGED | "device_changed" | MediaDeviceInfo[] | |
+| EVENT_MICROPHONE_FAILED | "microphone_failed" | { error?: any; reason?: string } | |
+| EVENT_ERROR | "error" | Error | |
+| EVENT_ICE_RESTART_OFFER | "ice_restart_offer" | RTCSessionDescriptionInit | (2.0) Emitted after `iceRestart()` creates and sets a new local offer. Consumers MUST forward it via signaling. |
+| EVENT_NEGOTIATION_NEEDED | "negotiation_needed" | undefined | (2.0) Forwarded from `pc.onnegotiationneeded`. Fires when renegotiation is required (e.g. late data channel or track change). |
 
 ## Signaling Flow (User Responsibility)
 
@@ -327,9 +351,12 @@ deno task serve:example # Run signaling server
 2. Data channels auto-cleanup on close
 3. Device change listener auto-setup on initialize
 4. "User-Initiated Abort" errors from intentional `close()` are ignored
-5. `recvonly` transceiver added when microphone disabled (ensures audio SDP)
+5. Audio transceiver added when microphone disabled (ensures audio SDP). Direction defaults to `recvonly`; override with `audioDirection` config (2.0).
 6. Private fields use `#` syntax (true ES2022 private fields)
 7. Signaling transport NOT included - users implement their own
+8. (2.0) `#reconnectAttempts` is reset whenever the user explicitly calls `connect()` / `disconnect()` / `reset()` / `dispose()`, so a prior exhausted reconnect budget never blocks a fresh session.
+9. (2.0) ICE-restart success transitions `RECONNECTING -> CONNECTED` directly via the new FSM edge. Previously the FSM stayed stuck in `RECONNECTING` because the transition did not exist.
+10. (2.0) `switchMicrophone()` promotes `recvonly` / `inactive` transceivers to `sendrecv` so replacing the track actually transmits.
 
 ## Common Usage Patterns
 
@@ -379,7 +406,54 @@ manager.on("reconnecting", ({ attempt, strategy }) => {
   }
 });
 
+// (2.0) For strategy="ice-restart", forward the offer manually if desired.
+// The library emits the local offer via EVENT_ICE_RESTART_OFFER — consumers
+// must send it to the remote peer for the restart to actually succeed.
+manager.on("ice_restart_offer", (offer) => {
+  signalingChannel.send({ type: "offer", offer });
+});
+
 manager.on("reconnect_failed", ({ attempts }) => {
   console.log(`Reconnection failed after ${attempts} attempts`);
 });
 ```
+
+## Breaking Changes (2.0)
+
+Migrating from 1.x → 2.x. Most changes are bug fixes that align with documented behavior; only one consumer-visible break.
+
+### 1. `gatherIceCandidates` — `onCandidate` callback no longer receives the terminal `null`
+
+1.x forwarded the end-of-gathering `null` sentinel to `onCandidate`. 2.x forwards only real candidates. End-of-gathering is signaled by the returned promise resolving.
+
+```typescript
+// 1.x
+await manager.gatherIceCandidates({
+  onCandidate: (c) => {
+    if (c === null) handleEnd();
+    else collect.push(c);
+  },
+});
+
+// 2.x
+await manager.gatherIceCandidates({
+  onCandidate: (c) => collect.push(c),
+});
+handleEnd(); // promise resolution == end of gathering
+```
+
+### 2. Behavior changes (no API change, but observable)
+
+- `local_stream` / `remote_stream` events are now emitted with `null` payload on `disconnect()` / `cleanup()`. Subscribers that only handled `MediaStream` payloads must also handle `null` (this matches how `enableMicrophone(false)` already behaved).
+- `reset()` now works from every state, including `INITIALIZING` / `CONNECTING` / `CONNECTED`. Previously these silently no-op'd — consumers relying on `reset()` being a no-op in those states must now expect the FSM to land in IDLE.
+- After a successful ICE-restart reconnect, the FSM now transitions `RECONNECTING -> CONNECTED`. In 1.x it remained stuck in `RECONNECTING`.
+- `#reconnectAttempts` is reset on every explicit `connect()` / `disconnect()` / `reset()` / `dispose()`. A 1.x consumer that exhausted the reconnect budget and then called `connect()` again would see no further reconnect attempts — 2.x correctly resumes.
+
+### 3. Additive (no code change required)
+
+- New config: `audioDirection` (default `"recvonly"` — same effective behavior as 1.x).
+- New getter: `remoteStreams: ReadonlyMap<string, MediaStream>`.
+- New method: `dispose()`.
+- New option: `gatherIceCandidates({ resolveOnTimeout: true })`.
+- New events: `ice_restart_offer`, `negotiation_needed`.
+- New static constants: `EVENT_ICE_RESTART_OFFER`, `EVENT_NEGOTIATION_NEEDED`.

package/API.md

@@ -16,6 +16,7 @@ Complete API documentation for `@marianmeres/webrtc`.
 - [Types](#types)
   - [WebRTCFactory](#webrtcfactory)
   - [WebRTCManagerConfig](#webrtcmanagerconfig)
+  - [GatherIceCandidatesOptions](#gathericecandidatesoptions)
   - [WebRTCState](#webrtcstate)
   - [WebRTCFsmEvent](#webrtcfsmevent)
   - [WebRTCEvents](#webrtcevents)
@@ -99,12 +100,26 @@ Returns the local media stream (microphone audio), or `null` if not initialized.
 get remoteStream(): MediaStream | null
 ```
 
-Returns the remote media stream received from peer, or `null` if not connected.
+Returns the **first** remote media stream received from the peer, or `null` if not connected. Provided for backwards compatibility; prefer `remoteStreams` when the remote side may publish more than one stream.
 
 **Returns:** `MediaStream | null`
 
 ---
 
+#### remoteStreams
+
+```typescript
+get remoteStreams(): ReadonlyMap<string, MediaStream>
+```
+
+Returns every remote media stream received so far, keyed by `stream.id`. Populated incrementally as `ontrack` events fire. Useful when the remote peer publishes multiple streams (e.g. separate audio and video, or audio from multiple participants in an SFU-style setup).
+
+**Returns:** `ReadonlyMap<string, MediaStream>`
+
+**Added in:** 2.0
+
+---
+
 #### dataChannels
 
 ```typescript
@@ -199,6 +214,8 @@ Transitions to the `CONNECTING` state. Automatically calls `initialize()` if in
 - From `INITIALIZING`: Transitions to `CONNECTING`
 - From `CONNECTED` or `CONNECTING`: No-op
 
+**Side effects (2.0):** Resets the internal reconnect attempts counter when starting a fresh session, so a previously-exhausted reconnect budget does not block new attempts.
+
 **Example:**
 
 ```typescript
@@ -219,6 +236,8 @@ Disconnects the peer connection and cleans up all resources:
 - Stops local media tracks
 - Closes peer connection
 - Clears reconnection timers
+- (2.0) Publishes `local_stream` / `remote_stream` with `null` payload so UIs drop stale stream references
+- (2.0) Resets the reconnect attempts counter
 
 **Transitions:** Any state → `DISCONNECTED`
 
@@ -241,6 +260,8 @@ Resets the manager to `IDLE` state from any state. Performs full cleanup and all
 
 **Transitions:** Any state → `IDLE`
 
+**Changed in 2.0:** Now works correctly from every state. In 1.x, calling `reset()` from `INITIALIZING` / `CONNECTING` / `CONNECTED` silently no-op'd because those FSM transitions didn't exist.
+
 **Example:**
 
 ```typescript
@@ -251,6 +272,28 @@ console.log(manager.state); // "IDLE"
 
 ---
 
+#### dispose()
+
+```typescript
+dispose(): void
+```
+
+Fully disposes the manager. Unsubscribes every listener registered via `on()` or `subscribe()`, closes the peer connection, stops streams, and transitions to `IDLE`. Idempotent. After calling this, the manager should not be reused.
+
+Use this in framework teardown hooks (React `useEffect` cleanup, Svelte `onDestroy`, Vue `onUnmounted`, etc.) instead of tracking each returned unsubscribe handle manually.
+
+**Added in:** 2.0
+
+**Example:**
+
+```typescript
+onDestroy(() => {
+  manager.dispose();
+});
+```
+
+---
+
 ### Audio Methods
 
 #### enableMicrophone()
@@ -302,6 +345,8 @@ Switches the active microphone to a different audio input device.
 
 **Requirements:** Peer connection must be initialized and microphone must be enabled.
 
+**Changed in 2.0:** Also promotes `recvonly` / `inactive` audio transceivers to `sendrecv`. In 1.x, switching the mic on a connection initialized with `enableMicrophone: false` would replace the track but leave the direction as `recvonly`, silently producing no audio.
+
 **Example:**
 
 ```typescript
@@ -551,15 +596,47 @@ await manager.addIceCandidate(remoteCandidate);
 async iceRestart(): Promise<boolean>
 ```
 
-Performs an ICE restart to recover from connection issues. Creates a new offer with the `iceRestart` flag.
+Performs an ICE restart to recover from connection issues. Creates a new offer with the `iceRestart` flag, sets it as the local description, and emits `ice_restart_offer` with the new offer.
 
 **Returns:** `boolean` - `true` if successful
 
+**Changed in 2.0:** Emits `EVENT_ICE_RESTART_OFFER` with the new local offer. Consumers **must** forward this offer to the remote peer via their signaling channel — otherwise the ICE restart silently has no effect. In 1.x the offer never left the library.
+
 **Example:**
 
 ```typescript
+manager.on(WebRTCManager.EVENT_ICE_RESTART_OFFER, (offer) => {
+  signalingChannel.send({ type: "offer", offer });
+});
+
 const success = await manager.iceRestart();
-// New ICE candidates will be generated
+// New ICE candidates will be generated once the remote side responds
+// to the forwarded offer with an answer.
+```
+
+---
+
+#### gatherIceCandidates()
+
+```typescript
+gatherIceCandidates(options?: GatherIceCandidatesOptions): Promise<void>
+```
+
+Waits for ICE gathering to complete. Useful for HTTP-POST signaling patterns where you need the local description to bundle all candidates before sending.
+
+**Parameters:** See [GatherIceCandidatesOptions](#gathericecandidatesoptions).
+
+**Returns:** `Promise<void>` — resolves when gathering completes, rejects on timeout (unless `resolveOnTimeout: true`) or if the peer connection is not initialized.
+
+**Changed in 2.0:** The `onCandidate` callback no longer receives the terminal `null` sentinel. End-of-gathering is signaled exclusively by the promise resolving.
+
+**Example:**
+
+```typescript
+const offer = await manager.createOffer();
+await manager.setLocalDescription(offer);
+await manager.gatherIceCandidates({ timeout: 5000 });
+// manager.peerConnection.localDescription now has all candidates bundled
 ```
 
 ---
@@ -779,6 +856,15 @@ interface WebRTCManagerConfig {
   /** Enable microphone on initialization. Default: false */
   enableMicrophone?: boolean;
 
+  /**
+   * Direction of the audio transceiver added during `initialize()` when the
+   * microphone is NOT enabled. Default: "recvonly".
+   * Use "sendrecv" if you plan to enable the mic later and want to avoid
+   * renegotiation when the track is added.
+   * Added in 2.0.
+   */
+  audioDirection?: RTCRtpTransceiverDirection;
+
   /** Create a data channel with this label on connect */
   dataChannelLabel?: string;
 
@@ -808,6 +894,34 @@ interface WebRTCManagerConfig {
 
 ---
 
+### GatherIceCandidatesOptions
+
+Options for `gatherIceCandidates()`.
+
+```typescript
+interface GatherIceCandidatesOptions {
+  /** Timeout in milliseconds. Default: 10000 */
+  timeout?: number;
+
+  /**
+   * Called for each real ICE candidate as it's gathered.
+   * The terminal `null` (end-of-gathering sentinel) is NOT forwarded —
+   * use the returned promise's resolution to detect completion.
+   */
+  onCandidate?: (candidate: RTCIceCandidate) => void;
+
+  /**
+   * When true, the returned promise resolves instead of rejecting on timeout.
+   * Useful for HTTP-POST signaling where partial candidates are better than none.
+   * Default: false.
+   * Added in 2.0.
+   */
+  resolveOnTimeout?: boolean;
+}
+```
+
+---
+
 ### WebRTCState
 
 Enum of possible connection states.
@@ -872,6 +986,10 @@ interface WebRTCEvents {
   device_changed: MediaDeviceInfo[];
   microphone_failed: { error?: any; reason?: string };
   error: Error;
+  /** (2.0) Local offer produced by iceRestart(); forward via signaling. */
+  ice_restart_offer: RTCSessionDescriptionInit;
+  /** (2.0) Forwarded from pc.onnegotiationneeded. */
+  negotiation_needed: undefined;
 }
 ```
 
@@ -884,12 +1002,14 @@ Static event name constants on `WebRTCManager`.
 | Constant | Value | Payload |
 |----------|-------|---------|
 | `EVENT_STATE_CHANGE` | `"state_change"` | `WebRTCState` |
-| `EVENT_LOCAL_STREAM` | `"local_stream"` | `MediaStream \| null` |
-| `EVENT_REMOTE_STREAM` | `"remote_stream"` | `MediaStream \| null` |
+| `EVENT_LOCAL_STREAM` | `"local_stream"` | `MediaStream \| null` (also fires `null` on teardown — 2.0) |
+| `EVENT_REMOTE_STREAM` | `"remote_stream"` | `MediaStream \| null` (also fires `null` on teardown — 2.0) |
 | `EVENT_DATA_CHANNEL_OPEN` | `"data_channel_open"` | `RTCDataChannel` |
 | `EVENT_DATA_CHANNEL_MESSAGE` | `"data_channel_message"` | `{ channel, data }` |
 | `EVENT_DATA_CHANNEL_CLOSE` | `"data_channel_close"` | `RTCDataChannel` |
 | `EVENT_ICE_CANDIDATE` | `"ice_candidate"` | `RTCIceCandidate \| null` |
+| `EVENT_ICE_RESTART_OFFER` | `"ice_restart_offer"` | `RTCSessionDescriptionInit` (2.0) |
+| `EVENT_NEGOTIATION_NEEDED` | `"negotiation_needed"` | `undefined` (2.0) |
 | `EVENT_RECONNECTING` | `"reconnecting"` | `{ attempt, strategy }` |
 | `EVENT_RECONNECT_FAILED` | `"reconnect_failed"` | `{ attempts }` |
 | `EVENT_DEVICE_CHANGED` | `"device_changed"` | `MediaDeviceInfo[]` |
@@ -948,23 +1068,30 @@ manager.on(WebRTCManager.EVENT_ICE_CANDIDATE, (candidate) => {
 
 ### Valid Transitions
 
-| From State | Event | To State |
-|------------|-------|----------|
-| IDLE | INIT | INITIALIZING |
-| INITIALIZING | CONNECT | CONNECTING |
-| INITIALIZING | ERROR | ERROR |
-| CONNECTING | CONNECTED | CONNECTED |
-| CONNECTING | DISCONNECT | DISCONNECTED |
-| CONNECTING | ERROR | ERROR |
-| CONNECTED | DISCONNECT | DISCONNECTED |
-| CONNECTED | ERROR | ERROR |
-| RECONNECTING | CONNECT | CONNECTING |
-| RECONNECTING | DISCONNECT | DISCONNECTED |
-| RECONNECTING | RESET | IDLE |
-| DISCONNECTED | CONNECT | CONNECTING |
-| DISCONNECTED | RECONNECTING | RECONNECTING |
-| DISCONNECTED | RESET | IDLE |
-| ERROR | RESET | IDLE |
+| From State | Event | To State | Notes |
+|------------|-------|----------|-------|
+| IDLE | INIT | INITIALIZING | |
+| IDLE | RESET | IDLE | 2.0 — idempotent reset |
+| INITIALIZING | CONNECT | CONNECTING | |
+| INITIALIZING | DISCONNECT | DISCONNECTED | 2.0 — was silent no-op |
+| INITIALIZING | ERROR | ERROR | |
+| INITIALIZING | RESET | IDLE | 2.0 — was silent no-op |
+| CONNECTING | CONNECTED | CONNECTED | |
+| CONNECTING | DISCONNECT | DISCONNECTED | |
+| CONNECTING | ERROR | ERROR | |
+| CONNECTING | RESET | IDLE | 2.0 — was silent no-op |
+| CONNECTED | DISCONNECT | DISCONNECTED | |
+| CONNECTED | ERROR | ERROR | |
+| CONNECTED | RESET | IDLE | 2.0 — was silent no-op |
+| RECONNECTING | CONNECT | CONNECTING | |
+| RECONNECTING | CONNECTED | CONNECTED | 2.0 — fixes ICE-restart stuck-state bug |
+| RECONNECTING | DISCONNECT | DISCONNECTED | |
+| RECONNECTING | ERROR | ERROR | 2.0 |
+| RECONNECTING | RESET | IDLE | |
+| DISCONNECTED | CONNECT | CONNECTING | |
+| DISCONNECTED | RECONNECTING | RECONNECTING | |
+| DISCONNECTED | RESET | IDLE | |
+| ERROR | RESET | IDLE | |
 
 ### Reconnection Strategy
 

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/README.md

@@ -49,6 +49,7 @@ const manager = new WebRTCManager<TContext>(factory, config);
 **Configuration Options:**
 - `peerConfig`: RTCConfiguration (ICE servers, etc.)
 - `enableMicrophone`: Enable microphone on initialization (default: false)
+- `audioDirection`: Direction of the audio transceiver added when `enableMicrophone` is false (default: `"recvonly"`). Use `"sendrecv"` if you plan to enable the mic later and want to avoid renegotiation.
 - `dataChannelLabel`: Create a default data channel with this label
 - `autoReconnect`: Enable automatic reconnection (default: false)
 - `maxReconnectAttempts`: Max reconnection attempts (default: 5)
@@ -62,7 +63,8 @@ const manager = new WebRTCManager<TContext>(factory, config);
 ```typescript
 manager.state                 // Current WebRTCState
 manager.localStream           // MediaStream | null
-manager.remoteStream          // MediaStream | null
+manager.remoteStream          // MediaStream | null  (first stream — legacy)
+manager.remoteStreams         // ReadonlyMap<string, MediaStream>  (all remote streams by id)
 manager.dataChannels          // ReadonlyMap<string, RTCDataChannel>
 manager.peerConnection        // RTCPeerConnection | null
 manager.context               // TContext | null - user-defined data
@@ -74,7 +76,8 @@ manager.context               // TContext | null - user-defined data
 await manager.initialize()    // Initialize peer connection
 await manager.connect()       // Transition to CONNECTING state
 manager.disconnect()          // Disconnect and cleanup
-manager.reset()               // Reset to IDLE state
+manager.reset()               // Reset to IDLE state (valid from any state)
+manager.dispose()             // Full teardown: cleanup + unsubscribe every listener
 ```
 
 ### Audio Methods
@@ -101,7 +104,10 @@ await manager.gatherIceCandidates(options)     // Wait for ICE gathering to comp
 
 Wait for ICE gathering to complete. Useful for HTTP POST signaling patterns where you need all ICE candidates bundled in the local description before sending to the server.
 
-**Options:** `timeout` (ms, default 10000), `onCandidate` (callback for each candidate)
+**Options:**
+- `timeout` (ms, default 10000)
+- `onCandidate` — callback fired for each real candidate as it arrives (the terminal `null` sentinel is NOT forwarded; use the promise resolution to detect completion)
+- `resolveOnTimeout` (boolean, default `false`) — when `true`, the promise resolves on timeout instead of rejecting, allowing you to proceed with whatever candidates were gathered so far
 
 ```typescript
 const offer = await manager.createOffer();
@@ -121,6 +127,7 @@ try {
     // 1. Retry with longer timeout
     // 2. Proceed anyway - localDescription may have partial candidates
     // 3. Treat as fatal: manager.reset()
+    // 4. Or pass `resolveOnTimeout: true` upfront to skip the reject path
   }
 }
 ```
@@ -198,12 +205,14 @@ const unsub = manager.subscribe((state) => {
 
 **Available Event Constants:**
 - `EVENT_STATE_CHANGE`
-- `EVENT_LOCAL_STREAM`
-- `EVENT_REMOTE_STREAM`
+- `EVENT_LOCAL_STREAM` — also fires with `null` when the local stream is torn down
+- `EVENT_REMOTE_STREAM` — also fires with `null` when the remote stream is torn down
 - `EVENT_DATA_CHANNEL_OPEN`
 - `EVENT_DATA_CHANNEL_MESSAGE`
 - `EVENT_DATA_CHANNEL_CLOSE`
 - `EVENT_ICE_CANDIDATE`
+- `EVENT_ICE_RESTART_OFFER` — emitted after `iceRestart()` with the new local offer; forward via signaling
+- `EVENT_NEGOTIATION_NEEDED` — forwarded from `pc.onnegotiationneeded` (e.g. after a late track or data channel)
 - `EVENT_RECONNECTING`
 - `EVENT_RECONNECT_FAILED`
 - `EVENT_DEVICE_CHANGED`
@@ -563,6 +572,60 @@ This example demonstrates:
 - **Audio streaming via WebRTC media tracks** (click "Send Beep" to transmit generated audio)
 - State change monitoring
 
+## Upgrading from 1.x to 2.x
+
+Version 2.0 is a **bug-fix-driven major release**. Most changes are internal corrections that make the library behave the way the docs already said it did. There is exactly **one API-level breaking change**, plus a handful of observable behavior changes you should audit.
+
+### Breaking: `gatherIceCandidates` — `onCandidate` no longer receives the terminal `null`
+
+In 1.x, the `onCandidate` callback was invoked once with `null` to signal end-of-gathering. In 2.x, only real ICE candidates are forwarded. End-of-gathering is signaled exclusively by the returned promise resolving.
+
+```typescript
+// 1.x
+await manager.gatherIceCandidates({
+  onCandidate: (c) => {
+    if (c === null) onGatheringComplete();
+    else collectedCandidates.push(c);
+  },
+});
+
+// 2.x
+await manager.gatherIceCandidates({
+  onCandidate: (c) => collectedCandidates.push(c),
+});
+onGatheringComplete(); // promise resolution = end of gathering
+```
+
+If you weren't using `onCandidate`, nothing changes.
+
+### Behavior changes (no API change, but worth auditing)
+
+1. **Stream events now fire with `null` on teardown.** `local_stream` and `remote_stream` subscribers will now receive `null` when `disconnect()` or `dispose()` runs. If your handler assumed the payload was always a `MediaStream`, add a null check. This matches how `enableMicrophone(false)` already behaved and fixes stale `<audio srcObject>` references in UIs.
+
+2. **`reset()` now works from every state.** In 1.x, calling `reset()` from `INITIALIZING`, `CONNECTING`, or `CONNECTED` silently did nothing (the FSM refused the transition). In 2.x, it always lands in `IDLE`. If you relied on `reset()` being a no-op from those states, wrap the call in a state guard.
+
+3. **ICE-restart reconnects now actually transition to `CONNECTED`.** In 1.x, a successful ICE-restart reconnect left the FSM stuck in `RECONNECTING` because the necessary transition was missing. In 2.x, `RECONNECTING → CONNECTED` is valid and the state machine tracks reality. Code that polled for `state === "RECONNECTING"` as a proxy for "still in flux" may now see `CONNECTED` sooner.
+
+4. **`#reconnectAttempts` resets on every explicit `connect()`/`disconnect()`/`reset()`/`dispose()`.** In 1.x, once the reconnect budget was exhausted, a subsequent user-initiated `connect()` inherited the exhausted counter and would skip all further reconnect attempts on the new session. In 2.x, the counter resets so the next session gets a fresh budget.
+
+5. **`iceRestart()` now emits `ice_restart_offer`.** A real ICE restart requires the new local offer to reach the remote peer via signaling. In 1.x, the library set the local description and returned — the offer never left the process, so ICE restarts silently failed unless the remote side also initiated. In 2.x, subscribe to `ice_restart_offer` and forward the offer through your signaling channel:
+
+   ```typescript
+   manager.on("ice_restart_offer", (offer) => {
+     signalingChannel.send({ type: "offer", offer });
+   });
+   ```
+
+6. **`switchMicrophone()` now promotes `recvonly`/`inactive` transceivers to `sendrecv`.** Previously, calling `switchMicrophone()` on a connection that was originally set up with the mic disabled would replace the track but leave the transceiver direction as `recvonly`, silently producing no audio. 2.x promotes the direction so the new track actually transmits.
+
+### New, additive APIs (no code changes required)
+
+- `audioDirection` config — set to `"sendrecv"` if you plan to enable the mic mid-session and want to avoid renegotiation.
+- `remoteStreams` getter — `ReadonlyMap<string, MediaStream>` of all remote streams, keyed by stream id. The legacy single-stream `remoteStream` getter still works and points at the first stream received.
+- `dispose()` method — one-shot teardown that unsubscribes every listener registered via `on()` or `subscribe()` and cleans up the peer connection. Use in framework teardown hooks instead of tracking each returned unsubscribe handle.
+- `gatherIceCandidates({ resolveOnTimeout: true })` — resolves the promise on timeout instead of rejecting.
+- `negotiation_needed` event — forwarded from `pc.onnegotiationneeded`. Listen for it when you create data channels or add tracks after the initial handshake.
+
 ## License
 
 MIT

package/dist/types.d.ts

@@ -18,6 +18,13 @@ export interface WebRTCManagerConfig {
     peerConfig?: RTCConfiguration;
     /** Whether to enable microphone initially. Defaults to false. */
     enableMicrophone?: boolean;
+    /**
+     * Direction of the audio transceiver added during `initialize()` when the
+     * microphone is NOT enabled. Defaults to "recvonly".
+     * Use "sendrecv" if you expect to enable the microphone mid-session and want
+     * to avoid renegotiation.
+     */
+    audioDirection?: RTCRtpTransceiverDirection;
     /** Label for the default data channel. If provided, a data channel will be created on connect. */
     dataChannelLabel?: string;
     /** Enable automatic reconnection on connection failure. Defaults to false. */
@@ -153,6 +160,18 @@ export interface WebRTCEvents {
     };
     /** Emitted when an error occurs. Payload: the Error object. */
     error: Error;
+    /**
+     * Emitted after `iceRestart()` creates and sets a new local offer.
+     * Consumers MUST forward this offer to the remote peer via signaling for
+     * the ICE restart to actually succeed.
+     */
+    ice_restart_offer: RTCSessionDescriptionInit;
+    /**
+     * Emitted when the peer connection reports that renegotiation is needed
+     * (e.g. after adding tracks or creating a data channel post-handshake).
+     * Consumers should create a new offer and re-signal.
+     */
+    negotiation_needed: undefined;
 }
 /**
  * Options for waiting for ICE gathering to complete.
@@ -161,6 +180,16 @@ export interface WebRTCEvents {
 export interface GatherIceCandidatesOptions {
     /** Timeout in milliseconds (default: 10000) */
     timeout?: number;
-    /** Called for each ICE candidate as it's gathered */
-    onCandidate?: (candidate: RTCIceCandidate | null) => void;
+    /**
+     * Called for each real ICE candidate as it's gathered.
+     * The terminal `null` (end-of-gathering sentinel) is NOT forwarded —
+     * use the returned promise's resolution to detect completion.
+     */
+    onCandidate?: (candidate: RTCIceCandidate) => void;
+    /**
+     * If true, the returned promise resolves instead of rejecting when the timeout
+     * elapses. Useful for HTTP-POST signaling where partial candidates are better
+     * than no candidates at all. Defaults to false (preserving existing behavior).
+     */
+    resolveOnTimeout?: boolean;
 }

package/dist/webrtc-manager.d.ts

@@ -51,6 +51,19 @@ export declare class WebRTCManager<TContext = unknown> {
     static readonly EVENT_MICROPHONE_FAILED = "microphone_failed";
     /** Event emitted when an error occurs. Payload: `Error` */
     static readonly EVENT_ERROR = "error";
+    /**
+     * Event emitted after `iceRestart()` creates and sets a new local offer.
+     * Consumers MUST forward the offer SDP to the remote peer via signaling.
+     * Payload: `RTCSessionDescriptionInit`
+     */
+    static readonly EVENT_ICE_RESTART_OFFER = "ice_restart_offer";
+    /**
+     * Event emitted when the peer connection fires `negotiationneeded`
+     * (e.g., when a data channel is created after the initial handshake, or when
+     * tracks are added/removed). Consumers should create a new offer and renegotiate.
+     * Payload: `undefined`
+     */
+    static readonly EVENT_NEGOTIATION_NEEDED = "negotiation_needed";
     /**
      * User-defined context object for storing arbitrary data associated with this manager.
      * Useful for attaching application-specific state (e.g., audio streams, metadata)
@@ -81,8 +94,17 @@ export declare class WebRTCManager<TContext = unknown> {
     get dataChannels(): ReadonlyMap<string, RTCDataChannel>;
     /** Returns the local media stream, or null if not initialized. */
     get localStream(): MediaStream | null;
-    /** Returns the remote media stream, or null if not connected. */
+    /**
+     * Returns the first remote media stream received, or null if not connected.
+     * For connections that may produce multiple remote streams, prefer {@link remoteStreams}.
+     */
     get remoteStream(): MediaStream | null;
+    /**
+     * Returns a readonly map of all remote media streams, keyed by stream id.
+     * Populated as `ontrack` fires. Useful when the remote peer publishes more
+     * than one stream (e.g. separate audio + video).
+     */
+    get remoteStreams(): ReadonlyMap<string, MediaStream>;
     /** Returns the underlying RTCPeerConnection, or null if not initialized. */
     get peerConnection(): RTCPeerConnection | null;
     /** Returns a Mermaid diagram representation of the FSM state machine. */
@@ -145,6 +167,12 @@ export declare class WebRTCManager<TContext = unknown> {
      * Cleans up all resources and allows reinitialization.
      */
     reset(): void;
+    /**
+     * Fully disposes the manager: closes the connection, stops streams, and
+     * unsubscribes every event listener registered via `on()` or `subscribe()`.
+     * After calling this, the manager should not be reused.
+     */
+    dispose(): void;
     /**
      * Creates a new data channel with the specified label.
      * Returns existing channel if one with the same label already exists.

package/dist/webrtc-manager.js

@@ -53,6 +53,19 @@ export class WebRTCManager {
     static EVENT_MICROPHONE_FAILED = "microphone_failed";
     /** Event emitted when an error occurs. Payload: `Error` */
     static EVENT_ERROR = "error";
+    /**
+     * Event emitted after `iceRestart()` creates and sets a new local offer.
+     * Consumers MUST forward the offer SDP to the remote peer via signaling.
+     * Payload: `RTCSessionDescriptionInit`
+     */
+    static EVENT_ICE_RESTART_OFFER = "ice_restart_offer";
+    /**
+     * Event emitted when the peer connection fires `negotiationneeded`
+     * (e.g., when a data channel is created after the initial handshake, or when
+     * tracks are added/removed). Consumers should create a new offer and renegotiate.
+     * Payload: `undefined`
+     */
+    static EVENT_NEGOTIATION_NEEDED = "negotiation_needed";
     #fsm;
     #pubsub;
     #pc = null;
@@ -61,8 +74,10 @@ export class WebRTCManager {
     #logger;
     #localStream = null;
     #remoteStream = null;
+    #remoteStreams = new Map();
     #dataChannels = new Map();
     #reconnectAttempts = 0;
+    #disposed = false;
     /**
      * User-defined context object for storing arbitrary data associated with this manager.
      * Useful for attaching application-specific state (e.g., audio streams, metadata)
@@ -100,12 +115,17 @@ export class WebRTCManager {
             logger: this.#logger,
             states: {
                 [WebRTCState.IDLE]: {
-                    on: { [WebRTCFsmEvent.INIT]: WebRTCState.INITIALIZING },
+                    on: {
+                        [WebRTCFsmEvent.INIT]: WebRTCState.INITIALIZING,
+                        [WebRTCFsmEvent.RESET]: WebRTCState.IDLE,
+                    },
                 },
                 [WebRTCState.INITIALIZING]: {
                     on: {
                         [WebRTCFsmEvent.CONNECT]: WebRTCState.CONNECTING,
+                        [WebRTCFsmEvent.DISCONNECT]: WebRTCState.DISCONNECTED,
                         [WebRTCFsmEvent.ERROR]: WebRTCState.ERROR,
+                        [WebRTCFsmEvent.RESET]: WebRTCState.IDLE,
                     },
                 },
                 [WebRTCState.CONNECTING]: {
@@ -113,18 +133,24 @@ export class WebRTCManager {
                         [WebRTCFsmEvent.CONNECTED]: WebRTCState.CONNECTED,
                         [WebRTCFsmEvent.DISCONNECT]: WebRTCState.DISCONNECTED,
                         [WebRTCFsmEvent.ERROR]: WebRTCState.ERROR,
+                        [WebRTCFsmEvent.RESET]: WebRTCState.IDLE,
                     },
                 },
                 [WebRTCState.CONNECTED]: {
                     on: {
                         [WebRTCFsmEvent.DISCONNECT]: WebRTCState.DISCONNECTED,
                         [WebRTCFsmEvent.ERROR]: WebRTCState.ERROR,
+                        [WebRTCFsmEvent.RESET]: WebRTCState.IDLE,
                     },
                 },
                 [WebRTCState.RECONNECTING]: {
                     on: {
                         [WebRTCFsmEvent.CONNECT]: WebRTCState.CONNECTING,
+                        // ICE-restart success transitions directly from RECONNECTING to CONNECTED
+                        // without going through CONNECTING (the PC was never torn down).
+                        [WebRTCFsmEvent.CONNECTED]: WebRTCState.CONNECTED,
                         [WebRTCFsmEvent.DISCONNECT]: WebRTCState.DISCONNECTED,
+                        [WebRTCFsmEvent.ERROR]: WebRTCState.ERROR,
                         [WebRTCFsmEvent.RESET]: WebRTCState.IDLE,
                     },
                 },
@@ -154,10 +180,21 @@ export class WebRTCManager {
     get localStream() {
         return this.#localStream;
     }
-    /** Returns the remote media stream, or null if not connected. */
+    /**
+     * Returns the first remote media stream received, or null if not connected.
+     * For connections that may produce multiple remote streams, prefer {@link remoteStreams}.
+     */
     get remoteStream() {
         return this.#remoteStream;
     }
+    /**
+     * Returns a readonly map of all remote media streams, keyed by stream id.
+     * Populated as `ontrack` fires. Useful when the remote peer publishes more
+     * than one stream (e.g. separate audio + video).
+     */
+    get remoteStreams() {
+        return this.#remoteStreams;
+    }
     /** Returns the underlying RTCPeerConnection, or null if not initialized. */
     get peerConnection() {
         return this.#pc;
@@ -241,21 +278,22 @@ export class WebRTCManager {
             if (!newTrack) {
                 throw new Error("No audio track in new stream");
             }
-            // Find the sender for the audio track - check both senders and transceivers
-            let sender = this.#pc.getSenders().find((s) => s.track?.kind === "audio");
-            if (!sender) {
-                // Try to find via transceiver
-                const transceivers = this.#pc.getTransceivers();
-                const audioTransceiver = transceivers.find((t) => t.receiver.track.kind === "audio");
-                if (audioTransceiver) {
-                    sender = audioTransceiver.sender;
-                }
+            // Locate the audio transceiver so we can both replace the track AND
+            // ensure the direction allows sending. Using the transceiver (rather
+            // than just the sender) lets us flip `recvonly` -> `sendrecv` when
+            // the mic was previously disabled.
+            const transceivers = this.#pc.getTransceivers();
+            const audioTransceiver = transceivers.find((t) => t.sender.track?.kind === "audio" ||
+                t.receiver.track?.kind === "audio");
+            if (!audioTransceiver) {
+                throw new Error("No audio transceiver found - enable microphone first");
             }
-            if (!sender) {
-                throw new Error("No audio sender found - enable microphone first");
+            await audioTransceiver.sender.replaceTrack(newTrack);
+            if (audioTransceiver.direction === "recvonly" ||
+                audioTransceiver.direction === "inactive") {
+                audioTransceiver.direction = "sendrecv";
+                this.#logger.debug("switchMicrophone: promoted transceiver direction to sendrecv.");
             }
-            // Replace the track
-            await sender.replaceTrack(newTrack);
             // Stop old tracks
             this.#localStream.getAudioTracks().forEach((track) => track.stop());
             // Update local stream reference
@@ -296,10 +334,12 @@ export class WebRTCManager {
                 }
             }
             else {
-                // Always setup to receive audio, even if we don't enable microphone
-                // This ensures the SDP includes audio media line
-                this.#pc.addTransceiver("audio", { direction: "recvonly" });
-                this.#logger.debug("Added receive-only audio transceiver.");
+                // Always setup an audio transceiver so the SDP includes an audio media line.
+                // Direction is configurable (default recvonly for BC). Use 'sendrecv' when
+                // you expect to enable the mic later without having to renegotiate.
+                const direction = this.#config.audioDirection ?? "recvonly";
+                this.#pc.addTransceiver("audio", { direction });
+                this.#logger.debug(`Added audio transceiver (direction=${direction}).`);
             }
             if (this.#config.dataChannelLabel) {
                 this.#logger.debug(`Creating default data channel '${this.#config.dataChannelLabel}'.`);
@@ -318,6 +358,13 @@ export class WebRTCManager {
      */
     async connect() {
         this.#logger.debug(`Connect called with current state ${this.state}.`);
+        // A user-initiated connect starts a fresh reconnect budget. Without this,
+        // a second connection attempt after an earlier exhausted reconnect would
+        // short-circuit in #handleConnectionFailure and never retry.
+        if (this.state !== WebRTCState.RECONNECTING &&
+            this.state !== WebRTCState.CONNECTING) {
+            this.#reconnectAttempts = 0;
+        }
         // Initialize if needed
         if (this.state === WebRTCState.IDLE) {
             this.#logger.debug("State is IDLE, initializing first.");
@@ -329,7 +376,7 @@ export class WebRTCManager {
             // Clean up old connection
             this.#cleanup();
             // Reset to IDLE and reinitialize
-            this.#fsm.transition(WebRTCFsmEvent.RESET);
+            this.#dispatch(WebRTCFsmEvent.RESET);
             await this.initialize();
             // Stay in INITIALIZING state - caller needs to create offer/answer
             return;
@@ -423,7 +470,11 @@ export class WebRTCManager {
      */
     disconnect() {
         this.#logger.debug("Disconnect called.");
+        // Explicit disconnect is a user-initiated cancel of any in-flight reconnect.
+        this.#reconnectAttempts = 0;
         this.#cleanup();
+        // DISCONNECT is only valid from INITIALIZING/CONNECTING/CONNECTED/RECONNECTING.
+        // From other states, the event is a no-op, which is the desired behavior.
         this.#dispatch(WebRTCFsmEvent.DISCONNECT);
     }
     /**
@@ -432,23 +483,30 @@ export class WebRTCManager {
      */
     reset() {
         this.#logger.debug(`Reset called with current state ${this.state}.`);
+        this.#reconnectAttempts = 0;
         this.#cleanup();
-        // Reset from any non-IDLE state
-        if (this.state !== WebRTCState.IDLE) {
-            // Force transition to DISCONNECTED first if needed, then to IDLE
-            if (this.state === WebRTCState.ERROR ||
-                this.state === WebRTCState.DISCONNECTED ||
-                this.state === WebRTCState.RECONNECTING) {
-                this.#dispatch(WebRTCFsmEvent.RESET);
-            }
-            else {
-                // For other states, go through DISCONNECTED first
-                this.#dispatch(WebRTCFsmEvent.DISCONNECT);
-                this.#dispatch(WebRTCFsmEvent.RESET);
-            }
-        }
+        // RESET is now valid from every state, so a single dispatch always lands in IDLE.
+        this.#dispatch(WebRTCFsmEvent.RESET);
         this.#logger.debug(`Reset complete, state is now ${this.state}.`);
     }
+    /**
+     * Fully disposes the manager: closes the connection, stops streams, and
+     * unsubscribes every event listener registered via `on()` or `subscribe()`.
+     * After calling this, the manager should not be reused.
+     */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#logger.debug("Dispose called.");
+        this.#disposed = true;
+        this.#reconnectAttempts = 0;
+        // Drop every subscriber first so teardown side-effects (stream clears,
+        // state transitions) don't fire notifications at a consumer that's
+        // explicitly asked to let go.
+        this.#pubsub.unsubscribeAll();
+        this.#cleanup();
+        this.#dispatch(WebRTCFsmEvent.RESET);
+    }
     /**
      * Creates a new data channel with the specified label.
      * Returns existing channel if one with the same label already exists.
@@ -642,6 +700,10 @@ export class WebRTCManager {
         try {
             const offer = await this.#pc.createOffer({ iceRestart: true });
             await this.#pc.setLocalDescription(offer);
+            // A real ICE restart requires the new offer to reach the remote peer
+            // and an answer to come back. Emit the offer so consumers can forward it
+            // via their signaling channel. Without this, ICE restart silently fails.
+            this.#pubsub.publish(WebRTCManager.EVENT_ICE_RESTART_OFFER, offer);
             this.#logger.debug("ICE restart initiated.");
             return true;
         }
@@ -658,7 +720,7 @@ export class WebRTCManager {
      * @param options - Optional configuration for timeout and candidate callback.
      */
     gatherIceCandidates(options = {}) {
-        const { timeout = 10000, onCandidate } = options;
+        const { timeout = 10000, onCandidate, resolveOnTimeout = false } = options;
         if (!this.#pc) {
             return Promise.reject(new Error("Peer connection not initialized"));
         }
@@ -671,7 +733,13 @@ export class WebRTCManager {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 cleanup();
-                reject(new Error("ICE gathering timeout"));
+                if (resolveOnTimeout) {
+                    this.#logger.debug("ICE gathering timed out; resolving with partial candidates.");
+                    resolve();
+                }
+                else {
+                    reject(new Error("ICE gathering timeout"));
+                }
             }, timeout);
             const cleanup = () => {
                 clearTimeout(timer);
@@ -686,8 +754,12 @@ export class WebRTCManager {
                 }
             };
             const handleCandidate = (event) => {
-                onCandidate?.(event.candidate);
-                if (event.candidate === null) {
+                // Only forward real candidates to the callback; the terminal `null`
+                // is an end-of-gathering sentinel, not a candidate.
+                if (event.candidate) {
+                    onCandidate?.(event.candidate);
+                }
+                else {
                     this.#logger.debug("ICE gathering complete via null candidate.");
                     cleanup();
                     resolve();
@@ -762,9 +834,10 @@ export class WebRTCManager {
             const state = this.#pc.connectionState;
             this.#logger.debug(`Connection state changed to ${state}.`);
             if (state === "connected") {
-                // Only dispatch if in CONNECTING state (FSM can handle CONNECTED event)
-                // This guards against late connection success after user has disconnected
-                if (this.state === WebRTCState.CONNECTING) {
+                // Dispatch CONNECTED from either CONNECTING (fresh connection / full reconnect)
+                // or RECONNECTING (successful ICE-restart keeps the PC alive).
+                if (this.state === WebRTCState.CONNECTING ||
+                    this.state === WebRTCState.RECONNECTING) {
                     // Connection successful - reset reconnect attempts and clear any pending timeout
                     this.#reconnectAttempts = 0;
                     if (this.#fullReconnectTimeoutTimer !== null) {
@@ -782,10 +855,13 @@ export class WebRTCManager {
                 this.#handleConnectionFailure();
             }
             else if (state === "disconnected" || state === "closed") {
-                // Only dispatch if not already in a terminal state
+                // Only dispatch if not already in a terminal state.
+                // Also skip INITIALIZING (no DISCONNECT transition is meaningful there —
+                // initialize() owns that state and will handle failure via ERROR).
                 if (this.state !== WebRTCState.DISCONNECTED &&
                     this.state !== WebRTCState.ERROR &&
-                    this.state !== WebRTCState.IDLE) {
+                    this.state !== WebRTCState.IDLE &&
+                    this.state !== WebRTCState.INITIALIZING) {
                     this.#dispatch(WebRTCFsmEvent.DISCONNECT);
                 }
             }
@@ -793,8 +869,14 @@ export class WebRTCManager {
         this.#pc.ontrack = (event) => {
             this.#logger.debug(`Remote ${event.track.kind} track received.`);
             if (event.streams && event.streams[0]) {
-                this.#remoteStream = event.streams[0];
-                this.#pubsub.publish(WebRTCManager.EVENT_REMOTE_STREAM, this.#remoteStream);
+                const stream = event.streams[0];
+                // Track the first stream under the legacy `remoteStream` getter for BC,
+                // and accumulate every distinct stream under `remoteStreams` by id.
+                if (!this.#remoteStream) {
+                    this.#remoteStream = stream;
+                }
+                this.#remoteStreams.set(stream.id, stream);
+                this.#pubsub.publish(WebRTCManager.EVENT_REMOTE_STREAM, stream);
             }
         };
         this.#pc.ondatachannel = (event) => {
@@ -807,6 +889,10 @@ export class WebRTCManager {
             this.#logger.debug(`ICE candidate generated: ${event.candidate ? "candidate" : "null (gathering complete)"}.`);
             this.#pubsub.publish(WebRTCManager.EVENT_ICE_CANDIDATE, event.candidate);
         };
+        this.#pc.onnegotiationneeded = () => {
+            this.#logger.debug("Negotiation needed.");
+            this.#pubsub.publish(WebRTCManager.EVENT_NEGOTIATION_NEEDED, undefined);
+        };
     }
     #cleanup() {
         this.#logger.debug("Cleanup started.");
@@ -837,6 +923,7 @@ export class WebRTCManager {
             this.#logger.debug(`Closed ${dcCount} data channel(s).`);
         }
         // Stop local stream tracks
+        const hadLocalStream = this.#localStream !== null;
         if (this.#localStream) {
             this.#localStream.getTracks().forEach((track) => track.stop());
             this.#localStream = null;
@@ -848,7 +935,17 @@ export class WebRTCManager {
             this.#pc = null;
             this.#logger.debug("Peer connection closed.");
         }
+        const hadRemoteStream = this.#remoteStream !== null || this.#remoteStreams.size > 0;
         this.#remoteStream = null;
+        this.#remoteStreams.clear();
+        // Notify subscribers that streams are gone so UIs can drop stale <audio>/<video>
+        // srcObject references. Symmetric with enableMicrophone(false).
+        if (hadLocalStream) {
+            this.#pubsub.publish(WebRTCManager.EVENT_LOCAL_STREAM, null);
+        }
+        if (hadRemoteStream) {
+            this.#pubsub.publish(WebRTCManager.EVENT_REMOTE_STREAM, null);
+        }
         this.#logger.debug("Cleanup complete.");
     }
     #handleConnectionFailure() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.4.5",
+	"version": "2.1.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -10,11 +10,19 @@
 			"import": "./dist/mod.js"
 		}
 	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md"
+	],
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/fsm": "^2.16.4",
-		"@marianmeres/pubsub": "^2.4.4"
+		"@marianmeres/fsm": "^3.0.0",
+		"@marianmeres/pubsub": "^3.0.0"
 	},
 	"repository": {
 		"type": "git",