openrtc 0.1.0

package/dist/core/bridges/WasmBridge.js

@@ -0,0 +1,1811 @@
+import { getAuthHost } from '../../auth/host';
+import { resolveAppTag, resolveAuthMode, resolveProjectId, resolveStorageNamespace } from '../config';
+import { BrowserFirestoreSignaling } from './BrowserFirestoreSignaling';
+import { RtdbPresence } from './RtdbPresence';
+import { openRtcDebug, openRtcDebugInfo } from '../../utils/debug';
+import { isPersonalSpaceMode as isPersonalDiscoveryMode, matchesDiscoveryTag, normalizeConnectionStateSnapshot as normalizeConnectionStateSnapshotRecord, normalizeDeviceRecord, normalizeDeviceStatusSnapshotRecord, normalizePeerSessionSnapshotRecord, peerSessionToBackendConnectionState, sameConnectionState as sameNormalizedConnectionState, } from './BridgeCodecs';
+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 summarizeCompoundTicketForLogs(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,
+    };
+}
+/**
+ * WasmBridge is the browser host wrapper over the Rust/WASM runtime.
+ *
+ * Allowed:
+ * - normalize JS/WASM binding shapes
+ * - forward auth, discovery, signaling, and lifecycle calls into Rust
+ * - expose typed browser-facing results
+ *
+ * Not allowed:
+ * - become a second lifecycle engine
+ * - invent peer identity or connect policy that is not backed by Rust
+ * - normalize app-specific payload protocols into runtime behavior
+ *
+ * Source of truth:
+ * - Rust/WASM owns lifecycle, discovery, signaling, and connection health
+ * - RuntimeClient owns app-facing orchestration
+ */
+export class WasmBridge {
+    /** Phase 2: expose the RTDB presence instance so RuntimeClient can wire it into RoomManager. */
+    get rtdbPresence() {
+        return this._rtdbPresence;
+    }
+    constructor(options) {
+        this.authListeners = [];
+        // To be injected/set once WASM boots
+        this.wasmClient = null;
+        this.createdAtMs = Date.now();
+        this.missingWasmWarnings = new Set();
+        this.wasmReadyWarningDelayMs = 15000;
+        this.browserFirestoreSignaling = null;
+        this.lastObservedFirebaseUserId = null;
+        this.sessionReaders = new Set();
+        this.authContext = null;
+        this.injectedBrowserAuthSessionActive = false;
+        this.startedAutoConnectKey = null;
+        this.autoConnectStartsInFlight = new Set();
+        this.browserAutoConnectUnsubscribe = null;
+        this.browserAutoConnectLastAttemptAt = new Map();
+        this.browserAutoConnectInFlight = new Set();
+        this.browserAutoConnectWaitStartedAt = new Map();
+        this.browserAutoConnectEscalationCount = new Map();
+        this.browserAutoConnectObservedSignatures = new Map();
+        this.browserAutoConnectRecoveryTimers = new Map();
+        this.browserAutoConnectPendingDevices = new Map();
+        this.browserAutoConnectScanTimer = null;
+        this.browserPresenceLoopInterval = null;
+        this.browserPresenceLoopState = null;
+        // Phase 1: RTDB presence — replaces the 60-second Firestore heartbeat loop.
+        // Exposed via getter so RuntimeClient can wire the same instance into RoomManager.
+        this._rtdbPresence = null;
+        this.rtdbPresenceScope = null;
+        this.rtdbTicketVersion = 0;
+        this.rtdbPresenceDisabledForSession = false;
+        this.hasSyncedAuthToWasmClient = false;
+        this.lastWasmAuthUserId = null;
+        this.lastWasmAuthToken = null;
+        this.lastDeliveredConnectionStates = new Map();
+        this.appTag = resolveAppTag(options);
+        this.options = {
+            ...options,
+            appTag: this.appTag,
+            authMode: resolveAuthMode(options),
+            projectId: resolveProjectId(options),
+        };
+        this.persistenceReady = Promise.resolve();
+        if (this.isTicketOnlyMode()) {
+            this.app = null;
+            this.auth = null;
+            return;
+        }
+        const authHost = getAuthHost();
+        this.app = authHost.getApp();
+        this.auth = authHost.getAuth();
+        authHost.onAuthStateChanged((user) => {
+            if (this.authContext) {
+                return;
+            }
+            if (this.isPersonalSpaceMode()) {
+                this.authListeners.forEach(cb => cb(this.toRuntimeIdentity(user)));
+                return;
+            }
+            const nextUserId = user?.uid ?? null;
+            const previousUserId = this.lastObservedFirebaseUserId;
+            this.lastObservedFirebaseUserId = nextUserId;
+            if (previousUserId && previousUserId !== nextUserId) {
+                void this.stopAuthScopedActivity({ userId: previousUserId });
+            }
+            void this.browserFirestoreSignaling?.handleScopeChange();
+            this.authListeners.forEach(cb => cb(this.toRuntimeIdentity(user)));
+        });
+    }
+    get tag() {
+        return this.appTag;
+    }
+    getDeviceIdentityStorageKey() {
+        const suffix = resolveStorageNamespace(this.options);
+        return `${WasmBridge.WEB_DEVICE_ID_STORAGE_PREFIX}_${suffix}`;
+    }
+    getNodeIdPersistenceMode() {
+        return this.options.nodeIdPersistence ?? 'persistent';
+    }
+    isTicketOnlyMode() {
+        return this.options.signalingMode === 'ticket-only';
+    }
+    createRandomDeviceId() {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        return `web-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+    resolveWebLogicalDeviceId() {
+        const mode = this.getNodeIdPersistenceMode();
+        if (typeof localStorage === 'undefined') {
+            return this.createRandomDeviceId();
+        }
+        const key = this.getDeviceIdentityStorageKey();
+        const now = Date.now();
+        let stored = null;
+        try {
+            const raw = localStorage.getItem(key);
+            stored = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            stored = null;
+        }
+        const storedDeviceId = typeof stored?.deviceId === 'string' ? stored.deviceId.trim() : '';
+        const storedExpiry = typeof stored?.expiresAt === 'number' ? stored.expiresAt : undefined;
+        if (mode === 'persistent') {
+            const nextDeviceId = storedDeviceId || this.createRandomDeviceId();
+            localStorage.setItem(key, JSON.stringify({ deviceId: nextDeviceId }));
+            return nextDeviceId;
+        }
+        if (storedDeviceId && typeof storedExpiry === 'number' && storedExpiry > now) {
+            const refreshedExpiry = now + WasmBridge.EPHEMERAL_DEVICE_ID_TTL_MS;
+            localStorage.setItem(key, JSON.stringify({ deviceId: storedDeviceId, expiresAt: refreshedExpiry }));
+            return storedDeviceId;
+        }
+        const nextDeviceId = this.createRandomDeviceId();
+        const expiresAt = now + WasmBridge.EPHEMERAL_DEVICE_ID_TTL_MS;
+        localStorage.setItem(key, JSON.stringify({ deviceId: nextDeviceId, expiresAt }));
+        return nextDeviceId;
+    }
+    getDefaultBrowserDeviceName() {
+        return this.options.deviceName?.trim() || (this.options.storagePrefix
+            ? `Web (${this.options.storagePrefix.replace(/_$/, '')})`
+            : 'Web Browser');
+    }
+    getBrowserFirestoreSignaling() {
+        if (this.isTicketOnlyMode()) {
+            throw new Error('[openrtc] Browser signaling is disabled when signalingMode="ticket-only".');
+        }
+        if (!this.browserFirestoreSignaling) {
+            this.browserFirestoreSignaling = new BrowserFirestoreSignaling({
+                app: this.app,
+                auth: this.auth,
+                appTag: this.appTag,
+                apiKey: this.options.apiKey,
+                spaceKey: this.options.spaceKey,
+                discoveryMode: this.options.discoveryMode,
+                getCurrentUserId: () => this.getCurrentUserId(),
+                getDiscoveryScopeId: () => this.getDiscoveryScopeId(),
+                getLocalDeviceId: () => this.resolveWebLogicalDeviceId(),
+                getDefaultDeviceName: () => this.getDefaultBrowserDeviceName(),
+                matchesTag: (device) => this.matchesTag(device),
+                normalizeDevice: (raw, fallbackId) => this.normalizeDevice(raw, fallbackId),
+            });
+        }
+        return this.browserFirestoreSignaling;
+    }
+    withWebPresenceMetadata(metadata, localDeviceId) {
+        if (!metadata || !metadata.trim()) {
+            return JSON.stringify({ deviceId: localDeviceId });
+        }
+        try {
+            const parsed = JSON.parse(metadata);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return JSON.stringify({
+                    ...parsed,
+                    deviceId: localDeviceId,
+                });
+            }
+        }
+        catch {
+            // fall through to opaque metadata wrapper
+        }
+        return JSON.stringify({
+            deviceId: localDeviceId,
+            metadata,
+        });
+    }
+    async setAuthContext(context) {
+        const previousInjectedSessionActive = this.injectedBrowserAuthSessionActive;
+        this.authContext = context;
+        if (!this.isTicketOnlyMode() && context?.customToken?.trim()) {
+            try {
+                await this.ensureBrowserFirestoreAuth(context.userId, context.customToken.trim());
+            }
+            catch (error) {
+                // Browser Firestore auth is only needed for the web-signaling fallback path.
+                // On native (Tauri/IPC) all device ops go through native IPC, so a failure
+                // here must not abort the auth context — doing so clears authContext and breaks
+                // device discovery on mobile where this sign-in can fail or be unavailable.
+                console.warn('[WasmBridge] ensureBrowserFirestoreAuth failed (non-fatal):', error);
+            }
+        }
+        else if (!this.isTicketOnlyMode() && !context && previousInjectedSessionActive) {
+            try {
+                await this.auth?.signOut();
+            }
+            catch (error) {
+                console.warn('[WasmBridge] Failed to clear injected browser auth session:', error);
+            }
+            finally {
+                this.injectedBrowserAuthSessionActive = false;
+            }
+        }
+        this.syncWasmAuthToken();
+        if (!this.isTicketOnlyMode()) {
+            await this.browserFirestoreSignaling?.handleScopeChange();
+        }
+        this.authListeners.forEach((callback) => callback(this.currentUser));
+    }
+    async ensureBrowserFirestoreAuth(userId, customToken) {
+        const currentUid = this.auth?.currentUser?.uid ?? null;
+        if (currentUid === userId) {
+            this.injectedBrowserAuthSessionActive = true;
+            return;
+        }
+        await getAuthHost().signInWithCustomTokenValue(customToken);
+        this.injectedBrowserAuthSessionActive = true;
+    }
+    syncWasmAuthToken() {
+        if (!this.wasmClient || typeof this.wasmClient.set_auth_token !== 'function') {
+            return;
+        }
+        const nextUserId = this.authContext?.userId ?? null;
+        const nextToken = this.authContext?.token ?? null;
+        if (this.hasSyncedAuthToWasmClient &&
+            this.lastWasmAuthUserId === nextUserId &&
+            this.lastWasmAuthToken === nextToken) {
+            return;
+        }
+        this.lastWasmAuthUserId = nextUserId;
+        this.lastWasmAuthToken = nextToken;
+        this.hasSyncedAuthToWasmClient = true;
+        this.wasmClient.set_auth_token(nextToken);
+    }
+    toRuntimeIdentity(user) {
+        if (!user) {
+            return null;
+        }
+        return {
+            id: user.uid,
+            email: user.email,
+            displayName: user.displayName,
+            isAnonymous: user.isAnonymous,
+            getToken: async (forceRefresh = false) => {
+                try {
+                    return await user.getIdToken(forceRefresh);
+                }
+                catch {
+                    return null;
+                }
+            },
+        };
+    }
+    getCurrentUserId() {
+        if (this.authContext?.userId) {
+            return this.authContext.userId;
+        }
+        if (this.isTicketOnlyMode()) {
+            return null;
+        }
+        return this.auth?.currentUser?.uid ?? null;
+    }
+    getCurrentUserIdForScope() {
+        return this.getCurrentUserId();
+    }
+    getAuthContext() {
+        return this.authContext;
+    }
+    isPersonalSpaceMode() {
+        return isPersonalDiscoveryMode(this.options);
+    }
+    getResolvedOptions() {
+        return this.options;
+    }
+    usesLegacyBrowserSignalingFallback() {
+        if (this.isTicketOnlyMode()) {
+            return false;
+        }
+        if (this.isPersonalSpaceMode()) {
+            return false;
+        }
+        const hasApiKey = typeof this.options.apiKey === 'string' && this.options.apiKey.trim().length > 0;
+        return !hasApiKey;
+    }
+    getDiscoveryScopeId() {
+        if (this.isTicketOnlyMode()) {
+            return null;
+        }
+        const currentUserId = this.getCurrentUserId();
+        if (currentUserId) {
+            return currentUserId;
+        }
+        if (this.isPersonalSpaceMode()) {
+            return this.resolveWebLogicalDeviceId();
+        }
+        return null;
+    }
+    matchesTag(device) {
+        return matchesDiscoveryTag(device, this.appTag, this.isPersonalSpaceMode());
+    }
+    matchesDiscoveryTag(device) {
+        return this.matchesTag(device);
+    }
+    async stopSessionSubscriptions() {
+        const readers = Array.from(this.sessionReaders);
+        this.sessionReaders.clear();
+        await Promise.allSettled(readers.map(async (reader) => {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // noop
+            }
+        }));
+    }
+    async stopRuntimeAuthScopedLoops() {
+        const wasmClient = await this.waitForWasmClient(250);
+        if (!wasmClient) {
+            return;
+        }
+        try {
+            if (typeof wasmClient.stop_auth_scoped_activity === 'function') {
+                wasmClient.stop_auth_scoped_activity();
+            }
+            else {
+                if (typeof wasmClient.stop_presence_loop === 'function') {
+                    wasmClient.stop_presence_loop();
+                }
+                if (typeof wasmClient.stop_auto_connect === 'function') {
+                    wasmClient.stop_auto_connect();
+                }
+            }
+        }
+        catch (error) {
+            console.warn('[WasmSignaling] Failed to stop auth-scoped runtime loops:', error);
+        }
+    }
+    stopBrowserAutoConnect() {
+        this.browserAutoConnectUnsubscribe?.();
+        this.browserAutoConnectUnsubscribe = null;
+        if (this.browserAutoConnectScanTimer) {
+            clearTimeout(this.browserAutoConnectScanTimer);
+            this.browserAutoConnectScanTimer = null;
+        }
+        this.browserAutoConnectPendingDevices.clear();
+        this.startedAutoConnectKey = null;
+        this.autoConnectStartsInFlight.clear();
+        this.browserAutoConnectInFlight.clear();
+        this.browserAutoConnectLastAttemptAt.clear();
+        this.browserAutoConnectWaitStartedAt.clear();
+        this.browserAutoConnectEscalationCount.clear();
+        this.browserAutoConnectObservedSignatures.clear();
+        for (const timer of this.browserAutoConnectRecoveryTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.browserAutoConnectRecoveryTimers.clear();
+    }
+    clearBrowserAutoConnectDeviceState(deviceKey) {
+        this.browserAutoConnectWaitStartedAt.delete(deviceKey);
+        this.browserAutoConnectEscalationCount.delete(deviceKey);
+        this.browserAutoConnectLastAttemptAt.delete(deviceKey);
+        const timer = this.browserAutoConnectRecoveryTimers.get(deviceKey);
+        if (timer) {
+            clearTimeout(timer);
+            this.browserAutoConnectRecoveryTimers.delete(deviceKey);
+        }
+    }
+    queueBrowserAutoConnectRecoveryForDevice(targetDevice, options) {
+        if (!targetDevice?.deviceId) {
+            return;
+        }
+        const deviceKey = targetDevice.deviceId;
+        this.browserAutoConnectInFlight.delete(deviceKey);
+        this.browserAutoConnectObservedSignatures.delete(deviceKey);
+        this.browserAutoConnectLastAttemptAt.delete(deviceKey);
+        if (options?.resetWaitStartedAt) {
+            this.browserAutoConnectWaitStartedAt.delete(deviceKey);
+        }
+        const localNodeId = typeof this.browserPresenceLoopState?.localNodeId === 'string'
+            ? this.browserPresenceLoopState.localNodeId.trim() || null
+            : null;
+        const localDeviceId = this.resolveWebLogicalDeviceId();
+        this.scheduleBrowserAutoConnectScan([...this.browserAutoConnectPendingDevices.values()], localNodeId, localDeviceId);
+        const existingTimer = this.browserAutoConnectRecoveryTimers.get(deviceKey);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        const retryTimer = setTimeout(() => {
+            this.browserAutoConnectRecoveryTimers.delete(deviceKey);
+            if (!this.browserAutoConnectPendingDevices.has(deviceKey)) {
+                return;
+            }
+            this.browserAutoConnectInFlight.delete(deviceKey);
+            this.browserAutoConnectObservedSignatures.delete(deviceKey);
+            this.browserAutoConnectLastAttemptAt.delete(deviceKey);
+            const retryLocalNodeId = typeof this.browserPresenceLoopState?.localNodeId === 'string'
+                ? this.browserPresenceLoopState.localNodeId.trim() || null
+                : null;
+            this.scheduleBrowserAutoConnectScan([...this.browserAutoConnectPendingDevices.values()], retryLocalNodeId, this.resolveWebLogicalDeviceId());
+        }, WasmBridge.BROWSER_AUTO_CONNECT_SETTLE_GUARD_MS + 100);
+        this.browserAutoConnectRecoveryTimers.set(deviceKey, retryTimer);
+    }
+    triggerBrowserAutoConnectRecovery(state) {
+        if (!this.startedAutoConnectKey || this.browserAutoConnectPendingDevices.size === 0) {
+            return;
+        }
+        const targetDevice = [...this.browserAutoConnectPendingDevices.values()].find((device) => {
+            const deviceId = typeof device.deviceId === 'string' ? device.deviceId.trim() : '';
+            const nodeId = typeof device.nodeId === 'string' ? device.nodeId.trim() : '';
+            return ((!!state.deviceId && deviceId === state.deviceId) ||
+                (!!state.deviceIdHint && deviceId === state.deviceIdHint) ||
+                (!!state.remoteNodeId && nodeId === state.remoteNodeId));
+        });
+        if (!targetDevice?.deviceId) {
+            return;
+        }
+        this.queueBrowserAutoConnectRecoveryForDevice(targetDevice);
+    }
+    browserAutoConnectLifecycleFresh(lastLifecycleTransitionAtMs) {
+        return (typeof lastLifecycleTransitionAtMs === 'number' &&
+            lastLifecycleTransitionAtMs > 0 &&
+            Date.now() - lastLifecycleTransitionAtMs <
+                WasmBridge.BROWSER_AUTO_CONNECT_SETTLE_GUARD_MS);
+    }
+    getRustOwnedAutoConnectGate(device) {
+        const deviceId = typeof device.deviceId === 'string' ? device.deviceId.trim() : '';
+        const remoteNodeId = typeof device.nodeId === 'string' ? device.nodeId.trim() : '';
+        if (!deviceId && !remoteNodeId) {
+            return 'none';
+        }
+        let hasTransitionalGate = false;
+        for (const state of this.lastDeliveredConnectionStates.values()) {
+            const matchesDeviceId = deviceId.length > 0 &&
+                (state.deviceId === deviceId || state.deviceIdHint === deviceId);
+            const matchesRemoteNodeId = remoteNodeId.length > 0 &&
+                state.remoteNodeId === remoteNodeId;
+            if (!matchesDeviceId && !matchesRemoteNodeId) {
+                continue;
+            }
+            if (state.replacementInProgress) {
+                if (this.browserAutoConnectLifecycleFresh(state.lastLifecycleTransitionAtMs)) {
+                    hasTransitionalGate = true;
+                }
+                continue;
+            }
+            if (state.state === 'connecting') {
+                if (state.routable === true) {
+                    return 'healthy';
+                }
+                if (this.browserAutoConnectLifecycleFresh(state.lastLifecycleTransitionAtMs)) {
+                    hasTransitionalGate = true;
+                }
+                continue;
+            }
+            if (state.state === 'connected') {
+                if (state.routable === true) {
+                    return 'healthy';
+                }
+                if (this.browserAutoConnectLifecycleFresh(state.lastLifecycleTransitionAtMs)) {
+                    hasTransitionalGate = true;
+                }
+                continue;
+            }
+            if (state.state === 'pending') {
+                hasTransitionalGate = true;
+            }
+        }
+        return hasTransitionalGate ? 'transitional' : 'none';
+    }
+    browserAutoConnectNonInitiatorGraceMs(escalationCount) {
+        const cappedCount = Math.max(0, Math.min(3, Math.trunc(escalationCount)));
+        const baseMs = 2000;
+        const expMs = Math.min(baseMs * (1 << cappedCount), 16000);
+        const jitterPct = (((cappedCount * 37) + 7) % 41) - 20;
+        return Math.max(1000, expMs + Math.trunc((expMs * jitterPct) / 100));
+    }
+    queueBrowserAutoConnectGraceExpiryRecheck(deviceKey, delayMs) {
+        if (!deviceKey) {
+            return;
+        }
+        const existingTimer = this.browserAutoConnectRecoveryTimers.get(deviceKey);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        const retryTimer = setTimeout(() => {
+            this.browserAutoConnectRecoveryTimers.delete(deviceKey);
+            if (!this.browserAutoConnectPendingDevices.has(deviceKey)) {
+                return;
+            }
+            this.browserAutoConnectObservedSignatures.delete(deviceKey);
+            const localNodeId = typeof this.browserPresenceLoopState?.localNodeId === 'string'
+                ? this.browserPresenceLoopState.localNodeId.trim() || null
+                : null;
+            this.scheduleBrowserAutoConnectScan([...this.browserAutoConnectPendingDevices.values()], localNodeId, this.resolveWebLogicalDeviceId());
+        }, Math.max(50, Math.trunc(delayMs)));
+        this.browserAutoConnectRecoveryTimers.set(deviceKey, retryTimer);
+    }
+    async shouldAttemptBrowserAutoConnectDial(device, localNodeId, localDeviceId) {
+        if (!device.online || !device.ticket || !device.deviceId) {
+            return false;
+        }
+        if (device.deviceId === localDeviceId) {
+            return false;
+        }
+        const deviceKey = device.deviceId;
+        const remoteNodeId = typeof device.nodeId === 'string' ? device.nodeId.trim() : '';
+        const rustOwnedGate = this.getRustOwnedAutoConnectGate(device);
+        if (rustOwnedGate !== 'none') {
+            if (rustOwnedGate === 'healthy' && remoteNodeId.length > 0) {
+                this.clearBrowserAutoConnectDeviceState(deviceKey);
+            }
+            return false;
+        }
+        const sessionLookupId = device.deviceId || remoteNodeId;
+        const session = sessionLookupId
+            ? await this.getPeerSession(sessionLookupId).catch(() => null)
+            : null;
+        if (session?.settledReady) {
+            this.clearBrowserAutoConnectDeviceState(deviceKey);
+            return false;
+        }
+        const lastTransitionAtMs = typeof session?.lastLifecycleTransitionAtMs === 'number'
+            ? session.lastLifecycleTransitionAtMs
+            : 0;
+        const withinSettleGuard = this.browserAutoConnectLifecycleFresh(lastTransitionAtMs);
+        const sessionHasActiveTransport = session?.activeTransportStableId != null;
+        const transportConnected = remoteNodeId.length > 0 &&
+            await this.isConnected(remoteNodeId).catch(() => false);
+        if ((session?.replacementPending && withinSettleGuard) ||
+            (session?.status === 'connecting' &&
+                (withinSettleGuard || sessionHasActiveTransport)) ||
+            (session?.status === 'connected' &&
+                withinSettleGuard) ||
+            (transportConnected && withinSettleGuard)) {
+            if (session?.settledReady) {
+                this.clearBrowserAutoConnectDeviceState(deviceKey);
+            }
+            return false;
+        }
+        if (!localNodeId || !remoteNodeId) {
+            return true;
+        }
+        if (localNodeId > remoteNodeId) {
+            this.browserAutoConnectWaitStartedAt.delete(deviceKey);
+            return true;
+        }
+        const now = Date.now();
+        const escalationCount = this.browserAutoConnectEscalationCount.get(deviceKey) ?? 0;
+        const waitStartedAt = this.browserAutoConnectWaitStartedAt.get(deviceKey) ?? now;
+        if (!this.browserAutoConnectWaitStartedAt.has(deviceKey)) {
+            this.browserAutoConnectWaitStartedAt.set(deviceKey, waitStartedAt);
+        }
+        const waitedMs = now - waitStartedAt;
+        const graceMs = this.browserAutoConnectNonInitiatorGraceMs(escalationCount);
+        if (waitedMs < graceMs) {
+            this.queueBrowserAutoConnectGraceExpiryRecheck(deviceKey, graceMs - waitedMs + 25);
+            return false;
+        }
+        this.browserAutoConnectWaitStartedAt.delete(deviceKey);
+        this.browserAutoConnectEscalationCount.set(deviceKey, escalationCount + 1);
+        return true;
+    }
+    async hasHealthyBrowserAutoConnectSession(device) {
+        const remoteNodeId = typeof device.nodeId === 'string' ? device.nodeId.trim() : '';
+        const rustOwnedGate = this.getRustOwnedAutoConnectGate(device);
+        if (rustOwnedGate !== 'none') {
+            return true;
+        }
+        const lookupId = device.deviceId || remoteNodeId;
+        if (!lookupId) {
+            return false;
+        }
+        const session = await this.getPeerSession(lookupId).catch(() => null);
+        if (session?.settledReady) {
+            return true;
+        }
+        const withinSettleGuard = this.browserAutoConnectLifecycleFresh(session?.lastLifecycleTransitionAtMs);
+        if (withinSettleGuard &&
+            (((session?.status === 'connecting' || session?.status === 'connected') &&
+                session.activeTransportStableId != null) ||
+                (remoteNodeId.length > 0 &&
+                    await this.isConnected(remoteNodeId).catch(() => false)))) {
+            return true;
+        }
+        return false;
+    }
+    browserAutoConnectSignature(device) {
+        const updatedAt = typeof device.updatedAt === 'number'
+            ? device.updatedAt
+            : typeof device.updatedAt?.toMillis === 'function'
+                ? device.updatedAt.toMillis()
+                : typeof device.lastSeenAt === 'number'
+                    ? device.lastSeenAt
+                    : typeof device.lastSeenAt?.toMillis === 'function'
+                        ? device.lastSeenAt.toMillis()
+                        : 0;
+        return JSON.stringify({
+            deviceId: device.deviceId,
+            nodeId: device.nodeId ?? null,
+            online: !!device.online,
+            ticket: device.ticket ?? null,
+            updatedAt,
+        });
+    }
+    async refreshBrowserAutoConnectDeviceForDial(device) {
+        const deviceId = typeof device.deviceId === 'string' ? device.deviceId.trim() : '';
+        if (!deviceId) {
+            return device;
+        }
+        const refreshed = await this.getBrowserFirestoreSignaling()
+            .refreshDeviceForAutoConnect(deviceId)
+            .catch((error) => {
+            console.warn('[WasmSignaling][auto-connect][dial-refresh] failed to refresh device ticket before dial', {
+                deviceId,
+                error,
+                cachedTicket: summarizeCompoundTicketForLogs(device.ticket),
+            });
+            return null;
+        });
+        const effective = refreshed ?? device;
+        const ticketChanged = (effective.ticket ?? null) !== (device.ticket ?? null);
+        const nodeChanged = (effective.nodeId ?? null) !== (device.nodeId ?? null);
+        console.info('[WasmSignaling][auto-connect][dial-ticket]', {
+            deviceId,
+            ticketChanged,
+            nodeChanged,
+            cachedTicket: summarizeCompoundTicketForLogs(device.ticket),
+            effectiveTicket: summarizeCompoundTicketForLogs(effective.ticket),
+            cachedNodeId: device.nodeId ?? null,
+            effectiveNodeId: effective.nodeId ?? null,
+        });
+        return effective;
+    }
+    scheduleBrowserAutoConnectScan(devices, localNodeId, localDeviceId) {
+        this.browserAutoConnectPendingDevices = new Map(devices
+            .filter((device) => !!device.deviceId)
+            .map((device) => [device.deviceId, device]));
+        if (this.browserAutoConnectScanTimer) {
+            return;
+        }
+        this.browserAutoConnectScanTimer = setTimeout(() => {
+            this.browserAutoConnectScanTimer = null;
+            void this.processBrowserAutoConnectSnapshot(localNodeId, localDeviceId);
+        }, WasmBridge.BROWSER_AUTO_CONNECT_SCAN_DEBOUNCE_MS);
+    }
+    async processBrowserAutoConnectSnapshot(localNodeId, localDeviceId) {
+        const devicesById = new Map(this.browserAutoConnectPendingDevices);
+        const activeDeviceIds = new Set(devicesById.keys());
+        for (const deviceId of Array.from(this.browserAutoConnectObservedSignatures.keys())) {
+            if (activeDeviceIds.has(deviceId)) {
+                continue;
+            }
+            this.browserAutoConnectObservedSignatures.delete(deviceId);
+            this.clearBrowserAutoConnectDeviceState(deviceId);
+        }
+        for (const device of devicesById.values()) {
+            if (!device.deviceId) {
+                continue;
+            }
+            const deviceKey = device.deviceId;
+            const nextSignature = this.browserAutoConnectSignature(device);
+            const previousSignature = this.browserAutoConnectObservedSignatures.get(deviceKey) ?? null;
+            const lastAttemptAt = this.browserAutoConnectLastAttemptAt.get(deviceKey) ?? 0;
+            const shouldReevaluateUnchanged = lastAttemptAt > 0 &&
+                Date.now() - lastAttemptAt >= WasmBridge.BROWSER_AUTO_CONNECT_RETRY_COOLDOWN_MS;
+            if (previousSignature === nextSignature && !shouldReevaluateUnchanged) {
+                continue;
+            }
+            this.browserAutoConnectObservedSignatures.set(deviceKey, nextSignature);
+            if (this.browserAutoConnectInFlight.has(deviceKey)) {
+                continue;
+            }
+            this.browserAutoConnectInFlight.add(deviceKey);
+            void (async () => {
+                try {
+                    const shouldAttempt = await this.shouldAttemptBrowserAutoConnectDial(device, localNodeId, localDeviceId);
+                    if (!shouldAttempt) {
+                        return;
+                    }
+                    const now = Date.now();
+                    const lastAttemptAtInner = this.browserAutoConnectLastAttemptAt.get(deviceKey) ?? 0;
+                    if (now - lastAttemptAtInner <
+                        WasmBridge.BROWSER_AUTO_CONNECT_RETRY_COOLDOWN_MS) {
+                        return;
+                    }
+                    if (await this.hasHealthyBrowserAutoConnectSession(device)) {
+                        this.clearBrowserAutoConnectDeviceState(deviceKey);
+                        return;
+                    }
+                    const effectiveDevice = await this.refreshBrowserAutoConnectDeviceForDial(device);
+                    if (!effectiveDevice?.ticket) {
+                        console.warn('[WasmSignaling][auto-connect][dial] skipped because the refreshed device has no ticket', {
+                            deviceId: device.deviceId,
+                            cachedTicket: summarizeCompoundTicketForLogs(device.ticket),
+                        });
+                        return;
+                    }
+                    const refreshedSignature = this.browserAutoConnectSignature(effectiveDevice);
+                    this.browserAutoConnectPendingDevices.set(deviceKey, effectiveDevice);
+                    this.browserAutoConnectObservedSignatures.set(deviceKey, refreshedSignature);
+                    if (await this.hasHealthyBrowserAutoConnectSession(effectiveDevice)) {
+                        this.clearBrowserAutoConnectDeviceState(deviceKey);
+                        return;
+                    }
+                    this.browserAutoConnectLastAttemptAt.set(deviceKey, now);
+                    await this.connectToDevice({
+                        deviceId: effectiveDevice.deviceId,
+                        endpointTicket: effectiveDevice.ticket,
+                    });
+                }
+                catch (error) {
+                    if (await this.hasHealthyBrowserAutoConnectSession(device).catch(() => false)) {
+                        this.clearBrowserAutoConnectDeviceState(deviceKey);
+                        return;
+                    }
+                    console.warn('[WasmSignaling] browser auto-connect attempt failed:', {
+                        deviceId: device.deviceId,
+                        ticket: summarizeCompoundTicketForLogs(device.ticket),
+                        error,
+                    });
+                }
+                finally {
+                    this.browserAutoConnectInFlight.delete(deviceKey);
+                }
+            })();
+        }
+    }
+    stopBrowserPresenceLoop() {
+        if (this.browserPresenceLoopInterval) {
+            clearInterval(this.browserPresenceLoopInterval);
+            this.browserPresenceLoopInterval = null;
+        }
+        this.browserPresenceLoopState = null;
+    }
+    disableRtdbPresenceForSession(reason, error) {
+        if (!this.rtdbPresenceDisabledForSession) {
+            console.warn(`[WasmBridge] Disabling RTDB presence for this browser session (${reason})`, error);
+        }
+        this.rtdbPresenceDisabledForSession = true;
+        this.rtdbPresenceScope = null;
+        this.browserFirestoreSignaling?.stopRtdbPresence();
+    }
+    startLegacyBrowserPresenceLoop() {
+        const tick = () => {
+            const state = this.browserPresenceLoopState;
+            if (!state) {
+                return;
+            }
+            const devId = this.resolveWebLogicalDeviceId();
+            const mergedMetadata = this.withWebPresenceMetadata(state.metadata, devId);
+            void this.updatePresence(state.localNodeId, state.ticket, true, 300000, mergedMetadata, state.deviceName).catch((error) => {
+                console.warn('[WasmBridge] browser presence tick failed:', error);
+            });
+        };
+        tick();
+        this.browserPresenceLoopInterval = setInterval(tick, 60000);
+    }
+    /**
+     * Phase 1: Register RTDB presence for the current device.
+     *
+     * Initialises an RtdbPresence instance (lazy, one per WasmBridge), wires
+     * it into the BrowserFirestoreSignaling device watcher so RTDB state is
+     * used for the online/offline overlay, and registers this device as online
+     * with an onDisconnect cleanup hook.
+     *
+     * Called by startPresenceLoop (and directly from updatePresence when the
+     * ticket changes after initial registration).
+     */
+    async registerRtdbPresence(scope, deviceId, ticketVersion) {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        if (!this._rtdbPresence) {
+            this._rtdbPresence = new RtdbPresence(this.app);
+        }
+        this.rtdbPresenceScope = scope;
+        const version = ticketVersion ?? this.rtdbTicketVersion;
+        // Wire scope into the signaling layer so device watcher uses RTDB.
+        const signaling = this.getBrowserFirestoreSignaling();
+        signaling.setRtdbPresence(this._rtdbPresence, scope);
+        try {
+            await this._rtdbPresence.registerDevice(scope, deviceId, version);
+        }
+        catch (error) {
+            this.disableRtdbPresenceForSession('registerDevice failed', error);
+            throw error;
+        }
+    }
+    async stopAuthScopedActivity(options) {
+        void options;
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.revoke_tokens_by_scope === 'function') {
+            try {
+                await wasmClient.revoke_tokens_by_scope('user-device');
+            }
+            catch (error) {
+                console.warn('[WasmBridge] user-device revoke during auth-scoped shutdown failed:', error);
+            }
+        }
+        this.stopBrowserAutoConnect();
+        this.stopBrowserPresenceLoop();
+        // Phase 1: clear RTDB scope so next login re-registers cleanly.
+        this.rtdbPresenceDisabledForSession = false;
+        this.rtdbPresenceScope = null;
+        this.rtdbTicketVersion = 0;
+        this.browserFirestoreSignaling?.stopAuthScopedActivity();
+        await this.stopSessionSubscriptions();
+        this.lastDeliveredConnectionStates.clear();
+        this.startedAutoConnectKey = null;
+        this.autoConnectStartsInFlight.clear();
+        await this.stopRuntimeAuthScopedLoops();
+    }
+    setWasmClient(client) {
+        this.wasmClient = client;
+        this.hasSyncedAuthToWasmClient = false;
+        this.lastDeliveredConnectionStates.clear();
+        this.syncWasmAuthToken();
+    }
+    warnMissingWasmOnce(method) {
+        if (!this.wasmClient && Date.now() - this.createdAtMs < this.wasmReadyWarningDelayMs) {
+            return;
+        }
+        if (this.missingWasmWarnings.has(method)) {
+            return;
+        }
+        this.missingWasmWarnings.add(method);
+        console.warn(`[WasmSignaling] ${method} skipped: wasm client is not ready.`);
+    }
+    async waitForWasmClient(timeoutMs = 4000, pollMs = 50) {
+        if (this.wasmClient) {
+            return this.wasmClient;
+        }
+        const start = Date.now();
+        while (!this.wasmClient && Date.now() - start < timeoutMs) {
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        return this.wasmClient ?? null;
+    }
+    normalizeDevice(raw, fallbackId) {
+        return normalizeDeviceRecord(raw, fallbackId);
+    }
+    normalizeDeviceRecord(raw, fallbackId) {
+        return this.normalizeDevice(raw, fallbackId);
+    }
+    getResolvedWebLogicalDeviceId() {
+        return this.resolveWebLogicalDeviceId();
+    }
+    normalizeDeviceStatusSnapshot(raw) {
+        return normalizeDeviceStatusSnapshotRecord(raw);
+    }
+    normalizePeerSessionSnapshot(raw) {
+        return normalizePeerSessionSnapshotRecord(raw);
+    }
+    toBackendConnectionStateFromPeerSession(snapshot) {
+        return peerSessionToBackendConnectionState(snapshot);
+    }
+    normalizeConnectionStateSnapshot(raw) {
+        return normalizeConnectionStateSnapshotRecord(raw);
+    }
+    normalizeWindowConnectionStateDetail(detail) {
+        return this.normalizeConnectionStateSnapshot(detail);
+    }
+    stabilizeConnectionState(state) {
+        const previous = this.lastDeliveredConnectionStates.get(state.connectionId);
+        return {
+            ...state,
+            deviceId: state.deviceId ?? previous?.deviceId ?? null,
+            deviceIdHint: state.deviceIdHint ?? previous?.deviceIdHint ?? null,
+            remoteNodeId: state.remoteNodeId ?? previous?.remoteNodeId ?? null,
+            createdAt: state.createdAt ?? previous?.createdAt,
+            updatedAt: state.updatedAt ?? previous?.updatedAt,
+        };
+    }
+    sameConnectionState(left, right) {
+        return sameNormalizedConnectionState(left, right);
+    }
+    deliverConnectionState(state, callback, source, subscriberDedup) {
+        const stabilized = this.stabilizeConnectionState(state);
+        // Always update shared cache for stabilization of future events
+        this.lastDeliveredConnectionStates.set(stabilized.connectionId, stabilized);
+        // Per-subscriber dedup: use subscriber-local map when provided
+        const dedupMap = subscriberDedup ?? this.lastDeliveredConnectionStates;
+        const previous = dedupMap.get(stabilized.connectionId);
+        if (this.sameConnectionState(previous, stabilized)) {
+            return;
+        }
+        if (subscriberDedup) {
+            subscriberDedup.set(stabilized.connectionId, stabilized);
+        }
+        if (source === 'event') {
+            openRtcDebug('[WasmBridge] connection-state-changed event', {
+                connectionId: stabilized.connectionId,
+                deviceId: stabilized.deviceId ?? null,
+                deviceIdHint: stabilized.deviceIdHint ?? null,
+                remoteNodeId: stabilized.remoteNodeId ?? null,
+                state: stabilized.state,
+                transportState: stabilized.transportState ?? null,
+                protocolState: stabilized.protocolState ?? null,
+                routable: stabilized.routable ?? null,
+                error: stabilized.error ?? null,
+            });
+        }
+        if (source === 'event' &&
+            (stabilized.replacementInProgress ||
+                (stabilized.state === 'connecting' &&
+                    !stabilized.routable &&
+                    stabilized.activeTransportStableId == null))) {
+            this.triggerBrowserAutoConnectRecovery(stabilized);
+        }
+        callback(stabilized);
+    }
+    async enrichBackendConnectionState(state) {
+        const session = await this.getPeerSession(state.connectionId).catch(() => null);
+        const fromSession = session ? this.toBackendConnectionStateFromPeerSession(session) : null;
+        if (fromSession) {
+            const updatedAt = Math.max(state.updatedAt ?? 0, fromSession.updatedAt ?? 0) || undefined;
+            const preferRawRoutable = !!state.routable && !fromSession.routable;
+            return {
+                ...fromSession,
+                ...state,
+                deviceId: fromSession.deviceId ?? state.deviceId ?? null,
+                deviceIdHint: fromSession.deviceIdHint ?? state.deviceIdHint ?? null,
+                remoteNodeId: fromSession.remoteNodeId ?? state.remoteNodeId ?? null,
+                state: preferRawRoutable ? state.state : fromSession.state,
+                transportState: preferRawRoutable
+                    ? (state.transportState ?? fromSession.transportState)
+                    : fromSession.transportState,
+                protocolState: preferRawRoutable
+                    ? (state.protocolState ?? fromSession.protocolState)
+                    : fromSession.protocolState,
+                routable: preferRawRoutable ? state.routable : fromSession.routable,
+                transportGeneration: state.transportGeneration ?? fromSession.transportGeneration,
+                replacementInProgress: state.replacementInProgress ?? fromSession.replacementInProgress,
+                transitionCount: state.transitionCount ?? fromSession.transitionCount,
+                connectingTransitionCount: state.connectingTransitionCount ?? fromSession.connectingTransitionCount,
+                replacementCount: state.replacementCount ?? fromSession.replacementCount,
+                retireCount: state.retireCount ?? fromSession.retireCount,
+                lastDisconnectReason: state.lastDisconnectReason ?? fromSession.lastDisconnectReason,
+                lastReconnectReason: state.lastReconnectReason ?? fromSession.lastReconnectReason,
+                createdAt: state.createdAt ?? fromSession.updatedAt,
+                updatedAt,
+            };
+        }
+        const identity = await this.resolvePeerIdentity(state.connectionId).catch(() => null);
+        return {
+            ...state,
+            deviceId: state.deviceId ?? identity?.deviceId ?? null,
+            deviceIdHint: state.deviceIdHint ?? identity?.deviceIdHint ?? null,
+            remoteNodeId: state.remoteNodeId ?? identity?.nodeId ?? null,
+        };
+    }
+    get currentUser() {
+        if (this.authContext?.userId) {
+            const token = this.authContext.token ?? null;
+            const tokenProvider = this.authContext.tokenProvider;
+            return {
+                id: this.authContext.userId,
+                getToken: async (forceRefresh = false) => {
+                    if (token && (!forceRefresh || !tokenProvider)) {
+                        return token;
+                    }
+                    if (tokenProvider) {
+                        try {
+                            const refreshed = await tokenProvider(forceRefresh);
+                            if (refreshed) {
+                                return refreshed;
+                            }
+                        }
+                        catch {
+                            // fall through to Firebase auth state
+                        }
+                    }
+                    // When authContext is user-scoped without an explicit token,
+                    // fall back to Firebase auth state if it matches this user.
+                    const firebaseUser = this.isTicketOnlyMode() ? null : (this.auth?.currentUser ?? null);
+                    if (firebaseUser &&
+                        firebaseUser.uid === this.authContext?.userId) {
+                        try {
+                            return await firebaseUser.getIdToken(forceRefresh);
+                        }
+                        catch {
+                            return null;
+                        }
+                    }
+                    return null;
+                },
+            };
+        }
+        if (this.isTicketOnlyMode()) {
+            return null;
+        }
+        return this.toRuntimeIdentity(this.auth?.currentUser ?? null);
+    }
+    onAuthChange(callback) {
+        this.authListeners.push(callback);
+        callback(this.currentUser);
+        return () => {
+            this.authListeners = this.authListeners.filter(cb => cb !== callback);
+        };
+    }
+    async checkForSSOToken() {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        await getAuthHost().checkForSSOToken();
+    }
+    async waitForAuth() {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        if (this.isPersonalSpaceMode()) {
+            return;
+        }
+        if (this.authContext?.userId || this.auth?.currentUser) {
+            return;
+        }
+        await getAuthHost().waitForAuth();
+    }
+    async signInAnonymously() {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        if (this.options.authMode !== 'anonymous') {
+            throw new Error(`[pluto-rtc] Anonymous sign-in is disabled when authMode=${this.options.authMode}.`);
+        }
+        await getAuthHost().signInAnonymously();
+    }
+    async signInWithPluto() {
+        if (this.isTicketOnlyMode()) {
+            throw new Error('[openrtc] Pluto sign-in is unavailable when signalingMode="ticket-only".');
+        }
+        await getAuthHost().signInWithPluto();
+    }
+    async signOut() {
+        const userId = this.getCurrentUserId();
+        await this.stopAuthScopedActivity({ userId });
+        this.authContext = null;
+        this.hasSyncedAuthToWasmClient = false;
+        this.syncWasmAuthToken();
+        if (!this.isTicketOnlyMode()) {
+            await this.auth?.signOut();
+        }
+        this.authListeners.forEach((callback) => callback(this.currentUser));
+    }
+    async getTurnCredentials() {
+        if (this.isTicketOnlyMode())
+            return null;
+        if (!this.auth?.currentUser)
+            return null;
+        // In the future this should come from Rust/Tauri IPC.
+        return null;
+    }
+    async updatePresence(localNodeId, ticketStr, isOnline = true, ttlMs = 300000, metadata, deviceNameOverride) {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        const localDeviceId = this.resolveWebLogicalDeviceId();
+        const effectiveTtlMs = this.getNodeIdPersistenceMode() === 'ephemeral'
+            ? WasmBridge.EPHEMERAL_DEVICE_ID_TTL_MS
+            : ttlMs;
+        const mergedMetadata = this.withWebPresenceMetadata(metadata, localDeviceId);
+        this.browserPresenceLoopState = {
+            localNodeId,
+            ticket: ticketStr,
+            metadata: mergedMetadata,
+            deviceName: deviceNameOverride?.trim() || this.getDefaultBrowserDeviceName(),
+        };
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            const userId = this.getDiscoveryScopeId();
+            const wasmClient = await this.waitForWasmClient(500);
+            if (!userId || !wasmClient || typeof wasmClient.update_presence !== 'function') {
+                return;
+            }
+            await wasmClient.update_presence(userId, deviceNameOverride?.trim() || this.getDefaultBrowserDeviceName(), ticketStr, mergedMetadata, BigInt(Math.max(0, Math.trunc(effectiveTtlMs))));
+            return;
+        }
+        await this.getBrowserFirestoreSignaling().updatePresence(localNodeId, ticketStr, isOnline, effectiveTtlMs, mergedMetadata, deviceNameOverride);
+        // Phase 1: bump RTDB ticketVersion so other clients invalidate their cache.
+        if (this._rtdbPresence && this.rtdbPresenceScope) {
+            const deviceId = this.resolveWebLogicalDeviceId();
+            if (deviceId) {
+                this.rtdbTicketVersion += 1;
+                void this._rtdbPresence.bumpTicketVersion(this.rtdbPresenceScope, deviceId, this.rtdbTicketVersion).catch((err) => console.warn('[WasmBridge] RTDB ticketVersion bump failed:', err));
+            }
+        }
+    }
+    async setOffline(localNodeId) {
+        this.stopBrowserPresenceLoop();
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        // Phase 1: mark offline in RTDB immediately (graceful disconnect).
+        if (this._rtdbPresence && this.rtdbPresenceScope) {
+            const deviceId = this.resolveWebLogicalDeviceId();
+            if (deviceId) {
+                void this._rtdbPresence.markOffline(this.rtdbPresenceScope, deviceId, this.rtdbTicketVersion).catch((err) => console.warn('[WasmBridge] RTDB markOffline failed:', err));
+            }
+        }
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            const userId = this.getDiscoveryScopeId();
+            const wasmClient = await this.waitForWasmClient(500);
+            if (!userId || !wasmClient || typeof wasmClient.set_offline !== 'function') {
+                return;
+            }
+            await wasmClient.set_offline(userId);
+            return;
+        }
+        await this.getBrowserFirestoreSignaling().setOffline(localNodeId);
+    }
+    async updateDevice(deviceId, updates) {
+        if (!deviceId?.trim()) {
+            throw new Error('updateDevice requires a deviceId');
+        }
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            const userId = this.getDiscoveryScopeId();
+            const wasmClient = await this.waitForWasmClient(500);
+            if (!userId || !wasmClient || typeof wasmClient.update_device !== 'function') {
+                return;
+            }
+            await wasmClient.update_device(userId, deviceId, updates.deviceName ?? null, updates.capabilities ?? null, updates.metadata ?? null);
+            return;
+        }
+        await this.getBrowserFirestoreSignaling().updateDevice(deviceId, updates);
+    }
+    async deleteDevice(deviceId) {
+        if (!deviceId?.trim()) {
+            throw new Error('deleteDevice requires a deviceId');
+        }
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            const userId = this.getDiscoveryScopeId();
+            const wasmClient = await this.waitForWasmClient(500);
+            if (!userId || !wasmClient || typeof wasmClient.delete_device !== 'function') {
+                return;
+            }
+            await wasmClient.delete_device(userId, deviceId);
+            return;
+        }
+        await this.getBrowserFirestoreSignaling().deleteDevice(deviceId);
+    }
+    async cleanupStaleDevices() {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            return;
+        }
+        await this.getBrowserFirestoreSignaling().cleanupStaleDevices();
+    }
+    async sendMessage(targetId, payload, state, replyPayload) {
+        if (this.isTicketOnlyMode()) {
+            throw new Error('[openrtc] sendMessage() is unavailable when signalingMode="ticket-only".');
+        }
+        return this.getBrowserFirestoreSignaling().sendMessage(targetId, payload, state, replyPayload);
+    }
+    async pollMessages(targetId) {
+        if (this.isTicketOnlyMode()) {
+            return [];
+        }
+        return this.getBrowserFirestoreSignaling().pollMessages(targetId);
+    }
+    async searchDevices(excludeNodeId) {
+        if (this.isTicketOnlyMode()) {
+            return [];
+        }
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            return this.searchDevicesViaWasm(excludeNodeId);
+        }
+        return this.getBrowserFirestoreSignaling().searchDevices(excludeNodeId);
+    }
+    async listDevicesWithStatus() {
+        if (this.isTicketOnlyMode()) {
+            return [];
+        }
+        const userId = this.getDiscoveryScopeId();
+        if (!userId)
+            return [];
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.devices_with_status === 'function') {
+            const devices = await wasmClient.devices_with_status(userId);
+            const rawDevices = Array.isArray(devices) ? devices : [];
+            const normalized = rawDevices
+                .map((device) => this.normalizeDeviceStatusSnapshot(device))
+                .filter((device) => this.matchesTag(device));
+            return normalized;
+        }
+        return [];
+    }
+    async searchDevicesViaWasm(excludeNodeId) {
+        const userId = this.getDiscoveryScopeId();
+        if (!userId) {
+            return [];
+        }
+        const wasmClient = await this.waitForWasmClient(500);
+        if (!wasmClient || typeof wasmClient.search_devices !== 'function') {
+            return [];
+        }
+        const devices = await wasmClient.search_devices(userId);
+        let normalized = (Array.isArray(devices) ? devices : [])
+            .map((device) => this.normalizeDevice(device))
+            .filter((device) => this.matchesTag(device));
+        if (excludeNodeId) {
+            normalized = normalized.filter((device) => device.ticket !== excludeNodeId &&
+                device.deviceId !== excludeNodeId &&
+                device.nodeId !== excludeNodeId);
+        }
+        return normalized;
+    }
+    onDevicesChangeViaWasmPolling(callback, excludeNodeId) {
+        let cancelled = false;
+        let lastSnapshotKey = '';
+        const emit = async () => {
+            if (cancelled) {
+                return;
+            }
+            try {
+                const devices = await this.searchDevicesViaWasm(excludeNodeId);
+                const snapshotKey = JSON.stringify(devices
+                    .map((device) => ({
+                    deviceId: device.deviceId,
+                    nodeId: device.nodeId ?? null,
+                    ticket: device.ticket ?? null,
+                    online: device.online,
+                    updatedAt: typeof device.updatedAt === 'number'
+                        ? device.updatedAt
+                        : device.updatedAt?.toMillis?.() ?? null,
+                }))
+                    .sort((left, right) => left.deviceId.localeCompare(right.deviceId)));
+                if (snapshotKey === lastSnapshotKey) {
+                    return;
+                }
+                lastSnapshotKey = snapshotKey;
+                callback(devices);
+            }
+            catch (error) {
+                if (!cancelled) {
+                    console.warn('[WasmBridge] legacy device polling failed:', error);
+                }
+            }
+        };
+        void emit();
+        const interval = setInterval(() => {
+            void emit();
+        }, 2000);
+        return () => {
+            cancelled = true;
+            clearInterval(interval);
+        };
+    }
+    async getPeerSession(id) {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.peer_session === 'function') {
+            const snapshot = await wasmClient.peer_session(id);
+            if (!snapshot || typeof snapshot !== 'object') {
+                return null;
+            }
+            return this.normalizePeerSessionSnapshot(snapshot);
+        }
+        this.warnMissingWasmOnce('getPeerSession');
+        return null;
+    }
+    async listPeerSessions() {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.peer_sessions === 'function') {
+            const snapshots = await wasmClient.peer_sessions();
+            return (Array.isArray(snapshots) ? snapshots : [])
+                .map((snapshot) => this.normalizePeerSessionSnapshot(snapshot))
+                .filter((snapshot) => !!snapshot.peerId);
+        }
+        this.warnMissingWasmOnce('listPeerSessions');
+        return [];
+    }
+    async waitForSettledPeer(id, timeoutMs) {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.wait_for_settled_peer === 'function') {
+            const snapshot = await wasmClient.wait_for_settled_peer(id, timeoutMs);
+            if (!snapshot || typeof snapshot !== 'object') {
+                return null;
+            }
+            return this.normalizePeerSessionSnapshot(snapshot);
+        }
+        this.warnMissingWasmOnce('waitForSettledPeer');
+        return null;
+    }
+    async openPeerBi(id, timeoutMs) {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.open_peer_bi === 'function') {
+            const biStream = await wasmClient.open_peer_bi(id, timeoutMs);
+            if (!biStream?.recv || !biStream?.send) {
+                throw new Error('WASM open_peer_bi returned an invalid bidirectional stream');
+            }
+            return {
+                readable: biStream.recv,
+                writable: biStream.send,
+            };
+        }
+        this.warnMissingWasmOnce('openPeerBi');
+        throw new Error('WASM runtime does not support open_peer_bi()');
+    }
+    async openPeerUni(id, timeoutMs) {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.open_peer_uni === 'function') {
+            const writable = await wasmClient.open_peer_uni(id, timeoutMs);
+            if (!writable) {
+                throw new Error('WASM open_peer_uni returned an invalid writable stream');
+            }
+            return { writable };
+        }
+        this.warnMissingWasmOnce('openPeerUni');
+        throw new Error('WASM runtime does not support open_peer_uni()');
+    }
+    async resolvePeerConnectionRecords(id) {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.resolve_peer_connection_records === 'function') {
+            const records = await wasmClient.resolve_peer_connection_records(id);
+            return (Array.isArray(records) ? records : []).map((record) => ({
+                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,
+                createdAtMs: typeof record.createdAtMs === 'number' ? record.createdAtMs : 0,
+                updatedAtMs: typeof record.updatedAtMs === 'number' ? record.updatedAtMs : 0,
+            }));
+        }
+        this.warnMissingWasmOnce('resolvePeerConnectionRecords');
+        return [];
+    }
+    async resolvePeerIdentity(id) {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient) {
+            const fromRecord = (record) => {
+                if (!record || typeof record !== 'object') {
+                    return {
+                        peerId: null,
+                        deviceId: null,
+                        deviceIdHint: null,
+                        nodeId: null,
+                    };
+                }
+                const normalized = record;
+                return {
+                    peerId: typeof normalized.peerId === 'string' ? normalized.peerId : null,
+                    deviceId: typeof normalized.deviceId === 'string' ? normalized.deviceId : null,
+                    deviceIdHint: typeof normalized.deviceIdHint === 'string' ? normalized.deviceIdHint : null,
+                    nodeId: typeof normalized.nodeId === 'string' ? normalized.nodeId : null,
+                };
+            };
+            if (typeof wasmClient.peer_session === 'function') {
+                try {
+                    const session = await wasmClient.peer_session(id);
+                    const identity = fromRecord(session);
+                    if (identity.peerId || identity.deviceId || identity.deviceIdHint || identity.nodeId) {
+                        return identity;
+                    }
+                }
+                catch {
+                    // Fall through to peer_snapshot for compatibility.
+                }
+            }
+            if (typeof wasmClient.peer_snapshot === 'function') {
+                try {
+                    return fromRecord(await wasmClient.peer_snapshot(id));
+                }
+                catch {
+                    // Fall through to the empty identity below.
+                }
+            }
+        }
+        this.warnMissingWasmOnce('resolvePeerIdentity');
+        return {
+            peerId: null,
+            deviceId: null,
+            deviceIdHint: null,
+            nodeId: null,
+        };
+    }
+    onDevicesChange(callback, excludeNodeId) {
+        if (this.isTicketOnlyMode()) {
+            callback([]);
+            return () => undefined;
+        }
+        if (this.usesLegacyBrowserSignalingFallback()) {
+            return this.onDevicesChangeViaWasmPolling(callback, excludeNodeId);
+        }
+        return this.getBrowserFirestoreSignaling().onDevicesChange(callback, excludeNodeId);
+    }
+    async subscribeDevices(userId) {
+        void userId;
+        if (this.isTicketOnlyMode()) {
+            return new ReadableStream({
+                start(controller) {
+                    controller.close();
+                },
+            });
+        }
+        return this.getBrowserFirestoreSignaling().subscribeDevices();
+    }
+    startAutoConnect(userId, localDeviceId) {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        void (async () => {
+            const effectiveLocalDeviceId = this.resolveWebLogicalDeviceId();
+            const localNodeId = typeof this.browserPresenceLoopState?.localNodeId === 'string'
+                ? this.browserPresenceLoopState.localNodeId.trim() || null
+                : null;
+            const autoConnectKey = `${userId}::${effectiveLocalDeviceId}`;
+            if (this.startedAutoConnectKey === autoConnectKey ||
+                this.autoConnectStartsInFlight.has(autoConnectKey)) {
+                return;
+            }
+            this.autoConnectStartsInFlight.add(autoConnectKey);
+            try {
+                void localDeviceId;
+                this.stopBrowserAutoConnect();
+                this.startedAutoConnectKey = autoConnectKey;
+                this.browserAutoConnectUnsubscribe = this.getBrowserFirestoreSignaling().onDevicesChange((devices) => {
+                    this.scheduleBrowserAutoConnectScan(devices, localNodeId, effectiveLocalDeviceId);
+                });
+            }
+            finally {
+                this.autoConnectStartsInFlight.delete(autoConnectKey);
+            }
+        })();
+    }
+    notifyDisconnectRequested(remoteNodeId) {
+        if (!this.startedAutoConnectKey || this.browserAutoConnectPendingDevices.size === 0) {
+            return;
+        }
+        const normalizedRemoteNodeId = remoteNodeId.trim();
+        if (!normalizedRemoteNodeId) {
+            return;
+        }
+        const targetDevice = [...this.browserAutoConnectPendingDevices.values()].find((device) => {
+            const nodeId = typeof device.nodeId === 'string' ? device.nodeId.trim() : '';
+            return nodeId === normalizedRemoteNodeId;
+        });
+        if (!targetDevice?.deviceId) {
+            return;
+        }
+        this.queueBrowserAutoConnectRecoveryForDevice(targetDevice, {
+            resetWaitStartedAt: true,
+        });
+    }
+    async setAutoConnectExcluded(deviceId, excluded) {
+        const wasmClient = await this.waitForWasmClient();
+        if (wasmClient && typeof wasmClient.set_auto_connect_excluded === 'function') {
+            wasmClient.set_auto_connect_excluded(deviceId, excluded);
+        }
+    }
+    async connectToDevice(params) {
+        const wasmClient = await this.waitForWasmClient();
+        if (!wasmClient || typeof wasmClient.connect_device !== 'function') {
+            this.warnMissingWasmOnce('connectToDevice');
+            throw new Error('WASM runtime does not support connect_device()');
+        }
+        return wasmClient.connect_device(params.deviceId ?? null, params.endpointTicket);
+    }
+    forceReconnectSnapshot() {
+        void (async () => {
+            const wasmClient = await this.waitForWasmClient();
+            if (wasmClient && typeof wasmClient.force_reconnect_snapshot === 'function') {
+                wasmClient.force_reconnect_snapshot();
+            }
+            else {
+                this.warnMissingWasmOnce('forceReconnectSnapshot');
+            }
+        })();
+    }
+    startPresenceLoop(userId, localNodeId, deviceName, ticket, metadata) {
+        if (this.isTicketOnlyMode()) {
+            return;
+        }
+        this.stopBrowserPresenceLoop();
+        this.browserPresenceLoopState = { localNodeId, ticket, metadata, deviceName };
+        const localDeviceId = this.resolveWebLogicalDeviceId();
+        // Phase 1: register RTDB presence instead of polling Firestore every 60s.
+        // We still call updatePresence ONCE to write the Firestore ticket doc,
+        // but we do NOT start the setInterval heartbeat when RTDB is available.
+        const scope = this.buildRtdbScope(userId);
+        if (!this.rtdbPresenceDisabledForSession && scope && localDeviceId) {
+            const mergedMetadata = this.withWebPresenceMetadata(metadata, localDeviceId);
+            // Write Firestore ticket once.
+            void this.updatePresence(localNodeId, ticket, true, 
+            // Long TTL: the doc is kept alive by RTDB onDisconnect, not by polling.
+            // 7 days ensures the ticket stays valid even across RTDB reconnects.
+            7 * 24 * 60 * 60 * 1000, mergedMetadata, deviceName).catch((err) => console.warn('[WasmBridge] initial presence write failed:', err));
+            // Register RTDB onDisconnect + online state (replaces the interval).
+            void this.registerRtdbPresence(scope, localDeviceId, this.rtdbTicketVersion)
+                .catch((err) => {
+                console.warn('[WasmBridge] RTDB presence register failed; falling back to Firestore heartbeat:', err);
+                this.startLegacyBrowserPresenceLoop();
+            });
+            // No setInterval — RTDB WebSocket keepalive handles liveness.
+            return;
+        }
+        // Fallback: legacy 60-second Firestore heartbeat (no RTDB).
+        this.startLegacyBrowserPresenceLoop();
+    }
+    /**
+     * Build the RTDB discovery scope from the current auth context and options.
+     * Returns null if scope cannot be determined (e.g. not yet authenticated).
+     */
+    buildRtdbScope(userIdHint) {
+        if (this.isTicketOnlyMode()) {
+            return null;
+        }
+        const mode = this.options.discoveryMode ?? 'personal';
+        const appTag = this.appTag;
+        if (mode === 'personal') {
+            // Personal mode uses the space namespace derived from apiKey+spaceKey.
+            // This is async (SHA-256 hash), so we skip RTDB for personal mode
+            // in startPresenceLoop and rely on the caller to set it explicitly.
+            // TODO: wire personal mode RTDB in a follow-up once namespace is cached.
+            return null;
+        }
+        const userId = userIdHint
+            || this.getDiscoveryScopeId()
+            || this.getCurrentUserId();
+        if (!userId)
+            return null;
+        // user-scoped (default for managed mode)
+        return { kind: 'user-scoped', appTag, userId };
+    }
+    async createSession(session) {
+        if (this.isTicketOnlyMode()) {
+            throw new Error('[openrtc] createSession() is unavailable when signalingMode="ticket-only".');
+        }
+        const userId = this.getCurrentUserId();
+        if (!userId && !session.initiator && !session.target && !this.isPersonalSpaceMode()) {
+            throw new Error('createSession requires user scope');
+        }
+        const scopedSession = {
+            ...session,
+            appTag: session.appTag ?? this.appTag,
+            initiator: session.initiator ?? userId ?? undefined,
+            target: session.target ?? userId ?? undefined,
+        };
+        await this.getBrowserFirestoreSignaling().createSession(scopedSession);
+    }
+    async updateSession(sessionId, updateData) {
+        if (this.isTicketOnlyMode()) {
+            throw new Error('[openrtc] updateSession() is unavailable when signalingMode="ticket-only".');
+        }
+        await this.getBrowserFirestoreSignaling().updateSession(sessionId, updateData);
+    }
+    async subscribeSessions(localDeviceId) {
+        if (this.isTicketOnlyMode()) {
+            return new ReadableStream({
+                start(controller) {
+                    controller.close();
+                },
+            });
+        }
+        return this.getBrowserFirestoreSignaling().subscribeSessions(localDeviceId);
+    }
+    async getLocalDeviceId() {
+        return this.resolveWebLogicalDeviceId();
+    }
+    async isConnected(node_id) {
+        const wasmClient = await this.waitForWasmClient();
+        if (wasmClient && typeof wasmClient.is_connected === 'function') {
+            return await wasmClient.is_connected(node_id);
+        }
+        return false;
+    }
+    async getConnectionStates() {
+        const wasmClient = await this.waitForWasmClient(500);
+        if (wasmClient && typeof wasmClient.connection_states === 'function') {
+            const snapshots = await wasmClient.connection_states();
+            const states = (Array.isArray(snapshots) ? snapshots : [])
+                .map((snapshot) => this.normalizeConnectionStateSnapshot(snapshot))
+                .filter((state) => !!state);
+            if (states.length > 0) {
+                openRtcDebug('[WasmBridge] replaying current wasm connection states', states.map((state) => ({
+                    connectionId: state.connectionId,
+                    deviceId: state.deviceId ?? null,
+                    deviceIdHint: state.deviceIdHint ?? null,
+                    remoteNodeId: state.remoteNodeId ?? null,
+                    state: state.state,
+                    transportState: state.transportState ?? null,
+                    protocolState: state.protocolState ?? null,
+                    routable: state.routable ?? null,
+                })));
+            }
+            return states;
+        }
+        const sessions = await this.listPeerSessions().catch(() => []);
+        const states = sessions
+            .map((snapshot) => this.toBackendConnectionStateFromPeerSession(snapshot))
+            .filter((state) => !!state);
+        if (states.length > 0) {
+            openRtcDebug('[WasmBridge] replaying current wasm connection states', states.map((state) => ({
+                connectionId: state.connectionId,
+                deviceId: state.deviceId ?? null,
+                deviceIdHint: state.deviceIdHint ?? null,
+                remoteNodeId: state.remoteNodeId ?? null,
+                state: state.state,
+                transportState: state.transportState ?? null,
+                protocolState: state.protocolState ?? null,
+                routable: state.routable ?? null,
+            })));
+        }
+        return states;
+    }
+    onConnectionStateChange(callback) {
+        if (typeof window === 'undefined') {
+            return () => { };
+        }
+        // Per-subscriber dedup map so multiple subscribers each receive all events
+        const subscriberDedup = new Map();
+        const handleEvent = (event) => {
+            const customEvent = event;
+            const detail = customEvent?.detail && typeof customEvent.detail === 'object'
+                ? customEvent.detail
+                : null;
+            if (!detail) {
+                return;
+            }
+            const rawState = this.normalizeWindowConnectionStateDetail(detail);
+            if (!rawState) {
+                return;
+            }
+            void this.enrichBackendConnectionState(rawState)
+                .then((enriched) => {
+                this.deliverConnectionState(enriched, callback, 'event', subscriberDedup);
+            })
+                .catch((error) => {
+                console.warn('[WasmBridge] Failed to enrich connection-state-changed event:', error);
+                this.deliverConnectionState(rawState, callback, 'event', subscriberDedup);
+            });
+        };
+        window.addEventListener('connection-state-changed', handleEvent);
+        void this.getConnectionStates()
+            .then((states) => {
+            states.forEach((state) => this.deliverConnectionState(state, callback, 'replay', subscriberDedup));
+        })
+            .catch((error) => {
+            console.warn('[WasmBridge] Failed to replay wasm connection states after subscription:', error);
+        });
+        return () => {
+            window.removeEventListener('connection-state-changed', handleEvent);
+        };
+    }
+    async sendExplicitFilePath(connectionId, filePath, transferId = '') {
+        throw new Error('sendExplicitFilePath is native-only. Use sendExplicitFileData in web/wasm runtime.');
+    }
+    async sendExplicitFileData(params) {
+        const connection = params.connection;
+        const file = params.file;
+        const remoteNodeId = params.remoteNodeId?.trim()
+            || connection?.remoteNodeId?.trim()
+            || connection?.deviceId?.trim();
+        openRtcDebugInfo('[WasmBridge] sendExplicitFileData start', {
+            connectionId: params.connectionId ?? null,
+            connectionRemoteNodeId: connection?.remoteNodeId ?? null,
+            remoteNodeId: remoteNodeId ?? null,
+            fileName: file.name,
+            fileSize: file.size,
+            transferId: params.transferId ?? null,
+        });
+        if (!remoteNodeId) {
+            throw new Error('Web explicit transfer requires an active connection with a resolved remote node ID');
+        }
+        const wasmClient = await this.waitForWasmClient();
+        if (!wasmClient || typeof wasmClient.open_bi !== 'function') {
+            throw new Error('WASM explicit transfer requires open_bi support');
+        }
+        const biStream = await wasmClient.open_bi(remoteNodeId);
+        openRtcDebugInfo('[WasmBridge] sendExplicitFileData open_bi resolved', {
+            remoteNodeId,
+            transferId: params.transferId ?? null,
+        });
+        const writer = biStream.send.getWriter();
+        const encoder = new TextEncoder();
+        const transferId = params.transferId && params.transferId.trim().length > 0
+            ? params.transferId
+            : `transfer-${Date.now()}`;
+        try {
+            const header = {
+                transfer_id: transferId,
+                filename: file.name,
+                size: file.size,
+                mime_type: file.type || 'application/octet-stream',
+            };
+            const headerBytes = encoder.encode(JSON.stringify(header));
+            const headerLen = new Uint8Array(4);
+            new DataView(headerLen.buffer).setUint32(0, headerBytes.byteLength, false);
+            await writer.write(new Uint8Array([WasmBridge.EXPLICIT_FILE_PROTOCOL_TYPE]));
+            await writer.write(headerLen);
+            await writer.write(headerBytes);
+            const payload = new Uint8Array(await file.arrayBuffer());
+            for (let offset = 0; offset < payload.byteLength; offset += WasmBridge.EXPLICIT_FILE_CHUNK_SIZE_BYTES) {
+                const chunk = payload.slice(offset, Math.min(offset + WasmBridge.EXPLICIT_FILE_CHUNK_SIZE_BYTES, payload.byteLength));
+                await writer.write(chunk);
+            }
+        }
+        finally {
+            await writer.close().catch(() => { });
+            writer.releaseLock();
+            openRtcDebugInfo('[WasmBridge] sendExplicitFileData completed', {
+                remoteNodeId,
+                transferId,
+                fileName: file.name,
+                fileSize: file.size,
+            });
+        }
+    }
+    async getTransferHistory(limit = 50) {
+        return [];
+    }
+    async deleteTransferJob(jobId) {
+        // Web runtime keeps transfer history in app-managed storage.
+    }
+}
+WasmBridge.EXPLICIT_FILE_PROTOCOL_TYPE = 0x02;
+WasmBridge.EXPLICIT_FILE_CHUNK_SIZE_BYTES = 64 * 1024;
+WasmBridge.BROWSER_AUTO_CONNECT_SCAN_DEBOUNCE_MS = 150;
+WasmBridge.BROWSER_AUTO_CONNECT_RETRY_COOLDOWN_MS = 2000;
+WasmBridge.BROWSER_AUTO_CONNECT_SETTLE_GUARD_MS = 10000;
+WasmBridge.WEB_DEVICE_ID_STORAGE_PREFIX = 'pluto_rtc_web_device_identity';
+WasmBridge.EPHEMERAL_DEVICE_ID_TTL_MS = 60000;