doover-js 0.2.0-alpha.0 → 0.2.0

package/dist/apis/connections-api.d.ts

@@ -20,4 +20,10 @@ export declare class ConnectionsApi {
     getAgentSubscriptionHistory(agentId: string, params: SubscriptionHistoryParams): Promise<ConnectionSubscriptionLog[]>;
     getConnection(connectionId: string): Promise<ConnectionDetails>;
     getChannelSubscriptions(agentId: string, channelName: string): Promise<ConnectionSubscription[]>;
+    /**
+     * Ask the server to push the latest state of all channels this agent
+     * owns to every active WSS connection. Used to recover from missed updates
+     * after a gap in connectivity.
+     */
+    syncConnection(agentId: string): Promise<unknown>;
 }

package/dist/apis/connections-api.js

@@ -20,5 +20,13 @@ class ConnectionsApi {
     getChannelSubscriptions(agentId, channelName) {
         return this.rest.get(`/agents/${agentId}/channels/${channelName}/subscriptions`);
     }
+    /**
+     * Ask the server to push the latest state of all channels this agent
+     * owns to every active WSS connection. Used to recover from missed updates
+     * after a gap in connectivity.
+     */
+    syncConnection(agentId) {
+        return this.rest.post(`/agents/${agentId}/connection_sync`, {});
+    }
 }
 exports.ConnectionsApi = ConnectionsApi;

package/dist/client/doover-client.d.ts

@@ -12,6 +12,7 @@ import type { DooverAuth } from "../auth/doover-auth";
 import { GatewayClient } from "../gateway/gateway-client";
 import { RestClient, type DooverClientConfig } from "../http/rest-client";
 import { DooverDataProvider } from "../viewer/doover-data-provider";
+import { DooverStatsCollector, type DooverStatsSnapshot } from "./stats";
 export declare class DooverClient {
     readonly auth: DooverAuth;
     readonly rest: RestClient;
@@ -27,5 +28,17 @@ export declare class DooverClient {
     readonly turn: TurnApi;
     readonly agents: AgentsApi;
     readonly gateway: GatewayClient;
+    /** Opt-in instrumentation. Disabled by default — see {@link enableStats}. */
+    readonly stats: DooverStatsCollector;
     constructor(config: DooverClientConfig);
+    /** Start capturing request/message stats. Off by default. */
+    enableStats(): void;
+    /** Stop capturing stats. Existing counters are retained; call `stats.reset()` to clear. */
+    disableStats(): void;
+    /**
+     * Snapshot the current stats. Returns zeroed counters if stats were
+     * never enabled. Combine with {@link GatewayClient.getSubscriptionCount}
+     * and {@link GatewayClient.getSession} for a full debug view.
+     */
+    getStats(): DooverStatsSnapshot;
 }

package/dist/client/doover-client.js

@@ -12,9 +12,9 @@ const permissions_api_1 = require("../apis/permissions-api");
 const processors_api_1 = require("../apis/processors-api");
 const turn_api_1 = require("../apis/turn-api");
 const build_auth_1 = require("../auth/build-auth");
-const gateway_client_1 = require("../gateway/gateway-client");
 const rest_client_1 = require("../http/rest-client");
 const doover_data_provider_1 = require("../viewer/doover-data-provider");
+const stats_1 = require("./stats");
 class DooverClient {
     constructor(config) {
         this.auth = (0, build_auth_1.buildAuth)({
@@ -41,7 +41,35 @@ class DooverClient {
         this.processors = new processors_api_1.ProcessorsApi(this.rest);
         this.turn = new turn_api_1.TurnApi(this.rest);
         this.agents = new agents_api_1.AgentsApi(this.rest);
-        this.gateway = new gateway_client_1.GatewayClient(config, this.auth);
+        // Reuse the viewer's gateway so `client.gateway` and
+        // `client.viewer.gateway` are the same instance → one WebSocket per
+        // client. Without this, `client.gateway.connect()` and
+        // `client.viewer.subscribeToChannel(...)` each opened their own socket.
+        this.gateway = this.viewer.gateway;
+        // Stats collector, disabled by default. Attached to both REST clients
+        // (facade + viewer's internal) and the shared gateway so every recorded
+        // call flows through the same counters. Pay-to-play: record methods
+        // short-circuit when disabled.
+        this.stats = new stats_1.DooverStatsCollector();
+        this.rest.setStats(this.stats);
+        this.viewer.rest.setStats(this.stats);
+        this.gateway.setStats(this.stats);
+    }
+    /** Start capturing request/message stats. Off by default. */
+    enableStats() {
+        this.stats.setEnabled(true);
+    }
+    /** Stop capturing stats. Existing counters are retained; call `stats.reset()` to clear. */
+    disableStats() {
+        this.stats.setEnabled(false);
+    }
+    /**
+     * Snapshot the current stats. Returns zeroed counters if stats were
+     * never enabled. Combine with {@link GatewayClient.getSubscriptionCount}
+     * and {@link GatewayClient.getSession} for a full debug view.
+     */
+    getStats() {
+        return this.stats.snapshot();
     }
 }
 exports.DooverClient = DooverClient;

package/dist/client/singleton.d.ts

@@ -0,0 +1,26 @@
+import type { DooverClientConfig } from "../http/rest-client";
+import { DooverClient } from "./doover-client";
+/**
+ * Get the process-wide `DooverClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_client__` to survive module-level duplicates
+ * — if this module is loaded more than once (HMR, federation boundaries,
+ * multiple bundles) each load still returns the same instance and therefore
+ * the same WebSocket + REST configuration.
+ *
+ * The first caller's `config` wins. Subsequent calls ignore the `config`
+ * arg and return the existing instance — log a warning if they differ so
+ * drift is visible in dev tools.
+ */
+export declare function getDooverClient(config: DooverClientConfig): DooverClient;
+/**
+ * Returns the current singleton if one has been initialised, otherwise
+ * `null`. Useful for callers that want to read the client opportunistically
+ * without forcing construction.
+ */
+export declare function peekDooverClient(): DooverClient | null;
+/**
+ * Clear the singleton. Primarily for tests — not recommended in production
+ * code since any active subscriptions reference the old instance.
+ */
+export declare function resetDooverClient(): void;

package/dist/client/singleton.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDooverClient = getDooverClient;
+exports.peekDooverClient = peekDooverClient;
+exports.resetDooverClient = resetDooverClient;
+const doover_client_1 = require("./doover-client");
+const GLOBAL_KEY = "__doover_js_client__";
+function globalBag() {
+    return globalThis;
+}
+/**
+ * Get the process-wide `DooverClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_client__` to survive module-level duplicates
+ * — if this module is loaded more than once (HMR, federation boundaries,
+ * multiple bundles) each load still returns the same instance and therefore
+ * the same WebSocket + REST configuration.
+ *
+ * The first caller's `config` wins. Subsequent calls ignore the `config`
+ * arg and return the existing instance — log a warning if they differ so
+ * drift is visible in dev tools.
+ */
+function getDooverClient(config) {
+    const bag = globalBag();
+    const existing = bag[GLOBAL_KEY];
+    if (existing) {
+        if (configsDiffer(existing, config)) {
+            // eslint-disable-next-line no-console
+            console.warn("[doover-js] getDooverClient called with a config that differs " +
+                "from the already-initialised singleton. The existing client is " +
+                "being reused; the new config is ignored.");
+        }
+        return existing;
+    }
+    const client = new doover_client_1.DooverClient(config);
+    bag[GLOBAL_KEY] = client;
+    return client;
+}
+/**
+ * Returns the current singleton if one has been initialised, otherwise
+ * `null`. Useful for callers that want to read the client opportunistically
+ * without forcing construction.
+ */
+function peekDooverClient() {
+    return globalBag()[GLOBAL_KEY] ?? null;
+}
+/**
+ * Clear the singleton. Primarily for tests — not recommended in production
+ * code since any active subscriptions reference the old instance.
+ */
+function resetDooverClient() {
+    delete globalBag()[GLOBAL_KEY];
+}
+function configsDiffer(existing, next) {
+    const a = existing.rest.config;
+    return (a.dataRestUrl !== next.dataRestUrl ||
+        a.dataWssUrl !== next.dataWssUrl ||
+        a.controlApiUrl !== next.controlApiUrl);
+}

package/dist/client/stats.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Opt-in instrumentation for `DooverClient`. When enabled, counts REST
+ * requests and gateway messages and keeps running latency stats. Disabled
+ * by default — the record methods short-circuit so production apps pay
+ * nothing unless a debug UI turns it on.
+ */
+export interface RestStatsSnapshot {
+    enabled: boolean;
+    /** Total requests started since stats were enabled (or last reset). */
+    totalRequests: number;
+    /** Requests currently in flight. */
+    pendingRequests: number;
+    /** Requests that resolved successfully. */
+    completedRequests: number;
+    /** Requests that threw / rejected. */
+    failedRequests: number;
+    /** Mean latency of settled requests, ms. Null until at least one lands. */
+    averageLatencyMs: number | null;
+    /** Latency of the most recently settled request, ms. */
+    lastLatencyMs: number | null;
+}
+export interface GatewayStatsSnapshot {
+    enabled: boolean;
+    /** Frames we've sent on the gateway socket. */
+    messagesSent: number;
+    /** Frames we've received on the gateway socket. */
+    messagesReceived: number;
+}
+export interface DooverStatsSnapshot {
+    rest: RestStatsSnapshot;
+    gateway: GatewayStatsSnapshot;
+}
+export declare class DooverStatsCollector {
+    private enabled;
+    private rTotal;
+    private rPending;
+    private rCompleted;
+    private rFailed;
+    private rLatencySum;
+    private rLastLatency;
+    private gSent;
+    private gReceived;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    reset(): void;
+    /**
+     * Record the start of a REST request. Returns the start timestamp the
+     * caller must hand back to `recordRestEnd`, or `null` if stats are off.
+     */
+    recordRestStart(): number | null;
+    recordRestEnd(startedAt: number | null, succeeded: boolean): void;
+    recordGatewaySent(): void;
+    recordGatewayReceived(): void;
+    snapshot(): DooverStatsSnapshot;
+}

package/dist/client/stats.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Opt-in instrumentation for `DooverClient`. When enabled, counts REST
+ * requests and gateway messages and keeps running latency stats. Disabled
+ * by default — the record methods short-circuit so production apps pay
+ * nothing unless a debug UI turns it on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DooverStatsCollector = void 0;
+class DooverStatsCollector {
+    constructor() {
+        this.enabled = false;
+        this.rTotal = 0;
+        this.rPending = 0;
+        this.rCompleted = 0;
+        this.rFailed = 0;
+        this.rLatencySum = 0;
+        this.rLastLatency = null;
+        this.gSent = 0;
+        this.gReceived = 0;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    reset() {
+        this.rTotal = 0;
+        this.rPending = 0;
+        this.rCompleted = 0;
+        this.rFailed = 0;
+        this.rLatencySum = 0;
+        this.rLastLatency = null;
+        this.gSent = 0;
+        this.gReceived = 0;
+    }
+    /**
+     * Record the start of a REST request. Returns the start timestamp the
+     * caller must hand back to `recordRestEnd`, or `null` if stats are off.
+     */
+    recordRestStart() {
+        if (!this.enabled)
+            return null;
+        this.rTotal += 1;
+        this.rPending += 1;
+        return now();
+    }
+    recordRestEnd(startedAt, succeeded) {
+        if (!this.enabled || startedAt === null)
+            return;
+        this.rPending = Math.max(0, this.rPending - 1);
+        if (succeeded)
+            this.rCompleted += 1;
+        else
+            this.rFailed += 1;
+        const latency = now() - startedAt;
+        this.rLastLatency = latency;
+        this.rLatencySum += latency;
+    }
+    recordGatewaySent() {
+        if (!this.enabled)
+            return;
+        this.gSent += 1;
+    }
+    recordGatewayReceived() {
+        if (!this.enabled)
+            return;
+        this.gReceived += 1;
+    }
+    snapshot() {
+        const settled = this.rCompleted + this.rFailed;
+        return {
+            rest: {
+                enabled: this.enabled,
+                totalRequests: this.rTotal,
+                pendingRequests: this.rPending,
+                completedRequests: this.rCompleted,
+                failedRequests: this.rFailed,
+                averageLatencyMs: settled > 0 ? this.rLatencySum / settled : null,
+                lastLatencyMs: this.rLastLatency,
+            },
+            gateway: {
+                enabled: this.enabled,
+                messagesSent: this.gSent,
+                messagesReceived: this.gReceived,
+            },
+        };
+    }
+}
+exports.DooverStatsCollector = DooverStatsCollector;
+function now() {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+        return performance.now();
+    }
+    return Date.now();
+}

package/dist/gateway/gateway-client.d.ts

@@ -1,4 +1,5 @@
 import type { DooverAuth } from "../auth/doover-auth";
+import type { DooverStatsCollector } from "../client/stats";
 import type { DooverClientConfig } from "../http/rest-client";
 import type { GatewayListenerMap, WebSocketSession } from "./types";
 import type { ChannelRef, JSONValue } from "../types/common";
@@ -6,15 +7,21 @@ export declare class GatewayClient {
     private readonly config;
     private socket;
     private session;
-    private heartbeatTimer;
-    private lastHeartbeatAt;
-    private missedHeartbeats;
     private reconnectTimer;
+    private reconnectAttempts;
+    /** Set when the consumer explicitly disconnects — suppresses reconnect. */
+    private explicitlyDisconnected;
+    /** Guards against concurrent connect() callers creating duplicate sockets. */
+    private opening;
     private listeners;
     private subscriptions;
     private readonly auth;
+    private stats;
     constructor(config: DooverClientConfig, auth?: DooverAuth);
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats: DooverStatsCollector | null): void;
     connect(): Promise<void>;
+    private openSocket;
     disconnect(code?: number, reason?: string): void;
     on<K extends keyof GatewayListenerMap>(eventName: K, listener: GatewayListenerMap[K]): void;
     off<K extends keyof GatewayListenerMap>(eventName: K, listener: GatewayListenerMap[K]): void;
@@ -25,15 +32,32 @@ export declare class GatewayClient {
     syncChannel(channel: ChannelRef): void;
     sendOneShotMessage(channel: ChannelRef, data: JSONValue): void;
     getSession(): WebSocketSession | null;
-    getLatency(): number | null;
     isConnected(): boolean;
+    /** Number of channels the gateway is currently subscribed to. */
+    getSubscriptionCount(): number;
+    /** Snapshot of currently subscribed channels (for debug/inspection). */
+    getSubscriptions(): ChannelRef[];
+    /**
+     * Force a fresh connection: close the current socket (without suppressing
+     * reconnects) and immediately open a new one. Useful for a manual
+     * "reconnect now" control in debug UIs.
+     */
+    reconnect(): Promise<void>;
     private handleMessage;
     private identifyOrResume;
     private resubscribeAll;
-    private startHeartbeat;
-    private stopHeartbeat;
     private send;
     private emit;
     private scheduleReconnect;
+    /** Exponential backoff with full-jitter, capped at RECONNECT_CAP_MS. */
+    private computeReconnectDelay;
+    private installLifecycleListeners;
+    private handleVisibilityChange;
+    private handleOnline;
+    /**
+     * Called by lifecycle hooks when we have a strong signal that the network
+     * or tab has come back — skip the backoff schedule and reconnect now.
+     */
+    private tryImmediateReconnect;
     private channelKey;
 }

package/dist/gateway/gateway-client.js

@@ -3,15 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GatewayClient = void 0;
 const errors_1 = require("../http/errors");
 const snowflake_1 = require("../utils/snowflake");
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_CAP_MS = 30000;
 class GatewayClient {
     constructor(config, auth) {
         this.config = config;
         this.socket = null;
         this.session = null;
-        this.heartbeatTimer = null;
-        this.lastHeartbeatAt = null;
-        this.missedHeartbeats = 0;
         this.reconnectTimer = null;
+        this.reconnectAttempts = 0;
+        /** Set when the consumer explicitly disconnects — suppresses reconnect. */
+        this.explicitlyDisconnected = false;
+        /** Guards against concurrent connect() callers creating duplicate sockets. */
+        this.opening = false;
         this.listeners = {
             ready: new Set(),
             channelSync: new Set(),
@@ -26,15 +30,50 @@ class GatewayClient {
             sessionCancelled: new Set(),
             open: new Set(),
             close: new Set(),
-            heartbeatAck: new Set(),
         };
         this.subscriptions = new Map();
+        this.stats = null;
+        this.handleVisibilityChange = () => {
+            if (typeof document === "undefined")
+                return;
+            if (document.visibilityState !== "visible")
+                return;
+            this.tryImmediateReconnect();
+        };
+        this.handleOnline = () => {
+            this.tryImmediateReconnect();
+        };
         this.auth = auth ?? null;
+        this.installLifecycleListeners();
+    }
+    /** Attach a stats collector. Call with `null` to detach. */
+    setStats(stats) {
+        this.stats = stats;
     }
     async connect() {
+        this.explicitlyDisconnected = false;
         if (this.socket && this.socket.readyState <= WebSocket.OPEN) {
             return;
         }
+        // De-dupe concurrent callers. Without this, N simultaneous
+        // `subscribeToChannel(...)` calls each await auth, then each create
+        // their own socket — the last one wins `this.socket`, but the earlier
+        // sockets' `onmessage` handlers still fire and try to send() through
+        // `this.socket` (a newer, not-yet-open socket → throws). The flag is
+        // cleared synchronously as soon as the new socket is assigned in
+        // `openSocket`, so reconnects after close still work.
+        if (this.opening) {
+            return;
+        }
+        this.opening = true;
+        try {
+            await this.openSocket();
+        }
+        finally {
+            this.opening = false;
+        }
+    }
+    async openSocket() {
         if (this.auth) {
             await this.auth.ensureReady();
         }
@@ -42,31 +81,36 @@ class GatewayClient {
         const wsParams = this.auth
             ? await this.auth.prepareWebSocket(this.config.dataWssUrl, hasFactory)
             : { url: this.config.dataWssUrl };
+        let socket;
         if (this.config.webSocketFactory) {
-            this.socket = this.config.webSocketFactory({
+            socket = this.config.webSocketFactory({
                 url: wsParams.url,
                 headers: wsParams.headers,
             });
         }
         else {
             const WebSocketImpl = this.config.webSocketImpl ?? WebSocket;
-            this.socket = new WebSocketImpl(wsParams.url);
+            socket = new WebSocketImpl(wsParams.url);
         }
-        this.socket.onopen = () => this.emit("open");
-        this.socket.onclose = (event) => {
-            this.stopHeartbeat();
+        this.socket = socket;
+        // Release the concurrency gate synchronously now that the new socket is
+        // assigned — any subsequent connect() will see it via `this.socket`.
+        this.opening = false;
+        socket.onopen = () => this.emit("open");
+        socket.onclose = (event) => {
             this.emit("close", event);
             this.scheduleReconnect();
         };
-        this.socket.onerror = () => undefined;
-        this.socket.onmessage = (event) => this.handleMessage(event.data);
+        socket.onerror = () => undefined;
+        socket.onmessage = (event) => this.handleMessage(event.data);
     }
     disconnect(code, reason) {
-        this.stopHeartbeat();
+        this.explicitlyDisconnected = true;
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        this.reconnectAttempts = 0;
         this.socket?.close(code, reason);
         this.socket = null;
     }
@@ -136,20 +180,44 @@ class GatewayClient {
     getSession() {
         return this.session;
     }
-    getLatency() {
-        return this.lastHeartbeatAt === null ? null : Date.now() - this.lastHeartbeatAt;
-    }
     isConnected() {
         return this.socket?.readyState === WebSocket.OPEN;
     }
+    /** Number of channels the gateway is currently subscribed to. */
+    getSubscriptionCount() {
+        return this.subscriptions.size;
+    }
+    /** Snapshot of currently subscribed channels (for debug/inspection). */
+    getSubscriptions() {
+        return [...this.subscriptions.values()].map((s) => s.channel);
+    }
+    /**
+     * Force a fresh connection: close the current socket (without suppressing
+     * reconnects) and immediately open a new one. Useful for a manual
+     * "reconnect now" control in debug UIs.
+     */
+    async reconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.reconnectAttempts = 0;
+        // Drop the session so the new socket identifies fresh (op 10) rather
+        // than attempting to resume a just-closed session (op 11) that the
+        // server has already torn down.
+        this.session = null;
+        if (this.socket) {
+            // Suppress the auto-reconnect path so we don't double-schedule.
+            const prev = this.socket;
+            prev.onclose = null;
+            prev.close(1000, "manual reconnect");
+            this.socket = null;
+        }
+        await this.connect();
+    }
     handleMessage(raw) {
+        this.stats?.recordGatewayReceived();
         const message = JSON.parse(raw);
-        if (message.op === 2) {
-            this.missedHeartbeats = 0;
-            const latency = this.lastHeartbeatAt === null ? null : Date.now() - this.lastHeartbeatAt;
-            this.emit("heartbeatAck", latency);
-            return;
-        }
         if (message.op === 3) {
             this.session = null;
             this.emit("sessionCancelled");
@@ -161,9 +229,9 @@ class GatewayClient {
         switch (message.t) {
             case "Hello":
                 this.identifyOrResume();
-                this.startHeartbeat();
                 break;
             case "Ready":
+                this.reconnectAttempts = 0;
                 this.session = message.d;
                 this.emit("ready", message.d);
                 this.resubscribeAll();
@@ -225,33 +293,12 @@ class GatewayClient {
             this.subscribe(entry.channel, { diff_only: entry.diff_only });
         }
     }
-    startHeartbeat() {
-        this.stopHeartbeat();
-        this.heartbeatTimer = setInterval(() => {
-            if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-                return;
-            }
-            this.lastHeartbeatAt = Date.now();
-            this.missedHeartbeats += 1;
-            if (this.missedHeartbeats > 3) {
-                this.socket.close(4000, "Missed heartbeats");
-                return;
-            }
-            this.send({ op: 1, d: {} });
-        }, 20000);
-    }
-    stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-        this.missedHeartbeats = 0;
-    }
     send(payload) {
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
             throw new errors_1.DooverGatewayError("WebSocket is not connected");
         }
         this.socket.send(JSON.stringify(payload));
+        this.stats?.recordGatewaySent();
     }
     emit(eventName, ...args) {
         this.listeners[eventName].forEach((listener) => {
@@ -259,13 +306,45 @@ class GatewayClient {
         });
     }
     scheduleReconnect() {
-        if (this.reconnectTimer) {
+        if (this.reconnectTimer || this.explicitlyDisconnected) {
             return;
         }
+        const delay = this.computeReconnectDelay();
+        this.reconnectAttempts += 1;
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             void this.connect();
-        }, 1000);
+        }, delay);
+    }
+    /** Exponential backoff with full-jitter, capped at RECONNECT_CAP_MS. */
+    computeReconnectDelay() {
+        const exp = Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** this.reconnectAttempts);
+        return Math.floor(Math.random() * exp);
+    }
+    installLifecycleListeners() {
+        if (this.config.disableBrowserLifecycleHooks)
+            return;
+        if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+            document.addEventListener("visibilitychange", this.handleVisibilityChange);
+        }
+        if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+            window.addEventListener("online", this.handleOnline);
+        }
+    }
+    /**
+     * Called by lifecycle hooks when we have a strong signal that the network
+     * or tab has come back — skip the backoff schedule and reconnect now.
+     */
+    tryImmediateReconnect() {
+        if (this.explicitlyDisconnected)
+            return;
+        if (this.isConnected())
+            return;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        void this.connect();
     }
     channelKey(channel) {
         return `${channel.agent_id}/${channel.name}`;

package/dist/gateway/types.d.ts

@@ -131,5 +131,4 @@ export interface GatewayListenerMap {
     sessionCancelled: () => void;
     open: () => void;
     close: (event: CloseEvent) => void;
-    heartbeatAck: (latencyMs: number | null) => void;
 }