openrtc 0.1.0

package/dist/core/bridges/BrowserFirestoreSignaling.js

@@ -0,0 +1,1010 @@
+import { getFunctions, httpsCallable } from 'firebase/functions';
+import { collection, deleteDoc, doc, getDoc, getDocFromServer, getDocs, getFirestore, limit, onSnapshot, query, serverTimestamp, setDoc, updateDoc, where, } from 'firebase/firestore';
+import { deriveSpaceNamespace } from '../config';
+const DEVICE_STALE_HEARTBEAT_MS = 300000;
+const DEVICE_OFFLINE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const CREATE_SIGNALING_SESSION_FUNCTION = 'createSignalingSession';
+function decodeBase64UrlJsonForLogs(payload) {
+    try {
+        const normalized = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const paddingLen = (4 - (normalized.length % 4)) % 4;
+        const padded = normalized + '='.repeat(paddingLen);
+        if (typeof atob === 'function') {
+            return JSON.parse(atob(padded));
+        }
+        const globalBuffer = globalThis.Buffer;
+        if (globalBuffer) {
+            return JSON.parse(globalBuffer.from(padded, 'base64').toString('utf8'));
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function fingerprintForLogs(value) {
+    if (!value) {
+        return null;
+    }
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fp-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+function summarizeTicketForLogs(ticket) {
+    const trimmed = typeof ticket === 'string' ? ticket.trim() : '';
+    if (!trimmed) {
+        return {
+            present: false,
+        };
+    }
+    const dotIndex = trimmed.lastIndexOf('.');
+    const irohTicket = dotIndex >= 0 ? trimmed.slice(0, dotIndex) : trimmed;
+    const tokenSuffix = dotIndex >= 0 ? trimmed.slice(dotIndex + 1) : null;
+    const decoded = tokenSuffix ? decodeBase64UrlJsonForLogs(tokenSuffix) : null;
+    const token = decoded && typeof decoded.t === 'string' && decoded.t.trim().length > 0
+        ? decoded.t.trim()
+        : null;
+    const scope = decoded && typeof decoded.s === 'string' && decoded.s.trim().length > 0
+        ? decoded.s.trim()
+        : null;
+    const maxConnections = decoded && typeof decoded.m === 'number' && Number.isFinite(decoded.m)
+        ? decoded.m
+        : null;
+    return {
+        present: true,
+        irohFingerprint: fingerprintForLogs(irohTicket),
+        tokenFingerprint: fingerprintForLogs(token),
+        tokenSuffixFingerprint: fingerprintForLogs(tokenSuffix),
+        scope,
+        maxConnections,
+    };
+}
+export class BrowserFirestoreSignaling {
+    constructor(options) {
+        this.options = options;
+        this.deviceListeners = new Map();
+        this.devicesById = new Map();
+        this.staleDeviceOfflineWrites = new Set();
+        this.nextListenerIdSeed = { value: 1 };
+        this.activeDeviceScopeKey = null;
+        this.activeDeviceUnsubscribe = null;
+        this.deviceWatchGeneration = 0;
+        this.namespaceRootPromise = null;
+        // Phase 1: RTDB presence overlay.
+        // deviceTicketCache: one-time getDocs snapshot of Firestore device docs (tickets/metadata).
+        // rtdbPresenceMap: live online/offline boolean map from RTDB, updated in real-time.
+        // knownTicketVersions: last seen ticketVersion per deviceId; if RTDB pushes a new version
+        //   we re-fetch that device's Firestore doc to get the updated ticket.
+        this.rtdbPresence = null;
+        this.rtdbScope = null;
+        this.rtdbPresenceMap = {};
+        this.rtdbUnsubscribe = null;
+        this.knownTicketVersions = new Map();
+        this.firestore = getFirestore(options.app);
+    }
+    /**
+     * Wire in the RTDB presence instance and scope. Called by WasmBridge after
+     * auth is established. Must be called before the first onDevicesChange call
+     * for RTDB presence to take effect. If not called, falls back to the legacy
+     * Firestore onSnapshot watcher (no regression for callers that don't upgrade).
+     */
+    setRtdbPresence(rtdbPresence, scope) {
+        // If scope changed, tear down existing RTDB subscription.
+        if (this.rtdbUnsubscribe) {
+            this.rtdbUnsubscribe();
+            this.rtdbUnsubscribe = null;
+        }
+        this.rtdbPresence = rtdbPresence;
+        this.rtdbScope = scope;
+        this.rtdbPresenceMap = {};
+        this.knownTicketVersions.clear();
+    }
+    /** Stop RTDB subscription and clear scope. Called on sign-out or scope change. */
+    stopRtdbPresence() {
+        this.rtdbUnsubscribe?.();
+        this.rtdbUnsubscribe = null;
+        this.rtdbPresence = null;
+        this.rtdbScope = null;
+        this.rtdbPresenceMap = {};
+        this.knownTicketVersions.clear();
+    }
+    async searchDevices(excludeNodeId) {
+        const snapshot = await this.readCurrentDeviceSnapshot();
+        const devices = snapshot.filter((device) => device.online);
+        if (!excludeNodeId) {
+            return devices;
+        }
+        return this.filterDevices(devices, excludeNodeId);
+    }
+    async subscribeDevices() {
+        const collectionRef = await this.getDevicesCollectionRef();
+        if (!collectionRef) {
+            return new ReadableStream({
+                start(controller) {
+                    controller.close();
+                },
+            });
+        }
+        let unsubscribe = null;
+        return new ReadableStream({
+            start: (controller) => {
+                unsubscribe = onSnapshot(collectionRef, (snapshot) => {
+                    const now = Date.now();
+                    const events = [];
+                    for (const change of snapshot.docChanges()) {
+                        const device = this.toDevice(change.doc, now);
+                        if (change.type === 'removed') {
+                            events.push({ type: 'removed', deviceId: change.doc.id });
+                            continue;
+                        }
+                        if (!device) {
+                            events.push({ type: 'removed', deviceId: change.doc.id });
+                            continue;
+                        }
+                        events.push({
+                            type: change.type === 'added' ? 'added' : 'modified',
+                            device,
+                        });
+                    }
+                    if (events.length > 0) {
+                        controller.enqueue(events);
+                    }
+                }, (error) => controller.error(error));
+            },
+            cancel: () => {
+                unsubscribe?.();
+                unsubscribe = null;
+            },
+        });
+    }
+    onDevicesChange(callback, excludeNodeId) {
+        const listenerId = this.nextListenerIdSeed.value++;
+        this.deviceListeners.set(listenerId, { callback, excludeNodeId });
+        this.emitDevicesToListener(listenerId);
+        void this.ensureDeviceWatch();
+        return () => {
+            this.deviceListeners.delete(listenerId);
+            if (this.deviceListeners.size === 0) {
+                this.stopDeviceWatch({ clearDevices: true });
+            }
+        };
+    }
+    async handleScopeChange() {
+        const hasListeners = this.deviceListeners.size > 0;
+        this.stopDeviceWatch({ clearDevices: true });
+        if (hasListeners) {
+            await this.ensureDeviceWatch();
+        }
+    }
+    stopAuthScopedActivity() {
+        this.stopRtdbPresence();
+        this.stopDeviceWatch({ clearDevices: true });
+    }
+    async updatePresence(localNodeId, ticketStr, isOnline, ttlMs, metadata, deviceNameOverride) {
+        const deviceRef = await this.resolveOrCreateLocalDeviceRef();
+        if (!deviceRef) {
+            return;
+        }
+        const deviceId = this.options.getLocalDeviceId();
+        const now = Date.now();
+        const deviceName = deviceNameOverride?.trim() || this.options.getDefaultDeviceName();
+        const userId = this.options.getCurrentUserId();
+        const expiresAt = isOnline
+            ? now + Math.max(0, Math.trunc(ttlMs))
+            : now + DEVICE_OFFLINE_RETENTION_MS;
+        const existing = await getDoc(deviceRef).catch(() => null);
+        const payload = {
+            appTag: this.options.appTag,
+            tag: this.options.appTag,
+            kind: 'device',
+            deviceId,
+            deviceName,
+            nodeId: localNodeId,
+            platformType: 'web',
+            online: isOnline,
+            ticket: ticketStr,
+            metadata: metadata ?? null,
+            capabilities: {
+                canHost: false,
+                canSync: false,
+                readOnly: false,
+            },
+            lastSeenAt: serverTimestamp(),
+            updatedAt: serverTimestamp(),
+            expiresAt,
+        };
+        if (userId) {
+            payload.userId = userId;
+        }
+        if (!existing?.exists()) {
+            payload.createdAt = serverTimestamp();
+        }
+        await setDoc(deviceRef, payload, { merge: true });
+    }
+    async setOffline(localNodeId) {
+        const deviceRef = await this.resolveOrCreateLocalDeviceRef();
+        if (!deviceRef) {
+            return;
+        }
+        await setDoc(deviceRef, {
+            appTag: this.options.appTag,
+            tag: this.options.appTag,
+            kind: 'device',
+            deviceId: this.options.getLocalDeviceId(),
+            userId: this.options.getCurrentUserId(),
+            deviceName: this.options.getDefaultDeviceName(),
+            nodeId: localNodeId,
+            platformType: 'web',
+            online: false,
+            updatedAt: serverTimestamp(),
+            lastSeenAt: serverTimestamp(),
+            expiresAt: Date.now() + DEVICE_OFFLINE_RETENTION_MS,
+        }, { merge: true });
+    }
+    async cleanupStaleDevices() {
+        const devicesCollection = await this.getDevicesCollectionRef();
+        if (!devicesCollection) {
+            return;
+        }
+        const snapshot = await getDocs(devicesCollection);
+        const now = Date.now();
+        await Promise.allSettled(snapshot.docs.map(async (document) => {
+            const raw = document.data();
+            const expired = this.isDeviceExpired(raw, now);
+            const isOnline = raw.online === true;
+            if (expired && !isOnline) {
+                await deleteDoc(document.ref);
+                return;
+            }
+            const lastSeenMs = this.toMillis(raw.updatedAt) ??
+                this.toMillis(raw.lastSeenAt) ??
+                0;
+            if (!isOnline || !lastSeenMs || lastSeenMs + DEVICE_STALE_HEARTBEAT_MS > now) {
+                return;
+            }
+            await setDoc(document.ref, {
+                online: false,
+                updatedAt: serverTimestamp(),
+                expiresAt: now + DEVICE_OFFLINE_RETENTION_MS,
+            }, { merge: true });
+        }));
+    }
+    async updateDevice(deviceId, updates) {
+        const deviceRef = await this.resolveDeviceRef(deviceId);
+        if (!deviceRef) {
+            throw new Error('updateDevice requires a known device record');
+        }
+        const payload = {
+            updatedAt: serverTimestamp(),
+        };
+        if (typeof updates.deviceName === 'string') {
+            payload.deviceName = updates.deviceName;
+        }
+        if (updates.capabilities) {
+            payload.capabilities = {
+                canHost: updates.capabilities.canHost ??
+                    updates.capabilities.can_host ??
+                    false,
+                canSync: updates.capabilities.canSync ??
+                    updates.capabilities.can_sync ??
+                    false,
+                readOnly: updates.capabilities.readOnly ??
+                    updates.capabilities.read_only ??
+                    false,
+            };
+        }
+        if (typeof updates.metadata === 'string') {
+            payload.metadata = updates.metadata;
+        }
+        await setDoc(deviceRef, payload, { merge: true });
+    }
+    async deleteDevice(deviceId) {
+        const deviceRef = await this.resolveDeviceRef(deviceId);
+        if (!deviceRef) {
+            return;
+        }
+        await deleteDoc(deviceRef);
+    }
+    async createSession(session) {
+        if (this.shouldUseHostedSessionCallable()) {
+            await this.createHostedSession(session);
+            return;
+        }
+        const sessionsCollection = await this.getSessionsCollectionRef();
+        if (!sessionsCollection) {
+            throw new Error('createSession requires an active browser signaling namespace');
+        }
+        const sessionRef = doc(sessionsCollection, session.connectionId);
+        const now = Date.now();
+        // 10-minute TTL: Firestore native TTL policy will delete this doc once
+        // the session has either completed or was abandoned (e.g. client crash).
+        const SESSION_TTL_MS = 10 * 60 * 1000;
+        await setDoc(sessionRef, {
+            appTag: session.appTag ?? this.options.appTag,
+            connectionId: session.connectionId,
+            initiator: session.initiator ?? this.options.getCurrentUserId(),
+            target: session.target ?? this.options.getCurrentUserId(),
+            initiatorDeviceId: session.initiatorDeviceId,
+            targetDeviceId: session.targetDeviceId,
+            connectionType: session.connectionType ?? null,
+            state: session.state,
+            offer: session.offer ? JSON.stringify(session.offer) : null,
+            offerE2ee: session.offerE2ee ? JSON.stringify(session.offerE2ee) : null,
+            answer: session.answer ? JSON.stringify(session.answer) : null,
+            answerE2ee: session.answerE2ee ? JSON.stringify(session.answerE2ee) : null,
+            iceCandidates: Array.isArray(session.iceCandidates)
+                ? JSON.stringify(session.iceCandidates)
+                : null,
+            initiatorNodeId: session.initiatorNodeId ?? null,
+            targetNodeId: session.targetNodeId ?? null,
+            initiatorEndpointAddr: session.initiatorEndpointAddr ?? null,
+            targetEndpointAddr: session.targetEndpointAddr ?? null,
+            intent: session.intent ?? null,
+            createdAt: session.createdAt ?? now,
+            updatedAt: now,
+            expiresAt: now + SESSION_TTL_MS,
+        }, { merge: true });
+    }
+    shouldUseHostedSessionCallable() {
+        return (this.options.discoveryMode ?? 'personal') !== 'personal' && !!this.options.getCurrentUserId();
+    }
+    async createHostedSession(session) {
+        const callable = httpsCallable(getFunctions(this.options.app), CREATE_SIGNALING_SESSION_FUNCTION);
+        await callable({
+            ...session,
+            appTag: session.appTag ?? this.options.appTag,
+            initiator: session.initiator ?? this.options.getCurrentUserId() ?? undefined,
+            target: session.target ?? this.options.getCurrentUserId() ?? undefined,
+        });
+    }
+    async updateSession(sessionId, updateData) {
+        const sessionsCollection = await this.getSessionsCollectionRef();
+        if (!sessionsCollection) {
+            throw new Error('updateSession requires an active browser signaling namespace');
+        }
+        const sessionRef = doc(sessionsCollection, this.parseScopedId(sessionId));
+        const payload = {};
+        if (updateData && typeof updateData === 'object') {
+            for (const [key, value] of Object.entries(updateData)) {
+                if (value === undefined) {
+                    continue;
+                }
+                if (value === null ||
+                    typeof value === 'string' ||
+                    typeof value === 'number' ||
+                    typeof value === 'boolean') {
+                    payload[key] = value;
+                    continue;
+                }
+                payload[key] = JSON.stringify(value);
+            }
+        }
+        if (Object.keys(payload).length === 0) {
+            return;
+        }
+        payload.updatedAt = Date.now();
+        await updateDoc(sessionRef, payload);
+    }
+    async sendMessage(targetId, payload, state, replyPayload) {
+        const messagesCollection = await this.getMessagesCollectionRef();
+        if (!messagesCollection) {
+            throw new Error('sendMessage requires an active browser signaling namespace');
+        }
+        const messageId = this.createDocumentId();
+        const messageRef = doc(messagesCollection, messageId);
+        const senderId = this.getMessageSenderId();
+        const messageTimestamp = Date.now();
+        // 24-hour TTL: messages are short-lived polling fallback docs.
+        // Firestore native TTL policy deletes them if the target never polls.
+        const MESSAGE_TTL_MS = 24 * 60 * 60 * 1000;
+        await setDoc(messageRef, {
+            appTag: this.options.appTag,
+            senderId,
+            targetId,
+            payload,
+            state: state ?? null,
+            replyPayload: replyPayload ?? null,
+            timestamp: messageTimestamp,
+            expiresAt: messageTimestamp + MESSAGE_TTL_MS,
+        });
+        return messageRef.path;
+    }
+    async pollMessages(targetId) {
+        const messagesCollection = await this.getMessagesCollectionRef();
+        if (!messagesCollection) {
+            return [];
+        }
+        const snapshot = await getDocs(query(messagesCollection, where('targetId', '==', targetId), limit(50)));
+        const envelopes = [];
+        for (const document of snapshot.docs) {
+            const raw = document.data();
+            const senderId = typeof raw.senderId === 'string' ? raw.senderId : '';
+            const envelopeTargetId = typeof raw.targetId === 'string' ? raw.targetId : '';
+            const payload = typeof raw.payload === 'string' ? raw.payload : '';
+            if (!senderId || !envelopeTargetId || !payload) {
+                continue;
+            }
+            envelopes.push({
+                senderId,
+                targetId: envelopeTargetId,
+                payload,
+                state: typeof raw.state === 'string' ? raw.state : undefined,
+                replyPayload: typeof raw.replyPayload === 'string' ? raw.replyPayload : undefined,
+                timestamp: this.toMillis(raw.timestamp),
+                _documentId: document.id,
+            });
+        }
+        envelopes.sort((left, right) => (left.timestamp ?? 0) - (right.timestamp ?? 0));
+        await Promise.allSettled(envelopes.map(async (envelope) => {
+            await deleteDoc(doc(messagesCollection, envelope._documentId));
+        }));
+        return envelopes.map(({ _documentId, ...envelope }) => envelope);
+    }
+    async subscribeSessions(localDeviceId) {
+        const sessionsCollection = await this.getSessionsCollectionRef();
+        const targetDeviceId = this.parseScopedId(localDeviceId);
+        if (!sessionsCollection || !targetDeviceId) {
+            return new ReadableStream({
+                start(controller) {
+                    controller.close();
+                },
+            });
+        }
+        let unsubscribeInitiator = null;
+        let unsubscribeTarget = null;
+        let closed = false;
+        return new ReadableStream({
+            start: (controller) => {
+                const memberships = {
+                    initiator: new Set(),
+                    target: new Set(),
+                };
+                const sessions = new Map();
+                const applyChanges = (source, snapshot) => {
+                    if (closed) {
+                        return;
+                    }
+                    const events = [];
+                    for (const change of snapshot.docChanges()) {
+                        const id = change.doc.id;
+                        if (change.type === 'removed') {
+                            memberships[source].delete(id);
+                            const stillTracked = memberships.initiator.has(id) || memberships.target.has(id);
+                            if (!stillTracked && sessions.delete(id)) {
+                                events.push({ type: 'removed', sessionId: id });
+                            }
+                            continue;
+                        }
+                        const parsed = this.toSession(change.doc.id, change.doc.data());
+                        if (!parsed) {
+                            continue;
+                        }
+                        memberships[source].add(id);
+                        const existed = sessions.has(id);
+                        sessions.set(id, parsed);
+                        events.push({
+                            type: existed ? 'modified' : 'added',
+                            session: parsed,
+                        });
+                    }
+                    if (events.length > 0) {
+                        controller.enqueue(events);
+                    }
+                };
+                unsubscribeInitiator = onSnapshot(query(sessionsCollection, where('initiatorDeviceId', '==', targetDeviceId)), (snapshot) => applyChanges('initiator', snapshot), (error) => {
+                    if (!closed) {
+                        controller.error(error);
+                    }
+                });
+                unsubscribeTarget = onSnapshot(query(sessionsCollection, where('targetDeviceId', '==', targetDeviceId)), (snapshot) => applyChanges('target', snapshot), (error) => {
+                    if (!closed) {
+                        controller.error(error);
+                    }
+                });
+            },
+            cancel: () => {
+                closed = true;
+                unsubscribeInitiator?.();
+                unsubscribeTarget?.();
+                unsubscribeInitiator = null;
+                unsubscribeTarget = null;
+            },
+        });
+    }
+    async ensureDeviceWatch() {
+        if (this.deviceListeners.size === 0) {
+            return;
+        }
+        const collectionRef = await this.getDevicesCollectionRef();
+        const scopeKey = collectionRef?.path ?? null;
+        if (!collectionRef || !scopeKey) {
+            this.devicesById.clear();
+            this.emitDevicesToAll();
+            return;
+        }
+        if (this.activeDeviceUnsubscribe && this.activeDeviceScopeKey === scopeKey) {
+            return;
+        }
+        this.stopDeviceWatch({ clearDevices: true });
+        // Phase 1: if RTDB presence is configured, use getDocs (one-time cache)
+        // for Firestore tickets + RTDB for the live online/offline overlay.
+        if (this.rtdbPresence && this.rtdbScope) {
+            await this.ensureDeviceWatchRtdb(collectionRef, scopeKey);
+            return;
+        }
+        // Fallback: legacy Firestore onSnapshot watcher (no RTDB).
+        const generation = ++this.deviceWatchGeneration;
+        this.activeDeviceScopeKey = scopeKey;
+        this.activeDeviceUnsubscribe = onSnapshot(collectionRef, (snapshot) => {
+            if (generation !== this.deviceWatchGeneration) {
+                return;
+            }
+            const now = Date.now();
+            this.devicesById.clear();
+            for (const document of snapshot.docs) {
+                const device = this.toDevice(document, now);
+                if (!device) {
+                    continue;
+                }
+                this.devicesById.set(device.deviceId, device);
+            }
+            this.emitDevicesToAll();
+        }, (error) => {
+            if (generation !== this.deviceWatchGeneration) {
+                return;
+            }
+            console.warn('[BrowserFirestoreSignaling] device watch failed:', error);
+        });
+    }
+    /**
+     * RTDB-backed device watch (Phase 1).
+     *
+     * 1. One-time getDocs() to populate devicesById with Firestore tickets.
+     * 2. Subscribe to RTDB for the live online/offline boolean overlay.
+     * 3. When RTDB fires, merge online state into devicesById and emit.
+     * 4. If ticketVersion changed for a device, re-fetch its Firestore doc.
+     */
+    async ensureDeviceWatchRtdb(collectionRef, scopeKey) {
+        const generation = ++this.deviceWatchGeneration;
+        this.activeDeviceScopeKey = scopeKey;
+        // Step 1: one-time Firestore fetch to warm the ticket cache.
+        const snapshot = await getDocs(collectionRef);
+        if (generation !== this.deviceWatchGeneration) {
+            return; // scope changed while we were fetching
+        }
+        const now = Date.now();
+        this.devicesById.clear();
+        for (const document of snapshot.docs) {
+            const device = this.toDevice(document, now);
+            if (device) {
+                this.devicesById.set(device.deviceId, device);
+            }
+        }
+        // Step 2: subscribe to RTDB for live online state.
+        const rtdb = this.rtdbPresence;
+        const scope = this.rtdbScope;
+        if (this.rtdbUnsubscribe) {
+            this.rtdbUnsubscribe();
+        }
+        this.rtdbUnsubscribe = rtdb.onPresenceChange(scope, (presenceMap) => {
+            if (generation !== this.deviceWatchGeneration) {
+                return;
+            }
+            this.rtdbPresenceMap = presenceMap;
+            // Check for ticket version changes and re-fetch those devices.
+            const refetchIds = [];
+            for (const [deviceId, state] of Object.entries(presenceMap)) {
+                const knownVersion = this.knownTicketVersions.get(deviceId) ?? -1;
+                if (state.ticketVersion !== knownVersion) {
+                    this.knownTicketVersions.set(deviceId, state.ticketVersion);
+                    if (knownVersion !== -1) {
+                        // Version changed after initial load — ticket is stale.
+                        refetchIds.push(deviceId);
+                    }
+                }
+            }
+            // Apply RTDB online/offline overlay to devicesById.
+            this.applyRtdbOverlay();
+            // Re-fetch stale tickets in the background, then re-emit.
+            if (refetchIds.length > 0) {
+                void this.refetchDeviceTickets(refetchIds, collectionRef, generation);
+            }
+        });
+        // No separate activeDeviceUnsubscribe — we manage rtdbUnsubscribe directly.
+        // Set a no-op so stopDeviceWatch() doesn't break.
+        this.activeDeviceUnsubscribe = () => {
+            this.rtdbUnsubscribe?.();
+            this.rtdbUnsubscribe = null;
+        };
+        // Initial emit with current Firestore state (RTDB callback will follow shortly).
+        this.emitDevicesToAll();
+    }
+    /**
+     * Merge RTDB online/offline map into devicesById, then emit.
+     * Devices present in Firestore cache but absent from RTDB are shown as-is
+     * (their Firestore `online` field is the fallback).
+     */
+    applyRtdbOverlay() {
+        for (const [deviceId, device] of this.devicesById) {
+            const rtdbState = this.rtdbPresenceMap[deviceId];
+            if (!rtdbState)
+                continue;
+            if (device.online !== rtdbState.online) {
+                // Shallow-clone so listeners always get a new object reference.
+                this.devicesById.set(deviceId, { ...device, online: rtdbState.online });
+            }
+        }
+        this.emitDevicesToAll();
+    }
+    /**
+     * Re-fetch specific device docs from Firestore (ticket version changed).
+     * Updates devicesById and re-emits.
+     */
+    async refetchDeviceTickets(deviceIds, collectionRef, generation) {
+        await Promise.allSettled(deviceIds.map(async (deviceId) => {
+            try {
+                const deviceRef = doc(collectionRef, deviceId);
+                const snap = await getDoc(deviceRef);
+                if (generation !== this.deviceWatchGeneration)
+                    return;
+                if (!snap.exists()) {
+                    this.devicesById.delete(deviceId);
+                    return;
+                }
+                const fresh = this.deviceFromSnapshot(deviceId, typeof snap.data === 'function'
+                    ? snap.data()
+                    : null, Date.now());
+                if (fresh) {
+                    // Apply current RTDB online state to the freshly fetched doc.
+                    const rtdbState = this.rtdbPresenceMap[deviceId];
+                    this.devicesById.set(deviceId, rtdbState
+                        ? { ...fresh, online: rtdbState.online }
+                        : fresh);
+                }
+                else {
+                    this.devicesById.delete(deviceId);
+                }
+            }
+            catch (err) {
+                console.warn('[BrowserFirestoreSignaling] refetch device ticket failed:', err);
+            }
+        }));
+        if (generation === this.deviceWatchGeneration) {
+            this.emitDevicesToAll();
+        }
+    }
+    async refreshDeviceForAutoConnect(deviceId) {
+        const trimmedDeviceId = deviceId.trim();
+        if (!trimmedDeviceId) {
+            return null;
+        }
+        const collectionRef = await this.getDevicesCollectionRef();
+        if (!collectionRef) {
+            return this.devicesById.get(trimmedDeviceId) ?? null;
+        }
+        const deviceRef = doc(collectionRef, trimmedDeviceId);
+        const previous = this.devicesById.get(trimmedDeviceId) ?? null;
+        let source = 'server';
+        let snap = null;
+        try {
+            snap = await getDocFromServer(deviceRef);
+        }
+        catch (error) {
+            source = 'cache';
+            console.warn('[BrowserFirestoreSignaling][auto-connect][refresh] getDocFromServer failed; falling back to getDoc', {
+                deviceId: trimmedDeviceId,
+                error,
+            });
+            snap = await getDoc(deviceRef).catch(() => null);
+        }
+        if (!snap?.exists()) {
+            this.devicesById.delete(trimmedDeviceId);
+            console.info('[BrowserFirestoreSignaling][auto-connect][refresh] device doc missing during refresh', {
+                deviceId: trimmedDeviceId,
+                source,
+                previousTicket: summarizeTicketForLogs(previous?.ticket),
+            });
+            this.emitDevicesToAll();
+            return null;
+        }
+        const raw = typeof snap.data === 'function'
+            ? snap.data()
+            : null;
+        const fresh = this.deviceFromSnapshot(trimmedDeviceId, raw, Date.now());
+        if (!fresh) {
+            this.devicesById.delete(trimmedDeviceId);
+            console.info('[BrowserFirestoreSignaling][auto-connect][refresh] refreshed device doc was filtered out', {
+                deviceId: trimmedDeviceId,
+                source,
+                previousTicket: summarizeTicketForLogs(previous?.ticket),
+            });
+            this.emitDevicesToAll();
+            return null;
+        }
+        const rtdbState = this.rtdbPresenceMap[trimmedDeviceId];
+        const refreshed = rtdbState ? { ...fresh, online: rtdbState.online } : fresh;
+        this.devicesById.set(trimmedDeviceId, refreshed);
+        const ticketChanged = (previous?.ticket ?? null) !== (refreshed.ticket ?? null);
+        console.info('[BrowserFirestoreSignaling][auto-connect][refresh]', {
+            deviceId: trimmedDeviceId,
+            source,
+            ticketChanged,
+            previousTicket: summarizeTicketForLogs(previous?.ticket),
+            refreshedTicket: summarizeTicketForLogs(refreshed.ticket),
+            previousNodeId: previous?.nodeId ?? null,
+            refreshedNodeId: refreshed.nodeId ?? null,
+        });
+        this.emitDevicesToAll();
+        return refreshed;
+    }
+    stopDeviceWatch(options) {
+        this.deviceWatchGeneration += 1;
+        this.activeDeviceUnsubscribe?.();
+        this.activeDeviceUnsubscribe = null;
+        this.activeDeviceScopeKey = null;
+        if (options?.clearDevices) {
+            this.devicesById.clear();
+            this.emitDevicesToAll();
+        }
+    }
+    emitDevicesToAll() {
+        for (const listenerId of this.deviceListeners.keys()) {
+            this.emitDevicesToListener(listenerId);
+        }
+    }
+    emitDevicesToListener(listenerId) {
+        const listener = this.deviceListeners.get(listenerId);
+        if (!listener) {
+            return;
+        }
+        const devices = Array.from(this.devicesById.values());
+        const filtered = listener.excludeNodeId
+            ? this.filterDevices(devices, listener.excludeNodeId)
+            : devices;
+        listener.callback(filtered);
+    }
+    filterDevices(devices, excludeNodeId) {
+        return devices.filter((device) => device.ticket !== excludeNodeId &&
+            device.deviceId !== excludeNodeId &&
+            device.nodeId !== excludeNodeId);
+    }
+    async readCurrentDeviceSnapshot() {
+        const collectionRef = await this.getDevicesCollectionRef();
+        if (!collectionRef) {
+            return [];
+        }
+        const snapshot = await getDocs(collectionRef);
+        const now = Date.now();
+        const devices = [];
+        for (const document of snapshot.docs) {
+            const raw = document.data();
+            if (this.isDeviceExpired(raw, now)) {
+                if (raw.online === true) {
+                    await this.markStaleDeviceOffline(document, raw, now);
+                }
+                continue;
+            }
+            const device = this.options.normalizeDevice({
+                ...raw,
+                deviceId: raw.deviceId ?? document.id,
+            }, document.id);
+            if (!device) {
+                continue;
+            }
+            if (!device.deviceId || !this.options.matchesTag(device)) {
+                continue;
+            }
+            devices.push(device);
+        }
+        return devices;
+    }
+    toDevice(document, now) {
+        return this.deviceFromSnapshot(document.id, document.data(), now, document);
+    }
+    deviceFromSnapshot(fallbackId, raw, now, document) {
+        if (!raw) {
+            return null;
+        }
+        if (this.isDeviceExpired(raw, now)) {
+            if (raw.online === true && document) {
+                void this.markStaleDeviceOffline(document, raw, now);
+            }
+            return null;
+        }
+        const device = this.options.normalizeDevice({
+            ...raw,
+            deviceId: raw.deviceId ?? fallbackId,
+        }, fallbackId);
+        if (!device.deviceId || !this.options.matchesTag(device)) {
+            return null;
+        }
+        return device;
+    }
+    async markStaleDeviceOffline(document, raw, now) {
+        const deviceId = typeof raw.deviceId === 'string' && raw.deviceId.trim().length > 0
+            ? raw.deviceId
+            : document.id;
+        const key = document.ref?.path || deviceId;
+        if (!key || this.staleDeviceOfflineWrites.has(key)) {
+            return;
+        }
+        this.staleDeviceOfflineWrites.add(key);
+        try {
+            const deviceRef = await this.resolveDeviceRef(deviceId);
+            if (!deviceRef) {
+                return;
+            }
+            await setDoc(deviceRef, {
+                online: false,
+                updatedAt: serverTimestamp(),
+                expiresAt: now + DEVICE_OFFLINE_RETENTION_MS,
+            }, { merge: true });
+        }
+        catch (error) {
+            console.warn('[BrowserFirestoreSignaling] failed to mark stale device offline:', error);
+        }
+        finally {
+            this.staleDeviceOfflineWrites.delete(key);
+        }
+    }
+    toSession(id, raw) {
+        const initiatorDeviceId = typeof raw.initiatorDeviceId === 'string' ? raw.initiatorDeviceId : '';
+        const targetDeviceId = typeof raw.targetDeviceId === 'string' ? raw.targetDeviceId : '';
+        if (!initiatorDeviceId && !targetDeviceId) {
+            return null;
+        }
+        return {
+            connectionId: typeof raw.connectionId === 'string' ? raw.connectionId : id,
+            initiator: typeof raw.initiator === 'string' ? raw.initiator : '',
+            target: typeof raw.target === 'string' ? raw.target : '',
+            initiatorDeviceId,
+            targetDeviceId,
+            connectionType: typeof raw.connectionType === 'string' ? raw.connectionType : undefined,
+            offer: this.parseMaybeJson(raw.offer),
+            offerE2ee: this.parseMaybeJson(raw.offerE2ee),
+            answer: this.parseMaybeJson(raw.answer),
+            answerE2ee: this.parseMaybeJson(raw.answerE2ee),
+            iceCandidates: Array.isArray(raw.iceCandidates) ? raw.iceCandidates : [],
+            initiatorNodeId: typeof raw.initiatorNodeId === 'string' ? raw.initiatorNodeId : undefined,
+            targetNodeId: typeof raw.targetNodeId === 'string' ? raw.targetNodeId : undefined,
+            initiatorEndpointAddr: typeof raw.initiatorEndpointAddr === 'string'
+                ? raw.initiatorEndpointAddr
+                : undefined,
+            targetEndpointAddr: typeof raw.targetEndpointAddr === 'string'
+                ? raw.targetEndpointAddr
+                : undefined,
+            intent: typeof raw.intent === 'string' ? raw.intent : undefined,
+            appTag: typeof raw.appTag === 'string' ? raw.appTag : this.options.appTag,
+            createdAt: this.toMillis(raw.createdAt),
+            expiresAt: this.toMillis(raw.expiresAt),
+            state: typeof raw.state === 'string' ? raw.state : '',
+        };
+    }
+    parseMaybeJson(value) {
+        if (typeof value !== 'string') {
+            return value;
+        }
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    isDeviceExpired(raw, now) {
+        const expiresAtMs = this.toMillis(raw.expiresAt);
+        if (typeof expiresAtMs === 'number') {
+            return expiresAtMs <= now;
+        }
+        const updatedAtMs = this.toMillis(raw.updatedAt);
+        if (typeof updatedAtMs === 'number') {
+            return updatedAtMs + DEVICE_STALE_HEARTBEAT_MS <= now;
+        }
+        const lastSeenAtMs = this.toMillis(raw.lastSeenAt);
+        if (typeof lastSeenAtMs === 'number') {
+            return lastSeenAtMs + DEVICE_STALE_HEARTBEAT_MS <= now;
+        }
+        return false;
+    }
+    toMillis(value) {
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const parsed = Date.parse(value);
+            return Number.isNaN(parsed) ? undefined : parsed;
+        }
+        if (value instanceof Date) {
+            return value.getTime();
+        }
+        if (value &&
+            typeof value === 'object' &&
+            typeof value.toMillis === 'function') {
+            return value.toMillis();
+        }
+        return undefined;
+    }
+    async getDevicesCollectionRef() {
+        const path = await this.getDevicesCollectionPath();
+        return path ? collection(this.firestore, path) : null;
+    }
+    async getSessionsCollectionRef() {
+        const namespaceRoot = await this.getNamespaceRoot();
+        return namespaceRoot ? collection(this.firestore, `${namespaceRoot}/sessions`) : null;
+    }
+    async getMessagesCollectionRef() {
+        const namespaceRoot = await this.getNamespaceRoot();
+        return namespaceRoot ? collection(this.firestore, `${namespaceRoot}/messages`) : null;
+    }
+    async getDevicesCollectionPath() {
+        const namespaceRoot = await this.getNamespaceRoot();
+        if (!namespaceRoot) {
+            return null;
+        }
+        if (this.usesPersonalSpaceMode()) {
+            return `${namespaceRoot}/devices`;
+        }
+        const userId = this.options.getDiscoveryScopeId();
+        if (!userId) {
+            return null;
+        }
+        return `${namespaceRoot}/users/${userId}/devices`;
+    }
+    async getNamespaceRoot() {
+        if (this.usesPersonalSpaceMode()) {
+            if (!this.namespaceRootPromise) {
+                const apiKey = this.options.apiKey?.trim() ?? '';
+                const spaceKey = this.options.spaceKey?.trim() ?? '';
+                this.namespaceRootPromise = deriveSpaceNamespace(apiKey, spaceKey).then((namespace) => `spaces/${namespace}`);
+            }
+            return this.namespaceRootPromise;
+        }
+        return `apps/${this.options.appTag}`;
+    }
+    usesPersonalSpaceMode() {
+        return (this.options.discoveryMode ?? 'personal') === 'personal'
+            && typeof this.options.apiKey === 'string'
+            && this.options.apiKey.trim().length > 0
+            && typeof this.options.spaceKey === 'string'
+            && this.options.spaceKey.trim().length > 0;
+    }
+    parseScopedId(value) {
+        const parts = value.split('::');
+        return parts.length === 2 ? parts[1] : value;
+    }
+    getMessageSenderId() {
+        return this.options.getCurrentUserId() ?? this.options.getLocalDeviceId();
+    }
+    createDocumentId() {
+        return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+    async resolveOrCreateLocalDeviceRef() {
+        const collectionRef = await this.getDevicesCollectionRef();
+        if (!collectionRef) {
+            return null;
+        }
+        return doc(collectionRef, this.options.getLocalDeviceId());
+    }
+    async resolveDeviceRef(deviceId) {
+        const collectionRef = await this.getDevicesCollectionRef();
+        if (!collectionRef) {
+            return null;
+        }
+        const directRef = doc(collectionRef, deviceId);
+        if ((await getDoc(directRef)).exists()) {
+            return directRef;
+        }
+        const byDeviceId = await getDocs(query(collectionRef, where('deviceId', '==', deviceId), limit(1)));
+        if (!byDeviceId.empty) {
+            return byDeviceId.docs[0].ref;
+        }
+        const byNodeId = await getDocs(query(collectionRef, where('nodeId', '==', deviceId), limit(1)));
+        if (!byNodeId.empty) {
+            return byNodeId.docs[0].ref;
+        }
+        return null;
+    }
+}