openrtc 0.1.0

package/dist/core/Client.js

@@ -0,0 +1,3689 @@
+import { Connection } from './Connection';
+import { Signaling } from './Signaling';
+import { RoomManager } from './Room';
+import { MoQSession } from '../moq/MoQSession';
+import { TransportFactory } from './transports/TransportFactory';
+import { PeerProjectionStore } from './PeerProjectionStore';
+import { getAuthHost } from '../auth/host';
+import { openRtcDebug, openRtcDebugInfo, openRtcDebugLog } from '../utils/debug';
+import { createTransportTrustChallenge, getLocalTrustedIdentity, parseTrustedDeviceMetadata, signTransportTrustChallenge, verifyTransportTrustChallenge, } from './trust';
+// Import the generated OpenRTC WASM package from ../../wasm/openrtc.js
+// @ts-ignore
+import initWasm, { WasmClient, start } from '../../wasm/openrtc.js';
+function splitCompoundTicket(rawTicket) {
+    const dotIndex = rawTicket.lastIndexOf('.');
+    return {
+        irohTicket: dotIndex >= 0 ? rawTicket.slice(0, dotIndex) : rawTicket,
+        tokenSuffix: dotIndex >= 0 ? rawTicket.slice(dotIndex + 1) : null,
+    };
+}
+function decodeCompoundTicketPayload(tokenSuffix) {
+    try {
+        const padded = tokenSuffix.replace(/-/g, '+').replace(/_/g, '/');
+        const paddingLen = (4 - (padded.length % 4)) % 4;
+        return JSON.parse(atob(padded + '='.repeat(paddingLen)));
+    }
+    catch {
+        return null;
+    }
+}
+// Ensure WebRTC and other configs exist
+import { DEFAULT_FREE_LIMITS, DEFAULT_WEBRTC_CONFIG, DEFAULT_MOQ_CONFIG, DEFAULT_ICE_SERVERS, } from './types';
+import { deriveSpaceNamespace, resolveAppTag, resolveAuthMode, resolveProjectId, resolveStorageNamespace } from './config';
+function withTimeout(promise, timeoutMs) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+        }),
+    ]);
+}
+async function pollUntilReady(check, attempts, intervalMs) {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const ready = await check().catch(() => false);
+        if (ready) {
+            return true;
+        }
+        if (attempt < attempts - 1) {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    return false;
+}
+class SharedIncomingStreamHub {
+    constructor(wasmClient) {
+        this.wasmClient = wasmClient;
+        this.clients = new Set();
+        this.listenLoopTask = null;
+    }
+    addClient(client) {
+        if (this.clients.has(client)) {
+            return;
+        }
+        this.clients.add(client);
+        this.ensureListening();
+    }
+    removeClient(client) {
+        this.clients.delete(client);
+    }
+    ensureListening() {
+        if (this.listenLoopTask) {
+            return;
+        }
+        this.listenLoopTask = this.listenLoop().finally(() => {
+            this.listenLoopTask = null;
+            if (this.clients.size > 0) {
+                this.ensureListening();
+            }
+        });
+    }
+    nextRetryDelayMs(attempt) {
+        const backoff = SharedIncomingStreamHub.RETRY_MIN_DELAY_MS * Math.pow(2, Math.max(0, attempt - 1));
+        return Math.min(SharedIncomingStreamHub.RETRY_MAX_DELAY_MS, backoff);
+    }
+    getPrimaryClient() {
+        const iterator = this.clients.values().next();
+        return iterator.done ? null : iterator.value;
+    }
+    getChannelTargetClients(channelId) {
+        return Array.from(this.clients)
+            .reverse()
+            .filter((client) => client.hasIncomingChannelListener(channelId));
+    }
+    async dispatchIncoming(rawIncoming) {
+        const parserClient = this.getPrimaryClient();
+        if (!parserClient) {
+            return;
+        }
+        const inspectChannelEnvelope = Array.from(this.clients).some((client) => Boolean(client.hasAnyIncomingChannelListeners()));
+        const listenerEvent = await parserClient.normalizeIncomingStreamEvent(rawIncoming, {
+            inspectChannelEnvelope,
+        });
+        const channelId = listenerEvent.channel?.channelId?.trim();
+        if (channelId) {
+            for (const client of this.getChannelTargetClients(channelId)) {
+                const handled = Boolean(client.dispatchIncomingChannelListeners(listenerEvent));
+                if (handled) {
+                    return;
+                }
+            }
+        }
+        const primaryClient = this.getPrimaryClient();
+        if (!primaryClient) {
+            return;
+        }
+        const handledByGenericListeners = Boolean(primaryClient.dispatchIncomingGenericListeners(listenerEvent));
+        if (handledByGenericListeners) {
+            return;
+        }
+        await primaryClient.handleUnhandledIncomingStreamEvent(listenerEvent);
+    }
+    async listenLoop() {
+        let attempt = 0;
+        while (true) {
+            if (this.clients.size === 0) {
+                return;
+            }
+            let reader = null;
+            try {
+                const streams = await this.wasmClient.incoming_streams();
+                const activeReader = streams.getReader();
+                reader = activeReader;
+                attempt = 0;
+                while (this.clients.size > 0) {
+                    const { done, value } = await activeReader.read();
+                    if (done) {
+                        throw new Error('incoming stream reader closed unexpectedly');
+                    }
+                    if (!value) {
+                        continue;
+                    }
+                    console.debug('[Client][INCOMING] Received stream from WASM node', {
+                        type: value?.type || 'unknown',
+                        endpointId: value?.endpointId || value?.endpoint_id || 'unknown',
+                        sharedHubClients: this.clients.size,
+                    });
+                    try {
+                        await this.dispatchIncoming(value);
+                    }
+                    catch (error) {
+                        const incoming = value;
+                        const streamType = typeof incoming.type === 'string' ? incoming.type : 'bi';
+                        const remoteNodeId = typeof incoming.endpointId === 'string'
+                            ? incoming.endpointId
+                            : typeof incoming.endpoint_id === 'string'
+                                ? incoming.endpoint_id
+                                : 'unknown';
+                        console.error('[Client][INCOMING] Failed to handle incoming stream via shared hub', {
+                            remoteNodeId,
+                            type: streamType,
+                            error,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                if (this.clients.size === 0) {
+                    return;
+                }
+                attempt += 1;
+                const delayMs = this.nextRetryDelayMs(attempt);
+                console.warn('[Client][INCOMING] Shared listen loop restarting after stream failure', {
+                    attempt,
+                    delayMs,
+                    error,
+                });
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+            finally {
+                if (reader) {
+                    try {
+                        reader.releaseLock();
+                    }
+                    catch {
+                        // no-op
+                    }
+                }
+            }
+        }
+    }
+}
+SharedIncomingStreamHub.RETRY_MIN_DELAY_MS = 250;
+SharedIncomingStreamHub.RETRY_MAX_DELAY_MS = 2000;
+export class Client {
+    constructor(options) {
+        this.wasmLoaded = false;
+        this.wasmClient = null;
+        this.initPromise = null;
+        // node is kept as a dummy for legacy compat if needed, but pointed to null
+        this.node = null;
+        this.connections = new Map();
+        this.connectionListeners = [];
+        this.disconnectionListeners = [];
+        this.messageListeners = [];
+        this.roomRequestListeners = [];
+        this.streamListeners = [];
+        this.channelStreamListeners = new Map();
+        this.registeredChannels = new Map();
+        this.announcedConnections = new Set();
+        this.peerLifecycle = new PeerProjectionStore();
+        this.knownDevicesById = new Map();
+        this.knownDeviceIdsByNodeId = new Map();
+        this.connectionTrustStates = new Map();
+        this.connectionChannelIds = new Map();
+        this.managedPresenceGrant = null;
+        /** Token extracted from a compound ticket during connect(), keyed by remote node ID. */
+        this.pendingTokenByNodeId = new Map();
+        this.localNodeId = '';
+        this.listening = false;
+        this.listenLoopTask = null;
+        this.appLimits = { ...DEFAULT_FREE_LIMITS };
+        // Prevent GC
+        this.pendingConnection = null;
+        this.authSyncUnsubscribe = null;
+        this.backendConnectionStateUnsubscribe = null;
+        this.authRefreshInterval = null;
+        this.deviceId = null;
+        this.lastWasmAuthSyncUserId = null;
+        this.lastWasmAuthSyncToken = null;
+        // Presence loop
+        this.presenceInterval = null;
+        this.hostedAppSettingsLoaded = false;
+        // --- Shared MoQ Session ---
+        this._moqSession = null;
+        this._moqState = 'none';
+        this.moqReadyListeners = [];
+        this.moqFailedListeners = [];
+        this.moqObjectListeners = [];
+        this.roomCreationMode = 'client-open';
+        const appTag = resolveAppTag(options);
+        const authMode = resolveAuthMode(options);
+        this.options = {
+            strictMode: true,
+            disableIrohFallback: false,
+            transportPriority: ['webrtc', 'moq', 'iroh'],
+            ...options,
+            authMode,
+        };
+        this.effectiveRoomBackendTag = appTag;
+        this.roomCreationMode = (this.options.discoveryMode ?? 'personal') === 'personal'
+            ? 'client-open'
+            : 'client-auth';
+        // Normalizing Transport Configs
+        if (this.options.transports) {
+            // ... (transport normalization logic remains same)
+            // WebRTC Logic
+            if (this.options.transports.webrtc === true) {
+                this.options.transports.webrtc = { ...DEFAULT_WEBRTC_CONFIG };
+            }
+            else if (this.options.transports.webrtc === false) {
+                this.options.transports.webrtc = undefined;
+            }
+            // MoQ Logic
+            if (this.options.transports.moq === true) {
+                this.options.transports.moq = { ...DEFAULT_MOQ_CONFIG };
+            }
+            else if (this.options.transports.moq === false) {
+                this.options.transports.moq = undefined;
+            }
+            // Iroh Logic
+            if (this.options.transports.iroh === true) {
+                this.options.transports.iroh = {};
+            }
+            else if (this.options.transports.iroh === false) {
+                this.options.transports.iroh = undefined;
+            }
+        }
+        const irohTransport = this.options.transports?.iroh;
+        const configuredPersistenceMode = this.options.nodeIdPersistence ??
+            (typeof irohTransport === 'object' ? irohTransport.persistenceMode : undefined) ??
+            'persistent';
+        // Initialize TS wrappers that will use the loaded WASM underneath
+        const sigOptions = {
+            apiKey: this.options.apiKey,
+            allowAnonymousHostedDefaults: this.options.allowAnonymousHostedDefaults,
+            authMode: this.options.authMode,
+            projectId: this.options.projectId,
+            storagePrefix: this.options.storagePrefix,
+            nodeIdPersistence: configuredPersistenceMode,
+        };
+        let backend = null;
+        // Placeholder backend until the host app injects a concrete runtime bridge.
+        const proxyBackend = new Proxy({}, {
+            get(target, prop) {
+                if (backend)
+                    return backend[prop];
+                return undefined;
+            }
+        });
+        this.signaling = new Signaling(sigOptions, proxyBackend);
+        this.rooms = new RoomManager(this, this.signaling);
+        this.registerChannel({
+            id: Client.DEFAULT_PEER_CHANNEL_ID,
+            kind: 'system',
+            ownership: 'shared',
+            peerModel: 'device-first',
+            routing: 'session-default',
+            readiness: 'settled-peer',
+            promotionPolicy: 'eligible',
+            signalingPolicy: 'hosted',
+            description: 'Default trusted device/runtime traffic',
+        });
+        this.registerChannel({
+            id: Client.SHARE_FILE_CHANNEL_ID,
+            kind: 'share',
+            ownership: 'shared',
+            peerModel: 'anonymous-ticket',
+            routing: 'stream-envelope',
+            readiness: 'transport-only',
+            promotionPolicy: 'never',
+            signalingPolicy: 'ticket-only',
+            description: 'Explicit file transfer channel for share/ticket traffic',
+        });
+        this.registerChannel({
+            id: Client.SHARE_CONTROL_CHANNEL_ID,
+            kind: 'share',
+            ownership: 'shared',
+            peerModel: 'anonymous-ticket',
+            routing: 'stream-envelope',
+            readiness: 'transport-only',
+            promotionPolicy: 'never',
+            signalingPolicy: 'ticket-only',
+            description: 'Explicit control channel for share/ticket traffic',
+        });
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    get apiKey() {
+        return this.options.apiKey;
+    }
+    get discoveryMode() {
+        return this.options.discoveryMode ?? 'personal';
+    }
+    usesTicketOnlySignalingMode() {
+        return this.options.signalingMode === 'ticket-only';
+    }
+    usesDirectRoomBackend() {
+        return this.effectiveRoomBackendTag.startsWith('space::')
+            || ((this.options.discoveryMode === undefined || this.options.discoveryMode === 'personal')
+                && typeof this.options.spaceKey === 'string'
+                && this.options.spaceKey.trim().length > 0);
+    }
+    getRoomBackendTag() {
+        return this.effectiveRoomBackendTag;
+    }
+    async refreshHostedAppSettings(force = false) {
+        if (this.usesTicketOnlySignalingMode()) {
+            return;
+        }
+        if (this.hostedAppSettingsLoaded && !force) {
+            return;
+        }
+        try {
+            const { getFunctions, httpsCallable } = await import('firebase/functions');
+            const functions = getFunctions(getAuthHost().getApp());
+            const validate = httpsCallable(functions, 'validateApiKey');
+            const result = await validate({ apiKey: this.apiKey });
+            const data = result.data;
+            if (data.warning) {
+                console.warn('[pluto-rtc]', data.warning);
+            }
+            this.appLimits = data.limits;
+            if (data.discoveryMode) {
+                this.options.discoveryMode = data.discoveryMode;
+            }
+            this.roomCreationMode = data.roomCreationMode
+                ?? ((this.options.discoveryMode ?? 'personal') === 'personal' ? 'client-open' : 'client-auth');
+            this.hostedAppSettingsLoaded = true;
+        }
+        catch (e) {
+            console.warn('[pluto-rtc] Could not fetch hosted app settings, using local defaults.', e);
+        }
+    }
+    // --- Dependency Injection Point ---
+    // The wrapper (PlutoRTC) or the main app will call this upon instantiation
+    // to provide the correctly environment-gated backend implementation.
+    setSignalingBackend(backend) {
+        // Here we can swap the proxy out or reset the signaling instance
+        this.backendConnectionStateUnsubscribe?.();
+        this.backendConnectionStateUnsubscribe = null;
+        this.signaling = new Signaling(this.options, backend);
+        this.rooms = new RoomManager(this, this.signaling);
+        // Check for SSO token after the real backend is injected
+        backend.checkForSSOToken();
+        openRtcDebug('[Client] subscribing to backend connection state changes', {
+            backendType: backend?.constructor?.name ?? 'unknown',
+            hasGetConnectionStates: typeof backend.getConnectionStates === 'function',
+            hasOnConnectionStateChange: typeof backend.onConnectionStateChange === 'function',
+        });
+        const maybeUnsubscribe = this.signaling.onConnectionStateChange((state) => {
+            this.applyBackendConnectionState(state);
+        });
+        if (typeof maybeUnsubscribe === 'function') {
+            this.backendConnectionStateUnsubscribe = maybeUnsubscribe;
+            openRtcDebug('[Client] backend connection state subscription established synchronously');
+        }
+        else if (maybeUnsubscribe && typeof maybeUnsubscribe.then === 'function') {
+            void maybeUnsubscribe
+                .then((unsubscribe) => {
+                this.backendConnectionStateUnsubscribe = unsubscribe;
+                openRtcDebug('[Client] backend connection state subscription established asynchronously');
+            })
+                .catch((error) => {
+                console.warn('[Client] Failed to subscribe to backend connection state changes:', error);
+            });
+        }
+    }
+    // --- Helpers ---
+    get currentUser() {
+        return this.signaling.currentUser;
+    }
+    onAuthChange(callback) {
+        return this.signaling.onAuthChange(callback);
+    }
+    async signInAnonymously() {
+        return this.signaling.signInAnonymously();
+    }
+    async signInWithPluto() {
+        return this.signaling.signInWithPluto();
+    }
+    async signOut() {
+        this.listening = false;
+        await this.signaling.stopAuthScopedActivity();
+        return this.signaling.signOut();
+    }
+    getSignalingTelemetry() {
+        return {
+            transport: 'runtime-bridge',
+            wasmLoaded: this.wasmLoaded,
+        };
+    }
+    getProtocolCapabilities() {
+        return TransportFactory.getProtocolCapabilities();
+    }
+    async getRuntimeStatus() {
+        let runtime = 'unknown';
+        if (typeof window !== 'undefined') {
+            runtime = window.__TAURI__ ? 'tauri' : 'browser';
+        }
+        return {
+            runtime,
+            wasmLoaded: this.wasmLoaded,
+            localNodeId: this.localNodeId || undefined,
+            userId: this.signaling.currentUser?.id,
+        };
+    }
+    async ensureWasmRuntimeForP2P() {
+        if (this.wasmClient && this.localNodeId) {
+            return;
+        }
+        await this.init();
+        if (!this.wasmClient || !this.localNodeId) {
+            throw new Error('Node not initialized');
+        }
+    }
+    async ensureSignalingReadyForDiscovery(reason) {
+        if (this.usesTicketOnlySignalingMode()) {
+            return;
+        }
+        if (!this.wasmLoaded) {
+            await this.init();
+        }
+        try {
+            await this.ensureAuthenticated('discovery');
+        }
+        catch (error) {
+            console.warn(`[Client][AUTH] ensureAuthenticated failed for ${reason}:`, error);
+        }
+        try {
+            if (this.wasmClient) {
+                await this.syncAuthTokenToWasm('auth-change');
+            }
+        }
+        catch (error) {
+            console.warn(`[Client][WASM-AUTH] Token sync failed for ${reason}:`, error);
+        }
+    }
+    requiresManagedTransportTrust() {
+        return !this.usesTicketOnlySignalingMode()
+            && this.discoveryMode !== 'personal'
+            && !!this.currentUser?.id;
+    }
+    getRegisteredChannel(channelId) {
+        const normalized = typeof channelId === 'string' ? channelId.trim() : '';
+        if (!normalized) {
+            return null;
+        }
+        return this.registeredChannels.get(normalized) ?? null;
+    }
+    isChannelPromotionEligible(channelId) {
+        const descriptor = this.getRegisteredChannel(channelId);
+        if (!descriptor) {
+            return true;
+        }
+        return descriptor.promotionPolicy !== 'never';
+    }
+    getConnectionChannelId(connectionId) {
+        const normalized = typeof connectionId === 'string' ? connectionId.trim() : '';
+        if (!normalized) {
+            return null;
+        }
+        return this.connectionChannelIds.get(normalized) ?? null;
+    }
+    resolvePromotionEligibility(identifiers) {
+        const directChannelId = this.getConnectionChannelId(identifiers.connectionId);
+        if (directChannelId) {
+            return this.isChannelPromotionEligible(directChannelId);
+        }
+        const normalizedNodeId = typeof identifiers.nodeId === 'string' ? identifiers.nodeId.trim() : '';
+        for (const connection of this.connections.values()) {
+            if (identifiers.connectionId && connection.id === identifiers.connectionId) {
+                return this.isChannelPromotionEligible(this.getConnectionChannelId(connection.id));
+            }
+            if (normalizedNodeId && connection.remoteNodeId === normalizedNodeId) {
+                return this.isChannelPromotionEligible(this.getConnectionChannelId(connection.id));
+            }
+        }
+        return true;
+    }
+    assignConnectionChannel(connection, channelId) {
+        const normalizedChannelId = typeof channelId === 'string' ? channelId.trim() : '';
+        if (!normalizedChannelId) {
+            return;
+        }
+        this.connectionChannelIds.set(connection.id, normalizedChannelId);
+        const trustState = this.connectionTrustStates.get(connection.id);
+        if (trustState && !this.isChannelPromotionEligible(normalizedChannelId)) {
+            trustState.required = false;
+            trustState.verified = true;
+            trustState.failed = false;
+            trustState.failureReason = undefined;
+            trustState.issuedChallenge = null;
+            if (!trustState.verifiedDeviceId) {
+                trustState.verifiedDeviceId =
+                    trustState.expectedDeviceId
+                        || this.knownDeviceIdsByNodeId.get(connection.remoteNodeId)
+                        || null;
+            }
+        }
+        if (!this.hasRustPeerLifecycleProjection()) {
+            const existing = this.connections.get(connection.id);
+            if (existing) {
+                this.applyConnectionTrustProjection(existing);
+            }
+        }
+        else {
+            void this.refreshPeerSnapshot().catch(() => { });
+        }
+    }
+    rememberKnownDevice(device) {
+        if (!device?.deviceId) {
+            return;
+        }
+        this.knownDevicesById.set(device.deviceId, device);
+        if (typeof device.nodeId === 'string' && device.nodeId.trim()) {
+            this.knownDeviceIdsByNodeId.set(device.nodeId.trim(), device.deviceId);
+        }
+    }
+    getKnownDevice(deviceId, remoteNodeId) {
+        const directDeviceId = typeof deviceId === 'string' ? deviceId.trim() : '';
+        if (directDeviceId) {
+            const direct = this.knownDevicesById.get(directDeviceId);
+            if (direct) {
+                return direct;
+            }
+        }
+        const normalizedNodeId = typeof remoteNodeId === 'string' ? remoteNodeId.trim() : '';
+        if (normalizedNodeId) {
+            const mappedDeviceId = this.knownDeviceIdsByNodeId.get(normalizedNodeId);
+            if (mappedDeviceId) {
+                return this.knownDevicesById.get(mappedDeviceId) ?? null;
+            }
+        }
+        return null;
+    }
+    async refreshKnownDeviceCache() {
+        if (!this.requiresManagedTransportTrust()) {
+            return;
+        }
+        const devices = await this.searchDevices().catch(() => []);
+        devices.forEach((device) => this.rememberKnownDevice(device));
+    }
+    initializeConnectionTrust(connection, expectedDeviceId) {
+        const existing = this.connectionTrustStates.get(connection.id);
+        if (existing) {
+            if (expectedDeviceId && !existing.expectedDeviceId) {
+                existing.expectedDeviceId = expectedDeviceId;
+            }
+            return existing;
+        }
+        const promotionEligible = this.resolvePromotionEligibility({
+            connectionId: connection.id,
+            nodeId: connection.remoteNodeId,
+            deviceId: expectedDeviceId ?? undefined,
+        });
+        const required = promotionEligible && this.requiresManagedTransportTrust();
+        const initialState = {
+            required,
+            verified: !required,
+            failed: false,
+            expectedDeviceId: expectedDeviceId
+                || this.knownDeviceIdsByNodeId.get(connection.remoteNodeId)
+                || null,
+            verifiedDeviceId: !required
+                ? expectedDeviceId || this.knownDeviceIdsByNodeId.get(connection.remoteNodeId) || null
+                : null,
+            issuedChallenge: required ? createTransportTrustChallenge() : null,
+        };
+        this.connectionTrustStates.set(connection.id, initialState);
+        return initialState;
+    }
+    getConnectionTrustState(identifiers) {
+        const directConnectionId = typeof identifiers.connectionId === 'string' ? identifiers.connectionId.trim() : '';
+        if (directConnectionId) {
+            return this.connectionTrustStates.get(directConnectionId) ?? null;
+        }
+        for (const [connectionId, state] of this.connectionTrustStates.entries()) {
+            if ((state.verifiedDeviceId
+                && (state.verifiedDeviceId === identifiers.deviceId
+                    || state.verifiedDeviceId === identifiers.deviceIdHint))
+                || (state.expectedDeviceId
+                    && (state.expectedDeviceId === identifiers.deviceId
+                        || state.expectedDeviceId === identifiers.deviceIdHint))) {
+                return this.connectionTrustStates.get(connectionId) ?? null;
+            }
+        }
+        return null;
+    }
+    getConnectionTrustProjection(identifiers) {
+        const state = this.getConnectionTrustState(identifiers);
+        if (!state || !state.required) {
+            return null;
+        }
+        const verified = state.verified && !state.failed;
+        if (verified) {
+            return {
+                routable: true,
+                protocolState: 'routable',
+                health: 'healthy',
+                deviceId: state.verifiedDeviceId ?? state.expectedDeviceId ?? identifiers.deviceId ?? null,
+            };
+        }
+        return {
+            routable: false,
+            protocolState: 'unverified',
+            health: state.failed ? 'stale' : 'unknown',
+            error: state.failureReason ?? 'trusted-device-proof-pending',
+            deviceId: state.expectedDeviceId ?? identifiers.deviceId ?? identifiers.deviceIdHint ?? null,
+        };
+    }
+    applyConnectionTrustProjection(connection) {
+        if (this.hasRustPeerLifecycleProjection()) {
+            return;
+        }
+        const promotionEligible = this.resolvePromotionEligibility({
+            connectionId: connection.id,
+            nodeId: connection.remoteNodeId,
+        });
+        const trustProjection = this.getConnectionTrustProjection({
+            connectionId: connection.id,
+            nodeId: connection.remoteNodeId,
+        });
+        if (!trustProjection) {
+            this.syncConnectionPeerLifecycle(connection);
+            return;
+        }
+        this.peerLifecycle.upsert({
+            peerId: trustProjection.deviceId ?? undefined,
+            deviceId: trustProjection.deviceId ?? undefined,
+            deviceIdHint: trustProjection.deviceId ?? undefined,
+            nodeId: connection.deviceId,
+            connectionId: connection.id,
+            status: connection.isClosed ? 'closed' : 'connected',
+            health: trustProjection.health,
+            transportState: connection.isClosed ? 'closed' : 'connected',
+            protocolState: trustProjection.protocolState,
+            routable: trustProjection.routable,
+            promotionEligible,
+            error: trustProjection.error,
+            lastSeenAt: Date.now(),
+        });
+    }
+    async buildLocalTransportTrustPayload(connection) {
+        const identity = await getLocalTrustedIdentity().catch(() => null);
+        const localDeviceId = (await this.getLocalDeviceId().catch(() => null))
+            || this.deviceId
+            || this.options.localDeviceId
+            || null;
+        if (!identity || !localDeviceId) {
+            return null;
+        }
+        const trustState = this.initializeConnectionTrust(connection);
+        return {
+            version: 1,
+            deviceId: localDeviceId,
+            identityFingerprint: identity.fingerprint,
+            challenge: trustState.issuedChallenge ?? undefined,
+        };
+    }
+    async sendTransportHandshake(connection, action, challengeToSign) {
+        // Attach session token on the outgoing 'hello' if we have one for this peer.
+        const sessionToken = action === 'hello'
+            ? (this.pendingTokenByNodeId.get(connection.remoteNodeId) ?? undefined)
+            : undefined;
+        if (sessionToken) {
+            // Token has been picked up — remove from pending map.
+            this.pendingTokenByNodeId.delete(connection.remoteNodeId);
+        }
+        const localPayload = await this.buildLocalTransportTrustPayload(connection);
+        if (!localPayload) {
+            if (this.requiresManagedTransportTrust()) {
+                const state = this.initializeConnectionTrust(connection);
+                state.failed = true;
+                state.failureReason = 'local-trusted-identity-unavailable';
+            }
+            await connection.send({
+                type: 'handshake',
+                action,
+                moq: this.moqState === 'ready',
+                channelId: this.getConnectionChannelId(connection.id) ?? undefined,
+                ...(sessionToken ? { sessionToken } : {}),
+            });
+            return;
+        }
+        if (challengeToSign) {
+            const identity = await getLocalTrustedIdentity().catch(() => null);
+            if (!identity) {
+                throw new Error('Local trusted identity unavailable for handshake proof');
+            }
+            localPayload.signedChallenge = signTransportTrustChallenge(challengeToSign, identity.secretKey);
+        }
+        await connection.send({
+            type: 'handshake',
+            action,
+            moq: this.moqState === 'ready',
+            channelId: this.getConnectionChannelId(connection.id) ?? undefined,
+            transportTrust: localPayload,
+            ...(sessionToken ? { sessionToken } : {}),
+        });
+    }
+    async verifyRemoteTransportTrust(connection, payload) {
+        const trustState = this.initializeConnectionTrust(connection);
+        if (!trustState.required) {
+            return {
+                verified: true,
+                deviceId: payload?.deviceId ?? trustState.expectedDeviceId ?? null,
+            };
+        }
+        if (!payload) {
+            return { verified: false, reason: 'missing-transport-trust-payload' };
+        }
+        const claimedDeviceId = typeof payload.deviceId === 'string' ? payload.deviceId.trim() : '';
+        if (!claimedDeviceId) {
+            return { verified: false, reason: 'missing-remote-device-id' };
+        }
+        if (trustState.expectedDeviceId && trustState.expectedDeviceId !== claimedDeviceId) {
+            return {
+                verified: false,
+                reason: `expected-device-mismatch:${trustState.expectedDeviceId}:${claimedDeviceId}`,
+            };
+        }
+        let knownDevice = this.getKnownDevice(claimedDeviceId, connection.remoteNodeId);
+        if (!knownDevice) {
+            await this.refreshKnownDeviceCache();
+            knownDevice = this.getKnownDevice(claimedDeviceId, connection.remoteNodeId);
+        }
+        if (!knownDevice) {
+            return { verified: false, reason: `unknown-trusted-device:${claimedDeviceId}` };
+        }
+        const trustedMetadata = parseTrustedDeviceMetadata(knownDevice.metadata);
+        if (!trustedMetadata) {
+            return { verified: false, reason: `missing-trusted-device-metadata:${claimedDeviceId}` };
+        }
+        if (payload.identityFingerprint
+            && trustedMetadata.identityFingerprint !== payload.identityFingerprint) {
+            return {
+                verified: false,
+                reason: `trusted-device-fingerprint-mismatch:${claimedDeviceId}`,
+            };
+        }
+        const expectedChallenge = trustState.issuedChallenge;
+        if (!expectedChallenge || !payload.signedChallenge) {
+            return { verified: false, reason: 'missing-signed-transport-challenge' };
+        }
+        const verified = verifyTransportTrustChallenge(expectedChallenge, payload.signedChallenge, trustedMetadata.identityPublicKey);
+        if (!verified) {
+            return { verified: false, reason: `invalid-transport-proof:${claimedDeviceId}` };
+        }
+        return { verified: true, deviceId: claimedDeviceId };
+    }
+    async enforceConnectionTrustFailure(connection, reason) {
+        const trustState = this.initializeConnectionTrust(connection);
+        trustState.failed = true;
+        trustState.verified = false;
+        trustState.failureReason = reason;
+        this.applyConnectionTrustProjection(connection);
+        console.warn('[Client][TRUST] Disconnecting unverified connection', {
+            connectionId: connection.id,
+            remoteNodeId: connection.remoteNodeId,
+            reason,
+        });
+        await Promise.allSettled([
+            connection.disconnect(),
+            this.disconnectNode(connection.remoteNodeId).catch(() => undefined),
+        ]);
+    }
+    markConnectionTrustVerified(connection, verifiedDeviceId) {
+        const trustState = this.initializeConnectionTrust(connection, verifiedDeviceId);
+        trustState.verified = true;
+        trustState.failed = false;
+        trustState.failureReason = undefined;
+        trustState.verifiedDeviceId =
+            verifiedDeviceId
+                || trustState.verifiedDeviceId
+                || trustState.expectedDeviceId
+                || null;
+        if (verifiedDeviceId && !trustState.expectedDeviceId) {
+            trustState.expectedDeviceId = verifiedDeviceId;
+        }
+        this.applyConnectionTrustProjection(connection);
+    }
+    async searchDevices() {
+        await this.ensureSignalingReadyForDiscovery('search');
+        const devices = await this.signaling.searchDevices();
+        devices.forEach((device) => {
+            this.rememberKnownDevice(device);
+            this.peerLifecycle.upsertDevice(device);
+        });
+        return devices;
+    }
+    async updateDevice(deviceId, updates) {
+        await this.ensureSignalingReadyForDiscovery('search');
+        await this.signaling.updateDevice(deviceId, updates);
+    }
+    async deleteDevice(deviceId) {
+        await this.ensureSignalingReadyForDiscovery('search');
+        await this.signaling.deleteDevice(deviceId);
+    }
+    onDevicesChange(callback) {
+        let active = true;
+        let innerUnsubscribe = null;
+        void (async () => {
+            await this.ensureSignalingReadyForDiscovery('watch');
+            if (!active) {
+                return;
+            }
+            innerUnsubscribe = this.signaling.onDevicesChange((devices) => {
+                devices.forEach((device) => {
+                    this.rememberKnownDevice(device);
+                    this.peerLifecycle.upsertDevice(device);
+                });
+                callback(devices);
+            });
+        })().catch((error) => {
+            console.warn('[Client] Failed to initialize onDevicesChange listener:', error);
+            if (active) {
+                callback([]);
+            }
+        });
+        return () => {
+            active = false;
+            if (innerUnsubscribe) {
+                innerUnsubscribe();
+                innerUnsubscribe = null;
+            }
+        };
+    }
+    async subscribeSessions(localDeviceId, callback) {
+        await this.ensureSignalingReadyForDiscovery('sessions');
+        return this.signaling.subscribeSessions(localDeviceId, callback);
+    }
+    async startScanningLoop(options) {
+        const autoConnect = options.autoConnect ?? false;
+        const handledSessions = new Set();
+        let stopped = false;
+        let unsubscribeDevices = null;
+        let unsubscribeSessions = null;
+        let effectiveLocalDeviceId = options.localDeviceId;
+        try {
+            const resolvedLocalDeviceId = await this.signaling.getLocalDeviceId();
+            if (resolvedLocalDeviceId) {
+                effectiveLocalDeviceId = resolvedLocalDeviceId;
+            }
+        }
+        catch {
+            // Fall back to caller-provided localDeviceId.
+        }
+        unsubscribeDevices = this.onDevicesChange((devices) => {
+            if (stopped)
+                return;
+            options.onDevices?.(devices);
+        });
+        if (options.onIncomingSession) {
+            unsubscribeSessions = await this.subscribeSessions(effectiveLocalDeviceId, async (session) => {
+                if (stopped)
+                    return;
+                const sessionId = session.sessionId || session.connectionId;
+                if (!sessionId || handledSessions.has(sessionId))
+                    return;
+                if (session.targetDeviceId !== effectiveLocalDeviceId)
+                    return;
+                if (session.initiatorDeviceId === effectiveLocalDeviceId)
+                    return;
+                if (session.state === 'connected' || session.state === 'closed' || session.state === 'failed')
+                    return;
+                handledSessions.add(sessionId);
+                try {
+                    if (options.onIncomingSession) {
+                        await options.onIncomingSession(session);
+                        return;
+                    }
+                    const runtimeConnected = this.getPeerState(session.initiatorDeviceId)?.status === 'connected';
+                    if (runtimeConnected || options.isConnected?.(session.initiatorDeviceId)) {
+                        const isProtected = this.peerLifecycle.hasScopes(session.initiatorDeviceId) ||
+                            (options.hasProtectedConnectionIntent?.(session.initiatorDeviceId) ?? false);
+                        if (!isProtected) {
+                            await this.forceDisconnectPeer(session.initiatorDeviceId).catch(async () => {
+                                await options.cleanupStaleConnection?.(session.initiatorDeviceId);
+                            });
+                        }
+                    }
+                    if (session.initiatorNodeId) {
+                        await options.allowIncomingNodeId?.(session.initiatorNodeId);
+                    }
+                    const result = await options.acceptIncomingSession?.(sessionId, session.initiatorDeviceId);
+                    if (!result?.success) {
+                        throw new Error(result?.error || 'Failed to accept incoming signaling session');
+                    }
+                    await options.onIncomingSessionAccepted?.(session);
+                }
+                catch (error) {
+                    handledSessions.delete(sessionId);
+                    throw error;
+                }
+            });
+        }
+        return {
+            stop: () => {
+                stopped = true;
+                if (unsubscribeDevices) {
+                    unsubscribeDevices();
+                    unsubscribeDevices = null;
+                }
+                if (unsubscribeSessions) {
+                    unsubscribeSessions();
+                    unsubscribeSessions = null;
+                }
+            },
+        };
+    }
+    async connectDeviceWithRetry(device, hooks, options) {
+        if (!options.localDeviceId) {
+            return {
+                success: false,
+                skipped: 'missing-local-device-id',
+                attempts: 0,
+                error: 'Missing local device ID',
+            };
+        }
+        const maxRetries = options.maxRetries ?? 3;
+        const initialBackoffMs = options.initialBackoffMs ?? 2000;
+        const connectionState = await hooks.getConnectionState?.(device.deviceId);
+        if (connectionState === 'connecting') {
+            return {
+                success: true,
+                skipped: 'already-connecting',
+                attempts: 0,
+            };
+        }
+        if (connectionState === 'connected' && hooks.forceDisconnect) {
+            await hooks.forceDisconnect(device.deviceId);
+            await hooks.refreshState?.();
+        }
+        const attemptConnect = async () => {
+            const hasDirectIdentity = !!(typeof device.nodeId === 'string' && device.nodeId.trim().length > 0) ||
+                !!(typeof device.ticket === 'string' && device.ticket.trim().length > 0);
+            if (hasDirectIdentity) {
+                await hooks.directConnect(device);
+                await hooks.onConnected?.(device);
+                return;
+            }
+            const signalingResult = await hooks.signalConnect({
+                localDeviceId: options.localDeviceId,
+                targetDeviceId: device.deviceId,
+                targetUserId: options.targetUserId,
+                device,
+            });
+            if (!signalingResult.success) {
+                throw new Error(signalingResult.error || 'Signaling failed');
+            }
+        };
+        let attempt = 0;
+        let lastError = undefined;
+        while (attempt <= maxRetries) {
+            try {
+                await attemptConnect();
+                return {
+                    success: true,
+                    attempts: attempt,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === maxRetries) {
+                    break;
+                }
+                const delayMs = initialBackoffMs * Math.pow(2, attempt);
+                hooks.onRetry?.(device, attempt + 1, delayMs);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+                attempt += 1;
+            }
+        }
+        return {
+            success: false,
+            attempts: maxRetries + 1,
+            error: lastError instanceof Error ? lastError.message : 'Connection failed',
+        };
+    }
+    async bootstrapRuntime(options) {
+        const initializeClient = options.initializeClient ?? true;
+        if (options.platform === 'web') {
+            await options.initializeWeb?.();
+            if (initializeClient) {
+                await this.init();
+            }
+            return { ready: true, mode: 'web' };
+        }
+        const quickPollAttempts = options.quickPollAttempts ?? 5;
+        const quickPollIntervalMs = options.quickPollIntervalMs ?? 300;
+        const retryPollAttempts = options.retryPollAttempts ?? 8;
+        const retryPollIntervalMs = options.retryPollIntervalMs ?? 300;
+        const nativeInitEventTimeoutMs = options.nativeInitEventTimeoutMs ?? 4000;
+        if (!options.isNativeReady) {
+            console.warn('[Client][INIT] No isNativeReady callback provided for native platform; treating runtime as not ready');
+            return { ready: false, mode: 'native' };
+        }
+        const isReadyCallable = options.isNativeReady;
+        const quickReady = await pollUntilReady(isReadyCallable, quickPollAttempts, quickPollIntervalMs);
+        if (!quickReady) {
+            await options.retryNativeInit?.();
+            const [eventReady, pollReadyAfterRetry] = await Promise.all([
+                options.waitForNativeInitEvent?.(nativeInitEventTimeoutMs) ?? Promise.resolve(false),
+                pollUntilReady(isReadyCallable, retryPollAttempts, retryPollIntervalMs),
+            ]);
+            const ready = eventReady || pollReadyAfterRetry;
+            if (!ready) {
+                return { ready: false, mode: 'native' };
+            }
+        }
+        if (initializeClient) {
+            await this.init();
+        }
+        return { ready: true, mode: 'native' };
+    }
+    updateTransportConfig(transports) {
+        if (transports) {
+            // Merge with existing
+            this.options.transports = { ...(this.options.transports || {}), ...transports };
+        }
+    }
+    /**
+     * Bootstraps the WASM module and Rust signaling.
+     * Must be called before connect or createRoom.
+     */
+    async init() {
+        if (this.initPromise)
+            return this.initPromise;
+        if (this.wasmLoaded && this.wasmClient && this.localNodeId)
+            return;
+        // Note: The specific transport implementations (like TauriBridge) 
+        // may bypass this entirely if they rely strictly on IPC.
+        this.initPromise = (async () => {
+            try {
+                // Initialize WASM
+                openRtcDebugLog('[Client][INIT] Loading WASM module...');
+                await initWasm();
+                start();
+                this.wasmLoaded = true;
+                openRtcDebugLog('[Client][INIT] WASM module loaded');
+                // Instantiate the Rust WasmClient.
+                // In Personal Mode (apiKey + spaceKey), encode the space namespace into the appTag
+                // using a "space::{hash}" prefix so the Rust room backend routes to spaces/{hash}/rooms/.
+                const projectId = resolveProjectId(this.options);
+                const apiKey = typeof this.options.apiKey === 'string' ? this.options.apiKey.trim() : '';
+                const spaceKey = typeof this.options.spaceKey === 'string' ? this.options.spaceKey.trim() : '';
+                const isPersonalMode = (this.options.discoveryMode === undefined || this.options.discoveryMode === 'personal') && !!apiKey && !!spaceKey;
+                let wasmAppTag = resolveAppTag(this.options);
+                if (isPersonalMode) {
+                    const spaceNamespaceId = await deriveSpaceNamespace(apiKey, spaceKey);
+                    wasmAppTag = `space::${spaceNamespaceId}`;
+                    openRtcDebugLog(`[Client][INIT] Personal Mode — WASM rooms routed to spaces/${spaceNamespaceId.slice(0, 8)}…`);
+                }
+                this.effectiveRoomBackendTag = wasmAppTag;
+                this.wasmClient = new WasmClient(projectId, wasmAppTag);
+                openRtcDebugLog('PlutoRTC WASM Core Initialized');
+                this.signaling.setWasmClient(this.wasmClient);
+                if (!this.usesTicketOnlySignalingMode()) {
+                    await this.ensureAuthenticated('init');
+                    await this.syncAuthTokenToWasm('init');
+                    this.installAuthTokenSync();
+                }
+                const storageKey = `iroh_secret_key_${resolveStorageNamespace(this.options)}`;
+                let secretKeyBytes = undefined;
+                const persistenceMode = this.options.nodeIdPersistence ??
+                    (typeof this.options.transports?.iroh === 'object'
+                        ? this.options.transports.iroh.persistenceMode
+                        : undefined) ??
+                    'persistent';
+                // 1. Manual User Specified Key
+                if (this.options.secretKey) {
+                    const match = this.options.secretKey.match(/.{1,2}/g);
+                    if (match) {
+                        secretKeyBytes = new Uint8Array(match.map(byte => parseInt(byte, 16)));
+                    }
+                }
+                // 2. Persistent Mode (Default) - Try Load
+                else if (persistenceMode === 'persistent') {
+                    const storedKeyHex = typeof localStorage !== 'undefined' ? localStorage.getItem(storageKey) : null;
+                    if (storedKeyHex) {
+                        const match = storedKeyHex.match(/.{1,2}/g);
+                        if (match) {
+                            secretKeyBytes = new Uint8Array(match.map(byte => parseInt(byte, 16)));
+                        }
+                    }
+                }
+                // 3. Ephemeral Mode - secretKeyBytes remains undefined (generates new)
+                // Canonical device identity is always sourced from signaling bridge state.
+                this.deviceId = await this.signaling.getLocalDeviceId().catch(() => null);
+                const initIrohStartedAt = Date.now();
+                openRtcDebugLog(`[Client][INIT][IROH] start persistence=${persistenceMode} hasSecretKey=${!!secretKeyBytes} secretKeyLen=${secretKeyBytes?.length || 0} hasStoredDeviceId=${!!this.deviceId}`);
+                const pendingTimer = setInterval(() => {
+                    const elapsed = Date.now() - initIrohStartedAt;
+                    console.warn(`[Client][INIT][IROH] pending elapsedMs=${elapsed} hasWasmClient=${!!this.wasmClient}`);
+                }, 5000);
+                try {
+                    this.localNodeId = await withTimeout(this.wasmClient.init_iroh(secretKeyBytes), 20000);
+                }
+                catch (error) {
+                    const elapsed = Date.now() - initIrohStartedAt;
+                    throw new Error(`[Client] init_iroh stalled or failed: ${error?.message || error}; elapsed_ms=${elapsed}; persistence=${persistenceMode}; has_secret_key=${!!secretKeyBytes}`);
+                }
+                finally {
+                    clearInterval(pendingTimer);
+                }
+                openRtcDebugLog(`[Client][INIT][IROH] complete elapsedMs=${Date.now() - initIrohStartedAt} nodeId=${this.localNodeId}`);
+                if (!this.localNodeId) {
+                    throw new Error('[Client] init_iroh returned empty node id');
+                }
+                if (!this.deviceId) {
+                    this.deviceId = await this.signaling.getLocalDeviceId().catch(() => null);
+                }
+                this.node = { initialized: true, localNodeId: this.localNodeId };
+                if (this.localNodeId) {
+                    if (persistenceMode === 'persistent' && !this.options.secretKey && typeof localStorage !== 'undefined') {
+                        const keyToPersist = secretKeyBytes
+                            ?? (typeof this.wasmClient?.iroh_secret_key === 'function'
+                                ? await this.wasmClient.iroh_secret_key().catch(() => undefined)
+                                : undefined);
+                        if (keyToPersist && keyToPersist.length > 0) {
+                            const hex = Array.from(keyToPersist)
+                                .map((byte) => Number(byte).toString(16).padStart(2, '0'))
+                                .join('');
+                            localStorage.setItem(storageKey, hex);
+                            openRtcDebugLog(`[Client][INIT][IROH] persisted secret key bytes=${keyToPersist.length} nodeId=${this.localNodeId}`);
+                        }
+                        else {
+                            console.warn(`[Client][INIT][IROH] unable to persist secret key for nodeId=${this.localNodeId}`);
+                        }
+                    }
+                }
+                // Initialize shared MoQ session if enabled
+                if (this.options.transports?.moq) {
+                    this.initMoQ();
+                }
+                // Automatic TURN credentials
+                // Trigger if: useTurn OR privacyMode OR strictMode
+                // Note: Constructor normalizes `webrtc: true` to an object, so casting is safe.
+                const webrtcConfig = this.options.transports?.webrtc || DEFAULT_WEBRTC_CONFIG;
+                const shouldFetchTurn = webrtcConfig?.useTurn ||
+                    webrtcConfig?.privacyMode ||
+                    this.options.strictMode;
+                if (shouldFetchTurn) {
+                    try {
+                        const turnData = await this.signaling.getTurnCredentials();
+                        if (turnData && turnData.iceServers) {
+                            let servers = Array.isArray(turnData.iceServers) ? turnData.iceServers : [turnData.iceServers];
+                            // Filter STUN if privacyMode OR strictMode is enabled
+                            // Use the webrtcConfig reference we cast earlier
+                            if (webrtcConfig?.privacyMode || this.options.strictMode) {
+                                servers = servers.map((server) => {
+                                    if (typeof server.urls === 'string') {
+                                        return server.urls.startsWith('stun:') ? null : server;
+                                    }
+                                    else if (Array.isArray(server.urls)) {
+                                        const filteredUrls = server.urls.filter((url) => !url.startsWith('stun:'));
+                                        return filteredUrls.length > 0 ? { ...server, urls: filteredUrls } : null;
+                                    }
+                                    return server;
+                                }).filter((s) => s !== null);
+                                openRtcDebugLog(`[Client] Strict / Privacy Mode: Filtered STUN servers. Remaining=${servers.length}`);
+                            }
+                            else {
+                                openRtcDebugLog(`[Client] Automatically fetched ${servers.length} TURN servers.`);
+                            }
+                            // Merge into existing config
+                            if (!this.options.transports)
+                                this.options.transports = {};
+                            if (!this.options.transports.webrtc)
+                                this.options.transports.webrtc = {};
+                            // Ensure webrtc is an object (it is if we are here, but TS might complain)
+                            // It should be normalized by constructor.
+                            const currentConfig = this.options.transports.webrtc || DEFAULT_WEBRTC_CONFIG;
+                            if (!currentConfig.iceServers) {
+                                currentConfig.iceServers = [];
+                            }
+                            // If Strict Mode, we must ALSO filter the user-provided servers!
+                            if (this.options.strictMode) {
+                                currentConfig.iceServers = currentConfig.iceServers
+                                    .map((server) => {
+                                    if (typeof server.urls === 'string') {
+                                        return server.urls.startsWith('stun:') ? null : server;
+                                    }
+                                    else if (Array.isArray(server.urls)) {
+                                        const filteredUrls = server.urls.filter((url) => !url.startsWith('stun:'));
+                                        return filteredUrls.length > 0 ? { ...server, urls: filteredUrls } : null;
+                                    }
+                                    return server;
+                                }).filter(Boolean);
+                            }
+                            // RTCConfiguration.iceServers is technically RTCIceServer[], so we can push
+                            currentConfig.iceServers.push(...servers);
+                        }
+                    }
+                    catch (e) {
+                        console.warn("[Client] Failed to auto-fetch TURN credentials:", e);
+                    }
+                }
+                // Fallback to Default STUN if no config provided and not in strict/privacy mode
+                if (!this.options.strictMode && !webrtcConfig?.privacyMode) {
+                    // Only proceed if transports.webrtc is actually enabled/defined
+                    const config = this.options.transports?.webrtc;
+                    if (config) {
+                        // Check if iceServers is missing or empty
+                        if (!config.iceServers || (Array.isArray(config.iceServers) && config.iceServers.length === 0)) {
+                            openRtcDebugLog('[Client] No ICE servers provided. Using default public STUN servers.');
+                            config.iceServers = [...DEFAULT_ICE_SERVERS];
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                console.error("Failed to initialize PlutoRTC:", e);
+                throw e;
+            }
+        })();
+        return this.initPromise;
+    }
+    async ensureAuthenticated(reason) {
+        if (this.usesTicketOnlySignalingMode()) {
+            return;
+        }
+        const authMode = (this.options.authMode ?? 'anonymous');
+        const shouldLog = reason !== 'discovery';
+        // Personal Mode with spaceKey is auth-free: discovery uses sha256(apiKey+spaceKey) namespace,
+        // not Firebase user identity. Skip all auth checks entirely.
+        const isPersonalWithSpaceKey = (this.options.discoveryMode === undefined || this.options.discoveryMode === 'personal') &&
+            typeof this.options.spaceKey === 'string' &&
+            this.options.spaceKey.trim().length > 0;
+        if (isPersonalWithSpaceKey) {
+            return;
+        }
+        try {
+            await withTimeout(this.signaling.waitForAuth(), 5000);
+        }
+        catch (error) {
+            if (shouldLog) {
+                console.warn(`[Client][AUTH] waitForAuth timed out (${reason})`, error);
+            }
+        }
+        if (this.signaling.currentUser) {
+            if (shouldLog) {
+                openRtcDebugLog(`[Client][AUTH] Authenticated (${reason}) as ${this.signaling.currentUser.id}`);
+            }
+            return;
+        }
+        if (authMode === 'external' || authMode === 'required') {
+            throw new Error(`[Client][AUTH] ${authMode} auth mode requires host-provided auth before ${reason}`);
+        }
+        if (shouldLog) {
+            openRtcDebugLog(`[Client][AUTH] No user (${reason}); attempting anonymous sign-in...`);
+        }
+        await withTimeout(this.signaling.signInAnonymously(), 8000);
+        try {
+            await withTimeout(this.signaling.waitForAuth(), 5000);
+        }
+        catch {
+            // If auth state listener is slow, we still verify currentUser below.
+        }
+        if (!this.signaling.currentUser) {
+            throw new Error('[Client][AUTH] Anonymous sign-in did not produce an authenticated user');
+        }
+        if (shouldLog) {
+            openRtcDebugLog(`[Client][AUTH] Anonymous sign-in success (${reason})`);
+        }
+    }
+    installAuthTokenSync() {
+        if (this.authSyncUnsubscribe) {
+            return;
+        }
+        this.authSyncUnsubscribe = this.signaling.onAuthChange(() => {
+            this.syncAuthTokenToWasm('auth-change').catch((error) => {
+                console.warn('[Client][WASM-AUTH] Failed syncing auth token on auth change:', error);
+            });
+        });
+        if (!this.authRefreshInterval) {
+            this.authRefreshInterval = setInterval(() => {
+                this.syncAuthTokenToWasm('periodic-refresh', true).catch((error) => {
+                    console.warn('[Client][WASM-AUTH] Periodic auth refresh sync failed:', error);
+                });
+            }, 10 * 60 * 1000);
+        }
+    }
+    async syncAuthTokenToWasm(reason, forceRefresh = false) {
+        if (!this.wasmClient || typeof this.wasmClient.set_auth_token !== 'function') {
+            console.warn('[Client][WASM-AUTH] WasmClient.set_auth_token is unavailable');
+            return;
+        }
+        const user = this.signaling.currentUser;
+        const token = user && user.getToken ? await user.getToken(forceRefresh) : null;
+        const hasToken = !!token;
+        const tokenLen = token?.length || 0;
+        const userId = user?.id || null;
+        if (this.lastWasmAuthSyncUserId === userId && this.lastWasmAuthSyncToken === token) {
+            return;
+        }
+        this.lastWasmAuthSyncUserId = userId;
+        this.lastWasmAuthSyncToken = token;
+        openRtcDebugLog(`[Client][WASM-AUTH] Sync token (${reason}) hasToken=${hasToken} tokenLen=${tokenLen} uid=${userId || 'none'} forceRefresh=${forceRefresh}`);
+        this.wasmClient.set_auth_token(token);
+    }
+    // --- Shared MoQ Session ---
+    get moqState() { return this._moqState; }
+    get moq() {
+        if (this._moqState !== 'ready' || !this._moqSession)
+            return null;
+        return {
+            session: this._moqSession,
+            publisher: this._moqSession.publisher,
+            subscriber: this._moqSession.subscriber
+        };
+    }
+    onMoQReady(cb) { this.moqReadyListeners.push(cb); }
+    onMoQFailed(cb) { this.moqFailedListeners.push(cb); }
+    onMoQObject(callback) {
+        this.moqObjectListeners.push(callback);
+    }
+    async initMoQ() {
+        if (this._moqState !== 'none')
+            return;
+        this._moqState = 'connecting';
+        const moqConfig = this.options.transports?.moq || DEFAULT_MOQ_CONFIG;
+        const relayUrl = moqConfig.relayUrl;
+        try {
+            // @ts-ignore — WebTransport may not be in all TS lib targets
+            const wt = new WebTransport(relayUrl);
+            await wt.ready;
+            this._moqSession = new MoQSession(wt, (ns, name, obj, meta) => {
+                // 1. Dispatch to internal listeners/watchers
+                this.moqObjectListeners.forEach(cb => cb(ns, name, obj, meta));
+                // 2. Dispatch to Connection (for Chat/Signaling/Data)
+                // Only for 'data/' tracks to avoid injecting raw media into Connection frame parser
+                if (name.startsWith('data/') && this.localNodeId) {
+                    const connId = this.getDeterministicConnectionId(ns);
+                    const conn = this.connections.get(connId);
+                    if (conn) {
+                        conn.injectData(obj);
+                    }
+                }
+            });
+            await this._moqSession.init();
+            await this._moqSession.waitForSetup();
+            // Announce our namespace once
+            await this._moqSession.publisher.announce(this.localNodeId);
+            // Create Data Tracks
+            await this.createMoQDataTracks();
+            this._moqState = 'ready';
+            openRtcDebugLog(`[Client] MoQ Session Ready: Pub/Sub via ${relayUrl}`);
+            this.moqReadyListeners.forEach(cb => cb());
+        }
+        catch (e) {
+            console.warn("[Client] MoQ init failed:", e);
+            this._moqState = 'failed';
+            this.moqFailedListeners.forEach(cb => cb());
+        }
+    }
+    async connect(ticket, timeoutMs = 20000, expectedDeviceId, channelId) {
+        await this.ensureWasmRuntimeForP2P();
+        if (!ticket || !ticket.trim()) {
+            throw new Error('connect requires a non-empty endpoint ticket');
+        }
+        // Split compound ticket: "<iroh_ticket>.<base64url_token_payload>"
+        // We must split on the LAST `.` because endpoint tickets can contain
+        // dots (for example through embedded relay URL data).
+        const rawTicket = ticket.trim();
+        const { irohTicket, tokenSuffix } = splitCompoundTicket(rawTicket);
+        let nodeId;
+        try {
+            nodeId = await this.wasmClient.endpoint_id_from_ticket(irohTicket);
+        }
+        catch (error) {
+            throw new Error(`connect requires a valid endpoint ticket: ${error?.message || error}`);
+        }
+        // Store extracted token so sendTransportHandshake can include it.
+        let compoundTicketToken = null;
+        if (tokenSuffix) {
+            const decoded = decodeCompoundTicketPayload(tokenSuffix);
+            if (typeof decoded?.t === 'string') {
+                compoundTicketToken = decoded.t;
+                this.pendingTokenByNodeId.set(nodeId, decoded.t);
+            }
+        }
+        // Check if already connected
+        const connId = this.getDeterministicConnectionId(nodeId);
+        const existing = this.connections.get(connId);
+        if (existing) {
+            if (expectedDeviceId) {
+                this.initializeConnectionTrust(existing, expectedDeviceId);
+            }
+            return existing;
+        }
+        // Initiate connection
+        try {
+            openRtcDebugLog(`Initiating connection to ${nodeId}...`);
+            this.pendingConnection = await this.wasmClient.connect(irohTicket);
+        }
+        catch (e) {
+            console.warn("Connect trigger failed:", e);
+        }
+        // Retry open_bi loop
+        let biStream = null;
+        let retries = 0;
+        const interval = 500;
+        const maxRetries = Math.ceil(timeoutMs / interval);
+        if (compoundTicketToken
+            && this.wasmClient
+            && typeof this.wasmClient.present_session_token_to_host === 'function') {
+            let presented = false;
+            let presentationError = null;
+            let presentationRetries = 0;
+            let approvedScope = null;
+            while (presentationRetries < maxRetries) {
+                try {
+                    approvedScope = await this.wasmClient.present_session_token_to_host(nodeId, compoundTicketToken);
+                    console.info('[Client][AUTH] host approved session token', {
+                        nodeId,
+                        approvalScope: approvedScope || null,
+                        nextStep: 'open-main-stream-and-register-connection',
+                    });
+                    presented = true;
+                    break;
+                }
+                catch (error) {
+                    presentationError = error;
+                    presentationRetries++;
+                    await new Promise(r => setTimeout(r, interval));
+                }
+            }
+            if (!presented) {
+                throw new Error(`Failed to present session token to ${nodeId} after ${timeoutMs} ms: ${presentationError?.message || presentationError}`);
+            }
+        }
+        while (retries < maxRetries) {
+            try {
+                biStream = await this.wasmClient.open_bi(nodeId);
+                break;
+            }
+            catch (e) {
+                retries++;
+                await new Promise(r => setTimeout(r, interval));
+            }
+        }
+        if (!biStream) {
+            throw new Error(`Failed to establish connection to ${nodeId} after ${timeoutMs} ms`);
+        }
+        const connection = new Connection(connId, this.localNodeId, // Local
+        nodeId, // Remote
+        biStream.send.getWriter(), biStream.recv.getReader(), {
+            rtcConfig: this.getRTCConfig(),
+            transportContext: {
+                priorities: this.options.transportPriority || ['webrtc', 'moq', 'iroh'],
+                disableIrohFallback: this.options.disableIrohFallback || false,
+                isMoQReady: () => this.moqState === 'ready',
+                sendMoQ: (data) => this.sendMoQData(nodeId, data)
+            }
+        });
+        this.assignConnectionChannel(connection, channelId);
+        this.initializeConnectionTrust(connection, expectedDeviceId);
+        this.registerConnection(connection);
+        if (compoundTicketToken) {
+            console.info('[Client][AUTH] token-approved connection registered locally', {
+                nodeId,
+                connectionId: connection.id,
+                localNodeId: connection.localNodeId,
+                remoteNodeId: connection.remoteNodeId,
+            });
+        }
+        this.announceConnectionWhenStable(connection);
+        void this.sendTransportHandshake(connection, 'hello').catch((error) => {
+            console.warn('[Client][TRUST] Failed to send outgoing handshake', {
+                connectionId: connection.id,
+                remoteNodeId: connection.remoteNodeId,
+                error,
+            });
+        });
+        return connection;
+    }
+    /**
+     * Low-level dial helper.
+     * Ensures the ticket is connected and returns only connection identity metadata.
+     */
+    async connectRaw(ticket, timeoutMs = 20000) {
+        const connection = await this.connect(ticket, timeoutMs);
+        return {
+            connectionId: connection.id,
+            localNodeId: connection.localNodeId,
+            remoteNodeId: connection.deviceId,
+        };
+    }
+    /**
+     * Start core-managed auto-connect for the authenticated user.
+     * This is intentionally low-level: callers decide when to start/stop and
+     * what higher-level protocol to run on top of the resulting connection.
+     */
+    async startAutoConnect(localDeviceId) {
+        await this.ensureSignalingReadyForDiscovery('watch');
+        const userId = this.currentUser?.id;
+        if (!userId) {
+            throw new Error('startAutoConnect requires an authenticated user');
+        }
+        const effectiveLocalDeviceId = localDeviceId ||
+            (await this.getLocalDeviceId()) ||
+            this.deviceId;
+        if (!effectiveLocalDeviceId) {
+            throw new Error('startAutoConnect requires a local device identity');
+        }
+        this.signaling.startAutoConnect(userId, effectiveLocalDeviceId);
+    }
+    // --- Multiplexing API ---
+    async openBi(peerId) {
+        await this.ensureWasmRuntimeForP2P();
+        const bi = typeof this.wasmClient.open_peer_bi === 'function'
+            ? await this.wasmClient.open_peer_bi(peerId, 5000)
+            : await this.wasmClient.open_bi(peerId);
+        return {
+            readable: bi.recv,
+            writable: bi.send
+        };
+    }
+    async openUni(peerId) {
+        await this.ensureWasmRuntimeForP2P();
+        if (typeof this.wasmClient.open_peer_uni === 'function') {
+            return await this.wasmClient.open_peer_uni(peerId, 5000);
+        }
+        return await this.wasmClient.open_uni(peerId);
+    }
+    // --- Listener Management ---
+    getConnections() {
+        return Array.from(this.connections.values());
+    }
+    watchPeerStates(callback) {
+        return this.peerLifecycle.watch(callback);
+    }
+    getPeerState(id) {
+        return this.peerLifecycle.get(id);
+    }
+    listConnectedPeers() {
+        return this.peerLifecycle.listConnected();
+    }
+    isPeerPromotionEligible(identifiers) {
+        return this.resolvePromotionEligibility(identifiers);
+    }
+    addPeerScope(id, scope = 'persistent') {
+        if (this.wasmClient && typeof this.wasmClient.add_peer_scope === 'function') {
+            void this.wasmClient.add_peer_scope(id, scope).then(() => {
+                void this.refreshPeerSnapshot();
+            }).catch(() => { });
+            return this.peerLifecycle.get(id);
+        }
+        return this.peerLifecycle.addScope(id, scope);
+    }
+    releasePeerScope(id, scope) {
+        if (this.wasmClient && typeof this.wasmClient.release_peer_scope === 'function') {
+            void this.wasmClient.release_peer_scope(id, scope ?? null).then(() => {
+                void this.refreshPeerSnapshot();
+            }).catch(() => { });
+            return this.peerLifecycle.get(id);
+        }
+        return this.peerLifecycle.releaseScope(id, scope);
+    }
+    getPeerScopes(id) {
+        return this.peerLifecycle.get(id)?.scopes ?? [];
+    }
+    isSamePeer(a, b) {
+        const left = this.peerLifecycle.get(a);
+        const right = this.peerLifecycle.get(b);
+        if (left && right) {
+            return left.peerId === right.peerId;
+        }
+        return false;
+    }
+    async refreshPeerSnapshot() {
+        const hasRustProjection = this.hasRustPeerLifecycleProjection();
+        let hasRustPeerSnapshots = false;
+        if (this.wasmClient && typeof this.wasmClient.peer_sessions === 'function') {
+            const sessions = (await this.wasmClient.peer_sessions());
+            if (Array.isArray(sessions)) {
+                hasRustPeerSnapshots = true;
+                sessions.forEach((session) => {
+                    const activeConnectionId = session.activeConnectionId || session.candidateConnectionIds?.[0];
+                    const promotionEligible = this.resolvePromotionEligibility({
+                        connectionId: activeConnectionId || undefined,
+                        deviceId: session.deviceId ?? undefined,
+                        deviceIdHint: session.deviceIdHint ?? undefined,
+                        nodeId: session.nodeId ?? undefined,
+                    });
+                    const trustProjection = this.getConnectionTrustProjection({
+                        connectionId: activeConnectionId || undefined,
+                        deviceId: session.deviceId ?? undefined,
+                        deviceIdHint: session.deviceIdHint ?? undefined,
+                        nodeId: session.nodeId ?? undefined,
+                    });
+                    const settledReady = trustProjection
+                        ? trustProjection.routable
+                        : !!session.settledReady;
+                    this.peerLifecycle.upsert({
+                        deviceId: (trustProjection?.deviceId ?? session.deviceId) ?? undefined,
+                        deviceIdHint: session.deviceIdHint,
+                        nodeId: session.nodeId,
+                        connectionId: activeConnectionId || undefined,
+                        status: this.mapRustPeerStatus(session.status),
+                        health: trustProjection?.health ?? this.mapRustPeerHealth(session.health),
+                        transportState: activeConnectionId
+                            ? 'connected'
+                            : session.status === 'connecting'
+                                ? 'connecting'
+                                : 'closed',
+                        protocolState: trustProjection?.protocolState
+                            ?? (settledReady
+                                ? 'routable'
+                                : activeConnectionId
+                                    ? 'transport-only'
+                                    : session.status === 'connecting'
+                                        ? 'connecting'
+                                        : 'closed'),
+                        routable: settledReady,
+                        promotionEligible,
+                        scopes: session.scopes ?? [],
+                        error: trustProjection?.error ?? session.error ?? undefined,
+                        lastSeenAt: session.lastSeenAtMs,
+                    });
+                });
+            }
+        }
+        else if (this.wasmClient && typeof this.wasmClient.peer_snapshots === 'function') {
+            const snapshots = (await this.wasmClient.peer_snapshots());
+            if (Array.isArray(snapshots)) {
+                hasRustPeerSnapshots = true;
+                snapshots.forEach((snapshot) => {
+                    const promotionEligible = this.resolvePromotionEligibility({
+                        connectionId: snapshot.connectionIds?.[0],
+                        deviceId: snapshot.deviceId ?? undefined,
+                        deviceIdHint: snapshot.deviceIdHint ?? undefined,
+                        nodeId: snapshot.nodeId ?? undefined,
+                    });
+                    this.peerLifecycle.upsert({
+                        deviceId: snapshot.deviceId,
+                        deviceIdHint: snapshot.deviceIdHint,
+                        nodeId: snapshot.nodeId,
+                        connectionId: snapshot.connectionIds?.[0],
+                        status: this.mapRustPeerStatus(snapshot.status),
+                        health: this.mapRustPeerHealth(snapshot.health),
+                        promotionEligible,
+                        scopes: snapshot.scopes ?? [],
+                        error: snapshot.error ?? undefined,
+                        lastSeenAt: snapshot.lastSeenAtMs,
+                    });
+                });
+            }
+        }
+        const devices = await this.searchDevices().catch(() => []);
+        devices.forEach((device) => {
+            this.peerLifecycle.upsertDevice(device);
+        });
+        if (!hasRustProjection) {
+            this.connections.forEach((connection) => {
+                this.syncConnectionPeerLifecycle(connection);
+            });
+        }
+        const backendStates = await this.signaling.getConnectionStates().catch(() => []);
+        backendStates.forEach((state) => {
+            this.applyBackendConnectionState(state);
+        });
+        if (hasRustProjection && !hasRustPeerSnapshots && backendStates.length === 0) {
+            return this.peerLifecycle.list();
+        }
+        return this.peerLifecycle.list();
+    }
+    async connectPeer(options) {
+        const scope = options.scope ?? 'persistent';
+        if (!options.ticket) {
+            throw new Error('connectPeer requires a ticket.');
+        }
+        const connection = await this.connect(options.ticket, 20000, options.deviceId, options.channelId);
+        const promotionEligible = this.resolvePromotionEligibility({
+            connectionId: connection.id,
+            nodeId: connection.remoteNodeId,
+            deviceId: options.deviceId ?? undefined,
+        });
+        const peerId = options.deviceId ||
+            connection.remoteNodeId ||
+            connection.deviceId ||
+            connection.id;
+        if (this.hasRustPeerLifecycleProjection()) {
+            void this.refreshPeerSnapshot().catch(() => { });
+        }
+        else {
+            this.peerLifecycle.upsert({
+                peerId,
+                deviceId: options.deviceId,
+                nodeId: connection.deviceId,
+                connectionId: connection.id,
+                ticket: options.ticket,
+                status: 'connected',
+                health: 'healthy',
+                promotionEligible,
+                scopes: [scope],
+                lastSeenAt: Date.now(),
+            });
+        }
+        void this.addPeerScope(peerId, scope);
+        return connection;
+    }
+    async disconnectPeer(id, scope = 'persistent') {
+        const nextState = this.peerLifecycle.releaseScope(id, scope);
+        if (nextState && nextState.scopes.length > 0) {
+            return;
+        }
+        await this.forceDisconnectPeer(id);
+    }
+    async forceDisconnectPeer(id) {
+        const peer = this.peerLifecycle.releaseScope(id);
+        const candidates = this.getPeerCandidates(peer?.peerId || id);
+        await Promise.allSettled(Array.from(candidates).map(async (candidate) => {
+            const connectionMatches = Array.from(this.connections.values()).filter((connection) => {
+                const connectionId = connection.id.trim().toLowerCase();
+                const remoteNodeId = connection.deviceId.trim().toLowerCase();
+                return candidate === remoteNodeId || candidate === connectionId || connectionId.includes(candidate);
+            });
+            await Promise.allSettled(connectionMatches.map((connection) => connection.disconnect()));
+            const nodeId = peer?.nodeId || (connectionMatches[0]?.deviceId ?? null);
+            if (nodeId && candidate === nodeId.trim().toLowerCase()) {
+                await this.disconnectNode(nodeId).catch(() => { });
+            }
+        }));
+        if (this.hasRustPeerLifecycleProjection()) {
+            await this.refreshPeerSnapshot().catch(() => { });
+        }
+        else {
+            this.peerLifecycle.updateHealth(id, 'stale', 'closed');
+        }
+    }
+    async getPeerHealth(id) {
+        const peer = this.peerLifecycle.get(id);
+        if (!peer) {
+            return 'unknown';
+        }
+        return peer.health;
+    }
+    mapRustPeerStatus(status) {
+        switch ((status || '').toLowerCase()) {
+            case 'connected':
+                return 'connected';
+            case 'connecting':
+            case 'pending':
+                return 'connecting';
+            case 'failed':
+                return 'failed';
+            case 'closing':
+            case 'closed':
+                return 'closed';
+            default:
+                return 'disconnected';
+        }
+    }
+    mapRustPeerHealth(health) {
+        switch ((health || '').toLowerCase()) {
+            case 'healthy':
+                return 'healthy';
+            case 'suspect':
+                return 'suspect';
+            case 'stale':
+                return 'stale';
+            default:
+                return 'unknown';
+        }
+    }
+    async getTicket() {
+        await this.ensureWasmRuntimeForP2P();
+        const config = this.getRTCConfig();
+        const irohConfig = this.options.transports?.iroh;
+        // Use safe ticket (Relay Only) if:
+        // 1. Strict Mode is enabled
+        // 2. WebRTC Privacy Mode is enabled (Legacy/Compat)
+        // 3. Iroh is explicitly configured with relayOnly: true
+        const irohRelayOnly = typeof irohConfig === 'object' && irohConfig.relayOnly;
+        if (this.options.strictMode || config?.privacyMode || irohRelayOnly) {
+            return await this.wasmClient.endpoint_ticket();
+        }
+        return await this.wasmClient.endpoint_ticket();
+    }
+    async getNodeId() {
+        await this.ensureWasmRuntimeForP2P();
+        return this.localNodeId;
+    }
+    async getNodeIdFromTicket(ticket) {
+        const trimmed = ticket.trim();
+        if (!trimmed)
+            return null;
+        // Strip only the compound-ticket suffix; raw iroh tickets can contain dots.
+        const { irohTicket } = splitCompoundTicket(trimmed);
+        if (!this.wasmClient || typeof this.wasmClient.endpoint_id_from_ticket !== 'function') {
+            return null;
+        }
+        try {
+            return await this.wasmClient.endpoint_id_from_ticket(irohTicket);
+        }
+        catch {
+            return null;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Session grant helpers — the Rust wasm client owns token registration,
+    // validation, and revoke semantics for short-lived share-style admission.
+    // -----------------------------------------------------------------------
+    /**
+     * Generate a random session token, register it, and return a compound
+     * ticket string with the token suffix appended.
+     *
+     * @param scope      Logical label (e.g. "share"). Used for bulk-revoke.
+     * @param maxConnections  0 = unlimited.
+     */
+    async getEndpointTicketWithToken(grantScope, maxConnections = 0) {
+        await this.ensureWasmRuntimeForP2P();
+        if (this.wasmClient && typeof this.wasmClient.endpoint_ticket_with_token === 'function') {
+            return await this.wasmClient.endpoint_ticket_with_token(grantScope, maxConnections);
+        }
+        const irohTicket = await this.getTicket();
+        return this.buildCompoundTicketWithToken(irohTicket, grantScope, maxConnections);
+    }
+    /**
+     * Build a compound ticket from an externally-provided iroh ticket string.
+     * Generates a session token, registers it with the Rust wasm client when available,
+     * and appends the token
+     * payload as a base64url suffix separated by `.`.
+     *
+     * Used by RuntimeClient.getTicketWithToken() on native desktop where the
+     * iroh ticket comes from the Rust backend (via Tauri IPC) rather than the
+     * WASM node running in the webview.
+     */
+    buildCompoundTicketWithToken(irohTicket, grantScope, maxConnections = 0) {
+        const token = Client.generateSessionToken();
+        if (this.wasmClient && typeof this.wasmClient.register_session_token === 'function') {
+            this.wasmClient.register_session_token(token, grantScope, maxConnections);
+        }
+        return Client.buildCompoundTicketWithPayload(irohTicket, token, grantScope, maxConnections);
+    }
+    setManagedPresenceTicket(ticket) {
+        const trimmed = ticket?.trim() || '';
+        if (!trimmed) {
+            this.managedPresenceGrant = null;
+            return;
+        }
+        const { irohTicket, tokenSuffix } = splitCompoundTicket(trimmed);
+        const payload = tokenSuffix ? decodeCompoundTicketPayload(tokenSuffix) : null;
+        if (!payload?.t || !payload?.s) {
+            throw new Error('Managed presence ticket must be a compound ticket with an embedded token payload');
+        }
+        this.managedPresenceGrant = {
+            scope: payload.s,
+            token: payload.t,
+            maxConnections: typeof payload.m === 'number' ? payload.m : 0,
+            compoundTicket: trimmed,
+            irohTicket,
+        };
+        if (this.wasmClient && typeof this.wasmClient.register_session_token === 'function') {
+            this.wasmClient.register_session_token(payload.t, payload.s, typeof payload.m === 'number' ? payload.m : 0);
+        }
+    }
+    clearManagedPresenceTicket() {
+        this.managedPresenceGrant = null;
+    }
+    /** Register an externally-generated session token with the Rust wasm client. */
+    registerSessionToken(token, grantScope, maxConnections) {
+        if (this.wasmClient && typeof this.wasmClient.register_session_token === 'function') {
+            this.wasmClient.register_session_token(token, grantScope, maxConnections);
+        }
+    }
+    /** Revoke a specific session token. */
+    revokeSessionToken(token) {
+        if (this.wasmClient && typeof this.wasmClient.revoke_session_token === 'function') {
+            this.wasmClient.revoke_session_token(token);
+        }
+    }
+    /** Revoke all tokens that match the given scope. */
+    async revokeTokensByScope(grantScope) {
+        await this.ensureWasmRuntimeForP2P();
+        if (!this.wasmClient || typeof this.wasmClient.revoke_tokens_by_scope !== 'function') {
+            return [];
+        }
+        const affectedConnectionIds = await this.wasmClient.revoke_tokens_by_scope(grantScope);
+        if (!Array.isArray(affectedConnectionIds) || affectedConnectionIds.length === 0) {
+            return [];
+        }
+        const liveConnections = affectedConnectionIds
+            .map((connectionId) => this.connections.get(connectionId))
+            .filter((connection) => !!connection);
+        await Promise.allSettled(liveConnections.map((connection) => connection.disconnect()));
+        return affectedConnectionIds;
+    }
+    static generateSessionToken() {
+        const bytes = new Uint8Array(24);
+        crypto.getRandomValues(bytes);
+        // base64url, no padding
+        return btoa(String.fromCharCode(...bytes))
+            .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    static encodeSessionTokenPayload(token, grantScope, maxConnections) {
+        return btoa(JSON.stringify({ t: token, s: grantScope, m: maxConnections }))
+            .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    static buildCompoundTicketWithPayload(irohTicket, token, grantScope, maxConnections) {
+        return `${irohTicket}.${Client.encodeSessionTokenPayload(token, grantScope, maxConnections)}`;
+    }
+    async clearSessionTokens() {
+        await this.ensureWasmRuntimeForP2P();
+        this.clearManagedPresenceTicket();
+        if (this.wasmClient && typeof this.wasmClient.clear_session_tokens === 'function') {
+            this.wasmClient.clear_session_tokens();
+        }
+    }
+    async resolvePresenceTicket(ticketOverride) {
+        const explicitTicket = ticketOverride?.trim();
+        if (explicitTicket) {
+            return explicitTicket;
+        }
+        if (this.managedPresenceGrant) {
+            return this.refreshManagedPresenceTicketIfNeeded();
+        }
+        const configuredTicket = this.options.ticket?.trim();
+        if (configuredTicket) {
+            return configuredTicket;
+        }
+        return this.getTicket();
+    }
+    async refreshManagedPresenceTicketIfNeeded() {
+        const grant = this.managedPresenceGrant;
+        if (!grant) {
+            return this.getTicket();
+        }
+        let nextIrohTicket = grant.irohTicket;
+        try {
+            nextIrohTicket = await this.getTicket();
+        }
+        catch {
+            return grant.compoundTicket;
+        }
+        if (nextIrohTicket === grant.irohTicket) {
+            return grant.compoundTicket;
+        }
+        grant.irohTicket = nextIrohTicket;
+        grant.compoundTicket = Client.buildCompoundTicketWithPayload(nextIrohTicket, grant.token, grant.scope, grant.maxConnections);
+        console.info('[Client][PRESENCE] rebuilt managed compound ticket after endpoint change', {
+            grantScope: grant.scope,
+        });
+        return grant.compoundTicket;
+    }
+    async validateIncomingSessionToken(token, connectionId) {
+        if (!this.wasmClient || typeof this.wasmClient.validate_session_token !== 'function') {
+            return { ok: true };
+        }
+        try {
+            let scope = '';
+            if (connectionId &&
+                typeof this.wasmClient.validate_session_token_for_connection === 'function') {
+                scope = await this.wasmClient.validate_session_token_for_connection(token, connectionId);
+            }
+            else {
+                scope = this.wasmClient.validate_session_token(token);
+            }
+            return { ok: true, scope: scope || undefined };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: error?.message || `${error}`,
+            };
+        }
+    }
+    /**
+     * Start the signaling-backed presence loop owned by the Rust core.
+     * A ticket can be provided explicitly, otherwise the current endpoint ticket is used.
+     */
+    async startPresenceLoop(options) {
+        await this.ensureWasmRuntimeForP2P();
+        if (!this.localNodeId) {
+            throw new Error('startPresenceLoop requires an initialized node');
+        }
+        const isPersonalWithSpaceKey = (this.options.discoveryMode === undefined || this.options.discoveryMode === 'personal') &&
+            typeof this.options.spaceKey === 'string' &&
+            this.options.spaceKey.trim().length > 0;
+        // In personal mode there's no Firebase user — use the node ID as the
+        // synthetic scope id so the Rust core can publish into the shared
+        // spaces/{namespaceId}/devices collection without auth.
+        const userId = this.currentUser?.id ?? (isPersonalWithSpaceKey ? this.localNodeId : null);
+        if (!userId) {
+            throw new Error('startPresenceLoop requires an authenticated user');
+        }
+        const ticket = await this.resolvePresenceTicket(options?.ticket);
+        if (!ticket || !ticket.trim()) {
+            throw new Error('startPresenceLoop requires a valid endpoint ticket');
+        }
+        this.signaling.startPresenceLoop(userId, this.localNodeId, options?.deviceName || this.options.deviceName || 'Unknown Device', ticket, options?.metadata);
+    }
+    /**
+     * Mark local presence offline in the signaling backend.
+     */
+    async setOffline() {
+        if (!this.localNodeId) {
+            return;
+        }
+        await this.signaling.setOffline(this.localNodeId);
+    }
+    /**
+     * Check raw connectivity against a remote node id.
+     */
+    async isConnected(nodeId) {
+        await this.ensureWasmRuntimeForP2P();
+        if (!nodeId || !nodeId.trim()) {
+            return false;
+        }
+        if (this.wasmClient && typeof this.wasmClient.is_connected === 'function') {
+            return this.wasmClient.is_connected(nodeId);
+        }
+        return this.signaling.isConnected(nodeId);
+    }
+    /**
+     * Disconnect a remote node from the local connection manager.
+     */
+    async disconnectNode(nodeId) {
+        if (!nodeId || !nodeId.trim()) {
+            return;
+        }
+        const matchingConnections = Array.from(this.connections.values()).filter((connection) => connection.deviceId === nodeId);
+        await Promise.allSettled(matchingConnections.map((connection) => connection.disconnect()));
+        if (this.wasmClient && typeof this.wasmClient.disconnect === 'function') {
+            try {
+                await this.wasmClient.disconnect(nodeId);
+            }
+            catch {
+                // Best-effort at core-level disconnect; local manager disconnect already applied.
+            }
+        }
+        this.signaling.notifyDisconnectRequested(nodeId);
+    }
+    async getLocalDeviceId() {
+        return this.signaling.getLocalDeviceId();
+    }
+    /**
+     * Route a raw message received on a native iroh connection through token
+     * validation. Called by RuntimeClient when NativeIpcBridge fires an
+     * `iroh://message` event for an incoming native connection.
+     *
+     * If we have a TS Connection object for this peer (e.g. the client also
+     * called connect()), route through handleMessage. Otherwise, for connections
+     * that were accepted purely by the Rust protocol handler, perform token
+     * validation directly.
+     *
+     * @returns true if the connection should be rejected (caller should disconnect)
+     */
+    async acceptNativeMessage(connectionId, remoteNodeId, msg) {
+        if (!remoteNodeId)
+            return false;
+        // Try to find an existing TS Connection object (bidirectional case).
+        const connId = this.getDeterministicConnectionId(remoteNodeId);
+        const conn = this.connections.get(connId);
+        if (conn) {
+            void this.handleMessage(conn, msg);
+            return false;
+        }
+        // No TS Connection — this is an incoming-only native connection.
+        // Validate incoming grant material if the runtime exposes a validator.
+        if (msg &&
+            typeof msg === 'object' &&
+            msg.type === 'handshake' &&
+            (msg.action === 'hello' || !msg.action)) {
+            const result = await this.validateIncomingSessionToken(msg.sessionToken ?? '', connectionId ?? undefined);
+            if (!result.ok) {
+                console.warn('[Client][SESSION-TOKEN] Rejecting native connection — invalid session token', {
+                    remoteNodeId,
+                    reason: result.reason,
+                    hasToken: !!msg.sessionToken,
+                });
+                return true; // caller should disconnect
+            }
+            // Valid token — Rust already accepted; nothing more to do here.
+        }
+        return false;
+    }
+    async startListening() {
+        if (this.listening)
+            return;
+        // Always ensure runtime is ready for listening/discovery
+        await this.ensureWasmRuntimeForP2P();
+        this.listening = true;
+        const sharedHub = this.getSharedIncomingStreamHub();
+        if (sharedHub) {
+            sharedHub.addClient(this);
+        }
+        else if (!this.listenLoopTask) {
+            this.listenLoopTask = this.listenLoop().finally(() => {
+                this.listenLoopTask = null;
+            });
+        }
+        const userId = this.signaling.currentUser?.id;
+        if (userId && this.localNodeId) {
+            const ticket = await this.resolvePresenceTicket();
+            this.signaling.startPresenceLoop(userId, this.localNodeId, this.options.deviceName || 'Unknown Device', ticket, '' // metadata
+            );
+        }
+    }
+    stopListening() {
+        this.listening = false;
+        this.getSharedIncomingStreamHub()?.removeClient(this);
+        if (this.localNodeId) {
+            this.signaling.setOffline(this.localNodeId);
+        }
+    }
+    getSharedIncomingStreamHub() {
+        if (!this.wasmClient || typeof this.wasmClient.incoming_streams !== 'function') {
+            return null;
+        }
+        const cacheKey = this.wasmClient;
+        let hub = Client.incomingStreamHubs.get(cacheKey);
+        if (!hub) {
+            hub = new SharedIncomingStreamHub(this.wasmClient);
+            Client.incomingStreamHubs.set(cacheKey, hub);
+        }
+        return hub;
+    }
+    nextIncomingStreamRetryDelayMs(attempt) {
+        const backoff = Client.INCOMING_STREAM_RETRY_MIN_DELAY_MS * Math.pow(2, Math.max(0, attempt - 1));
+        return Math.min(Client.INCOMING_STREAM_RETRY_MAX_DELAY_MS, backoff);
+    }
+    /**
+     * Force an immediate presence update and reconnect snapshot.
+     */
+    forceReconnectSnapshot() {
+        this.signaling.forceReconnectSnapshot();
+    }
+    async updatePresenceInternal() {
+        if (this.localNodeId) {
+            const ticket = await this.resolvePresenceTicket();
+            await this.updatePresence(true, this.options.deviceTTL, undefined, ticket);
+        }
+    }
+    async listenLoop() {
+        let attempt = 0;
+        while (this.listening) {
+            if (!this.wasmClient || typeof this.wasmClient.incoming_streams !== 'function') {
+                console.warn('[Client][INCOMING] incoming_streams is unavailable; stopping listen loop');
+                return;
+            }
+            let reader = null;
+            try {
+                const streams = await this.wasmClient.incoming_streams();
+                reader = streams.getReader();
+                const activeReader = reader;
+                attempt = 0;
+                while (this.listening) {
+                    const { done, value } = await activeReader.read();
+                    if (done) {
+                        throw new Error('incoming stream reader closed unexpectedly');
+                    }
+                    if (!value) {
+                        continue;
+                    }
+                    console.debug('[Client][INCOMING] Received stream from WASM node', {
+                        type: value?.type || 'unknown',
+                        endpointId: value?.endpointId || value?.endpoint_id || 'unknown',
+                    });
+                    try {
+                        await this.handleIncomingStream(value);
+                    }
+                    catch (error) {
+                        const incoming = value;
+                        const streamType = typeof incoming.type === 'string' ? incoming.type : 'bi';
+                        const remoteNodeId = typeof incoming.endpointId === 'string'
+                            ? incoming.endpointId
+                            : typeof incoming.endpoint_id === 'string'
+                                ? incoming.endpoint_id
+                                : 'unknown';
+                        console.error('[Client][INCOMING] Failed to handle incoming stream', {
+                            remoteNodeId,
+                            type: streamType,
+                            error,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                if (!this.listening) {
+                    break;
+                }
+                attempt += 1;
+                const delayMs = this.nextIncomingStreamRetryDelayMs(attempt);
+                console.warn('[Client][INCOMING] Listen loop restarting after stream failure', {
+                    attempt,
+                    delayMs,
+                    error,
+                });
+                await this.sleep(delayMs);
+            }
+            finally {
+                if (reader) {
+                    // Avoid canceling the wasm-backed incoming-stream reader here.
+                    // The underlying wasm-streams source uses a one-shot cancel
+                    // closure, and teardown paths (especially in React dev remounts)
+                    // can end up invoking that callback more than once.
+                    try {
+                        reader.releaseLock();
+                    }
+                    catch {
+                        // no-op
+                    }
+                }
+            }
+        }
+    }
+    prependChunkToReadable(readable, firstChunk) {
+        const sourceReader = readable.getReader();
+        let emittedFirst = false;
+        return new ReadableStream({
+            async pull(controller) {
+                if (!emittedFirst) {
+                    emittedFirst = true;
+                    controller.enqueue(firstChunk);
+                    return;
+                }
+                const { done, value } = await sourceReader.read();
+                if (done) {
+                    controller.close();
+                    sourceReader.releaseLock();
+                    return;
+                }
+                if (value)
+                    controller.enqueue(value);
+            },
+            async cancel(reason) {
+                await sourceReader.cancel(reason).catch(() => undefined);
+            },
+        });
+    }
+    async cancelUnhandledIncomingUniStream(stream, remoteNodeId) {
+        if (!stream || typeof stream !== 'object') {
+            return;
+        }
+        try {
+            const readable = stream;
+            if (typeof readable.cancel === 'function') {
+                await readable.cancel('unhandled-incoming-uni');
+                openRtcDebugLog('[Client][INCOMING] Cancelled unhandled uni stream', {
+                    remoteNodeId,
+                });
+                return;
+            }
+            if (typeof readable.getReader === 'function') {
+                const reader = readable.getReader();
+                try {
+                    await reader.cancel('unhandled-incoming-uni');
+                }
+                finally {
+                    try {
+                        reader.releaseLock();
+                    }
+                    catch {
+                        // no-op
+                    }
+                }
+                openRtcDebugLog('[Client][INCOMING] Cancelled unhandled uni stream via reader', {
+                    remoteNodeId,
+                });
+            }
+        }
+        catch (error) {
+            console.warn('[Client][INCOMING] Failed to cancel unhandled uni stream', {
+                remoteNodeId,
+                error,
+            });
+        }
+    }
+    prependBytesToReader(sourceReader, prefix) {
+        let emittedPrefix = prefix.byteLength === 0;
+        return new ReadableStream({
+            async pull(controller) {
+                if (!emittedPrefix) {
+                    emittedPrefix = true;
+                    controller.enqueue(prefix);
+                    return;
+                }
+                const { done, value } = await sourceReader.read();
+                if (done) {
+                    controller.close();
+                    return;
+                }
+                if (value) {
+                    controller.enqueue(value);
+                }
+            },
+            async cancel(reason) {
+                await sourceReader.cancel(reason).catch(() => undefined);
+            },
+        });
+    }
+    concatBytes(parts) {
+        const total = parts.reduce((sum, part) => sum + part.byteLength, 0);
+        const merged = new Uint8Array(total);
+        let offset = 0;
+        for (const part of parts) {
+            merged.set(part, offset);
+            offset += part.byteLength;
+        }
+        return merged;
+    }
+    encodeChannelEnvelope(channelId, metadata) {
+        const normalizedChannelId = channelId.trim();
+        if (!normalizedChannelId) {
+            throw new Error('Channel envelope requires a non-empty channel id.');
+        }
+        const encoder = new TextEncoder();
+        const channelBytes = encoder.encode(normalizedChannelId);
+        const metadataBytes = metadata ? encoder.encode(JSON.stringify(metadata)) : new Uint8Array(0);
+        const header = new Uint8Array(Client.CHANNEL_ENVELOPE_HEADER_BYTES + channelBytes.byteLength + metadataBytes.byteLength);
+        const view = new DataView(header.buffer);
+        header[0] = Client.CHANNEL_ENVELOPE_MAGIC;
+        header[1] = Client.CHANNEL_ENVELOPE_VERSION;
+        view.setUint16(2, channelBytes.byteLength, false);
+        view.setUint16(4, metadataBytes.byteLength, false);
+        header.set(channelBytes, Client.CHANNEL_ENVELOPE_HEADER_BYTES);
+        header.set(metadataBytes, Client.CHANNEL_ENVELOPE_HEADER_BYTES + channelBytes.byteLength);
+        return header;
+    }
+    wrapChannelWritable(writable, channelId, metadata) {
+        const envelope = this.encodeChannelEnvelope(channelId, metadata);
+        const writer = writable.getWriter();
+        let envelopeWritten = false;
+        const ensureEnvelope = async () => {
+            if (envelopeWritten) {
+                return;
+            }
+            envelopeWritten = true;
+            await writer.write(envelope);
+        };
+        return new WritableStream({
+            write: async (chunk) => {
+                await ensureEnvelope();
+                await writer.write(chunk);
+            },
+            close: async () => {
+                await ensureEnvelope();
+                try {
+                    await writer.close();
+                }
+                finally {
+                    writer.releaseLock();
+                }
+            },
+            abort: async (reason) => {
+                try {
+                    await writer.abort(reason);
+                }
+                finally {
+                    writer.releaseLock();
+                }
+            },
+        });
+    }
+    async extractIncomingChannelEnvelope(stream, remoteNodeId) {
+        if (!this.isBiStreamLike(stream)) {
+            return { stream, channel: null };
+        }
+        let reader;
+        try {
+            reader = stream.recv.getReader();
+        }
+        catch (error) {
+            console.warn('[Client][CHANNEL] Incoming stream recv reader unavailable; skipping channel envelope inspection', {
+                remoteNodeId,
+                error,
+            });
+            return { stream, channel: null };
+        }
+        const chunks = [];
+        let bufferedLength = 0;
+        try {
+            while (bufferedLength < Client.CHANNEL_ENVELOPE_HEADER_BYTES) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                if (!value || value.byteLength === 0) {
+                    continue;
+                }
+                const chunk = new Uint8Array(value);
+                chunks.push(chunk);
+                bufferedLength += chunk.byteLength;
+            }
+        }
+        catch (error) {
+            console.warn('[Client][CHANNEL] Failed reading incoming channel envelope prefix', {
+                remoteNodeId,
+                error,
+            });
+            reader.releaseLock();
+            return { stream, channel: null };
+        }
+        const buffered = this.concatBytes(chunks);
+        if (buffered.byteLength < Client.CHANNEL_ENVELOPE_HEADER_BYTES ||
+            buffered[0] !== Client.CHANNEL_ENVELOPE_MAGIC ||
+            buffered[1] !== Client.CHANNEL_ENVELOPE_VERSION) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, buffered));
+            return { stream: rebuilt, channel: null };
+        }
+        const view = new DataView(buffered.buffer, buffered.byteOffset, buffered.byteLength);
+        const channelLength = view.getUint16(2, false);
+        const metadataLength = view.getUint16(4, false);
+        const totalEnvelopeBytes = Client.CHANNEL_ENVELOPE_HEADER_BYTES + channelLength + metadataLength;
+        let extendedBuffered = buffered;
+        if (extendedBuffered.byteLength < totalEnvelopeBytes) {
+            try {
+                while (extendedBuffered.byteLength < totalEnvelopeBytes) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    if (!value || value.byteLength === 0) {
+                        continue;
+                    }
+                    extendedBuffered = this.concatBytes([extendedBuffered, new Uint8Array(value)]);
+                }
+            }
+            catch (error) {
+                console.warn('[Client][CHANNEL] Failed extending incoming channel envelope read', {
+                    remoteNodeId,
+                    error,
+                });
+            }
+        }
+        if (extendedBuffered.byteLength < totalEnvelopeBytes || channelLength === 0) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, extendedBuffered));
+            return { stream: rebuilt, channel: null };
+        }
+        const channelStart = Client.CHANNEL_ENVELOPE_HEADER_BYTES;
+        const channelEnd = channelStart + channelLength;
+        const metadataEnd = channelEnd + metadataLength;
+        const decoder = new TextDecoder();
+        const channelId = decoder.decode(extendedBuffered.slice(channelStart, channelEnd)).trim();
+        let metadata = null;
+        if (metadataLength > 0) {
+            try {
+                const parsed = JSON.parse(decoder.decode(extendedBuffered.slice(channelEnd, metadataEnd)));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    metadata = parsed;
+                }
+            }
+            catch (error) {
+                console.warn('[Client][CHANNEL] Failed to parse incoming channel metadata', {
+                    remoteNodeId,
+                    channelId,
+                    error,
+                });
+            }
+        }
+        if (!channelId) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, extendedBuffered));
+            return { stream: rebuilt, channel: null };
+        }
+        const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, extendedBuffered.slice(totalEnvelopeBytes)));
+        return {
+            stream: rebuilt,
+            channel: {
+                channelId,
+                metadata,
+            },
+        };
+    }
+    isBiStreamLike(stream) {
+        try {
+            const candidate = stream;
+            return !!candidate
+                && !!candidate.send
+                && typeof candidate.send.getWriter === 'function'
+                && !!candidate.recv
+                && typeof candidate.recv.getReader === 'function';
+        }
+        catch {
+            return false;
+        }
+    }
+    materializeIncomingBiStream(stream, fallbackEndpointId) {
+        const candidate = stream;
+        if (!candidate) {
+            return null;
+        }
+        try {
+            const send = candidate.send;
+            const recv = candidate.recv;
+            if (!send || typeof send.getWriter !== 'function') {
+                return null;
+            }
+            if (!recv || typeof recv.getReader !== 'function') {
+                return null;
+            }
+            const endpointId = typeof candidate.endpoint_id === 'string' && candidate.endpoint_id.trim().length > 0
+                ? candidate.endpoint_id
+                : fallbackEndpointId;
+            return {
+                send,
+                recv,
+                endpoint_id: endpointId,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    rebuildBiIncomingStream(stream, recv) {
+        return {
+            send: stream.send,
+            recv,
+            endpoint_id: typeof stream.endpoint_id === 'string' ? stream.endpoint_id : '',
+        };
+    }
+    async classifyBiIncomingStream(stream) {
+        if (!this.isBiStreamLike(stream)) {
+            return { stream, protocolHint: 'unknown' };
+        }
+        const reader = stream.recv.getReader();
+        let firstRead;
+        try {
+            firstRead = await reader.read();
+        }
+        catch {
+            reader.releaseLock();
+            return { stream, protocolHint: 'unknown' };
+        }
+        reader.releaseLock();
+        if (firstRead.done || !firstRead.value || firstRead.value.byteLength === 0) {
+            console.debug('[Client][INCOMING] classifyBiIncomingStream: empty read', {
+                done: firstRead.done,
+                hasValue: !!firstRead.value,
+                byteLength: firstRead.value?.byteLength,
+            });
+            return { stream, protocolHint: 'unknown' };
+        }
+        const firstChunk = new Uint8Array(firstRead.value);
+        const firstByte = firstChunk[0];
+        console.debug('[Client][INCOMING] classifyBiIncomingStream: first byte', {
+            firstByte: '0x' + firstByte.toString(16),
+            EXPLICIT_PROTOCOL_BYTE: '0x' + Client.EXPLICIT_PROTOCOL_BYTE.toString(16),
+            isExplicit: firstByte === Client.EXPLICIT_PROTOCOL_BYTE,
+            chunkLength: firstChunk.length,
+        });
+        const rebuilt = this.rebuildBiIncomingStream(stream, this.prependChunkToReadable(stream.recv, firstChunk));
+        if (firstByte === Client.EXPLICIT_PROTOCOL_BYTE) {
+            return { stream: rebuilt, protocolHint: 'explicit' };
+        }
+        return { stream: rebuilt, protocolHint: 'control' };
+    }
+    async detectNativeMainStream(stream, remoteNodeId) {
+        if (!this.isBiStreamLike(stream)) {
+            return { handled: false, stream, protocolHint: 'unknown' };
+        }
+        const reader = stream.recv.getReader();
+        const chunks = [];
+        let bufferedLength = 0;
+        const requiredPrefixBytes = 1 + 4;
+        let reachedEof = false;
+        try {
+            while (bufferedLength < requiredPrefixBytes) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    reachedEof = true;
+                    break;
+                }
+                if (!value || value.byteLength === 0) {
+                    continue;
+                }
+                chunks.push(new Uint8Array(value));
+                bufferedLength += value.byteLength;
+            }
+        }
+        catch (error) {
+            console.warn('[Client][NATIVE-MAIN] Failed reading incoming prefix', {
+                remoteNodeId,
+                error,
+            });
+            reader.releaseLock();
+            return { handled: false, stream, protocolHint: 'control' };
+        }
+        const buffered = this.concatBytes(chunks);
+        if (buffered.byteLength < requiredPrefixBytes || buffered[0] !== Client.NATIVE_MAIN_PROTOCOL_BYTE) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, buffered));
+            return {
+                handled: false,
+                stream: rebuilt,
+                protocolHint: buffered[0] === Client.EXPLICIT_PROTOCOL_BYTE ? 'explicit' : 'control',
+            };
+        }
+        const labelLen = new DataView(buffered.buffer, buffered.byteOffset, buffered.byteLength).getUint32(1, false);
+        if (labelLen === 0 || labelLen > Client.NATIVE_MAIN_MAX_LABEL_BYTES) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, buffered));
+            return { handled: false, stream: rebuilt, protocolHint: 'control' };
+        }
+        const totalPrefixBytes = 1 + 4 + labelLen;
+        let extendedBuffered = buffered;
+        if (extendedBuffered.byteLength < totalPrefixBytes && !reachedEof) {
+            const extraChunks = [extendedBuffered];
+            let currentLength = extendedBuffered.byteLength;
+            try {
+                while (currentLength < totalPrefixBytes) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        reachedEof = true;
+                        break;
+                    }
+                    if (!value || value.byteLength === 0) {
+                        continue;
+                    }
+                    const chunk = new Uint8Array(value);
+                    extraChunks.push(chunk);
+                    currentLength += chunk.byteLength;
+                }
+            }
+            catch (error) {
+                console.warn('[Client][NATIVE-MAIN] Failed extending prefix read', {
+                    remoteNodeId,
+                    error,
+                });
+            }
+            extendedBuffered = this.concatBytes(extraChunks);
+        }
+        if (extendedBuffered.byteLength < totalPrefixBytes) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, extendedBuffered));
+            return { handled: false, stream: rebuilt, protocolHint: 'control' };
+        }
+        const labelBytes = extendedBuffered.slice(5, totalPrefixBytes);
+        const label = new TextDecoder().decode(labelBytes);
+        if (label !== Client.NATIVE_MAIN_LABEL) {
+            const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, extendedBuffered));
+            return { handled: false, stream: rebuilt, protocolHint: 'control' };
+        }
+        const remainder = extendedBuffered.slice(totalPrefixBytes);
+        const rebuilt = this.rebuildBiIncomingStream(stream, this.prependBytesToReader(reader, remainder));
+        openRtcDebugInfo('[Client][NATIVE-MAIN] Detected desktop native main stream', {
+            remoteNodeId,
+            label,
+        });
+        return {
+            handled: true,
+            stream: rebuilt,
+            protocolHint: 'native-main',
+        };
+    }
+    async resolveLocalHandshakePayload() {
+        const localDeviceId = (await this.getLocalDeviceId().catch(() => null)) ||
+            this.deviceId ||
+            this.options.localDeviceId;
+        if (!localDeviceId) {
+            throw new Error('Local device id unavailable for native handshake response');
+        }
+        return {
+            deviceId: localDeviceId,
+            deviceName: this.options.deviceName || 'Browser Device',
+            platformType: 'web',
+            capabilities: {
+                canHost: false,
+                canSync: true,
+                readOnly: false,
+            },
+            protocolVersion: Client.NATIVE_MAIN_PROTOCOL_VERSION,
+            timestamp: Date.now(),
+        };
+    }
+    getDeterministicConnectionId(remoteNodeId) {
+        if (!this.localNodeId) {
+            return `native-main-${remoteNodeId}`;
+        }
+        return this.localNodeId <= remoteNodeId
+            ? `${this.localNodeId}-${remoteNodeId}`
+            : `${remoteNodeId}-${this.localNodeId}`;
+    }
+    getNativeMainConnectionId(remoteNodeId) {
+        return this.getDeterministicConnectionId(remoteNodeId);
+    }
+    hasRustPeerLifecycleProjection() {
+        if (this.signaling && typeof this.signaling.supportsRustPeerLifecycleProjection === 'function'
+            && this.signaling.supportsRustPeerLifecycleProjection()) {
+            return true;
+        }
+        return !!(this.wasmClient &&
+            (typeof this.wasmClient.peer_sessions === 'function'
+                || typeof this.wasmClient.peer_snapshots === 'function'));
+    }
+    shouldProjectNativeMainLifecycle() {
+        return !this.hasRustPeerLifecycleProjection();
+    }
+    emitNativeMainConnectionState(remoteNodeId, state, deviceId) {
+        if (!this.shouldProjectNativeMainLifecycle()) {
+            return;
+        }
+        const connectionId = this.getNativeMainConnectionId(remoteNodeId);
+        const previous = this.peerLifecycle && typeof this.peerLifecycle.get === 'function'
+            ? this.peerLifecycle.get(connectionId)
+            : undefined;
+        const next = {
+            connectionId,
+            deviceId,
+            remoteNodeId,
+            state,
+            transportState: state === 'connected' ? 'connected' : 'closed',
+            protocolState: state === 'connected' ? 'routable' : 'closed',
+            routable: state === 'connected',
+            updatedAt: Date.now(),
+        };
+        const unchanged = previous
+            && previous.status === next.state
+            && previous.deviceId === next.deviceId
+            && previous.nodeId === next.remoteNodeId
+            && previous.transportState === next.transportState
+            && previous.protocolState === next.protocolState
+            && previous.routable === next.routable;
+        this.peerLifecycle.upsert({
+            deviceId: next.deviceId,
+            nodeId: next.remoteNodeId,
+            connectionId: next.connectionId,
+            status: next.state === 'connected' ? 'connected' : 'closed',
+            health: next.state === 'connected' ? 'healthy' : 'stale',
+            transportState: next.transportState,
+            protocolState: next.protocolState,
+            routable: next.routable,
+            lastSeenAt: next.updatedAt,
+        });
+        if (unchanged || typeof window === 'undefined') {
+            return;
+        }
+        window.dispatchEvent(new CustomEvent(Client.CONNECTION_STATE_CHANGED_EVENT, {
+            detail: {
+                connectionId: next.connectionId,
+                deviceId: next.deviceId ?? null,
+                remoteNodeId: next.remoteNodeId,
+                state: next.state,
+                transportState: next.transportState,
+                protocolState: next.protocolState,
+                routable: next.routable,
+                updatedAt: next.updatedAt,
+            },
+        }));
+    }
+    applyBackendConnectionState(state) {
+        if (!state?.connectionId) {
+            return;
+        }
+        if (!state.deviceId && !state.deviceIdHint && !state.remoteNodeId) {
+            // Raw connection-state events can arrive before Rust has resolved the
+            // authoritative peer identity. Keep those events diagnostic-only
+            // until the runtime exposes at least one stable identifier.
+            return;
+        }
+        openRtcDebug('[Client] applyBackendConnectionState', {
+            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,
+            updatedAt: state.updatedAt ?? null,
+            error: state.error ?? null,
+        });
+        const trustProjection = this.getConnectionTrustProjection({
+            connectionId: state.connectionId,
+            deviceId: state.deviceId ?? undefined,
+            deviceIdHint: state.deviceIdHint ?? undefined,
+            nodeId: state.remoteNodeId ?? undefined,
+        });
+        const effectiveRoutable = trustProjection ? trustProjection.routable : state.routable;
+        const effectiveProtocolState = trustProjection?.protocolState ?? state.protocolState;
+        const effectiveError = trustProjection?.error ?? state.error;
+        const effectiveHealth = trustProjection?.health
+            ?? (state.routable || state.readinessState === 'routable'
+                ? 'healthy'
+                : state.state === 'failed' || state.state === 'closed'
+                    ? 'stale'
+                    : 'unknown');
+        this.peerLifecycle.upsert({
+            deviceId: (trustProjection?.deviceId ?? state.deviceId) ?? undefined,
+            deviceIdHint: state.deviceIdHint ?? undefined,
+            nodeId: state.remoteNodeId ?? undefined,
+            connectionId: state.connectionId,
+            status: state.state === 'connected'
+                ? 'connected'
+                : state.state === 'connecting' || state.state === 'new'
+                    ? 'connecting'
+                    : state.state === 'failed'
+                        ? 'failed'
+                        : state.state === 'closed'
+                            ? 'closed'
+                            : 'disconnected',
+            health: effectiveHealth,
+            transportState: state.transportState,
+            protocolState: effectiveProtocolState,
+            routable: effectiveRoutable,
+            error: effectiveError,
+            lastSeenAt: state.updatedAt ?? Date.now(),
+        });
+    }
+    encodeNativeMainFrame(message) {
+        const payload = new TextEncoder().encode(JSON.stringify(message));
+        const labelBytes = new TextEncoder().encode(Client.NATIVE_MAIN_LABEL);
+        const envelope = new Uint8Array(1 + 4 + labelBytes.byteLength + 4 + payload.byteLength);
+        const view = new DataView(envelope.buffer);
+        let offset = 0;
+        envelope[offset] = Client.NATIVE_MAIN_PROTOCOL_BYTE;
+        offset += 1;
+        view.setUint32(offset, labelBytes.byteLength, false);
+        offset += 4;
+        envelope.set(labelBytes, offset);
+        offset += labelBytes.byteLength;
+        view.setUint32(offset, payload.byteLength, false);
+        offset += 4;
+        envelope.set(payload, offset);
+        return envelope;
+    }
+    async writeNativeMainMessage(writer, message) {
+        await writer.write(this.encodeNativeMainFrame(message));
+    }
+    async handleNativeHandshakeRequest(writer, remoteNodeId, request) {
+        const localPayload = await this.resolveLocalHandshakePayload();
+        const remoteDeviceId = request.payload && typeof request.payload.deviceId === 'string'
+            ? request.payload.deviceId
+            : undefined;
+        const response = {
+            channel: 'handshake',
+            action: 'response',
+            requestId: request.requestId,
+            payload: {
+                accepted: true,
+                ...localPayload,
+            },
+            timestamp: Date.now(),
+        };
+        await this.writeNativeMainMessage(writer, response);
+        this.emitNativeMainConnectionState(remoteNodeId, 'connected', remoteDeviceId);
+        openRtcDebugInfo('[Client][NATIVE-MAIN] Responded to desktop handshake', {
+            remoteNodeId,
+            requestId: request.requestId ?? null,
+            localDeviceId: localPayload.deviceId,
+        });
+    }
+    async handleNativeSessionTokenRequest(writer, remoteNodeId, request) {
+        const token = request.payload && typeof request.payload.token === 'string'
+            ? request.payload.token.trim()
+            : '';
+        const connectionId = this.getNativeMainConnectionId(remoteNodeId);
+        const result = await this.validateIncomingSessionToken(token, connectionId);
+        const response = result.ok
+            ? {
+                channel: 'session-token',
+                action: 'response',
+                requestId: request.requestId,
+                payload: {
+                    approved: true,
+                    scope: result.scope ?? null,
+                    connectionId,
+                },
+                timestamp: Date.now(),
+            }
+            : {
+                channel: 'session-token',
+                action: 'response',
+                requestId: request.requestId,
+                payload: {
+                    approved: false,
+                    reason: result.reason ?? 'session-token-rejected',
+                    connectionId,
+                },
+                timestamp: Date.now(),
+            };
+        await this.writeNativeMainMessage(writer, response);
+        if (result.ok) {
+            console.info('[Client][AUTH] host approved managed session token', {
+                remoteNodeId,
+                connectionId,
+                scope: result.scope ?? null,
+            });
+            return;
+        }
+        console.warn('[Client][AUTH] host rejected managed session token', {
+            remoteNodeId,
+            connectionId,
+            reason: result.reason ?? 'session-token-rejected',
+            hasToken: token.length > 0,
+        });
+    }
+    async handleNativeMainStream(stream, remoteNodeId) {
+        if (!this.isBiStreamLike(stream)) {
+            return;
+        }
+        const reader = stream.recv.getReader();
+        const writer = stream.send.getWriter();
+        const chunks = [];
+        let buffered = new Uint8Array(0);
+        try {
+            while (true) {
+                while (buffered.byteLength < 4) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        if (this.shouldProjectNativeMainLifecycle()) {
+                            this.emitNativeMainConnectionState(remoteNodeId, 'closed');
+                        }
+                        else {
+                            void this.refreshPeerSnapshot().catch(() => { });
+                        }
+                        openRtcDebugInfo('[Client][NATIVE-MAIN] Remote closed native main stream', {
+                            remoteNodeId,
+                        });
+                        return;
+                    }
+                    if (value && value.byteLength > 0) {
+                        chunks.push(new Uint8Array(value));
+                        buffered = this.concatBytes(chunks);
+                    }
+                }
+                const view = new DataView(buffered.buffer, buffered.byteOffset, buffered.byteLength);
+                const messageLen = view.getUint32(0, false);
+                if (messageLen === 0) {
+                    buffered = buffered.slice(4);
+                    chunks.length = 0;
+                    if (buffered.byteLength > 0) {
+                        chunks.push(buffered);
+                    }
+                    continue;
+                }
+                while (buffered.byteLength < 4 + messageLen) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        if (this.shouldProjectNativeMainLifecycle()) {
+                            this.emitNativeMainConnectionState(remoteNodeId, 'closed');
+                        }
+                        else {
+                            void this.refreshPeerSnapshot().catch(() => { });
+                        }
+                        console.warn('[Client][NATIVE-MAIN] Native main stream ended mid-frame', {
+                            remoteNodeId,
+                            messageLen,
+                            bufferedBytes: buffered.byteLength,
+                        });
+                        return;
+                    }
+                    if (value && value.byteLength > 0) {
+                        chunks.length = 0;
+                        buffered = this.concatBytes([buffered, new Uint8Array(value)]);
+                    }
+                }
+                const payloadBytes = buffered.slice(4, 4 + messageLen);
+                buffered = buffered.slice(4 + messageLen);
+                chunks.length = 0;
+                if (buffered.byteLength > 0) {
+                    chunks.push(buffered);
+                }
+                let message;
+                try {
+                    message = JSON.parse(new TextDecoder().decode(payloadBytes));
+                }
+                catch (error) {
+                    console.warn('[Client][NATIVE-MAIN] Failed to parse native main message', {
+                        remoteNodeId,
+                        error,
+                    });
+                    continue;
+                }
+                openRtcDebugInfo('[Client][NATIVE-MAIN] Received native main message', {
+                    remoteNodeId,
+                    channel: message.channel,
+                    action: message.action,
+                    requestId: message.requestId ?? null,
+                });
+                if (message.channel === 'handshake' && message.action === 'request') {
+                    await this.handleNativeHandshakeRequest(writer, remoteNodeId, message);
+                    continue;
+                }
+                if (message.channel === 'session-token' && message.action === 'request') {
+                    await this.handleNativeSessionTokenRequest(writer, remoteNodeId, message);
+                }
+            }
+        }
+        catch (error) {
+            if (this.shouldProjectNativeMainLifecycle()) {
+                this.emitNativeMainConnectionState(remoteNodeId, 'closed');
+            }
+            else {
+                void this.refreshPeerSnapshot().catch(() => { });
+            }
+            console.error('[Client][NATIVE-MAIN] Native main stream handler failed', {
+                remoteNodeId,
+                error,
+            });
+        }
+        finally {
+            writer.releaseLock();
+            reader.releaseLock();
+        }
+    }
+    async isCoreConnectionHealthy(remoteNodeId) {
+        if (!remoteNodeId)
+            return false;
+        if (this.wasmClient && typeof this.wasmClient.is_connected === 'function') {
+            try {
+                return !!(await this.wasmClient.is_connected(remoteNodeId));
+            }
+            catch {
+                // fall through
+            }
+        }
+        try {
+            return await this.signaling.isConnected(remoteNodeId);
+        }
+        catch {
+            return false;
+        }
+    }
+    async waitForStableConnection(connection) {
+        const trustState = this.initializeConnectionTrust(connection);
+        if (this.wasmClient && typeof this.wasmClient.wait_for_settled_peer === 'function') {
+            try {
+                const settled = await this.wasmClient.wait_for_settled_peer(connection.deviceId, Client.CONNECTION_STABLE_TIMEOUT_MS);
+                if (settled?.settledReady && (!trustState.required || trustState.verified)) {
+                    return true;
+                }
+                if (trustState.required && trustState.failed) {
+                    return false;
+                }
+                if (!this.usesTicketOnlySignalingMode()) {
+                    return false;
+                }
+            }
+            catch {
+                // Fall back to the legacy transport-only stability gate below.
+            }
+        }
+        const startedAt = Date.now();
+        let stableSince = null;
+        while (Date.now() - startedAt < Client.CONNECTION_STABLE_TIMEOUT_MS) {
+            if (connection.isClosed)
+                return false;
+            if (trustState.required && trustState.failed) {
+                return false;
+            }
+            const healthy = await this.isCoreConnectionHealthy(connection.deviceId);
+            if (healthy) {
+                if (stableSince === null)
+                    stableSince = Date.now();
+                if (Date.now() - stableSince >= Client.CONNECTION_STABLE_WINDOW_MS
+                    && (!trustState.required || trustState.verified)) {
+                    return true;
+                }
+            }
+            else {
+                stableSince = null;
+            }
+            await new Promise((resolve) => setTimeout(resolve, Client.CONNECTION_STABLE_POLL_MS));
+        }
+        return false;
+    }
+    announceConnectionWhenStable(connection) {
+        void (async () => {
+            const stable = await this.waitForStableConnection(connection);
+            if (!stable) {
+                if (!connection.isClosed) {
+                    console.warn(`[Client] Suppressing unstable connection ${connection.id}`);
+                }
+                const trustState = this.connectionTrustStates.get(connection.id);
+                if (trustState?.required && !connection.isClosed) {
+                    await this.enforceConnectionTrustFailure(connection, trustState.failureReason ?? 'trusted-device-proof-timeout').catch(() => undefined);
+                }
+                return;
+            }
+            if (this.announcedConnections.has(connection.id))
+                return;
+            this.announcedConnections.add(connection.id);
+            this.connectionListeners.forEach((cb) => cb(connection));
+        })();
+    }
+    async normalizeIncomingStreamEvent(incoming, options) {
+        // Compatibility check: OLD behavior returned BiStream directly?
+        // New behavior returns { type, stream, endpointId }
+        // Normalize
+        let type = 'bi';
+        let stream = incoming;
+        let endpointId = '';
+        let channel = null;
+        if ('type' in incoming) {
+            // New structure
+            type = incoming.type;
+            stream = incoming.stream;
+            endpointId = incoming.endpointId;
+        }
+        else {
+            endpointId = incoming.endpoint_id ?? '';
+        }
+        console.debug('[Client][INCOMING] handleIncomingStream called', {
+            hasType: 'type' in incoming,
+            type,
+            endpointId,
+        });
+        let protocolHint = 'unknown';
+        if (type === 'bi') {
+            const materializedStream = this.materializeIncomingBiStream(stream, endpointId);
+            if (!materializedStream || !this.isBiStreamLike(materializedStream)) {
+                let hasSend = false;
+                let hasRecv = false;
+                try {
+                    hasSend = !!stream?.send;
+                }
+                catch { }
+                try {
+                    hasRecv = !!stream?.recv;
+                }
+                catch { }
+                console.error('[Client][INCOMING] Invalid bidirectional stream payload', {
+                    remoteNodeId: endpointId,
+                    hasSend,
+                    hasRecv,
+                });
+                return {
+                    type: 'bi',
+                    stream,
+                    remoteNodeId: endpointId,
+                    protocolHint: 'unknown',
+                    channel: null,
+                    invalid: true,
+                };
+            }
+            stream = materializedStream;
+            if (options?.inspectChannelEnvelope) {
+                const channelEnvelope = await this.extractIncomingChannelEnvelope(stream, endpointId);
+                stream = channelEnvelope.stream;
+                channel = channelEnvelope.channel;
+            }
+            const classified = await this.classifyBiIncomingStream(stream);
+            stream = classified.stream;
+            protocolHint = classified.protocolHint;
+            if (protocolHint !== 'explicit') {
+                const nativeMain = await this.detectNativeMainStream(stream, endpointId);
+                stream = nativeMain.stream;
+                if (nativeMain.protocolHint === 'native-main') {
+                    protocolHint = 'native-main';
+                }
+            }
+        }
+        return {
+            type: type,
+            stream,
+            remoteNodeId: endpointId,
+            protocolHint,
+            channel,
+        };
+    }
+    hasIncomingChannelListener(channelId) {
+        const normalizedChannelId = channelId.trim();
+        if (!normalizedChannelId) {
+            return false;
+        }
+        return (this.channelStreamListeners?.get(normalizedChannelId)?.size ?? 0) > 0;
+    }
+    hasAnyIncomingChannelListeners() {
+        if (!this.channelStreamListeners) {
+            return false;
+        }
+        for (const listeners of this.channelStreamListeners.values()) {
+            if (listeners.size > 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    dispatchIncomingChannelListeners(listenerEvent) {
+        const channelId = listenerEvent.channel?.channelId?.trim();
+        if (!channelId) {
+            return false;
+        }
+        const listeners = this.channelStreamListeners?.get(channelId);
+        if (!listeners) {
+            return false;
+        }
+        for (const callback of listeners) {
+            if (callback(listenerEvent) === true) {
+                return true;
+            }
+        }
+        return false;
+    }
+    dispatchIncomingGenericListeners(listenerEvent) {
+        let handled = false;
+        for (const callback of this.streamListeners ?? []) {
+            handled = callback(listenerEvent) === true || handled;
+        }
+        return handled;
+    }
+    async handleUnhandledIncomingStreamEvent(listenerEvent) {
+        const { type, stream, remoteNodeId, protocolHint } = listenerEvent;
+        if (listenerEvent.invalid) {
+            return;
+        }
+        if (type === 'uni') {
+            await this.cancelUnhandledIncomingUniStream(stream, remoteNodeId);
+            return;
+        }
+        if (type === 'bi' && protocolHint === 'native-main') {
+            openRtcDebugInfo('[Client][INCOMING] Handling native desktop main stream', {
+                remoteNodeId,
+            });
+            void this.handleNativeMainStream(stream, remoteNodeId).catch((error) => {
+                console.error('[Client][NATIVE-MAIN] Background handler crashed', {
+                    remoteNodeId,
+                    error,
+                });
+            });
+            return;
+        }
+        // Legacy Connection handling for FIRST Bidirectional Stream
+        // If we don't have a connection for this peer yet, create one using this stream.
+        // This assumes the first stream is the "main" signaling/control channel.
+        if (type === 'bi' && protocolHint !== 'explicit') {
+            const remoteId = remoteNodeId;
+            const connId = this.getDeterministicConnectionId(remoteId);
+            if (!this.connections.has(connId)) {
+                // New connection!
+                const biStream = stream;
+                if (!this.isBiStreamLike(biStream)) {
+                    console.error('[Client][INCOMING] Unable to construct connection from invalid bi stream', {
+                        remoteNodeId: remoteId,
+                    });
+                    return;
+                }
+                const connection = new Connection(connId, this.localNodeId, remoteId, biStream.send.getWriter(), biStream.recv.getReader(), {
+                    rtcConfig: this.getRTCConfig(),
+                    transportContext: {
+                        priorities: this.options.transportPriority || ['webrtc', 'moq', 'iroh'],
+                        disableIrohFallback: this.options.disableIrohFallback || false,
+                        isMoQReady: () => this.moqState === 'ready',
+                        sendMoQ: (data) => this.sendMoQData(remoteId, data)
+                    }
+                });
+                this.initializeConnectionTrust(connection, this.knownDeviceIdsByNodeId.get(remoteId) ?? null);
+                this.registerConnection(connection);
+                this.announceConnectionWhenStable(connection);
+                void this.sendTransportHandshake(connection, 'hello').catch((error) => {
+                    console.warn('[Client][TRUST] Failed to send incoming handshake', {
+                        connectionId: connection.id,
+                        remoteNodeId: connection.remoteNodeId,
+                        error,
+                    });
+                });
+            }
+        }
+    }
+    async handleIncomingStream(incoming) {
+        const listenerEvent = await this.normalizeIncomingStreamEvent(incoming, {
+            inspectChannelEnvelope: this.hasAnyIncomingChannelListeners(),
+        });
+        const handledByChannel = this.dispatchIncomingChannelListeners(listenerEvent);
+        if (handledByChannel) {
+            return;
+        }
+        const handledByGenericListeners = this.dispatchIncomingGenericListeners(listenerEvent);
+        if (handledByGenericListeners) {
+            return;
+        }
+        await this.handleUnhandledIncomingStreamEvent(listenerEvent);
+    }
+    registerConnection(conn) {
+        this.connections.set(conn.id, conn);
+        if (!this.hasRustPeerLifecycleProjection()) {
+            this.applyConnectionTrustProjection(conn);
+        }
+        else {
+            void this.refreshPeerSnapshot().catch(() => { });
+        }
+        conn.onMessage((msg) => {
+            void this.handleMessage(conn, msg);
+        });
+        conn.onDisconnect(() => {
+            this.connections.delete(conn.id);
+            this.connectionTrustStates.delete(conn.id);
+            this.connectionChannelIds.delete(conn.id);
+            // Reflect the transport close immediately so peer-state watchers do
+            // not remain stuck on a stale connected snapshot while the Rust
+            // projection catches up.
+            this.peerLifecycle.removeConnection(conn.id);
+            this.peerLifecycle.updateHealth(conn.id, 'stale', 'closed');
+            if (this.hasRustPeerLifecycleProjection()) {
+                void this.refreshPeerSnapshot().catch(() => { });
+            }
+            const announced = this.announcedConnections.delete(conn.id);
+            if (announced) {
+                this.disconnectionListeners.forEach(cb => cb(conn));
+            }
+        });
+    }
+    syncConnectionPeerLifecycle(conn) {
+        const promotionEligible = this.resolvePromotionEligibility({
+            connectionId: conn.id,
+            nodeId: conn.remoteNodeId,
+        });
+        const trustProjection = this.getConnectionTrustProjection({
+            connectionId: conn.id,
+            nodeId: conn.remoteNodeId,
+        });
+        if (trustProjection) {
+            this.peerLifecycle.upsert({
+                peerId: trustProjection.deviceId ?? undefined,
+                deviceId: trustProjection.deviceId ?? undefined,
+                deviceIdHint: trustProjection.deviceId ?? undefined,
+                nodeId: conn.deviceId,
+                connectionId: conn.id,
+                status: conn.isClosed ? 'closed' : 'connected',
+                health: trustProjection.health,
+                transportState: conn.isClosed ? 'closed' : 'connected',
+                protocolState: trustProjection.protocolState,
+                routable: trustProjection.routable,
+                promotionEligible,
+                error: trustProjection.error,
+                lastSeenAt: Date.now(),
+            });
+            return;
+        }
+        const existing = this.peerLifecycle.get(conn.id) ||
+            this.peerLifecycle
+                .list()
+                .find((peer) => peer.connectionIds.includes(conn.id) || peer.nodeId === conn.deviceId);
+        const peerId = existing?.peerId || existing?.deviceId || existing?.deviceIdHint;
+        const deviceId = existing?.deviceId;
+        const deviceIdHint = existing?.deviceIdHint;
+        // Do not synthesize a public peer identity from transport metadata.
+        if (!peerId && !deviceId && !deviceIdHint) {
+            return;
+        }
+        this.peerLifecycle.upsert({
+            peerId,
+            deviceId,
+            deviceIdHint,
+            nodeId: conn.deviceId,
+            connectionId: conn.id,
+            status: conn.isClosed ? 'closed' : 'connected',
+            health: conn.isClosed ? 'stale' : 'healthy',
+            promotionEligible,
+            lastSeenAt: Date.now(),
+        });
+    }
+    getPeerCandidates(id) {
+        const peer = this.peerLifecycle.get(id);
+        const candidates = new Set();
+        const values = [
+            id,
+            peer?.peerId,
+            peer?.deviceId,
+            peer?.nodeId,
+            peer?.connectionId,
+            ...(peer?.connectionIds ?? []),
+        ];
+        values.forEach((value) => {
+            if (!value)
+                return;
+            const normalized = value.trim().toLowerCase();
+            if (normalized) {
+                candidates.add(normalized);
+            }
+        });
+        return candidates;
+    }
+    // --- Listeners ---
+    async updatePresence(isOnline = true, ttlMs = 300000, metadata, ticketOverride) {
+        if (!this.wasmClient)
+            return;
+        const userId = this.currentUser?.id;
+        const isPersonalWithSpaceKey = (this.options.discoveryMode === undefined || this.options.discoveryMode === 'personal') &&
+            typeof this.options.spaceKey === 'string' &&
+            this.options.spaceKey.trim().length > 0;
+        if (!userId && !isPersonalWithSpaceKey)
+            return;
+        const nodeId = this.localNodeId;
+        if (!nodeId)
+            return;
+        const ticket = await this.resolvePresenceTicket(ticketOverride);
+        if (!ticket || !ticket.trim()) {
+            throw new Error('updatePresence requires a valid endpoint ticket');
+        }
+        const name = this.options.deviceName || "Browser Device";
+        // Merge deviceId into metadata if not present
+        let finalMetadata = metadata;
+        const currentDeviceId = (await this.getLocalDeviceId()) || this.deviceId;
+        if (!currentDeviceId) {
+            throw new Error('updatePresence requires a stable local device ID');
+        }
+        try {
+            const metaObj = metadata ? JSON.parse(metadata) : {};
+            if (!metaObj.deviceId) {
+                metaObj.deviceId = currentDeviceId;
+                finalMetadata = JSON.stringify(metaObj);
+            }
+        }
+        catch {
+            finalMetadata = JSON.stringify({
+                deviceId: currentDeviceId,
+                rawMetadata: metadata,
+            });
+        }
+        await this.signaling.updatePresence(nodeId, ticket, isOnline, ttlMs, finalMetadata);
+    }
+    onConnection(callback) {
+        this.connectionListeners.push(callback);
+        return () => {
+            this.connectionListeners = this.connectionListeners.filter((cb) => cb !== callback);
+        };
+    }
+    onDisconnection(callback) {
+        this.disconnectionListeners.push(callback);
+        return () => {
+            this.disconnectionListeners = this.disconnectionListeners.filter((cb) => cb !== callback);
+        };
+    }
+    onMessage(callback) {
+        this.messageListeners.push(callback);
+        return () => {
+            this.messageListeners = this.messageListeners.filter((cb) => cb !== callback);
+        };
+    }
+    // New: listen for raw headers
+    onIncomingStream(callback) {
+        this.streamListeners.push(callback);
+        return () => {
+            this.streamListeners = this.streamListeners.filter((cb) => cb !== callback);
+        };
+    }
+    registerChannel(descriptor) {
+        const channelId = descriptor.id.trim();
+        if (!channelId) {
+            throw new Error('Channel registration requires a non-empty channel id.');
+        }
+        this.registeredChannels.set(channelId, {
+            ...descriptor,
+            id: channelId,
+        });
+    }
+    unregisterChannel(channelId) {
+        const normalizedChannelId = channelId.trim();
+        if (!normalizedChannelId) {
+            return;
+        }
+        this.registeredChannels.delete(normalizedChannelId);
+        this.channelStreamListeners.delete(normalizedChannelId);
+    }
+    listChannels() {
+        return Array.from(this.registeredChannels.values());
+    }
+    onIncomingChannelStream(channelId, callback) {
+        const normalizedChannelId = channelId.trim();
+        if (!normalizedChannelId) {
+            throw new Error('Channel stream listener requires a non-empty channel id.');
+        }
+        const listeners = this.channelStreamListeners.get(normalizedChannelId) ?? new Set();
+        listeners.add(callback);
+        this.channelStreamListeners.set(normalizedChannelId, listeners);
+        return () => {
+            const existing = this.channelStreamListeners.get(normalizedChannelId);
+            if (!existing) {
+                return;
+            }
+            existing.delete(callback);
+            if (existing.size === 0) {
+                this.channelStreamListeners.delete(normalizedChannelId);
+            }
+        };
+    }
+    onRoomJoinRequest(callback) {
+        this.roomRequestListeners.push(callback);
+        return () => {
+            this.roomRequestListeners = this.roomRequestListeners.filter((cb) => cb !== callback);
+        };
+    }
+    // --- Signaling (for WebRTC Upgrade) ---
+    // Deprecated: Connection handles its own signaling via #pluto-signal messages.
+    // Keeping hooks if user wants to send custom signals (e.g. app specific)
+    // --- MoQ Data Strategy ---
+    async createMoQDataTracks() {
+        if (!this._moqSession || this._moqState !== 'ready')
+            return;
+        try {
+            // 1. Broadcast Track
+            await this._moqSession.publisher.createTrack(this.localNodeId, "data/broadcast");
+            openRtcDebugLog('[Client] MoQ Data Track created: data / broadcast');
+        }
+        catch (e) {
+            console.warn("Failed to create MoQ broadcast track", e);
+        }
+    }
+    /**
+     * Send data via MoQ.
+     * @param peerId Target Node ID (for 1:1) or null (for Broadcast)
+     * @param data Payload
+     */
+    async sendMoQData(peerId, data) {
+        if (this._moqState !== 'ready' || !this.moq)
+            throw new Error("MoQ not ready");
+        const trackName = peerId ? `data / ${peerId} ` : `data / broadcast`;
+        // Ensure track exists (create on demand for 1:1)
+        // Check if we are already publishing this track? 
+        // MoQPublisher.createTrack checks internally and returns existing if so.
+        // We'll trust createTrack's cache logic we added earlier.
+        const trackPub = await this.moq.publisher.createTrack(this.localNodeId, trackName);
+        if (!trackPub)
+            return; // Should not happen if logic works or tracks exist
+        // Push data (single object group)
+        // We need a timestamp?
+        const timestamp = Date.now();
+        await trackPub.push(data, { isKey: true, timestamp });
+        // Do NOT close track for 1:1, keep it open for session?
+        // Actually, if we keep opening tracks, we might hit limits?
+        // MoQPublisher caches tracks. It's fine.
+    }
+    async handleMessage(conn, msg) {
+        // Intercept Handshake to detect MoQ support
+        if (msg && typeof msg === 'object' && msg.type === 'handshake') {
+            const handshake = msg;
+            // Session grant gate: Rust/wasm validation decides whether the hello is allowed.
+            if (handshake.action === 'hello' || !handshake.action) {
+                const result = await this.validateIncomingSessionToken(handshake.sessionToken ?? '', conn.id);
+                if (!result.ok) {
+                    console.warn('[Client][SESSION-TOKEN] Rejecting connection — invalid session token', {
+                        connectionId: conn.id,
+                        remoteNodeId: conn.remoteNodeId,
+                        reason: result.reason,
+                        hasToken: !!handshake.sessionToken,
+                    });
+                    void conn.disconnect();
+                    return;
+                }
+            }
+            if (msg.moq && this.moqState === 'ready') {
+                openRtcDebugLog(`[Client] Peer ${conn.deviceId.substring(0, 6)} supports MoQ. Upgrading...`);
+                conn.peerMoQReady = true;
+                // Subscribe to Peer's tracks
+                if (this.moq) {
+                    const peerId = conn.deviceId;
+                    // Subscribe to their broadcast and DM track
+                    // Format: [PeerID]/data/broadcast and [PeerID]/data/[MyNodeID]
+                    this.moq.subscriber.subscribe(peerId, "data/broadcast");
+                    this.moq.subscriber.subscribe(peerId, `data / ${this.localNodeId} `);
+                }
+                // If we are Responder, we should reply with Handshake containing moq: true (if not already sent)
+                // But connect() sends it initially.
+                // If we received an inbound connection, we haven't sent Handshake yet!
+                // We should send a handshake reply on incoming connections?
+                // The current implementation of accept (handleIncomingStream -> Connection) doesn't auto-send handshake.
+                // We should probably reply.
+                // To avoid loops: assume if we initiated, we sent handshake.
+                // If we accepted, we respond.
+                // Or just always reply if we haven't?
+            }
+            // Assign channel from handshake if present
+            this.assignConnectionChannel(conn, handshake.channelId ?? null);
+            if (handshake.transportTrust || this.requiresManagedTransportTrust()) {
+                void (async () => {
+                    const action = handshake.action ?? 'hello';
+                    const payload = handshake.transportTrust ?? null;
+                    const trustState = this.initializeConnectionTrust(conn);
+                    if (payload?.deviceId
+                        && !trustState.expectedDeviceId
+                        && this.getKnownDevice(payload.deviceId, conn.remoteNodeId)) {
+                        trustState.expectedDeviceId = payload.deviceId;
+                    }
+                    if (action === 'hello') {
+                        const responseChallenge = typeof payload?.challenge === 'string' ? payload.challenge : null;
+                        if (!responseChallenge && trustState.required) {
+                            await this.enforceConnectionTrustFailure(conn, 'missing-transport-trust-challenge');
+                            return;
+                        }
+                        await this.sendTransportHandshake(conn, 'response', responseChallenge);
+                    }
+                    else if (action === 'response' || action === 'ack') {
+                        const verification = await this.verifyRemoteTransportTrust(conn, payload);
+                        if (!verification.verified) {
+                            if (trustState.required) {
+                                await this.enforceConnectionTrustFailure(conn, verification.reason ?? 'remote-transport-proof-invalid');
+                            }
+                            return;
+                        }
+                        this.markConnectionTrustVerified(conn, verification.deviceId);
+                        if (action === 'response' && typeof payload?.challenge === 'string') {
+                            await this.sendTransportHandshake(conn, 'ack', payload.challenge);
+                        }
+                    }
+                })().catch((error) => {
+                    console.warn('[Client][TRUST] Handshake processing failed', {
+                        connectionId: conn.id,
+                        remoteNodeId: conn.remoteNodeId,
+                        error,
+                    });
+                });
+            }
+            else if ((handshake.action === 'hello' || !handshake.action) && handshake.sessionToken) {
+                // Token-gated connection without transport trust (e.g. share session).
+                // Send a response handshake so the peer knows it was accepted.
+                void this.sendTransportHandshake(conn, 'response').catch((error) => {
+                    console.warn('[Client][SESSION-TOKEN] Failed to send response handshake', {
+                        connectionId: conn.id,
+                        error,
+                    });
+                });
+            }
+        }
+        // We no longer intercept #signal here, Connection does it before emitting message event.
+        this.messageListeners.forEach(cb => cb(conn, msg));
+    }
+    getRTCConfig() {
+        const config = this.options.transports?.webrtc || undefined;
+        // If strict mode is on, we might need to synthesize a config if it's missing?
+        // But usually transports are defined.
+        if (!config)
+            return undefined;
+        if (this.options.strictMode || config.privacyMode) {
+            return {
+                ...config,
+                iceTransportPolicy: 'relay'
+            };
+        }
+        return config;
+    }
+}
+Client.CHANNEL_ENVELOPE_MAGIC = 0x7f;
+Client.CHANNEL_ENVELOPE_VERSION = 0x01;
+Client.CHANNEL_ENVELOPE_HEADER_BYTES = 1 + 1 + 2 + 2;
+Client.EXPLICIT_PROTOCOL_BYTE = 0x02;
+Client.NATIVE_MAIN_PROTOCOL_BYTE = 0x00;
+Client.NATIVE_MAIN_LABEL = 'main';
+Client.NATIVE_MAIN_MAX_LABEL_BYTES = 64;
+Client.NATIVE_MAIN_PROTOCOL_VERSION = 1;
+Client.CONNECTION_STATE_CHANGED_EVENT = 'connection-state-changed';
+Client.INCOMING_STREAM_RETRY_MIN_DELAY_MS = 250;
+Client.INCOMING_STREAM_RETRY_MAX_DELAY_MS = 2000;
+Client.DEFAULT_PEER_CHANNEL_ID = 'system/peer-default';
+Client.SHARE_FILE_CHANNEL_ID = 'share/explicit-file';
+Client.SHARE_CONTROL_CHANNEL_ID = 'share/explicit-control';
+Client.incomingStreamHubs = new WeakMap();
+Client.CONNECTION_STABLE_WINDOW_MS = 600;
+Client.CONNECTION_STABLE_TIMEOUT_MS = 2000;
+Client.CONNECTION_STABLE_POLL_MS = 120;