openrtc 0.1.0

package/dist/runtime/RuntimeClient.js

@@ -0,0 +1,1484 @@
+import { Client } from '../core/Client';
+import { resolveStorageNamespace } from '../core/config';
+import { openRtcDebugInfo } from '../utils/debug';
+/**
+ * RuntimeClient is the primary application-facing API.
+ * It owns host/runtime orchestration on top of the Rust core and should be the
+ * only high-level surface consumed by product code. App code should not rebuild
+ * lifecycle, discovery, or transfer-readiness policy above this layer.
+ *
+ * Allowed:
+ * - app-facing session startup/shutdown
+ * - typed device, peer, room, and transfer APIs
+ * - thin host/runtime coordination
+ *
+ * Not allowed:
+ * - teaching app code to depend on `advanced.unwrap*()`
+ * - treating `nodeId` as high-level peer identity
+ * - reimplementing Rust-owned lifecycle policy in product code
+ *
+ * Source of truth:
+ * - Rust core owns discovery, peer identity, presence, and transport lifecycle
+ * - RuntimeClient should converge toward thin wrappers over those core surfaces
+ */
+export class RuntimeClient {
+    constructor(options, backend) {
+        this.managedSessionKey = null;
+        this.managedSessionUserId = null;
+        this.managedSessionOptions = null;
+        this.apiKey = options.apiKey;
+        this.storageNamespace = resolveStorageNamespace({
+            apiKey: options.apiKey,
+            storagePrefix: options.storagePrefix,
+        });
+        this.client = new Client(options);
+        this.backend = backend ?? null;
+        if (backend) {
+            this.client.setSignalingBackend(backend);
+        }
+    }
+    get identity() {
+        return this.client.currentUser;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async fetchAndApplyAppLimits() {
+        try {
+            await this.client.refreshHostedAppSettings();
+        }
+        catch (e) {
+            console.warn('[pluto-rtc] Could not fetch app limits, using free-tier defaults.', e);
+        }
+    }
+    normalizeUiConnectionStatus(status) {
+        switch ((status || 'disconnected').trim().toLowerCase()) {
+            case 'connected':
+                return 'connected';
+            case 'connecting':
+                return 'connecting';
+            case 'failed':
+                return 'failed';
+            case 'closed':
+            case 'disconnected':
+            case 'online':
+            default:
+                return 'disconnected';
+        }
+    }
+    managedUserDeviceStorageKey(userId) {
+        return [
+            RuntimeClient.MANAGED_USER_DEVICE_STORAGE_KEY_PREFIX,
+            this.storageNamespace,
+            (userId || 'anonymous').trim() || 'anonymous',
+        ].join(':');
+    }
+    static encodeManagedCompoundTicket(irohTicket, grant) {
+        const payload = btoa(JSON.stringify({
+            t: grant.token,
+            s: grant.scope,
+            m: grant.maxConnections,
+        }))
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/g, '');
+        return `${irohTicket}.${payload}`;
+    }
+    decodeManagedUserDeviceGrantFromTicket(ticket) {
+        const trimmed = ticket?.trim() || '';
+        if (!trimmed) {
+            return null;
+        }
+        const dotIndex = trimmed.lastIndexOf('.');
+        if (dotIndex < 0) {
+            return null;
+        }
+        try {
+            const suffix = trimmed.slice(dotIndex + 1).replace(/-/g, '+').replace(/_/g, '/');
+            const padding = (4 - (suffix.length % 4)) % 4;
+            const decoded = JSON.parse(atob(suffix + '='.repeat(padding)));
+            if (typeof decoded?.t !== 'string' ||
+                typeof decoded?.s !== 'string' ||
+                decoded.s.trim() !== RuntimeClient.MANAGED_USER_DEVICE_SCOPE) {
+                return null;
+            }
+            return {
+                scope: decoded.s,
+                token: decoded.t,
+                maxConnections: typeof decoded.m === 'number' ? decoded.m : 0,
+                savedAtMs: Date.now(),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    loadPersistedManagedUserDeviceGrant(userId) {
+        if (typeof localStorage === 'undefined') {
+            return null;
+        }
+        const storageKey = this.managedUserDeviceStorageKey(userId);
+        try {
+            const raw = localStorage.getItem(storageKey);
+            if (!raw) {
+                return null;
+            }
+            const parsed = JSON.parse(raw);
+            if (typeof parsed?.token !== 'string' ||
+                typeof parsed?.scope !== 'string' ||
+                parsed.scope.trim() !== RuntimeClient.MANAGED_USER_DEVICE_SCOPE) {
+                localStorage.removeItem(storageKey);
+                return null;
+            }
+            return {
+                scope: parsed.scope,
+                token: parsed.token,
+                maxConnections: typeof parsed.maxConnections === 'number' ? parsed.maxConnections : 0,
+                savedAtMs: typeof parsed.savedAtMs === 'number' ? parsed.savedAtMs : 0,
+            };
+        }
+        catch (error) {
+            console.warn('[RuntimeClient][managed-ticket][restore] failed parsing stored grant', {
+                storageKey,
+                error,
+            });
+            return null;
+        }
+    }
+    persistManagedUserDeviceGrant(userId, grant) {
+        if (typeof localStorage === 'undefined') {
+            return;
+        }
+        const storageKey = this.managedUserDeviceStorageKey(userId);
+        try {
+            localStorage.setItem(storageKey, JSON.stringify({
+                ...grant,
+                savedAtMs: Date.now(),
+            }));
+            console.info('[RuntimeClient][managed-ticket][persist]', {
+                storageKey,
+                scope: grant.scope,
+            });
+        }
+        catch (error) {
+            console.warn('[RuntimeClient][managed-ticket][persist] failed', {
+                storageKey,
+                error,
+            });
+        }
+    }
+    persistManagedUserDeviceGrantFromTicket(userId, ticket) {
+        const grant = this.decodeManagedUserDeviceGrantFromTicket(ticket);
+        if (!grant) {
+            return;
+        }
+        this.persistManagedUserDeviceGrant(userId, grant);
+    }
+    clearPersistedManagedUserDeviceGrant(userId) {
+        if (typeof localStorage === 'undefined') {
+            return;
+        }
+        const storageKey = this.managedUserDeviceStorageKey(userId);
+        try {
+            localStorage.removeItem(storageKey);
+            console.info('[RuntimeClient][managed-ticket][clear]', {
+                storageKey,
+                scope: RuntimeClient.MANAGED_USER_DEVICE_SCOPE,
+            });
+        }
+        catch (error) {
+            console.warn('[RuntimeClient][managed-ticket][clear] failed', {
+                storageKey,
+                error,
+            });
+        }
+    }
+    async resolvePeerStreamTarget(id) {
+        const peer = this.getPeerState(id) ?? null;
+        const session = await this.getPeerSession(id).catch(() => null);
+        const activeConnectionId = session?.activeConnectionId?.trim() || null;
+        const connection = (activeConnectionId
+            ? this.client.getConnections().find((candidate) => !candidate.isClosed && candidate.id === activeConnectionId)
+            : undefined) ?? null;
+        const remoteNodeId = session?.nodeId?.trim() ||
+            connection?.remoteNodeId?.trim() ||
+            peer?.nodeId?.trim() ||
+            null;
+        return { peer, session, connection, remoteNodeId };
+    }
+    compatPeerConnectionFromTarget(target, id) {
+        const connectionId = target.session?.activeConnectionId?.trim() || `peer-stream:${id}`;
+        const remoteNodeId = target.remoteNodeId || id;
+        return {
+            id: connectionId,
+            deviceId: remoteNodeId,
+            remoteNodeId,
+            isClosed: false,
+        };
+    }
+    deviceStatusSnapshotKey(devices) {
+        return JSON.stringify([...devices]
+            .map((device) => ({
+            deviceId: device.deviceId,
+            deviceName: device.deviceName ?? null,
+            online: !!device.online,
+            connectionStatus: device.connectionStatus ?? null,
+            settledReady: !!device.settledReady,
+            readinessState: device.readinessState ?? null,
+            readinessReason: device.readinessReason ?? null,
+            peerHealth: device.peerHealth ?? null,
+            peerId: device.peerId ?? null,
+            promotionEligible: device.promotionEligible ?? true,
+            connectionId: device.connectionId ?? null,
+            deviceIdHint: device.deviceIdHint ?? null,
+            nodeId: device.nodeId ?? null,
+            ticket: device.ticket ?? null,
+            activeTransportStableId: device.activeTransportStableId ?? null,
+            transportGeneration: device.transportGeneration ?? null,
+            scopes: [...(device.scopes ?? [])].sort(),
+        }))
+            .sort((left, right) => left.deviceId.localeCompare(right.deviceId)));
+    }
+    buildDeviceStatusLookup(items, readIdentity) {
+        const lookup = new Map();
+        const remember = (value, item) => {
+            const normalized = typeof value === 'string' ? value.trim() : '';
+            if (!normalized || lookup.has(normalized)) {
+                return;
+            }
+            lookup.set(normalized, item);
+        };
+        for (const item of items) {
+            for (const key of readIdentity(item)) {
+                remember(key, item);
+            }
+        }
+        return lookup;
+    }
+    overlayPeerSessionsOnDeviceSnapshots(devices, sessions) {
+        if (!sessions.length) {
+            return devices;
+        }
+        const sessionIndex = this.buildDeviceStatusLookup(sessions, (session) => [
+            session.peerId,
+            session.deviceId,
+            session.deviceIdHint,
+            session.nodeId,
+            session.activeConnectionId,
+        ]);
+        return devices.map((device) => {
+            const session = sessionIndex.get(device.deviceId) ??
+                sessionIndex.get(device.deviceIdHint ?? '') ??
+                sessionIndex.get(device.nodeId ?? '') ??
+                sessionIndex.get(device.connectionId ?? '') ??
+                sessionIndex.get(device.peerId ?? '');
+            if (!session) {
+                return device;
+            }
+            const promotionEligible = this.client.isPeerPromotionEligible({
+                connectionId: session.activeConnectionId ?? undefined,
+                deviceId: session.deviceId ?? undefined,
+                deviceIdHint: session.deviceIdHint ?? undefined,
+                nodeId: session.nodeId ?? undefined,
+            });
+            if (!promotionEligible) {
+                return device;
+            }
+            const status = session.status ?? device.connectionStatus;
+            return {
+                ...device,
+                connectionStatus: status,
+                settledReady: session.settledReady ?? device.settledReady ?? false,
+                readinessState: session.readinessState ??
+                    (session.settledReady ? 'routable' : device.readinessState),
+                readinessReason: session.readinessReason ??
+                    (session.settledReady ? 'peer-session-settled' : device.readinessReason),
+                peerHealth: session.health ?? device.peerHealth,
+                peerId: session.peerId ?? device.peerId,
+                promotionEligible,
+                scopes: session.scopes?.length ? [...session.scopes] : device.scopes,
+                connectionId: session.activeConnectionId ?? device.connectionId,
+                deviceIdHint: session.deviceIdHint ?? device.deviceIdHint,
+                activeTransportStableId: session.activeTransportStableId ?? device.activeTransportStableId,
+                transportGeneration: session.transportGeneration ?? device.transportGeneration,
+            };
+        });
+    }
+    overlayPeerStateOnDeviceSnapshots(devices, peers) {
+        if (!peers.length) {
+            return devices;
+        }
+        const peerIndex = this.buildDeviceStatusLookup(peers, (peer) => [
+            peer.peerId,
+            peer.deviceId,
+            peer.deviceIdHint,
+            peer.nodeId,
+            peer.connectionId,
+        ]);
+        return devices.map((device) => {
+            const peer = peerIndex.get(device.deviceId) ??
+                peerIndex.get(device.deviceIdHint ?? '') ??
+                peerIndex.get(device.nodeId ?? '') ??
+                peerIndex.get(device.connectionId ?? '') ??
+                peerIndex.get(device.peerId ?? '');
+            if (!peer) {
+                return device;
+            }
+            if (peer.promotionEligible === false) {
+                return device;
+            }
+            const status = peer.status ?? device.connectionStatus;
+            return {
+                ...device,
+                connectionStatus: status,
+                settledReady: peer.routable ?? device.settledReady ?? false,
+                readinessState: (peer.routable === false && peer.protocolState
+                    ? peer.protocolState
+                    : undefined)
+                    ?? device.readinessState
+                    ?? (peer.routable === true
+                        ? 'routable'
+                        : peer.status === 'connecting'
+                            ? 'connecting'
+                            : undefined),
+                readinessReason: (peer.routable === false && peer.error
+                    ? peer.error
+                    : undefined)
+                    ?? device.readinessReason
+                    ?? (peer.routable === true
+                        ? 'peer-projection-routable'
+                        : peer.status === 'connecting'
+                            ? 'peer-projection-connecting'
+                            : undefined),
+                peerHealth: peer.health ?? device.peerHealth,
+                peerId: peer.peerId ?? device.peerId,
+                promotionEligible: peer.promotionEligible ?? true,
+                connectionId: peer.connectionId ?? device.connectionId,
+                deviceIdHint: peer.deviceIdHint ?? device.deviceIdHint,
+                scopes: peer.scopes?.length ? [...peer.scopes] : device.scopes,
+            };
+        });
+    }
+    runtimeDeviceToStatusSnapshot(device) {
+        return {
+            ...device,
+            connectionStatus: device.online ? 'online' : 'disconnected',
+            settledReady: false,
+            peerHealth: 'unknown',
+            promotionEligible: true,
+            scopes: [],
+        };
+    }
+    uniqueLookupIds(...values) {
+        const seen = new Set();
+        const ordered = [];
+        for (const value of values) {
+            const normalized = typeof value === 'string' ? value.trim() : '';
+            if (!normalized || seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            ordered.push(normalized);
+        }
+        return ordered;
+    }
+    matchSessionByLookupId(sessions, lookupIds) {
+        if (!sessions.length || !lookupIds.length) {
+            return null;
+        }
+        const sessionIndex = this.buildDeviceStatusLookup(sessions, (session) => [
+            session.peerId,
+            session.deviceId,
+            session.deviceIdHint,
+            session.nodeId,
+            session.activeConnectionId,
+        ]);
+        for (const lookupId of lookupIds) {
+            const matched = sessionIndex.get(lookupId);
+            if (matched) {
+                return matched;
+            }
+        }
+        return null;
+    }
+    async resolvePeerLookupIds(id, backend) {
+        const resolvedIdentity = typeof backend.resolvePeerIdentity === 'function'
+            ? await backend.resolvePeerIdentity(id).catch(() => null)
+            : null;
+        const baseIds = this.uniqueLookupIds(id, resolvedIdentity?.peerId, resolvedIdentity?.deviceId, resolvedIdentity?.deviceIdHint, resolvedIdentity?.nodeId);
+        if (typeof backend.listPeerSessions !== 'function') {
+            return baseIds;
+        }
+        const matchedSession = this.matchSessionByLookupId(await backend.listPeerSessions().catch(() => []), baseIds);
+        return this.uniqueLookupIds(...baseIds, matchedSession?.peerId, matchedSession?.deviceId, matchedSession?.deviceIdHint, matchedSession?.nodeId, matchedSession?.activeConnectionId);
+    }
+    mergeWatchedDevicesIntoStatusSnapshots(watchedDevices, authoritativeDevices) {
+        if (!watchedDevices) {
+            return authoritativeDevices;
+        }
+        const authoritativeById = new Map(authoritativeDevices.map((device) => [device.deviceId, device]));
+        return watchedDevices.map((device) => {
+            const authoritative = authoritativeById.get(device.deviceId);
+            if (!authoritative) {
+                return this.runtimeDeviceToStatusSnapshot(device);
+            }
+            return {
+                ...authoritative,
+                ...device,
+                connectionStatus: authoritative.connectionStatus,
+                settledReady: authoritative.settledReady,
+                readinessState: authoritative.readinessState,
+                readinessReason: authoritative.readinessReason,
+                peerHealth: authoritative.peerHealth,
+                peerId: authoritative.peerId,
+                scopes: authoritative.scopes,
+                connectionId: authoritative.connectionId,
+                deviceIdHint: authoritative.deviceIdHint,
+                activeTransportStableId: authoritative.activeTransportStableId,
+                transportGeneration: authoritative.transportGeneration,
+            };
+        });
+    }
+    nextNativeStartRetryDelayMs(attempt) {
+        const backoff = RuntimeClient.NATIVE_START_RETRY_MIN_DELAY_MS * Math.pow(2, Math.max(0, attempt - 1));
+        return Math.min(RuntimeClient.NATIVE_START_RETRY_MAX_DELAY_MS, backoff);
+    }
+    hasManagedSession() {
+        return !!(this.managedSessionKey || this.managedSessionUserId);
+    }
+    startManagedReconciliation(task) {
+        if (!this.hasManagedSession()) {
+            return () => undefined;
+        }
+        const timer = setInterval(() => {
+            if (!this.hasManagedSession()) {
+                return;
+            }
+            task();
+        }, RuntimeClient.MANAGED_RECONCILIATION_INTERVAL_MS);
+        return () => clearInterval(timer);
+    }
+    connectionStateSnapshotKey(state) {
+        return JSON.stringify({
+            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,
+            readinessState: state.readinessState ?? null,
+            readinessReason: state.readinessReason ?? null,
+            transportGeneration: state.transportGeneration ?? null,
+            replacementInProgress: state.replacementInProgress ?? null,
+            error: state.error ?? null,
+            updatedAt: state.updatedAt ?? null,
+        });
+    }
+    async runNativeStartLoop(options) {
+        const startedAt = Date.now();
+        let attempt = 0;
+        while (Date.now() - startedAt <= RuntimeClient.NATIVE_START_RETRY_WINDOW_MS) {
+            attempt += 1;
+            try {
+                await options.start();
+                if (attempt > 1) {
+                    openRtcDebugInfo(`[RuntimeClient] ${options.label} recovered after ${attempt} attempts`);
+                }
+                return;
+            }
+            catch (error) {
+                const delayMs = this.nextNativeStartRetryDelayMs(attempt);
+                console.warn(`[RuntimeClient] ${options.label} failed attempt=${attempt} retry_in_ms=${delayMs}:`, error);
+                await this.sleep(delayMs);
+            }
+        }
+        throw new Error(options.exhaustedMessage);
+    }
+    onIdentityChange(callback) {
+        return this.client.onAuthChange(callback);
+    }
+    async signInAnonymously() {
+        await this.client.signInAnonymously();
+    }
+    async signInWithPluto() {
+        await this.client.signInWithPluto();
+    }
+    async setAuthContext(context) {
+        const backend = this.backend;
+        if (!backend || typeof backend.setAuthContext !== 'function') {
+            throw new Error('RuntimeClient auth context requires a runtime adapter that supports setAuthContext().');
+        }
+        await backend.setAuthContext(context);
+    }
+    async signOut() {
+        await this.stopManagedSession().catch(() => undefined);
+        await this.client.signOut();
+    }
+    async initialize() {
+        await this.client.init();
+    }
+    async getRuntimeStatus() {
+        return this.client.getRuntimeStatus();
+    }
+    async start(options) {
+        if (options?.clearSessionTokens !== false) {
+            await this.client.clearSessionTokens().catch(() => { });
+        }
+        await this.client.startListening();
+        // Subscribe to native iroh messages so the TS Client can run token
+        // validation for incoming native-host connections.
+        const nativeBackend = this.backend;
+        if (nativeBackend?.onIncomingNativeMessage) {
+            nativeBackend.onIncomingNativeMessage((connectionId, remoteNodeId, msg) => {
+                void (async () => {
+                    const reject = await this.client.acceptNativeMessage(connectionId, remoteNodeId, msg);
+                    if (reject && nativeBackend.disconnectDevice) {
+                        nativeBackend.disconnectDevice(connectionId).catch(() => { });
+                    }
+                })();
+            }).catch(() => { });
+        }
+    }
+    stop() {
+        this.client.stopListening();
+    }
+    async getNodeId() {
+        return this.client.getNodeId();
+    }
+    async getNodeIdFromTicket(ticket) {
+        return this.client.getNodeIdFromTicket(ticket);
+    }
+    async getLocalDeviceId() {
+        return this.client.getLocalDeviceId();
+    }
+    async getLocalDeviceInfo() {
+        const backend = this.backend;
+        if (!backend || typeof backend.getLocalDeviceInfo !== 'function') {
+            return null;
+        }
+        return backend.getLocalDeviceInfo();
+    }
+    async getLocalDeviceProfile(options) {
+        const localInfo = await this.getLocalDeviceInfo().catch(() => null);
+        const localDeviceId = options?.localDeviceId ??
+            localInfo?.deviceId ??
+            (await this.getLocalDeviceId().catch(() => null)) ??
+            null;
+        const runtimeStatus = await this.getRuntimeStatus().catch(() => ({
+            runtime: 'unknown',
+            wasmLoaded: false,
+            localNodeId: undefined,
+            userId: undefined,
+        }));
+        const platform = options?.platform ??
+            (runtimeStatus.runtime === 'tauri' ? 'native' : 'web');
+        return {
+            deviceId: localDeviceId,
+            deviceName: options?.deviceName || localInfo?.deviceName || 'Unknown Device',
+            platformType: localInfo?.platformType || (platform === 'native' ? 'desktop' : 'web'),
+            userId: options?.userId ?? this.identity?.id ?? runtimeStatus.userId ?? null,
+            capabilities: localInfo?.capabilities ?? {
+                can_host: platform === 'native',
+                can_sync: platform === 'native',
+                read_only: platform !== 'native',
+            },
+            lastSeenAt: localInfo?.lastSeenAt || new Date().toISOString(),
+            localNodeId: runtimeStatus.localNodeId || null,
+        };
+    }
+    async updateLocalDeviceName(deviceName) {
+        const backend = this.backend;
+        if (!backend || typeof backend.updateLocalDeviceName !== 'function') {
+            return null;
+        }
+        return backend.updateLocalDeviceName(deviceName);
+    }
+    async getManagedNodeId(options) {
+        const backend = this.backend;
+        if (!backend || typeof backend.getManagedNodeId !== 'function') {
+            return null;
+        }
+        return backend.getManagedNodeId(options);
+    }
+    async getTicket() {
+        return this.client.getTicket();
+    }
+    /**
+     * Generate a session-scoped endpoint ticket with an embedded random token.
+     * The token gates incoming connections: only clients that present the token
+     * in their handshake are accepted while the registry is non-empty.
+     *
+     * @param scope          Logical label for bulk-revoke (e.g. "share").
+     * @param maxConnections 0 = unlimited.
+     */
+    async getTicketWithToken(grantScope, maxConnections = 0) {
+        // On native (Tauri IPC), generate the compound ticket entirely on the
+        // native Rust backend. This ensures the ticket points to the native iroh
+        // node (which owns the file system and protocol handler) and the token is
+        // registered in the native SessionTokenRegistry.
+        const nativeBackend = this.backend;
+        if (nativeBackend?.getEndpointTicketWithToken) {
+            try {
+                const nativeCompoundTicket = await nativeBackend.getEndpointTicketWithToken(grantScope, maxConnections);
+                if (nativeCompoundTicket) {
+                    return nativeCompoundTicket;
+                }
+            }
+            catch {
+                // Fall back to WASM path
+            }
+        }
+        // Fallback: use native ticket with TS-generated token
+        if (nativeBackend?.getEndpointTicket) {
+            try {
+                const nativeTicket = await nativeBackend.getEndpointTicket();
+                const compound = this.client.buildCompoundTicketWithToken(nativeTicket, grantScope, maxConnections);
+                // Sync the generated token to native backend
+                if (nativeBackend.registerSessionToken) {
+                    const dotIdx = compound.indexOf('.');
+                    if (dotIdx >= 0) {
+                        const suffix = compound.slice(dotIdx + 1);
+                        try {
+                            const padded = suffix.replace(/-/g, '+').replace(/_/g, '/');
+                            const padding = (4 - (padded.length % 4)) % 4;
+                            const decoded = JSON.parse(atob(padded + '='.repeat(padding)));
+                            if (typeof decoded?.t === 'string') {
+                                await nativeBackend.registerSessionToken(decoded.t, grantScope, maxConnections).catch(() => { });
+                            }
+                        }
+                        catch { /* malformed suffix */ }
+                    }
+                }
+                return compound;
+            }
+            catch {
+                // Fall back to WASM ticket
+            }
+        }
+        return this.client.getEndpointTicketWithToken(grantScope, maxConnections);
+    }
+    /** Revoke all session tokens that match the given scope. */
+    async revokeTokensByScope(grantScope) {
+        return this.revokeTokensByScopeInternal(grantScope, {
+            rotateManagedScopeIfActive: true,
+        });
+    }
+    async revokeTokensByScopeInternal(grantScope, options) {
+        const localAffected = await this.client.revokeTokensByScope(grantScope);
+        // Also revoke on native backend and disconnect affected connections
+        const nativeBackend = this.backend;
+        let nativeAffected = [];
+        if (nativeBackend?.revokeSessionTokensByScope) {
+            nativeAffected = await nativeBackend.revokeSessionTokensByScope(grantScope).catch(() => []);
+        }
+        const affected = Array.from(new Set([...localAffected, ...nativeAffected]));
+        const shouldRotateManagedGrant = options?.rotateManagedScopeIfActive !== false &&
+            grantScope === RuntimeClient.MANAGED_USER_DEVICE_SCOPE &&
+            !!this.managedSessionOptions &&
+            this.managedSessionOptions.presence !== false;
+        if (!shouldRotateManagedGrant && grantScope === RuntimeClient.MANAGED_USER_DEVICE_SCOPE) {
+            this.clearPersistedManagedUserDeviceGrant(this.managedSessionUserId);
+        }
+        if (shouldRotateManagedGrant) {
+            await this.rotateManagedUserDeviceGrant();
+        }
+        return affected;
+    }
+    /** Revoke a single session token by its raw value. */
+    revokeSessionToken(token) {
+        this.client.revokeSessionToken(token);
+    }
+    async getEndpointTicket() {
+        const backend = this.backend;
+        if (backend && typeof backend.getEndpointTicket === 'function') {
+            try {
+                return await backend.getEndpointTicket();
+            }
+            catch {
+                // Wasm adapters may not implement a dedicated endpoint-ticket method.
+                // Fall back to the runtime client ticket surface instead of failing
+                // managed-session startup.
+            }
+        }
+        return this.client.getTicket();
+    }
+    async startManagedSession(options) {
+        const sessionKey = JSON.stringify({
+            platform: options.platform,
+            userId: options.userId ?? null,
+            deviceName: options.deviceName ?? null,
+            localDeviceId: options.localDeviceId ?? null,
+            metadata: options.metadata ?? null,
+            autoConnect: options.autoConnect !== false,
+            presence: options.presence !== false,
+        });
+        if (this.managedSessionKey === sessionKey) {
+            const device = await this.getLocalDeviceProfile({
+                deviceName: options.deviceName,
+                localDeviceId: options.localDeviceId ?? null,
+                platform: options.platform,
+                userId: options.userId ?? null,
+            });
+            return {
+                mode: options.platform,
+                device,
+                stop: async () => this.stopManagedSession(),
+            };
+        }
+        await this.stopManagedSession();
+        this.managedSessionKey = sessionKey;
+        this.managedSessionUserId = options.userId ?? this.identity?.id ?? null;
+        this.managedSessionOptions = { ...options };
+        let managedTicket = null;
+        if (options.platform === 'web') {
+            await this.initialize();
+            if (options.presence !== false) {
+                await this.client.clearSessionTokens().catch(() => { });
+                const restoredGrant = this.loadPersistedManagedUserDeviceGrant(this.managedSessionUserId);
+                if (restoredGrant) {
+                    managedTicket = RuntimeClient.encodeManagedCompoundTicket(await this.getEndpointTicket(), restoredGrant);
+                    console.info('[RuntimeClient][managed-ticket][restore]', {
+                        scope: restoredGrant.scope,
+                        userId: this.managedSessionUserId,
+                    });
+                }
+                else {
+                    managedTicket = await this.getTicketWithToken(RuntimeClient.MANAGED_USER_DEVICE_SCOPE, 0);
+                    this.persistManagedUserDeviceGrantFromTicket(this.managedSessionUserId, managedTicket);
+                }
+                this.client.setManagedPresenceTicket(managedTicket);
+                await this.start({ clearSessionTokens: false });
+            }
+            else {
+                this.client.clearManagedPresenceTicket();
+                await this.start();
+            }
+        }
+        else {
+            await this.getManagedNodeId({ initializeIfMissing: true });
+            if (options.presence !== false) {
+                managedTicket = await this.getTicketWithToken(RuntimeClient.MANAGED_USER_DEVICE_SCOPE, 0);
+                this.client.setManagedPresenceTicket(managedTicket);
+            }
+            else {
+                this.client.clearManagedPresenceTicket();
+            }
+        }
+        // Non-blocking: fetch and cache app limits for this session. Falls back
+        // to free-tier defaults already set on client.appLimits if this fails.
+        void this.fetchAndApplyAppLimits();
+        const device = await this.getLocalDeviceProfile({
+            deviceName: options.deviceName,
+            localDeviceId: options.localDeviceId ?? null,
+            platform: options.platform,
+            userId: options.userId ?? null,
+        });
+        if (options.presence !== false) {
+            await this.startPresenceLoop({
+                deviceName: device.deviceName,
+                ticket: managedTicket,
+                metadata: options.metadata,
+            });
+        }
+        if (options.autoConnect !== false && device.deviceId) {
+            await this.startAutoConnect(device.deviceId);
+        }
+        await this.refreshPeerSnapshot().catch(() => []);
+        return {
+            mode: options.platform,
+            device,
+            stop: async () => this.stopManagedSession(),
+        };
+    }
+    async stopManagedSession(options) {
+        if (!this.managedSessionKey && !this.managedSessionUserId) {
+            return;
+        }
+        const preserveBackendSession = !!options?.preserveBackendSession;
+        const backend = this.backend;
+        const managedOptions = this.managedSessionOptions;
+        this.client.clearManagedPresenceTicket();
+        if (!preserveBackendSession) {
+            await this.revokeTokensByScopeInternal(RuntimeClient.MANAGED_USER_DEVICE_SCOPE, {
+                rotateManagedScopeIfActive: false,
+            }).catch(() => []);
+            this.stop();
+            if (backend && typeof backend.stopAuthScopedActivity === 'function') {
+                await backend.stopAuthScopedActivity({
+                    userId: this.managedSessionUserId ?? this.identity?.id ?? null,
+                });
+            }
+            else {
+                await this.setOffline().catch(() => undefined);
+            }
+        }
+        else {
+            console.info('[RuntimeClient] Preserving native backend-managed session across frontend teardown', {
+                userId: this.managedSessionUserId ?? this.identity?.id ?? null,
+                scope: RuntimeClient.MANAGED_USER_DEVICE_SCOPE,
+            });
+        }
+        this.managedSessionKey = null;
+        this.managedSessionUserId = null;
+        this.managedSessionOptions = null;
+        if (managedOptions?.platform === 'web') {
+            this.clearPersistedManagedUserDeviceGrant(managedOptions.userId ?? this.identity?.id ?? null);
+        }
+    }
+    async rotateManagedUserDeviceGrant() {
+        const managedOptions = this.managedSessionOptions;
+        if (!managedOptions || managedOptions.presence === false) {
+            return;
+        }
+        const nextTicket = await this.getTicketWithToken(RuntimeClient.MANAGED_USER_DEVICE_SCOPE, 0);
+        const effectiveUserId = this.managedSessionUserId ?? managedOptions.userId ?? this.identity?.id ?? null;
+        if (managedOptions.platform === 'web') {
+            this.persistManagedUserDeviceGrantFromTicket(effectiveUserId, nextTicket);
+        }
+        this.client.setManagedPresenceTicket(nextTicket);
+        const device = await this.getLocalDeviceProfile({
+            deviceName: managedOptions.deviceName,
+            localDeviceId: managedOptions.localDeviceId ?? null,
+            platform: managedOptions.platform,
+            userId: managedOptions.userId ?? null,
+        });
+        await this.startPresenceLoop({
+            deviceName: device.deviceName,
+            ticket: nextTicket,
+            metadata: managedOptions.metadata,
+        });
+        console.info('[RuntimeClient][managed-ticket][rotate]', {
+            scope: RuntimeClient.MANAGED_USER_DEVICE_SCOPE,
+            platform: managedOptions.platform,
+            userId: effectiveUserId,
+        });
+    }
+    async listDevices() {
+        return this.client.searchDevices();
+    }
+    async listDevicesWithStatus() {
+        const backend = this.backend;
+        if (backend && typeof backend.listDevicesWithStatus === 'function') {
+            const devices = await backend.listDevicesWithStatus();
+            const [sessionsResult, peersResult] = await Promise.allSettled([
+                typeof backend.listPeerSessions === 'function'
+                    ? backend.listPeerSessions()
+                    : Promise.resolve([]),
+                this.refreshPeerSnapshot().catch((error) => {
+                    const cachedPeers = this.listConnectedPeers();
+                    console.warn(`[RuntimeClient] refreshPeerSnapshot failed during listDevicesWithStatus(); using ${cachedPeers.length} cached connected peers`, error);
+                    return cachedPeers;
+                }),
+            ]);
+            const sessions = sessionsResult.status === 'fulfilled' ? sessionsResult.value : [];
+            const peers = peersResult.status === 'fulfilled' ? peersResult.value : [];
+            const withSessions = this.overlayPeerSessionsOnDeviceSnapshots(devices, sessions);
+            return this.overlayPeerStateOnDeviceSnapshots(withSessions, peers);
+        }
+        throw new Error('[pluto-rtc] listDevicesWithStatus() requires a Rust-backed runtime adapter that implements listDevicesWithStatus().');
+    }
+    async updateDevice(deviceId, updates) {
+        await this.client.updateDevice(deviceId, updates);
+    }
+    async deleteDevice(deviceId) {
+        await this.client.deleteDevice(deviceId);
+    }
+    watchDevices(callback) {
+        return this.client.onDevicesChange(callback);
+    }
+    watchDevicesWithStatus(callback) {
+        const backend = this.backend;
+        if (!backend || typeof backend.listDevicesWithStatus !== 'function') {
+            throw new Error('[pluto-rtc] watchDevicesWithStatus() requires a Rust-backed runtime adapter that implements listDevicesWithStatus().');
+        }
+        let active = true;
+        let lastSnapshotKey = null;
+        let lastAuthoritativeSnapshot = [];
+        let lastWatchedDevices = null;
+        let latestPeerStates = [];
+        let refreshTimer = null;
+        let refreshInFlight = false;
+        let refreshQueued = false;
+        const emitSnapshot = (devices) => {
+            const nextDevices = this.overlayPeerStateOnDeviceSnapshots(devices, latestPeerStates);
+            const nextKey = this.deviceStatusSnapshotKey(nextDevices);
+            if (nextKey === lastSnapshotKey) {
+                return;
+            }
+            lastSnapshotKey = nextKey;
+            callback(nextDevices);
+        };
+        const runRefresh = () => {
+            if (!active)
+                return;
+            if (refreshInFlight) {
+                refreshQueued = true;
+                return;
+            }
+            refreshInFlight = true;
+            void this.listDevicesWithStatus()
+                .then((devices) => {
+                if (active) {
+                    lastAuthoritativeSnapshot = devices;
+                    emitSnapshot(this.mergeWatchedDevicesIntoStatusSnapshots(lastWatchedDevices, devices));
+                }
+            })
+                .catch(() => undefined)
+                .finally(() => finalizeRefresh());
+        };
+        const finalizeRefresh = () => {
+            refreshInFlight = false;
+            if (!active || !refreshQueued) {
+                return;
+            }
+            refreshQueued = false;
+            scheduleRefresh();
+        };
+        const scheduleRefresh = () => {
+            if (!active || refreshTimer) {
+                return;
+            }
+            refreshTimer = setTimeout(() => {
+                refreshTimer = null;
+                runRefresh();
+            }, RuntimeClient.DEVICE_STATUS_REFRESH_DEBOUNCE_MS);
+        };
+        const offDevices = this.watchDevices((devices) => {
+            if (Array.isArray(devices)) {
+                lastWatchedDevices = devices;
+                emitSnapshot(this.mergeWatchedDevicesIntoStatusSnapshots(devices, lastAuthoritativeSnapshot));
+            }
+            scheduleRefresh();
+        });
+        const offPeers = this.watchPeerStates((peers) => {
+            latestPeerStates = Array.isArray(peers) ? peers : [];
+            if (!lastAuthoritativeSnapshot.length) {
+                return;
+            }
+            emitSnapshot(lastAuthoritativeSnapshot);
+        });
+        const stopReconciliation = this.startManagedReconciliation(() => scheduleRefresh());
+        runRefresh();
+        return () => {
+            active = false;
+            if (refreshTimer) {
+                clearTimeout(refreshTimer);
+            }
+            stopReconciliation();
+            offDevices();
+            offPeers();
+        };
+    }
+    async connectDeviceWithRetry(device, hooks, options) {
+        return this.client.connectDeviceWithRetry(device, hooks, options);
+    }
+    /**
+     * Runtime-owned device connect flow used by product code.
+     * Rust owns the actual managed dial policy. This wrapper only:
+     * - validates the app-facing device/ticket input
+     * - forwards the request to the active runtime adapter
+     * - refreshes peer state and invokes optional app callbacks
+     */
+    async connectDevice(device, options) {
+        let resolvedDevice = device;
+        let ticket = typeof device.ticket === 'string' ? device.ticket.trim() : '';
+        if (!ticket) {
+            const candidates = await this.listDevicesWithStatus()
+                .catch(() => this.listDevices().catch(() => []));
+            const refreshed = candidates.find((candidate) => candidate.deviceId === device.deviceId);
+            if (refreshed) {
+                resolvedDevice = { ...device, ...refreshed };
+                ticket = typeof refreshed.ticket === 'string' ? refreshed.ticket.trim() : '';
+            }
+        }
+        if (!ticket) {
+            return {
+                success: false,
+                error: `Cannot connect to ${device.deviceId}: missing endpoint ticket`,
+                attempts: 1,
+            };
+        }
+        const currentState = this.getPeerState(device.deviceId)?.status;
+        if (currentState === 'connected') {
+            return {
+                success: true,
+                skipped: 'already-connecting',
+                attempts: 0,
+            };
+        }
+        try {
+            await this.connectToDevice({
+                deviceId: resolvedDevice.deviceId,
+                endpointTicket: ticket,
+            });
+            await this.refreshPeerSnapshot().catch(() => undefined);
+            await options.onConnected?.(resolvedDevice);
+            return {
+                success: true,
+                attempts: 1,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : `Cannot connect to ${device.deviceId}`,
+                attempts: 1,
+            };
+        }
+    }
+    watchPeerStates(callback) {
+        return this.client.watchPeerStates(callback);
+    }
+    getPeerState(id) {
+        return this.client.getPeerState(id);
+    }
+    async resolvePeerConnectionRecords(id) {
+        const backend = this.backend;
+        if (!backend || typeof backend.resolvePeerConnectionRecords !== 'function') {
+            throw new Error('[pluto-rtc] resolvePeerConnectionRecords() requires a Rust-backed runtime adapter that implements resolvePeerConnectionRecords().');
+        }
+        return backend.resolvePeerConnectionRecords(id);
+    }
+    async getPeerSession(id) {
+        const backend = this.backend;
+        if (!backend || typeof backend.getPeerSession !== 'function') {
+            throw new Error('[pluto-rtc] getPeerSession() requires a Rust-backed runtime adapter that implements getPeerSession().');
+        }
+        const lookupIds = await this.resolvePeerLookupIds(id, backend);
+        for (const lookupId of lookupIds) {
+            const session = await backend.getPeerSession(lookupId);
+            if (session) {
+                return session;
+            }
+        }
+        if (typeof backend.listPeerSessions === 'function') {
+            return this.matchSessionByLookupId(await backend.listPeerSessions(), lookupIds);
+        }
+        return null;
+    }
+    async listPeerSessions() {
+        const backend = this.backend;
+        if (!backend || typeof backend.listPeerSessions !== 'function') {
+            throw new Error('[pluto-rtc] listPeerSessions() requires a Rust-backed runtime adapter that implements listPeerSessions().');
+        }
+        return backend.listPeerSessions();
+    }
+    async waitForConnectedPeer(id, timeoutMs) {
+        const backend = this.backend;
+        if (!backend || typeof backend.waitForSettledPeer !== 'function') {
+            throw new Error('[pluto-rtc] waitForConnectedPeer() requires a Rust-backed runtime adapter that implements waitForSettledPeer().');
+        }
+        const resolvedIdentity = typeof backend.resolvePeerIdentity === 'function'
+            ? await backend.resolvePeerIdentity(id).catch(() => null)
+            : null;
+        const preferredLookupId = this.uniqueLookupIds(resolvedIdentity?.peerId, resolvedIdentity?.deviceId, resolvedIdentity?.deviceIdHint, resolvedIdentity?.nodeId, id)[0] ?? id;
+        return backend.waitForSettledPeer(preferredLookupId, timeoutMs);
+    }
+    async getPeerReadiness(id, timeoutMs) {
+        const peer = this.getPeerState(id) ?? null;
+        const session = typeof timeoutMs === 'number'
+            ? await this.waitForConnectedPeer(id, timeoutMs).catch(() => null)
+            : await this.getPeerSession(id).catch(() => null);
+        const status = this.normalizeUiConnectionStatus(session?.status ?? peer?.status ?? 'disconnected');
+        const trustBlocked = peer?.routable === false && peer?.protocolState === 'unverified';
+        return {
+            requestedId: id,
+            connected: status === 'connected',
+            settledReady: trustBlocked ? false : !!session?.settledReady,
+            status,
+            health: session?.health ?? peer?.health ?? 'unknown',
+            deviceId: session?.deviceId ?? peer?.deviceId ?? null,
+            deviceIdHint: session?.deviceIdHint ?? peer?.deviceIdHint ?? null,
+            activeConnectionId: session?.activeConnectionId ?? peer?.connectionId ?? null,
+            readinessState: trustBlocked
+                ? peer?.protocolState
+                : session?.readinessState ?? peer?.protocolState,
+            readinessReason: trustBlocked
+                ? peer?.error
+                : session?.readinessReason ?? peer?.error,
+            scopes: [...(session?.scopes ?? peer?.scopes ?? [])],
+        };
+    }
+    async resolvePeerIdentity(id) {
+        const backend = this.backend;
+        if (!backend || typeof backend.resolvePeerIdentity !== 'function') {
+            throw new Error('[pluto-rtc] resolvePeerIdentity() requires a Rust-backed runtime adapter that implements resolvePeerIdentity().');
+        }
+        return backend.resolvePeerIdentity(id);
+    }
+    async resolveIncomingStreamPeer(remoteNodeId) {
+        return this.resolvePeerIdentity(remoteNodeId);
+    }
+    listConnectedPeers() {
+        return this.client.listConnectedPeers();
+    }
+    addPeerScope(id, scope) {
+        return this.client.addPeerScope(id, scope);
+    }
+    releasePeerScope(id, scope) {
+        return this.client.releasePeerScope(id, scope);
+    }
+    getPeerScopes(id) {
+        return this.client.getPeerScopes(id);
+    }
+    isSamePeer(a, b) {
+        return this.client.isSamePeer(a, b);
+    }
+    async refreshPeerSnapshot() {
+        return this.client.refreshPeerSnapshot();
+    }
+    async subscribeSessions(localDeviceId, callback) {
+        return this.client.subscribeSessions(localDeviceId, callback);
+    }
+    getAppLimits() {
+        return this.client.appLimits;
+    }
+    async createRoom() {
+        return this.client.rooms.createRoom();
+    }
+    async joinRoom(roomId, options) {
+        return this.client.rooms.joinRoom(roomId, options);
+    }
+    async leaveRoom(roomId) {
+        return this.client.rooms.leaveRoom(roomId);
+    }
+    async getRoomMembers(roomId) {
+        return this.client.rooms.getRoomMembers(roomId);
+    }
+    watchRoom(roomId, callback) {
+        return this.client.rooms.watchRoom(roomId, callback);
+    }
+    /** @deprecated Use connect() (no-arg) for lifecycle, or connectTo() for peer connections */
+    async connectByTicket(target) {
+        return this.client.connect(target.ticket, target.timeoutMs);
+    }
+    async connectPeer(options) {
+        return this.client.connectPeer(options);
+    }
+    async openPeerBi(id, options) {
+        const backend = this.backend;
+        if (backend && typeof backend.openPeerBi === 'function') {
+            const stream = await backend.openPeerBi(id, options?.timeoutMs);
+            const target = await this.resolvePeerStreamTarget(id);
+            return {
+                connection: target.connection ?? this.compatPeerConnectionFromTarget(target, id),
+                readable: stream.readable,
+                writable: options?.channelId
+                    ? this.client.wrapChannelWritable(stream.writable, options.channelId)
+                    : stream.writable,
+            };
+        }
+        throw new Error('[pluto-rtc] openPeerBi() requires a Rust-backed runtime adapter that implements openPeerBi().');
+    }
+    async openPeerUni(id, options) {
+        const backend = this.backend;
+        if (backend && typeof backend.openPeerUni === 'function') {
+            const stream = await backend.openPeerUni(id, options?.timeoutMs);
+            const target = await this.resolvePeerStreamTarget(id);
+            return {
+                connection: target.connection ?? this.compatPeerConnectionFromTarget(target, id),
+                writable: options?.channelId
+                    ? this.client.wrapChannelWritable(stream.writable, options.channelId)
+                    : stream.writable,
+            };
+        }
+        throw new Error('[pluto-rtc] openPeerUni() requires a Rust-backed runtime adapter that implements openPeerUni().');
+    }
+    async connectToDevice(params) {
+        const backend = this.backend;
+        if (!backend || typeof backend.connectToDevice !== 'function') {
+            throw new Error('Selected runtime adapter does not support connectToDevice().');
+        }
+        return backend.connectToDevice(params);
+    }
+    async connectRaw(target) {
+        return this.client.connectRaw(target.ticket, target.timeoutMs);
+    }
+    async openBi(nodeId) {
+        return this.client.openBi(nodeId);
+    }
+    async openUni(nodeId) {
+        return this.client.openUni(nodeId);
+    }
+    onIncomingStream(callback) {
+        return this.client.onIncomingStream(callback);
+    }
+    registerChannel(descriptor) {
+        this.client.registerChannel(descriptor);
+    }
+    unregisterChannel(channelId) {
+        this.client.unregisterChannel(channelId);
+    }
+    listChannels() {
+        return this.client.listChannels();
+    }
+    onIncomingChannelStream(channelId, callback) {
+        return this.client.onIncomingChannelStream(channelId, callback);
+    }
+    async sendExplicitFilePath(connectionId, filePath, transferId) {
+        const backend = this.backend;
+        if (!backend || typeof backend.sendExplicitFilePath !== 'function') {
+            throw new Error('Selected runtime adapter does not support sendExplicitFilePath().');
+        }
+        return backend.sendExplicitFilePath(connectionId, filePath, transferId);
+    }
+    async sendExplicitFileData(params) {
+        const backend = this.backend;
+        if (!backend || typeof backend.sendExplicitFileData !== 'function') {
+            throw new Error('Selected runtime adapter does not support sendExplicitFileData().');
+        }
+        return backend.sendExplicitFileData(params);
+    }
+    async getTransferHistory(limit) {
+        const backend = this.backend;
+        if (!backend || typeof backend.getTransferHistory !== 'function') {
+            return [];
+        }
+        return backend.getTransferHistory(limit);
+    }
+    async deleteTransferJob(jobId) {
+        const backend = this.backend;
+        if (!backend || typeof backend.deleteTransferJob !== 'function') {
+            return;
+        }
+        return backend.deleteTransferJob(jobId);
+    }
+    async startPresenceLoop(options) {
+        const backend = this.backend;
+        if (backend && typeof backend.startPresenceLoopOnce === 'function') {
+            const userId = this.identity?.id;
+            if (!userId) {
+                throw new Error('startPresenceLoop requires an authenticated user');
+            }
+            const localNodeId = await this.getNodeId();
+            const ticket = options?.ticket || await this.getEndpointTicket();
+            const profile = await this.getLocalDeviceProfile({
+                deviceName: options?.deviceName,
+                platform: 'native',
+                userId,
+            });
+            await this.runNativeStartLoop({
+                label: 'startPresenceLoop',
+                exhaustedMessage: `[RuntimeClient] startPresenceLoop exhausted retries user_id=${userId} local_node_id=${localNodeId}`,
+                start: () => backend.startPresenceLoopOnce(userId, localNodeId, options?.deviceName || profile.deviceName, ticket, options?.metadata),
+            });
+            // Phase 2: wire the RTDB presence instance (created during startPresenceLoop)
+            // into RoomManager so room member liveness uses RTDB instead of Firestore heartbeats.
+            const rtdbPresence = backend.rtdbPresence;
+            if (rtdbPresence) {
+                this.client.rooms.setRtdbPresence(rtdbPresence);
+            }
+            return;
+        }
+        await this.client.startPresenceLoop(options);
+    }
+    async updatePresence(options) {
+        await this.client.updatePresence(options?.isOnline, options?.ttlMs, options?.metadata, options?.ticket);
+    }
+    async setOffline() {
+        await this.client.setOffline();
+    }
+    async startAutoConnect(localDeviceId) {
+        const backend = this.backend;
+        if (backend && typeof backend.startAutoConnectOnce === 'function') {
+            const userId = this.identity?.id;
+            if (!userId) {
+                throw new Error('startAutoConnect requires an authenticated user');
+            }
+            const effectiveLocalDeviceId = localDeviceId || (await this.getLocalDeviceId());
+            if (!effectiveLocalDeviceId) {
+                throw new Error('startAutoConnect requires a local device id');
+            }
+            await this.runNativeStartLoop({
+                label: 'startAutoConnect',
+                exhaustedMessage: `[RuntimeClient] startAutoConnect exhausted retries user_id=${userId} local_device_id=${effectiveLocalDeviceId}`,
+                start: () => backend.startAutoConnectOnce(userId, effectiveLocalDeviceId),
+            });
+            return;
+        }
+        await this.client.startAutoConnect(localDeviceId);
+    }
+    async isConnected(nodeId) {
+        return this.client.isConnected(nodeId);
+    }
+    async disconnectNode(nodeId) {
+        await this.client.disconnectNode(nodeId);
+    }
+    async disconnectDevice(deviceId) {
+        const backend = this.backend;
+        if (!backend || typeof backend.disconnectDevice !== 'function') {
+            await this.client.forceDisconnectPeer(deviceId);
+            return;
+        }
+        return backend.disconnectDevice(deviceId);
+    }
+    async setAutoConnectExcluded(deviceId, excluded) {
+        const backend = this.backend;
+        if (backend && typeof backend.setAutoConnectExcluded === 'function') {
+            await backend.setAutoConnectExcluded(deviceId, excluded);
+        }
+    }
+    async disconnectPeer(id, scope) {
+        await this.client.disconnectPeer(id, scope);
+    }
+    async forceDisconnectPeer(id) {
+        await this.client.forceDisconnectPeer(id);
+    }
+    async getPeerHealth(id) {
+        return this.client.getPeerHealth(id);
+    }
+    async getConnectionStates() {
+        return this.client.signaling.getConnectionStates();
+    }
+    onConnectionStateChange(callback) {
+        let active = true;
+        const seenByConnectionId = new Map();
+        const deliver = (state) => {
+            if (!active) {
+                return;
+            }
+            const nextKey = this.connectionStateSnapshotKey(state);
+            if (seenByConnectionId.get(state.connectionId) === nextKey) {
+                return;
+            }
+            seenByConnectionId.set(state.connectionId, nextKey);
+            callback(state);
+        };
+        const emitSnapshot = () => {
+            if (!active) {
+                return;
+            }
+            void this.getConnectionStates()
+                .then((states) => {
+                states.forEach((state) => deliver(state));
+            })
+                .catch(() => undefined);
+        };
+        const finalize = (off) => () => {
+            active = false;
+            stopReconciliation();
+            off?.();
+        };
+        const stopReconciliation = this.startManagedReconciliation(() => emitSnapshot());
+        const off = this.client.signaling.onConnectionStateChange((state) => deliver(state));
+        emitSnapshot();
+        if (typeof off === 'function') {
+            return finalize(off);
+        }
+        return Promise.resolve(off).then((resolved) => finalize(typeof resolved === 'function' ? resolved : null));
+    }
+    getConnections() {
+        return this.client.getConnections();
+    }
+    onConnection(callback) {
+        return this.client.onConnection(callback);
+    }
+    onDisconnection(callback) {
+        return this.client.onDisconnection(callback);
+    }
+    onConnectionEvent(callback) {
+        const offConnected = this.client.onConnection((connection) => {
+            callback({
+                type: 'connected',
+                connectionId: connection.id,
+                localNodeId: connection.localNodeId,
+                remoteNodeId: connection.remoteNodeId,
+                transport: connection.transportType,
+            });
+        });
+        const offDisconnected = this.client.onDisconnection((connection) => {
+            callback({
+                type: 'disconnected',
+                connectionId: connection.id,
+                localNodeId: connection.localNodeId,
+                remoteNodeId: connection.remoteNodeId,
+                transport: connection.transportType,
+            });
+        });
+        return () => {
+            offConnected();
+            offDisconnected();
+        };
+    }
+    forceReconnectSnapshot() {
+        this.client.forceReconnectSnapshot();
+    }
+    // ─── Method Aliases (new naming convention) ─────────────────────────
+    // These provide the simplified API. Old names remain for backward compat.
+    /** Single-call lifecycle: combines initialize() + start() */
+    async connect() {
+        await this.initialize();
+        await this.start();
+    }
+    /** Disconnect from the runtime (alias for stop()) */
+    disconnect() {
+        this.stop();
+    }
+    /** Alias for onIdentityChange */
+    onAuthChange(callback) {
+        return this.onIdentityChange(callback);
+    }
+    /** Alias for setAuthContext */
+    async setAuth(context) {
+        return this.setAuthContext(context);
+    }
+    /** Alias for signInWithPluto */
+    async signIn() {
+        return this.signInWithPluto();
+    }
+    /** Alias for listDevices */
+    async getDevices() {
+        return this.listDevices();
+    }
+    onDevices(callback, options) {
+        if (options?.status) {
+            return this.watchDevicesWithStatus(callback);
+        }
+        return this.watchDevices(callback);
+    }
+    /** Alias for getTicket — returns an invite/ticket string */
+    async getInvite() {
+        return this.getTicket();
+    }
+    /** Connect to a peer by device ID or options */
+    async connectTo(options) {
+        return this.connectPeer(options);
+    }
+    /** Alias for waitForConnectedPeer */
+    async waitFor(id, timeoutMs) {
+        return this.waitForConnectedPeer(id, timeoutMs);
+    }
+    /** Open a stream to a peer (default: bidirectional) */
+    async openStream(id, options) {
+        if (options?.direction === 'send') {
+            return this.openPeerUni(id, options);
+        }
+        return this.openPeerBi(id, options);
+    }
+    async openChannelStream(channelId, id, options) {
+        return this.openStream(id, {
+            ...options,
+            channelId,
+        });
+    }
+    /** Alias for onIncomingStream */
+    onStream(callback) {
+        return this.onIncomingStream(callback);
+    }
+    onChannelStream(channelId, callback) {
+        return this.onIncomingChannelStream(channelId, callback);
+    }
+    /** Alias for watchRoom */
+    onRoomChange(roomId, callback) {
+        return this.watchRoom(roomId, callback);
+    }
+}
+RuntimeClient.NATIVE_START_RETRY_WINDOW_MS = 120000;
+RuntimeClient.NATIVE_START_RETRY_MIN_DELAY_MS = 400;
+RuntimeClient.NATIVE_START_RETRY_MAX_DELAY_MS = 5000;
+RuntimeClient.MANAGED_RECONCILIATION_INTERVAL_MS = 30000;
+RuntimeClient.DEVICE_STATUS_REFRESH_DEBOUNCE_MS = 150;
+RuntimeClient.MANAGED_USER_DEVICE_SCOPE = 'user-device';
+RuntimeClient.MANAGED_USER_DEVICE_STORAGE_KEY_PREFIX = 'openrtc:managed:user-device';