@marianmeres/webrtc 0.0.2 → 1.0.0

package/README.md

@@ -1,6 +1,7 @@
 # @marianmeres/webrtc
 
-> **Full Disclosure:** This code was written by Claude (Anthropic's AI). The human (that is @marianmeres) just asked nicely, occasionally said "thanks", and went through about 47 iterations of "could you improve this", "what about that", and "make it more Svelte-friendly". To be fair, the prompt engineering was top-notch. So if you find bugs, we'll split the blame 50/50. If it works perfectly, Claude gets 95% of the credit and @marianmeres gets the remaining 5% for excellent taste in asking the right questions. 🤖
+[![NPM Version](https://img.shields.io/npm/v/@marianmeres/webrtc)](https://www.npmjs.com/package/@marianmeres/webrtc)
+[![JSR Version](https://jsr.io/badges/@marianmeres/webrtc)](https://jsr.io/@marianmeres/webrtc)
 
 A lightweight, framework-agnostic WebRTC manager with state machine-based lifecycle management and event-driven architecture.
 
@@ -366,6 +367,10 @@ await connection.createOffer();
 connection.sendMessage('Hello!');
 ```
 
+## API Reference
+
+For complete API documentation, see [API.md](API.md).
+
 ## State Machine
 
 The manager uses a finite state machine with the following states:

package/dist/webrtc-manager.d.ts

@@ -1,18 +1,61 @@
 import { type WebRtcFactory, type WebRtcManagerConfig, WebRtcState, type WebRtcEvents } from "./types.js";
+/**
+ * WebRTC connection manager with FSM-based lifecycle and event-driven architecture.
+ *
+ * Provides a high-level API for managing WebRTC peer connections, audio streams,
+ * and data channels. The manager uses a finite state machine to handle connection
+ * lifecycle and emits events for all state changes and important occurrences.
+ *
+ * @example
+ * ```typescript
+ * const factory = {
+ *   createPeerConnection: (config) => new RTCPeerConnection(config),
+ *   getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
+ *   enumerateDevices: () => navigator.mediaDevices.enumerateDevices(),
+ * };
+ *
+ * const manager = new WebRtcManager(factory, {
+ *   peerConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
+ *   enableMicrophone: true,
+ * });
+ *
+ * await manager.initialize();
+ * await manager.connect();
+ * const offer = await manager.createOffer();
+ * await manager.setLocalDescription(offer);
+ * ```
+ */
 export declare class WebRtcManager {
     #private;
+    /** Event emitted when connection state changes. Payload: {@link WebRtcState} */
     static readonly EVENT_STATE_CHANGE = "state_change";
+    /** Event emitted when local media stream changes. Payload: `MediaStream | null` */
     static readonly EVENT_LOCAL_STREAM = "local_stream";
+    /** Event emitted when remote media stream is received. Payload: `MediaStream | null` */
     static readonly EVENT_REMOTE_STREAM = "remote_stream";
+    /** Event emitted when a data channel opens. Payload: `RTCDataChannel` */
     static readonly EVENT_DATA_CHANNEL_OPEN = "data_channel_open";
+    /** Event emitted when a data channel receives a message. Payload: `{ channel: RTCDataChannel; data: any }` */
     static readonly EVENT_DATA_CHANNEL_MESSAGE = "data_channel_message";
+    /** Event emitted when a data channel closes. Payload: `RTCDataChannel` */
     static readonly EVENT_DATA_CHANNEL_CLOSE = "data_channel_close";
+    /** Event emitted when an ICE candidate is generated. Payload: `RTCIceCandidate | null` */
     static readonly EVENT_ICE_CANDIDATE = "ice_candidate";
+    /** Event emitted when reconnection is attempted. Payload: `{ attempt: number; strategy: "ice-restart" | "full" }` */
     static readonly EVENT_RECONNECTING = "reconnecting";
+    /** Event emitted when all reconnection attempts fail. Payload: `{ attempts: number }` */
     static readonly EVENT_RECONNECT_FAILED = "reconnect_failed";
+    /** Event emitted when audio devices change. Payload: `MediaDeviceInfo[]` */
     static readonly EVENT_DEVICE_CHANGED = "device_changed";
+    /** Event emitted when microphone access fails. Payload: `{ error?: any; reason?: string }` */
     static readonly EVENT_MICROPHONE_FAILED = "microphone_failed";
+    /** Event emitted when an error occurs. Payload: `Error` */
     static readonly EVENT_ERROR = "error";
+    /**
+     * Creates a new WebRtcManager instance.
+     * @param factory - Factory object providing WebRTC primitives (peer connection, media, devices).
+     * @param config - Optional configuration for the manager.
+     */
     constructor(factory: WebRtcFactory, config?: WebRtcManagerConfig);
     /** Returns the current state of the WebRTC connection. */
     get state(): WebRtcState;
@@ -28,6 +71,8 @@ export declare class WebRtcManager {
     toMermaid(): string;
     /**
      * Subscribe to a specific WebRTC event.
+     * @param event - The event name to subscribe to (e.g., "state_change", "ice_candidate").
+     * @param handler - Callback function that receives the event data.
      * @returns Unsubscribe function to remove the event listener.
      */
     on(event: keyof WebRtcEvents, handler: (data: any) => void): () => void;

package/dist/webrtc-manager.js

@@ -1,19 +1,56 @@
 import { FSM } from "@marianmeres/fsm";
 import { PubSub } from "@marianmeres/pubsub";
 import { WebRtcState, WebRtcFsmEvent, } from "./types.js";
+/**
+ * WebRTC connection manager with FSM-based lifecycle and event-driven architecture.
+ *
+ * Provides a high-level API for managing WebRTC peer connections, audio streams,
+ * and data channels. The manager uses a finite state machine to handle connection
+ * lifecycle and emits events for all state changes and important occurrences.
+ *
+ * @example
+ * ```typescript
+ * const factory = {
+ *   createPeerConnection: (config) => new RTCPeerConnection(config),
+ *   getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
+ *   enumerateDevices: () => navigator.mediaDevices.enumerateDevices(),
+ * };
+ *
+ * const manager = new WebRtcManager(factory, {
+ *   peerConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
+ *   enableMicrophone: true,
+ * });
+ *
+ * await manager.initialize();
+ * await manager.connect();
+ * const offer = await manager.createOffer();
+ * await manager.setLocalDescription(offer);
+ * ```
+ */
 export class WebRtcManager {
-    // Event name constants
+    /** Event emitted when connection state changes. Payload: {@link WebRtcState} */
     static EVENT_STATE_CHANGE = "state_change";
+    /** Event emitted when local media stream changes. Payload: `MediaStream | null` */
     static EVENT_LOCAL_STREAM = "local_stream";
+    /** Event emitted when remote media stream is received. Payload: `MediaStream | null` */
     static EVENT_REMOTE_STREAM = "remote_stream";
+    /** Event emitted when a data channel opens. Payload: `RTCDataChannel` */
     static EVENT_DATA_CHANNEL_OPEN = "data_channel_open";
+    /** Event emitted when a data channel receives a message. Payload: `{ channel: RTCDataChannel; data: any }` */
     static EVENT_DATA_CHANNEL_MESSAGE = "data_channel_message";
+    /** Event emitted when a data channel closes. Payload: `RTCDataChannel` */
     static EVENT_DATA_CHANNEL_CLOSE = "data_channel_close";
+    /** Event emitted when an ICE candidate is generated. Payload: `RTCIceCandidate | null` */
     static EVENT_ICE_CANDIDATE = "ice_candidate";
+    /** Event emitted when reconnection is attempted. Payload: `{ attempt: number; strategy: "ice-restart" | "full" }` */
     static EVENT_RECONNECTING = "reconnecting";
+    /** Event emitted when all reconnection attempts fail. Payload: `{ attempts: number }` */
     static EVENT_RECONNECT_FAILED = "reconnect_failed";
+    /** Event emitted when audio devices change. Payload: `MediaDeviceInfo[]` */
     static EVENT_DEVICE_CHANGED = "device_changed";
+    /** Event emitted when microphone access fails. Payload: `{ error?: any; reason?: string }` */
     static EVENT_MICROPHONE_FAILED = "microphone_failed";
+    /** Event emitted when an error occurs. Payload: `Error` */
     static EVENT_ERROR = "error";
     #fsm;
     #pubsub;
@@ -26,6 +63,11 @@ export class WebRtcManager {
     #reconnectAttempts = 0;
     #reconnectTimer = null;
     #deviceChangeHandler = null;
+    /**
+     * Creates a new WebRtcManager instance.
+     * @param factory - Factory object providing WebRTC primitives (peer connection, media, devices).
+     * @param config - Optional configuration for the manager.
+     */
     constructor(factory, config = {}) {
         this.#factory = factory;
         this.#config = config;
@@ -103,6 +145,8 @@ export class WebRtcManager {
     }
     /**
      * Subscribe to a specific WebRTC event.
+     * @param event - The event name to subscribe to (e.g., "state_change", "ice_candidate").
+     * @param handler - Callback function that receives the event data.
      * @returns Unsubscribe function to remove the event listener.
      */
     on(event, handler) {

package/llm.txt

@@ -0,0 +1,364 @@
+# @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}
+```

package/package.json

@@ -1,20 +1,20 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "0.0.2",
+	"version": "1.0.0",
 	"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"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/marianmeres/webrtc.git"
 	},
 	"bugs": {
 		"url": "https://github.com/marianmeres/webrtc/issues"
-	},
-	"dependencies": {
-		"@marianmeres/fsm": "^2.3.0",
-		"@marianmeres/pubsub": "^2.3.0"
 	}
-}
+}