@edge-base/web 0.2.5 → 0.2.7

package/dist/room-p2p-media.js

@@ -1,3 +1,4 @@
+import { EdgeBaseError } from '@edge-base/core';
 import { createSubscription } from './room.js';
 const DEFAULT_SIGNAL_PREFIX = 'edgebase.media.p2p';
 const DEFAULT_ICE_SERVERS = [
@@ -12,9 +13,22 @@ const DEFAULT_RATE_LIMIT_RETRY_DELAYS_MS = [160, 320, 640];
 const DEFAULT_MEDIA_HEALTH_CHECK_INTERVAL_MS = 4_000;
 const DEFAULT_VIDEO_FLOW_GRACE_MS = 8_000;
 const DEFAULT_VIDEO_FLOW_STALL_GRACE_MS = 12_000;
+const DEFAULT_INITIAL_NEGOTIATION_GRACE_MS = 5_000;
+const DEFAULT_STUCK_SIGNALING_GRACE_MS = 2_500;
+const DEFAULT_NEGOTIATION_QUEUE_SPACING_MS = 180;
+const DEFAULT_SYNC_REMOVAL_GRACE_MS = 9_000;
+const DEFAULT_TRACK_REMOVAL_GRACE_MS = 2_600;
+const DEFAULT_PENDING_VIDEO_PROMOTION_GRACE_MS = 900;
 function buildTrackKey(memberId, trackId) {
     return `${memberId}:${trackId}`;
 }
+function isMediaStreamTrackLike(value) {
+    return Boolean(value
+        && typeof value === 'object'
+        && 'id' in value
+        && 'kind' in value
+        && 'readyState' in value);
+}
 function buildExactDeviceConstraint(deviceId) {
     return { deviceId: { exact: deviceId } };
 }
@@ -95,16 +109,27 @@ function sameIceServer(candidate, urls) {
     const candidateUrls = normalizeIceServerUrls(candidate.urls);
     return candidateUrls.length === urls.length && candidateUrls.every((url, index) => url === urls[index]);
 }
+function getErrorMessage(error) {
+    if (error instanceof Error && typeof error.message === 'string' && error.message.length > 0) {
+        return error.message;
+    }
+    return 'Unknown room media error.';
+}
 export class RoomP2PMediaTransport {
     room;
     options;
     localTracks = new Map();
     peers = new Map();
     remoteTrackHandlers = [];
+    remoteVideoStateHandlers = [];
     remoteTrackKinds = new Map();
     emittedRemoteTracks = new Set();
     pendingRemoteTracks = new Map();
+    pendingTrackRemovalTimers = new Map();
+    pendingSyncRemovalTimers = new Map();
+    pendingVideoPromotionTimers = new Map();
     pendingIceCandidates = new Map();
+    remoteVideoStreamCache = new Map();
     subscriptions = [];
     localMemberId = null;
     connected = false;
@@ -113,6 +138,10 @@ export class RoomP2PMediaTransport {
     syncAllPeerSendersScheduled = false;
     syncAllPeerSendersPending = false;
     healthCheckTimer = null;
+    negotiationTail = Promise.resolve();
+    remoteVideoStateSignature = '';
+    debugEvents = [];
+    debugEventCounter = 0;
     constructor(room, options) {
         this.room = room;
         this.options = {
@@ -134,6 +163,12 @@ export class RoomP2PMediaTransport {
             mediaHealthCheckIntervalMs: options?.mediaHealthCheckIntervalMs ?? DEFAULT_MEDIA_HEALTH_CHECK_INTERVAL_MS,
             videoFlowGraceMs: options?.videoFlowGraceMs ?? DEFAULT_VIDEO_FLOW_GRACE_MS,
             videoFlowStallGraceMs: options?.videoFlowStallGraceMs ?? DEFAULT_VIDEO_FLOW_STALL_GRACE_MS,
+            initialNegotiationGraceMs: options?.initialNegotiationGraceMs ?? DEFAULT_INITIAL_NEGOTIATION_GRACE_MS,
+            stuckSignalingGraceMs: options?.stuckSignalingGraceMs ?? DEFAULT_STUCK_SIGNALING_GRACE_MS,
+            negotiationQueueSpacingMs: options?.negotiationQueueSpacingMs ?? DEFAULT_NEGOTIATION_QUEUE_SPACING_MS,
+            syncRemovalGraceMs: options?.syncRemovalGraceMs ?? DEFAULT_SYNC_REMOVAL_GRACE_MS,
+            trackRemovalGraceMs: options?.trackRemovalGraceMs ?? DEFAULT_TRACK_REMOVAL_GRACE_MS,
+            pendingVideoPromotionGraceMs: options?.pendingVideoPromotionGraceMs ?? DEFAULT_PENDING_VIDEO_PROMOTION_GRACE_MS,
         };
     }
     getSessionId() {
@@ -149,9 +184,21 @@ export class RoomP2PMediaTransport {
         if (this.connected && this.localMemberId) {
             return this.localMemberId;
         }
+        this.recordDebugEvent('transport:connect');
         if (payload && typeof payload === 'object' && 'sessionDescription' in payload) {
             throw new Error('RoomP2PMediaTransport.connect() does not accept sessionDescription; use room.signals through the built-in transport instead.');
         }
+        const capabilities = await this.collectCapabilities({ includeProviderChecks: false });
+        const fatalIssue = capabilities.issues.find((issue) => issue.fatal);
+        if (fatalIssue) {
+            const error = new EdgeBaseError(400, fatalIssue.message, { preflight: { code: fatalIssue.code, message: fatalIssue.message } }, 'room-media-preflight-failed');
+            Object.assign(error, {
+                provider: capabilities.provider,
+                issue: fatalIssue,
+                capabilities,
+            });
+            throw error;
+        }
         const currentMember = await this.waitForCurrentMember();
         if (!currentMember) {
             throw new Error('Join the room before connecting a P2P media transport.');
@@ -168,6 +215,7 @@ export class RoomP2PMediaTransport {
                     this.ensurePeer(member.memberId);
                 }
             }
+            this.emitRemoteVideoStateChange(true);
         }
         catch (error) {
             this.rollbackConnectedState();
@@ -175,6 +223,257 @@ export class RoomP2PMediaTransport {
         }
         return this.localMemberId;
     }
+    async getCapabilities() {
+        return this.collectCapabilities({ includeProviderChecks: true });
+    }
+    getUsableRemoteVideoStream(memberId) {
+        const now = Date.now();
+        const peer = this.peers.get(memberId);
+        const connectedish = peer
+            ? peer.pc.connectionState === 'connected'
+                || peer.pc.iceConnectionState === 'connected'
+                || peer.pc.iceConnectionState === 'completed'
+            : false;
+        const mediaMembers = this.room.media.list?.() ?? [];
+        const mediaMember = mediaMembers.find((entry) => entry.member.memberId === memberId);
+        const publishedKinds = this.getPublishedVideoLikeKinds(memberId);
+        const stillPublished = publishedKinds.length > 0
+            || Boolean(mediaMember?.state?.video?.published || mediaMember?.state?.screen?.published)
+            || Boolean(mediaMember?.tracks.some((track) => (track.kind === 'video' || track.kind === 'screen') && track.trackId));
+        const flow = peer
+            ? Array.from(peer.remoteVideoFlows.values())
+                .filter((entry) => isMediaStreamTrackLike(entry.track) && entry.track.readyState === 'live')
+                .sort((a, b) => Number((b.lastHealthyAt ?? 0) > 0) - Number((a.lastHealthyAt ?? 0) > 0)
+                || (b.lastHealthyAt ?? 0) - (a.lastHealthyAt ?? 0)
+                || (b.receivedAt ?? 0) - (a.receivedAt ?? 0))[0] ?? null
+            : null;
+        const track = flow?.track;
+        const graceMs = Math.max(this.options.videoFlowGraceMs, this.options.videoFlowStallGraceMs);
+        const connectedTrackGraceMs = Math.max(graceMs, this.options.videoFlowStallGraceMs + 6_000);
+        const lastObservedAt = Math.max(flow?.receivedAt ?? 0, flow?.lastHealthyAt ?? 0);
+        const isRecentLiveFlow = isMediaStreamTrackLike(track)
+            && track.readyState === 'live'
+            && now - (flow?.receivedAt ?? 0) <= graceMs;
+        const isLiveConnectedFlow = isMediaStreamTrackLike(track)
+            && track.readyState === 'live'
+            && connectedish
+            && stillPublished
+            && lastObservedAt > 0
+            && now - lastObservedAt <= connectedTrackGraceMs;
+        const isHealthyFlow = isMediaStreamTrackLike(track)
+            && track.readyState === 'live'
+            && (((flow?.lastHealthyAt ?? 0) > 0) || track.muted === false || isRecentLiveFlow || isLiveConnectedFlow);
+        const cached = this.remoteVideoStreamCache.get(memberId);
+        if (!isHealthyFlow || !isMediaStreamTrackLike(track)) {
+            const pending = this.getPendingRemoteVideoTrack(memberId);
+            if (pending) {
+                this.remoteVideoStreamCache.set(memberId, {
+                    trackId: pending.track.id,
+                    stream: pending.stream,
+                    lastUsableAt: now,
+                });
+                return pending.stream;
+            }
+            if (cached) {
+                const cachedTrack = cached.stream.getVideoTracks?.()[0]
+                    ?? cached.stream.getTracks?.()[0]
+                    ?? null;
+                const cachedTrackStillLive = isMediaStreamTrackLike(cachedTrack)
+                    ? cachedTrack.readyState === 'live'
+                    : true;
+                if (cachedTrackStillLive && now - cached.lastUsableAt <= graceMs) {
+                    return cached.stream;
+                }
+                if (cachedTrackStillLive && connectedish && stillPublished && now - cached.lastUsableAt <= connectedTrackGraceMs) {
+                    return cached.stream;
+                }
+            }
+            this.remoteVideoStreamCache.delete(memberId);
+            return null;
+        }
+        if (cached?.trackId === track.id) {
+            cached.lastUsableAt = now;
+            return cached.stream;
+        }
+        const stream = new MediaStream([track]);
+        this.remoteVideoStreamCache.set(memberId, {
+            trackId: track.id,
+            stream,
+            lastUsableAt: now,
+        });
+        return stream;
+    }
+    getUsableRemoteVideoEntries() {
+        const candidateIds = new Set();
+        for (const memberId of this.peers.keys())
+            candidateIds.add(memberId);
+        for (const pending of this.pendingRemoteTracks.values()) {
+            if (pending?.memberId)
+                candidateIds.add(pending.memberId);
+        }
+        for (const memberId of this.remoteVideoStreamCache.keys())
+            candidateIds.add(memberId);
+        for (const mediaMember of this.room.media.list?.() ?? []) {
+            if (mediaMember?.member?.memberId)
+                candidateIds.add(mediaMember.member.memberId);
+        }
+        const mediaMembers = this.room.media.list?.() ?? [];
+        return Array.from(candidateIds).map((memberId) => {
+            const stream = this.getUsableRemoteVideoStream(memberId);
+            const trackId = stream?.getVideoTracks?.()[0]?.id
+                ?? stream?.getTracks?.()[0]?.id
+                ?? null;
+            const participant = this.findMember(memberId);
+            const displayName = typeof participant?.state?.displayName === 'string'
+                ? participant.state.displayName
+                : undefined;
+            const published = this.getPublishedVideoLikeKinds(memberId).length > 0
+                || mediaMembers.some((entry) => {
+                    if (entry?.member?.memberId !== memberId)
+                        return false;
+                    return Boolean(entry?.state?.video?.published
+                        || entry?.state?.screen?.published
+                        || entry?.tracks?.some((track) => (track.kind === 'video' || track.kind === 'screen') && track.trackId));
+                });
+            return {
+                memberId,
+                userId: participant?.userId,
+                displayName,
+                stream,
+                trackId,
+                published,
+                isCameraOff: !(published || stream instanceof MediaStream),
+            };
+        });
+    }
+    getRemoteVideoStates() {
+        const now = Date.now();
+        return this.getUsableRemoteVideoEntries().map((entry) => ({
+            participantId: entry.memberId,
+            updatedAt: now,
+            ...entry,
+        }));
+    }
+    getActiveRemoteMemberIds() {
+        return this.getRemoteVideoStates()
+            .filter((entry) => entry.stream instanceof MediaStream || entry.published)
+            .map((entry) => entry.memberId);
+    }
+    async collectCapabilities(options) {
+        const issues = [];
+        const currentMember = this.room.members.current();
+        const roomIssueFatal = !currentMember;
+        let room = {
+            ok: true,
+            type: 'room_connect_ready',
+            category: 'ready',
+            message: 'Room WebSocket preflight passed',
+        };
+        if (typeof this.room.checkConnection === 'function') {
+            try {
+                room = await this.room.checkConnection();
+            }
+            catch (error) {
+                issues.push({
+                    code: 'room_connect_check_failed',
+                    category: 'room',
+                    message: `Room connect-check failed: ${getErrorMessage(error)}`,
+                    fatal: roomIssueFatal,
+                });
+            }
+        }
+        if (!room.ok) {
+            issues.push({
+                code: room.type,
+                category: 'room',
+                message: room.message,
+                fatal: roomIssueFatal,
+            });
+        }
+        if (!currentMember) {
+            issues.push({
+                code: 'room_member_not_joined',
+                category: 'room',
+                message: 'Join the room before connecting a P2P media transport.',
+                fatal: true,
+            });
+        }
+        const browser = {
+            mediaDevices: !!this.options.mediaDevices,
+            getUserMedia: typeof this.options.mediaDevices?.getUserMedia === 'function',
+            getDisplayMedia: typeof this.options.mediaDevices?.getDisplayMedia === 'function',
+            enumerateDevices: typeof this.options.mediaDevices?.enumerateDevices === 'function',
+            rtcPeerConnection: typeof this.options.peerConnectionFactory === 'function'
+                || typeof RTCPeerConnection !== 'undefined',
+        };
+        if (!browser.rtcPeerConnection) {
+            issues.push({
+                code: 'webrtc_unavailable',
+                category: 'browser',
+                message: 'RTCPeerConnection is not available in this environment.',
+                fatal: true,
+            });
+        }
+        if (!browser.getUserMedia) {
+            issues.push({
+                code: 'media_devices_get_user_media_unavailable',
+                category: 'browser',
+                message: 'getUserMedia() is not available; local audio/video capture will be unavailable.',
+                fatal: false,
+            });
+        }
+        if (!browser.getDisplayMedia) {
+            issues.push({
+                code: 'media_devices_get_display_media_unavailable',
+                category: 'browser',
+                message: 'getDisplayMedia() is not available; screen sharing will be unavailable.',
+                fatal: false,
+            });
+        }
+        let turn;
+        const loadIceServers = this.room.media.realtime?.iceServers;
+        if (options.includeProviderChecks && typeof loadIceServers === 'function') {
+            turn = {
+                requested: true,
+                available: false,
+                iceServerCount: 0,
+            };
+            try {
+                const response = await loadIceServers({ ttl: this.options.turnCredentialTtlSeconds });
+                const servers = normalizeIceServers(response?.iceServers);
+                turn.available = servers.length > 0;
+                turn.iceServerCount = servers.length;
+                if (!turn.available) {
+                    issues.push({
+                        code: 'turn_credentials_unavailable',
+                        category: 'provider',
+                        message: 'No TURN credentials were returned; the transport will fall back to its configured ICE servers.',
+                        fatal: false,
+                    });
+                }
+            }
+            catch (error) {
+                turn.error = getErrorMessage(error);
+                issues.push({
+                    code: 'turn_credentials_failed',
+                    category: 'provider',
+                    message: `Failed to resolve TURN credentials: ${turn.error}`,
+                    fatal: false,
+                });
+            }
+        }
+        return {
+            provider: 'p2p',
+            canConnect: !issues.some((issue) => issue.fatal),
+            issues,
+            room,
+            joined: !!currentMember,
+            currentMemberId: currentMember?.memberId ?? null,
+            sessionId: this.getSessionId(),
+            browser,
+            turn,
+        };
+    }
     async waitForCurrentMember(timeoutMs = DEFAULT_MEMBER_READY_TIMEOUT_MS) {
         const startedAt = Date.now();
         while (Date.now() - startedAt < timeoutMs) {
@@ -337,6 +636,67 @@ export class RoomP2PMediaTransport {
             }
         });
     }
+    onRemoteVideoStateChange(handler) {
+        this.remoteVideoStateHandlers.push(handler);
+        try {
+            handler(this.getRemoteVideoStates());
+        }
+        catch {
+            // Ignore eager remote video state handler failures.
+        }
+        return createSubscription(() => {
+            const index = this.remoteVideoStateHandlers.indexOf(handler);
+            if (index >= 0) {
+                this.remoteVideoStateHandlers.splice(index, 1);
+            }
+        });
+    }
+    getDebugSnapshot() {
+        return {
+            localMemberId: this.localMemberId ?? null,
+            connected: Boolean(this.connected),
+            iceServersResolved: Boolean(this.iceServersResolved),
+            localTracks: Array.from(this.localTracks.entries()).map(([kind, localTrack]) => ({
+                kind,
+                trackId: localTrack.track?.id ?? null,
+                readyState: localTrack.track?.readyState ?? null,
+                enabled: localTrack.track?.enabled ?? null,
+            })),
+            peers: Array.from(this.peers.values()).map((peer) => ({
+                memberId: peer.memberId,
+                polite: peer.polite,
+                makingOffer: peer.makingOffer,
+                ignoreOffer: peer.ignoreOffer,
+                pendingNegotiation: peer.pendingNegotiation,
+                recoveryAttempts: peer.recoveryAttempts,
+                signalingState: peer.pc?.signalingState ?? null,
+                connectionState: peer.pc?.connectionState ?? null,
+                iceConnectionState: peer.pc?.iceConnectionState ?? null,
+                senderKinds: Array.from(peer.senders.keys()),
+                senderTrackIds: Array.from(peer.senders.values()).map((sender) => sender.track?.id ?? null),
+                receiverTrackIds: peer.pc?.getReceivers?.().map((receiver) => receiver.track?.id ?? null) ?? [],
+                receiverTrackKinds: peer.pc?.getReceivers?.().map((receiver) => receiver.track?.kind ?? null) ?? [],
+                pendingCandidates: peer.pendingCandidates?.length ?? 0,
+                remoteVideoFlows: Array.from(peer.remoteVideoFlows.values()).map((flow) => ({
+                    trackId: flow.track?.id ?? null,
+                    readyState: flow.track?.readyState ?? null,
+                    muted: flow.track?.muted ?? null,
+                    receivedAt: flow.receivedAt ?? null,
+                    lastHealthyAt: flow.lastHealthyAt ?? null,
+                })),
+            })),
+            pendingRemoteTracks: Array.from(this.pendingRemoteTracks.values()).map((pending) => ({
+                memberId: pending.memberId,
+                trackId: pending.track?.id ?? null,
+                trackKind: pending.track?.kind ?? null,
+                readyState: pending.track?.readyState ?? null,
+                muted: pending.track?.muted ?? null,
+            })),
+            remoteTrackKinds: Array.from(this.remoteTrackKinds.entries()),
+            emittedRemoteTracks: Array.from(this.emittedRemoteTracks.values()),
+            recentEvents: this.debugEvents.slice(-120),
+        };
+    }
     destroy() {
         this.connected = false;
         this.localMemberId = null;
@@ -359,10 +719,24 @@ export class RoomP2PMediaTransport {
                 clearTimeout(pending.timer);
             }
         }
+        for (const timer of this.pendingTrackRemovalTimers.values()) {
+            globalThis.clearTimeout(timer);
+        }
+        for (const timer of this.pendingSyncRemovalTimers.values()) {
+            globalThis.clearTimeout(timer);
+        }
+        for (const timer of this.pendingVideoPromotionTimers.values()) {
+            globalThis.clearTimeout(timer);
+        }
+        this.pendingTrackRemovalTimers.clear();
+        this.pendingSyncRemovalTimers.clear();
+        this.pendingVideoPromotionTimers.clear();
         this.pendingIceCandidates.clear();
         this.remoteTrackKinds.clear();
         this.emittedRemoteTracks.clear();
         this.pendingRemoteTracks.clear();
+        this.remoteVideoStreamCache.clear();
+        this.emitRemoteVideoStateChange(true);
     }
     attachRoomSubscriptions() {
         if (this.subscriptions.length > 0) {
@@ -370,25 +744,29 @@ export class RoomP2PMediaTransport {
         }
         this.subscriptions.push(this.room.members.onJoin((member) => {
             if (member.memberId !== this.localMemberId) {
-                this.ensurePeer(member.memberId);
-                this.schedulePeerRecoveryCheck(member.memberId, 'member-join');
+                this.cancelPendingSyncRemoval(member.memberId);
+                this.ensurePeer(member.memberId, { passive: true });
+                this.emitRemoteVideoStateChange();
             }
         }), this.room.members.onSync((members) => {
             const activeMemberIds = new Set();
             for (const member of members) {
                 if (member.memberId !== this.localMemberId) {
                     activeMemberIds.add(member.memberId);
-                    this.ensurePeer(member.memberId);
-                    this.schedulePeerRecoveryCheck(member.memberId, 'member-sync');
+                    this.cancelPendingSyncRemoval(member.memberId);
+                    this.ensurePeer(member.memberId, { passive: true });
                 }
             }
             for (const memberId of Array.from(this.peers.keys())) {
                 if (!activeMemberIds.has(memberId)) {
-                    this.removeRemoteMember(memberId);
+                    this.scheduleSyncRemoval(memberId);
                 }
             }
+            this.emitRemoteVideoStateChange();
         }), this.room.members.onLeave((member) => {
+            this.cancelPendingSyncRemoval(member.memberId);
             this.removeRemoteMember(member.memberId);
+            this.emitRemoteVideoStateChange();
         }), this.room.signals.on(this.offerEvent, (payload, meta) => {
             void this.handleDescriptionSignal('offer', payload, meta);
         }), this.room.signals.on(this.answerEvent, (payload, meta) => {
@@ -397,26 +775,26 @@ export class RoomP2PMediaTransport {
             void this.handleIceSignal(payload, meta);
         }), this.room.media.onTrack((track, member) => {
             if (member.memberId !== this.localMemberId) {
-                this.ensurePeer(member.memberId);
+                this.ensurePeer(member.memberId, { passive: true });
                 this.schedulePeerRecoveryCheck(member.memberId, 'media-track');
             }
             this.rememberRemoteTrackKind(track, member);
+            this.emitRemoteVideoStateChange();
         }), this.room.media.onTrackRemoved((track, member) => {
             if (!track.trackId)
                 return;
-            const key = buildTrackKey(member.memberId, track.trackId);
-            this.remoteTrackKinds.delete(key);
-            this.emittedRemoteTracks.delete(key);
-            this.pendingRemoteTracks.delete(key);
-            this.schedulePeerRecoveryCheck(member.memberId, 'media-track-removed');
+            this.scheduleTrackRemoval(track, member);
+            this.emitRemoteVideoStateChange();
         }));
         if (typeof this.room.media.onStateChange === 'function') {
             this.subscriptions.push(this.room.media.onStateChange((member, state) => {
                 if (member.memberId === this.localMemberId) {
                     return;
                 }
+                this.ensurePeer(member.memberId, { passive: true });
                 this.rememberRemoteTrackKindsFromState(member, state);
                 this.schedulePeerRecoveryCheck(member.memberId, 'media-state');
+                this.emitRemoteVideoStateChange();
             }));
         }
     }
@@ -465,15 +843,20 @@ export class RoomP2PMediaTransport {
         const pending = this.pendingRemoteTracks.get(key);
         if (pending) {
             this.pendingRemoteTracks.delete(key);
+            this.clearPendingVideoPromotionTimer(key);
             this.emitRemoteTrack(member.memberId, pending.track, pending.stream, track.kind);
             return;
         }
         this.flushPendingRemoteTracks(member.memberId, track.kind);
     }
-    ensurePeer(memberId) {
+    ensurePeer(memberId, options) {
+        const passive = options?.passive === true;
         const existing = this.peers.get(memberId);
         if (existing) {
-            this.syncPeerSenders(existing);
+            if (!passive) {
+                existing.bootstrapPassive = false;
+                this.syncPeerSenders(existing);
+            }
             return existing;
         }
         const pc = this.options.peerConnectionFactory(this.options.rtcConfiguration);
@@ -481,6 +864,7 @@ export class RoomP2PMediaTransport {
             memberId,
             pc,
             polite: !!this.localMemberId && this.localMemberId.localeCompare(memberId) > 0,
+            bootstrapPassive: passive,
             makingOffer: false,
             ignoreOffer: false,
             isSettingRemoteAnswerPending: false,
@@ -490,6 +874,9 @@ export class RoomP2PMediaTransport {
             recoveryAttempts: 0,
             recoveryTimer: null,
             healthCheckInFlight: false,
+            createdAt: Date.now(),
+            signalingStateChangedAt: Date.now(),
+            hasRemoteDescription: false,
             remoteVideoFlows: new Map(),
         };
         pc.onicecandidate = (event) => {
@@ -500,9 +887,13 @@ export class RoomP2PMediaTransport {
             this.queueIceCandidate(memberId, serializeCandidate(event.candidate));
         };
         pc.onnegotiationneeded = () => {
+            if (peer.bootstrapPassive && !peer.hasRemoteDescription && peer.pc.signalingState === 'stable') {
+                return;
+            }
             void this.negotiatePeer(peer);
         };
         pc.onsignalingstatechange = () => {
+            peer.signalingStateChangedAt = Date.now();
             this.maybeRetryPendingNegotiation(peer);
         };
         pc.oniceconnectionstatechange = () => {
@@ -520,49 +911,88 @@ export class RoomP2PMediaTransport {
             const kind = exactKind ?? fallbackKind ?? normalizeTrackKind(event.track);
             if (!kind || (!exactKind && !fallbackKind && kind === 'video' && event.track.kind === 'video')) {
                 this.pendingRemoteTracks.set(key, { memberId, track: event.track, stream });
+                this.schedulePendingVideoPromotion(memberId, event.track, stream);
                 return;
             }
+            this.clearPendingVideoPromotionTimer(key);
             this.emitRemoteTrack(memberId, event.track, stream, kind);
             this.registerPeerRemoteTrack(peer, event.track, kind);
             this.resetPeerRecovery(peer);
         };
         this.peers.set(memberId, peer);
-        this.syncPeerSenders(peer);
-        this.schedulePeerRecoveryCheck(memberId, 'peer-created');
+        if (!peer.bootstrapPassive) {
+            this.syncPeerSenders(peer);
+            this.schedulePeerRecoveryCheck(memberId, 'peer-created');
+        }
         return peer;
     }
     async negotiatePeer(peer) {
-        if (!this.connected
-            || peer.pc.connectionState === 'closed') {
-            return;
-        }
-        if (peer.makingOffer
-            || peer.isSettingRemoteAnswerPending
-            || peer.pc.signalingState !== 'stable') {
-            peer.pendingNegotiation = true;
+        if (peer.answeringOffer) {
+            peer.pendingNegotiation = false;
             return;
         }
-        try {
-            peer.pendingNegotiation = false;
-            peer.makingOffer = true;
-            await peer.pc.setLocalDescription();
-            if (!peer.pc.localDescription) {
+        const runNegotiation = async () => {
+            if (!this.connected || peer.pc.connectionState === 'closed') {
                 return;
             }
-            await this.sendSignalWithRetry(peer.memberId, this.offerEvent, {
-                description: serializeDescription(peer.pc.localDescription),
-            });
-        }
-        catch (error) {
-            console.warn('[RoomP2PMediaTransport] Failed to negotiate peer offer.', {
-                memberId: peer.memberId,
-                signalingState: peer.pc.signalingState,
-                error,
-            });
+            if (peer.makingOffer
+                || peer.isSettingRemoteAnswerPending
+                || peer.pc.signalingState !== 'stable') {
+                peer.pendingNegotiation = true;
+                return;
+            }
+            try {
+                peer.pendingNegotiation = false;
+                peer.makingOffer = true;
+                await peer.pc.setLocalDescription();
+                const localDescription = peer.pc.localDescription;
+                const signalingState = peer.pc.signalingState;
+                if (!localDescription) {
+                    return;
+                }
+                if (localDescription.type !== 'offer'
+                    || signalingState !== 'have-local-offer') {
+                    return;
+                }
+                await this.sendSignalWithRetry(peer.memberId, this.offerEvent, {
+                    description: serializeDescription(localDescription),
+                });
+            }
+            catch (error) {
+                console.warn('[RoomP2PMediaTransport] Failed to negotiate peer offer.', {
+                    memberId: peer.memberId,
+                    signalingState: peer.pc.signalingState,
+                    error,
+                });
+            }
+            finally {
+                peer.makingOffer = false;
+                this.maybeRetryPendingNegotiation(peer);
+            }
+        };
+        const shouldSerializeBootstrap = !peer.hasRemoteDescription
+            && (peer.pc.connectionState === 'new' || peer.pc.connectionState === 'connecting');
+        if (!shouldSerializeBootstrap) {
+            await runNegotiation();
+            return;
         }
-        finally {
-            peer.makingOffer = false;
+        const bootstrapQueue = peer;
+        if (bootstrapQueue.bootstrapNegotiationQueued) {
+            peer.pendingNegotiation = true;
+            return;
         }
+        bootstrapQueue.bootstrapNegotiationQueued = true;
+        const queuedRun = this.negotiationTail
+            .catch(() => { })
+            .then(async () => {
+            await runNegotiation();
+            await new Promise((resolve) => globalThis.setTimeout(resolve, this.options.negotiationQueueSpacingMs));
+        })
+            .finally(() => {
+            bootstrapQueue.bootstrapNegotiationQueued = false;
+        });
+        this.negotiationTail = queuedRun;
+        await queuedRun;
     }
     async handleDescriptionSignal(expectedType, payload, meta) {
         const senderId = typeof meta.memberId === 'string' && meta.memberId.trim() ? meta.memberId.trim() : '';
@@ -594,17 +1024,30 @@ export class RoomP2PMediaTransport {
             }
             peer.isSettingRemoteAnswerPending = description.type === 'answer';
             await peer.pc.setRemoteDescription(description);
+            peer.hasRemoteDescription = true;
+            peer.bootstrapPassive = false;
             peer.isSettingRemoteAnswerPending = false;
             await this.flushPendingCandidates(peer);
             if (description.type === 'offer') {
-                this.syncPeerSenders(peer);
-                await peer.pc.setLocalDescription();
-                if (!peer.pc.localDescription) {
-                    return;
+                peer.answeringOffer = true;
+                try {
+                    this.syncPeerSenders(peer);
+                    await peer.pc.setLocalDescription();
+                    const localDescription = peer.pc.localDescription;
+                    if (!localDescription) {
+                        return;
+                    }
+                    if (localDescription.type !== 'answer') {
+                        return;
+                    }
+                    await this.sendSignalWithRetry(senderId, this.answerEvent, {
+                        description: serializeDescription(localDescription),
+                    });
+                }
+                finally {
+                    peer.answeringOffer = false;
+                    peer.pendingNegotiation = false;
                 }
-                await this.sendSignalWithRetry(senderId, this.answerEvent, {
-                    description: serializeDescription(peer.pc.localDescription),
-                });
             }
         }
         catch (error) {
@@ -792,8 +1235,12 @@ export class RoomP2PMediaTransport {
             stream,
             trackName: track.id,
             providerSessionId: memberId,
+            memberId,
             participantId: memberId,
             userId: participant?.userId,
+            displayName: typeof participant?.state?.displayName === 'string'
+                ? participant.state.displayName
+                : undefined,
         };
         for (const handler of this.remoteTrackHandlers) {
             handler(payload);
@@ -807,6 +1254,7 @@ export class RoomP2PMediaTransport {
                 this.schedulePeerRecoveryCheck(memberId, 'partial-remote-track');
             }
         }
+        this.emitRemoteVideoStateChange();
     }
     resolveFallbackRemoteTrackKind(memberId, track) {
         const normalizedKind = normalizeTrackKind(track);
@@ -825,10 +1273,68 @@ export class RoomP2PMediaTransport {
                 continue;
             }
             this.pendingRemoteTracks.delete(key);
+            this.clearPendingVideoPromotionTimer(key);
             this.emitRemoteTrack(memberId, pending.track, pending.stream, roomKind);
             return;
         }
     }
+    hasReplacementTrack(memberId, removedTrackId) {
+        const peer = this.peers.get(memberId);
+        const hasLiveTrackedReplacement = Array.from(peer?.remoteVideoFlows?.values() ?? []).some((flow) => {
+            const track = flow?.track;
+            return isMediaStreamTrackLike(track) && track.id !== removedTrackId && track.readyState === 'live';
+        });
+        if (hasLiveTrackedReplacement) {
+            return true;
+        }
+        return Array.from(this.pendingRemoteTracks.values()).some((pending) => pending.memberId === memberId
+            && pending.track.kind === 'video'
+            && pending.track.id !== removedTrackId
+            && pending.track.readyState === 'live');
+    }
+    isRoomTrackStillPublished(memberId, removedTrack) {
+        const mediaMember = this.room.media.list().find((entry) => entry.member.memberId === memberId);
+        if (!mediaMember) {
+            return false;
+        }
+        const kind = removedTrack.kind;
+        if (kind === 'audio' || kind === 'video' || kind === 'screen') {
+            const kindState = mediaMember.state?.[kind];
+            if (kindState?.published) {
+                if (!removedTrack.trackId || kindState.trackId !== removedTrack.trackId) {
+                    return true;
+                }
+            }
+        }
+        return mediaMember.tracks.some((track) => track.kind === removedTrack.kind
+            && Boolean(track.trackId)
+            && (!removedTrack.trackId || track.trackId !== removedTrack.trackId));
+    }
+    scheduleTrackRemoval(track, member) {
+        if (!track.trackId || !member.memberId) {
+            return;
+        }
+        const key = buildTrackKey(member.memberId, track.trackId);
+        const existingTimer = this.pendingTrackRemovalTimers.get(key);
+        if (existingTimer) {
+            globalThis.clearTimeout(existingTimer);
+        }
+        this.pendingTrackRemovalTimers.set(key, globalThis.setTimeout(() => {
+            this.pendingTrackRemovalTimers.delete(key);
+            const replacementTrack = (track.kind === 'video' || track.kind === 'screen')
+                && this.hasReplacementTrack(member.memberId, track.trackId);
+            const stillPublished = this.isRoomTrackStillPublished(member.memberId, track);
+            if (replacementTrack || stillPublished) {
+                return;
+            }
+            this.remoteTrackKinds.delete(key);
+            this.emittedRemoteTracks.delete(key);
+            this.pendingRemoteTracks.delete(key);
+            this.clearPendingVideoPromotionTimer(key);
+            this.schedulePeerRecoveryCheck(member.memberId, 'media-track-removed');
+            this.emitRemoteVideoStateChange();
+        }, this.options.trackRemovalGraceMs));
+    }
     getPublishedVideoLikeKinds(memberId) {
         const mediaMember = this.room.media.list().find((entry) => entry.member.memberId === memberId);
         if (!mediaMember) {
@@ -864,6 +1370,73 @@ export class RoomP2PMediaTransport {
         }
         return publishedKinds.find((kind) => !assignedKinds.has(kind)) ?? null;
     }
+    resolveDeferredVideoKind(memberId) {
+        const publishedKinds = this.getPublishedVideoLikeKinds(memberId);
+        const assignedKinds = new Set();
+        for (const key of this.emittedRemoteTracks) {
+            if (!key.startsWith(`${memberId}:`)) {
+                continue;
+            }
+            const kind = this.remoteTrackKinds.get(key);
+            if (kind === 'video' || kind === 'screen') {
+                assignedKinds.add(kind);
+            }
+        }
+        if (publishedKinds.length === 1) {
+            return publishedKinds[0];
+        }
+        if (publishedKinds.length > 1) {
+            if (assignedKinds.size === 1) {
+                const [kind] = Array.from(assignedKinds.values());
+                if (publishedKinds.includes(kind)) {
+                    return kind;
+                }
+            }
+            return null;
+        }
+        if (assignedKinds.size === 1) {
+            return Array.from(assignedKinds.values())[0];
+        }
+        return null;
+    }
+    schedulePendingVideoPromotion(memberId, track, stream) {
+        const key = buildTrackKey(memberId, track.id);
+        if (this.pendingVideoPromotionTimers.has(key)) {
+            return;
+        }
+        this.pendingVideoPromotionTimers.set(key, globalThis.setTimeout(() => {
+            this.pendingVideoPromotionTimers.delete(key);
+            const pending = this.pendingRemoteTracks.get(key);
+            if (!pending) {
+                return;
+            }
+            if (!isMediaStreamTrackLike(pending.track) || pending.track.readyState !== 'live') {
+                this.pendingRemoteTracks.delete(key);
+                this.emitRemoteVideoStateChange();
+                return;
+            }
+            const promotedKind = this.resolveDeferredVideoKind(memberId);
+            if (!promotedKind) {
+                return;
+            }
+            const peer = this.peers.get(memberId);
+            this.pendingRemoteTracks.delete(key);
+            this.emitRemoteTrack(memberId, pending.track, pending.stream, promotedKind);
+            if (peer) {
+                this.registerPeerRemoteTrack(peer, pending.track, promotedKind);
+                this.resetPeerRecovery(peer);
+            }
+            this.emitRemoteVideoStateChange();
+        }, this.options.pendingVideoPromotionGraceMs));
+    }
+    clearPendingVideoPromotionTimer(key) {
+        const timer = this.pendingVideoPromotionTimers.get(key);
+        if (!timer) {
+            return;
+        }
+        globalThis.clearTimeout(timer);
+        this.pendingVideoPromotionTimers.delete(key);
+    }
     closePeer(memberId) {
         const peer = this.peers.get(memberId);
         if (!peer)
@@ -872,9 +1445,15 @@ export class RoomP2PMediaTransport {
         this.peers.delete(memberId);
     }
     removeRemoteMember(memberId) {
+        this.cancelPendingSyncRemoval(memberId);
         this.remoteTrackKinds.forEach((_kind, key) => {
             if (key.startsWith(`${memberId}:`)) {
                 this.remoteTrackKinds.delete(key);
+                const timer = this.pendingTrackRemovalTimers.get(key);
+                if (timer) {
+                    globalThis.clearTimeout(timer);
+                    this.pendingTrackRemovalTimers.delete(key);
+                }
             }
         });
         this.emittedRemoteTracks.forEach((key) => {
@@ -885,9 +1464,35 @@ export class RoomP2PMediaTransport {
         this.pendingRemoteTracks.forEach((_pending, key) => {
             if (key.startsWith(`${memberId}:`)) {
                 this.pendingRemoteTracks.delete(key);
+                this.clearPendingVideoPromotionTimer(key);
             }
         });
+        this.remoteVideoStreamCache.delete(memberId);
         this.closePeer(memberId);
+        this.emitRemoteVideoStateChange();
+    }
+    scheduleSyncRemoval(memberId) {
+        if (!memberId || memberId === this.localMemberId || this.pendingSyncRemovalTimers.has(memberId)) {
+            return;
+        }
+        this.pendingSyncRemovalTimers.set(memberId, globalThis.setTimeout(() => {
+            this.pendingSyncRemovalTimers.delete(memberId);
+            const stillActive = this.room.members.list().some((member) => member.memberId === memberId);
+            const hasMedia = this.room.media.list().some((entry) => entry.member.memberId === memberId);
+            if (stillActive || hasMedia) {
+                return;
+            }
+            this.removeRemoteMember(memberId);
+            this.emitRemoteVideoStateChange();
+        }, this.options.syncRemovalGraceMs));
+    }
+    cancelPendingSyncRemoval(memberId) {
+        const timer = this.pendingSyncRemovalTimers.get(memberId);
+        if (!timer) {
+            return;
+        }
+        globalThis.clearTimeout(timer);
+        this.pendingSyncRemovalTimers.delete(memberId);
     }
     findMember(memberId) {
         return this.room.members.list().find((member) => member.memberId === memberId);
@@ -911,10 +1516,24 @@ export class RoomP2PMediaTransport {
                 clearTimeout(pending.timer);
             }
         }
+        for (const timer of this.pendingTrackRemovalTimers.values()) {
+            globalThis.clearTimeout(timer);
+        }
+        for (const timer of this.pendingSyncRemovalTimers.values()) {
+            globalThis.clearTimeout(timer);
+        }
+        for (const timer of this.pendingVideoPromotionTimers.values()) {
+            globalThis.clearTimeout(timer);
+        }
+        this.pendingTrackRemovalTimers.clear();
+        this.pendingSyncRemovalTimers.clear();
+        this.pendingVideoPromotionTimers.clear();
         this.pendingIceCandidates.clear();
         this.remoteTrackKinds.clear();
         this.emittedRemoteTracks.clear();
         this.pendingRemoteTracks.clear();
+        this.remoteVideoStreamCache.clear();
+        this.emitRemoteVideoStateChange(true);
     }
     destroyPeer(peer) {
         this.clearPeerRecoveryTimer(peer);
@@ -984,6 +1603,7 @@ export class RoomP2PMediaTransport {
         const handleEnded = () => {
             flow.cleanup();
             peer.remoteVideoFlows.delete(track.id);
+            this.emitRemoteVideoStateChange();
         };
         track.addEventListener('unmute', markHealthy);
         track.addEventListener('ended', handleEnded);
@@ -992,6 +1612,7 @@ export class RoomP2PMediaTransport {
             track.removeEventListener('ended', handleEnded);
         };
         peer.remoteVideoFlows.set(track.id, flow);
+        this.emitRemoteVideoStateChange();
     }
     async inspectPeerVideoHealth(peer) {
         if (this.hasMissingPublishedMedia(peer.memberId)) {
@@ -1074,6 +1695,16 @@ export class RoomP2PMediaTransport {
         if (publishedAt > 0 && Date.now() - publishedAt > this.options.videoFlowGraceMs) {
             return 'health-video-flow-timeout';
         }
+        const signalingState = peer.pc.signalingState;
+        if (signalingState !== 'stable' && signalingState !== 'closed') {
+            const connectionLooksHealthy = peer.pc.connectionState === 'connected'
+                || peer.pc.iceConnectionState === 'connected'
+                || peer.pc.iceConnectionState === 'completed';
+            const signalingAgeMs = Date.now() - (peer.signalingStateChangedAt || peer.createdAt || Date.now());
+            if (connectionLooksHealthy && signalingAgeMs > this.options.stuckSignalingGraceMs) {
+                return `health-stuck-${signalingState}`;
+            }
+        }
         return null;
     }
     async createUserMediaTrack(kind, constraints) {
@@ -1110,6 +1741,16 @@ export class RoomP2PMediaTransport {
         }
         return this.connect();
     }
+    getPendingRemoteVideoTrack(memberId) {
+        for (const pending of this.pendingRemoteTracks.values()) {
+            if (pending.memberId === memberId
+                && pending.track.kind === 'video'
+                && pending.track.readyState === 'live') {
+                return { track: pending.track, stream: pending.stream };
+            }
+        }
+        return null;
+    }
     normalizeDescription(payload) {
         if (!payload || typeof payload !== 'object') {
             return null;
@@ -1191,9 +1832,18 @@ export class RoomP2PMediaTransport {
         }
         const connectionState = peer.pc.connectionState;
         const iceConnectionState = peer.pc.iceConnectionState;
-        if (connectionState === 'connected'
+        const connectedish = connectionState === 'connected'
             || iceConnectionState === 'connected'
-            || iceConnectionState === 'completed') {
+            || iceConnectionState === 'completed';
+        if (connectedish) {
+            const unstableSignaling = peer.pc.signalingState !== 'stable';
+            const missingPublishedMedia = this.hasMissingPublishedMedia(peer.memberId);
+            const allRemoteVideoFlowsUnhealthy = peer.remoteVideoFlows.size > 0
+                && Array.from(peer.remoteVideoFlows.values()).every((flow) => (flow.lastHealthyAt ?? 0) <= 0);
+            if (unstableSignaling || missingPublishedMedia || allRemoteVideoFlowsUnhealthy) {
+                this.schedulePeerRecoveryCheck(peer.memberId, `${source}-connected-but-incomplete`, Math.max(1_200, this.options.missingMediaGraceMs));
+                return;
+            }
             this.resetPeerRecovery(peer);
             return;
         }
@@ -1210,6 +1860,11 @@ export class RoomP2PMediaTransport {
         if (!peer || !this.connected || peer.pc.connectionState === 'closed') {
             return;
         }
+        const peerAgeMs = Date.now() - peer.createdAt;
+        const inInitialBootstrapWindow = !peer.hasRemoteDescription
+            && peer.pc.connectionState === 'new'
+            && peer.pc.iceConnectionState === 'new'
+            && peerAgeMs < this.options.initialNegotiationGraceMs;
         const healthSensitiveReason = reason.includes('health')
             || reason.includes('stalled')
             || reason.includes('flow');
@@ -1220,6 +1875,12 @@ export class RoomP2PMediaTransport {
             this.resetPeerRecovery(peer);
             return;
         }
+        if (inInitialBootstrapWindow
+            && !healthSensitiveReason
+            && !reason.includes('failed')
+            && !reason.includes('disconnected')) {
+            delayMs = Math.max(delayMs, this.options.initialNegotiationGraceMs - peerAgeMs);
+        }
         this.clearPeerRecoveryTimer(peer);
         peer.recoveryTimer = globalThis.setTimeout(() => {
             peer.recoveryTimer = null;
@@ -1242,6 +1903,34 @@ export class RoomP2PMediaTransport {
             this.resetPeerRecovery(peer);
             return;
         }
+        if (healthIssue === 'health-stuck-have-local-offer'
+            && (peer.pc.connectionState === 'connected'
+                || peer.pc.iceConnectionState === 'connected'
+                || peer.pc.iceConnectionState === 'completed')) {
+            try {
+                await peer.pc.setLocalDescription({ type: 'rollback' });
+                peer.pendingNegotiation = true;
+                peer.ignoreOffer = false;
+                this.maybeRetryPendingNegotiation(peer);
+                this.schedulePeerRecoveryCheck(peer.memberId, `${reason}:post-rollback`, 1_200);
+                return;
+            }
+            catch (error) {
+                console.warn('[RoomP2PMediaTransport] Failed to roll back stale local offer.', {
+                    memberId: peer.memberId,
+                    reason,
+                    error,
+                });
+            }
+        }
+        if (healthIssue
+            && healthIssue.startsWith('health-stuck-')
+            && (peer.pc.connectionState === 'connected'
+                || peer.pc.iceConnectionState === 'connected'
+                || peer.pc.iceConnectionState === 'completed')) {
+            this.resetPeer(peer.memberId, `${reason}:${healthIssue}`);
+            return;
+        }
         if (peer.recoveryAttempts >= this.options.maxRecoveryAttempts) {
             this.resetPeer(peer.memberId, reason);
             return;
@@ -1335,5 +2024,43 @@ export class RoomP2PMediaTransport {
         const emittedVideoLikeCount = Array.from(emittedKinds).filter((kind) => kind === 'video' || kind === 'screen').length;
         return emittedVideoLikeCount + pendingVideoLikeCount < expectedVideoLikeKinds.length;
     }
+    emitRemoteVideoStateChange(force = false) {
+        if (this.remoteVideoStateHandlers.length === 0 && !force) {
+            return;
+        }
+        const entries = this.getRemoteVideoStates();
+        const signature = JSON.stringify(entries.map((entry) => ({
+            memberId: entry.memberId,
+            userId: entry.userId ?? null,
+            displayName: entry.displayName ?? null,
+            trackId: entry.trackId ?? null,
+            published: entry.published,
+            isCameraOff: entry.isCameraOff,
+            hasStream: entry.stream instanceof MediaStream,
+        })));
+        if (!force && signature === this.remoteVideoStateSignature) {
+            return;
+        }
+        this.remoteVideoStateSignature = signature;
+        for (const handler of this.remoteVideoStateHandlers) {
+            try {
+                handler(entries.map((entry) => ({ ...entry })));
+            }
+            catch {
+                // Ignore remote video state handler failures.
+            }
+        }
+    }
+    recordDebugEvent(type, details = {}) {
+        this.debugEvents.push({
+            id: ++this.debugEventCounter,
+            at: Date.now(),
+            type,
+            details,
+        });
+        if (this.debugEvents.length > 200) {
+            this.debugEvents.splice(0, this.debugEvents.length - 200);
+        }
+    }
 }
 //# sourceMappingURL=room-p2p-media.js.map