@marianmeres/webrtc 1.0.0 → 1.0.2

package/AGENTS.md

@@ -117,6 +117,21 @@ ERROR         --RESET-->       IDLE
 new WebRtcManager(factory: WebRtcFactory, config?: WebRtcManagerConfig)
 ```
 
+### Logger Interface
+
+Console-compatible logger interface for custom logging implementations.
+
+```typescript
+interface Logger {
+  debug: (...args: any[]) => string;
+  log: (...args: any[]) => string;
+  warn: (...args: any[]) => string;
+  error: (...args: any[]) => string;
+}
+```
+
+Each method returns a string representation of the first argument, enabling patterns like `throw new Error(logger.error("msg"))`.
+
 ### WebRtcFactory Interface
 
 ```typescript
@@ -138,6 +153,7 @@ interface WebRtcManagerConfig {
   maxReconnectAttempts?: number;      // Default: 5
   reconnectDelay?: number;            // Default: 1000ms
   debug?: boolean;                    // Default: false
+  logger?: Logger;                    // Custom logger, falls back to console
 }
 ```
 

package/API.md

@@ -681,6 +681,36 @@ console.log(manager.toMermaid());
 
 ## Types
 
+### Logger
+
+Console-compatible logger interface for custom logging implementations.
+
+```typescript
+interface Logger {
+  debug: (...args: any[]) => string;
+  log: (...args: any[]) => string;
+  warn: (...args: any[]) => string;
+  error: (...args: any[]) => string;
+}
+```
+
+Each method accepts variadic arguments and returns a string representation of the first argument. This enables patterns like `throw new Error(logger.error("msg"))`.
+
+**Example Custom Logger:**
+
+```typescript
+import { clog } from '@marianmeres/clog';
+
+const logger = clog('WebRTC');
+
+const manager = new WebRtcManager(factory, {
+  debug: true,
+  logger: logger,
+});
+```
+
+---
+
 ### WebRtcFactory
 
 Interface for dependency injection of WebRTC primitives.
@@ -731,6 +761,9 @@ interface WebRtcManagerConfig {
 
   /** Enable debug logging. Default: false */
   debug?: boolean;
+
+  /** Custom logger instance. If not provided, falls back to console. */
+  logger?: Logger;
 }
 ```
 

package/README.md

@@ -52,6 +52,7 @@ const manager = new WebRtcManager(factory, config);
 - `maxReconnectAttempts`: Max reconnection attempts (default: 5)
 - `reconnectDelay`: Initial reconnection delay in ms (default: 1000)
 - `debug`: Enable debug logging (default: false)
+- `logger`: Custom logger instance implementing `Logger` interface (default: console)
 
 ### State and Properties
 

package/dist/types.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Console-compatible logger interface.
+ * Each method accepts variadic arguments and returns a string representation of the first argument.
+ * This enables patterns like `throw new Error(logger.error("msg"))`.
+ */
+export interface Logger {
+    debug: (...args: any[]) => string;
+    log: (...args: any[]) => string;
+    warn: (...args: any[]) => string;
+    error: (...args: any[]) => string;
+}
 export interface WebRtcManagerConfig {
     /** Initial peer configuration (ICE servers, etc.) */
     peerConfig?: RTCConfiguration;
@@ -11,8 +22,10 @@ export interface WebRtcManagerConfig {
     maxReconnectAttempts?: number;
     /** Initial reconnection delay in ms. Doubles with each attempt. Defaults to 1000. */
     reconnectDelay?: number;
-    /** Debug mode for logging */
+    /** Enable debug logging. Defaults to false. */
     debug?: boolean;
+    /** Custom logger instance. If not provided, falls back to console. */
+    logger?: Logger;
 }
 export interface WebRtcFactory {
     createPeerConnection(config?: RTCConfiguration): RTCPeerConnection;

package/dist/webrtc-manager.js

@@ -1,6 +1,28 @@
 import { FSM } from "@marianmeres/fsm";
 import { PubSub } from "@marianmeres/pubsub";
 import { WebRtcState, WebRtcFsmEvent, } from "./types.js";
+/**
+ * Default console-based logger that wraps console methods to satisfy the Logger interface.
+ * Returns string representation of the first argument for chaining.
+ */
+const createDefaultLogger = () => ({
+    debug: (...args) => {
+        console.debug(...args);
+        return String(args[0] ?? "");
+    },
+    log: (...args) => {
+        console.log(...args);
+        return String(args[0] ?? "");
+    },
+    warn: (...args) => {
+        console.warn(...args);
+        return String(args[0] ?? "");
+    },
+    error: (...args) => {
+        console.error(...args);
+        return String(args[0] ?? "");
+    },
+});
 /**
  * WebRTC connection manager with FSM-based lifecycle and event-driven architecture.
  *
@@ -57,6 +79,7 @@ export class WebRtcManager {
     #pc = null;
     #factory;
     #config;
+    #logger;
     #localStream = null;
     #remoteStream = null;
     #dataChannels = new Map();
@@ -71,6 +94,7 @@ export class WebRtcManager {
     constructor(factory, config = {}) {
         this.#factory = factory;
         this.#config = config;
+        this.#logger = config.logger ?? createDefaultLogger();
         this.#pubsub = new PubSub();
         // Initialize FSM
         this.#fsm = new FSM({
@@ -193,7 +217,7 @@ export class WebRtcManager {
             return devices.filter((d) => d.kind === "audioinput");
         }
         catch (e) {
-            console.error("Failed to enumerate devices:", e);
+            this.#logger.error("[WebRtcManager] Failed to enumerate devices:", e);
             return [];
         }
     }
@@ -204,7 +228,7 @@ export class WebRtcManager {
      */
     async switchMicrophone(deviceId) {
         if (!this.#pc || !this.#localStream) {
-            console.error("Cannot switch microphone: not initialized or no active stream");
+            this.#logger.error("[WebRtcManager] Cannot switch microphone: not initialized or no active stream");
             return false;
         }
         try {
@@ -240,7 +264,7 @@ export class WebRtcManager {
             return true;
         }
         catch (e) {
-            console.error("Failed to switch microphone:", e);
+            this.#logger.error("[WebRtcManager] Failed to switch microphone:", e);
             this.#error(e);
             return false;
         }
@@ -250,15 +274,20 @@ export class WebRtcManager {
      * Must be called before creating offers or answers. Can only be called from IDLE state.
      */
     async initialize() {
-        if (this.state !== WebRtcState.IDLE)
+        if (this.state !== WebRtcState.IDLE) {
+            this.#debug("initialize() called but state is not IDLE:", this.state);
             return;
+        }
+        this.#debug("Initializing...");
         this.#dispatch(WebRtcFsmEvent.INIT);
         try {
             this.#pc = this.#factory.createPeerConnection(this.#config.peerConfig);
+            this.#debug("Peer connection created");
             this.#setupPcListeners();
             // Setup device change detection now that we have a connection
             this.#setupDeviceChangeListener();
             if (this.#config.enableMicrophone) {
+                this.#debug("Enabling microphone (config enabled)");
                 const success = await this.enableMicrophone(true);
                 if (!success) {
                     this.#pubsub.publish(WebRtcManager.EVENT_MICROPHONE_FAILED, {
@@ -270,10 +299,13 @@ export class WebRtcManager {
                 // 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.#debug("Added recvonly audio transceiver");
             }
             if (this.#config.dataChannelLabel) {
+                this.#debug("Creating default data channel:", this.#config.dataChannelLabel);
                 this.createDataChannel(this.#config.dataChannelLabel);
             }
+            this.#debug("Initialization complete");
         }
         catch (e) {
             this.#error(e);
@@ -284,12 +316,15 @@ export class WebRtcManager {
      * If disconnected, reinitializes the peer connection.
      */
     async connect() {
+        this.#debug("connect() called, current state:", this.state);
         // Initialize if needed
         if (this.state === WebRtcState.IDLE) {
+            this.#debug("State is IDLE, initializing first");
             await this.initialize();
         }
         // Reinitialize if disconnected (PeerConnection was closed)
         if (this.state === WebRtcState.DISCONNECTED) {
+            this.#debug("State is DISCONNECTED, reinitializing");
             // Clean up old connection
             this.#cleanup();
             // Reset to IDLE and reinitialize
@@ -299,8 +334,11 @@ export class WebRtcManager {
             return;
         }
         if (this.state === WebRtcState.CONNECTED ||
-            this.state === WebRtcState.CONNECTING)
+            this.state === WebRtcState.CONNECTING) {
+            this.#debug("Already connected or connecting, skipping");
             return;
+        }
+        this.#debug("Transitioning to CONNECTING");
         this.#dispatch(WebRtcFsmEvent.CONNECT);
     }
     /**
@@ -309,14 +347,19 @@ export class WebRtcManager {
      * @returns True if successful, false if failed to get user media.
      */
     async enableMicrophone(enable) {
+        this.#debug("enableMicrophone() called:", enable);
         if (enable) {
-            if (this.#localStream)
-                return true; // Already enabled
+            if (this.#localStream) {
+                this.#debug("Microphone already enabled");
+                return true;
+            }
             try {
+                this.#debug("Requesting user media...");
                 const stream = await this.#factory.getUserMedia({
                     audio: true,
                     video: false,
                 });
+                this.#debug("User media obtained, tracks:", stream.getAudioTracks().length);
                 this.#localStream = stream;
                 this.#pubsub.publish(WebRtcManager.EVENT_LOCAL_STREAM, stream);
                 if (this.#pc) {
@@ -329,25 +372,31 @@ export class WebRtcManager {
                         await audioTransceiver.sender.replaceTrack(track);
                         // Update direction to sendrecv
                         audioTransceiver.direction = "sendrecv";
+                        this.#debug("Replaced track in existing transceiver");
                     }
                     else {
                         // Add track normally
                         stream.getTracks().forEach((track) => {
                             this.#pc.addTrack(track, stream);
                         });
+                        this.#debug("Added tracks to peer connection");
                     }
                 }
+                this.#debug("Microphone enabled successfully");
                 return true;
             }
             catch (e) {
-                console.error("Failed to get user media", e);
+                this.#logger.error("[WebRtcManager] Failed to get user media:", e);
                 this.#pubsub.publish(WebRtcManager.EVENT_MICROPHONE_FAILED, { error: e });
                 return false;
             }
         }
         else {
-            if (!this.#localStream)
+            if (!this.#localStream) {
+                this.#debug("Microphone already disabled");
                 return true;
+            }
+            this.#debug("Disabling microphone...");
             this.#localStream.getTracks().forEach((track) => {
                 track.stop();
                 // Remove from PC if needed, or just stop sending
@@ -361,6 +410,7 @@ export class WebRtcManager {
             });
             this.#localStream = null;
             this.#pubsub.publish(WebRtcManager.EVENT_LOCAL_STREAM, null);
+            this.#debug("Microphone disabled");
             return true;
         }
     }
@@ -369,6 +419,7 @@ export class WebRtcManager {
      * Transitions to DISCONNECTED state.
      */
     disconnect() {
+        this.#debug("disconnect() called");
         this.#cleanup();
         this.#dispatch(WebRtcFsmEvent.DISCONNECT);
     }
@@ -377,6 +428,7 @@ export class WebRtcManager {
      * Cleans up all resources and allows reinitialization.
      */
     reset() {
+        this.#debug("reset() called, current state:", this.state);
         this.#cleanup();
         // Reset from any non-IDLE state
         if (this.state !== WebRtcState.IDLE) {
@@ -392,6 +444,7 @@ export class WebRtcManager {
                 this.#dispatch(WebRtcFsmEvent.RESET);
             }
         }
+        this.#debug("Reset complete, state:", this.state);
     }
     /**
      * Creates a new data channel with the specified label.
@@ -401,14 +454,20 @@ export class WebRtcManager {
      * @returns The created data channel, or null if peer connection not initialized.
      */
     createDataChannel(label, options) {
-        if (!this.#pc)
+        this.#debug("createDataChannel() called:", label);
+        if (!this.#pc) {
+            this.#debug("Cannot create data channel: peer connection not initialized");
             return null;
-        if (this.#dataChannels.has(label))
+        }
+        if (this.#dataChannels.has(label)) {
+            this.#debug("Returning existing data channel:", label);
             return this.#dataChannels.get(label);
+        }
         try {
             const dc = this.#pc.createDataChannel(label, options);
             this.#setupDataChannelListeners(dc);
             this.#dataChannels.set(label, dc);
+            this.#debug("Data channel created:", label);
             return dc;
         }
         catch (e) {
@@ -457,10 +516,14 @@ export class WebRtcManager {
      * @returns The offer SDP, or null if peer connection not initialized.
      */
     async createOffer(options) {
-        if (!this.#pc)
+        this.#debug("createOffer() called");
+        if (!this.#pc) {
+            this.#debug("Cannot create offer: peer connection not initialized");
             return null;
+        }
         try {
             const offer = await this.#pc.createOffer(options);
+            this.#debug("Offer created:", offer.type);
             return offer;
         }
         catch (e) {
@@ -474,10 +537,14 @@ export class WebRtcManager {
      * @returns The answer SDP, or null if peer connection not initialized.
      */
     async createAnswer(options) {
-        if (!this.#pc)
+        this.#debug("createAnswer() called");
+        if (!this.#pc) {
+            this.#debug("Cannot create answer: peer connection not initialized");
             return null;
+        }
         try {
             const answer = await this.#pc.createAnswer(options);
+            this.#debug("Answer created:", answer.type);
             return answer;
         }
         catch (e) {
@@ -491,10 +558,14 @@ export class WebRtcManager {
      * @returns True if successful, false otherwise.
      */
     async setLocalDescription(description) {
-        if (!this.#pc)
+        this.#debug("setLocalDescription() called:", description.type);
+        if (!this.#pc) {
+            this.#debug("Cannot set local description: peer connection not initialized");
             return false;
+        }
         try {
             await this.#pc.setLocalDescription(description);
+            this.#debug("Local description set successfully");
             return true;
         }
         catch (e) {
@@ -508,10 +579,14 @@ export class WebRtcManager {
      * @returns True if successful, false otherwise.
      */
     async setRemoteDescription(description) {
-        if (!this.#pc)
+        this.#debug("setRemoteDescription() called:", description.type);
+        if (!this.#pc) {
+            this.#debug("Cannot set remote description: peer connection not initialized");
             return false;
+        }
         try {
             await this.#pc.setRemoteDescription(description);
+            this.#debug("Remote description set successfully");
             return true;
         }
         catch (e) {
@@ -525,11 +600,15 @@ export class WebRtcManager {
      * @returns True if successful, false otherwise.
      */
     async addIceCandidate(candidate) {
-        if (!this.#pc)
+        this.#debug("addIceCandidate() called:", candidate ? "candidate" : "null (end-of-candidates)");
+        if (!this.#pc) {
+            this.#debug("Cannot add ICE candidate: peer connection not initialized");
             return false;
+        }
         try {
             if (candidate) {
                 await this.#pc.addIceCandidate(candidate);
+                this.#debug("ICE candidate added");
             }
             return true;
         }
@@ -544,11 +623,15 @@ export class WebRtcManager {
      * @returns True if successful, false otherwise.
      */
     async iceRestart() {
-        if (!this.#pc)
+        this.#debug("iceRestart() called");
+        if (!this.#pc) {
+            this.#debug("Cannot perform ICE restart: peer connection not initialized");
             return false;
+        }
         try {
             const offer = await this.#pc.createOffer({ iceRestart: true });
             await this.#pc.setLocalDescription(offer);
+            this.#debug("ICE restart initiated");
             return true;
         }
         catch (e) {
@@ -591,24 +674,27 @@ export class WebRtcManager {
         this.#fsm.transition(event);
         const newState = this.#fsm.state;
         if (oldState !== newState) {
+            this.#debug("State transition:", oldState, "->", newState, "(event:", event + ")");
             this.#pubsub.publish(WebRtcManager.EVENT_STATE_CHANGE, newState);
         }
     }
     #debug(...args) {
         if (this.#config.debug) {
-            console.debug("[WebRtcManager]", ...args);
+            this.#logger.debug("[WebRtcManager]", ...args);
         }
     }
     #error(error) {
-        console.error(error);
+        this.#logger.error("[WebRtcManager]", error);
         this.#dispatch(WebRtcFsmEvent.ERROR);
         this.#pubsub.publish(WebRtcManager.EVENT_ERROR, error);
     }
     #setupPcListeners() {
         if (!this.#pc)
             return;
+        this.#debug("Setting up peer connection listeners");
         this.#pc.onconnectionstatechange = () => {
             const state = this.#pc.connectionState;
+            this.#debug("Connection state changed:", state);
             if (state === "connected") {
                 // Connection successful - reset reconnect attempts
                 this.#reconnectAttempts = 0;
@@ -623,6 +709,7 @@ export class WebRtcManager {
             }
         };
         this.#pc.ontrack = (event) => {
+            this.#debug("Remote track received:", event.track.kind);
             if (event.streams && event.streams[0]) {
                 this.#remoteStream = event.streams[0];
                 this.#pubsub.publish(WebRtcManager.EVENT_REMOTE_STREAM, this.#remoteStream);
@@ -630,14 +717,17 @@ export class WebRtcManager {
         };
         this.#pc.ondatachannel = (event) => {
             const dc = event.channel;
+            this.#debug("Remote data channel received:", dc.label);
             this.#setupDataChannelListeners(dc);
             this.#dataChannels.set(dc.label, dc);
         };
         this.#pc.onicecandidate = (event) => {
+            this.#debug("ICE candidate generated:", event.candidate ? "candidate" : "null (gathering complete)");
             this.#pubsub.publish(WebRtcManager.EVENT_ICE_CANDIDATE, event.candidate);
         };
     }
     #cleanup() {
+        this.#debug("Cleanup started");
         // Clear any pending reconnect timers
         if (this.#reconnectTimer !== null) {
             clearTimeout(this.#reconnectTimer);
@@ -649,33 +739,43 @@ export class WebRtcManager {
             this.#deviceChangeHandler = null;
         }
         // Close all data channels
+        const dcCount = this.#dataChannels.size;
         this.#dataChannels.forEach((dc) => {
             if (dc.readyState !== "closed") {
                 dc.close();
             }
         });
         this.#dataChannels.clear();
+        if (dcCount > 0) {
+            this.#debug("Closed", dcCount, "data channel(s)");
+        }
         // Stop local stream tracks
         if (this.#localStream) {
             this.#localStream.getTracks().forEach((track) => track.stop());
             this.#localStream = null;
+            this.#debug("Local stream stopped");
         }
         // Close peer connection
         if (this.#pc) {
             this.#pc.close();
             this.#pc = null;
+            this.#debug("Peer connection closed");
         }
         this.#remoteStream = null;
+        this.#debug("Cleanup complete");
     }
     #handleConnectionFailure() {
+        this.#debug("Handling connection failure");
         this.#dispatch(WebRtcFsmEvent.DISCONNECT);
         // Check if auto-reconnect is enabled
         if (!this.#config.autoReconnect) {
+            this.#debug("Auto-reconnect disabled, not attempting reconnection");
             return;
         }
         const maxAttempts = this.#config.maxReconnectAttempts ?? 5;
         // Check if we've exceeded max attempts
         if (this.#reconnectAttempts >= maxAttempts) {
+            this.#debug("Max reconnection attempts reached:", maxAttempts);
             this.#pubsub.publish(WebRtcManager.EVENT_RECONNECT_FAILED, {
                 attempts: this.#reconnectAttempts,
             });
@@ -692,6 +792,11 @@ export class WebRtcManager {
         const delay = baseDelay * Math.pow(2, this.#reconnectAttempts - 1);
         // Try ICE restart first (attempts 1-2), then full reconnect
         const strategy = this.#reconnectAttempts <= 2 ? "ice-restart" : "full";
+        this.#debug("Attempting reconnection:", {
+            attempt: this.#reconnectAttempts,
+            strategy,
+            delay: delay + "ms",
+        });
         this.#pubsub.publish(WebRtcManager.EVENT_RECONNECTING, {
             attempt: this.#reconnectAttempts,
             strategy,
@@ -718,7 +823,7 @@ export class WebRtcManager {
                     // If successful, onconnectionstatechange will reset attempts
                 }
                 catch (e) {
-                    console.error("Reconnection failed:", e);
+                    this.#logger.error("[WebRtcManager] Reconnection failed:", e);
                     this.#handleConnectionFailure();
                 }
             }
@@ -739,7 +844,7 @@ export class WebRtcManager {
                 this.#pubsub.publish(WebRtcManager.EVENT_DEVICE_CHANGED, devices);
             }
             catch (e) {
-                console.error("Error handling device change:", e);
+                this.#logger.error("[WebRtcManager] Error handling device change:", e);
             }
         };
         navigator.mediaDevices.addEventListener("devicechange", this.#deviceChangeHandler);
@@ -762,7 +867,7 @@ export class WebRtcManager {
             // Ignore "User-Initiated Abort" errors which occur during intentional close()
             const isUserAbort = error?.error?.message?.includes("User-Initiated Abort");
             if (!isUserAbort) {
-                console.error("Data Channel Error:", error);
+                this.#logger.error("[WebRtcManager] Data channel error:", error);
                 this.#pubsub.publish(WebRtcManager.EVENT_ERROR, error);
             }
         };

package/package.json

@@ -1,14 +1,14 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/fsm": "^2.5.4",
-		"@marianmeres/pubsub": "^2.4.2"
+		"@marianmeres/fsm": "^2.6.4",
+		"@marianmeres/pubsub": "^2.4.3"
 	},
 	"repository": {
 		"type": "git",

package/llm.txt

@@ -1,364 +0,0 @@
-# @marianmeres/webrtc - LLM Knowledge Base
-
-## Package Identity
-
-name: @marianmeres/webrtc
-version: 0.0.2
-license: MIT
-author: Marian Meres
-repository: https://github.com/marianmeres/webrtc
-runtime: Deno (source), Node.js/Browser (distribution)
-type: WebRTC connection management library
-
-## Purpose
-
-A lightweight, framework-agnostic WebRTC manager providing:
-- Finite State Machine (FSM) based lifecycle management
-- Event-driven architecture with PubSub pattern
-- Svelte store compatibility
-- Audio device management (microphone switching)
-- Data channel support
-- Auto-reconnection with exponential backoff
-- Full TypeScript type safety
-
-## Architecture Overview
-
-```
-WebRtcManager
-├── FSM (@marianmeres/fsm) - State transitions
-├── PubSub (@marianmeres/pubsub) - Event subscriptions
-├── RTCPeerConnection - WebRTC connection (via factory)
-├── MediaStream (local/remote) - Audio streams
-└── DataChannels Map - RTCDataChannel instances
-```
-
-## Dependencies
-
-Production:
-- @marianmeres/fsm: ^2.3.0 (state machine)
-- @marianmeres/pubsub: ^2.3.0 (event system)
-
-Development (Deno):
-- @std/assert: testing
-- @std/fs: file operations
-- @std/path: path utilities
-
-## File Structure
-
-```
-src/
-├── mod.ts              # Entry point, re-exports all public APIs
-├── types.ts            # Type definitions (interfaces, enums)
-└── webrtc-manager.ts   # Main WebRtcManager class (839 lines)
-
-tests/
-├── mocks.ts                    # Mock WebRtcFactory for testing
-├── webrtc-manager.test.ts      # Deno unit tests
-└── browser/
-    ├── p2p-tests.ts            # Browser integration tests
-    └── README.md               # Browser test documentation
-
-example/
-├── peer.ts             # Two-peer example with localStorage signaling
-├── p2p.ts              # Single-page P2P example
-├── audio-peer.ts       # Audio testing implementation
-└── main.ts             # Signaling server example
-
-scripts/
-├── build-npm.ts        # npm distribution build
-├── build-example.ts    # Example bundling
-├── build-browser-tests.ts
-├── serve-browser-tests.ts
-└── signaling-server.ts
-```
-
-## State Machine
-
-### States (WebRtcState enum)
-
-| State | Description | Valid Transitions |
-|-------|-------------|-------------------|
-| IDLE | Initial state, no resources | → INITIALIZING |
-| INITIALIZING | Creating peer connection | → CONNECTING, ERROR |
-| CONNECTING | Performing SDP exchange | → CONNECTED, DISCONNECTED, ERROR |
-| CONNECTED | Connection established | → DISCONNECTED, ERROR |
-| RECONNECTING | Auto-reconnection in progress | → CONNECTING, DISCONNECTED, IDLE |
-| DISCONNECTED | Closed but recoverable | → CONNECTING, RECONNECTING, IDLE |
-| ERROR | Error occurred, must reset | → IDLE |
-
-### Events (WebRtcFsmEvent enum)
-
-| Event | Description |
-|-------|-------------|
-| INIT ("initialize") | Start initialization |
-| CONNECT ("connect") | Begin connection |
-| CONNECTED ("connected") | Connection succeeded |
-| RECONNECTING ("reconnecting") | Start reconnection |
-| DISCONNECT ("disconnect") | Close connection |
-| ERROR ("error") | Error occurred |
-| RESET ("reset") | Return to IDLE |
-
-### State Transition Diagram
-
-```
-IDLE --INIT--> INITIALIZING --CONNECT--> CONNECTING --CONNECTED--> CONNECTED
-                    |                        |                         |
-                    v                        v                         v
-                  ERROR <-----------------ERROR<----------------------ERROR
-                    |
-                    v
-                  IDLE (via RESET)
-
-CONNECTED --DISCONNECT--> DISCONNECTED --RESET--> IDLE
-                               |
-                               v
-                          RECONNECTING --CONNECT--> CONNECTING
-```
-
-## Public API
-
-### Constructor
-
-```typescript
-new WebRtcManager(factory: WebRtcFactory, config?: WebRtcManagerConfig)
-```
-
-### WebRtcFactory Interface
-
-```typescript
-interface WebRtcFactory {
-  createPeerConnection(config?: RTCConfiguration): RTCPeerConnection;
-  getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
-  enumerateDevices(): Promise<MediaDeviceInfo[]>;
-}
-```
-
-Browser implementation:
-```typescript
-const factory = {
-  createPeerConnection: (config) => new RTCPeerConnection(config),
-  getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
-  enumerateDevices: () => navigator.mediaDevices.enumerateDevices(),
-};
-```
-
-### WebRtcManagerConfig Interface
-
-```typescript
-interface WebRtcManagerConfig {
-  peerConfig?: RTCConfiguration;      // ICE servers, certificates
-  enableMicrophone?: boolean;         // Enable mic on init (default: false)
-  dataChannelLabel?: string;          // Auto-create data channel
-  autoReconnect?: boolean;            // Enable auto-reconnect (default: false)
-  maxReconnectAttempts?: number;      // Max attempts (default: 5)
-  reconnectDelay?: number;            // Initial delay ms (default: 1000)
-  debug?: boolean;                    // Enable logging (default: false)
-}
-```
-
-### Properties (Getters)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| state | WebRtcState | Current FSM state |
-| localStream | MediaStream \| null | Local audio stream |
-| remoteStream | MediaStream \| null | Remote audio stream |
-| dataChannels | ReadonlyMap<string, RTCDataChannel> | Active data channels |
-| peerConnection | RTCPeerConnection \| null | Underlying connection |
-
-### Lifecycle Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| initialize | `(): Promise<void>` | Create peer connection, setup tracks |
-| connect | `(): Promise<void>` | Transition to CONNECTING (auto-initializes) |
-| disconnect | `(): void` | Close connection, cleanup resources |
-| reset | `(): void` | Reset to IDLE from any state |
-
-### Audio Methods
-
-| Method | Signature | Returns | Description |
-|--------|-----------|---------|-------------|
-| enableMicrophone | `(enable: boolean): Promise<boolean>` | success | Enable/disable microphone |
-| switchMicrophone | `(deviceId: string): Promise<boolean>` | success | Switch audio input device |
-| getAudioInputDevices | `(): Promise<MediaDeviceInfo[]>` | devices | List audio inputs |
-
-### Data Channel Methods
-
-| Method | Signature | Returns | Description |
-|--------|-----------|---------|-------------|
-| createDataChannel | `(label: string, options?: RTCDataChannelInit): RTCDataChannel \| null` | channel | Create/get data channel |
-| getDataChannel | `(label: string): RTCDataChannel \| undefined` | channel | Get existing channel |
-| sendData | `(label: string, data: string \| Blob \| ArrayBuffer \| ArrayBufferView): boolean` | success | Send through channel |
-
-### Signaling Methods
-
-| Method | Signature | Returns | Description |
-|--------|-----------|---------|-------------|
-| createOffer | `(options?: RTCOfferOptions): Promise<RTCSessionDescriptionInit \| null>` | offer | Create SDP offer |
-| createAnswer | `(options?: RTCAnswerOptions): Promise<RTCSessionDescriptionInit \| null>` | answer | Create SDP answer |
-| setLocalDescription | `(description: RTCSessionDescriptionInit): Promise<boolean>` | success | Set local SDP |
-| setRemoteDescription | `(description: RTCSessionDescriptionInit): Promise<boolean>` | success | Set remote SDP |
-| addIceCandidate | `(candidate: RTCIceCandidateInit \| null): Promise<boolean>` | success | Add ICE candidate |
-| iceRestart | `(): Promise<boolean>` | success | Perform ICE restart |
-| getLocalDescription | `(): RTCSessionDescription \| null` | description | Get local SDP |
-| getRemoteDescription | `(): RTCSessionDescription \| null` | description | Get remote SDP |
-| getStats | `(): Promise<RTCStatsReport \| null>` | stats | Get connection statistics |
-
-### Event Subscription Methods
-
-| Method | Signature | Returns | Description |
-|--------|-----------|---------|-------------|
-| on | `<K extends keyof WebRtcEvents>(event: K, handler: (data: WebRtcEvents[K]) => void): () => void` | unsubscribe | Subscribe to specific event |
-| subscribe | `(handler: (state: OverallState) => void): () => void` | unsubscribe | Subscribe to overall state (Svelte compatible) |
-
-### Utility Methods
-
-| Method | Signature | Returns | Description |
-|--------|-----------|---------|-------------|
-| toMermaid | `(): string` | mermaid | Get FSM as Mermaid diagram |
-
-## Events
-
-### Event Constants (Static)
-
-| 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 |
-
-### WebRtcEvents Interface
-
-```typescript
-interface WebRtcEvents {
-  state_change: WebRtcState;
-  local_stream: MediaStream | null;
-  remote_stream: MediaStream | null;
-  data_channel_open: RTCDataChannel;
-  data_channel_message: { channel: RTCDataChannel; data: any };
-  data_channel_close: RTCDataChannel;
-  ice_candidate: RTCIceCandidate | null;
-  reconnecting: { attempt: number; strategy: "ice-restart" | "full" };
-  reconnect_failed: { attempts: number };
-  device_changed: MediaDeviceInfo[];
-  microphone_failed: { error?: any; reason?: string };
-  error: Error;
-}
-```
-
-## Signaling Flow (User Responsibility)
-
-The library does NOT handle signaling transport. Users must:
-
-1. Create signaling channel (WebSocket, HTTP, localStorage, etc.)
-2. Listen for `ice_candidate` events and send to remote peer
-3. Send offers/answers through signaling channel
-4. Receive remote offers/answers and call setRemoteDescription
-5. Receive remote ICE candidates and call addIceCandidate
-
-### Offer/Answer Flow
-
-```
-Initiator:                          Responder:
-1. initialize()
-2. connect()
-3. createOffer()
-4. setLocalDescription(offer)
-5. [send offer via signaling] ───→  6. initialize()
-                                    7. setRemoteDescription(offer)
-                                    8. createAnswer()
-                                    9. setLocalDescription(answer)
-10. setRemoteDescription(answer) ←── [send answer via signaling]
-11. [exchange ICE candidates] ←───→ [exchange ICE candidates]
-12. CONNECTED                       12. CONNECTED
-```
-
-## Reconnection Strategy
-
-When autoReconnect is enabled:
-
-1. Attempts 1-2: ICE restart (preserves connection, quick recovery)
-2. Attempts 3+: Full reconnection (new peer connection)
-3. Exponential backoff: delay * 2^(attempt-1)
-4. Max attempts configurable (default: 5)
-
-For "full" strategy reconnections, consumers MUST:
-- Listen for `reconnecting` event with strategy="full"
-- Re-perform signaling handshake (create new offer/answer)
-
-## Error Handling Patterns
-
-1. Methods return boolean for success/failure
-2. Critical errors transition to ERROR state
-3. ERROR state requires reset() to recover
-4. EVENT_ERROR emitted for all errors
-5. Specific events: EVENT_MICROPHONE_FAILED, EVENT_RECONNECT_FAILED
-
-## Testing
-
-### Unit Tests (Deno)
-```bash
-deno task test
-```
-
-### Browser Integration Tests
-```bash
-deno task test:browser
-```
-
-## Build Commands
-
-```bash
-deno task npm:build     # Build npm distribution
-deno task npm:publish   # Build and publish to npm
-deno task build:example # Build examples
-deno task serve:example # Run signaling server
-```
-
-## Important Implementation Details
-
-1. subscribe() is Svelte store compatible (immediate callback + updates)
-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)
-6. Private fields use # (true private, not accessible externally)
-
-## Common Usage Patterns
-
-### Minimal P2P Setup
-```typescript
-const manager = new WebRtcManager(factory, { enableMicrophone: true });
-await manager.initialize();
-await manager.connect();
-const offer = await manager.createOffer();
-await manager.setLocalDescription(offer);
-// Send offer, receive answer, exchange ICE candidates...
-```
-
-### With Data Channel
-```typescript
-const manager = new WebRtcManager(factory, { dataChannelLabel: "chat" });
-manager.on("data_channel_message", ({ data }) => console.log(data));
-// After connection...
-manager.sendData("chat", "Hello!");
-```
-
-### Svelte Integration
-```svelte
-<script>
-const manager = new WebRtcManager(factory, config);
-// $manager reactive access to state
-</script>
-{$manager.state}
-```