nexabase-console 2.1.2 → 2.1.3

package/dist/transport/WebSocketClient.js

@@ -1,47 +1,940 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = void 0;
+exports.WebSocketClient = exports.NexaWebSocketError = void 0;
 const socket_io_client_1 = require("socket.io-client");
+/**
+ * Production error class preserving structured metadata across tab boundaries.
+ */
+class NexaWebSocketError extends Error {
+    constructor(options) {
+        super(options.message);
+        this.name = 'NexaWebSocketError';
+        this.code = options.code || 'unavailable';
+        this.retryable = options.retryable ?? false;
+        this.source = options.source || 'client';
+        this.isAmbiguous = options.isAmbiguous ?? false;
+        this.details = options.details;
+        if (options.cause && typeof this.cause === 'undefined') {
+            this.cause = options.cause;
+        }
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, NexaWebSocketError);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            retryable: this.retryable,
+            source: this.source,
+            isAmbiguous: this.isAmbiguous,
+            details: this.details,
+        };
+    }
+    static from(err, defaultSource = 'client') {
+        if (err instanceof NexaWebSocketError) {
+            return err;
+        }
+        if (err && typeof err === 'object') {
+            const e = err;
+            if (typeof e.message === 'string' && typeof e.code === 'string') {
+                return new NexaWebSocketError({
+                    message: e.message,
+                    code: e.code,
+                    retryable: Boolean(e.retryable),
+                    source: e.source || defaultSource,
+                    isAmbiguous: Boolean(e.isAmbiguous),
+                    details: e.details,
+                });
+            }
+            if (e instanceof Error) {
+                return new NexaWebSocketError({
+                    message: e.message,
+                    code: 'unavailable',
+                    source: defaultSource,
+                    cause: e,
+                });
+            }
+        }
+        return new NexaWebSocketError({
+            message: typeof err === 'string' ? err : 'Unknown error',
+            code: 'unavailable',
+            source: defaultSource,
+        });
+    }
+}
+exports.NexaWebSocketError = NexaWebSocketError;
+/**
+ * Production-hardened WebSocketClient with distributed coordination,
+ * term-fenced follower forwarding, BFCache/background resilience, and strict invariants.
+ */
 class WebSocketClient {
-    constructor(projectId, serverUrl) {
-        this.socket = null;
-        this.isConnected = false;
+    constructor(projectId, serverUrl, options = {}) {
+        this._socket = null;
+        this._isConnected = false;
+        this._lastReportedConnected = false;
+        this._state = 'idle';
+        this._isSuspended = false;
+        // Leadership Term Fencing
+        this._electionId = null;
+        this._currentLeaderId = null;
+        this._currentElectionId = null;
+        this._currentTermSeq = 0;
+        this._isLeaderSocketConnected = false;
+        // Local Tab State
         this.listeners = new Map();
-        this.subscribedPaths = new Set();
-        // Cross-tab sync properties
+        this.localSubscribedPaths = new Map(); // cleanPath -> refCount
+        this.activeLocalSendsCount = 0;
+        // Cross-Tab Synchronization
         this.broadcastChannel = null;
-        this.isLeader = false;
-        this.hasInitialized = false;
-        this.projectId = projectId;
-        this.serverUrl = serverUrl;
-        if (typeof window !== 'undefined' && 'BroadcastChannel' in window) {
-            this.broadcastChannel = new BroadcastChannel(`nexabase_ws_${projectId}`);
-            this.broadcastChannel.onmessage = this.handleBroadcastMessage.bind(this);
+        this.lockAbortController = null;
+        this.resolveLeaderLock = null;
+        // Leader State
+        this.followerSubscriptions = new Map(); // cleanPath -> Set<tabId>
+        this.followerSubscriptionsByTab = new Map(); // tabId -> Set<cleanPath>
+        this.followerGlobalNeeds = new Map();
+        // Bounded deduplication cache for follower requests executed by the leader
+        this.processedFollowerRequests = new Map();
+        // Active Executions & Waiters
+        this.pendingSendRequests = new Map();
+        this.activeLeaderSends = new Map();
+        this.readinessWaiters = new Set();
+        // Timers
+        this.heartbeatTimer = null;
+        this.pruneTimer = null;
+        this.leaseTimer = null;
+        this.reconnectTimer = null;
+        this.pageLifecycleCleanup = null;
+        if (typeof projectId !== 'string' || !projectId.trim()) {
+            throw new NexaWebSocketError({
+                message: 'Invalid projectId: must be a non-empty string',
+                code: 'invalid-argument',
+            });
+        }
+        if (typeof serverUrl !== 'string' || !serverUrl.trim()) {
+            throw new NexaWebSocketError({
+                message: 'Invalid serverUrl: must be a non-empty string',
+                code: 'invalid-argument',
+            });
+        }
+        this._projectId = projectId.trim();
+        this._serverUrl = serverUrl.trim();
+        this._options = options;
+        this._authPayload = options.authPayload;
+        this._tabId = WebSocketClient.generateId();
+        this.followerTtlMs = options.followerTtlMs || WebSocketClient.DEFAULT_FOLLOWER_TTL;
+        this.heartbeatIntervalMs =
+            options.heartbeatIntervalMs || WebSocketClient.DEFAULT_HEARTBEAT_INTERVAL;
+        this.pruneIntervalMs = options.pruneIntervalMs || WebSocketClient.DEFAULT_PRUNE_INTERVAL;
+        this.leaderLeaseIntervalMs =
+            options.leaderLeaseIntervalMs || WebSocketClient.DEFAULT_LEADER_LEASE_INTERVAL;
+        this.defaultTimeoutMs = options.defaultTimeoutMs || WebSocketClient.DEFAULT_TIMEOUT_MS;
+        const rawScope = options.sessionScope;
+        if (typeof rawScope === 'string' && rawScope.trim().length > 0) {
+            this._sessionScope = WebSocketClient.hashScope(rawScope.trim());
+        }
+        else {
+            this._sessionScope = null;
+        }
+        this._coordinationKey = WebSocketClient.deriveCoordinationKey(this._projectId, this._serverUrl, this._sessionScope);
+        // Determine initial coordination mode
+        const hasWindow = typeof window !== 'undefined';
+        const hasBC = hasWindow &&
+            (typeof options.broadcastChannelFactory === 'function' || 'BroadcastChannel' in window);
+        const hasLocks = hasWindow &&
+            (options.locks !== undefined ||
+                (typeof navigator !== 'undefined' &&
+                    navigator.locks &&
+                    typeof navigator.locks.request === 'function'));
+        if (options.coordinationMode === 'independent' || !hasBC || !hasLocks) {
+            this._coordinationMode = 'independent';
+        }
+        else {
+            this._coordinationMode = options.coordinationMode || 'shared';
+        }
+        if (this._coordinationMode === 'shared' && hasWindow) {
+            const channelName = `nexabase_bc_${this._coordinationKey}`;
+            try {
+                if (typeof options.broadcastChannelFactory === 'function') {
+                    this.broadcastChannel = options.broadcastChannelFactory(channelName);
+                }
+                else if ('BroadcastChannel' in window) {
+                    this.broadcastChannel = new BroadcastChannel(channelName);
+                }
+                if (this.broadcastChannel) {
+                    this.broadcastChannel.onmessage = this.handleBroadcastMessage.bind(this);
+                }
+            }
+            catch {
+                this.broadcastChannel = null;
+                this._coordinationMode = 'independent';
+            }
+        }
+        this.setupPageLifecycleListeners();
+    }
+    // Public Getters
+    get projectId() {
+        return this._projectId;
+    }
+    get serverUrl() {
+        return this._serverUrl;
+    }
+    get tabId() {
+        return this._tabId;
+    }
+    get isConnected() {
+        return this._isConnected;
+    }
+    get isLeader() {
+        return this._state === 'leader';
+    }
+    get state() {
+        return this._state;
+    }
+    get electionId() {
+        return this._electionId;
+    }
+    get currentLeaderId() {
+        return this._currentLeaderId;
+    }
+    get currentElectionId() {
+        return this._currentElectionId;
+    }
+    get isIndependent() {
+        return this._coordinationMode === 'independent';
+    }
+    get coordinationMode() {
+        return this._coordinationMode;
+    }
+    get isSuspended() {
+        return this._isSuspended;
+    }
+    /**
+     * Unique ID generation with Web Crypto fallback.
+     */
+    static generateId() {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            try {
+                return crypto.randomUUID();
+            }
+            catch { }
+        }
+        return `id_${Math.random().toString(36).substring(2, 9)}_${Date.now().toString(36)}`;
+    }
+    /**
+     * Stable deterministic hashing function.
+     */
+    static hashScope(scope) {
+        let h1 = 0xdeadbeef;
+        let h2 = 0x41c6ce57;
+        for (let i = 0; i < scope.length; i++) {
+            const ch = scope.charCodeAt(i);
+            h1 = Math.imul(h1 ^ ch, 2654435761);
+            h2 = Math.imul(h2 ^ ch, 1597334677);
+        }
+        h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+        h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+        const p1 = (h1 >>> 0).toString(16).padStart(8, '0');
+        const p2 = (h2 >>> 0).toString(16).padStart(8, '0');
+        return `${p1}${p2}`;
+    }
+    /**
+     * Normalizes server URL and creates a unique coordination key.
+     */
+    static deriveCoordinationKey(projectId, serverUrl, sessionScope) {
+        let normalizedUrl = serverUrl.trim().toLowerCase();
+        try {
+            if (typeof URL !== 'undefined') {
+                const parsed = new URL(normalizedUrl);
+                normalizedUrl = `${parsed.protocol}//${parsed.host}${parsed.pathname.replace(/\/+$/, '')}`;
+            }
+        }
+        catch { }
+        const raw = `v2_${projectId.trim()}_${normalizedUrl}_${sessionScope || 'anon'}`;
+        return WebSocketClient.hashScope(raw);
+    }
+    /**
+     * Sanitizes, segments, and bounds path strings.
+     */
+    static cleanAndValidatePath(path) {
+        if (typeof path !== 'string')
+            return null;
+        const trimmed = path.trim();
+        if (!trimmed)
+            return null;
+        // Reject control characters
+        // eslint-disable-next-line no-control-regex
+        if (/[\x00-\x1F\x7F]/.test(trimmed))
+            return null;
+        const stripped = trimmed.replace(/^\/+|\/+$/g, '');
+        if (!stripped)
+            return null;
+        // Reject empty path segments
+        if (stripped.includes('//'))
+            return null;
+        // Check segment and total length limits
+        if (stripped.length > 2048)
+            return null;
+        const segments = stripped.split('/');
+        for (const segment of segments) {
+            if (!segment || segment.length > 500)
+                return null;
+        }
+        return stripped;
+    }
+    static validatePathOrThrow(path) {
+        const clean = WebSocketClient.cleanAndValidatePath(path);
+        if (!clean) {
+            throw new NexaWebSocketError({
+                message: `Invalid path: "${String(path)}"`,
+                code: 'invalid-argument',
+            });
+        }
+        return clean;
+    }
+    /**
+     * Segment-aware path matcher: checks exact match or segment hierarchy.
+     */
+    static isPathMatch(eventPath, subPath) {
+        if (eventPath === subPath)
+            return true;
+        if (eventPath.startsWith(subPath + '/'))
+            return true;
+        if (subPath.startsWith(eventPath + '/'))
+            return true;
+        return false;
+    }
+    /**
+     * Tri-state path extraction distinguishing: none vs valid vs invalid.
+     */
+    static extractPayloadPathTriState(payload) {
+        if (!payload || typeof payload !== 'object') {
+            return { status: 'none' };
+        }
+        const p = payload;
+        const hasPathField = 'path' in p || 'docPath' in p || 'collectionPath' in p;
+        if (!hasPathField) {
+            return { status: 'none' };
+        }
+        const raw = p.path !== undefined ? p.path : p.docPath !== undefined ? p.docPath : p.collectionPath;
+        const clean = WebSocketClient.cleanAndValidatePath(raw);
+        if (clean) {
+            return { status: 'valid', path: clean };
+        }
+        return { status: 'invalid', raw };
+    }
+    /**
+     * Backward-compatible extractor returning valid path or null.
+     */
+    static extractPayloadPath(payload) {
+        const res = WebSocketClient.extractPayloadPathTriState(payload);
+        return res.status === 'valid' ? res.path : null;
+    }
+    /**
+     * Dynamic authentication updater.
+     */
+    updateAuth(authPayload) {
+        this._authPayload = authPayload;
+        if (this._socket) {
+            this._socket.auth = authPayload;
+        }
+    }
+    async getFreshAuthPayload() {
+        if (typeof this._options.getAuthPayload === 'function') {
+            try {
+                const payload = await this._options.getAuthPayload();
+                this._authPayload = payload;
+                return payload;
+            }
+            catch (err) {
+                console.warn('[WebSocketClient] Error resolving fresh auth payload:', err);
+            }
+        }
+        return this._authPayload;
+    }
+    transitionTo(newState) {
+        const current = this._state;
+        if (current === 'disposed')
+            return false;
+        if (current === newState)
+            return true;
+        if (current === 'disconnecting' && newState !== 'idle' && newState !== 'disposed') {
+            return false;
+        }
+        this._state = newState;
+        return true;
+    }
+    /**
+     * Atomically downgrades from shared coordination to independent socket mode.
+     */
+    switchToIndependentMode(reason) {
+        if (this._coordinationMode === 'independent')
+            return;
+        this._coordinationMode = 'independent';
+        this.stopFollowerHeartbeat();
+        this.stopLeaderPruneTimer();
+        this.stopLeaderLeaseTimer();
+        if (this.broadcastChannel) {
+            try {
+                this.broadcastChannel.close();
+            }
+            catch { }
+            this.broadcastChannel = null;
+        }
+        this.releaseLeaderLock();
+        this._currentLeaderId = this._tabId;
+        this._currentElectionId = this._electionId || WebSocketClient.generateId();
+        this._electionId = this._currentElectionId;
+        this.transitionTo('leader');
+        this.startSocketConnection();
+        this.checkReadinessWaiters();
+    }
+    /**
+     * Safe non-throwing broadcast poster returning a delivery indicator boolean.
+     */
+    postBroadcast(type, payload = {}) {
+        if (!this.broadcastChannel ||
+            this._state === 'disposed' ||
+            this._isSuspended ||
+            this._coordinationMode === 'independent') {
+            return false;
+        }
+        try {
+            let msg;
+            const now = Date.now();
+            if (type === 'leader_elected' ||
+                type === 'leader_state' ||
+                type === 'leader_event' ||
+                type === 'leader_send_response') {
+                if (!this.isLeader || !this._electionId)
+                    return false;
+                if (type === 'leader_elected' || type === 'leader_state') {
+                    msg = {
+                        type,
+                        senderId: this._tabId,
+                        leaderId: this._tabId,
+                        electionId: this._electionId,
+                        termSeq: this._currentTermSeq,
+                        timestamp: now,
+                        payload: {
+                            leaderId: this._tabId,
+                            electionId: this._electionId,
+                            isConnected: this._isConnected,
+                            termSeq: this._currentTermSeq,
+                        },
+                    };
+                }
+                else if (type === 'leader_event') {
+                    msg = {
+                        type: 'leader_event',
+                        senderId: this._tabId,
+                        leaderId: this._tabId,
+                        electionId: this._electionId,
+                        timestamp: now,
+                        payload: {
+                            event: payload.event,
+                            data: payload.data,
+                            targetTabIds: payload.targetTabIds,
+                        },
+                    };
+                }
+                else {
+                    msg = {
+                        type: 'leader_send_response',
+                        senderId: this._tabId,
+                        leaderId: this._tabId,
+                        electionId: this._electionId,
+                        timestamp: now,
+                        payload: {
+                            requestId: payload.requestId,
+                            targetTabId: payload.targetTabId,
+                            response: payload.response,
+                            error: payload.error,
+                        },
+                    };
+                }
+            }
+            else {
+                msg = {
+                    type,
+                    senderId: this._tabId,
+                    timestamp: now,
+                    payload,
+                };
+            }
+            this.broadcastChannel.postMessage(msg);
+            return true;
+        }
+        catch (err) {
+            console.warn('[WebSocketClient] Failed to post broadcast message:', err);
+            return false;
+        }
+    }
+    /**
+     * Strictly validates incoming broadcast payload schema, types, bounds, and string sizes.
+     */
+    validateBroadcastMessage(raw) {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const msg = raw;
+        if (typeof msg.type !== 'string' ||
+            typeof msg.senderId !== 'string' ||
+            !msg.senderId ||
+            msg.senderId.length > 128) {
+            return null;
+        }
+        if (msg.senderId === this._tabId)
+            return null; // Ignore messages from self
+        const type = msg.type;
+        const payload = msg.payload;
+        if (!payload || typeof payload !== 'object') {
+            if (type !== 'follower_sync_request' && type !== 'follower_disconnect') {
+                return null;
+            }
+        }
+        const timestamp = typeof msg.timestamp === 'number' ? msg.timestamp : Date.now();
+        switch (type) {
+            case 'follower_subscribe':
+            case 'follower_unsubscribe': {
+                const clean = WebSocketClient.cleanAndValidatePath(payload.path);
+                if (!clean)
+                    return null;
+                return {
+                    type,
+                    senderId: msg.senderId,
+                    timestamp,
+                    payload: { path: clean },
+                };
+            }
+            case 'follower_sync_request': {
+                return {
+                    type: 'follower_sync_request',
+                    senderId: msg.senderId,
+                    timestamp,
+                    payload: {},
+                };
+            }
+            case 'follower_announce': {
+                if (!Array.isArray(payload.paths))
+                    return null;
+                if (payload.paths.length > 500)
+                    return null;
+                const validPaths = [];
+                for (const p of payload.paths) {
+                    const clean = WebSocketClient.cleanAndValidatePath(p);
+                    if (clean)
+                        validPaths.push(clean);
+                }
+                const count = payload.globalListenersCount;
+                if (typeof count !== 'number' || !Number.isInteger(count) || count < 0 || count > 100000) {
+                    return null;
+                }
+                return {
+                    type: 'follower_announce',
+                    senderId: msg.senderId,
+                    timestamp,
+                    payload: {
+                        paths: validPaths,
+                        globalListenersCount: count,
+                    },
+                };
+            }
+            case 'follower_heartbeat': {
+                const count = payload.globalListenersCount;
+                if (typeof count !== 'number' || !Number.isInteger(count) || count < 0 || count > 100000) {
+                    return null;
+                }
+                let paths;
+                if (Array.isArray(payload.paths)) {
+                    if (payload.paths.length > 500)
+                        return null;
+                    paths = [];
+                    for (const p of payload.paths) {
+                        const clean = WebSocketClient.cleanAndValidatePath(p);
+                        if (clean)
+                            paths.push(clean);
+                    }
+                }
+                return {
+                    type: 'follower_heartbeat',
+                    senderId: msg.senderId,
+                    timestamp,
+                    payload: {
+                        globalListenersCount: count,
+                        paths,
+                    },
+                };
+            }
+            case 'follower_disconnect': {
+                return {
+                    type: 'follower_disconnect',
+                    senderId: msg.senderId,
+                    timestamp,
+                    payload: { tabId: msg.senderId },
+                };
+            }
+            case 'follower_send': {
+                const { requestId, expectedLeaderId, expectedElectionId, event, data, targetTabId, deadline, idempotencyKey, } = payload;
+                if (typeof requestId !== 'string' || !requestId || requestId.length > 128)
+                    return null;
+                if (typeof expectedLeaderId !== 'string' ||
+                    !expectedLeaderId ||
+                    expectedLeaderId.length > 128)
+                    return null;
+                if (typeof expectedElectionId !== 'string' ||
+                    !expectedElectionId ||
+                    expectedElectionId.length > 128)
+                    return null;
+                if (typeof event !== 'string' || !event || event.length > 128)
+                    return null;
+                if (typeof targetTabId !== 'string' || targetTabId !== msg.senderId)
+                    return null;
+                if (typeof deadline !== 'number' || !Number.isFinite(deadline) || deadline <= 0)
+                    return null;
+                if (deadline > Date.now() + 300000)
+                    return null; // Cap deadline at 5m
+                return {
+                    type: 'follower_send',
+                    senderId: msg.senderId,
+                    timestamp,
+                    payload: {
+                        requestId,
+                        expectedLeaderId,
+                        expectedElectionId,
+                        event,
+                        data,
+                        targetTabId,
+                        deadline,
+                        idempotencyKey: typeof idempotencyKey === 'string' && idempotencyKey.length <= 128
+                            ? idempotencyKey
+                            : undefined,
+                    },
+                };
+            }
+            case 'leader_elected':
+            case 'leader_state': {
+                const leaderId = msg.leaderId || payload.leaderId;
+                const electionId = msg.electionId || payload.electionId;
+                const termSeq = typeof msg.termSeq === 'number' ? msg.termSeq : payload.termSeq || 0;
+                if (typeof leaderId !== 'string' || !leaderId || leaderId !== msg.senderId)
+                    return null;
+                if (typeof electionId !== 'string' || !electionId)
+                    return null;
+                return {
+                    type,
+                    senderId: msg.senderId,
+                    leaderId,
+                    electionId,
+                    termSeq,
+                    timestamp,
+                    payload: {
+                        leaderId,
+                        electionId,
+                        isConnected: Boolean(payload.isConnected),
+                        termSeq,
+                    },
+                };
+            }
+            case 'leader_event': {
+                const leaderId = msg.leaderId || payload.leaderId;
+                const electionId = msg.electionId || payload.electionId;
+                if (typeof leaderId !== 'string' || !leaderId || leaderId !== msg.senderId)
+                    return null;
+                if (typeof electionId !== 'string' || !electionId)
+                    return null;
+                if (typeof payload.event !== 'string' || !payload.event)
+                    return null;
+                let targetTabIds;
+                if (Array.isArray(payload.targetTabIds)) {
+                    targetTabIds = payload.targetTabIds.filter((id) => typeof id === 'string' && id.length > 0 && id.length <= 128);
+                }
+                return {
+                    type: 'leader_event',
+                    senderId: msg.senderId,
+                    leaderId,
+                    electionId,
+                    timestamp,
+                    payload: {
+                        event: payload.event,
+                        data: payload.data,
+                        targetTabIds,
+                    },
+                };
+            }
+            case 'leader_send_response': {
+                const leaderId = msg.leaderId || payload.leaderId;
+                const electionId = msg.electionId || payload.electionId;
+                if (typeof leaderId !== 'string' || !leaderId || leaderId !== msg.senderId)
+                    return null;
+                if (typeof electionId !== 'string' || !electionId)
+                    return null;
+                if (typeof payload.requestId !== 'string' || !payload.requestId)
+                    return null;
+                if (typeof payload.targetTabId !== 'string' || !payload.targetTabId)
+                    return null;
+                let error;
+                if (payload.error) {
+                    if (typeof payload.error === 'object') {
+                        error = {
+                            name: String(payload.error.name || 'Error'),
+                            message: String(payload.error.message || 'Operation failed'),
+                            code: payload.error.code || 'unavailable',
+                            retryable: Boolean(payload.error.retryable),
+                            source: payload.error.source || 'server',
+                            isAmbiguous: Boolean(payload.error.isAmbiguous),
+                            details: payload.error.details,
+                        };
+                    }
+                    else if (typeof payload.error === 'string') {
+                        error = {
+                            name: 'Error',
+                            message: payload.error,
+                            code: 'unavailable',
+                            retryable: false,
+                            source: 'leader',
+                            isAmbiguous: false,
+                        };
+                    }
+                }
+                return {
+                    type: 'leader_send_response',
+                    senderId: msg.senderId,
+                    leaderId,
+                    electionId,
+                    timestamp,
+                    payload: {
+                        requestId: payload.requestId,
+                        targetTabId: payload.targetTabId,
+                        response: payload.response,
+                        error,
+                    },
+                };
+            }
+            default:
+                return null;
         }
     }
     handleBroadcastMessage(event) {
-        const { type, payload } = event.data;
+        if (this._state === 'disposed' ||
+            this._isSuspended ||
+            this._coordinationMode === 'independent') {
+            return;
+        }
+        const msg = this.validateBroadcastMessage(event.data);
+        if (!msg)
+            return;
         if (this.isLeader) {
-            if (type === 'follower_subscribe') {
-                this.socket?.emit('subscribe', this.projectId, payload.path);
+            this.handleMessageAsLeader(msg);
+        }
+        else {
+            this.handleMessageAsFollower(msg);
+        }
+    }
+    handleMessageAsLeader(msg) {
+        const senderId = msg.senderId;
+        if (msg.type === 'follower_subscribe') {
+            this.addFollowerPathSubscription(senderId, msg.payload.path);
+        }
+        else if (msg.type === 'follower_unsubscribe') {
+            this.removeFollowerPathSubscription(senderId, msg.payload.path);
+        }
+        else if (msg.type === 'follower_sync_request') {
+            this.postBroadcast('leader_state', {
+                leaderId: this._tabId,
+                electionId: this._electionId,
+                isConnected: this._isConnected,
+                termSeq: this._currentTermSeq,
+            });
+        }
+        else if (msg.type === 'follower_announce') {
+            this.handleFollowerAnnounce(senderId, msg.payload.paths, msg.payload.globalListenersCount);
+        }
+        else if (msg.type === 'follower_heartbeat') {
+            if (Array.isArray(msg.payload.paths)) {
+                this.handleFollowerAnnounce(senderId, msg.payload.paths, msg.payload.globalListenersCount);
+            }
+            else {
+                const existing = this.followerGlobalNeeds.get(senderId);
+                this.followerGlobalNeeds.set(senderId, {
+                    lastSeen: Date.now(),
+                    globalListenersCount: msg.payload.globalListenersCount,
+                    paths: existing?.paths,
+                });
             }
-            else if (type === 'follower_unsubscribe') {
-                this.socket?.emit('unsubscribe', this.projectId, payload.path);
+        }
+        else if (msg.type === 'follower_disconnect') {
+            this.pruneFollower(senderId);
+        }
+        else if (msg.type === 'follower_send') {
+            this.handleFollowerSendRequest(msg);
+        }
+    }
+    pruneDedupCache() {
+        const now = Date.now();
+        this.processedFollowerRequests.forEach((entry, key) => {
+            if (now - entry.timestamp > WebSocketClient.DEDUP_CACHE_TTL_MS) {
+                this.processedFollowerRequests.delete(key);
             }
-            else if (type === 'follower_sync_request') {
-                this.broadcastChannel?.postMessage({ type: 'leader_state', payload: { isConnected: this.isConnected } });
+        });
+        if (this.processedFollowerRequests.size > WebSocketClient.MAX_DEDUP_CACHE_SIZE) {
+            const keysToDelete = Array.from(this.processedFollowerRequests.keys()).slice(0, this.processedFollowerRequests.size - WebSocketClient.MAX_DEDUP_CACHE_SIZE);
+            for (const k of keysToDelete) {
+                this.processedFollowerRequests.delete(k);
             }
         }
-        else {
-            if (type === 'leader_event') {
-                const { event: socketEvent, data } = payload;
+    }
+    handleFollowerSendRequest(msg) {
+        const { requestId, expectedLeaderId, expectedElectionId, event, data, targetTabId, deadline, idempotencyKey, } = msg.payload;
+        const senderId = msg.senderId;
+        // Strict Term Fencing: Ignore if not addressed to this leader's active term
+        if (!this.isLeader ||
+            !this._electionId ||
+            expectedLeaderId !== this._tabId ||
+            expectedElectionId !== this._electionId) {
+            return;
+        }
+        if (Date.now() >= deadline)
+            return; // Expired
+        this.pruneDedupCache();
+        // Bounded Deduplication: if already processed, return cached response directly
+        const cached = this.processedFollowerRequests.get(requestId);
+        if (cached) {
+            this.postBroadcast('leader_send_response', {
+                requestId,
+                targetTabId: senderId,
+                response: cached.response,
+                error: cached.error,
+            });
+            return;
+        }
+        // If currently executing, do not duplicate
+        if (this.activeLeaderSends.has(requestId)) {
+            return;
+        }
+        const currentElectionId = this._electionId;
+        const isMutating = WebSocketClient.isMutatingEvent(event);
+        const execution = {
+            requestId,
+            cancelled: false,
+            timer: null,
+            cleanup: () => {
+                if (execution.timer) {
+                    clearTimeout(execution.timer);
+                    execution.timer = null;
+                }
+                this.activeLeaderSends.delete(requestId);
+            },
+        };
+        this.activeLeaderSends.set(requestId, execution);
+        const payloadData = idempotencyKey && data && typeof data === 'object'
+            ? { ...data, idempotencyKey }
+            : data;
+        this.executeSendAsLeader(event, payloadData, deadline)
+            .then((response) => {
+            execution.cleanup();
+            if (execution.cancelled || this._state === 'disposed' || !this.isLeader)
+                return;
+            this.processedFollowerRequests.set(requestId, {
+                timestamp: Date.now(),
+                response,
+            });
+            this.postBroadcast('leader_send_response', {
+                requestId,
+                targetTabId: senderId,
+                response,
+            });
+        })
+            .catch((error) => {
+            execution.cleanup();
+            if (execution.cancelled || this._state === 'disposed' || !this.isLeader)
+                return;
+            const isAmbiguous = isMutating &&
+                (this._electionId !== currentElectionId ||
+                    !this._isConnected ||
+                    (error instanceof NexaWebSocketError && error.isAmbiguous));
+            const structuredErr = error instanceof NexaWebSocketError
+                ? { ...error.toJSON(), isAmbiguous: isAmbiguous || error.isAmbiguous }
+                : {
+                    name: error?.name || 'Error',
+                    message: error?.message || 'Send error',
+                    code: isAmbiguous ? 'ambiguous-outcome' : 'unavailable',
+                    retryable: !isAmbiguous,
+                    source: 'leader',
+                    isAmbiguous,
+                };
+            this.processedFollowerRequests.set(requestId, {
+                timestamp: Date.now(),
+                error: structuredErr,
+            });
+            this.postBroadcast('leader_send_response', {
+                requestId,
+                targetTabId: senderId,
+                error: structuredErr,
+            });
+        });
+    }
+    handleMessageAsFollower(msg) {
+        if (msg.type === 'leader_elected' ||
+            msg.type === 'leader_state' ||
+            msg.type === 'leader_event' ||
+            msg.type === 'leader_send_response') {
+            if (msg.type === 'leader_elected' || msg.type === 'leader_state') {
+                const { leaderId, electionId, isConnected, termSeq } = msg.payload;
+                // Fencing: Reject messages from older term sequences
+                if (termSeq < this._currentTermSeq) {
+                    return;
+                }
+                const isNewTerm = this._currentLeaderId !== leaderId || this._currentElectionId !== electionId;
+                if (isNewTerm) {
+                    this._currentLeaderId = leaderId;
+                    this._currentElectionId = electionId;
+                    this._currentTermSeq = termSeq;
+                    // Invalidate and reject all pending follower sends tied to the older term
+                    this.pendingSendRequests.forEach((req, reqId) => {
+                        if (req.expectedElectionId !== electionId || req.expectedLeaderId !== leaderId) {
+                            clearTimeout(req.timer);
+                            this.pendingSendRequests.delete(reqId);
+                            req.reject(new NexaWebSocketError({
+                                message: 'Leadership term changed while request was pending',
+                                code: req.isMutating ? 'ambiguous-outcome' : 'leader-changed',
+                                isAmbiguous: req.isMutating,
+                                source: 'leader',
+                            }));
+                        }
+                    });
+                }
+                this._isLeaderSocketConnected = isConnected;
+                this.updateFollowerConnectionState(isConnected);
+                if (isNewTerm) {
+                    this.announceNeedsToLeader();
+                }
+                this.checkReadinessWaiters();
+                return;
+            }
+            // Strict Term Fencing for leader events and responses
+            if (!this._currentLeaderId ||
+                !this._currentElectionId ||
+                msg.leaderId !== this._currentLeaderId ||
+                msg.electionId !== this._currentElectionId) {
+                return; // Reject messages from non-active or stale leadership term
+            }
+            if (msg.type === 'leader_event') {
+                const { event: socketEvent, data, targetTabIds } = msg.payload;
+                if (Array.isArray(targetTabIds) && !targetTabIds.includes(this._tabId)) {
+                    return; // Event was targeted to other tabs
+                }
                 if (socketEvent === 'connect') {
-                    this.isConnected = true;
-                    this.dispatch('open', data);
+                    this._isLeaderSocketConnected = true;
+                    this.updateFollowerConnectionState(true);
+                    this.checkReadinessWaiters();
                 }
                 else if (socketEvent === 'disconnect') {
-                    this.isConnected = false;
-                    this.dispatch('close', data);
+                    this._isLeaderSocketConnected = false;
+                    this.updateFollowerConnectionState(false);
+                }
+                else if (socketEvent === 'error') {
+                    this.dispatch('error', data);
                 }
                 else {
                     this.dispatch(socketEvent, data);
@@ -51,147 +944,598 @@ class WebSocketClient {
                     }
                 }
             }
-            else if (type === 'leader_state') {
-                this.isConnected = payload.isConnected;
-                if (this.isConnected) {
-                    this.dispatch('open', {});
+            else if (msg.type === 'leader_send_response') {
+                const { requestId, targetTabId, response, error } = msg.payload;
+                if (targetTabId === this._tabId && requestId && this.pendingSendRequests.has(requestId)) {
+                    const req = this.pendingSendRequests.get(requestId);
+                    clearTimeout(req.timer);
+                    this.pendingSendRequests.delete(requestId);
+                    if (error) {
+                        req.reject(NexaWebSocketError.from(error, 'server'));
+                    }
+                    else {
+                        req.resolve(response);
+                    }
                 }
             }
         }
     }
+    updateFollowerConnectionState(connected) {
+        this._isConnected = connected;
+        if (connected && !this._lastReportedConnected) {
+            this._lastReportedConnected = true;
+            this.dispatch('open', { socketId: 'follower' });
+        }
+        else if (!connected && this._lastReportedConnected) {
+            this._lastReportedConnected = false;
+            this.dispatch('close', { reason: 'leader disconnected' });
+        }
+    }
+    handleFollowerAnnounce(senderId, paths, globalListenersCount) {
+        const validPaths = new Set();
+        for (const p of paths) {
+            const clean = WebSocketClient.cleanAndValidatePath(p);
+            if (clean)
+                validPaths.add(clean);
+        }
+        const prevPaths = this.followerSubscriptionsByTab.get(senderId) || new Set();
+        this.followerSubscriptionsByTab.set(senderId, validPaths);
+        // Remove obsolete subscriptions
+        for (const p of prevPaths) {
+            if (!validPaths.has(p)) {
+                this.removeFollowerPathSubscription(senderId, p);
+            }
+        }
+        // Add newly declared subscriptions
+        for (const p of validPaths) {
+            if (!prevPaths.has(p)) {
+                this.addFollowerPathSubscription(senderId, p);
+            }
+        }
+        this.followerGlobalNeeds.set(senderId, {
+            lastSeen: Date.now(),
+            globalListenersCount: Math.max(0, Math.floor(globalListenersCount || 0)),
+            paths: validPaths,
+        });
+    }
+    announceNeedsToLeader() {
+        if (this._state === 'disposed' ||
+            this._isSuspended ||
+            this.isLeader ||
+            this._coordinationMode === 'independent') {
+            return;
+        }
+        const paths = Array.from(this.localSubscribedPaths.keys());
+        const globalCount = this.getGlobalListenersCount();
+        this.postBroadcast('follower_announce', {
+            paths,
+            globalListenersCount: globalCount,
+        });
+    }
+    announceGlobalListenersChange() {
+        if (this._state === 'disposed' ||
+            this._isSuspended ||
+            this.isLeader ||
+            this._coordinationMode === 'independent') {
+            return;
+        }
+        this.postBroadcast('follower_heartbeat', {
+            globalListenersCount: this.getGlobalListenersCount(),
+            paths: Array.from(this.localSubscribedPaths.keys()),
+        });
+    }
+    getGlobalListenersCount() {
+        let count = 0;
+        this.listeners.forEach((set, evt) => {
+            if (evt !== 'data_changed' &&
+                evt !== 'firestore_changed' &&
+                evt !== 'message' &&
+                evt !== 'all' &&
+                evt !== 'open' &&
+                evt !== 'close' &&
+                evt !== 'error' &&
+                evt !== 'resync') {
+                count += set.size;
+            }
+        });
+        return count;
+    }
+    addFollowerPathSubscription(tabId, cleanPath) {
+        let tabSubs = this.followerSubscriptionsByTab.get(tabId);
+        if (!tabSubs) {
+            tabSubs = new Set();
+            this.followerSubscriptionsByTab.set(tabId, tabSubs);
+        }
+        tabSubs.add(cleanPath);
+        let pathSubs = this.followerSubscriptions.get(cleanPath);
+        if (!pathSubs) {
+            pathSubs = new Set();
+            this.followerSubscriptions.set(cleanPath, pathSubs);
+        }
+        const prevTotal = pathSubs.size + (this.localSubscribedPaths.get(cleanPath) || 0);
+        pathSubs.add(tabId);
+        const newTotal = pathSubs.size + (this.localSubscribedPaths.get(cleanPath) || 0);
+        if (prevTotal === 0 && newTotal > 0 && this._socket && this._isConnected) {
+            this._socket.emit('subscribe', this._projectId, cleanPath);
+        }
+    }
+    removeFollowerPathSubscription(tabId, cleanPath) {
+        const tabSubs = this.followerSubscriptionsByTab.get(tabId);
+        if (tabSubs) {
+            tabSubs.delete(cleanPath);
+            if (tabSubs.size === 0) {
+                this.followerSubscriptionsByTab.delete(tabId);
+            }
+        }
+        const pathSubs = this.followerSubscriptions.get(cleanPath);
+        if (!pathSubs)
+            return;
+        const prevTotal = pathSubs.size + (this.localSubscribedPaths.get(cleanPath) || 0);
+        pathSubs.delete(tabId);
+        if (pathSubs.size === 0) {
+            this.followerSubscriptions.delete(cleanPath);
+        }
+        const newTotal = (this.followerSubscriptions.get(cleanPath)?.size || 0) +
+            (this.localSubscribedPaths.get(cleanPath) || 0);
+        if (prevTotal > 0 && newTotal === 0 && this._socket && this._isConnected) {
+            this._socket.emit('unsubscribe', this._projectId, cleanPath);
+        }
+    }
+    pruneFollower(tabId) {
+        const tabSubs = this.followerSubscriptionsByTab.get(tabId);
+        if (tabSubs) {
+            tabSubs.forEach((path) => {
+                this.removeFollowerPathSubscription(tabId, path);
+            });
+            this.followerSubscriptionsByTab.delete(tabId);
+        }
+        this.followerGlobalNeeds.delete(tabId);
+        this.checkCloseConnection();
+    }
+    startFollowerHeartbeat() {
+        if (this.heartbeatTimer ||
+            typeof window === 'undefined' ||
+            this._coordinationMode === 'independent') {
+            return;
+        }
+        this.heartbeatTimer = setInterval(() => {
+            if (this._state === 'follower' && !this._isSuspended) {
+                this.postBroadcast('follower_heartbeat', {
+                    globalListenersCount: this.getGlobalListenersCount(),
+                    paths: Array.from(this.localSubscribedPaths.keys()),
+                });
+            }
+        }, this.heartbeatIntervalMs);
+        if (typeof this.heartbeatTimer?.unref === 'function') {
+            this.heartbeatTimer.unref();
+        }
+    }
+    stopFollowerHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    startLeaderPruneTimer() {
+        if (this.pruneTimer ||
+            typeof window === 'undefined' ||
+            this._coordinationMode === 'independent') {
+            return;
+        }
+        this.pruneTimer = setInterval(() => {
+            if (this.isLeader && !this._isSuspended) {
+                const now = Date.now();
+                this.followerGlobalNeeds.forEach((data, tabId) => {
+                    if (now - data.lastSeen > this.followerTtlMs) {
+                        this.pruneFollower(tabId);
+                    }
+                });
+            }
+        }, this.pruneIntervalMs);
+        if (typeof this.pruneTimer?.unref === 'function') {
+            this.pruneTimer.unref();
+        }
+    }
+    stopLeaderPruneTimer() {
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+    }
+    startLeaderLeaseTimer() {
+        if (this.leaseTimer ||
+            typeof window === 'undefined' ||
+            this._coordinationMode === 'independent') {
+            return;
+        }
+        this.leaseTimer = setInterval(() => {
+            if (this.isLeader && !this._isSuspended) {
+                this.postBroadcast('leader_state', {
+                    leaderId: this._tabId,
+                    electionId: this._electionId,
+                    isConnected: this._isConnected,
+                    termSeq: this._currentTermSeq,
+                });
+            }
+        }, this.leaderLeaseIntervalMs);
+        if (typeof this.leaseTimer?.unref === 'function') {
+            this.leaseTimer.unref();
+        }
+    }
+    stopLeaderLeaseTimer() {
+        if (this.leaseTimer) {
+            clearInterval(this.leaseTimer);
+            this.leaseTimer = null;
+        }
+    }
+    /**
+     * Subscribes an event listener callback with reference counting and connection management.
+     */
     addListener(event, callback) {
-        if (!this.listeners.has(event)) {
-            this.listeners.set(event, new Set());
+        if (typeof event !== 'string' || !event.trim()) {
+            throw new NexaWebSocketError({
+                message: 'Invalid event: must be a non-empty string',
+                code: 'invalid-argument',
+            });
+        }
+        if (typeof callback !== 'function') {
+            throw new NexaWebSocketError({
+                message: 'Invalid callback: must be a function',
+                code: 'invalid-argument',
+            });
         }
-        this.listeners.get(event).add(callback);
+        if (this._state === 'disposed')
+            return () => { };
+        const cleanEvent = event.trim();
+        if (!this.listeners.has(cleanEvent)) {
+            this.listeners.set(cleanEvent, new Set());
+        }
+        this.listeners.get(cleanEvent).add(callback);
         this.ensureConnected();
+        this.announceGlobalListenersChange();
         return () => {
-            const callbacks = this.listeners.get(event);
+            const callbacks = this.listeners.get(cleanEvent);
             if (callbacks) {
                 callbacks.delete(callback);
                 if (callbacks.size === 0) {
-                    this.listeners.delete(event);
+                    this.listeners.delete(cleanEvent);
                 }
             }
+            this.announceGlobalListenersChange();
             this.checkCloseConnection();
         };
     }
+    /**
+     * Reference-counted path subscription.
+     */
     subscribe(path) {
-        const cleanPath = (path || '').replace(/^\/+|\/+$/g, '');
-        this.subscribedPaths.add(cleanPath);
-        if (this.isLeader && this.socket && this.isConnected) {
-            this.socket.emit('subscribe', this.projectId, cleanPath);
-        }
-        else if (!this.isLeader && this.broadcastChannel) {
-            this.broadcastChannel.postMessage({ type: 'follower_subscribe', payload: { path: cleanPath } });
+        if (this._state === 'disposed')
+            return;
+        const cleanPath = WebSocketClient.validatePathOrThrow(path);
+        const currentCount = this.localSubscribedPaths.get(cleanPath) || 0;
+        this.localSubscribedPaths.set(cleanPath, currentCount + 1);
+        this.ensureConnected();
+        if (currentCount === 0) {
+            if (this.isLeader || this._coordinationMode === 'independent') {
+                const followerCount = this.followerSubscriptions.get(cleanPath)?.size || 0;
+                if (followerCount === 0 && this._socket && this._isConnected) {
+                    this._socket.emit('subscribe', this._projectId, cleanPath);
+                }
+            }
+            else {
+                this.postBroadcast('follower_subscribe', { path: cleanPath });
+            }
         }
     }
+    /**
+     * Decrements reference-counted path subscription.
+     */
     unsubscribe(path) {
-        const cleanPath = (path || '').replace(/^\/+|\/+$/g, '');
-        this.subscribedPaths.delete(cleanPath);
-        if (this.isLeader && this.socket && this.isConnected) {
-            this.socket.emit('unsubscribe', this.projectId, cleanPath);
+        if (this._state === 'disposed')
+            return;
+        const cleanPath = WebSocketClient.validatePathOrThrow(path);
+        const currentCount = this.localSubscribedPaths.get(cleanPath) || 0;
+        if (currentCount <= 0)
+            return;
+        if (currentCount === 1) {
+            this.localSubscribedPaths.delete(cleanPath);
+            if (this.isLeader || this._coordinationMode === 'independent') {
+                const followerCount = this.followerSubscriptions.get(cleanPath)?.size || 0;
+                if (followerCount === 0 && this._socket && this._isConnected) {
+                    this._socket.emit('unsubscribe', this._projectId, cleanPath);
+                }
+            }
+            else {
+                this.postBroadcast('follower_unsubscribe', { path: cleanPath });
+            }
         }
-        else if (!this.isLeader && this.broadcastChannel) {
-            this.broadcastChannel.postMessage({ type: 'follower_unsubscribe', payload: { path: cleanPath } });
+        else {
+            this.localSubscribedPaths.set(cleanPath, currentCount - 1);
         }
+        this.checkCloseConnection();
     }
-    broadcastToFollowers(event, data) {
-        if (this.isLeader && this.broadcastChannel) {
-            this.broadcastChannel.postMessage({ type: 'leader_event', payload: { event, data } });
+    broadcastToFollowers(event, data, targetTabIds) {
+        if (this.isLeader && this._coordinationMode === 'shared') {
+            this.postBroadcast('leader_event', { event, data, targetTabIds });
         }
     }
+    /**
+     * Connects socket directly or coordinates election via Web Locks.
+     */
     ensureConnected() {
-        if (this.hasInitialized || typeof window === 'undefined')
+        if (this._state !== 'idle' || this._isSuspended || typeof window === 'undefined')
             return;
-        this.hasInitialized = true;
-        if (navigator.locks) {
-            navigator.locks.request(`nexabase_ws_leader_${this.projectId}`, { mode: 'exclusive', ifAvailable: false }, async (lock) => {
-                // This promise won't resolve until we explicitly return from it (which we only do on close)
+        if (this._coordinationMode === 'independent') {
+            this.transitionTo('leader');
+            this._electionId = WebSocketClient.generateId();
+            this._currentLeaderId = this._tabId;
+            this._currentElectionId = this._electionId;
+            this._currentTermSeq++;
+            this.startSocketConnection();
+            return;
+        }
+        this.transitionTo('electing');
+        const locksManager = this._options.locks || (typeof navigator !== 'undefined' ? navigator.locks : null);
+        if (locksManager && this.broadcastChannel) {
+            this.lockAbortController = new AbortController();
+            const lockName = `nexabase_lock_${this._coordinationKey}`;
+            this.transitionTo('follower');
+            this.startFollowerHeartbeat();
+            this.postBroadcast('follower_sync_request');
+            locksManager
+                .request(lockName, { signal: this.lockAbortController.signal }, async () => {
+                const current = this._state;
+                if (current === 'disposed' ||
+                    current === 'disconnecting' ||
+                    this._isSuspended) {
+                    return;
+                }
+                this.stopFollowerHeartbeat();
+                this.transitionTo('leader');
+                this._electionId = WebSocketClient.generateId();
+                this._currentLeaderId = this._tabId;
+                this._currentElectionId = this._electionId;
+                this._currentTermSeq++;
+                // Invalidate pending follower requests tied to older term
+                this.pendingSendRequests.forEach((req, reqId) => {
+                    clearTimeout(req.timer);
+                    this.pendingSendRequests.delete(reqId);
+                    req.reject(new NexaWebSocketError({
+                        message: 'Leadership term changed while request was pending',
+                        code: req.isMutating ? 'ambiguous-outcome' : 'leader-changed',
+                        isAmbiguous: req.isMutating,
+                        source: 'leader',
+                    }));
+                });
+                this.startLeaderPruneTimer();
+                this.startLeaderLeaseTimer();
+                this.startSocketConnection();
+                this.postBroadcast('leader_elected', {
+                    leaderId: this._tabId,
+                    electionId: this._electionId,
+                    isConnected: this._isConnected,
+                    termSeq: this._currentTermSeq,
+                });
+                this.checkReadinessWaiters();
                 return new Promise((resolve) => {
-                    this.isLeader = true;
-                    this.startSocketConnection();
-                    // If we are closed intentionally, resolve the lock
-                    const originalClose = this.close.bind(this);
-                    this.close = () => {
-                        originalClose();
-                        resolve();
-                    };
+                    this.resolveLeaderLock = resolve;
                 });
-            }).catch(() => {
-                // We are a follower
-                this.isLeader = false;
-                this.broadcastChannel?.postMessage({ type: 'follower_sync_request' });
+            })
+                .catch((err) => {
+                if (err?.name === 'AbortError')
+                    return; // Intentional abort on close/suspend
+                console.warn('[WebSocketClient] Web Lock failed, switching to independent mode:', err);
+                if (this._state !== 'disposed' && !this._isSuspended) {
+                    this.switchToIndependentMode('lock_error');
+                }
             });
         }
         else {
-            // Fallback if no Web Locks API
-            this.isLeader = true;
-            this.startSocketConnection();
+            this.switchToIndependentMode('no_locks_or_bc');
         }
     }
-    startSocketConnection() {
-        this.socket = (0, socket_io_client_1.io)(this.serverUrl, {
+    async startSocketConnection() {
+        if (this._socket || this._state === 'disposed' || this._isSuspended)
+            return;
+        const authPayload = await this.getFreshAuthPayload();
+        const socketOptions = {
             transports: ['websocket', 'polling'],
             autoConnect: true,
             reconnection: true,
             reconnectionDelay: 1000,
+        };
+        if (authPayload) {
+            socketOptions.auth = authPayload;
+        }
+        if (typeof this._options.socketFactory === 'function') {
+            this._socket = this._options.socketFactory(this._serverUrl, socketOptions);
+        }
+        else {
+            this._socket = (0, socket_io_client_1.io)(this._serverUrl, socketOptions);
+        }
+        const onConnectHandler = () => {
+            this._isConnected = true;
+            this._isLeaderSocketConnected = true;
+            if (!this._lastReportedConnected) {
+                this._lastReportedConnected = true;
+                this.dispatch('open', { socketId: this._socket?.id });
+            }
+            this.broadcastToFollowers('connect', { socketId: this._socket?.id });
+            // Resubscribe all local + follower active paths
+            const allPaths = new Set(this.localSubscribedPaths.keys());
+            this.followerSubscriptions.forEach((set, path) => {
+                if (set.size > 0)
+                    allPaths.add(path);
+            });
+            allPaths.forEach((path) => {
+                if (path && this._socket) {
+                    this._socket.emit('subscribe', this._projectId, path);
+                }
+            });
+            this.checkReadinessWaiters();
+        };
+        this._socket.on('connect', onConnectHandler);
+        if (this._socket.connected) {
+            onConnectHandler();
+        }
+        this._socket.on('data_changed', (payload) => {
+            this.handleSocketDataEvent('data_changed', payload);
+        });
+        this._socket.on('firestore_changed', (payload) => {
+            this.handleSocketDataEvent('firestore_changed', payload);
         });
-        this.socket.on('connect', () => {
-            this.isConnected = true;
-            this.dispatch('open', { socketId: this.socket?.id });
-            this.broadcastToFollowers('connect', { socketId: this.socket?.id });
-            // Always join project room
-            this.socket?.emit('subscribe', this.projectId, '');
-            // Resubscribe to all paths
-            this.subscribedPaths.forEach((path) => {
-                this.socket?.emit('subscribe', this.projectId, path);
-            });
-        });
-        this.socket.on('data_changed', (payload) => {
-            this.dispatch('data_changed', payload);
-            this.dispatch('message', payload);
-            this.dispatch('all', payload);
-            this.broadcastToFollowers('data_changed', payload);
-        });
-        this.socket.on('firestore_changed', (payload) => {
-            this.dispatch('firestore_changed', payload);
-            this.dispatch('message', payload);
-            this.dispatch('all', payload);
-            this.broadcastToFollowers('firestore_changed', payload);
-        });
-        this.socket.on('activity_logged', (payload) => {
+        this._socket.on('activity_logged', (payload) => {
             this.dispatch('activity_logged', payload);
             this.broadcastToFollowers('activity_logged', payload);
         });
-        this.socket.on('stats_update', (payload) => {
+        this._socket.on('stats_update', (payload) => {
             this.dispatch('stats_update', payload);
             this.broadcastToFollowers('stats_update', payload);
         });
-        this.socket.on('connect_error', (err) => {
-            this.dispatch('error', err);
-            this.broadcastToFollowers('connect_error', err);
+        this._socket.on('connect_error', (err) => {
+            const errObj = {
+                name: err?.name || 'ConnectError',
+                message: err?.message || String(err),
+                code: 'unavailable',
+                retryable: true,
+                source: 'server',
+                isAmbiguous: false,
+            };
+            this.dispatch('error', errObj);
+            this.broadcastToFollowers('error', errObj);
         });
-        this.socket.on('disconnect', (reason) => {
-            this.isConnected = false;
-            this.dispatch('close', { reason });
+        this._socket.on('disconnect', (reason) => {
+            this._isConnected = false;
+            this._isLeaderSocketConnected = false;
+            if (this._lastReportedConnected) {
+                this._lastReportedConnected = false;
+                this.dispatch('close', { reason });
+            }
             this.broadcastToFollowers('disconnect', { reason });
+            // Handle non-reconnecting disconnects (e.g. io server disconnect)
+            if (reason === 'io server disconnect' &&
+                this._state !== 'disposed' &&
+                !this._isSuspended &&
+                this.isLeader &&
+                this.hasNetworkNeeds()) {
+                if (this.reconnectTimer)
+                    clearTimeout(this.reconnectTimer);
+                this.reconnectTimer = setTimeout(async () => {
+                    if (this._state !== 'disposed' &&
+                        !this._isSuspended &&
+                        this.isLeader &&
+                        this.hasNetworkNeeds()) {
+                        const freshAuth = await this.getFreshAuthPayload();
+                        if (this._socket) {
+                            if (freshAuth)
+                                this._socket.auth = freshAuth;
+                            this._socket.connect();
+                        }
+                    }
+                }, 1000);
+            }
         });
     }
-    send(event, data) {
+    isLocalSubscribedToPath(eventPath) {
+        for (const subPath of this.localSubscribedPaths.keys()) {
+            if (WebSocketClient.isPathMatch(eventPath, subPath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    handleSocketDataEvent(eventName, payload) {
+        const pathResult = WebSocketClient.extractPayloadPathTriState(payload);
+        // If an invalid path was supplied, reject/quarantine to prevent malicious or malformed global broadcast
+        if (pathResult.status === 'invalid') {
+            console.warn(`[WebSocketClient] Quarantined event "${eventName}" with malformed path:`, pathResult.raw);
+            return;
+        }
+        const eventPath = pathResult.status === 'valid' ? pathResult.path : null;
+        // For data_changed / firestore_changed: if no path was provided and no explicit global marker is present, reject
+        if (!eventPath && (eventName === 'data_changed' || eventName === 'firestore_changed')) {
+            const isExplicitGlobal = Boolean(payload && typeof payload === 'object' && payload.isGlobal);
+            if (!isExplicitGlobal) {
+                console.warn(`[WebSocketClient] Ignored un-targeted change event "${eventName}" without path`);
+                return;
+            }
+        }
+        const shouldDispatchLocally = eventPath ? this.isLocalSubscribedToPath(eventPath) : true;
+        if (shouldDispatchLocally) {
+            this.dispatch(eventName, payload);
+            if (eventName === 'data_changed' || eventName === 'firestore_changed') {
+                this.dispatch('message', payload);
+                this.dispatch('all', payload);
+            }
+        }
+        // Route targeted event to matching follower tabs
+        let targetTabIds;
+        if (eventPath) {
+            const targets = new Set();
+            this.followerSubscriptions.forEach((subTabs, subPath) => {
+                if (WebSocketClient.isPathMatch(eventPath, subPath)) {
+                    subTabs.forEach((id) => targets.add(id));
+                }
+            });
+            targetTabIds = Array.from(targets);
+        }
+        else {
+            targetTabIds = undefined;
+        }
+        this.broadcastToFollowers(eventName, payload, targetTabIds);
+    }
+    executeSendAsLeader(event, data, deadline) {
         return new Promise((resolve, reject) => {
-            this.ensureConnected();
-            if (!this.socket && this.isLeader) {
-                return reject(new Error('WebSocket client unavailable'));
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                return reject(new NexaWebSocketError({
+                    message: `Send operation timed out before execution for event "${event}"`,
+                    code: 'timeout',
+                    source: 'leader',
+                }));
             }
-            if (!this.isLeader) {
-                // Followers can't send via websocket directly in this design without more plumbing.
-                // We fallback to standard HTTP API for writes anyway.
-                return reject(new Error('Cannot send WebSocket message from follower tab'));
+            if (!this._socket || !this._isConnected) {
+                return reject(new NexaWebSocketError({
+                    message: 'WebSocket client unavailable or disconnected',
+                    code: 'disconnected',
+                    source: 'leader',
+                }));
             }
-            this.socket.emit(event, data, (response) => {
+            const requestId = `leader_send_${WebSocketClient.generateId()}`;
+            let completed = false;
+            const cleanup = () => {
+                completed = true;
+                if (execution.timer) {
+                    clearTimeout(execution.timer);
+                    execution.timer = null;
+                }
+                this.activeLeaderSends.delete(requestId);
+            };
+            const timer = setTimeout(() => {
+                if (completed)
+                    return;
+                cleanup();
+                const isMutating = WebSocketClient.isMutatingEvent(event);
+                reject(new NexaWebSocketError({
+                    message: `WebSocket send timeout for event "${event}"`,
+                    code: isMutating ? 'ambiguous-outcome' : 'timeout',
+                    isAmbiguous: isMutating,
+                    source: 'leader',
+                }));
+            }, remainingMs);
+            const execution = {
+                requestId,
+                cancelled: false,
+                timer,
+                cleanup,
+            };
+            this.activeLeaderSends.set(requestId, execution);
+            this._socket.emit(event, data, (response) => {
+                if (completed || execution.cancelled || this._state === 'disposed')
+                    return;
+                cleanup();
                 if (response && response.error) {
-                    reject(new Error(response.error));
+                    reject(NexaWebSocketError.from(response.error, 'server'));
                 }
                 else {
                     resolve(response);
@@ -199,13 +1543,226 @@ class WebSocketClient {
             });
         });
     }
+    checkReadinessWaiters() {
+        if (this.readinessWaiters.size === 0)
+            return;
+        const isReady = this._state === 'disposed' ||
+            (this.isLeader && this._isConnected) ||
+            (this._coordinationMode === 'independent' && this._isConnected) ||
+            (this._state === 'follower' &&
+                this._currentLeaderId !== null &&
+                this._currentElectionId !== null &&
+                this._isLeaderSocketConnected);
+        if (!isReady)
+            return;
+        const waiters = Array.from(this.readinessWaiters);
+        this.readinessWaiters.clear();
+        waiters.forEach((waiter) => {
+            clearTimeout(waiter.timer);
+            if (this._state === 'disposed') {
+                waiter.reject(new NexaWebSocketError({
+                    message: 'WebSocketClient is disposed',
+                    code: 'disposed',
+                }));
+            }
+            else {
+                waiter.resolve();
+            }
+        });
+    }
+    waitForReady(deadline) {
+        if (this._state === 'disposed') {
+            return Promise.reject(new NexaWebSocketError({
+                message: 'WebSocketClient is disposed',
+                code: 'disposed',
+            }));
+        }
+        const isReady = (this.isLeader && this._isConnected) ||
+            (this._coordinationMode === 'independent' && this._isConnected) ||
+            (this._state === 'follower' &&
+                this._currentLeaderId !== null &&
+                this._currentElectionId !== null &&
+                this._isLeaderSocketConnected);
+        if (isReady) {
+            return Promise.resolve();
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            return Promise.reject(new NexaWebSocketError({
+                message: 'Send operation timed out waiting for connection/leader',
+                code: 'connection-timeout',
+            }));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.readinessWaiters.delete(waiter);
+                reject(new NexaWebSocketError({
+                    message: 'Send operation timed out waiting for connection/leader',
+                    code: 'connection-timeout',
+                }));
+            }, remainingMs);
+            const waiter = { deadline, resolve, reject, timer };
+            this.readinessWaiters.add(waiter);
+        });
+    }
+    static isMutatingEvent(event) {
+        const lower = event.toLowerCase();
+        return (lower.includes('write') ||
+            lower.includes('set') ||
+            lower.includes('update') ||
+            lower.includes('delete') ||
+            lower.includes('patch') ||
+            lower.includes('create') ||
+            lower.includes('batch') ||
+            lower.includes('transaction'));
+    }
+    /**
+     * Production-hardened request execution with invariant counter handling in a single finally block.
+     */
+    async send(event, data, timeoutMs) {
+        if (typeof event !== 'string' || !event.trim()) {
+            throw new NexaWebSocketError({
+                message: 'Invalid event: must be a non-empty string',
+                code: 'invalid-argument',
+            });
+        }
+        if (WebSocketClient.RESERVED_SEND_EVENTS.has(event.trim().toLowerCase())) {
+            throw new NexaWebSocketError({
+                message: `Event "${event}" is reserved by the WebSocket transport protocol`,
+                code: 'invalid-argument',
+            });
+        }
+        if (this._state === 'disposed') {
+            throw new NexaWebSocketError({
+                message: 'WebSocketClient is disposed',
+                code: 'disposed',
+            });
+        }
+        const effectiveTimeout = typeof timeoutMs === 'number'
+            ? timeoutMs
+            : typeof this.defaultTimeoutMs === 'number'
+                ? this.defaultTimeoutMs
+                : WebSocketClient.DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(effectiveTimeout) || effectiveTimeout <= 0) {
+            throw new NexaWebSocketError({
+                message: `Invalid timeout value: ${effectiveTimeout}. Must be a positive finite number.`,
+                code: 'invalid-argument',
+            });
+        }
+        const deadline = Date.now() + Math.min(effectiveTimeout, 300000);
+        const isMutating = WebSocketClient.isMutatingEvent(event);
+        // Invariant: Counter is incremented exactly once here
+        this.activeLocalSendsCount++;
+        try {
+            this.ensureConnected();
+            await this.waitForReady(deadline);
+            if (this._state === 'disposed') {
+                throw new NexaWebSocketError({
+                    message: 'WebSocketClient is disposed',
+                    code: 'disposed',
+                });
+            }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                throw new NexaWebSocketError({
+                    message: `Send operation timed out for event "${event}"`,
+                    code: 'timeout',
+                });
+            }
+            if (this.isLeader || this._coordinationMode === 'independent') {
+                return await this.executeSendAsLeader(event, data, deadline);
+            }
+            // Follower tab: forward to active leader via BroadcastChannel
+            const expectedLeaderId = this._currentLeaderId;
+            const expectedElectionId = this._currentElectionId;
+            if (!expectedLeaderId || !expectedElectionId) {
+                throw new NexaWebSocketError({
+                    message: 'No active leader elected to forward request',
+                    code: 'unavailable',
+                    source: 'follower',
+                });
+            }
+            const requestId = `req_${WebSocketClient.generateId()}`;
+            const idempotencyKey = isMutating ? `idem_${WebSocketClient.generateId()}` : undefined;
+            return await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pendingSendRequests.delete(requestId);
+                    reject(new NexaWebSocketError({
+                        message: `Follower send timeout for event "${event}"`,
+                        code: isMutating ? 'ambiguous-outcome' : 'timeout',
+                        isAmbiguous: isMutating,
+                        source: 'follower',
+                    }));
+                }, remainingMs);
+                this.pendingSendRequests.set(requestId, {
+                    requestId,
+                    resolve,
+                    reject,
+                    timer,
+                    deadline,
+                    expectedLeaderId,
+                    expectedElectionId,
+                    isMutating,
+                });
+                const posted = this.postBroadcast('follower_send', {
+                    requestId,
+                    expectedLeaderId,
+                    expectedElectionId,
+                    event,
+                    data,
+                    targetTabId: this._tabId,
+                    deadline,
+                    idempotencyKey,
+                });
+                if (!posted) {
+                    clearTimeout(timer);
+                    this.pendingSendRequests.delete(requestId);
+                    reject(new NexaWebSocketError({
+                        message: 'Failed to post message to BroadcastChannel',
+                        code: 'broadcast-failure',
+                        source: 'follower',
+                    }));
+                }
+            });
+        }
+        finally {
+            // Invariant: Counter is decremented exactly once in this single finally block
+            this.activeLocalSendsCount = Math.max(0, this.activeLocalSendsCount - 1);
+            this.checkCloseConnection();
+        }
+    }
     checkCloseConnection() {
-        if (!this.hasListeners() && this.subscribedPaths.size === 0 && this.socket) {
-            this.socket.disconnect();
-            this.socket = null;
-            this.isConnected = false;
-            this.hasInitialized = false;
+        const current = this._state;
+        if (current === 'disposed' ||
+            current === 'disconnecting' ||
+            this._isSuspended) {
+            return;
         }
+        if (this.hasNetworkNeeds())
+            return;
+        this.disconnectSocket();
+    }
+    hasNetworkNeeds() {
+        if (this.hasLocalNeeds())
+            return true;
+        if (this.isLeader && this._coordinationMode === 'shared') {
+            let totalFollowerSubs = 0;
+            this.followerSubscriptions.forEach((set) => {
+                totalFollowerSubs += set.size;
+            });
+            let totalFollowerGlobalListeners = 0;
+            this.followerGlobalNeeds.forEach((need) => {
+                totalFollowerGlobalListeners += need.globalListenersCount;
+            });
+            if (totalFollowerSubs > 0 || totalFollowerGlobalListeners > 0)
+                return true;
+        }
+        return false;
+    }
+    hasLocalNeeds() {
+        return (this.hasListeners() ||
+            this.localSubscribedPaths.size > 0 ||
+            this.activeLocalSendsCount > 0);
     }
     hasListeners() {
         let count = 0;
@@ -214,32 +1771,239 @@ class WebSocketClient {
         });
         return count > 0;
     }
+    /**
+     * Dispatches events using a defensive snapshot of listeners to avoid mutation hazards.
+     */
     dispatch(event, data) {
         const callbacks = this.listeners.get(event);
-        if (callbacks) {
-            callbacks.forEach((cb) => {
+        if (callbacks && callbacks.size > 0) {
+            const snapshot = Array.from(callbacks);
+            for (const cb of snapshot) {
                 try {
                     cb(data);
                 }
                 catch (e) {
-                    console.error(`[WebSocketClient] Error in listener for event ${event}:`, e);
+                    console.error(`[WebSocketClient] Error in listener for event "${event}":`, e);
                 }
-            });
+            }
+        }
+    }
+    releaseLeaderLock() {
+        if (this.lockAbortController) {
+            this.lockAbortController.abort();
+            this.lockAbortController = null;
+        }
+        if (this.resolveLeaderLock) {
+            this.resolveLeaderLock();
+            this.resolveLeaderLock = null;
+        }
+    }
+    disconnectSocket() {
+        if (this._state === 'disposed')
+            return;
+        this.stopFollowerHeartbeat();
+        this.stopLeaderPruneTimer();
+        this.stopLeaderLeaseTimer();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this._socket) {
+            this._socket.removeAllListeners();
+            this._socket.disconnect();
+            this._socket = null;
+        }
+        this._isConnected = false;
+        this._isLeaderSocketConnected = false;
+        if (this._lastReportedConnected) {
+            this._lastReportedConnected = false;
+            this.dispatch('close', { reason: 'client disconnected' });
+        }
+        this.releaseLeaderLock();
+        this.transitionTo('idle');
+    }
+    setupPageLifecycleListeners() {
+        if (typeof window === 'undefined' || typeof window.addEventListener !== 'function')
+            return;
+        const onBeforeUnload = () => {
+            if (this._state === 'disposed')
+                return;
+            if (!this.isLeader && this._coordinationMode === 'shared') {
+                this.postBroadcast('follower_disconnect', { tabId: this._tabId });
+            }
+            this.releaseLeaderLock();
+            if (this._socket) {
+                this._socket.disconnect();
+            }
+        };
+        const onPageHide = () => {
+            if (this._state === 'disposed')
+                return;
+            this._isSuspended = true;
+            this.stopFollowerHeartbeat();
+            this.stopLeaderPruneTimer();
+            this.stopLeaderLeaseTimer();
+            if (this.reconnectTimer) {
+                clearTimeout(this.reconnectTimer);
+                this.reconnectTimer = null;
+            }
+            this.releaseLeaderLock();
+            if (this._socket) {
+                this._socket.removeAllListeners();
+                this._socket.disconnect();
+                this._socket = null;
+            }
+            this._isConnected = false;
+            this._isLeaderSocketConnected = false;
+            this._currentLeaderId = null;
+            this._currentElectionId = null;
+            this._electionId = null;
+            if (this._lastReportedConnected) {
+                this._lastReportedConnected = false;
+                this.dispatch('close', { reason: 'page suspended' });
+            }
+            this.transitionTo('idle');
+        };
+        const onPageShow = (event) => {
+            if (this._state === 'disposed')
+                return;
+            this._isSuspended = false;
+            if (event?.persisted) {
+                this.dispatch('resync', { reason: 'bfcache_restore' });
+                if (this.hasLocalNeeds()) {
+                    this.ensureConnected();
+                }
+            }
+        };
+        const onVisibilityChange = () => {
+            if (this._state === 'disposed' ||
+                this._isSuspended ||
+                typeof document === 'undefined') {
+                return;
+            }
+            if (document.visibilityState === 'visible') {
+                if (!this.isLeader && this._coordinationMode === 'shared') {
+                    this.postBroadcast('follower_heartbeat', {
+                        globalListenersCount: this.getGlobalListenersCount(),
+                        paths: Array.from(this.localSubscribedPaths.keys()),
+                    });
+                    this.postBroadcast('follower_announce', {
+                        paths: Array.from(this.localSubscribedPaths.keys()),
+                        globalListenersCount: this.getGlobalListenersCount(),
+                    });
+                    this.postBroadcast('follower_sync_request');
+                }
+                if (this.hasLocalNeeds() && this._state === 'idle') {
+                    this.ensureConnected();
+                }
+            }
+        };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        window.addEventListener('pagehide', onPageHide);
+        window.addEventListener('pageshow', onPageShow);
+        if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+            document.addEventListener('visibilitychange', onVisibilityChange);
         }
+        this.pageLifecycleCleanup = () => {
+            window.removeEventListener('beforeunload', onBeforeUnload);
+            window.removeEventListener('pagehide', onPageHide);
+            window.removeEventListener('pageshow', onPageShow);
+            if (typeof document !== 'undefined' && typeof document.removeEventListener === 'function') {
+                document.removeEventListener('visibilitychange', onVisibilityChange);
+            }
+        };
     }
+    /**
+     * Idempotent client teardown releasing locks, clearing queues, and sending best-effort disconnect notice.
+     */
     close() {
-        if (this.socket) {
-            this.socket.disconnect();
-            this.socket = null;
+        if (this._state === 'disposed')
+            return;
+        // Send best-effort disconnect broadcast before channel teardown and state change
+        if (!this.isLeader && this._coordinationMode === 'shared') {
+            this.postBroadcast('follower_disconnect', { tabId: this._tabId });
         }
-        this.isConnected = false;
-        this.hasInitialized = false;
+        this._state = 'disposed';
+        if (this.pageLifecycleCleanup) {
+            this.pageLifecycleCleanup();
+            this.pageLifecycleCleanup = null;
+        }
+        // Reject all readiness waiters
+        this.readinessWaiters.forEach((waiter) => {
+            clearTimeout(waiter.timer);
+            waiter.reject(new NexaWebSocketError({
+                message: 'WebSocketClient is disposed',
+                code: 'disposed',
+            }));
+        });
+        this.readinessWaiters.clear();
+        // Reject all pending follower sends
+        this.pendingSendRequests.forEach((req) => {
+            clearTimeout(req.timer);
+            req.reject(new NexaWebSocketError({
+                message: 'WebSocketClient is disposed',
+                code: req.isMutating ? 'ambiguous-outcome' : 'disposed',
+                isAmbiguous: req.isMutating,
+            }));
+        });
+        this.pendingSendRequests.clear();
+        // Cancel all active leader executions
+        this.activeLeaderSends.forEach((exec) => {
+            exec.cancelled = true;
+            exec.cleanup();
+        });
+        this.activeLeaderSends.clear();
+        this.stopFollowerHeartbeat();
+        this.stopLeaderPruneTimer();
+        this.stopLeaderLeaseTimer();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this._socket) {
+            this._socket.removeAllListeners();
+            this._socket.disconnect();
+            this._socket = null;
+        }
+        this._isConnected = false;
+        this._isLeaderSocketConnected = false;
+        this._electionId = null;
+        this._currentLeaderId = null;
+        this._currentElectionId = null;
+        if (this._lastReportedConnected) {
+            this._lastReportedConnected = false;
+            this.dispatch('close', { reason: 'client disposed' });
+        }
+        this.releaseLeaderLock();
         this.listeners.clear();
-        this.subscribedPaths.clear();
+        this.localSubscribedPaths.clear();
+        this.followerSubscriptions.clear();
+        this.followerSubscriptionsByTab.clear();
+        this.followerGlobalNeeds.clear();
+        this.processedFollowerRequests.clear();
         if (this.broadcastChannel) {
-            this.broadcastChannel.close();
+            try {
+                this.broadcastChannel.close();
+            }
+            catch { }
             this.broadcastChannel = null;
         }
     }
 }
 exports.WebSocketClient = WebSocketClient;
+WebSocketClient.DEFAULT_FOLLOWER_TTL = 30000;
+WebSocketClient.DEFAULT_HEARTBEAT_INTERVAL = 5000;
+WebSocketClient.DEFAULT_PRUNE_INTERVAL = 10000;
+WebSocketClient.DEFAULT_LEADER_LEASE_INTERVAL = 10000;
+WebSocketClient.DEFAULT_TIMEOUT_MS = 10000;
+WebSocketClient.MAX_DEDUP_CACHE_SIZE = 500;
+WebSocketClient.DEDUP_CACHE_TTL_MS = 60000;
+WebSocketClient.RESERVED_SEND_EVENTS = new Set([
+    'connect',
+    'connect_error',
+    'disconnect',
+    'disconnecting',
+    'ping',
+    'pong',
+    'error',
+]);