@gwakko/shared-websocket 0.12.2 → 0.13.0

package/src/SharedWebSocket.ts

@@ -31,8 +31,9 @@ const NOOP_LOGGER: Logger = {
 /** Common interface for both SharedSocket and WorkerSocket. */
 interface SocketAdapter {
   readonly state: string;
-  connect(): void;
+  connect(): void | Promise<void>;
   send(data: unknown): void;
+  reconnect(): void;
   disconnect(): void;
   onMessage(fn: EventHandler): Unsubscribe;
   onStateChange(fn: (state: string) => void): Unsubscribe;
@@ -103,6 +104,16 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
       }),
     );
 
+    // Leader listens for reconnect requests from followers
+    this.cleanups.push(
+      this.bus.subscribe<void>('ws:reconnect', () => {
+        if (this.coordinator.isLeader && this.socket) {
+          this.log.info('[SharedWS] manual reconnect requested by follower');
+          this.socket.reconnect();
+        }
+      }),
+    );
+
     // Sync across tabs
     this.cleanups.push(
       this.bus.subscribe<{ key: string; value: unknown }>('ws:sync', (msg) => {
@@ -134,6 +145,9 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
           case 'reconnecting':
             this.subs.emit('$lifecycle:reconnecting', undefined);
             break;
+          case 'reconnectFailed':
+            this.subs.emit('$lifecycle:reconnectFailed', undefined);
+            break;
           case 'leader':
             this.subs.emit('$lifecycle:leader', msg.isLeader);
             break;
@@ -228,6 +242,38 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
     return this.subs.on('$lifecycle:reconnecting', fn);
   }
 
+  /**
+   * Called when auto-reconnect gives up after exhausting `reconnectMaxRetries`.
+   * Use this to show a "Reconnect" UI affordance (snackbar, banner, modal)
+   * so the user can call `ws.reconnect()` to try again.
+   *
+   * @example
+   * ws.onReconnectFailed(() => {
+   *   showSnackbar('Connection lost', { action: { label: 'Reconnect', onClick: () => ws.reconnect() } });
+   * });
+   */
+  onReconnectFailed(fn: () => void): Unsubscribe {
+    return this.subs.on('$lifecycle:reconnectFailed', fn);
+  }
+
+  /**
+   * Manually trigger a reconnect. Resets the retry counter and attempts a
+   * fresh connection. Safe to call from any tab — the leader actually owns
+   * the socket, followers route the request via BroadcastChannel.
+   *
+   * Use after `onReconnectFailed` fires to let the user retry.
+   *
+   * @example
+   * snackbar.action('Reconnect', () => ws.reconnect());
+   */
+  reconnect(): void {
+    if (this.coordinator.isLeader && this.socket) {
+      this.socket.reconnect();
+    } else {
+      this.bus.publish('ws:reconnect', undefined);
+    }
+  }
+
   /** Called when this tab becomes leader or loses leadership. */
   onLeaderChange(fn: (isLeader: boolean) => void): Unsubscribe {
     return this.subs.on('$lifecycle:leader', fn as EventHandler);
@@ -675,6 +721,9 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
       return new WorkerSocket(this.url, {
         ...socketOptions,
         workerUrl: this.options.workerUrl,
+        auth: this.options.auth,
+        authToken: this.options.authToken,
+        authParam: this.options.authParam,
       });
     }
 
@@ -718,7 +767,7 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
     });
 
     this.socket.onStateChange((state: string) => {
-      this.log.info('[SharedWS]', state === 'connected' ? '✓ connected' : state === 'reconnecting' ? '🔄 reconnecting' : `state: ${state}`);
+      this.log.info('[SharedWS]', state === 'connected' ? '✓ connected' : state === 'reconnecting' ? '🔄 reconnecting' : state === 'failed' ? '✗ reconnect failed' : `state: ${state}`);
       switch (state) {
         case 'connected':
           this.bus.broadcast('ws:lifecycle', { type: 'connect' });
@@ -730,6 +779,10 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
         case 'reconnecting':
           this.bus.broadcast('ws:lifecycle', { type: 'reconnecting' });
           break;
+        case 'failed':
+          this.bus.broadcast('ws:lifecycle', { type: 'reconnectFailed' });
+          this.bus.broadcast('ws:lifecycle', { type: 'disconnect' });
+          break;
       }
     });
 
@@ -748,7 +801,7 @@ export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Dis
       }),
     );
 
-    this.socket.connect();
+    void this.socket.connect();
   }
 
   private reAuthenticateOnReconnect(): void {

package/src/TabSync.ts

@@ -1,5 +1,5 @@
 import './utils/disposable';
-import type { Unsubscribe } from './types';
+import type { Unsubscribe, Logger } from './types';
 
 interface SyncMessage {
   key: string;
@@ -7,6 +7,15 @@ interface SyncMessage {
   deleted?: boolean;
 }
 
+interface TabSyncOptions {
+  /** Enable debug logging (default: false). */
+  debug?: boolean;
+  /** Custom logger (default: console). */
+  logger?: Logger;
+}
+
+const NOOP_LOGGER: Logger = { debug() {}, info() {}, warn() {}, error() {} };
+
 /**
  * Cross-tab state synchronization via BroadcastChannel.
  * No WebSocket needed — works standalone for sharing state between browser tabs.
@@ -15,21 +24,30 @@ interface SyncMessage {
  * const sync = new TabSync('my-app');
  * sync.set('theme', 'dark');
  * sync.on('theme', (theme) => applyTheme(theme));
+ *
+ * @example
+ * // With debug logging
+ * const sync = new TabSync('my-app', { debug: true });
  */
 export class TabSync implements Disposable {
   private store = new Map<string, unknown>();
   private listeners = new Map<string, Set<(value: unknown) => void>>();
   private bc: BroadcastChannel;
   private disposed = false;
+  private readonly log: Logger;
 
-  constructor(channel = 'tab-sync') {
+  constructor(channel = 'tab-sync', options?: TabSyncOptions) {
+    this.log = options?.debug ? (options.logger ?? console) : NOOP_LOGGER;
+    this.log.debug('[TabSync] init', { channel });
     this.bc = new BroadcastChannel(channel);
     this.bc.onmessage = (ev: MessageEvent<SyncMessage>) => {
       const { key, value, deleted } = ev.data;
       if (deleted) {
         this.store.delete(key);
+        this.log.debug('[TabSync] ← remote delete', key);
       } else {
         this.store.set(key, value);
+        this.log.debug('[TabSync] ← remote set', key, value);
       }
       this.emit(key, value);
     };
@@ -39,6 +57,7 @@ export class TabSync implements Disposable {
   set<T>(key: string, value: T): void {
     this.store.set(key, value);
     this.bc.postMessage({ key, value } satisfies SyncMessage);
+    this.log.debug('[TabSync] → set', key, value);
     this.emit(key, value);
   }
 
@@ -51,6 +70,7 @@ export class TabSync implements Disposable {
   delete(key: string): void {
     this.store.delete(key);
     this.bc.postMessage({ key, value: undefined, deleted: true } satisfies SyncMessage);
+    this.log.debug('[TabSync] → delete', key);
     this.emit(key, undefined);
   }
 
@@ -98,6 +118,7 @@ export class TabSync implements Disposable {
   /** Clear all keys and notify listeners. */
   clear(): void {
     const keys = [...this.store.keys()];
+    this.log.debug('[TabSync] → clear', keys);
     this.store.clear();
     for (const key of keys) {
       this.bc.postMessage({ key, value: undefined, deleted: true } satisfies SyncMessage);

package/src/WorkerSocket.ts

@@ -30,9 +30,14 @@ export class WorkerSocket implements Disposable {
       protocols?: string[];
       reconnect?: boolean;
       reconnectMaxDelay?: number;
+      reconnectMaxRetries?: number;
       heartbeatInterval?: number;
       sendBuffer?: number;
       workerUrl?: string | URL;
+      auth?: () => string | Promise<string>;
+      authToken?: string;
+      authParam?: string;
+      pingPayload?: unknown;
     } = {},
   ) {}
 
@@ -40,7 +45,18 @@ export class WorkerSocket implements Disposable {
     return this._state;
   }
 
-  connect(): void {
+  async connect(): Promise<void> {
+    // Resolve auth token before sending to worker (functions can't cross worker boundary)
+    let authToken: string | undefined;
+    if (this.options.auth) {
+      authToken = await this.options.auth();
+    } else if (this.options.authToken) {
+      authToken = this.options.authToken;
+    }
+
+    // Build URL with auth token
+    const connectUrl = authToken ? this.buildUrl(authToken) : this.url;
+
     // Create worker from inline blob if no workerUrl provided
     const workerUrl = this.options.workerUrl ?? this.createWorkerBlob();
 
@@ -74,19 +90,34 @@ export class WorkerSocket implements Disposable {
 
     this.worker.postMessage({
       type: 'connect',
-      url: this.url,
+      url: connectUrl,
       protocols: this.options.protocols ?? [],
       reconnect: this.options.reconnect ?? true,
       reconnectMaxDelay: this.options.reconnectMaxDelay ?? 30_000,
+      reconnectMaxRetries: this.options.reconnectMaxRetries ?? Infinity,
       heartbeatInterval: this.options.heartbeatInterval ?? 30_000,
       bufferSize: this.options.sendBuffer ?? 100,
+      pingPayload: this.options.pingPayload,
     });
   }
 
+  private buildUrl(token: string): string {
+    const param = this.options.authParam ?? 'token';
+    const httpUrl = this.url.replace(/^ws(s?):\/\//, 'http$1://');
+    const parsed = new URL(httpUrl);
+    parsed.searchParams.set(param, token);
+    return parsed.toString().replace(/^http(s?):\/\//, 'ws$1://');
+  }
+
   send(data: unknown): void {
     this.worker?.postMessage({ type: 'send', data });
   }
 
+  /** Manually trigger reconnect: resets retry counter, attempts a fresh connection. */
+  reconnect(): void {
+    this.worker?.postMessage({ type: 'reconnect' });
+  }
+
   disconnect(): void {
     this.worker?.postMessage({ type: 'disconnect' });
     setTimeout(() => {
@@ -113,27 +144,43 @@ export class WorkerSocket implements Disposable {
       let ws = null, state = 'closed', buffer = [], disposed = false;
       let heartbeatTimer = null, reconnectTimer = null;
       let url = '', protocols = [], shouldReconnect = true;
-      let maxDelay = 30000, hbInterval = 30000, maxBuf = 100, delay = 1000;
+      let maxDelay = 30000, maxRetries = Infinity, hbInterval = 30000, maxBuf = 100;
+      let delay = 1000, attempts = 0, pingPayload = '{"type":"ping"}';
 
       function setState(s) { state = s; self.postMessage({ type: 'state', state: s }); }
       function connect() {
         if (disposed) return;
         setState('connecting');
         ws = new WebSocket(url, protocols);
-        ws.onopen = () => { setState('connected'); delay = 1000; self.postMessage({ type: 'open' }); flush(); startHB(); };
+        ws.onopen = () => { attempts = 0; delay = 1000; setState('connected'); self.postMessage({ type: 'open' }); flush(); startHB(); };
         ws.onmessage = (e) => { let d; try { d = JSON.parse(e.data); } catch { d = e.data; } self.postMessage({ type: 'message', data: d }); };
         ws.onclose = (e) => { stopHB(); self.postMessage({ type: 'close', code: e.code, reason: e.reason }); if (!disposed && shouldReconnect && e.code !== 1000) reconnect(); else setState('closed'); };
         ws.onerror = () => { self.postMessage({ type: 'error', message: 'error' }); };
       }
       function send(d) { if (state === 'connected' && ws?.readyState === 1) ws.send(JSON.stringify(d)); else if (buffer.length < maxBuf) buffer.push(d); }
       function flush() { const p = buffer.splice(0); p.forEach(send); }
-      function startHB() { stopHB(); heartbeatTimer = setInterval(() => { if (ws?.readyState === 1) ws.send('{"type":"ping"}'); }, hbInterval); }
+      function startHB() { stopHB(); heartbeatTimer = setInterval(() => { if (ws?.readyState === 1) ws.send(pingPayload); }, hbInterval); }
       function stopHB() { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } }
-      function reconnect() { setState('reconnecting'); const j = delay * 0.25 * (Math.random() * 2 - 1); reconnectTimer = setTimeout(() => { if (!disposed) connect(); }, Math.min(delay + j, maxDelay)); delay = Math.min(delay * 2, maxDelay); }
+      function reconnect() {
+        attempts++;
+        if (attempts > maxRetries) { setState('failed'); return; }
+        setState('reconnecting');
+        const j = delay * 0.25 * (Math.random() * 2 - 1);
+        reconnectTimer = setTimeout(() => { if (!disposed) connect(); }, Math.min(delay + j, maxDelay));
+        delay = Math.min(delay * 2, maxDelay);
+      }
+      function manualReconnect() {
+        if (disposed) return;
+        if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+        attempts = 0; delay = 1000;
+        if (ws) { ws.onclose = null; ws.onmessage = null; ws.onerror = null; if (ws.readyState < 2) ws.close(1000, 'manual reconnect'); ws = null; }
+        connect();
+      }
       self.onmessage = (e) => {
         const c = e.data;
-        if (c.type === 'connect') { url = c.url; protocols = c.protocols || []; shouldReconnect = c.reconnect ?? true; maxDelay = c.reconnectMaxDelay || 30000; hbInterval = c.heartbeatInterval || 30000; maxBuf = c.bufferSize || 100; connect(); }
+        if (c.type === 'connect') { url = c.url; protocols = c.protocols || []; shouldReconnect = c.reconnect ?? true; maxDelay = c.reconnectMaxDelay || 30000; maxRetries = c.reconnectMaxRetries ?? Infinity; hbInterval = c.heartbeatInterval || 30000; maxBuf = c.bufferSize || 100; if (c.pingPayload) pingPayload = JSON.stringify(c.pingPayload); connect(); }
         if (c.type === 'send') send(c.data);
+        if (c.type === 'reconnect') manualReconnect();
         if (c.type === 'disconnect') { disposed = true; stopHB(); if (reconnectTimer) clearTimeout(reconnectTimer); if (ws) { ws.onclose = null; if (ws.readyState < 2) ws.close(1000); ws = null; } buffer = []; setState('closed'); }
       };
     `;

package/src/adapters/react.ts

@@ -48,13 +48,10 @@ export interface SharedWebSocketProviderProps {
  * }
  */
 export function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps) {
-  const [socket] = useState(() => {
-    const ws = new SharedWebSocket(url, options);
-    ws.connect();
-    return ws;
-  });
+  const [socket] = useState(() => new SharedWebSocket(url, options));
 
   useEffect(() => {
+    socket.connect();
     return () => {
       socket[Symbol.dispose]();
     };
@@ -341,6 +338,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   const onConnect = useEffectEvent(() => handlers.onConnect?.());
   const onDisconnect = useEffectEvent(() => handlers.onDisconnect?.());
   const onReconnecting = useEffectEvent(() => handlers.onReconnecting?.());
+  const onReconnectFailed = useEffectEvent(() => handlers.onReconnectFailed?.());
   const onLeaderChange = useEffectEvent((isLeader: boolean) => handlers.onLeaderChange?.(isLeader));
   const onError = useEffectEvent((error: unknown) => handlers.onError?.(error));
   const onActive = useEffectEvent(() => handlers.onActive?.());
@@ -353,6 +351,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
       socket.onConnect(onConnect),
       socket.onDisconnect(onDisconnect),
       socket.onReconnecting(onReconnecting),
+      socket.onReconnectFailed(onReconnectFailed),
       socket.onLeaderChange(onLeaderChange),
       socket.onError(onError),
       socket.onActive(onActive),
@@ -364,6 +363,51 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   }, [socket]);
 }
 
+/**
+ * Reactive reconnect state with a manual `reconnect` action. Use this to
+ * power a "Reconnect" snackbar/banner after auto-reconnect gives up.
+ *
+ * `hasFailed` is `true` after `reconnectMaxRetries` are exhausted. It resets
+ * to `false` once the connection succeeds again or the user calls `reconnect()`.
+ *
+ * @example
+ * function ConnectionBanner() {
+ *   const { hasFailed, reconnect } = useSocketReconnect();
+ *   if (!hasFailed) return null;
+ *   return (
+ *     <div className="snackbar">
+ *       Connection lost.
+ *       <button onClick={reconnect}>Reconnect</button>
+ *     </div>
+ *   );
+ * }
+ */
+export function useSocketReconnect(): {
+  hasFailed: boolean;
+  reconnect: () => void;
+} {
+  const socket = useSharedWebSocket();
+  const [hasFailed, setHasFailed] = useState(false);
+
+  const onFailed = useEffectEvent(() => setHasFailed(true));
+  const onConnected = useEffectEvent(() => setHasFailed(false));
+
+  useEffect(() => {
+    const unsubs = [
+      socket.onReconnectFailed(onFailed),
+      socket.onConnect(onConnected),
+    ];
+    return () => unsubs.forEach((u) => u());
+  }, [socket]);
+
+  const reconnect = useEffectEvent(() => {
+    setHasFailed(false);
+    socket.reconnect();
+  });
+
+  return { hasFailed, reconnect };
+}
+
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/src/adapters/sync-react.ts

@@ -28,11 +28,13 @@ const TabSyncContext = createContext<TabSync | null>(null);
 export interface TabSyncProviderProps {
   /** BroadcastChannel name (default: "tab-sync"). */
   channel?: string;
+  /** Enable debug logging. */
+  debug?: boolean;
   children: ReactNode;
 }
 
-export function TabSyncProvider({ channel, children }: TabSyncProviderProps) {
-  const [sync] = useState(() => new TabSync(channel));
+export function TabSyncProvider({ channel, debug, children }: TabSyncProviderProps) {
+  const [sync] = useState(() => new TabSync(channel, { debug }));
 
   useEffect(() => {
     return () => sync[Symbol.dispose]();

package/src/adapters/sync-vue.ts

@@ -21,10 +21,10 @@ export const TabSyncKey: InjectionKey<TabSync> = Symbol('TabSync');
  * const app = createApp(App);
  * app.use(createTabSyncPlugin('my-app'));
  */
-export function createTabSyncPlugin(channel?: string) {
+export function createTabSyncPlugin(channel?: string, options?: { debug?: boolean }) {
   return {
     install(app: App) {
-      const sync = new TabSync(channel);
+      const sync = new TabSync(channel, options);
       app.provide(TabSyncKey, sync);
 
       const originalUnmount = app.unmount.bind(app);

package/src/adapters/vue.ts

@@ -29,7 +29,7 @@ export function createSharedWebSocketPlugin(url: string, options?: SharedWebSock
   return {
     install(app: App) {
       const socket = new SharedWebSocket(url, options);
-      socket.connect();
+      void socket.connect();
       app.provide(SharedWebSocketKey, socket);
 
       const originalUnmount = app.unmount.bind(app);
@@ -275,6 +275,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   if (handlers.onConnect) unsubs.push(socket.onConnect(handlers.onConnect));
   if (handlers.onDisconnect) unsubs.push(socket.onDisconnect(handlers.onDisconnect));
   if (handlers.onReconnecting) unsubs.push(socket.onReconnecting(handlers.onReconnecting));
+  if (handlers.onReconnectFailed) unsubs.push(socket.onReconnectFailed(handlers.onReconnectFailed));
   if (handlers.onLeaderChange) unsubs.push(socket.onLeaderChange(handlers.onLeaderChange));
   if (handlers.onError) unsubs.push(socket.onError(handlers.onError));
   if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));
@@ -285,6 +286,52 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   onUnmounted(() => unsubs.forEach((u) => u()));
 }
 
+/**
+ * Reactive reconnect state with a manual `reconnect` action. Use this to
+ * power a "Reconnect" snackbar/banner after auto-reconnect gives up.
+ *
+ * `hasFailed` flips to `true` once `reconnectMaxRetries` are exhausted, and
+ * back to `false` once the connection succeeds or the user calls `reconnect()`.
+ *
+ * @example
+ * <script setup>
+ * const { hasFailed, reconnect } = useSocketReconnect();
+ * </script>
+ *
+ * <template>
+ *   <div v-if="hasFailed" class="snackbar">
+ *     Connection lost.
+ *     <button @click="reconnect">Reconnect</button>
+ *   </div>
+ * </template>
+ */
+export function useSocketReconnect(): {
+  hasFailed: Ref<boolean>;
+  reconnect: () => void;
+} {
+  const socket = useSharedWebSocket();
+  const hasFailed = ref(false);
+
+  const unsubs = [
+    socket.onReconnectFailed(() => {
+      hasFailed.value = true;
+    }),
+    socket.onConnect(() => {
+      hasFailed.value = false;
+    }),
+  ];
+
+  onUnmounted(() => unsubs.forEach((u) => u()));
+
+  return {
+    hasFailed: readonly(hasFailed) as Ref<boolean>,
+    reconnect: () => {
+      hasFailed.value = false;
+      socket.reconnect();
+    },
+  };
+}
+
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/src/sync.ts

@@ -1,2 +1,2 @@
 export { TabSync } from './TabSync';
-export type { Unsubscribe } from './types';
+export type { Unsubscribe, Logger } from './types';

package/src/types.ts

@@ -1,4 +1,4 @@
-export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'failed';
 export type TabRole = 'leader' | 'follower';
 export type Unsubscribe = () => void;
 export type EventHandler<T = unknown> = (data: T) => void;
@@ -136,6 +136,8 @@ export interface SocketLifecycleHandlers {
   onConnect?: () => void;
   onDisconnect?: () => void;
   onReconnecting?: () => void;
+  /** Called when auto-reconnect gives up after exhausting reconnectMaxRetries. */
+  onReconnectFailed?: () => void;
   onLeaderChange?: (isLeader: boolean) => void;
   onError?: (error: unknown) => void;
   /** Called when this tab becomes visible/focused. */

package/src/worker/socket.worker.ts

@@ -16,15 +16,16 @@
  *   { type: 'state', state: SocketState }
  */
 
-type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'failed';
 
 interface WorkerCommand {
-  type: 'connect' | 'send' | 'disconnect';
+  type: 'connect' | 'send' | 'disconnect' | 'reconnect';
   url?: string;
   protocols?: string[];
   data?: unknown;
   reconnect?: boolean;
   reconnectMaxDelay?: number;
+  reconnectMaxRetries?: number;
   heartbeatInterval?: number;
   bufferSize?: number;
 }
@@ -40,11 +41,13 @@ let currentUrl = '';
 let currentProtocols: string[] = [];
 let shouldReconnect = true;
 let maxDelay = 30_000;
+let maxRetries = Infinity;
 let heartbeatInterval = 30_000;
 let maxBuffer = 100;
 
 // Backoff state
 let backoffDelay = 1000;
+let reconnectAttempts = 0;
 
 function setState(s: SocketState) {
   state = s;
@@ -57,6 +60,7 @@ function connect(url: string, protocols: string[]) {
   currentUrl = url;
   currentProtocols = protocols;
   backoffDelay = 1000;
+  reconnectAttempts = 0;
 
   doConnect();
 }
@@ -76,6 +80,7 @@ function doConnect() {
   ws.onopen = () => {
     setState('connected');
     backoffDelay = 1000;
+    reconnectAttempts = 0;
     self.postMessage({ type: 'open' });
     flushBuffer();
     startHeartbeat();
@@ -161,6 +166,12 @@ function stopHeartbeat() {
 }
 
 function scheduleReconnect() {
+  reconnectAttempts++;
+  if (reconnectAttempts > maxRetries) {
+    setState('failed');
+    return;
+  }
+
   setState('reconnecting');
   clearReconnect();
 
@@ -174,6 +185,25 @@ function scheduleReconnect() {
   backoffDelay = Math.min(backoffDelay * 2, maxDelay);
 }
 
+function manualReconnect() {
+  if (disposed) return;
+  clearReconnect();
+  reconnectAttempts = 0;
+  backoffDelay = 1000;
+
+  if (ws) {
+    ws.onclose = null;
+    ws.onmessage = null;
+    ws.onerror = null;
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close(1000, 'manual reconnect');
+    }
+    ws = null;
+  }
+
+  doConnect();
+}
+
 function clearReconnect() {
   if (reconnectTimer) {
     clearTimeout(reconnectTimer);
@@ -189,6 +219,7 @@ self.onmessage = (ev: MessageEvent<WorkerCommand>) => {
     case 'connect':
       if (cmd.reconnect !== undefined) shouldReconnect = cmd.reconnect;
       if (cmd.reconnectMaxDelay) maxDelay = cmd.reconnectMaxDelay;
+      if (cmd.reconnectMaxRetries !== undefined) maxRetries = cmd.reconnectMaxRetries;
       if (cmd.heartbeatInterval) heartbeatInterval = cmd.heartbeatInterval;
       if (cmd.bufferSize) maxBuffer = cmd.bufferSize;
       connect(cmd.url!, cmd.protocols ?? []);
@@ -198,6 +229,10 @@ self.onmessage = (ev: MessageEvent<WorkerCommand>) => {
       send(cmd.data);
       break;
 
+    case 'reconnect':
+      manualReconnect();
+      break;
+
     case 'disconnect':
       disconnect();
       break;