@marianmeres/webrtc 1.1.1 → 1.2.1

package/AGENTS.md

@@ -114,9 +114,11 @@ ERROR         --RESET-->       IDLE
 ### Constructor
 
 ```typescript
-new WebRtcManager(factory: WebRtcFactory, config?: WebRtcManagerConfig)
+new WebRtcManager<TContext = unknown>(factory: WebRtcFactory, config?: WebRtcManagerConfig)
 ```
 
+**Type Parameter:** `TContext` - Optional type for the `context` property (default: `unknown`)
+
 ### Logger Interface
 
 Console-compatible logger interface for custom logging implementations.
@@ -166,6 +168,7 @@ interface WebRtcManagerConfig {
 | remoteStream | MediaStream \| null | Remote audio stream |
 | dataChannels | ReadonlyMap<string, RTCDataChannel> | Active data channels |
 | peerConnection | RTCPeerConnection \| null | Underlying connection |
+| context | TContext \| null | User-defined context for arbitrary data |
 
 ### Lifecycle Methods
 

package/API.md

@@ -31,9 +31,15 @@ The main class for managing WebRTC connections.
 ### Constructor
 
 ```typescript
-new WebRtcManager(factory: WebRtcFactory, config?: WebRtcManagerConfig)
+new WebRtcManager<TContext = unknown>(factory: WebRtcFactory, config?: WebRtcManagerConfig)
 ```
 
+**Type Parameters:**
+
+| Name | Default | Description |
+|------|---------|-------------|
+| TContext | `unknown` | Type for the `context` property |
+
 **Parameters:**
 
 | Name | Type | Required | Description |
@@ -123,6 +129,33 @@ Returns the underlying RTCPeerConnection, or `null` if not initialized.
 
 ---
 
+#### context
+
+```typescript
+context: TContext | null
+```
+
+User-defined context object for storing arbitrary data associated with this manager. The class accepts an optional generic type parameter for type-safe context access.
+
+**Type Parameter:** `TContext` - The type of the context object (default: `unknown`)
+
+**Default:** `null`
+
+**Example:**
+
+```typescript
+// With type parameter for full type safety:
+const manager = new WebRtcManager<{ audioStream: MediaStream; sessionId: string }>(factory);
+manager.context = { audioStream: myStream, sessionId: '123' };
+manager.context.audioStream; // typed as MediaStream
+
+// Without type parameter (backwards compatible):
+const manager = new WebRtcManager(factory);
+manager.context = { anything: 'goes' };
+```
+
+---
+
 ### Lifecycle Methods
 
 #### initialize()
@@ -759,6 +792,9 @@ interface WebRtcManagerConfig {
   /** Initial reconnection delay in ms (doubles each attempt). Default: 1000 */
   reconnectDelay?: number;
 
+  /** Timeout in ms for full reconnection to reach connected state. Default: 30000 */
+  fullReconnectTimeout?: number;
+
   /** Callback to control whether reconnection should proceed */
   shouldReconnect?: (context: {
     attempt: number;
@@ -942,19 +978,24 @@ When `autoReconnect: true`:
 2. **Attempts 3+:** Full reconnection (new peer connection)
 3. **Backoff:** `reconnectDelay * 2^(attempt-1)` milliseconds
 
-For "full" strategy reconnections, listen for the `reconnecting` event and re-perform signaling:
+#### Full Reconnection and Signaling
+
+**Important:** For "full" strategy reconnections, the manager creates a new peer connection but **cannot automatically complete the signaling handshake**. You must listen for the `reconnecting` event and re-perform signaling when `strategy === 'full'`:
 
 ```typescript
-manager.on('reconnecting', ({ attempt, strategy }) => {
+manager.on('reconnecting', async ({ attempt, strategy }) => {
   if (strategy === 'full') {
     // Re-do offer/answer exchange
     const offer = await manager.createOffer();
     await manager.setLocalDescription(offer);
     sendToRemote(offer);
   }
+  // For 'ice-restart', the manager handles it automatically
 });
 ```
 
+If the connection doesn't reach `CONNECTED` state within `fullReconnectTimeout` (default: 30 seconds), it's treated as a failed attempt and the next reconnection attempt begins. When all attempts are exhausted, `EVENT_RECONNECT_FAILED` is emitted.
+
 ### Conditional Reconnection
 
 Use the `shouldReconnect` callback to suppress reconnection when the peer disconnected intentionally:

package/README.md

@@ -38,9 +38,11 @@ The manager doesn't handle the signaling transport layer - you're responsible fo
 ### Constructor
 
 ```typescript
-const manager = new WebRtcManager(factory, config);
+const manager = new WebRtcManager<TContext>(factory, config);
 ```
 
+- `TContext`: Optional type parameter for the `context` property (default: `unknown`)
+
 - `factory`: Object implementing `WebRtcFactory` interface (provides `createPeerConnection`, `getUserMedia`, `enumerateDevices`)
 - `config`: Optional configuration object
 
@@ -51,6 +53,7 @@ const manager = new WebRtcManager(factory, config);
 - `autoReconnect`: Enable automatic reconnection (default: false)
 - `maxReconnectAttempts`: Max reconnection attempts (default: 5)
 - `reconnectDelay`: Initial reconnection delay in ms (default: 1000)
+- `fullReconnectTimeout`: Timeout in ms for full reconnection to succeed (default: 30000)
 - `shouldReconnect`: Callback to control whether reconnection should proceed (see below)
 - `debug`: Enable debug logging (default: false)
 - `logger`: Custom logger instance implementing `Logger` interface (default: console)
@@ -63,6 +66,7 @@ manager.localStream           // MediaStream | null
 manager.remoteStream          // MediaStream | null
 manager.dataChannels          // ReadonlyMap<string, RTCDataChannel>
 manager.peerConnection        // RTCPeerConnection | null
+manager.context               // TContext | null - user-defined data
 ```
 
 ### Lifecycle Methods
@@ -161,6 +165,39 @@ The callback receives:
 - `maxAttempts`: Configured maximum attempts
 - `strategy`: `"ice-restart"` (attempts 1-2) or `"full"` (attempts 3+)
 
+### Reconnection Strategies
+
+The manager uses two reconnection strategies with exponential backoff:
+
+1. **ICE Restart** (attempts 1-2): Lightweight reconnection that keeps the existing peer connection and restarts ICE negotiation. Works when the network path changed but the remote peer is still available.
+
+2. **Full Reconnection** (attempts 3+): Creates a completely new peer connection. This is necessary when ICE restart fails, but **requires consumer action** to complete the signaling handshake.
+
+#### Handling Full Reconnection
+
+When a full reconnection is triggered, the manager will:
+1. Clean up the old peer connection
+2. Create a new peer connection
+3. Emit `EVENT_RECONNECTING` with `strategy: 'full'`
+
+**Important:** The manager cannot automatically complete the signaling handshake for full reconnections. You must listen for the `reconnecting` event and re-establish signaling when the strategy is `'full'`:
+
+```typescript
+manager.on(WebRtcManager.EVENT_RECONNECTING, async ({ attempt, strategy }) => {
+  console.log(`Reconnecting (attempt ${attempt}, strategy: ${strategy})`);
+
+  if (strategy === 'full') {
+    // Re-do the signaling handshake
+    const offer = await manager.createOffer();
+    await manager.setLocalDescription(offer);
+    signalingChannel.send({ type: 'offer', offer });
+  }
+  // For 'ice-restart', the manager handles it automatically
+});
+```
+
+If the full reconnection doesn't reach `CONNECTED` state within `fullReconnectTimeout` (default: 30 seconds), it's treated as a failed attempt and the next reconnection attempt begins (or `EVENT_RECONNECT_FAILED` is emitted if max attempts reached).
+
 ## Examples
 
 ### Basic Usage (Vanilla JavaScript)
@@ -422,24 +459,31 @@ Mock-based tests for the manager's logic and state transitions:
 deno task test
 ```
 
-### Browser Integration Tests
+### Interactive Example
 
-Real peer-to-peer connection tests running in a browser environment:
+The `example/` directory contains a working demo of two peers communicating via WebRTC data channels:
 
 ```bash
-deno task test:browser
+# Build the example bundle
+deno task example:build
+
+# Serve the example directory
+cd example && deno run -A jsr:@std/http/file-server
 ```
 
-This builds the test bundle and starts a local server. Open the provided URL in your browser to run the tests interactively.
+Then open `http://localhost:8000/` in your browser.
 
-The browser tests verify:
-- Actual P2P connections between peers
-- Data channel message exchange
-- ICE candidate exchange
-- Connection state transitions
-- Resource cleanup
+**Structure:**
+- `index.html` - Parent page with two side-by-side iframes, acts as signaling relay via `postMessage`
+- `peer1.html` - The "offerer" peer (click "Connect" to initiate)
+- `peer2.html` - The "answerer" peer (waits for connection)
 
-See [tests/browser/README.md](tests/browser/README.md) for more details.
+This example demonstrates:
+- P2P connection establishment without a signaling server (uses `postMessage` between iframes)
+- SDP offer/answer exchange
+- ICE candidate exchange
+- Data channel creation and message passing
+- State change monitoring
 
 ## License
 

package/dist/types.d.ts

@@ -26,6 +26,8 @@ export interface WebRtcManagerConfig {
     maxReconnectAttempts?: number;
     /** Initial reconnection delay in ms. Doubles with each attempt. Defaults to 1000. */
     reconnectDelay?: number;
+    /** Timeout in ms for full reconnection strategy to reach connected state. Defaults to 30000. */
+    fullReconnectTimeout?: number;
     /**
      * Callback to determine whether reconnection should be attempted.
      * Called before each reconnection attempt when autoReconnect is enabled.

package/dist/webrtc-manager.d.ts

@@ -25,7 +25,7 @@ import { type WebRtcFactory, type WebRtcManagerConfig, WebRtcState, type WebRtcE
  * await manager.setLocalDescription(offer);
  * ```
  */
-export declare class WebRtcManager {
+export declare class WebRtcManager<TContext = unknown> {
     #private;
     /** Event emitted when connection state changes. Payload: {@link WebRtcState} */
     static readonly EVENT_STATE_CHANGE = "state_change";
@@ -51,6 +51,24 @@ export declare class WebRtcManager {
     static readonly EVENT_MICROPHONE_FAILED = "microphone_failed";
     /** Event emitted when an error occurs. Payload: `Error` */
     static readonly EVENT_ERROR = "error";
+    /**
+     * User-defined context object for storing arbitrary data associated with this manager.
+     * Useful for attaching application-specific state (e.g., audio streams, metadata)
+     * without modifying the manager internals.
+     *
+     * @example
+     * ```typescript
+     * // With type parameter for full type safety:
+     * const manager = new WebRtcManager<{ audioStream: MediaStream; sessionId: string }>(factory);
+     * manager.context = { audioStream: myStream, sessionId: '123' };
+     * manager.context.audioStream; // typed as MediaStream
+     *
+     * // Without type parameter (backwards compatible):
+     * const manager = new WebRtcManager(factory);
+     * manager.context = { anything: 'goes' };
+     * ```
+     */
+    context: TContext | null;
     /**
      * Creates a new WebRtcManager instance.
      * @param factory - Factory object providing WebRTC primitives (peer connection, media, devices).

package/dist/webrtc-manager.js

@@ -88,7 +88,26 @@ export class WebRtcManager {
     #remoteStream = null;
     #dataChannels = new Map();
     #reconnectAttempts = 0;
+    /**
+     * User-defined context object for storing arbitrary data associated with this manager.
+     * Useful for attaching application-specific state (e.g., audio streams, metadata)
+     * without modifying the manager internals.
+     *
+     * @example
+     * ```typescript
+     * // With type parameter for full type safety:
+     * const manager = new WebRtcManager<{ audioStream: MediaStream; sessionId: string }>(factory);
+     * manager.context = { audioStream: myStream, sessionId: '123' };
+     * manager.context.audioStream; // typed as MediaStream
+     *
+     * // Without type parameter (backwards compatible):
+     * const manager = new WebRtcManager(factory);
+     * manager.context = { anything: 'goes' };
+     * ```
+     */
+    context = null;
     #reconnectTimer = null;
+    #fullReconnectTimeoutTimer = null;
     #deviceChangeHandler = null;
     /**
      * Creates a new WebRtcManager instance.
@@ -705,8 +724,12 @@ export class WebRtcManager {
             const state = this.#pc.connectionState;
             this.#debug("Connection state changed:", state);
             if (state === "connected") {
-                // Connection successful - reset reconnect attempts
+                // Connection successful - reset reconnect attempts and clear any pending timeout
                 this.#reconnectAttempts = 0;
+                if (this.#fullReconnectTimeoutTimer !== null) {
+                    clearTimeout(this.#fullReconnectTimeoutTimer);
+                    this.#fullReconnectTimeoutTimer = null;
+                }
                 this.#dispatch(WebRtcFsmEvent.CONNECTED);
             }
             else if (state === "failed") {
@@ -747,6 +770,11 @@ export class WebRtcManager {
             clearTimeout(this.#reconnectTimer);
             this.#reconnectTimer = null;
         }
+        // Clear any pending full reconnection timeout
+        if (this.#fullReconnectTimeoutTimer !== null) {
+            clearTimeout(this.#fullReconnectTimeoutTimer);
+            this.#fullReconnectTimeoutTimer = null;
+        }
         // Remove device change listener
         if (this.#deviceChangeHandler) {
             navigator.mediaDevices.removeEventListener("devicechange", this.#deviceChangeHandler);
@@ -857,7 +885,17 @@ export class WebRtcManager {
                     this.#cleanup();
                     this.#dispatch(WebRtcFsmEvent.RESET);
                     await this.connect();
-                    // If successful, onconnectionstatechange will reset attempts
+                    // Start timeout for full reconnection - if connection doesn't succeed
+                    // within the timeout, treat it as a failure
+                    const timeout = this.#config.fullReconnectTimeout ?? 30000;
+                    this.#fullReconnectTimeoutTimer = setTimeout(() => {
+                        this.#fullReconnectTimeoutTimer = null;
+                        // Only trigger failure if still not connected
+                        if (this.state !== WebRtcState.CONNECTED) {
+                            this.#debug("Full reconnection timeout reached, connection not established");
+                            this.#handleConnectionFailure();
+                        }
+                    }, timeout);
                 }
                 catch (e) {
                     this.#logger.error("[WebRtcManager] Reconnection failed:", e);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.1.1",
+	"version": "1.2.1",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",