openrtc 0.1.0

package/dist/core/bridges/BridgeCodecs.js

@@ -0,0 +1,317 @@
+function coerceRecord(value) {
+    if (!value || typeof value !== 'object') {
+        return {};
+    }
+    if (value instanceof Map) {
+        return Object.fromEntries(value);
+    }
+    return value;
+}
+function flattenRecord(value) {
+    const record = coerceRecord(value);
+    const nestedDevice = coerceRecord(record.device);
+    if (!Object.keys(nestedDevice).length) {
+        return record;
+    }
+    const flattened = { ...nestedDevice, ...record };
+    delete flattened.device;
+    return flattened;
+}
+export function pickString(raw, ...keys) {
+    for (const key of keys) {
+        const value = raw[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function pickBoolean(raw, ...keys) {
+    for (const key of keys) {
+        const value = raw[key];
+        if (typeof value === 'boolean') {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function pickNumber(raw, ...keys) {
+    for (const key of keys) {
+        const value = raw[key];
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function isPersonalSpaceMode(options) {
+    return (options.discoveryMode ?? 'personal') === 'personal'
+        && typeof options.apiKey === 'string'
+        && options.apiKey.trim().length > 0
+        && typeof options.spaceKey === 'string'
+        && options.spaceKey.trim().length > 0;
+}
+export function matchesDiscoveryTag(device, appTag, personalMode) {
+    if (personalMode) {
+        return true;
+    }
+    const deviceAppTag = typeof device.appTag === 'string'
+        ? device.appTag
+        : typeof device.tag === 'string'
+            ? device.tag
+            : undefined;
+    return deviceAppTag === appTag;
+}
+export function normalizeDeviceRecord(raw, fallbackId) {
+    const normalizedRaw = flattenRecord(raw);
+    const deviceId = pickString(normalizedRaw, 'deviceId', 'device_id') || (fallbackId || '');
+    const nodeId = pickString(normalizedRaw, 'nodeId', 'node_id') || '';
+    const ticket = pickString(normalizedRaw, 'ticket') || '';
+    return {
+        appTag: pickString(normalizedRaw, 'appTag', 'app_tag', 'tag'),
+        deviceId,
+        deviceName: pickString(normalizedRaw, 'deviceName', 'device_name') || 'Unknown Device',
+        online: !!normalizedRaw.online,
+        ticket,
+        tag: pickString(normalizedRaw, 'tag', 'appTag', 'app_tag'),
+        kind: pickString(normalizedRaw, 'kind'),
+        nodeId: nodeId || undefined,
+        platformType: pickString(normalizedRaw, 'platformType', 'platform_type'),
+        capabilities: normalizedRaw.capabilities || undefined,
+        sessionId: pickString(normalizedRaw, 'sessionId', 'session_id'),
+        userId: pickString(normalizedRaw, 'userId', 'user_id'),
+        lastSeenAt: normalizedRaw.lastSeenAt ?? normalizedRaw.last_seen_at,
+        expiresAt: normalizedRaw.expiresAt ?? normalizedRaw.expires_at,
+        createdAt: normalizedRaw.createdAt ?? normalizedRaw.created_at,
+        updatedAt: normalizedRaw.updatedAt ?? normalizedRaw.updated_at,
+        metadata: pickString(normalizedRaw, 'metadata'),
+    };
+}
+export function normalizeDeviceStatusSnapshotRecord(raw) {
+    const normalizedRaw = flattenRecord(raw);
+    return {
+        ...normalizeDeviceRecord(normalizedRaw),
+        connectionStatus: pickString(normalizedRaw, 'connectionStatus', 'connection_status') ||
+            'disconnected',
+        settledReady: pickBoolean(normalizedRaw, 'settledReady', 'settled_ready') ?? false,
+        readinessState: pickString(normalizedRaw, 'readinessState', 'readiness_state') ?? undefined,
+        readinessReason: pickString(normalizedRaw, 'readinessReason', 'readiness_reason') ?? undefined,
+        peerHealth: pickString(normalizedRaw, 'peerHealth', 'peer_health') ||
+            'unknown',
+        peerId: pickString(normalizedRaw, 'peerId', 'peer_id'),
+        scopes: Array.isArray(normalizedRaw.scopes)
+            ? normalizedRaw.scopes.filter((scope) => typeof scope === 'string')
+            : [],
+        connectionId: pickString(normalizedRaw, 'connectionId', 'connection_id'),
+        deviceIdHint: pickString(normalizedRaw, 'deviceIdHint', 'device_id_hint'),
+        activeTransportStableId: pickNumber(normalizedRaw, 'activeTransportStableId', 'active_transport_stable_id') ?? undefined,
+        transportGeneration: pickNumber(normalizedRaw, 'transportGeneration', 'transport_generation') ?? undefined,
+    };
+}
+export function normalizePeerSessionSnapshotRecord(raw) {
+    const normalizedRaw = flattenRecord(raw);
+    return {
+        peerId: pickString(normalizedRaw, 'peerId', 'peer_id') || '',
+        deviceId: pickString(normalizedRaw, 'deviceId', 'device_id'),
+        deviceIdHint: pickString(normalizedRaw, 'deviceIdHint', 'device_id_hint'),
+        nodeId: pickString(normalizedRaw, 'nodeId', 'node_id'),
+        activeConnectionId: pickString(normalizedRaw, 'activeConnectionId', 'active_connection_id'),
+        candidateConnectionIds: Array.isArray(normalizedRaw.candidateConnectionIds)
+            ? normalizedRaw.candidateConnectionIds.filter((value) => typeof value === 'string')
+            : Array.isArray(normalizedRaw.candidate_connection_ids)
+                ? normalizedRaw.candidate_connection_ids.filter((value) => typeof value === 'string')
+                : [],
+        status: pickString(normalizedRaw, 'status') ||
+            'disconnected',
+        health: pickString(normalizedRaw, 'health') ||
+            'unknown',
+        settledReady: pickBoolean(normalizedRaw, 'settledReady', 'settled_ready') ?? false,
+        readinessState: pickString(normalizedRaw, 'readinessState', 'readiness_state') ?? undefined,
+        activeTransportStableId: pickNumber(normalizedRaw, 'activeTransportStableId', 'active_transport_stable_id') ?? undefined,
+        transportGeneration: pickNumber(normalizedRaw, 'transportGeneration', 'transport_generation') ?? undefined,
+        replacementPending: pickBoolean(normalizedRaw, 'replacementPending', 'replacement_pending') ?? undefined,
+        lastLifecycleTransitionAtMs: pickNumber(normalizedRaw, 'lastLifecycleTransitionAtMs', 'last_lifecycle_transition_at_ms') ?? undefined,
+        readinessReason: pickString(normalizedRaw, 'readinessReason', 'readiness_reason') ?? undefined,
+        transitionCount: pickNumber(normalizedRaw, 'transitionCount', 'transition_count') ?? undefined,
+        connectingTransitionCount: pickNumber(normalizedRaw, 'connectingTransitionCount', 'connecting_transition_count') ?? undefined,
+        replacementCount: pickNumber(normalizedRaw, 'replacementCount', 'replacement_count') ?? undefined,
+        retireCount: pickNumber(normalizedRaw, 'retireCount', 'retire_count') ?? undefined,
+        lastDisconnectReason: pickString(normalizedRaw, 'lastDisconnectReason', 'last_disconnect_reason') ?? undefined,
+        lastReconnectReason: pickString(normalizedRaw, 'lastReconnectReason', 'last_reconnect_reason') ?? undefined,
+        scopes: Array.isArray(normalizedRaw.scopes)
+            ? normalizedRaw.scopes.filter((scope) => typeof scope === 'string')
+            : [],
+        lastSeenAtMs: typeof normalizedRaw.lastSeenAtMs === 'number'
+            ? normalizedRaw.lastSeenAtMs
+            : typeof normalizedRaw.last_seen_at_ms === 'number'
+                ? normalizedRaw.last_seen_at_ms
+                : 0,
+        error: pickString(normalizedRaw, 'error'),
+    };
+}
+export function normalizeManagedConnectionRecord(raw) {
+    const record = coerceRecord(raw);
+    return {
+        connectionId: typeof record.connectionId === 'string' ? record.connectionId : '',
+        nodeId: typeof record.nodeId === 'string' ? record.nodeId : null,
+        deviceId: typeof record.deviceId === 'string' ? record.deviceId : null,
+        deviceIdHint: typeof record.deviceIdHint === 'string' ? record.deviceIdHint : null,
+        endpointId: typeof record.endpointId === 'string' ? record.endpointId : null,
+        transportGeneration: typeof record.transportGeneration === 'number' ? record.transportGeneration : 0,
+        transportStableId: typeof record.transportStableId === 'number' ? record.transportStableId : null,
+        transportSource: typeof record.transportSource === 'string' ? record.transportSource : null,
+        lastTransportChangeAtMs: typeof record.lastTransportChangeAtMs === 'number'
+            ? record.lastTransportChangeAtMs
+            : 0,
+        state: typeof record.state === 'string' ? record.state : 'pending',
+        statusReason: typeof record.statusReason === 'string' ? record.statusReason : null,
+        transitionCount: typeof record.transitionCount === 'number' ? record.transitionCount : undefined,
+        connectingTransitionCount: typeof record.connectingTransitionCount === 'number'
+            ? record.connectingTransitionCount
+            : undefined,
+        replacementCount: typeof record.replacementCount === 'number' ? record.replacementCount : undefined,
+        retireCount: typeof record.retireCount === 'number' ? record.retireCount : undefined,
+        lastDisconnectReason: typeof record.lastDisconnectReason === 'string'
+            ? record.lastDisconnectReason
+            : undefined,
+        lastReconnectReason: typeof record.lastReconnectReason === 'string'
+            ? record.lastReconnectReason
+            : undefined,
+        createdAtMs: typeof record.createdAtMs === 'number' ? record.createdAtMs : 0,
+        updatedAtMs: typeof record.updatedAtMs === 'number' ? record.updatedAtMs : 0,
+    };
+}
+export function normalizeResolvedPeerIdentity(raw) {
+    const record = coerceRecord(raw);
+    return {
+        peerId: typeof record.peerId === 'string' ? record.peerId : null,
+        deviceId: typeof record.deviceId === 'string' ? record.deviceId : null,
+        deviceIdHint: typeof record.deviceIdHint === 'string' ? record.deviceIdHint : null,
+        nodeId: typeof record.nodeId === 'string' ? record.nodeId : null,
+    };
+}
+export function mapPeerSessionStatusToBackendState(status) {
+    switch (status) {
+        case 'connected':
+            return 'connected';
+        case 'connecting':
+            return 'connecting';
+        case 'failed':
+            return 'failed';
+        case 'closed':
+        case 'disconnected':
+        default:
+            return 'closed';
+    }
+}
+export function peerSessionToBackendConnectionState(snapshot) {
+    const connectionId = snapshot.activeConnectionId || snapshot.candidateConnectionIds[0] || null;
+    if (!connectionId) {
+        return null;
+    }
+    const state = mapPeerSessionStatusToBackendState(snapshot.status);
+    const transportState = state === 'connected'
+        ? 'connected'
+        : state === 'connecting'
+            ? 'connecting'
+            : 'closed';
+    const protocolState = state === 'connected'
+        ? (snapshot.settledReady ? 'routable' : 'transport-only')
+        : state === 'connecting'
+            ? 'connecting'
+            : 'closed';
+    return {
+        connectionId,
+        deviceId: snapshot.deviceId ?? null,
+        deviceIdHint: snapshot.deviceIdHint ?? null,
+        remoteNodeId: snapshot.nodeId ?? null,
+        state,
+        transportState,
+        protocolState,
+        routable: !!snapshot.settledReady,
+        readinessState: snapshot.readinessState,
+        readinessReason: snapshot.readinessReason,
+        transportGeneration: snapshot.transportGeneration,
+        activeTransportStableId: snapshot.activeTransportStableId,
+        replacementInProgress: snapshot.replacementPending,
+        lastLifecycleTransitionAtMs: snapshot.lastLifecycleTransitionAtMs,
+        transitionCount: snapshot.transitionCount,
+        connectingTransitionCount: snapshot.connectingTransitionCount,
+        replacementCount: snapshot.replacementCount,
+        retireCount: snapshot.retireCount,
+        lastDisconnectReason: snapshot.lastDisconnectReason ?? undefined,
+        lastReconnectReason: snapshot.lastReconnectReason ?? undefined,
+        updatedAt: snapshot.lastSeenAtMs,
+        error: snapshot.error ?? undefined,
+    };
+}
+export function normalizeConnectionStateSnapshot(raw) {
+    const record = coerceRecord(raw);
+    const connectionId = pickString(record, 'connectionId', 'connection_id');
+    if (!connectionId) {
+        return null;
+    }
+    const state = pickString(record, 'state') || 'connecting';
+    const createdAt = pickNumber(record, 'createdAt', 'created_at')
+        ?? pickNumber(record, 'updatedAt', 'updated_at')
+        ?? Date.now();
+    const updatedAt = pickNumber(record, 'updatedAt', 'updated_at')
+        ?? createdAt;
+    return {
+        connectionId,
+        deviceId: pickString(record, 'deviceId', 'device_id'),
+        deviceIdHint: pickString(record, 'deviceIdHint', 'device_id_hint'),
+        remoteNodeId: pickString(record, 'remoteNodeId', 'remote_node_id'),
+        state,
+        transportState: pickString(record, 'transportState', 'transport_state')
+            ?? (state === 'connected'
+                ? 'connected'
+                : state === 'connecting'
+                    ? 'connecting'
+                    : 'closed'),
+        protocolState: pickString(record, 'protocolState', 'protocol_state')
+            ?? (state === 'connected'
+                ? 'routable'
+                : state === 'connecting'
+                    ? 'connecting'
+                    : 'closed'),
+        routable: pickBoolean(record, 'routable') ?? false,
+        readinessState: pickString(record, 'readinessState', 'readiness_state') ?? undefined,
+        readinessReason: pickString(record, 'readinessReason', 'readiness_reason') ?? undefined,
+        transportGeneration: pickNumber(record, 'transportGeneration', 'transport_generation') ?? undefined,
+        activeTransportStableId: pickNumber(record, 'activeTransportStableId', 'active_transport_stable_id') ?? undefined,
+        replacementInProgress: pickBoolean(record, 'replacementInProgress', 'replacement_in_progress') ?? undefined,
+        lastLifecycleTransitionAtMs: pickNumber(record, 'lastLifecycleTransitionAtMs', 'last_lifecycle_transition_at_ms') ?? undefined,
+        transitionCount: pickNumber(record, 'transitionCount', 'transition_count') ?? undefined,
+        connectingTransitionCount: pickNumber(record, 'connectingTransitionCount', 'connecting_transition_count') ?? undefined,
+        replacementCount: pickNumber(record, 'replacementCount', 'replacement_count') ?? undefined,
+        retireCount: pickNumber(record, 'retireCount', 'retire_count') ?? undefined,
+        lastDisconnectReason: pickString(record, 'lastDisconnectReason', 'last_disconnect_reason') ?? undefined,
+        lastReconnectReason: pickString(record, 'lastReconnectReason', 'last_reconnect_reason') ?? undefined,
+        error: pickString(record, 'error') ?? undefined,
+        createdAt,
+        updatedAt,
+    };
+}
+export function sameConnectionState(left, right) {
+    if (!left) {
+        return false;
+    }
+    return left.connectionId === right.connectionId
+        && (left.deviceId ?? null) === (right.deviceId ?? null)
+        && (left.deviceIdHint ?? null) === (right.deviceIdHint ?? null)
+        && (left.remoteNodeId ?? null) === (right.remoteNodeId ?? null)
+        && left.state === right.state
+        && (left.transportState ?? null) === (right.transportState ?? null)
+        && (left.protocolState ?? null) === (right.protocolState ?? null)
+        && !!left.routable === !!right.routable
+        && (left.transportGeneration ?? null) === (right.transportGeneration ?? null)
+        && !!left.replacementInProgress === !!right.replacementInProgress
+        && (left.transitionCount ?? null) === (right.transitionCount ?? null)
+        && (left.connectingTransitionCount ?? null) === (right.connectingTransitionCount ?? null)
+        && (left.replacementCount ?? null) === (right.replacementCount ?? null)
+        && (left.retireCount ?? null) === (right.retireCount ?? null)
+        && (left.lastDisconnectReason ?? null) === (right.lastDisconnectReason ?? null)
+        && (left.lastReconnectReason ?? null) === (right.lastReconnectReason ?? null)
+        && (left.error ?? null) === (right.error ?? null);
+}

package/dist/core/bridges/BrowserFirestoreRooms.d.ts

@@ -0,0 +1,36 @@
+import type { FirebaseApp } from 'firebase/app';
+import type { RoomMember } from '../types';
+import { RtdbPresence } from './RtdbPresence';
+export interface BrowserFirestoreRoomsOptions {
+    app: FirebaseApp;
+    getRoomBackendTag: () => string;
+}
+export declare class BrowserFirestoreRooms {
+    private readonly options;
+    private readonly firestore;
+    private rtdbPresence;
+    constructor(options: BrowserFirestoreRoomsOptions);
+    /**
+     * Wire in the RTDB presence instance. Called by RoomManager after join.
+     * Once set, all subsequent watchMembers calls use the RTDB overlay.
+     */
+    setRtdbPresence(rtdbPresence: RtdbPresence): void;
+    watchMembers(roomId: string, myNodeId: string, callback: (members: RoomMember[]) => void): () => void;
+    /**
+     * RTDB-backed member watch (Phase 2).
+     *
+     * Firestore onSnapshot provides the authoritative roster (join/leave only).
+     * RTDB onRoomPresenceChange provides the live online/offline boolean.
+     * The merged list is re-emitted whenever either source changes.
+     */
+    private watchMembersWithRtdb;
+    private getNamespaceRoot;
+    /**
+     * Returns the appTag used for RTDB room presence paths.
+     * Personal spaces use "space::{namespaceId}" as the appTag in RTDB too.
+     */
+    private getAppTag;
+    private toRoomMember;
+    private isExpired;
+    private toMillis;
+}

package/dist/core/bridges/BrowserFirestoreRooms.js

@@ -0,0 +1,169 @@
+import { collection, getFirestore, onSnapshot, } from 'firebase/firestore';
+const ROOM_MEMBER_TTL_MS = 600000;
+export class BrowserFirestoreRooms {
+    constructor(options) {
+        this.options = options;
+        // Phase 2: RTDB presence overlay for room members.
+        // When set, watchMembers uses Firestore onSnapshot for the roster (join/leave
+        // events only) and RTDB for the live online/offline boolean per member.
+        this.rtdbPresence = null;
+        this.firestore = getFirestore(options.app);
+    }
+    /**
+     * Wire in the RTDB presence instance. Called by RoomManager after join.
+     * Once set, all subsequent watchMembers calls use the RTDB overlay.
+     */
+    setRtdbPresence(rtdbPresence) {
+        this.rtdbPresence = rtdbPresence;
+    }
+    watchMembers(roomId, myNodeId, callback) {
+        const membersCollection = collection(this.firestore, `${this.getNamespaceRoot()}/rooms/${roomId}/members`);
+        // Phase 2: RTDB presence overlay.
+        // When RTDB is available, we maintain a live presenceMap alongside the
+        // Firestore roster. Any change to either triggers a re-emit of the
+        // merged member list. This means Firestore onSnapshot only fires on
+        // actual join/leave events (not heartbeats), while the online/offline
+        // boolean is driven by RTDB in near-real-time.
+        if (this.rtdbPresence) {
+            return this.watchMembersWithRtdb(roomId, myNodeId, membersCollection, callback);
+        }
+        // Fallback: legacy Firestore-only watch (no RTDB).
+        return onSnapshot(membersCollection, (snapshot) => {
+            const now = Date.now();
+            const members = snapshot.docs
+                .map((document) => this.toRoomMember(document))
+                .filter((member) => !!member)
+                .filter((member) => member.nodeId !== myNodeId)
+                .filter((member) => !this.isExpired(member, now))
+                .sort((left, right) => {
+                if (left.joinedAt !== right.joinedAt) {
+                    return left.joinedAt - right.joinedAt;
+                }
+                return left.nodeId.localeCompare(right.nodeId);
+            });
+            callback(members);
+        }, (error) => {
+            console.warn('[BrowserFirestoreRooms] room watch failed:', error);
+        });
+    }
+    /**
+     * RTDB-backed member watch (Phase 2).
+     *
+     * Firestore onSnapshot provides the authoritative roster (join/leave only).
+     * RTDB onRoomPresenceChange provides the live online/offline boolean.
+     * The merged list is re-emitted whenever either source changes.
+     */
+    watchMembersWithRtdb(roomId, myNodeId, membersCollection, callback) {
+        const rtdb = this.rtdbPresence;
+        const appTag = this.getAppTag();
+        let firestoreMembers = [];
+        let rtdbPresenceMap = {};
+        const emit = () => {
+            const now = Date.now();
+            const merged = firestoreMembers
+                .filter((m) => m.nodeId !== myNodeId)
+                .filter((m) => !this.isExpired(m, now))
+                // Hide members RTDB has confirmed offline (crashed without leaving).
+                // They stay in the Firestore roster until TTL/cleanup removes them,
+                // but we don't show them as connectable peers.
+                .filter((m) => {
+                const rtdbState = rtdbPresenceMap[m.nodeId];
+                // If RTDB has seen this member and says offline → hide.
+                if (rtdbState && !rtdbState.online)
+                    return false;
+                return true;
+            })
+                .sort((left, right) => {
+                if (left.joinedAt !== right.joinedAt) {
+                    return left.joinedAt - right.joinedAt;
+                }
+                return left.nodeId.localeCompare(right.nodeId);
+            });
+            callback(merged);
+        };
+        // Subscribe to Firestore for roster changes (join/leave only after Phase 2).
+        const unsubscribeFirestore = onSnapshot(membersCollection, (snapshot) => {
+            firestoreMembers = snapshot.docs
+                .map((document) => this.toRoomMember(document))
+                .filter((member) => !!member);
+            emit();
+        }, (error) => {
+            console.warn('[BrowserFirestoreRooms] room watch failed:', error);
+        });
+        // Subscribe to RTDB for live liveness.
+        const unsubscribeRtdb = rtdb.onRoomPresenceChange(appTag, roomId, (presenceMap) => {
+            rtdbPresenceMap = presenceMap;
+            emit();
+        });
+        return () => {
+            unsubscribeFirestore();
+            unsubscribeRtdb();
+        };
+    }
+    getNamespaceRoot() {
+        const backendTag = this.options.getRoomBackendTag().trim();
+        if (!backendTag) {
+            throw new Error('Room backend tag is required for browser room watches');
+        }
+        if (backendTag.startsWith('space::')) {
+            return `spaces/${backendTag.slice('space::'.length)}`;
+        }
+        return `apps/${backendTag}`;
+    }
+    /**
+     * Returns the appTag used for RTDB room presence paths.
+     * Personal spaces use "space::{namespaceId}" as the appTag in RTDB too.
+     */
+    getAppTag() {
+        return this.options.getRoomBackendTag().trim();
+    }
+    toRoomMember(document) {
+        const raw = document.data();
+        const nodeId = typeof raw.nodeId === 'string' && raw.nodeId.trim().length > 0
+            ? raw.nodeId.trim()
+            : document.id;
+        const ticket = typeof raw.ticket === 'string' ? raw.ticket : '';
+        return {
+            nodeId,
+            userId: typeof raw.userId === 'string' ? raw.userId : '',
+            ticket,
+            joinedAt: this.toMillis(raw.joinedAt) ?? 0,
+            lastSeenAt: this.toMillis(raw.lastSeenAt) ?? 0,
+            expiresAt: this.toMillis(raw.expiresAt),
+        };
+    }
+    isExpired(member, now) {
+        if (typeof member.expiresAt === 'number') {
+            return member.expiresAt <= now;
+        }
+        const referenceTime = member.lastSeenAt || member.joinedAt || 0;
+        return referenceTime > 0 && referenceTime + ROOM_MEMBER_TTL_MS <= now;
+    }
+    toMillis(value) {
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const asNumber = Number(value);
+            if (Number.isFinite(asNumber)) {
+                return asNumber;
+            }
+            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') {
+            try {
+                return value.toMillis();
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+}

package/dist/core/bridges/BrowserFirestoreSignaling.d.ts

@@ -0,0 +1,111 @@
+import type { FirebaseApp } from 'firebase/app';
+import type { Auth } from 'firebase/auth';
+import type { Device, DeviceEvent, DiscoveryMode, SessionEvent, SignalingEnvelope, SignalingSession } from '../types';
+import { RtdbPresence, type DiscoveryPresenceScope } from './RtdbPresence';
+export interface BrowserFirestoreSignalingOptions {
+    app: FirebaseApp;
+    auth: Auth;
+    appTag: string;
+    apiKey?: string;
+    spaceKey?: string;
+    discoveryMode?: DiscoveryMode;
+    getCurrentUserId: () => string | null;
+    getDiscoveryScopeId: () => string | null;
+    getLocalDeviceId: () => string;
+    getDefaultDeviceName: () => string;
+    matchesTag: (device: Pick<Device, 'tag' | 'appTag'>) => boolean;
+    normalizeDevice: (raw: Record<string, any>, fallbackId?: string) => Device;
+}
+export declare class BrowserFirestoreSignaling {
+    private readonly options;
+    private readonly deviceListeners;
+    private readonly devicesById;
+    private readonly staleDeviceOfflineWrites;
+    private readonly nextListenerIdSeed;
+    private activeDeviceScopeKey;
+    private activeDeviceUnsubscribe;
+    private deviceWatchGeneration;
+    private namespaceRootPromise;
+    private readonly firestore;
+    private rtdbPresence;
+    private rtdbScope;
+    private rtdbPresenceMap;
+    private rtdbUnsubscribe;
+    private readonly knownTicketVersions;
+    constructor(options: BrowserFirestoreSignalingOptions);
+    /**
+     * 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: RtdbPresence, scope: DiscoveryPresenceScope): void;
+    /** Stop RTDB subscription and clear scope. Called on sign-out or scope change. */
+    stopRtdbPresence(): void;
+    searchDevices(excludeNodeId?: string): Promise<Device[]>;
+    subscribeDevices(): Promise<ReadableStream<DeviceEvent[]>>;
+    onDevicesChange(callback: (devices: Device[]) => void, excludeNodeId?: string): () => void;
+    handleScopeChange(): Promise<void>;
+    stopAuthScopedActivity(): void;
+    updatePresence(localNodeId: string, ticketStr: string, isOnline: boolean, ttlMs: number, metadata?: string, deviceNameOverride?: string): Promise<void>;
+    setOffline(localNodeId: string): Promise<void>;
+    cleanupStaleDevices(): Promise<void>;
+    updateDevice(deviceId: string, updates: {
+        deviceName?: string;
+        capabilities?: Device['capabilities'];
+        metadata?: string;
+    }): Promise<void>;
+    deleteDevice(deviceId: string): Promise<void>;
+    createSession(session: SignalingSession): Promise<void>;
+    private shouldUseHostedSessionCallable;
+    private createHostedSession;
+    updateSession(sessionId: string, updateData: any): Promise<void>;
+    sendMessage(targetId: string, payload: string, state?: string, replyPayload?: string): Promise<string>;
+    pollMessages(targetId: string): Promise<SignalingEnvelope[]>;
+    subscribeSessions(localDeviceId: string): Promise<ReadableStream<SessionEvent[]>>;
+    private ensureDeviceWatch;
+    /**
+     * 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.
+     */
+    private ensureDeviceWatchRtdb;
+    /**
+     * 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).
+     */
+    private applyRtdbOverlay;
+    /**
+     * Re-fetch specific device docs from Firestore (ticket version changed).
+     * Updates devicesById and re-emits.
+     */
+    private refetchDeviceTickets;
+    refreshDeviceForAutoConnect(deviceId: string): Promise<Device | null>;
+    private stopDeviceWatch;
+    private emitDevicesToAll;
+    private emitDevicesToListener;
+    private filterDevices;
+    private readCurrentDeviceSnapshot;
+    private toDevice;
+    private deviceFromSnapshot;
+    private markStaleDeviceOffline;
+    private toSession;
+    private parseMaybeJson;
+    private isDeviceExpired;
+    private toMillis;
+    private getDevicesCollectionRef;
+    private getSessionsCollectionRef;
+    private getMessagesCollectionRef;
+    private getDevicesCollectionPath;
+    private getNamespaceRoot;
+    private usesPersonalSpaceMode;
+    private parseScopedId;
+    private getMessageSenderId;
+    private createDocumentId;
+    private resolveOrCreateLocalDeviceRef;
+    private resolveDeviceRef;
+}