@agatx/serenada-core 0.6.10

package/dist/media/MediaEngine.js

@@ -0,0 +1,1224 @@
+import { parseOfferPayload, parseAnswerPayload, parseIceCandidatePayload } from '../signaling/payloads.js';
+import { formatError } from '../formatError.js';
+import { normalizeIceServers } from '../iceServers.js';
+import { OFFER_TIMEOUT_MS, ICE_RESTART_COOLDOWN_MS, NON_HOST_FALLBACK_DELAY_MS, NON_HOST_FALLBACK_MAX_ATTEMPTS, ICE_CANDIDATE_BUFFER_MAX, CONNECTION_RETRYING_DELAY_MS, LOCAL_VIDEO_HEARTBEAT_INTERVAL_MS, } from '../constants.js';
+import { shouldForceLocalVideoRefresh, shouldRecoverLocalVideo } from './localVideoRecovery.js';
+const DEFAULT_RTC_CONFIG = {
+    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+};
+const ICE_STATE_PRIORITY = ['failed', 'disconnected', 'checking', 'new', 'connected', 'completed', 'closed'];
+const CONN_STATE_PRIORITY = ['failed', 'disconnected', 'connecting', 'new', 'connected', 'closed'];
+const SIG_STATE_PRIORITY = ['closed', 'have-local-offer', 'have-remote-offer', 'have-local-pranswer', 'have-remote-pranswer', 'stable'];
+export class MediaEngine {
+    localStream = null;
+    remoteStreams = new Map();
+    isScreenSharing = false;
+    canScreenShare = !!navigator.mediaDevices?.getDisplayMedia;
+    facingMode = 'user';
+    hasMultipleCameras = false;
+    videoCaptureSupported;
+    iceConnectionState = 'new';
+    connectionState = 'new';
+    signalingState = 'stable';
+    connectionStatus = 'connected';
+    peers = new Map();
+    initialVideoEnabled;
+    // Per-remote-CID tally of cumulative `inbound-rtp.bytesReceived`. Sampled
+    // on every `getInboundFlowingCids()` call; a CID is "flowing" when its
+    // current sample exceeds the previous one. Drives #3's `media_liveness`
+    // emission (see SerenadaSession.startMediaLivenessTimer).
+    lastInboundBytesByCid = new Map();
+    rtcConfig = DEFAULT_RTC_CONFIG;
+    screenShareTrack = null;
+    requestingMedia = false;
+    destroyed = false;
+    cameraRecoveryInFlight = false;
+    mediaRequestId = 0;
+    retryingTimer = null;
+    localVideoHeartbeatAt = Date.now();
+    localVideoHiddenAt = typeof document !== 'undefined' && document.hidden ? Date.now() : null;
+    visibilityHandler = null;
+    pageShowHandler = null;
+    heartbeatInterval = null;
+    onlineHandler = null;
+    networkChangeHandler = null;
+    deviceChangeHandler = null;
+    turnsOnly;
+    logger;
+    // Injected dependencies
+    sendSignalingMessage;
+    roomState = null;
+    clientId = null;
+    isSignalingConnected = false;
+    onChange = null;
+    constructor(config, sendMessage) {
+        this.turnsOnly = config.turnsOnly ?? false;
+        this.logger = config.logger;
+        this.facingMode = config.initialFacingMode ?? 'user';
+        this.initialVideoEnabled = config.initialVideoEnabled !== false;
+        this.videoCaptureSupported = config.videoCaptureSupported !== false;
+        this.sendSignalingMessage = sendMessage;
+        this.setupEventListeners();
+    }
+    setOnChange(cb) { this.onChange = cb; }
+    updateRoomState(state, clientId) {
+        this.roomState = state;
+        this.clientId = clientId;
+        this.syncPeers();
+    }
+    updateSignalingConnected(connected) {
+        this.isSignalingConnected = connected;
+        this.updateConnectionStatusValue();
+        if (connected) {
+            for (const [cid, peer] of this.peers) {
+                if (peer.pendingIceRestart && this.shouldIOffer(cid) && peer.pc.signalingState === 'stable') {
+                    peer.pendingIceRestart = false;
+                    peer.lastIceRestartAt = Date.now();
+                    void this.createOfferTo(cid, { iceRestart: true });
+                }
+                if (peer.pendingLocalTrackNegotiation) {
+                    this.scheduleLocalTrackNegotiation(cid, peer);
+                }
+            }
+        }
+    }
+    setIceServers(iceServers) {
+        const nextServers = this.normalizeIceServers(iceServers);
+        const nextConfig = {
+            iceServers: nextServers.length > 0 ? nextServers : DEFAULT_RTC_CONFIG.iceServers,
+        };
+        if (this.turnsOnly) {
+            nextConfig.iceTransportPolicy = 'relay';
+        }
+        this.rtcConfig = nextConfig;
+        for (const [, peer] of this.peers) {
+            try {
+                peer.pc.setConfiguration(nextConfig);
+            }
+            catch (error) {
+                this.logger?.log('warning', 'WebRTC', `Failed to update ICE config: ${formatError(error)}`);
+            }
+        }
+    }
+    handleSignalingReconnect() {
+        if (!this.isSignalingConnected) {
+            return;
+        }
+        for (const [remoteCid] of this.peers) {
+            if (this.shouldIOffer(remoteCid)) {
+                this.scheduleIceRestart(remoteCid, 'signaling-reconnect', 0);
+            }
+            else {
+                this.scheduleNonHostFallback(remoteCid);
+            }
+        }
+    }
+    /**
+     * Schedule glare-safe ICE restart for a specific peer because the server
+     * told us the pair is dirty after the peer reattached (#1).
+     */
+    scheduleDirtyPairRestart(remoteCid) {
+        if (!this.peers.has(remoteCid)) {
+            return;
+        }
+        if (this.shouldIOffer(remoteCid)) {
+            this.scheduleIceRestart(remoteCid, 'negotiation-dirty', 0);
+        }
+        else {
+            this.scheduleNonHostFallback(remoteCid);
+        }
+    }
+    processSignalingMessage(msg) {
+        const { type, payload } = msg;
+        if (!payload)
+            return;
+        try {
+            switch (type) {
+                case 'offer': {
+                    const offer = parseOfferPayload(payload);
+                    if (offer)
+                        void this.handleOfferFrom(offer.from, offer.sdp);
+                    break;
+                }
+                case 'answer': {
+                    const answer = parseAnswerPayload(payload);
+                    if (answer)
+                        void this.handleAnswerFrom(answer.from, answer.sdp);
+                    break;
+                }
+                case 'ice': {
+                    const ice = parseIceCandidatePayload(payload);
+                    if (ice)
+                        void this.handleIceFrom(ice.from, ice.candidate);
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `Error processing message ${type}: ${formatError(err)}`);
+        }
+    }
+    async startLocalMedia() {
+        const requestId = this.mediaRequestId + 1;
+        this.mediaRequestId = requestId;
+        if (this.localStream)
+            return this.localStream;
+        this.requestingMedia = true;
+        try {
+            if (!navigator.mediaDevices?.getUserMedia) {
+                this.requestingMedia = false;
+                return null;
+            }
+            const audioConstraints = {
+                echoCancellation: { ideal: true },
+                noiseSuppression: { ideal: true },
+                autoGainControl: { ideal: true },
+                channelCount: { ideal: 1 },
+                sampleRate: { ideal: 48000 }
+            };
+            let stream;
+            if (!this.videoCaptureSupported || !this.initialVideoEnabled) {
+                stream = await navigator.mediaDevices.getUserMedia({ video: false, audio: audioConstraints });
+            }
+            else {
+                try {
+                    stream = await navigator.mediaDevices.getUserMedia({
+                        video: { facingMode: this.facingMode },
+                        audio: audioConstraints
+                    });
+                }
+                catch {
+                    stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
+                }
+            }
+            if (this.destroyed || this.mediaRequestId !== requestId) {
+                stream.getTracks().forEach(t => t.stop());
+                return null;
+            }
+            this.applySpeechTrackHints(stream);
+            this.localStream = stream;
+            await this.detectCameras();
+            this.requestingMedia = false;
+            for (const [remoteCid, peer] of this.peers) {
+                await this.attachLocalTracksToPeer(remoteCid, peer, stream);
+                void this.applyAudioSenderParameters(peer.pc);
+                if (this.shouldIOffer(remoteCid) && !peer.pc.remoteDescription) {
+                    if (peer.pc.signalingState === 'stable') {
+                        void this.createOfferTo(remoteCid);
+                    }
+                    else {
+                        peer.pendingLocalTrackNegotiation = true;
+                    }
+                }
+                else if (!this.shouldIOffer(remoteCid) && peer.pc.remoteDescription) {
+                    if (peer.pc.signalingState === 'stable') {
+                        void this.createOfferTo(remoteCid);
+                    }
+                    else {
+                        peer.pendingLocalTrackNegotiation = true;
+                    }
+                }
+            }
+            this.notifyChange();
+            return stream;
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `Error accessing media: ${formatError(err)}`);
+            this.requestingMedia = false;
+            return null;
+        }
+    }
+    stopLocalMedia() {
+        this.mediaRequestId += 1;
+        if (this.screenShareTrack) {
+            this.screenShareTrack.onended = null;
+            this.screenShareTrack = null;
+        }
+        if (this.localStream) {
+            this.localStream.getTracks().forEach(t => t.stop());
+            this.localStream = null;
+        }
+        this.isScreenSharing = false;
+        this.requestingMedia = false;
+        this.notifyChange();
+    }
+    async releaseVideoTrack() {
+        if (this.isScreenSharing)
+            return;
+        const currentTrack = this.localStream?.getVideoTracks()[0] ?? null;
+        if (!currentTrack)
+            return;
+        await this.swapLocalVideoTrack(null, currentTrack);
+    }
+    async reacquireVideoTrack() {
+        if (!this.videoCaptureSupported)
+            return;
+        if (this.isScreenSharing)
+            return;
+        if (this.localStream?.getVideoTracks()[0])
+            return;
+        if (this.cameraRecoveryInFlight || this.requestingMedia)
+            return;
+        this.cameraRecoveryInFlight = true;
+        try {
+            const track = await this.acquireCameraTrack(this.facingMode, true);
+            await this.swapLocalVideoTrack(track, null);
+        }
+        catch (err) {
+            this.logger?.log('error', 'Camera', `Failed to reacquire camera: ${formatError(err)}`);
+        }
+        finally {
+            this.cameraRecoveryInFlight = false;
+        }
+    }
+    async startScreenShare() {
+        if (this.isScreenSharing || !this.canScreenShare)
+            return;
+        if (!this.localStream)
+            return;
+        try {
+            const displayStream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio: false });
+            const displayTrack = displayStream.getVideoTracks()[0];
+            if (!displayTrack) {
+                displayStream.getTracks().forEach(track => track.stop());
+                throw new Error('No display track returned');
+            }
+            const previousVideoTrack = this.localStream.getVideoTracks()[0];
+            const wasVideoEnabled = previousVideoTrack ? previousVideoTrack.enabled : true;
+            displayTrack.enabled = wasVideoEnabled;
+            if ('contentHint' in displayTrack) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- contentHint is a valid but untyped browser API
+                try {
+                    displayTrack.contentHint = 'detail';
+                }
+                catch { /* ignore */ }
+            }
+            if (this.screenShareTrack)
+                this.screenShareTrack.onended = null;
+            this.screenShareTrack = displayTrack;
+            displayTrack.onended = () => { void this.stopScreenShare(); };
+            await this.swapLocalVideoTrack(displayTrack, previousVideoTrack);
+            this.isScreenSharing = true;
+            this.sendSignalingMessage('content_state', { active: true, contentType: 'screenShare' });
+            this.notifyChange();
+        }
+        catch (err) {
+            this.logger?.log('error', 'ScreenShare', `Failed to start screen share: ${formatError(err)}`);
+        }
+    }
+    async stopScreenShare() {
+        if (!this.isScreenSharing)
+            return;
+        if (!this.localStream) {
+            this.isScreenSharing = false;
+            this.sendSignalingMessage('content_state', { active: false });
+            this.notifyChange();
+            return;
+        }
+        if (this.screenShareTrack) {
+            this.screenShareTrack.onended = null;
+            this.screenShareTrack = null;
+        }
+        const previousVideoTrack = this.localStream.getVideoTracks()[0];
+        const wasVideoEnabled = previousVideoTrack ? previousVideoTrack.enabled : true;
+        try {
+            const cameraTrack = await this.acquireCameraTrack(this.facingMode, wasVideoEnabled);
+            await this.swapLocalVideoTrack(cameraTrack, previousVideoTrack);
+        }
+        catch (err) {
+            this.logger?.log('error', 'ScreenShare', `Failed to stop screen share and restore camera: ${formatError(err)}`);
+            await this.swapLocalVideoTrack(null, previousVideoTrack);
+        }
+        finally {
+            this.isScreenSharing = false;
+            this.sendSignalingMessage('content_state', { active: false });
+            this.notifyChange();
+        }
+    }
+    async flipCamera() {
+        if (this.isScreenSharing)
+            return;
+        if (!this.hasMultipleCameras)
+            return;
+        const newMode = this.facingMode === 'user' ? 'environment' : 'user';
+        this.facingMode = newMode;
+        if (!this.localStream) {
+            this.notifyChange();
+            return;
+        }
+        try {
+            const oldVideoTrack = this.localStream.getVideoTracks()[0];
+            const newVideoTrack = await this.acquireCameraTrack(newMode, oldVideoTrack?.enabled ?? true);
+            await this.swapLocalVideoTrack(newVideoTrack, oldVideoTrack);
+            this.notifyChange();
+        }
+        catch (err) {
+            this.logger?.log('error', 'Camera', `Failed to flip camera: ${formatError(err)}`);
+        }
+    }
+    getPeerConnections() {
+        return Array.from(this.peers.values()).map(ps => ps.pc);
+    }
+    getPeerConnectionsMap() {
+        const map = new Map();
+        for (const [cid, ps] of this.peers)
+            map.set(cid, ps.pc);
+        return map;
+    }
+    cleanupAllPeers() {
+        for (const [, peer] of this.peers) {
+            this.clearPeerTimers(peer);
+            peer.pc.close();
+        }
+        this.peers.clear();
+        this.remoteStreams = new Map();
+        this.lastInboundBytesByCid.clear();
+        if (this.retryingTimer) {
+            window.clearTimeout(this.retryingTimer);
+            this.retryingTimer = null;
+        }
+        this.iceConnectionState = 'closed';
+        this.connectionState = 'closed';
+        this.signalingState = 'closed';
+        this.connectionStatus = 'connected';
+        this.notifyChange();
+    }
+    /**
+     * Sample inbound RTP `bytesReceived` per remote peer and return the CIDs
+     * whose totals advanced since the previous sample. Drives #3's
+     * `media_liveness{cids}` emission so the server can defer hard-eviction
+     * of suspended peers whose media is still being received locally.
+     *
+     * Conservative on first call (no baseline → empty result). Cleans up
+     * tracking for peers that have left.
+     */
+    async getInboundFlowingCids() {
+        const flowing = [];
+        const seen = new Set();
+        for (const [cid, peer] of this.peers) {
+            seen.add(cid);
+            let bytes = 0;
+            try {
+                const report = await peer.pc.getStats();
+                report.forEach((stat) => {
+                    if (stat.type !== 'inbound-rtp')
+                        return;
+                    const value = stat['bytesReceived'];
+                    if (typeof value === 'number')
+                        bytes += value;
+                });
+            }
+            catch {
+                continue;
+            }
+            const previous = this.lastInboundBytesByCid.get(cid);
+            if (previous !== undefined && bytes > previous) {
+                flowing.push(cid);
+            }
+            this.lastInboundBytesByCid.set(cid, bytes);
+        }
+        for (const cid of [...this.lastInboundBytesByCid.keys()]) {
+            if (!seen.has(cid))
+                this.lastInboundBytesByCid.delete(cid);
+        }
+        return flowing;
+    }
+    destroy() {
+        this.destroyed = true;
+        this.cleanupAllPeers();
+        this.stopLocalMedia();
+        this.removeEventListeners();
+        if (this.retryingTimer) {
+            window.clearTimeout(this.retryingTimer);
+            this.retryingTimer = null;
+        }
+    }
+    /**
+     * Inspects each peer connection's currently-selected ICE candidate pair
+     * and returns true only when at least one peer exists and every peer's
+     * local candidate is direct (host / srflx / prflx). Returns false when
+     * any peer is relaying through TURN, when any stats query fails, or when
+     * there are no peers (TURN may be needed for a future join).
+     *
+     * We identify the active pair via `RTCTransportStats.selectedCandidatePairId`,
+     * with a fallback to the nominated+succeeded pair. We do NOT accept any
+     * arbitrary succeeded pair: after an ICE failover the old pair stays
+     * present as "succeeded" for a while, so reading it would lie about the
+     * current active path and wrongly suppress TURN refresh while media is
+     * actually relaying.
+     *
+     * Used by the TURN refresh gate: if all active media flows are direct,
+     * refreshing TURN credentials over signaling is unnecessary upkeep. This
+     * lets a P2P call survive indefinite signaling outages.
+     */
+    async arePeerPathsAllDirect() {
+        const activePeers = Array.from(this.peers.values())
+            .filter((peer) => peer.pc.connectionState !== 'closed' && peer.pc.connectionState !== 'failed');
+        if (activePeers.length === 0)
+            return false;
+        const results = await Promise.all(activePeers.map(async (peer) => {
+            try {
+                return this.isPeerOnDirectPath(await peer.pc.getStats());
+            }
+            catch {
+                return false;
+            }
+        }));
+        return results.every(Boolean);
+    }
+    isPeerOnDirectPath(stats) {
+        // Preferred: resolve the active pair through the transport stat.
+        let selectedPairId = null;
+        for (const report of stats.values()) {
+            if (report.type !== 'transport')
+                continue;
+            const id = report.selectedCandidatePairId;
+            if (typeof id === 'string' && id !== '') {
+                selectedPairId = id;
+                break;
+            }
+        }
+        let activePair = null;
+        if (selectedPairId) {
+            const pair = stats.get(selectedPairId);
+            if (pair && pair.type === 'candidate-pair') {
+                activePair = pair;
+            }
+        }
+        // Fallback for browsers that don't populate selectedCandidatePairId:
+        // the nominated + succeeded pair is authoritative once ICE settles.
+        if (!activePair) {
+            for (const report of stats.values()) {
+                if (report.type !== 'candidate-pair')
+                    continue;
+                const pair = report;
+                if (pair.state !== 'succeeded')
+                    continue;
+                if (!pair.nominated)
+                    continue;
+                activePair = pair;
+                break;
+            }
+        }
+        if (!activePair)
+            return false;
+        const localId = activePair.localCandidateId;
+        if (!localId)
+            return false;
+        const local = stats.get(localId);
+        if (!local || local.type !== 'local-candidate')
+            return false;
+        const candType = (local.candidateType ?? '').toString();
+        return candType !== '' && candType !== 'relay';
+    }
+    // --- Private methods ---
+    syncPeers() {
+        const myId = this.clientId;
+        if (!this.roomState || !myId) {
+            if (this.peers.size > 0) {
+                this.logger?.log('debug', 'WebRTC', 'Room state cleared, cleaning up all peers');
+                this.cleanupAllPeers();
+            }
+            return;
+        }
+        const remotePeers = this.roomState.participants?.filter(p => p.cid !== myId) ?? [];
+        const remoteCids = new Set(remotePeers.map(p => p.cid));
+        for (const [cid] of this.peers) {
+            if (!remoteCids.has(cid)) {
+                this.logger?.log('debug', 'WebRTC', `Participant ${cid} left, cleaning up peer`);
+                this.cleanupPeer(cid);
+            }
+        }
+        for (const peer of remotePeers) {
+            if (!this.peers.has(peer.cid)) {
+                this.getOrCreatePeer(peer.cid);
+                if (this.shouldIOffer(peer.cid)) {
+                    const peerState = this.peers.get(peer.cid);
+                    if (peerState &&
+                        this.localStream &&
+                        peerState.pc.signalingState === 'stable' &&
+                        !peerState.pc.remoteDescription) {
+                        void this.createOfferTo(peer.cid);
+                    }
+                }
+                else {
+                    this.scheduleNonHostFallback(peer.cid);
+                }
+            }
+        }
+        this.notifyChange();
+    }
+    getOrCreatePeer(remoteCid) {
+        const existing = this.peers.get(remoteCid);
+        if (existing)
+            return existing;
+        const pc = new RTCPeerConnection(this.rtcConfig);
+        const peerState = {
+            pc, remoteStream: null, iceBuffer: [],
+            isMakingOffer: false, offerTimeout: null, iceRestartTimer: null,
+            lastIceRestartAt: 0, pendingIceRestart: false,
+            pendingLocalTrackNegotiation: false,
+            nonHostFallbackTimer: null, nonHostFallbackAttempts: 0,
+        };
+        if (this.localStream) {
+            this.localStream.getTracks().forEach(track => pc.addTrack(track, this.localStream));
+            void this.applyAudioSenderParameters(pc);
+        }
+        this.ensureMediaTransceivers(pc);
+        pc.ontrack = (event) => {
+            this.logger?.log('debug', 'WebRTC', `[${remoteCid}] Remote track received`);
+            let remoteStream;
+            if (event.streams?.[0]) {
+                remoteStream = event.streams[0];
+            }
+            else {
+                remoteStream = peerState.remoteStream || new MediaStream();
+                if (!remoteStream.getTracks().some(t => t.id === event.track.id)) {
+                    remoteStream.addTrack(event.track);
+                }
+            }
+            peerState.remoteStream = remoteStream;
+            this.remoteStreams = new Map(this.remoteStreams).set(remoteCid, remoteStream);
+            this.notifyChange();
+        };
+        pc.oniceconnectionstatechange = () => {
+            this.logger?.log('debug', 'WebRTC', `[${remoteCid}] ICE: ${pc.iceConnectionState}`);
+            this.updateAggregateState();
+            if (pc.iceConnectionState === 'connected' || pc.iceConnectionState === 'completed') {
+                if (peerState.iceRestartTimer) {
+                    window.clearTimeout(peerState.iceRestartTimer);
+                    peerState.iceRestartTimer = null;
+                }
+                peerState.pendingIceRestart = false;
+                return;
+            }
+            if (pc.iceConnectionState === 'disconnected') {
+                this.scheduleIceRestart(remoteCid, 'ice-disconnected', 2000);
+            }
+            else if (pc.iceConnectionState === 'failed') {
+                this.scheduleIceRestart(remoteCid, 'ice-failed', 0);
+            }
+        };
+        pc.onconnectionstatechange = () => {
+            this.logger?.log('debug', 'WebRTC', `[${remoteCid}] Connection: ${pc.connectionState}`);
+            this.updateAggregateState();
+            if (pc.connectionState === 'connected') {
+                if (peerState.iceRestartTimer) {
+                    window.clearTimeout(peerState.iceRestartTimer);
+                    peerState.iceRestartTimer = null;
+                }
+                peerState.pendingIceRestart = false;
+                return;
+            }
+            if (pc.connectionState === 'disconnected') {
+                this.scheduleIceRestart(remoteCid, 'conn-disconnected', 2000);
+            }
+            else if (pc.connectionState === 'failed') {
+                this.scheduleIceRestart(remoteCid, 'conn-failed', 0);
+            }
+        };
+        pc.onsignalingstatechange = () => {
+            this.updateAggregateState();
+            if (pc.signalingState === 'stable') {
+                if (peerState.offerTimeout) {
+                    window.clearTimeout(peerState.offerTimeout);
+                    peerState.offerTimeout = null;
+                }
+            }
+            if (pc.signalingState === 'stable' && peerState.pendingLocalTrackNegotiation) {
+                this.scheduleLocalTrackNegotiation(remoteCid, peerState);
+            }
+            if (pc.signalingState === 'stable' && peerState.pendingIceRestart) {
+                if (peerState.offerTimeout) {
+                    window.clearTimeout(peerState.offerTimeout);
+                    peerState.offerTimeout = null;
+                }
+                if (!this.isSignalingConnected || !this.shouldIOffer(remoteCid))
+                    return;
+                peerState.pendingIceRestart = false;
+                peerState.lastIceRestartAt = Date.now();
+                void this.createOfferTo(remoteCid, { iceRestart: true });
+            }
+        };
+        pc.onicecandidate = (event) => {
+            if (event.candidate) {
+                const candidate = event.candidate.toJSON();
+                if (!candidate.sdpMid) {
+                    candidate.sdpMid = String(candidate.sdpMLineIndex ?? 0);
+                }
+                this.sendSignalingMessage('ice', { candidate }, remoteCid);
+            }
+        };
+        pc.onnegotiationneeded = async () => {
+            const peer = this.peers.get(remoteCid);
+            if (!peer)
+                return;
+            if (!this.shouldIOffer(remoteCid))
+                return;
+            if (!this.localStream) {
+                peer.pendingLocalTrackNegotiation = true;
+                return;
+            }
+            await this.createOfferTo(remoteCid);
+        };
+        this.peers.set(remoteCid, peerState);
+        return peerState;
+    }
+    cleanupPeer(remoteCid) {
+        const peer = this.peers.get(remoteCid);
+        if (!peer)
+            return;
+        this.clearPeerTimers(peer);
+        peer.pc.close();
+        this.peers.delete(remoteCid);
+        const next = new Map(this.remoteStreams);
+        next.delete(remoteCid);
+        this.remoteStreams = next;
+        this.updateAggregateState();
+    }
+    clearPeerTimers(peer) {
+        if (peer.offerTimeout) {
+            window.clearTimeout(peer.offerTimeout);
+            peer.offerTimeout = null;
+        }
+        if (peer.iceRestartTimer) {
+            window.clearTimeout(peer.iceRestartTimer);
+            peer.iceRestartTimer = null;
+        }
+        if (peer.nonHostFallbackTimer) {
+            window.clearTimeout(peer.nonHostFallbackTimer);
+            peer.nonHostFallbackTimer = null;
+        }
+    }
+    shouldIOffer(remoteCid) {
+        const myId = this.clientId;
+        return typeof myId === 'string' && myId.length > 0 && myId < remoteCid;
+    }
+    async createOfferTo(remoteCid, options) {
+        const peer = this.peers.get(remoteCid);
+        if (!peer)
+            return;
+        if (peer.isMakingOffer) {
+            if (options?.iceRestart)
+                peer.pendingIceRestart = true;
+            return;
+        }
+        try {
+            if (peer.pc.signalingState !== 'stable') {
+                if (options?.iceRestart)
+                    peer.pendingIceRestart = true;
+                return;
+            }
+            peer.isMakingOffer = true;
+            const offer = await peer.pc.createOffer(options);
+            await peer.pc.setLocalDescription(offer);
+            this.sendSignalingMessage('offer', { sdp: offer.sdp }, remoteCid);
+            if (peer.offerTimeout)
+                window.clearTimeout(peer.offerTimeout);
+            peer.offerTimeout = window.setTimeout(() => {
+                peer.offerTimeout = null;
+                const currentPeer = this.peers.get(remoteCid);
+                if (!currentPeer)
+                    return;
+                this.logger?.log('warning', 'WebRTC', `[${remoteCid}] Offer timeout`);
+                currentPeer.pendingIceRestart = true;
+                if (currentPeer.pc.signalingState === 'have-local-offer') {
+                    currentPeer.pc.setLocalDescription({ type: 'rollback' })
+                        .catch(err => this.logger?.log('warning', 'WebRTC', `[${remoteCid}] Rollback failed: ${formatError(err)}`))
+                        .finally(() => this.scheduleIceRestart(remoteCid, 'offer-timeout', 0));
+                }
+                else {
+                    this.scheduleIceRestart(remoteCid, 'offer-timeout-unexpected-state', 0);
+                }
+            }, OFFER_TIMEOUT_MS);
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `[${remoteCid}] Error creating offer: ${formatError(err)}`);
+        }
+        finally {
+            peer.isMakingOffer = false;
+            if (peer.pendingIceRestart) {
+                peer.pendingIceRestart = false;
+                this.scheduleIceRestart(remoteCid, 'pending-retry', 500);
+            }
+        }
+    }
+    scheduleIceRestart(remoteCid, reason, delayMs) {
+        const peer = this.peers.get(remoteCid);
+        if (!peer)
+            return;
+        if (!this.isSignalingConnected) {
+            peer.pendingIceRestart = true;
+            return;
+        }
+        if (peer.iceRestartTimer)
+            return;
+        if (Date.now() - peer.lastIceRestartAt < ICE_RESTART_COOLDOWN_MS)
+            return;
+        peer.iceRestartTimer = window.setTimeout(() => {
+            peer.iceRestartTimer = null;
+            void this.triggerIceRestart(remoteCid, reason);
+        }, delayMs);
+    }
+    async triggerIceRestart(remoteCid, reason) {
+        const peer = this.peers.get(remoteCid);
+        if (!peer)
+            return;
+        if (!this.isSignalingConnected) {
+            peer.pendingIceRestart = true;
+            return;
+        }
+        if (!this.shouldIOffer(remoteCid))
+            return;
+        if (peer.isMakingOffer) {
+            peer.pendingIceRestart = true;
+            return;
+        }
+        peer.lastIceRestartAt = Date.now();
+        peer.pendingIceRestart = false;
+        this.logger?.log('warning', 'WebRTC', `ICE restart triggered for ${remoteCid} (${reason})`);
+        await this.createOfferTo(remoteCid, { iceRestart: true });
+    }
+    scheduleNonHostFallback(remoteCid) {
+        if (this.shouldIOffer(remoteCid))
+            return;
+        const peer = this.peers.get(remoteCid);
+        if (!peer || peer.nonHostFallbackTimer)
+            return;
+        if (peer.nonHostFallbackAttempts >= NON_HOST_FALLBACK_MAX_ATTEMPTS)
+            return;
+        peer.nonHostFallbackTimer = window.setTimeout(async () => {
+            peer.nonHostFallbackTimer = null;
+            const currentPeer = this.peers.get(remoteCid);
+            if (!currentPeer)
+                return;
+            if (this.shouldIOffer(remoteCid))
+                return;
+            if (currentPeer.pc.remoteDescription)
+                return;
+            if (currentPeer.pc.signalingState !== 'stable')
+                return;
+            if (!this.isSignalingConnected)
+                return;
+            currentPeer.nonHostFallbackAttempts++;
+            this.logger?.log('warning', 'WebRTC', `[${remoteCid}] Non-host fallback offer (attempt ${currentPeer.nonHostFallbackAttempts})`);
+            try {
+                const offer = await currentPeer.pc.createOffer();
+                await currentPeer.pc.setLocalDescription(offer);
+                this.sendSignalingMessage('offer', { sdp: offer.sdp }, remoteCid);
+                if (currentPeer.offerTimeout)
+                    window.clearTimeout(currentPeer.offerTimeout);
+                currentPeer.offerTimeout = window.setTimeout(async () => {
+                    currentPeer.offerTimeout = null;
+                    const p = this.peers.get(remoteCid);
+                    if (!p)
+                        return;
+                    if (p.pc.signalingState === 'have-local-offer') {
+                        try {
+                            await p.pc.setLocalDescription({ type: 'rollback' });
+                        }
+                        catch (err) {
+                            this.logger?.log('warning', 'WebRTC', `[${remoteCid}] Non-host rollback failed: ${formatError(err)}`);
+                        }
+                    }
+                    this.scheduleNonHostFallback(remoteCid);
+                }, OFFER_TIMEOUT_MS);
+            }
+            catch (err) {
+                this.logger?.log('error', 'WebRTC', `[${remoteCid}] Non-host fallback offer failed: ${formatError(err)}`);
+                this.scheduleNonHostFallback(remoteCid);
+            }
+        }, NON_HOST_FALLBACK_DELAY_MS);
+    }
+    async handleOfferFrom(fromCid, sdp) {
+        try {
+            const peer = this.getOrCreatePeer(fromCid);
+            if (peer.nonHostFallbackTimer) {
+                window.clearTimeout(peer.nonHostFallbackTimer);
+                peer.nonHostFallbackTimer = null;
+            }
+            await peer.pc.setRemoteDescription(new RTCSessionDescription({ type: 'offer', sdp }));
+            if (peer.offerTimeout) {
+                window.clearTimeout(peer.offerTimeout);
+                peer.offerTimeout = null;
+            }
+            while (peer.iceBuffer.length > 0) {
+                const c = peer.iceBuffer.shift();
+                if (c)
+                    await peer.pc.addIceCandidate(c);
+            }
+            const answer = await peer.pc.createAnswer();
+            await peer.pc.setLocalDescription(answer);
+            this.sendSignalingMessage('answer', { sdp: answer.sdp }, fromCid);
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `[${fromCid}] Error handling offer: ${formatError(err)}`);
+        }
+    }
+    async handleAnswerFrom(fromCid, sdp) {
+        try {
+            const peer = this.peers.get(fromCid);
+            if (!peer)
+                return;
+            if (peer.nonHostFallbackTimer) {
+                window.clearTimeout(peer.nonHostFallbackTimer);
+                peer.nonHostFallbackTimer = null;
+            }
+            await peer.pc.setRemoteDescription(new RTCSessionDescription({ type: 'answer', sdp }));
+            if (peer.offerTimeout) {
+                window.clearTimeout(peer.offerTimeout);
+                peer.offerTimeout = null;
+            }
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `[${fromCid}] Error handling answer: ${formatError(err)}`);
+        }
+    }
+    async handleIceFrom(fromCid, candidate) {
+        try {
+            const peer = this.getOrCreatePeer(fromCid);
+            if (peer.pc.remoteDescription) {
+                await peer.pc.addIceCandidate(candidate);
+            }
+            else {
+                if (peer.iceBuffer.length >= ICE_CANDIDATE_BUFFER_MAX)
+                    peer.iceBuffer.shift();
+                peer.iceBuffer.push(candidate);
+            }
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `[${fromCid}] Error handling ICE candidate: ${formatError(err)}`);
+        }
+    }
+    updateAggregateState() {
+        const peers = this.peers;
+        let worstIce = peers.size === 0 ? 'new' : 'completed';
+        let worstConn = peers.size === 0 ? 'new' : 'connected';
+        let worstSig = peers.size === 0 ? 'stable' : 'stable';
+        if (peers.size > 0) {
+            for (const [, peer] of peers) {
+                const ice = peer.pc.iceConnectionState;
+                const conn = peer.pc.connectionState;
+                const sig = peer.pc.signalingState;
+                if (ICE_STATE_PRIORITY.indexOf(ice) < ICE_STATE_PRIORITY.indexOf(worstIce))
+                    worstIce = ice;
+                if (CONN_STATE_PRIORITY.indexOf(conn) < CONN_STATE_PRIORITY.indexOf(worstConn))
+                    worstConn = conn;
+                if (SIG_STATE_PRIORITY.indexOf(sig) < SIG_STATE_PRIORITY.indexOf(worstSig))
+                    worstSig = sig;
+            }
+        }
+        this.iceConnectionState = worstIce;
+        this.connectionState = worstConn;
+        this.signalingState = worstSig;
+        this.updateConnectionStatusValue();
+        this.notifyChange();
+    }
+    updateConnectionStatusValue() {
+        const isActive = !!this.roomState && (this.roomState.participants?.length ?? 0) > 1;
+        if (!isActive) {
+            this.resetConnectionStatusMachine();
+            return;
+        }
+        const isDegraded = !this.isSignalingConnected ||
+            this.iceConnectionState === 'disconnected' || this.iceConnectionState === 'failed' ||
+            this.connectionState === 'disconnected' || this.connectionState === 'failed';
+        if (isDegraded) {
+            this.setConnectionRecovering();
+            return;
+        }
+        this.resetConnectionStatusMachine();
+    }
+    resetConnectionStatusMachine() {
+        if (this.retryingTimer) {
+            window.clearTimeout(this.retryingTimer);
+            this.retryingTimer = null;
+        }
+        this.connectionStatus = 'connected';
+    }
+    setConnectionRecovering() {
+        if (this.connectionStatus === 'connected')
+            this.connectionStatus = 'recovering';
+        if (this.connectionStatus !== 'retrying')
+            this.scheduleRetryingTransition();
+    }
+    scheduleRetryingTransition() {
+        if (this.retryingTimer)
+            return;
+        this.retryingTimer = window.setTimeout(() => {
+            this.retryingTimer = null;
+            if (this.connectionStatus === 'recovering')
+                this.connectionStatus = 'retrying';
+            this.notifyChange();
+        }, CONNECTION_RETRYING_DELAY_MS);
+    }
+    normalizeIceServers(iceServers) {
+        return normalizeIceServers(iceServers, this.turnsOnly);
+    }
+    applySpeechTrackHints(stream) {
+        const audioTrack = stream.getAudioTracks()[0];
+        if (!audioTrack)
+            return;
+        if ('contentHint' in audioTrack) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- contentHint is a valid but untyped browser API
+            try {
+                audioTrack.contentHint = 'speech';
+            }
+            catch { /* ignore */ }
+        }
+    }
+    async applyAudioSenderParameters(pc) {
+        const sender = pc.getSenders().find(s => s.track?.kind === 'audio');
+        if (!sender?.getParameters || !sender?.setParameters)
+            return;
+        try {
+            const params = sender.getParameters();
+            if (!params.encodings || params.encodings.length === 0)
+                return;
+            const firstEncoding = params.encodings[0];
+            if (!firstEncoding || firstEncoding.maxBitrate === 32000)
+                return;
+            const nextParams = {
+                ...params,
+                encodings: params.encodings.map((encoding, index) => (index === 0 ? { ...encoding, maxBitrate: 32000 } : encoding)),
+            };
+            await sender.setParameters(nextParams);
+        }
+        catch (err) {
+            this.logger?.log('warning', 'WebRTC', `Failed to apply audio sender parameters: ${formatError(err)}`);
+        }
+    }
+    async acquireCameraTrack(targetFacingMode, enabled) {
+        let cameraStream;
+        try {
+            cameraStream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: targetFacingMode }, audio: false });
+        }
+        catch {
+            cameraStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
+        }
+        const cameraTrack = cameraStream.getVideoTracks()[0];
+        if (!cameraTrack) {
+            cameraStream.getTracks().forEach(track => track.stop());
+            throw new Error('No camera track returned');
+        }
+        cameraTrack.enabled = enabled;
+        return cameraTrack;
+    }
+    async replaceVideoTrackOnAllPeers(newTrack, stream) {
+        await Promise.all(Array.from(this.peers.entries()).map(async ([remoteCid, peer]) => {
+            const videoTransceiver = this.findTransceiver(peer.pc, 'video');
+            if (videoTransceiver) {
+                try {
+                    await videoTransceiver.sender.replaceTrack(newTrack);
+                    if (videoTransceiver.direction !== 'sendrecv' && videoTransceiver.direction !== 'stopped' && this.videoCaptureSupported) {
+                        videoTransceiver.direction = 'sendrecv';
+                        this.scheduleLocalTrackNegotiation(remoteCid, peer);
+                    }
+                }
+                catch (err) {
+                    this.logger?.log('warning', 'WebRTC', `Failed to replace video track on peer: ${formatError(err)}`);
+                }
+                return;
+            }
+            if (newTrack && stream) {
+                try {
+                    peer.pc.addTrack(newTrack, stream);
+                    this.scheduleLocalTrackNegotiation(remoteCid, peer);
+                }
+                catch (err) {
+                    this.logger?.log('warning', 'WebRTC', `Failed to add video track on peer: ${formatError(err)}`);
+                }
+            }
+        }));
+    }
+    async swapLocalVideoTrack(nextTrack, previousTrack) {
+        if (!this.localStream) {
+            if (previousTrack && previousTrack !== nextTrack)
+                previousTrack.stop();
+            return;
+        }
+        const nextStream = new MediaStream();
+        let replacedVideo = false;
+        for (const track of this.localStream.getTracks()) {
+            if (track.kind !== 'video') {
+                nextStream.addTrack(track);
+                continue;
+            }
+            if (!replacedVideo && nextTrack) {
+                nextStream.addTrack(nextTrack);
+                replacedVideo = true;
+            }
+        }
+        if (nextTrack && !replacedVideo) {
+            nextStream.addTrack(nextTrack);
+        }
+        this.localStream = nextStream;
+        await this.replaceVideoTrackOnAllPeers(nextTrack, nextStream);
+        if (previousTrack && previousTrack !== nextTrack)
+            previousTrack.stop();
+        this.notifyChange();
+    }
+    ensureMediaTransceivers(pc) {
+        if (!this.findTransceiver(pc, 'audio') && !pc.getSenders().some(sender => sender.track?.kind === 'audio')) {
+            pc.addTransceiver('audio', { direction: 'recvonly' });
+        }
+        if (!this.findTransceiver(pc, 'video') && !pc.getSenders().some(sender => sender.track?.kind === 'video')) {
+            pc.addTransceiver('video', { direction: this.videoCaptureSupported ? 'sendrecv' : 'recvonly' });
+        }
+    }
+    findTransceiver(pc, kind) {
+        return pc.getTransceivers().find(transceiver => (transceiver.receiver.track?.kind === kind || transceiver.sender.track?.kind === kind));
+    }
+    async attachLocalTracksToPeer(remoteCid, peer, stream) {
+        let negotiationNeeded = false;
+        for (const track of stream.getTracks()) {
+            negotiationNeeded = await this.attachLocalTrackToPeer(peer, track, stream) || negotiationNeeded;
+        }
+        if (negotiationNeeded) {
+            this.scheduleLocalTrackNegotiation(remoteCid, peer);
+        }
+    }
+    async attachLocalTrackToPeer(peer, track, stream) {
+        if (peer.pc.getSenders().some(sender => sender.track?.kind === track.kind)) {
+            return false;
+        }
+        const transceiver = track.kind === 'audio' || track.kind === 'video'
+            ? this.findTransceiver(peer.pc, track.kind)
+            : undefined;
+        if (transceiver) {
+            try {
+                await transceiver.sender.replaceTrack(track);
+                if (transceiver.direction !== 'sendrecv' && transceiver.direction !== 'stopped') {
+                    transceiver.direction = 'sendrecv';
+                    return true;
+                }
+            }
+            catch (err) {
+                this.logger?.log('warning', 'WebRTC', `Failed to attach ${track.kind} track to peer: ${formatError(err)}`);
+            }
+            return false;
+        }
+        peer.pc.addTrack(track, stream);
+        return true;
+    }
+    scheduleLocalTrackNegotiation(remoteCid, peer) {
+        if (!this.isSignalingConnected) {
+            peer.pendingLocalTrackNegotiation = true;
+            return;
+        }
+        if (!this.shouldIOffer(remoteCid) && !peer.pc.remoteDescription) {
+            peer.pendingLocalTrackNegotiation = true;
+            return;
+        }
+        if (peer.pc.signalingState !== 'stable') {
+            peer.pendingLocalTrackNegotiation = true;
+            return;
+        }
+        peer.pendingLocalTrackNegotiation = false;
+        void this.createOfferTo(remoteCid);
+    }
+    async refreshLocalVideoTrack(reason, forceRefresh = false) {
+        const currentVideoTrack = this.localStream?.getVideoTracks()[0] ?? null;
+        const shouldRecover = shouldRecoverLocalVideo({
+            hasVideoTrack: !!currentVideoTrack,
+            isScreenSharing: this.isScreenSharing,
+            videoTrackReadyState: currentVideoTrack?.readyState ?? null,
+            videoTrackMuted: currentVideoTrack?.muted ?? false,
+            forceRefresh
+        });
+        if (!shouldRecover || this.cameraRecoveryInFlight || this.requestingMedia)
+            return false;
+        this.cameraRecoveryInFlight = true;
+        try {
+            const nextTrack = await this.acquireCameraTrack(this.facingMode, currentVideoTrack?.enabled ?? true);
+            await this.swapLocalVideoTrack(nextTrack, currentVideoTrack);
+            this.logger?.log('info', 'WebRTC', `Refreshed local video track (${reason})`);
+            return true;
+        }
+        catch (err) {
+            this.logger?.log('error', 'WebRTC', `Failed to refresh local video track (${reason}): ${formatError(err)}`);
+            return false;
+        }
+        finally {
+            this.cameraRecoveryInFlight = false;
+        }
+    }
+    async detectCameras() {
+        if (!navigator.mediaDevices?.enumerateDevices)
+            return;
+        try {
+            const devices = await navigator.mediaDevices.enumerateDevices();
+            this.hasMultipleCameras = devices.filter(d => d.kind === 'videoinput').length > 1;
+        }
+        catch { /* ignore */ }
+    }
+    setupEventListeners() {
+        this.onlineHandler = () => {
+            for (const [cid] of this.peers)
+                this.scheduleIceRestart(cid, 'network-online', 0);
+        };
+        window.addEventListener('online', this.onlineHandler);
+        this.networkChangeHandler = () => {
+            for (const [cid] of this.peers)
+                this.scheduleIceRestart(cid, 'network-change', 0);
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Network Information API is untyped
+        const conn = navigator.connection;
+        conn?.addEventListener?.('change', this.networkChangeHandler);
+        this.deviceChangeHandler = () => { void this.detectCameras(); };
+        navigator.mediaDevices?.addEventListener?.('devicechange', this.deviceChangeHandler);
+        void this.detectCameras();
+        // Local video recovery
+        const consumeHiddenDuration = () => {
+            const now = Date.now();
+            const hiddenDurationMs = this.localVideoHiddenAt ? now - this.localVideoHiddenAt : null;
+            this.localVideoHiddenAt = null;
+            this.localVideoHeartbeatAt = now;
+            return hiddenDurationMs;
+        };
+        this.visibilityHandler = () => {
+            if (document.hidden) {
+                const now = Date.now();
+                this.localVideoHiddenAt = now;
+                this.localVideoHeartbeatAt = now;
+                return;
+            }
+            const hiddenDurationMs = consumeHiddenDuration();
+            const forceRefresh = shouldForceLocalVideoRefresh({ hiddenDurationMs });
+            void this.refreshLocalVideoTrack('visibility-resume', forceRefresh);
+        };
+        document.addEventListener('visibilitychange', this.visibilityHandler);
+        this.pageShowHandler = (event) => {
+            const hiddenDurationMs = consumeHiddenDuration();
+            const forceRefresh = event.persisted || shouldForceLocalVideoRefresh({ hiddenDurationMs });
+            void this.refreshLocalVideoTrack('pageshow-resume', forceRefresh);
+        };
+        window.addEventListener('pageshow', this.pageShowHandler);
+        this.heartbeatInterval = window.setInterval(() => {
+            const now = Date.now();
+            const sleepGapMs = now - this.localVideoHeartbeatAt;
+            this.localVideoHeartbeatAt = now;
+            if (document.hidden || !shouldForceLocalVideoRefresh({ sleepGapMs }))
+                return;
+            void this.refreshLocalVideoTrack('sleep-resume', true);
+        }, LOCAL_VIDEO_HEARTBEAT_INTERVAL_MS);
+    }
+    removeEventListeners() {
+        if (this.onlineHandler)
+            window.removeEventListener('online', this.onlineHandler);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Network Information API is untyped
+        const conn = navigator.connection;
+        if (this.networkChangeHandler)
+            conn?.removeEventListener?.('change', this.networkChangeHandler);
+        if (this.deviceChangeHandler)
+            navigator.mediaDevices?.removeEventListener?.('devicechange', this.deviceChangeHandler);
+        if (this.visibilityHandler)
+            document.removeEventListener('visibilitychange', this.visibilityHandler);
+        if (this.pageShowHandler)
+            window.removeEventListener('pageshow', this.pageShowHandler);
+        if (this.heartbeatInterval !== null)
+            window.clearInterval(this.heartbeatInterval);
+    }
+    notifyChange() { this.onChange?.(); }
+}
+//# sourceMappingURL=MediaEngine.js.map