@unboundcx/video-sdk-client 2.0.0 → 2.0.1

package/VideoMeetingClient.js

@@ -1,10 +1,12 @@
-import { EventEmitter } from './utils/EventEmitter.js';
-import { Logger } from './utils/Logger.js';
-import { ConnectionManager } from './managers/ConnectionManager.js';
-import { MediasoupManager } from './managers/MediasoupManager.js';
-import { LocalMediaManager } from './managers/LocalMediaManager.js';
-import { RemoteMediaManager } from './managers/RemoteMediaManager.js';
-import { StateError, RoomError } from './utils/errors.js';
+import { EventEmitter } from "./utils/EventEmitter.js";
+import { Logger } from "./utils/Logger.js";
+import { ConnectionManager } from "./managers/ConnectionManager.js";
+import { MediasoupManager } from "./managers/MediasoupManager.js";
+import { LocalMediaManager } from "./managers/LocalMediaManager.js";
+import { RemoteMediaManager } from "./managers/RemoteMediaManager.js";
+import { QualityMonitor } from "./managers/QualityMonitor.js";
+import { ConnectionHealthMonitor } from "./managers/ConnectionHealthMonitor.js";
+import { StateError, RoomError } from "./utils/errors.js";
 
 /**
  * Main SDK client for video meeting functionality
@@ -24,1485 +26,1639 @@ import { StateError, RoomError } from './utils/errors.js';
  * });
  */
 export class VideoMeetingClient extends EventEmitter {
-	/**
-	 * @param {Object} options
-	 * @param {string} [options.serverUrl] - WebSocket server URL (optional if using joinFromApiResponse)
-	 * @param {boolean} [options.debug=false] - Enable debug logging
-	 * @param {Object} [options.sdk] - UnboundSDK instance, injected by
-	 *   `sdk.video.createMeetingClient()`. Required for transparent reassignment
-	 *   recovery (calls `sdk.video.joinRoom()`) and for `endSession()` to invoke
-	 *   `sdk.video.endSession()`. Without it, consumers must handle both paths
-	 *   themselves.
-	 */
-	constructor(options = {}) {
-		super();
-
-		this.logger = new Logger('SDK:VideoMeetingClient', options.debug);
-		this.state = 'disconnected'; // disconnected, connecting, connected, waiting-room, in-meeting
-		this.currentRoomId = null;
-		this.joinData = null; // Store video.join() response data
-		this.debug = options.debug;
-		this.isGuest = false;
-		this.inWaitingRoom = false;
-		this.sdk = options.sdk || null;
-
-		// Reassignment recovery state. Attempt window is 60s; cap at 3 attempts.
-		// Backoff schedule: 500ms, 2s, 5s. Counter resets once a connection has
-		// stayed up for >60s (see _onReassignmentStableConnect).
-		this._reassignmentAttempts = []; // timestamps (Date.now()) of recent attempts
-		this._reassignmentInFlight = false;
-		this._reassignmentStableTimer = null;
-		this._lastJoinArgs = null; // args used by consumer to call sdk.video.joinRoom()
-
-		// Managers will be initialized when we have connection info
-		this.connection = null;
-		this.mediasoup = null;
-		this.localMedia = null;
-		this.remoteMedia = null;
-
-		// If serverUrl provided, initialize managers now (old behavior)
-		if (options.serverUrl) {
-			this._initializeManagers(options.serverUrl);
-		}
-
-		this.logger.info('VideoMeetingClient initialized', { hasSdk: !!this.sdk });
-	}
-
-	/**
-	 * Initialize managers with server URL
-	 * @private
-	 * @param {string} serverUrl
-	 * @param {string} [namespace] - Socket.IO namespace path, e.g. `/video`
-	 */
-	_initializeManagers(serverUrl, namespace = null) {
-		this.connection = new ConnectionManager({
-			serverUrl,
-			namespace,
-			debug: this.debug,
-		});
-
-		this.mediasoup = new MediasoupManager({
-			connection: this.connection,
-			debug: this.debug,
-		});
-
-		this.localMedia = new LocalMediaManager({
-			mediasoup: this.mediasoup,
-			debug: this.debug,
-		});
-
-		this.remoteMedia = new RemoteMediaManager({
-			mediasoup: this.mediasoup,
-			connection: this.connection,
-			videoClient: this, // Pass reference to access joinData
-			debug: this.debug,
-		});
-
-		// Proxy manager events to SDK events
-		this._setupEventProxies();
-
-		// When mediasoup detects its transports are stale after a long disconnect,
-		// re-run the room.join flow to get fresh transport options + producer list
-		// from the server. This keeps media working across network blips >30s.
-		this.mediasoup.on('transports:recreated-needed', () => {
-			this._rejoinRoomForTransportRecreation().catch((err) => {
-				this.logger.error('Rejoin for transport recreation failed', err);
-			});
-		});
-	}
-
-	/**
-	 * Setup event proxies from managers to SDK
-	 * @private
-	 */
-	_setupEventProxies() {
-		// Connection events
-		this.connection.on('connected', () => {
-			this._setState('connected');
-			this.emit('connected');
-
-			// On Socket.IO reconnect (not initial connect), check whether the
-			// WebRTC transports died during the disconnect window. If the state
-			// has been bad for >10s, mediasoup will emit transports:recreated-needed.
-			if (this.mediasoup && (this.mediasoup.sendTransport || this.mediasoup.recvTransport)) {
-				this.mediasoup.recreateStaleTransports().catch((err) => {
-					this.logger.error('recreateStaleTransports threw', err);
-				});
-			}
-		});
-
-		this.connection.on('disconnected', (data) => {
-			this._setState('disconnected');
-			this.emit('disconnected', data);
-		});
-
-		this.connection.on('error', (error) => {
-			this.emit('error', error);
-		});
-
-		// Server signaled the assigned pod is stale — re-fetch joinRoom and reconnect.
-		this.connection.on('reassignmentRequired', ({ code }) => {
-			this.logger.warn('Reassignment required', { code });
-			this._handleReassignment(code).catch((err) => {
-				this.logger.error('Reassignment handler threw', err);
-			});
-		});
-
-		// Local media events
-		this.localMedia.on('stream:added', (data) => {
-			this.emit('local-stream:added', data);
-		});
-
-		this.localMedia.on('stream:removed', (data) => {
-			this.emit('local-stream:removed', data);
-		});
-
-		this.localMedia.on('device:changed', (data) => {
-			this.emit('device:changed', data);
-		});
-
-		// Remote media events
-		this.remoteMedia.on('participant:added', (data) => {
-			this.emit('participant:joined', data);
-		});
-
-		this.remoteMedia.on('participant:removed', (data) => {
-			this.emit('participant:left', data);
-		});
-
-		this.remoteMedia.on('participant:updated', (data) => {
-			this.emit('participant:updated', data);
-		});
-
-		this.remoteMedia.on('stream:added', (data) => {
-			this.emit('stream:added', data);
-		});
-
-		this.remoteMedia.on('stream:removed', (data) => {
-			this.emit('stream:removed', data);
-		});
-
-		// Stream consuming events (for retry logic and error handling)
-		this.remoteMedia.on('stream:consuming', (data) => {
-			this.emit('stream:consuming', data);
-		});
-
-		this.remoteMedia.on('stream:consume-failed', (data) => {
-			this.emit('stream:consume-failed', data);
-		});
-
-		// Volume control events
-		this.remoteMedia.on('participant:volume-changed', (data) => {
-			this.emit('participant:volume-changed', data);
-		});
-	}
-
-	/**
-	 * Setup room/participant event listeners
-	 * @private
-	 */
-	_setupRoomEventListeners() {
-		// Room events
-		this.connection.onServerEvent('room.closed', (data) => {
-			this.logger.info('Room closed', data);
-			this._setState('disconnected');
-			this.emit('room:closed', data);
-		});
-
-		this.connection.onServerEvent('room.update', (data) => {
-			this.logger.info('Room updated', data);
-			this.emit('room:updated', data);
-		});
-
-		// Participant events
-		this.connection.onServerEvent('participant.all', (data) => {
-			this.logger.info('All participants', data);
-			this.emit('participants:list', data);
-		});
-
-		this.connection.onServerEvent('participant.leave', (data) => {
-			this.logger.info('Participant left', data);
-			this.emit('participant:left', data);
-		});
-
-		this.connection.onServerEvent('participant.remove', (data) => {
-			this.logger.info('Participant removed', data);
-			this.emit('participant:removed', data);
-		});
-
-		this.connection.onServerEvent('participant.update', (data) => {
-			this.logger.info('Participant updated', data);
-			this.emit('participant:updated', data);
-		});
-
-		// Producer close event (for quality adaptation / reconnect)
-		this.connection.onServerEvent('participant.producer.close', async (data) => {
-			this.logger.info('Producer close requested', data);
-			await this._handleProducerCloseRequest(data);
-		});
-
-		// Waiting room events
-		this.connection.onServerEvent('room.waitingRoom.admit', (data) => {
-			this.logger.info('Admitted from waiting room', data);
-			this.inWaitingRoom = false;
-			this._setState('in-meeting');
-			this.emit('waitingRoom:admitted', data);
-		});
-
-		// Keepalive events
-		this.connection.onServerEvent('keepalive.send', (data) => {
-			this.emit('keepalive:received', data);
-			this.connection.emit('keepalive.ack', data);
-		});
-
-		this.connection.onServerEvent('keepalive.alert', (data) => {
-			this.emit('keepalive:alert', data);
-		});
-	}
-
-	/**
-	 * Connect to the server
-	 * @param {Object|string} auth - Authentication token or auth object
-	 * @returns {Promise<void>}
-	 */
-	async connect(auth = {}) {
-		if (this.state !== 'disconnected') {
-			throw new StateError(
-				'Cannot connect: already connected or connecting',
-				this.state,
-				'disconnected'
-			);
-		}
-
-		this.logger.info('Connecting to server...');
-		this._setState('connecting');
-
-		try {
-			// Normalize auth to object format
-			const authObj = typeof auth === 'string' ? { token: auth } : auth;
-
-			// Connect to server
-			await this.connection.connect(authObj);
-
-			// Load mediasoup device
-			await this.mediasoup.loadDevice();
-
-			this.logger.info('Connected successfully');
-			this._setState('connected');
-
-		} catch (error) {
-			this.logger.error('Connection failed:', error);
-			this._setState('disconnected');
-			throw error;
-		}
-	}
-
-	/**
-	 * Disconnect from server
-	 * @returns {Promise<void>}
-	 */
-	async disconnect() {
-		this.logger.info('Disconnecting...');
-
-		try {
-			// Leave room if in one
-			if (this.state === 'in-room') {
-				await this.leaveRoom();
-			}
-
-			// Clean up managers
-			await this.localMedia.cleanup();
-			await this.remoteMedia.cleanup();
-			await this.mediasoup.cleanup();
-
-			// Disconnect socket
-			await this.connection.disconnect();
-
-			this._setState('disconnected');
-			this.logger.info('Disconnected successfully');
-
-		} catch (error) {
-			this.logger.error('Disconnect error:', error);
-			throw error;
-		}
-	}
-
-	/**
-	 * Join meeting directly from API response (api.video.joinRoom)
-	 * This method extracts server info, connects, and determines if user needs to wait
-	 *
-	 * @param {Object} joinResponse - Response from api.video.joinRoom(room, password, email)
-	 * @param {Object} options - Additional options
-	 * @param {boolean} options.enterWaitingRoom - For guests, enter waiting room (default: auto-detect)
-	 * @returns {Promise<Object>} Join data
-	 *
-	 * @example
-	 * const joinResponse = await api.video.joinRoom('room-123', 'password', 'user@example.com');
-	 * await client.joinFromApiResponse(joinResponse);
-	 *
-	 * // For guests in waiting room:
-	 * client.on('waitingRoom:entered', () => showWaitingRoomUI());
-	 * client.on('waitingRoom:admitted', () => showMeetingUI());
-	 */
-	async joinFromApiResponse(joinResponse, options = {}) {
-		this.logger.info('Joining from API response');
-
-		// Store args used to obtain this response. If a reassignment is required
-		// later, we replay these against sdk.video.joinRoom() to get a fresh
-		// assignment without the consumer having to wire anything up.
-		if (options.joinRoomArgs !== undefined) {
-			this._lastJoinArgs = options.joinRoomArgs;
-		}
-
-		try {
-			const { videoRoom, participant } = joinResponse;
-
-			// Support both the new shape (connectionInfo.socket) and the legacy
-			// shape (top-level server + authorization) during the rollout.
-			// Legacy path is removed once every app1-api replica returns the new
-			// shape in staging/prod.
-			const connectionInfo = joinResponse.connectionInfo;
-			const socketInfo = connectionInfo?.socket;
-			const legacyServer = joinResponse.server;
-
-			let socketUrl;
-			let socketNamespace;
-			let authData;
-			let authorization;
-
-			if (socketInfo?.url) {
-				socketUrl = socketInfo.url;
-				socketNamespace = socketInfo.namespace || '/video';
-				authData = {
-					...socketInfo.auth,
-					roomId: videoRoom.id,
-					participantId: participant.id,
-				};
-				authorization = connectionInfo.authorization || null;
-			} else if (legacyServer?.url && legacyServer?.socketPort) {
-				// Legacy per-pod-ingress path. Remove once centralized signaling
-				// is fully deployed.
-				socketUrl = `https://${legacyServer.url}:${legacyServer.socketPort}`;
-				socketNamespace = null;
-				authorization = joinResponse.authorization;
-				authData = {
-					accountNamespace: authorization?.namespace,
-					roomId: videoRoom.id,
-					participantId: participant.id,
-				};
-			} else {
-				throw new Error('Invalid join response: missing connectionInfo.socket and legacy server info');
-			}
-
-			// Store join data for later use (including reassignment replay)
-			this.joinData = {
-				videoRoom,
-				participant,
-				connectionInfo: connectionInfo || null,
-				server: legacyServer || null,
-				authorization,
-			};
-
-			// Detect if this is a guest (no host privileges)
-			this.isGuest = !participant.isHost && !participant.isModerator;
-
-			this.logger.info('Connecting to video server:', { socketUrl, socketNamespace });
-
-			// Initialize managers if not already done
-			if (!this.connection) {
-				this._initializeManagers(socketUrl, socketNamespace);
-			}
-
-			this._setState('connecting');
-
-			this.logger.info('Connecting with auth (cookie-based):', authData);
-			await this.connection.connect(authData);
-
-			this._setState('connected');
-
-			// Connection succeeded. If it stays up >60s, reset the reassignment
-			// attempt counter so the next reassignment cycle starts fresh.
-			this._armReassignmentStableTimer();
-
-			// Setup remote media listeners and room event listeners
-			this.logger.info('Setting up event listeners');
-			this.remoteMedia._setupServerListeners();
-			this._setupRoomEventListeners();
-
-			// ALWAYS emit room.waitingRoom first to initialize room on video server
-			// The server requires this event to set up the room before any joins
-			this.logger.info('Emitting room.waitingRoom to initialize room on server');
-			this.connection.emit('room.waitingRoom', {});
-
-			// Enter waiting-room state for everyone (hosts and guests)
-			// This allows users to set up their devices while room initializes
-			this.inWaitingRoom = true;
-			this._setState('waiting-room');
-
-			this.logger.info('Entering waiting room - waiting for room to be ready');
-
-			this.emit('waitingRoom:entered', {
-				roomId: videoRoom.id,
-				participant,
-				isHost: participant.isHost,
-				canJoinImmediately: !this.isGuest // Hosts can join once ready, guests need admission
-			});
-
-			// Listen for media.routerCapabilities to know when room is ready
-			this.connection.onServerEvent('media.routerCapabilities', (data) => {
-				this.logger.info('Room is ready - received media.routerCapabilities');
-				this.emit('waitingRoom:ready', {
-					roomId: videoRoom.id,
-					participant
-				});
-			});
-
-			// Return - user must explicitly call joinMeeting() when ready
-			// For hosts: after they click "Join Meeting" button (once room is ready)
-			// For guests: after host admits them (room.waitingRoom.admit event)
-			return {
-				...this.joinData,
-				inWaitingRoom: true
-			};
-
-		} catch (error) {
-			this.logger.error('Failed to join from API response:', error);
-			this._setState('disconnected');
-			throw new RoomError(`Failed to join meeting: ${error.message}`);
-		}
-	}
-
-	/**
-	 * Public method to join meeting from waiting room
-	 * Call this after user clicks "Join Meeting" button
-	 */
-	async joinMeeting() {
-		if (this.state !== 'waiting-room') {
-			throw new StateError('Must be in waiting room to join meeting');
-		}
-
-		await this._joinMeeting();
-	}
-
-	/**
-	 * Internal method to join meeting (after connection established)
-	 * @private
-	 */
-	async _joinMeeting() {
-		this.logger.info('Joining meeting:', this.joinData.videoRoom.friendlyName);
-		this._setState('joining');
-
-		// Setup transport listener BEFORE emitting room.join (but handler will wait for device)
-		this._setupMediaEventListeners();
-
-		// Send room.join event to video server (emit, not request - no callback)
-		this.logger.info('Emitting room.join event');
-		this.connection.emit('room.join', {});
-
-		// Load mediasoup device (will wait for media.routerCapabilities event)
-		this.logger.info('Waiting for media.routerCapabilities...');
-		await this.mediasoup.loadDevice();
-		this.logger.info('Device loaded successfully');
-
-		// Wait for media.transports event (listener will create transports now that device is loaded)
-		this.logger.info('Waiting for media.transports...');
-		await this._waitForTransports();
-
-		// Process any producers that arrived before transports were ready
-		this.logger.info('Processing pending producers...');
-		await this.remoteMedia.processPendingProducers();
-
-		this.currentRoomId = this.joinData.videoRoom.id;
-		this._setState('in-meeting');
-
-		this.logger.info('Successfully joined meeting');
-		this.emit('meeting:joined', {
-			roomId: this.joinData.videoRoom.id,
-			joinData: this.joinData
-		});
-	}
-
-	/**
-	 * Join a meeting room (legacy method - requires manual connect first)
-	 * @param {string} roomId - Room ID to join
-	 * @param {Object} options - Join options
-	 * @returns {Promise<Object>} Room data
-	 */
-	async joinRoom(roomId, options = {}) {
-		if (this.state !== 'connected') {
-			throw new StateError(
-				'Cannot join room: not connected to server',
-				this.state,
-				'connected'
-			);
-		}
-
-		this.logger.info('Joining room:', roomId);
-		this._setState('joining');
-
-		try {
-			// Send join request to server
-			const response = await this.connection.request('room.join', {
-				roomId,
-				...options,
-			});
-
-			this.currentRoomId = roomId;
-			this._setState('in-room');
-
-			this.logger.info('Joined room successfully');
-			this.emit('room:joined', { roomId, data: response });
-
-			return response;
-
-		} catch (error) {
-			this.logger.error('Failed to join room:', error);
-			this._setState('connected');
-			throw new RoomError(`Failed to join room: ${error.message}`, roomId);
-		}
-	}
-
-	/**
-	 * Leave the current room
-	 * @returns {Promise<void>}
-	 */
-	async leaveRoom() {
-		if (this.state !== 'in-room') {
-			throw new StateError(
-				'Cannot leave room: not in a room',
-				this.state,
-				'in-room'
-			);
-		}
-
-		this.logger.info('Leaving room:', this.currentRoomId);
-
-		try {
-			// Stop all local media
-			await this.localMedia.cleanup();
-
-			// Notify server
-			await this.connection.request('room.leave', {
-				roomId: this.currentRoomId,
-			});
-
-			// Clean up remote media
-			await this.remoteMedia.cleanup();
-
-			const roomId = this.currentRoomId;
-			this.currentRoomId = null;
-			this._setState('connected');
-
-			this.logger.info('Left room successfully');
-			this.emit('room:left', { roomId });
-
-		} catch (error) {
-			this.logger.error('Failed to leave room:', error);
-			throw error;
-		}
-	}
-
-	// ========== Local Media Methods ==========
-
-	/**
-	 * Publish camera stream
-	 * @param {Object} options - Camera options
-	 * @param {string} options.deviceId - Camera device ID
-	 * @param {string} options.resolution - Resolution (480p, 720p, 1080p)
-	 * @param {number} options.frameRate - Frame rate
-	 * @returns {Promise<MediaStream>}
-	 */
-	async publishCamera(options = {}) {
-		this._ensureInRoom();
-		return await this.localMedia.publishCamera(options);
-	}
-
-	/**
-	 * Publish microphone stream
-	 * @param {Object} options - Microphone options
-	 * @param {string} options.deviceId - Microphone device ID
-	 * @returns {Promise<MediaStream>}
-	 */
-	async publishMicrophone(options = {}) {
-		this._ensureInRoom();
-		return await this.localMedia.publishMicrophone(options);
-	}
-
-	/**
-	 * Publish screen share
-	 * @param {Object} options - Screen share options
-	 * @param {boolean} options.audio - Include system audio
-	 * @returns {Promise<MediaStream>}
-	 */
-	async publishScreenShare(options = {}) {
-		this._ensureInRoom();
-		return await this.localMedia.publishScreenShare(options);
-	}
-
-	/**
-	 * Stop camera
-	 * @returns {Promise<void>}
-	 */
-	async stopCamera() {
-		return await this.localMedia.stopCamera();
-	}
-
-	/**
-	 * Stop microphone
-	 * @returns {Promise<void>}
-	 */
-	async stopMicrophone() {
-		return await this.localMedia.stopMicrophone();
-	}
-
-	/**
-	 * Stop screen share
-	 * @returns {Promise<void>}
-	 */
-	async stopScreenShare() {
-		return await this.localMedia.stopScreenShare();
-	}
-
-	/**
-	 * Enable screenshare audio (add audio to existing screenshare)
-	 * @returns {Promise<void>}
-	 */
-	async enableScreenShareAudio() {
-		return await this.localMedia.enableScreenShareAudio();
-	}
-
-	/**
-	 * Disable screenshare audio (remove audio from existing screenshare)
-	 * @returns {Promise<void>}
-	 */
-	async disableScreenShareAudio() {
-		return await this.localMedia.disableScreenShareAudio();
-	}
-
-	/**
-	 * Mute screenshare audio
-	 * @returns {Promise<void>}
-	 */
-	async muteScreenShareAudio() {
-		return await this.localMedia.muteScreenShareAudio();
-	}
-
-	/**
-	 * Unmute screenshare audio
-	 * @returns {Promise<void>}
-	 */
-	async unmuteScreenShareAudio() {
-		return await this.localMedia.unmuteScreenShareAudio();
-	}
-
-	/**
-	 * Toggle screenshare audio mute state
-	 * @returns {Promise<boolean>} New mute state
-	 */
-	async toggleScreenShareAudioMute() {
-		return await this.localMedia.toggleScreenShareAudioMute();
-	}
-
-	/**
-	 * Change camera device
-	 * @param {string} deviceId - New camera device ID
-	 * @returns {Promise<MediaStream>}
-	 */
-	async changeCamera(deviceId) {
-		return await this.localMedia.changeCamera(deviceId);
-	}
-
-	/**
-	 * Change microphone device
-	 * @param {string} deviceId - New microphone device ID
-	 * @returns {Promise<MediaStream>}
-	 */
-	async changeMicrophone(deviceId) {
-		return await this.localMedia.changeMicrophone(deviceId);
-	}
-
-	/**
-	 * Update camera background effect
-	 * @param {Object} options - Background options
-	 * @param {string} options.type - 'none' | 'blur' | 'image'
-	 * @param {number} options.blurLevel - Blur level in pixels (default: 8)
-	 * @param {string} options.imageUrl - Background image URL (for type: 'image')
-	 * @returns {Promise<MediaStream>}
-	 *
-	 * @example
-	 * // Apply blur
-	 * await client.updateCameraBackground({ type: 'blur', blurLevel: 8 });
-	 *
-	 * // Apply virtual background
-	 * await client.updateCameraBackground({
-	 *   type: 'image',
-	 *   imageUrl: '/images/backgrounds/office.jpg'
-	 * });
-	 *
-	 * // Remove background effect
-	 * await client.updateCameraBackground({ type: 'none' });
-	 */
-	async updateCameraBackground(options) {
-		this._ensureInRoom();
-		return await this.localMedia.updateCameraBackground(options);
-	}
-
-	/**
-	 * Mute camera
-	 * @returns {Promise<void>}
-	 */
-	async muteCamera() {
-		return await this.localMedia.muteCamera();
-	}
-
-	/**
-	 * Unmute camera
-	 * @returns {Promise<void>}
-	 */
-	async unmuteCamera() {
-		return await this.localMedia.unmuteCamera();
-	}
-
-	/**
-	 * Mute microphone
-	 * @returns {Promise<void>}
-	 */
-	async muteMicrophone() {
-		return await this.localMedia.muteMicrophone();
-	}
-
-	/**
-	 * Unmute microphone
-	 * @returns {Promise<void>}
-	 */
-	async unmuteMicrophone() {
-		return await this.localMedia.unmuteMicrophone();
-	}
-
-	// ========== Device Management ==========
-
-	/**
-	 * Get available media devices
-	 * @returns {Promise<Object>} Object with cameras, microphones, speakers
-	 */
-	async getDevices() {
-		return await this.localMedia.getDevices();
-	}
-
-	/**
-	 * Get local stream
-	 * @param {string} type - Stream type (camera, microphone, screenShare)
-	 * @returns {MediaStream|null}
-	 */
-	getLocalStream(type) {
-		return this.localMedia.getStream(type);
-	}
-
-	/**
-	 * Track a video element for automatic quality adjustment based on size
-	 * @param {string} participantId - Participant ID
-	 * @param {HTMLVideoElement} videoElement - Video element to track
-	 */
-	trackVideoElement(participantId, videoElement) {
-		if (!this.remoteMedia) {
-			this.logger.warn('RemoteMedia not initialized');
-			return;
-		}
-		this.remoteMedia.trackVideoElement(participantId, videoElement);
-	}
-
-	/**
-	 * Stop tracking a video element
-	 * @param {string} participantId - Participant ID
-	 */
-	untrackVideoElement(participantId) {
-		if (!this.remoteMedia) {
-			return;
-		}
-		this.remoteMedia.untrackVideoElement(participantId);
-	}
-
-	/**
-	 * Locally mute a remote participant's stream (only for local user, doesn't affect others)
-	 * @param {string} participantId - Participant ID
-	 * @param {string} type - Stream type (audio, screenShareAudio)
-	 * @returns {boolean} Success
-	 */
-	localMuteRemoteStream(participantId, type = 'audio') {
-		if (!this.remoteMedia) {
-			this.logger.warn('RemoteMedia not initialized');
-			return false;
-		}
-		return this.remoteMedia.localMuteRemoteStream(participantId, type);
-	}
-
-	/**
-	 * Locally unmute a remote participant's stream
-	 * @param {string} participantId - Participant ID
-	 * @param {string} type - Stream type (audio, screenShareAudio)
-	 * @returns {boolean} Success
-	 */
-	localUnmuteRemoteStream(participantId, type = 'audio') {
-		if (!this.remoteMedia) {
-			this.logger.warn('RemoteMedia not initialized');
-			return false;
-		}
-		return this.remoteMedia.localUnmuteRemoteStream(participantId, type);
-	}
-
-	/**
-	 * Toggle local mute state for a remote participant's stream
-	 * @param {string} participantId - Participant ID
-	 * @param {string} type - Stream type (audio, screenShareAudio)
-	 * @returns {boolean} New mute state
-	 */
-	toggleLocalMuteRemoteStream(participantId, type = 'audio') {
-		if (!this.remoteMedia) {
-			this.logger.warn('RemoteMedia not initialized');
-			return false;
-		}
-		return this.remoteMedia.toggleLocalMuteRemoteStream(participantId, type);
-	}
-
-	/**
-	 * Check if a remote stream is locally muted
-	 * @param {string} participantId - Participant ID
-	 * @param {string} type - Stream type (audio, screenShareAudio)
-	 * @returns {boolean} Mute state
-	 */
-	isRemoteStreamLocallyMuted(participantId, type = 'audio') {
-		if (!this.remoteMedia) {
-			return false;
-		}
-		return this.remoteMedia.isLocallyMuted(participantId, type);
-	}
-
-	/**
-	 * Set callback for stats updates (for local UI display)
-	 * @param {Function} callback - Callback function that receives stats data
-	 */
-	setStatsCallback(callback) {
-		if (this.mediasoup && this.mediasoup.statsCollector) {
-			this.mediasoup.statsCollector.setStatsCallback(callback);
-		}
-	}
-
-	// ========== Remote Participant Methods ==========
-
-	/**
-	 * Get participant by ID
-	 * @param {string} participantId - Participant ID
-	 * @returns {Object|null}
-	 */
-	getParticipant(participantId) {
-		return this.remoteMedia.getParticipant(participantId);
-	}
-
-	/**
-	 * Get all participants
-	 * @returns {Array<Object>}
-	 */
-	getAllParticipants() {
-		return this.remoteMedia.getAllParticipants();
-	}
-
-	/**
-	 * Get remote stream
-	 * @param {string} participantId - Participant ID
-	 * @param {string} type - Stream type (video, audio, screenShare)
-	 * @returns {MediaStream|null}
-	 */
-	getRemoteStream(participantId, type) {
-		return this.remoteMedia.getStream(participantId, type);
-	}
-
-	/**
-	 * Get all streams for a participant
-	 * @param {string} participantId - Participant ID
-	 * @returns {Object|null}
-	 */
-	getRemoteStreams(participantId) {
-		return this.remoteMedia.getStreams(participantId);
-	}
-
-	// ========== Logging Control ==========
-
-	/**
-	 * Set verbose logging for specific categories
-	 * @param {string} category - Category name (stats, keepalive, performance) or 'all'
-	 * @param {boolean} enabled - Enable or disable this category
-	 */
-	setVerboseLogging(category, enabled) {
-		if (category === 'all') {
-			Logger.setVerbose(enabled);
-		} else {
-			Logger.setFilter(category, enabled);
-		}
-	}
-
-	// ========== State Getters ==========
-
-	/**
-	 * Get current state
-	 * @returns {string}
-	 */
-	getState() {
-		return this.state;
-	}
-
-	/**
-	 * Check if connected to server
-	 * @returns {boolean}
-	 */
-	isConnected() {
-		return this.state !== 'disconnected' && this.connection.connected;
-	}
-
-	/**
-	 * Check if in a room
-	 * @returns {boolean}
-	 */
-	isInRoom() {
-		return this.state === 'in-room';
-	}
-
-	/**
-	 * Get current room ID
-	 * @returns {string|null}
-	 */
-	getRoomId() {
-		return this.currentRoomId;
-	}
-
-	/**
-	 * Check if camera is active
-	 * @returns {boolean}
-	 */
-	isCameraActive() {
-		return this.localMedia.isCameraActive;
-	}
-
-	/**
-	 * Check if microphone is active
-	 * @returns {boolean}
-	 */
-	isMicrophoneActive() {
-		return this.localMedia.isMicrophoneActive;
-	}
-
-	/**
-	 * Check if screen share is active
-	 * @returns {boolean}
-	 */
-	isScreenShareActive() {
-		return this.localMedia.isScreenShareActive;
-	}
-
-	/**
-	 * Check if camera is muted
-	 * @returns {boolean}
-	 */
-	isCameraMuted() {
-		return this.localMedia.isCameraMuted;
-	}
-
-	/**
-	 * Check if microphone is muted
-	 * @returns {boolean}
-	 */
-	isMicrophoneMuted() {
-		return this.localMedia.isMicrophoneMuted;
-	}
-
-	/**
-	 * Get participant count
-	 * @returns {number}
-	 */
-	getParticipantCount() {
-		return this.remoteMedia.participantCount;
-	}
-
-	/**
-	 * Get video room info from join data
-	 * @returns {Object|null}
-	 */
-	getVideoRoom() {
-		return this.joinData?.videoRoom || null;
-	}
-
-	/**
-	 * Get current participant info from join data
-	 * @returns {Object|null}
-	 */
-	getCurrentParticipant() {
-		return this.joinData?.participant || null;
-	}
-
-	/**
-	 * Get server info from join data
-	 * @returns {Object|null}
-	 */
-	getServerInfo() {
-		return this.joinData?.server || null;
-	}
-
-	/**
-	 * Get full join data (videoRoom, participant, server, authorization)
-	 * @returns {Object|null}
-	 */
-	getJoinData() {
-		return this.joinData;
-	}
-
-	// ========== Private Helpers ==========
-
-	/**
-	 * Set SDK state and emit event
-	 * @private
-	 */
-	_setState(newState) {
-		const oldState = this.state;
-		this.state = newState;
-		this.logger.info(`State changed: ${oldState} -> ${newState}`);
-		this.emit('state:changed', { from: oldState, to: newState });
-	}
-
-	/**
-	 * Ensure we're in a room, throw if not
-	 * @private
-	 */
-	_ensureInRoom() {
-		if (this.state !== 'in-room' && this.state !== 'in-meeting') {
-			throw new StateError(
-				'Not in a room. Call joinRoom() first.',
-				this.state,
-				'in-room or in-meeting'
-			);
-		}
-	}
-
-	/**
-	 * Setup listeners for media events from server
-	 * @private
-	 */
-	_setupMediaEventListeners() {
-		this.logger.info('Setting up media event listeners');
-
-		// Listen for media.transports event
-		this._transportsPromise = new Promise((resolve) => {
-			this._transportsResolve = resolve;
-		});
-
-		this.connection.onServerEvent('media.transports', async (data) => {
-			this.logger.info('Received media.transports', {
-				hasSend: !!data?.sendTransportOptions,
-				hasRecv: !!data?.recvTransportOptions
-			});
-
-			const { sendTransportOptions, recvTransportOptions } = data;
-
-			// Store transport data for later if device not loaded yet
-			this._pendingTransportData = data;
-
-			// Wait for device to be loaded before creating transports
-			if (!this.mediasoup.device.loaded) {
-				this.logger.warn('Device not loaded yet, storing transport data and waiting...');
-
-				// Poll for device to be loaded (with timeout)
-				let attempts = 0;
-				while (!this.mediasoup.device.loaded && attempts < 50) {
-					await new Promise(resolve => setTimeout(resolve, 100));
-					attempts++;
-				}
-
-				if (!this.mediasoup.device.loaded) {
-					this.logger.error('Device still not loaded after 5 seconds');
-					if (this._transportsResolve) {
-						this._transportsResolve();
-					}
-					return;
-				}
-				this.logger.info('Device now loaded, proceeding with transport creation');
-			}
-
-			// Create transports
-			try {
-				if (sendTransportOptions) {
-					this.mediasoup.sendTransport = this.mediasoup.device.createSendTransport(sendTransportOptions);
-					this.mediasoup._setupSendTransportListeners(); // Not async - just sets up event listeners
-					this.logger.info('Send transport created');
-				}
-
-				if (recvTransportOptions) {
-					this.mediasoup.recvTransport = this.mediasoup.device.createRecvTransport(recvTransportOptions);
-					this.mediasoup._setupRecvTransportListeners(); // Not async - just sets up event listeners
-					this.logger.info('Receive transport created');
-				}
-
-				// Resolve the promise
-				if (this._transportsResolve) {
-					this._transportsResolve();
-				}
-			} catch (error) {
-				this.logger.error('Failed to create transports:', error);
-				if (this._transportsResolve) {
-					this._transportsResolve();
-				}
-			}
-		});
-	}
-
-	/**
-	 * Wait for media.transports event from server
-	 * @private
-	 */
-	async _waitForTransports() {
-		const timeout = setTimeout(() => {
-			throw new Error('Timeout waiting for media.transports');
-		}, 10000);
-
-		await this._transportsPromise;
-		clearTimeout(timeout);
-		this.logger.info('Transports ready');
-	}
-
-	/**
-	 * Handle server request to close and reconnect producer
-	 * This happens during quality adaptation
-	 * @private
-	 */
-	async _handleProducerCloseRequest(data) {
-		const { producer } = data;
-		const { type, reconnect } = producer;
-
-		this.logger.info('Handling producer close request:', { type, reconnect });
-
-		if (!type) {
-			this.logger.error('Producer close request missing type');
-			return;
-		}
-
-		// Get the current stream for this producer before closing
-		const currentStream = this.localMedia.streams[type === 'video' ? 'camera' : type];
-		const currentProducer = this.localMedia.producers[type];
-
-		if (!currentProducer) {
-			this.logger.warn('No producer found to close:', type);
-			return;
-		}
-
-		// Close the producer on mediasoup
-		await this.mediasoup.closeProducer(type);
-
-		// If reconnect flag is true, republish with the same stream
-		if (reconnect && currentStream) {
-			this.logger.info('Reconnecting producer:', type);
-
-			try {
-				// Clone the stream to avoid issues with the old one
-				const clonedStream = currentStream.clone();
-
-				// Republish based on type
-				if (type === 'video') {
-					// Stop the old stream tracks
-					currentStream.getTracks().forEach(track => track.stop());
-
-					// Start camera with the cloned stream
-					await this.localMedia.startCamera({
-						existingStream: clonedStream,
-						// Preserve current background if any
-						background: this.localMedia.currentBackgroundOptions
-					});
-				} else if (type === 'audio') {
-					// Stop the old stream tracks
-					currentStream.getTracks().forEach(track => track.stop());
-
-					// Start microphone with the cloned stream
-					await this.localMedia.startMicrophone({
-						existingStream: clonedStream
-					});
-				}
-
-				this.logger.info('Producer reconnected successfully:', type);
-			} catch (error) {
-				this.logger.error('Failed to reconnect producer:', type, error);
-				// Emit error event so UI can handle it
-				this.emit('producer:reconnect:failed', { type, error });
-			}
-		}
-	}
-
-	/**
-	 * Set volume for a specific participant (0.0 to 1.0)
-	 * Works seamlessly with both audio elements (< 30 participants) and audio mixer (30+ participants)
-	 * @param {string} participantId - Participant ID
-	 * @param {number} volume - Volume level (0.0 to 1.0)
-	 * @returns {boolean} Success status
-	 */
-	setParticipantVolume(participantId, volume) {
-		return this.remoteMedia.setParticipantVolume(participantId, volume);
-	}
-
-	/**
-	 * Get volume for a specific participant
-	 * @param {string} participantId - Participant ID
-	 * @returns {number} Volume level (0.0 to 1.0)
-	 */
-	getParticipantVolume(participantId) {
-		return this.remoteMedia.getParticipantVolume(participantId);
-	}
-
-	/**
-	 * Check if audio mixer is currently enabled
-	 * Audio mixer is automatically enabled when participant count >= 30
-	 * @returns {boolean}
-	 */
-	isAudioMixerEnabled() {
-		return this.remoteMedia.isAudioMixerEnabled();
-	}
-
-	/**
-	 * Retry consuming a failed producer stream
-	 * Use this when a stream:consume-failed event is received
-	 * @param {string} producerId - Producer ID to retry
-	 * @param {string} participantId - Participant ID
-	 * @returns {Promise<boolean>} Success status
-	 *
-	 * @example
-	 * client.on('stream:consume-failed', async ({ producerId, participantId }) => {
-	 *   console.warn('Stream failed to load, retrying...');
-	 *   await client.retryConsumeStream(producerId, participantId);
-	 * });
-	 */
-	async retryConsumeStream(producerId, participantId) {
-		if (!this.remoteMedia) {
-			this.logger.warn('RemoteMedia not initialized');
-			return false;
-		}
-		return await this.remoteMedia.retryConsumeProducer(producerId, participantId);
-	}
-
-	// ========== Session Lifecycle ==========
-
-	/**
-	 * End the meeting session server-side. Clears the videoAuthToken cookie
-	 * and invalidates the token row so a stale cookie can't be replayed.
-	 *
-	 * Intended to be called on `leave()`, on a page `beforeunload`, or when the
-	 * consumer surfaces an "already joined in another tab" UX and wants to
-	 * clear the incumbent session before retrying. Safe to call from
-	 * `fetch({ keepalive: true })` during unload.
-	 *
-	 * Delegates to `sdk.video.endSession(roomId)` if an SDK was injected via
-	 * constructor options; otherwise this is a no-op (consumer must clear the
-	 * cookie through its own plumbing).
-	 *
-	 * @param {Object} [options]
-	 * @param {string} [options.roomId] - Override. Defaults to the current room.
-	 * @returns {Promise<void>}
-	 */
-	async endSession(options = {}) {
-		const roomId = options.roomId || this.currentRoomId || this.joinData?.videoRoom?.id;
-		if (!roomId) {
-			this.logger.warn('endSession: no roomId available');
-			return;
-		}
-		if (!this.sdk?.video?.endSession) {
-			this.logger.warn('endSession: sdk not injected — consumer must clear session cookie manually');
-			return;
-		}
-		try {
-			await this.sdk.video.endSession(roomId);
-			this.logger.info('Session ended', { roomId });
-		} catch (err) {
-			this.logger.error('endSession failed', err);
-		}
-	}
-
-	// ========== Long-Disconnect Transport Recreation ==========
-
-	/**
-	 * Re-run the `room.join` flow after mediasoup wiped stale transports.
-	 * The server responds with fresh media.routerCapabilities + media.transports;
-	 * we reuse the existing loadDevice / transport listener plumbing so producers
-	 * and consumers get re-wired.
-	 *
-	 * Consumer must re-publish local streams (camera/microphone) after this —
-	 * producers died with the old transports.
-	 * @private
-	 */
-	async _rejoinRoomForTransportRecreation() {
-		if (!this.joinData || !this.connection) {
-			this.logger.warn('Cannot rejoin for transport recreation: no joinData or connection');
-			return;
-		}
-		this.logger.info('Re-emitting room.join to recreate transports after long disconnect');
-
-		// Reset the transports promise — _setupMediaEventListeners() creates it
-		// via a fresh media.transports listener in the join flow.
-		this._setupMediaEventListeners();
-
-		// Also need a fresh routerCapabilities listener since device must be
-		// (re-)loaded. mediasoup.loadDevice() is idempotent only if device
-		// isn't already loaded; after cleanup it should be safe to reload.
-		this.connection.emit('room.join', {});
-
-		try {
-			if (!this.mediasoup.device.loaded) {
-				await this.mediasoup.loadDevice();
-			}
-			await this._waitForTransports();
-			this.emit('transports:recreated');
-			this.logger.info('Transport recreation complete');
-		} catch (err) {
-			this.logger.error('Transport recreation failed', err);
-			this.emit('error', {
-				code: 'transport_recreation_failed',
-				message: err.message,
-			});
-		}
-	}
-
-	// ========== Reassignment Recovery ==========
-
-	/**
-	 * Arm the stable-connect timer. If the current connection stays up for >60s,
-	 * clear the reassignment attempt counter so the next cycle starts fresh.
-	 * @private
-	 */
-	_armReassignmentStableTimer() {
-		if (this._reassignmentStableTimer) {
-			clearTimeout(this._reassignmentStableTimer);
-		}
-		this._reassignmentStableTimer = setTimeout(() => {
-			if (this._reassignmentAttempts.length > 0) {
-				this.logger.info('Connection stable >60s; resetting reassignment attempt counter');
-				this._reassignmentAttempts = [];
-			}
-			this._reassignmentStableTimer = null;
-		}, 60_000);
-	}
-
-	/**
-	 * Handle a reassignmentRequired signal from the ConnectionManager.
-	 * Caps at 3 attempts in a 60s window with backoff 500ms, 2s, 5s.
-	 * @private
-	 */
-	async _handleReassignment(code) {
-		if (this._reassignmentInFlight) {
-			this.logger.warn('Reassignment already in flight; ignoring duplicate signal');
-			return;
-		}
-		this._reassignmentInFlight = true;
-
-		try {
-			// Prune attempts older than 60s
-			const now = Date.now();
-			const windowStart = now - 60_000;
-			this._reassignmentAttempts = this._reassignmentAttempts.filter(ts => ts > windowStart);
-
-			const attemptIndex = this._reassignmentAttempts.length;
-			if (attemptIndex >= 3) {
-				this.logger.error('Reassignment cap reached (3 in 60s); emitting reassignment_exhausted');
-				this.emit('error', {
-					code: 'reassignment_exhausted',
-					message: 'Reassignment attempts exhausted',
-					triggeredBy: code,
-				});
-				return;
-			}
-
-			this._reassignmentAttempts.push(now);
-
-			const backoffs = [500, 2000, 5000];
-			const delay = backoffs[attemptIndex];
-			this.logger.info(`Reassignment attempt ${attemptIndex + 1}/3 in ${delay}ms (code=${code})`);
-
-			await new Promise((resolve) => setTimeout(resolve, delay));
-
-			if (!this.sdk?.video?.joinRoom || !this._lastJoinArgs) {
-				this.logger.error('Cannot reassign: sdk or last joinRoom args missing');
-				this.emit('error', {
-					code: 'reassignment_exhausted',
-					message: 'Reassignment plumbing missing (no sdk or joinRoomArgs)',
-					triggeredBy: code,
-				});
-				return;
-			}
-
-			// Teardown current media state. The old pod's mediasoup Router is
-			// gone (or the token was rejected); we re-run the full join flow.
-			await this._teardownForReassignment();
-
-			// Fetch a fresh assignment.
-			const args = Array.isArray(this._lastJoinArgs)
-				? this._lastJoinArgs
-				: [this._lastJoinArgs];
-			const response = await this.sdk.video.joinRoom(...args);
-
-			// Re-run the join flow with the fresh response.
-			await this.joinFromApiResponse(response, { joinRoomArgs: this._lastJoinArgs });
-
-			this.emit('reassigned', { code, attempt: attemptIndex + 1 });
-			this.logger.info('Reassignment succeeded', { attempt: attemptIndex + 1 });
-
-		} catch (err) {
-			this.logger.error('Reassignment failed', err);
-			// Don't count fetch/connect failures — they'll trigger another
-			// reassignmentRequired or a terminal error on their own.
-		} finally {
-			this._reassignmentInFlight = false;
-		}
-	}
-
-	/**
-	 * Tear down state before reconnecting on reassignment. Media is
-	 * unrecoverable (mediasoup Router died with the pod), so we clean up
-	 * transports, producers, consumers, local device tracks, and the old
-	 * Socket.IO handle. Consumer re-publishes camera/mic after the `reassigned`
-	 * event fires — matches the plan's "Media state lost (unavoidable)" stance
-	 * for pod death.
-	 * @private
-	 */
-	async _teardownForReassignment() {
-		try {
-			if (this.localMedia) {
-				await this.localMedia.cleanup();
-			}
-		} catch (err) {
-			this.logger.warn('LocalMedia cleanup threw during reassignment', err);
-		}
-		try {
-			if (this.mediasoup) {
-				await this.mediasoup.cleanup();
-			}
-		} catch (err) {
-			this.logger.warn('Mediasoup cleanup threw during reassignment', err);
-		}
-		try {
-			if (this.remoteMedia) {
-				await this.remoteMedia.cleanup();
-			}
-		} catch (err) {
-			this.logger.warn('RemoteMedia cleanup threw during reassignment', err);
-		}
-		try {
-			if (this.connection) {
-				await this.connection.disconnect();
-			}
-		} catch (err) {
-			this.logger.warn('Connection disconnect threw during reassignment', err);
-		}
-
-		// Null out managers so _initializeManagers runs again with the new URL.
-		this.connection = null;
-		this.mediasoup = null;
-		this.localMedia = null;
-		this.remoteMedia = null;
-
-		if (this._reassignmentStableTimer) {
-			clearTimeout(this._reassignmentStableTimer);
-			this._reassignmentStableTimer = null;
-		}
-	}
+  /**
+   * @param {Object} options
+   * @param {string} [options.serverUrl] - WebSocket server URL (optional if using joinFromApiResponse)
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   * @param {Object} [options.sdk] - UnboundSDK instance, injected by
+   *   `sdk.video.createMeetingClient()`. Required for transparent reassignment
+   *   recovery (calls `sdk.video.joinRoom()`) and for `endSession()` to invoke
+   *   `sdk.video.endSession()`. Without it, consumers must handle both paths
+   *   themselves.
+   */
+  constructor(options = {}) {
+    super();
+
+    this.logger = new Logger("SDK:VideoMeetingClient", options.debug);
+    this.state = "disconnected"; // disconnected, connecting, connected, waiting-room, in-meeting
+    this.currentRoomId = null;
+    this.joinData = null; // Store video.join() response data
+    this.debug = options.debug;
+    this.isGuest = false;
+    this.inWaitingRoom = false;
+    this.sdk = options.sdk || null;
+
+    // Reassignment recovery state. Attempt window is 60s; cap at 3 attempts.
+    // Backoff schedule: 500ms, 2s, 5s. Counter resets once a connection has
+    // stayed up for >60s (see _onReassignmentStableConnect).
+    this._reassignmentAttempts = []; // timestamps (Date.now()) of recent attempts
+    this._reassignmentInFlight = false;
+    this._reassignmentStableTimer = null;
+    this._lastJoinArgs = null; // args used by consumer to call sdk.video.joinRoom()
+
+    // Managers will be initialized when we have connection info
+    this.connection = null;
+    this.mediasoup = null;
+    this.localMedia = null;
+    this.remoteMedia = null;
+
+    // If serverUrl provided, initialize managers now (old behavior)
+    if (options.serverUrl) {
+      this._initializeManagers(options.serverUrl);
+    }
+
+    this.logger.info("VideoMeetingClient initialized", { hasSdk: !!this.sdk });
+  }
+
+  /**
+   * Initialize managers with server URL
+   * @private
+   * @param {string} serverUrl
+   * @param {string} [namespace] - Socket.IO namespace path, e.g. `/video`
+   */
+  _initializeManagers(serverUrl, namespace = null) {
+    this.connection = new ConnectionManager({
+      serverUrl,
+      namespace,
+      debug: this.debug,
+    });
+
+    this.mediasoup = new MediasoupManager({
+      connection: this.connection,
+      debug: this.debug,
+    });
+
+    this.localMedia = new LocalMediaManager({
+      mediasoup: this.mediasoup,
+      debug: this.debug,
+    });
+
+    this.remoteMedia = new RemoteMediaManager({
+      mediasoup: this.mediasoup,
+      connection: this.connection,
+      videoClient: this, // Pass reference to access joinData
+      debug: this.debug,
+    });
+
+    // Adaptive quality: subscribes to StatsCollector samples, runs
+    // state machines, silently caps simulcast layers under pressure,
+    // and emits user-visible events (`quality` SDK event) for the
+    // host app to render toasts / tile badges. See QualityMonitor.js.
+    this.qualityMonitor = new QualityMonitor({
+      statsCollector: this.mediasoup.statsCollector,
+      mediasoupManager: this.mediasoup,
+      onQualityEvent: (evt) => this.emit("quality", evt),
+      // Solo gate: until we actually have a remote consumer flowing,
+      // no one is receiving our media and the encoder / BWE numbers
+      // don't reflect a real user-impacting problem. We count
+      // mediasoup consumers (people whose media we're receiving) as
+      // proxy for "a real meeting is in progress" — this excludes
+      // waiting-room participants and pre-join lobby state, which
+      // can otherwise appear in the participants list. Returning 0
+      // here makes the monitor skip evaluation entirely.
+      getRemotePeerCount: () => {
+        try {
+          return this.mediasoup?.consumers?.size || 0;
+        } catch {
+          return 0;
+        }
+      },
+    });
+    this.qualityMonitor.start();
+
+    // Connection health: unified `connection` event combining socket events,
+    // mediasoup transport state, and a heartbeat that catches silent failures
+    // on bad networks where the OS hasn't admitted the problem yet. The host
+    // app subscribes via `client.on('connection', ...)` to render a
+    // "Reconnecting…" banner. See ConnectionHealthMonitor.js.
+    this.connectionHealth = new ConnectionHealthMonitor({
+      connectionManager: this.connection,
+      mediasoupManager: this.mediasoup,
+      statsCollector: this.mediasoup.statsCollector,
+      onConnectionEvent: (evt) => this.emit("connection", evt),
+      debug: this.debug,
+    });
+    this.connectionHealth.start();
+
+    // Proxy manager events to SDK events
+    this._setupEventProxies();
+
+    // When mediasoup detects its transports are stale after a long disconnect,
+    // re-run the room.join flow to get fresh transport options + producer list
+    // from the server. This keeps media working across network blips >30s.
+    this.mediasoup.on("transports:recreated-needed", () => {
+      this._rejoinRoomForTransportRecreation().catch((err) => {
+        this.logger.error("Rejoin for transport recreation failed", err);
+      });
+    });
+  }
+
+  /**
+   * Setup event proxies from managers to SDK
+   * @private
+   */
+  _setupEventProxies() {
+    // Connection events
+    this.connection.on("connected", () => {
+      this._setState("connected");
+      this.emit("connected");
+
+      // On Socket.IO reconnect (not initial connect), check whether the
+      // WebRTC transports died during the disconnect window. If the state
+      // has been bad for >10s, mediasoup will emit transports:recreated-needed.
+      if (
+        this.mediasoup &&
+        (this.mediasoup.sendTransport || this.mediasoup.recvTransport)
+      ) {
+        this.mediasoup.recreateStaleTransports().catch((err) => {
+          this.logger.error("recreateStaleTransports threw", err);
+        });
+      }
+    });
+
+    this.connection.on("disconnected", (data) => {
+      this._setState("disconnected");
+      this.emit("disconnected", data);
+    });
+
+    this.connection.on("error", (error) => {
+      this.emit("error", error);
+    });
+
+    // Server signaled the assigned pod is stale — re-fetch joinRoom and reconnect.
+    this.connection.on("reassignmentRequired", ({ code }) => {
+      this.logger.warn("Reassignment required", { code });
+      this._handleReassignment(code).catch((err) => {
+        this.logger.error("Reassignment handler threw", err);
+      });
+    });
+
+    // Local media events
+    this.localMedia.on("stream:added", (data) => {
+      this.emit("local-stream:added", data);
+    });
+
+    this.localMedia.on("stream:removed", (data) => {
+      this.emit("local-stream:removed", data);
+    });
+
+    this.localMedia.on("device:changed", (data) => {
+      this.emit("device:changed", data);
+    });
+
+    // Remote media events
+    this.remoteMedia.on("participant:added", (data) => {
+      this.emit("participant:joined", data);
+    });
+
+    this.remoteMedia.on("participant:removed", (data) => {
+      this.emit("participant:left", data);
+    });
+
+    this.remoteMedia.on("participant:updated", (data) => {
+      this.emit("participant:updated", data);
+    });
+
+    this.remoteMedia.on("stream:added", (data) => {
+      this.emit("stream:added", data);
+    });
+
+    this.remoteMedia.on("stream:removed", (data) => {
+      this.emit("stream:removed", data);
+    });
+
+    // Stream consuming events (for retry logic and error handling)
+    this.remoteMedia.on("stream:consuming", (data) => {
+      this.emit("stream:consuming", data);
+    });
+
+    this.remoteMedia.on("stream:consume-failed", (data) => {
+      this.emit("stream:consume-failed", data);
+    });
+
+    // Volume control events
+    this.remoteMedia.on("participant:volume-changed", (data) => {
+      this.emit("participant:volume-changed", data);
+    });
+  }
+
+  /**
+   * Setup room/participant event listeners
+   * @private
+   */
+  _setupRoomEventListeners() {
+    // Room events
+    this.connection.onServerEvent("room.closed", (data) => {
+      this.logger.info("Room closed", data);
+      this._setState("disconnected");
+      this.emit("room:closed", data);
+    });
+
+    this.connection.onServerEvent("room.update", (data) => {
+      this.logger.info("Room updated", data);
+      this.emit("room:updated", data);
+    });
+
+    // Participant events
+    this.connection.onServerEvent("participant.all", (data) => {
+      this.logger.info("All participants", data);
+      this.emit("participants:list", data);
+    });
+
+    this.connection.onServerEvent("participant.leave", (data) => {
+      this.logger.info("Participant left", data);
+      this.emit("participant:left", data);
+    });
+
+    this.connection.onServerEvent("participant.remove", (data) => {
+      this.logger.info("Participant removed", data);
+      this.emit("participant:removed", data);
+    });
+
+    this.connection.onServerEvent("participant.update", (data) => {
+      this.logger.info("Participant updated", data);
+      this.emit("participant:updated", data);
+    });
+
+    // Server-side detected a peer's WebRTC transport closed (their network
+    // died). Surface as `participant:connection` so the host UI can render a
+    // "Reconnecting…" overlay on that peer's tile. Recovery is implicit —
+    // when the peer re-joins, normal participant.update + new producer
+    // events will arrive and the host clears the overlay.
+    this.connection.onServerEvent("participant.connection", (data) => {
+      this.logger.info("Participant connection state", data);
+      this.emit("participant:connection", data);
+    });
+
+    // Producer close event (for quality adaptation / reconnect)
+    this.connection.onServerEvent(
+      "participant.producer.close",
+      async (data) => {
+        this.logger.info("Producer close requested", data);
+        await this._handleProducerCloseRequest(data);
+      },
+    );
+
+    // Waiting room events
+    this.connection.onServerEvent("room.waitingRoom.admit", (data) => {
+      this.logger.info("Admitted from waiting room", data);
+      this.inWaitingRoom = false;
+      this._setState("in-meeting");
+      this.emit("waitingRoom:admitted", data);
+    });
+
+    // Keepalive events
+    this.connection.onServerEvent("keepalive.send", (data) => {
+      this.emit("keepalive:received", data);
+      this.connection.emit("keepalive.ack", data);
+    });
+
+    this.connection.onServerEvent("keepalive.alert", (data) => {
+      this.emit("keepalive:alert", data);
+    });
+  }
+
+  /**
+   * Connect to the server
+   * @param {Object|string} auth - Authentication token or auth object
+   * @returns {Promise<void>}
+   */
+  async connect(auth = {}) {
+    if (this.state !== "disconnected") {
+      throw new StateError(
+        "Cannot connect: already connected or connecting",
+        this.state,
+        "disconnected",
+      );
+    }
+
+    this.logger.info("Connecting to server...");
+    this._setState("connecting");
+
+    try {
+      // Normalize auth to object format
+      const authObj = typeof auth === "string" ? { token: auth } : auth;
+
+      // Connect to server
+      await this.connection.connect(authObj);
+
+      // Load mediasoup device
+      await this.mediasoup.loadDevice();
+
+      this.logger.info("Connected successfully");
+      this._setState("connected");
+    } catch (error) {
+      this.logger.error("Connection failed:", error);
+      this._setState("disconnected");
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnect from server
+   * @returns {Promise<void>}
+   */
+  /**
+   * Host calls this when the user clicks "Keep camera on" in the
+   * auto-disable grace toast. Cancels the pending disable and resets
+   * the sustained-critical timer so it does not immediately re-fire.
+   */
+  cancelAutoDisableCamera() {
+    if (this.qualityMonitor) this.qualityMonitor.cancelAutoDisableCamera();
+  }
+
+  /**
+   * Pause/resume a single remote peer's video. Stops local rendering AND
+   * asks the SFU to stop forwarding bytes — real downlink bandwidth
+   * savings. Screenshare is unaffected.
+   * @param {string} peerParticipantId
+   * @param {boolean} paused
+   * @returns {boolean} true if a matching consumer was found
+   */
+  setPeerVideoPaused(peerParticipantId, paused) {
+    if (!this.mediasoup) return false;
+    return this.mediasoup.setPeerVideoPaused(peerParticipantId, paused);
+  }
+
+  /**
+   * Pause/resume every remote peer's video. Used by the "pause all
+   * incoming video" control. Returns the count of consumers affected.
+   * @param {boolean} paused
+   */
+  setAllRemoteVideoPaused(paused) {
+    if (!this.mediasoup) return 0;
+    return this.mediasoup.setAllRemoteVideoPaused(paused);
+  }
+
+  /**
+   * Returns a structured snapshot of the QualityMonitor — current
+   * state, recent samples (last 10/direction), recent emitted events
+   * (last 25). Designed for the in-app debug modal so a tester can
+   * reproduce conditions without dropping to DevTools. Returns null
+   * if the monitor isn't initialized.
+   */
+  getQualityDebugSnapshot() {
+    const quality = this.qualityMonitor
+      ? this.qualityMonitor.getDebugSnapshot()
+      : null;
+    if (!quality) return null;
+    // Fold the connection-health monitor's snapshot into the same
+    // payload so the debug modal can show both in one place — saves
+    // wiring a second getter through every consumer and makes it
+    // obvious whether stale SDK code is running (missing keys here
+    // = older bundle).
+    quality.connectionHealth = this.connectionHealth
+      ? this.connectionHealth.getSnapshot()
+      : null;
+    return quality;
+  }
+
+  /**
+   * Current connection health snapshot (state, silence, transport state,
+   * thresholds). Used by the debug modal and by the host app to render
+   * the "Reconnecting…" banner.
+   */
+  getConnectionSnapshot() {
+    return this.connectionHealth ? this.connectionHealth.getSnapshot() : null;
+  }
+
+  async disconnect() {
+    this.logger.info("Disconnecting...");
+
+    try {
+      // Leave room if in one
+      if (this.state === "in-room") {
+        await this.leaveRoom();
+      }
+
+      // Stop quality monitor before tearing down stats sources.
+      if (this.qualityMonitor) this.qualityMonitor.stop();
+      if (this.connectionHealth) this.connectionHealth.stop();
+
+      // Clean up managers
+      await this.localMedia.cleanup();
+      await this.remoteMedia.cleanup();
+      await this.mediasoup.cleanup();
+
+      // Disconnect socket
+      await this.connection.disconnect();
+
+      this._setState("disconnected");
+      this.logger.info("Disconnected successfully");
+    } catch (error) {
+      this.logger.error("Disconnect error:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Join meeting directly from API response (api.video.joinRoom)
+   * This method extracts server info, connects, and determines if user needs to wait
+   *
+   * @param {Object} joinResponse - Response from api.video.joinRoom(room, password, email)
+   * @param {Object} options - Additional options
+   * @param {boolean} options.enterWaitingRoom - For guests, enter waiting room (default: auto-detect)
+   * @returns {Promise<Object>} Join data
+   *
+   * @example
+   * const joinResponse = await api.video.joinRoom('room-123', 'password', 'user@example.com');
+   * await client.joinFromApiResponse(joinResponse);
+   *
+   * // For guests in waiting room:
+   * client.on('waitingRoom:entered', () => showWaitingRoomUI());
+   * client.on('waitingRoom:admitted', () => showMeetingUI());
+   */
+  async joinFromApiResponse(joinResponse, options = {}) {
+    this.logger.info("Joining from API response");
+
+    // Store args used to obtain this response. If a reassignment is required
+    // later, we replay these against sdk.video.joinRoom() to get a fresh
+    // assignment without the consumer having to wire anything up.
+    if (options.joinRoomArgs !== undefined) {
+      this._lastJoinArgs = options.joinRoomArgs;
+    }
+
+    try {
+      const { videoRoom, participant } = joinResponse;
+
+      // Support both the new shape (connectionInfo.socket) and the legacy
+      // shape (top-level server + authorization) during the rollout.
+      // Legacy path is removed once every app1-api replica returns the new
+      // shape in staging/prod.
+      const connectionInfo = joinResponse.connectionInfo;
+      const socketInfo = connectionInfo?.socket;
+      const legacyServer = joinResponse.server;
+
+      let socketUrl;
+      let socketNamespace;
+      let authData;
+      let authorization;
+
+      if (socketInfo?.url) {
+        socketUrl = socketInfo.url;
+        socketNamespace = socketInfo.namespace || "/video";
+        authData = {
+          ...socketInfo.auth,
+          roomId: videoRoom.id,
+          participantId: participant.id,
+        };
+        authorization = connectionInfo.authorization || null;
+      } else if (legacyServer?.url && legacyServer?.socketPort) {
+        // Legacy per-pod-ingress path. Remove once centralized signaling
+        // is fully deployed.
+        socketUrl = `https://${legacyServer.url}:${legacyServer.socketPort}`;
+        socketNamespace = null;
+        authorization = joinResponse.authorization;
+        authData = {
+          accountNamespace: authorization?.namespace,
+          roomId: videoRoom.id,
+          participantId: participant.id,
+        };
+      } else {
+        throw new Error(
+          "Invalid join response: missing connectionInfo.socket and legacy server info",
+        );
+      }
+
+      // Store join data for later use (including reassignment replay)
+      this.joinData = {
+        videoRoom,
+        participant,
+        connectionInfo: connectionInfo || null,
+        server: legacyServer || null,
+        authorization,
+      };
+
+      // Detect if this is a guest (no host privileges)
+      this.isGuest = !participant.isHost && !participant.isModerator;
+
+      this.logger.info("Connecting to video server:", {
+        socketUrl,
+        socketNamespace,
+      });
+
+      // Initialize managers if not already done
+      if (!this.connection) {
+        this._initializeManagers(socketUrl, socketNamespace);
+      }
+
+      this._setState("connecting");
+
+      this.logger.info("Connecting with auth (cookie-based):", authData);
+      await this.connection.connect(authData);
+
+      this._setState("connected");
+
+      // Connection succeeded. If it stays up >60s, reset the reassignment
+      // attempt counter so the next reassignment cycle starts fresh.
+      this._armReassignmentStableTimer();
+
+      // Setup remote media listeners and room event listeners
+      this.logger.info("Setting up event listeners");
+      this.remoteMedia._setupServerListeners();
+      this._setupRoomEventListeners();
+
+      // ALWAYS emit room.waitingRoom first to initialize room on video server
+      // The server requires this event to set up the room before any joins
+      this.logger.info(
+        "Emitting room.waitingRoom to initialize room on server",
+      );
+      this.connection.emit("room.waitingRoom", {});
+
+      // Enter waiting-room state for everyone (hosts and guests)
+      // This allows users to set up their devices while room initializes
+      this.inWaitingRoom = true;
+      this._setState("waiting-room");
+
+      this.logger.info("Entering waiting room - waiting for room to be ready");
+
+      this.emit("waitingRoom:entered", {
+        roomId: videoRoom.id,
+        participant,
+        isHost: participant.isHost,
+        canJoinImmediately: !this.isGuest, // Hosts can join once ready, guests need admission
+      });
+
+      // Listen for media.routerCapabilities to know when room is ready
+      this.connection.onServerEvent("media.routerCapabilities", (data) => {
+        this.logger.info("Room is ready - received media.routerCapabilities");
+        this.emit("waitingRoom:ready", {
+          roomId: videoRoom.id,
+          participant,
+        });
+      });
+
+      // Return - user must explicitly call joinMeeting() when ready
+      // For hosts: after they click "Join Meeting" button (once room is ready)
+      // For guests: after host admits them (room.waitingRoom.admit event)
+      return {
+        ...this.joinData,
+        inWaitingRoom: true,
+      };
+    } catch (error) {
+      this.logger.error("Failed to join from API response:", error);
+      this._setState("disconnected");
+      throw new RoomError(`Failed to join meeting: ${error.message}`);
+    }
+  }
+
+  /**
+   * Public method to join meeting from waiting room
+   * Call this after user clicks "Join Meeting" button
+   */
+  async joinMeeting() {
+    if (this.state !== "waiting-room") {
+      throw new StateError("Must be in waiting room to join meeting");
+    }
+
+    await this._joinMeeting();
+  }
+
+  /**
+   * Internal method to join meeting (after connection established)
+   * @private
+   */
+  async _joinMeeting() {
+    this.logger.info("Joining meeting:", this.joinData.videoRoom.friendlyName);
+    this._setState("joining");
+
+    // Setup transport listener BEFORE emitting room.join (but handler will wait for device)
+    this._setupMediaEventListeners();
+
+    // Send room.join event to video server (emit, not request - no callback)
+    this.logger.info("Emitting room.join event");
+    this.connection.emit("room.join", {});
+
+    // Load mediasoup device (will wait for media.routerCapabilities event)
+    this.logger.info("Waiting for media.routerCapabilities...");
+    await this.mediasoup.loadDevice();
+    this.logger.info("Device loaded successfully");
+
+    // Wait for media.transports event (listener will create transports now that device is loaded)
+    this.logger.info("Waiting for media.transports...");
+    await this._waitForTransports();
+
+    // Process any producers that arrived before transports were ready
+    this.logger.info("Processing pending producers...");
+    await this.remoteMedia.processPendingProducers();
+
+    this.currentRoomId = this.joinData.videoRoom.id;
+    this._setState("in-meeting");
+
+    this.logger.info("Successfully joined meeting");
+    this.emit("meeting:joined", {
+      roomId: this.joinData.videoRoom.id,
+      joinData: this.joinData,
+    });
+  }
+
+  /**
+   * Join a meeting room (legacy method - requires manual connect first)
+   * @param {string} roomId - Room ID to join
+   * @param {Object} options - Join options
+   * @returns {Promise<Object>} Room data
+   */
+  async joinRoom(roomId, options = {}) {
+    if (this.state !== "connected") {
+      throw new StateError(
+        "Cannot join room: not connected to server",
+        this.state,
+        "connected",
+      );
+    }
+
+    this.logger.info("Joining room:", roomId);
+    this._setState("joining");
+
+    try {
+      // Send join request to server
+      const response = await this.connection.request("room.join", {
+        roomId,
+        ...options,
+      });
+
+      this.currentRoomId = roomId;
+      this._setState("in-room");
+
+      this.logger.info("Joined room successfully");
+      this.emit("room:joined", { roomId, data: response });
+
+      return response;
+    } catch (error) {
+      this.logger.error("Failed to join room:", error);
+      this._setState("connected");
+      throw new RoomError(`Failed to join room: ${error.message}`, roomId);
+    }
+  }
+
+  /**
+   * Leave the current room
+   * @returns {Promise<void>}
+   */
+  async leaveRoom() {
+    if (this.state !== "in-room") {
+      throw new StateError(
+        "Cannot leave room: not in a room",
+        this.state,
+        "in-room",
+      );
+    }
+
+    this.logger.info("Leaving room:", this.currentRoomId);
+
+    try {
+      // Stop all local media
+      await this.localMedia.cleanup();
+
+      // Server-side teardown is driven by the socket disconnect handler
+      // (publishes participant.leave to the pod via NATS) and by the
+      // consumer's DELETE /video/:id/leave call. No room.leave socket
+      // event exists; do not send one.
+
+      // Clean up remote media
+      await this.remoteMedia.cleanup();
+
+      const roomId = this.currentRoomId;
+      this.currentRoomId = null;
+      this._setState("connected");
+
+      this.logger.info("Left room successfully");
+      this.emit("room:left", { roomId });
+    } catch (error) {
+      this.logger.error("Failed to leave room:", error);
+      throw error;
+    }
+  }
+
+  // ========== Local Media Methods ==========
+
+  /**
+   * Publish camera stream
+   * @param {Object} options - Camera options
+   * @param {string} options.deviceId - Camera device ID
+   * @param {string} options.resolution - Resolution (480p, 720p, 1080p)
+   * @param {number} options.frameRate - Frame rate
+   * @returns {Promise<MediaStream>}
+   */
+  async publishCamera(options = {}) {
+    this._ensureInRoom();
+    return await this.localMedia.publishCamera(options);
+  }
+
+  /**
+   * Publish microphone stream
+   * @param {Object} options - Microphone options
+   * @param {string} options.deviceId - Microphone device ID
+   * @returns {Promise<MediaStream>}
+   */
+  async publishMicrophone(options = {}) {
+    this._ensureInRoom();
+    return await this.localMedia.publishMicrophone(options);
+  }
+
+  /**
+   * Publish screen share
+   * @param {Object} options - Screen share options
+   * @param {boolean} options.audio - Include system audio
+   * @returns {Promise<MediaStream>}
+   */
+  async publishScreenShare(options = {}) {
+    this._ensureInRoom();
+    return await this.localMedia.publishScreenShare(options);
+  }
+
+  /**
+   * Stop camera
+   * @returns {Promise<void>}
+   */
+  async stopCamera() {
+    return await this.localMedia.stopCamera();
+  }
+
+  /**
+   * Stop microphone
+   * @returns {Promise<void>}
+   */
+  async stopMicrophone() {
+    return await this.localMedia.stopMicrophone();
+  }
+
+  /**
+   * Stop screen share
+   * @returns {Promise<void>}
+   */
+  async stopScreenShare() {
+    return await this.localMedia.stopScreenShare();
+  }
+
+  /**
+   * Enable screenshare audio (add audio to existing screenshare)
+   * @returns {Promise<void>}
+   */
+  async enableScreenShareAudio() {
+    return await this.localMedia.enableScreenShareAudio();
+  }
+
+  /**
+   * Disable screenshare audio (remove audio from existing screenshare)
+   * @returns {Promise<void>}
+   */
+  async disableScreenShareAudio() {
+    return await this.localMedia.disableScreenShareAudio();
+  }
+
+  /**
+   * Mute screenshare audio
+   * @returns {Promise<void>}
+   */
+  async muteScreenShareAudio() {
+    return await this.localMedia.muteScreenShareAudio();
+  }
+
+  /**
+   * Unmute screenshare audio
+   * @returns {Promise<void>}
+   */
+  async unmuteScreenShareAudio() {
+    return await this.localMedia.unmuteScreenShareAudio();
+  }
+
+  /**
+   * Toggle screenshare audio mute state
+   * @returns {Promise<boolean>} New mute state
+   */
+  async toggleScreenShareAudioMute() {
+    return await this.localMedia.toggleScreenShareAudioMute();
+  }
+
+  /**
+   * Change camera device
+   * @param {string} deviceId - New camera device ID
+   * @returns {Promise<MediaStream>}
+   */
+  async changeCamera(deviceId) {
+    return await this.localMedia.changeCamera(deviceId);
+  }
+
+  /**
+   * Change microphone device
+   * @param {string} deviceId - New microphone device ID
+   * @returns {Promise<MediaStream>}
+   */
+  async changeMicrophone(deviceId) {
+    return await this.localMedia.changeMicrophone(deviceId);
+  }
+
+  /**
+   * Update camera background effect
+   * @param {Object} options - Background options
+   * @param {string} options.type - 'none' | 'blur' | 'image'
+   * @param {number} options.blurLevel - Blur level in pixels (default: 8)
+   * @param {string} options.imageUrl - Background image URL (for type: 'image')
+   * @returns {Promise<MediaStream>}
+   *
+   * @example
+   * // Apply blur
+   * await client.updateCameraBackground({ type: 'blur', blurLevel: 8 });
+   *
+   * // Apply virtual background
+   * await client.updateCameraBackground({
+   *   type: 'image',
+   *   imageUrl: '/images/backgrounds/office.jpg'
+   * });
+   *
+   * // Remove background effect
+   * await client.updateCameraBackground({ type: 'none' });
+   */
+  async updateCameraBackground(options) {
+    this._ensureInRoom();
+    return await this.localMedia.updateCameraBackground(options);
+  }
+
+  /**
+   * Mute camera
+   * @returns {Promise<void>}
+   */
+  async muteCamera() {
+    return await this.localMedia.muteCamera();
+  }
+
+  /**
+   * Unmute camera
+   * @returns {Promise<void>}
+   */
+  async unmuteCamera() {
+    return await this.localMedia.unmuteCamera();
+  }
+
+  /**
+   * Mute microphone
+   * @returns {Promise<void>}
+   */
+  async muteMicrophone() {
+    return await this.localMedia.muteMicrophone();
+  }
+
+  /**
+   * Unmute microphone
+   * @returns {Promise<void>}
+   */
+  async unmuteMicrophone() {
+    return await this.localMedia.unmuteMicrophone();
+  }
+
+  // ========== Device Management ==========
+
+  /**
+   * Get available media devices
+   * @returns {Promise<Object>} Object with cameras, microphones, speakers
+   */
+  async getDevices() {
+    return await this.localMedia.getDevices();
+  }
+
+  /**
+   * Get local stream
+   * @param {string} type - Stream type (camera, microphone, screenShare)
+   * @returns {MediaStream|null}
+   */
+  getLocalStream(type) {
+    return this.localMedia.getStream(type);
+  }
+
+  /**
+   * Track a video element for automatic quality adjustment based on size
+   * @param {string} participantId - Participant ID
+   * @param {HTMLVideoElement} videoElement - Video element to track
+   */
+  trackVideoElement(participantId, videoElement) {
+    if (!this.remoteMedia) {
+      this.logger.warn("RemoteMedia not initialized");
+      return;
+    }
+    this.remoteMedia.trackVideoElement(participantId, videoElement);
+  }
+
+  /**
+   * Stop tracking a video element
+   * @param {string} participantId - Participant ID
+   */
+  untrackVideoElement(participantId) {
+    if (!this.remoteMedia) {
+      return;
+    }
+    this.remoteMedia.untrackVideoElement(participantId);
+  }
+
+  /**
+   * Locally mute a remote participant's stream (only for local user, doesn't affect others)
+   * @param {string} participantId - Participant ID
+   * @param {string} type - Stream type (audio, screenShareAudio)
+   * @returns {boolean} Success
+   */
+  localMuteRemoteStream(participantId, type = "audio") {
+    if (!this.remoteMedia) {
+      this.logger.warn("RemoteMedia not initialized");
+      return false;
+    }
+    return this.remoteMedia.localMuteRemoteStream(participantId, type);
+  }
+
+  /**
+   * Locally unmute a remote participant's stream
+   * @param {string} participantId - Participant ID
+   * @param {string} type - Stream type (audio, screenShareAudio)
+   * @returns {boolean} Success
+   */
+  localUnmuteRemoteStream(participantId, type = "audio") {
+    if (!this.remoteMedia) {
+      this.logger.warn("RemoteMedia not initialized");
+      return false;
+    }
+    return this.remoteMedia.localUnmuteRemoteStream(participantId, type);
+  }
+
+  /**
+   * Toggle local mute state for a remote participant's stream
+   * @param {string} participantId - Participant ID
+   * @param {string} type - Stream type (audio, screenShareAudio)
+   * @returns {boolean} New mute state
+   */
+  toggleLocalMuteRemoteStream(participantId, type = "audio") {
+    if (!this.remoteMedia) {
+      this.logger.warn("RemoteMedia not initialized");
+      return false;
+    }
+    return this.remoteMedia.toggleLocalMuteRemoteStream(participantId, type);
+  }
+
+  /**
+   * Check if a remote stream is locally muted
+   * @param {string} participantId - Participant ID
+   * @param {string} type - Stream type (audio, screenShareAudio)
+   * @returns {boolean} Mute state
+   */
+  isRemoteStreamLocallyMuted(participantId, type = "audio") {
+    if (!this.remoteMedia) {
+      return false;
+    }
+    return this.remoteMedia.isLocallyMuted(participantId, type);
+  }
+
+  /**
+   * Set callback for stats updates (for local UI display)
+   * @param {Function} callback - Callback function that receives stats data
+   */
+  setStatsCallback(callback) {
+    if (this.mediasoup && this.mediasoup.statsCollector) {
+      this.mediasoup.statsCollector.setStatsCallback(callback);
+    }
+  }
+
+  // ========== Remote Participant Methods ==========
+
+  /**
+   * Get participant by ID
+   * @param {string} participantId - Participant ID
+   * @returns {Object|null}
+   */
+  getParticipant(participantId) {
+    return this.remoteMedia.getParticipant(participantId);
+  }
+
+  /**
+   * Get all participants
+   * @returns {Array<Object>}
+   */
+  getAllParticipants() {
+    return this.remoteMedia.getAllParticipants();
+  }
+
+  /**
+   * Get remote stream
+   * @param {string} participantId - Participant ID
+   * @param {string} type - Stream type (video, audio, screenShare)
+   * @returns {MediaStream|null}
+   */
+  getRemoteStream(participantId, type) {
+    return this.remoteMedia.getStream(participantId, type);
+  }
+
+  /**
+   * Get all streams for a participant
+   * @param {string} participantId - Participant ID
+   * @returns {Object|null}
+   */
+  getRemoteStreams(participantId) {
+    return this.remoteMedia.getStreams(participantId);
+  }
+
+  // ========== Logging Control ==========
+
+  /**
+   * Set verbose logging for specific categories
+   * @param {string} category - Category name (stats, keepalive, performance) or 'all'
+   * @param {boolean} enabled - Enable or disable this category
+   */
+  setVerboseLogging(category, enabled) {
+    if (category === "all") {
+      Logger.setVerbose(enabled);
+    } else {
+      Logger.setFilter(category, enabled);
+    }
+  }
+
+  // ========== State Getters ==========
+
+  /**
+   * Get current state
+   * @returns {string}
+   */
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * Check if connected to server
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this.state !== "disconnected" && this.connection.connected;
+  }
+
+  /**
+   * Check if in a room
+   * @returns {boolean}
+   */
+  isInRoom() {
+    return this.state === "in-room";
+  }
+
+  /**
+   * Get current room ID
+   * @returns {string|null}
+   */
+  getRoomId() {
+    return this.currentRoomId;
+  }
+
+  /**
+   * Check if camera is active
+   * @returns {boolean}
+   */
+  isCameraActive() {
+    return this.localMedia.isCameraActive;
+  }
+
+  /**
+   * Check if microphone is active
+   * @returns {boolean}
+   */
+  isMicrophoneActive() {
+    return this.localMedia.isMicrophoneActive;
+  }
+
+  /**
+   * Check if screen share is active
+   * @returns {boolean}
+   */
+  isScreenShareActive() {
+    return this.localMedia.isScreenShareActive;
+  }
+
+  /**
+   * Check if camera is muted
+   * @returns {boolean}
+   */
+  isCameraMuted() {
+    return this.localMedia.isCameraMuted;
+  }
+
+  /**
+   * Check if microphone is muted
+   * @returns {boolean}
+   */
+  isMicrophoneMuted() {
+    return this.localMedia.isMicrophoneMuted;
+  }
+
+  /**
+   * Get participant count
+   * @returns {number}
+   */
+  getParticipantCount() {
+    return this.remoteMedia.participantCount;
+  }
+
+  /**
+   * Get video room info from join data
+   * @returns {Object|null}
+   */
+  getVideoRoom() {
+    return this.joinData?.videoRoom || null;
+  }
+
+  /**
+   * Get current participant info from join data
+   * @returns {Object|null}
+   */
+  getCurrentParticipant() {
+    return this.joinData?.participant || null;
+  }
+
+  /**
+   * Get server info from join data
+   * @returns {Object|null}
+   */
+  getServerInfo() {
+    return this.joinData?.server || null;
+  }
+
+  /**
+   * Get full join data (videoRoom, participant, server, authorization)
+   * @returns {Object|null}
+   */
+  getJoinData() {
+    return this.joinData;
+  }
+
+  // ========== Private Helpers ==========
+
+  /**
+   * Set SDK state and emit event
+   * @private
+   */
+  _setState(newState) {
+    const oldState = this.state;
+    this.state = newState;
+    this.logger.info(`State changed: ${oldState} -> ${newState}`);
+    this.emit("state:changed", { from: oldState, to: newState });
+  }
+
+  /**
+   * Ensure we're in a room, throw if not
+   * @private
+   */
+  _ensureInRoom() {
+    if (this.state !== "in-room" && this.state !== "in-meeting") {
+      throw new StateError(
+        "Not in a room. Call joinRoom() first.",
+        this.state,
+        "in-room or in-meeting",
+      );
+    }
+  }
+
+  /**
+   * Setup listeners for media events from server
+   * @private
+   */
+  _setupMediaEventListeners() {
+    this.logger.info("Setting up media event listeners");
+
+    // Listen for media.transports event
+    this._transportsPromise = new Promise((resolve) => {
+      this._transportsResolve = resolve;
+    });
+
+    this.connection.onServerEvent("media.transports", async (data) => {
+      this.logger.info("Received media.transports", {
+        hasSend: !!data?.sendTransportOptions,
+        hasRecv: !!data?.recvTransportOptions,
+      });
+
+      const { sendTransportOptions, recvTransportOptions } = data;
+
+      // Store transport data for later if device not loaded yet
+      this._pendingTransportData = data;
+
+      // Wait for device to be loaded before creating transports
+      if (!this.mediasoup.device.loaded) {
+        this.logger.warn(
+          "Device not loaded yet, storing transport data and waiting...",
+        );
+
+        // Poll for device to be loaded (with timeout)
+        let attempts = 0;
+        while (!this.mediasoup.device.loaded && attempts < 50) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          attempts++;
+        }
+
+        if (!this.mediasoup.device.loaded) {
+          this.logger.error("Device still not loaded after 5 seconds");
+          if (this._transportsResolve) {
+            this._transportsResolve();
+          }
+          return;
+        }
+        this.logger.info(
+          "Device now loaded, proceeding with transport creation",
+        );
+      }
+
+      // Create transports
+      try {
+        if (sendTransportOptions) {
+          this.mediasoup.sendTransport =
+            this.mediasoup.device.createSendTransport(sendTransportOptions);
+          this.mediasoup._setupSendTransportListeners(); // Not async - just sets up event listeners
+          this.logger.info("Send transport created");
+        }
+
+        if (recvTransportOptions) {
+          this.mediasoup.recvTransport =
+            this.mediasoup.device.createRecvTransport(recvTransportOptions);
+          this.mediasoup._setupRecvTransportListeners(); // Not async - just sets up event listeners
+          this.logger.info("Receive transport created");
+        }
+
+        // Resolve the promise
+        if (this._transportsResolve) {
+          this._transportsResolve();
+        }
+      } catch (error) {
+        this.logger.error("Failed to create transports:", error);
+        if (this._transportsResolve) {
+          this._transportsResolve();
+        }
+      }
+    });
+  }
+
+  /**
+   * Wait for media.transports event from server
+   * @private
+   */
+  async _waitForTransports() {
+    const timeout = setTimeout(() => {
+      throw new Error("Timeout waiting for media.transports");
+    }, 10000);
+
+    await this._transportsPromise;
+    clearTimeout(timeout);
+    this.logger.info("Transports ready");
+  }
+
+  /**
+   * Handle server request to close and reconnect producer
+   * This happens during quality adaptation
+   * @private
+   */
+  async _handleProducerCloseRequest(data) {
+    const { producer } = data;
+    const { type, reconnect } = producer;
+
+    this.logger.info("Handling producer close request:", { type, reconnect });
+
+    if (!type) {
+      this.logger.error("Producer close request missing type");
+      return;
+    }
+
+    // Get the current stream for this producer before closing
+    const currentStream =
+      this.localMedia.streams[type === "video" ? "camera" : type];
+    const currentProducer = this.localMedia.producers[type];
+
+    if (!currentProducer) {
+      this.logger.warn("No producer found to close:", type);
+      return;
+    }
+
+    // Close the producer on mediasoup
+    await this.mediasoup.closeProducer(type);
+
+    // If reconnect flag is true, republish with the same stream
+    if (reconnect && currentStream) {
+      this.logger.info("Reconnecting producer:", type);
+
+      try {
+        // Clone the stream to avoid issues with the old one
+        const clonedStream = currentStream.clone();
+
+        // Republish based on type
+        if (type === "video") {
+          // Stop the old stream tracks
+          currentStream.getTracks().forEach((track) => track.stop());
+
+          // Start camera with the cloned stream
+          await this.localMedia.startCamera({
+            existingStream: clonedStream,
+            // Preserve current background if any
+            background: this.localMedia.currentBackgroundOptions,
+          });
+        } else if (type === "audio") {
+          // Stop the old stream tracks
+          currentStream.getTracks().forEach((track) => track.stop());
+
+          // Start microphone with the cloned stream
+          await this.localMedia.startMicrophone({
+            existingStream: clonedStream,
+          });
+        }
+
+        this.logger.info("Producer reconnected successfully:", type);
+      } catch (error) {
+        this.logger.error("Failed to reconnect producer:", type, error);
+        // Emit error event so UI can handle it
+        this.emit("producer:reconnect:failed", { type, error });
+      }
+    }
+  }
+
+  /**
+   * Set volume for a specific participant (0.0 to 1.0)
+   * Works seamlessly with both audio elements (< 30 participants) and audio mixer (30+ participants)
+   * @param {string} participantId - Participant ID
+   * @param {number} volume - Volume level (0.0 to 1.0)
+   * @returns {boolean} Success status
+   */
+  setParticipantVolume(participantId, volume) {
+    return this.remoteMedia.setParticipantVolume(participantId, volume);
+  }
+
+  /**
+   * Get volume for a specific participant
+   * @param {string} participantId - Participant ID
+   * @returns {number} Volume level (0.0 to 1.0)
+   */
+  getParticipantVolume(participantId) {
+    return this.remoteMedia.getParticipantVolume(participantId);
+  }
+
+  /**
+   * Check if audio mixer is currently enabled
+   * Audio mixer is automatically enabled when participant count >= 30
+   * @returns {boolean}
+   */
+  isAudioMixerEnabled() {
+    return this.remoteMedia.isAudioMixerEnabled();
+  }
+
+  /**
+   * Retry consuming a failed producer stream
+   * Use this when a stream:consume-failed event is received
+   * @param {string} producerId - Producer ID to retry
+   * @param {string} participantId - Participant ID
+   * @returns {Promise<boolean>} Success status
+   *
+   * @example
+   * client.on('stream:consume-failed', async ({ producerId, participantId }) => {
+   *   console.warn('Stream failed to load, retrying...');
+   *   await client.retryConsumeStream(producerId, participantId);
+   * });
+   */
+  async retryConsumeStream(producerId, participantId) {
+    if (!this.remoteMedia) {
+      this.logger.warn("RemoteMedia not initialized");
+      return false;
+    }
+    return await this.remoteMedia.retryConsumeProducer(
+      producerId,
+      participantId,
+    );
+  }
+
+  // ========== Session Lifecycle ==========
+
+  /**
+   * End the meeting session server-side. Clears the videoAuthToken cookie
+   * and invalidates the token row so a stale cookie can't be replayed.
+   *
+   * Intended to be called on `leave()`, on a page `beforeunload`, or when the
+   * consumer surfaces an "already joined in another tab" UX and wants to
+   * clear the incumbent session before retrying. Safe to call from
+   * `fetch({ keepalive: true })` during unload.
+   *
+   * Delegates to `sdk.video.endSession(roomId)` if an SDK was injected via
+   * constructor options; otherwise this is a no-op (consumer must clear the
+   * cookie through its own plumbing).
+   *
+   * @param {Object} [options]
+   * @param {string} [options.roomId] - Override. Defaults to the current room.
+   * @returns {Promise<void>}
+   */
+  async endSession(options = {}) {
+    const roomId =
+      options.roomId || this.currentRoomId || this.joinData?.videoRoom?.id;
+    if (!roomId) {
+      this.logger.warn("endSession: no roomId available");
+      return;
+    }
+    if (!this.sdk?.video?.endSession) {
+      this.logger.warn(
+        "endSession: sdk not injected — consumer must clear session cookie manually",
+      );
+      return;
+    }
+    try {
+      await this.sdk.video.endSession(roomId);
+      this.logger.info("Session ended", { roomId });
+    } catch (err) {
+      this.logger.error("endSession failed", err);
+    }
+  }
+
+  // ========== Long-Disconnect Transport Recreation ==========
+
+  /**
+   * Re-run the `room.join` flow after mediasoup wiped stale transports.
+   * The server responds with fresh media.routerCapabilities + media.transports;
+   * we reuse the existing loadDevice / transport listener plumbing so producers
+   * and consumers get re-wired.
+   *
+   * Consumer must re-publish local streams (camera/microphone) after this —
+   * producers died with the old transports.
+   * @private
+   */
+  async _rejoinRoomForTransportRecreation() {
+    if (!this.joinData || !this.connection) {
+      this.logger.warn(
+        "Cannot rejoin for transport recreation: no joinData or connection",
+      );
+      return;
+    }
+    this.logger.info(
+      "Re-emitting room.join to recreate transports after long disconnect",
+    );
+
+    // Reset the transports promise — _setupMediaEventListeners() creates it
+    // via a fresh media.transports listener in the join flow.
+    this._setupMediaEventListeners();
+
+    // Also need a fresh routerCapabilities listener since device must be
+    // (re-)loaded. mediasoup.loadDevice() is idempotent only if device
+    // isn't already loaded; after cleanup it should be safe to reload.
+    this.connection.emit("room.join", {});
+
+    try {
+      if (!this.mediasoup.device.loaded) {
+        await this.mediasoup.loadDevice();
+      }
+      await this._waitForTransports();
+      this.emit("transports:recreated");
+      this.logger.info("Transport recreation complete");
+    } catch (err) {
+      this.logger.error("Transport recreation failed", err);
+      this.emit("error", {
+        code: "transport_recreation_failed",
+        message: err.message,
+      });
+    }
+  }
+
+  // ========== Reassignment Recovery ==========
+
+  /**
+   * Arm the stable-connect timer. If the current connection stays up for >60s,
+   * clear the reassignment attempt counter so the next cycle starts fresh.
+   * @private
+   */
+  _armReassignmentStableTimer() {
+    if (this._reassignmentStableTimer) {
+      clearTimeout(this._reassignmentStableTimer);
+    }
+    this._reassignmentStableTimer = setTimeout(() => {
+      if (this._reassignmentAttempts.length > 0) {
+        this.logger.info(
+          "Connection stable >60s; resetting reassignment attempt counter",
+        );
+        this._reassignmentAttempts = [];
+      }
+      this._reassignmentStableTimer = null;
+    }, 60_000);
+  }
+
+  /**
+   * Handle a reassignmentRequired signal from the ConnectionManager.
+   * Caps at 3 attempts in a 60s window with backoff 500ms, 2s, 5s.
+   * @private
+   */
+  async _handleReassignment(code) {
+    if (this._reassignmentInFlight) {
+      this.logger.warn(
+        "Reassignment already in flight; ignoring duplicate signal",
+      );
+      return;
+    }
+    this._reassignmentInFlight = true;
+
+    try {
+      // Prune attempts older than 60s
+      const now = Date.now();
+      const windowStart = now - 60_000;
+      this._reassignmentAttempts = this._reassignmentAttempts.filter(
+        (ts) => ts > windowStart,
+      );
+
+      const attemptIndex = this._reassignmentAttempts.length;
+      if (attemptIndex >= 3) {
+        this.logger.error(
+          "Reassignment cap reached (3 in 60s); emitting reassignment_exhausted",
+        );
+        this.emit("error", {
+          code: "reassignment_exhausted",
+          message: "Reassignment attempts exhausted",
+          triggeredBy: code,
+        });
+        return;
+      }
+
+      this._reassignmentAttempts.push(now);
+
+      const backoffs = [500, 2000, 5000];
+      const delay = backoffs[attemptIndex];
+      this.logger.info(
+        `Reassignment attempt ${attemptIndex + 1}/3 in ${delay}ms (code=${code})`,
+      );
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+
+      if (!this.sdk?.video?.joinRoom || !this._lastJoinArgs) {
+        this.logger.error("Cannot reassign: sdk or last joinRoom args missing");
+        this.emit("error", {
+          code: "reassignment_exhausted",
+          message: "Reassignment plumbing missing (no sdk or joinRoomArgs)",
+          triggeredBy: code,
+        });
+        return;
+      }
+
+      // Teardown current media state. The old pod's mediasoup Router is
+      // gone (or the token was rejected); we re-run the full join flow.
+      await this._teardownForReassignment();
+
+      // Fetch a fresh assignment.
+      const args = Array.isArray(this._lastJoinArgs)
+        ? this._lastJoinArgs
+        : [this._lastJoinArgs];
+      const response = await this.sdk.video.joinRoom(...args);
+
+      // Re-run the join flow with the fresh response.
+      await this.joinFromApiResponse(response, {
+        joinRoomArgs: this._lastJoinArgs,
+      });
+
+      this.emit("reassigned", { code, attempt: attemptIndex + 1 });
+      this.logger.info("Reassignment succeeded", { attempt: attemptIndex + 1 });
+    } catch (err) {
+      this.logger.error("Reassignment failed", err);
+      // Don't count fetch/connect failures — they'll trigger another
+      // reassignmentRequired or a terminal error on their own.
+    } finally {
+      this._reassignmentInFlight = false;
+    }
+  }
+
+  /**
+   * Tear down state before reconnecting on reassignment. Media is
+   * unrecoverable (mediasoup Router died with the pod), so we clean up
+   * transports, producers, consumers, local device tracks, and the old
+   * Socket.IO handle. Consumer re-publishes camera/mic after the `reassigned`
+   * event fires — matches the plan's "Media state lost (unavoidable)" stance
+   * for pod death.
+   * @private
+   */
+  async _teardownForReassignment() {
+    try {
+      if (this.localMedia) {
+        await this.localMedia.cleanup();
+      }
+    } catch (err) {
+      this.logger.warn("LocalMedia cleanup threw during reassignment", err);
+    }
+    try {
+      if (this.mediasoup) {
+        await this.mediasoup.cleanup();
+      }
+    } catch (err) {
+      this.logger.warn("Mediasoup cleanup threw during reassignment", err);
+    }
+    try {
+      if (this.remoteMedia) {
+        await this.remoteMedia.cleanup();
+      }
+    } catch (err) {
+      this.logger.warn("RemoteMedia cleanup threw during reassignment", err);
+    }
+    try {
+      if (this.connection) {
+        await this.connection.disconnect();
+      }
+    } catch (err) {
+      this.logger.warn("Connection disconnect threw during reassignment", err);
+    }
+
+    // Null out managers so _initializeManagers runs again with the new URL.
+    this.connection = null;
+    this.mediasoup = null;
+    this.localMedia = null;
+    this.remoteMedia = null;
+
+    if (this._reassignmentStableTimer) {
+      clearTimeout(this._reassignmentStableTimer);
+      this._reassignmentStableTimer = null;
+    }
+  }
 }