@gwakko/shared-websocket 0.12.2 → 0.13.0

package/README.md

@@ -210,7 +210,8 @@ usePush('notification', {
 | **Custom Serialization** | `serialize`/`deserialize` — JSON, MessagePack, Protobuf |
 | **Per-Event Serializers** | `ws.serializer(event, fn)` — binary for specific events |
 | **Runtime Auth** | `authenticate(token)` / `deauthenticate()` on existing connection |
-| **Lifecycle Hooks** | onConnect, onDisconnect, onActive, onInactive, onLeaderChange, onAuthChange |
+| **Lifecycle Hooks** | onConnect, onDisconnect, onReconnecting, onReconnectFailed, onActive, onInactive, onLeaderChange, onAuthChange |
+| **Manual Reconnect** | `ws.reconnect()` resets retry counter — pair with `onReconnectFailed` for a "Reconnect" snackbar |
 | **Debug/Logger** | `debug: true` + injectable logger (pino, Sentry) |
 | **Event Protocol** | Configurable field names (Socket.IO, Phoenix, Laravel Echo) |
 | **Auth** | URL param (`auth` callback / `authToken`) + runtime `authenticate()`/`deauthenticate()` |

package/dist/SharedSocket.d.ts

@@ -37,7 +37,14 @@ export declare class SharedSocket implements Disposable {
     send(data: unknown): void;
     onMessage(fn: EventHandler): Unsubscribe;
     onStateChange(fn: (state: SocketState) => void): Unsubscribe;
-    private reconnect;
+    /**
+     * Manually trigger a reconnect. Resets the retry counter and clears any
+     * scheduled backoff so the next attempt happens immediately. Use after
+     * `state === 'failed'` to let the user retry, or any time to force a
+     * fresh connection.
+     */
+    reconnect(): void;
+    private scheduleReconnect;
     private flushBuffer;
     private startHeartbeat;
     private stopHeartbeat;

package/dist/SharedWebSocket.d.ts

@@ -49,6 +49,28 @@ export declare class SharedWebSocket<TEvents extends EventMap = EventMap> implem
     onDisconnect(fn: () => void): Unsubscribe;
     /** Called when WebSocket starts reconnecting (broadcast to all tabs). */
     onReconnecting(fn: () => void): Unsubscribe;
+    /**
+     * 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;
+    /**
+     * 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;
     /** Called when this tab becomes leader or loses leadership. */
     onLeaderChange(fn: (isLeader: boolean) => void): Unsubscribe;
     /** Called on WebSocket or network error (broadcast to all tabs). */

package/dist/TabSync.d.ts

@@ -1,5 +1,11 @@
 import './utils/disposable';
-import type { Unsubscribe } from './types';
+import type { Unsubscribe, Logger } from './types';
+interface TabSyncOptions {
+    /** Enable debug logging (default: false). */
+    debug?: boolean;
+    /** Custom logger (default: console). */
+    logger?: Logger;
+}
 /**
  * Cross-tab state synchronization via BroadcastChannel.
  * No WebSocket needed — works standalone for sharing state between browser tabs.
@@ -8,13 +14,18 @@ import type { Unsubscribe } from './types';
  * 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 declare class TabSync implements Disposable {
     private store;
     private listeners;
     private bc;
     private disposed;
-    constructor(channel?: string);
+    private readonly log;
+    constructor(channel?: string, options?: TabSyncOptions);
     /** Set a value and broadcast to all tabs. Local listeners also fire. */
     set<T>(key: string, value: T): void;
     /** Get current value from local store. */
@@ -43,3 +54,4 @@ export declare class TabSync implements Disposable {
     private emit;
     [Symbol.dispose](): void;
 }
+export {};

package/dist/WorkerSocket.d.ts

@@ -27,13 +27,21 @@ export declare 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;
     });
     get state(): SocketState;
-    connect(): void;
+    connect(): Promise<void>;
+    private buildUrl;
     send(data: unknown): void;
+    /** Manually trigger reconnect: resets retry counter, attempts a fresh connection. */
+    reconnect(): void;
     disconnect(): void;
     onMessage(fn: EventHandler): Unsubscribe;
     onStateChange(fn: (state: SocketState) => void): Unsubscribe;

package/dist/adapters/react.d.ts

@@ -178,6 +178,29 @@ export declare function useSocketStatus(): {
  * });
  */
 export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): void;
+/**
+ * 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 declare function useSocketReconnect(): {
+    hasFailed: boolean;
+    reconnect: () => void;
+};
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/dist/adapters/sync-react.d.ts

@@ -15,9 +15,11 @@ import { TabSync } from '../TabSync';
 export interface TabSyncProviderProps {
     /** BroadcastChannel name (default: "tab-sync"). */
     channel?: string;
+    /** Enable debug logging. */
+    debug?: boolean;
     children: ReactNode;
 }
-export declare function TabSyncProvider({ channel, children }: TabSyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<TabSync | null>>;
+export declare function TabSyncProvider({ channel, debug, children }: TabSyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<TabSync | null>>;
 /**
  * Access the TabSync instance from context.
  *

package/dist/adapters/sync-vue.d.ts

@@ -8,7 +8,9 @@ export declare const TabSyncKey: InjectionKey<TabSync>;
  * const app = createApp(App);
  * app.use(createTabSyncPlugin('my-app'));
  */
-export declare function createTabSyncPlugin(channel?: string): {
+export declare function createTabSyncPlugin(channel?: string, options?: {
+    debug?: boolean;
+}): {
     install(app: App): void;
 };
 /**

package/dist/adapters/vue.d.ts

@@ -135,6 +135,29 @@ export declare function useSocketStatus(): {
  * });
  */
 export declare function useSocketLifecycle(handlers: SocketLifecycleHandlers): void;
+/**
+ * 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 declare function useSocketReconnect(): {
+    hasFailed: Ref<boolean>;
+    reconnect: () => void;
+};
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/dist/{chunk-RM27CYKT.js → chunk-7WBM2C7H.js}

@@ -1,17 +1,27 @@
 // src/TabSync.ts
+var NOOP_LOGGER = { debug() {
+}, info() {
+}, warn() {
+}, error() {
+} };
 var TabSync = class {
   store = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Map();
   bc;
   disposed = false;
-  constructor(channel = "tab-sync") {
+  log;
+  constructor(channel = "tab-sync", options) {
+    this.log = options?.debug ? options.logger ?? console : NOOP_LOGGER;
+    this.log.debug("[TabSync] init", { channel });
     this.bc = new BroadcastChannel(channel);
     this.bc.onmessage = (ev) => {
       const { key, value, deleted } = ev.data;
       if (deleted) {
         this.store.delete(key);
+        this.log.debug("[TabSync] \u2190 remote delete", key);
       } else {
         this.store.set(key, value);
+        this.log.debug("[TabSync] \u2190 remote set", key, value);
       }
       this.emit(key, value);
     };
@@ -20,6 +30,7 @@ var TabSync = class {
   set(key, value) {
     this.store.set(key, value);
     this.bc.postMessage({ key, value });
+    this.log.debug("[TabSync] \u2192 set", key, value);
     this.emit(key, value);
   }
   /** Get current value from local store. */
@@ -30,6 +41,7 @@ var TabSync = class {
   delete(key) {
     this.store.delete(key);
     this.bc.postMessage({ key, value: void 0, deleted: true });
+    this.log.debug("[TabSync] \u2192 delete", key);
     this.emit(key, void 0);
   }
   /** Check if a key exists in the local store. */
@@ -71,6 +83,7 @@ var TabSync = class {
   /** Clear all keys and notify listeners. */
   clear() {
     const keys = [...this.store.keys()];
+    this.log.debug("[TabSync] \u2192 clear", keys);
     this.store.clear();
     for (const key of keys) {
       this.bc.postMessage({ key, value: void 0, deleted: true });
@@ -99,4 +112,4 @@ var TabSync = class {
 export {
   TabSync
 };
-//# sourceMappingURL=chunk-RM27CYKT.js.map
+//# sourceMappingURL=chunk-7WBM2C7H.js.map

package/dist/chunk-7WBM2C7H.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/TabSync.ts"],"sourcesContent":["import './utils/disposable';\nimport type { Unsubscribe, Logger } from './types';\n\ninterface SyncMessage {\n  key: string;\n  value: unknown;\n  deleted?: boolean;\n}\n\ninterface TabSyncOptions {\n  /** Enable debug logging (default: false). */\n  debug?: boolean;\n  /** Custom logger (default: console). */\n  logger?: Logger;\n}\n\nconst NOOP_LOGGER: Logger = { debug() {}, info() {}, warn() {}, error() {} };\n\n/**\n * Cross-tab state synchronization via BroadcastChannel.\n * No WebSocket needed — works standalone for sharing state between browser tabs.\n *\n * @example\n * const sync = new TabSync('my-app');\n * sync.set('theme', 'dark');\n * sync.on('theme', (theme) => applyTheme(theme));\n *\n * @example\n * // With debug logging\n * const sync = new TabSync('my-app', { debug: true });\n */\nexport class TabSync implements Disposable {\n  private store = new Map<string, unknown>();\n  private listeners = new Map<string, Set<(value: unknown) => void>>();\n  private bc: BroadcastChannel;\n  private disposed = false;\n  private readonly log: Logger;\n\n  constructor(channel = 'tab-sync', options?: TabSyncOptions) {\n    this.log = options?.debug ? (options.logger ?? console) : NOOP_LOGGER;\n    this.log.debug('[TabSync] init', { channel });\n    this.bc = new BroadcastChannel(channel);\n    this.bc.onmessage = (ev: MessageEvent<SyncMessage>) => {\n      const { key, value, deleted } = ev.data;\n      if (deleted) {\n        this.store.delete(key);\n        this.log.debug('[TabSync] ← remote delete', key);\n      } else {\n        this.store.set(key, value);\n        this.log.debug('[TabSync] ← remote set', key, value);\n      }\n      this.emit(key, value);\n    };\n  }\n\n  /** Set a value and broadcast to all tabs. Local listeners also fire. */\n  set<T>(key: string, value: T): void {\n    this.store.set(key, value);\n    this.bc.postMessage({ key, value } satisfies SyncMessage);\n    this.log.debug('[TabSync] → set', key, value);\n    this.emit(key, value);\n  }\n\n  /** Get current value from local store. */\n  get<T>(key: string): T | undefined {\n    return this.store.get(key) as T | undefined;\n  }\n\n  /** Delete a key and broadcast deletion to all tabs. */\n  delete(key: string): void {\n    this.store.delete(key);\n    this.bc.postMessage({ key, value: undefined, deleted: true } satisfies SyncMessage);\n    this.log.debug('[TabSync] → delete', key);\n    this.emit(key, undefined);\n  }\n\n  /** Check if a key exists in the local store. */\n  has(key: string): boolean {\n    return this.store.has(key);\n  }\n\n  /** Get all keys in the local store. */\n  keys(): string[] {\n    return [...this.store.keys()];\n  }\n\n  /** Get number of entries. */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Listen for changes to a key. Fires when any tab (including this one) calls set().\n   *\n   * @example\n   * sync.on('cart', (cart) => updateBadge(cart.items.length));\n   */\n  on<T>(key: string, fn: (value: T) => void): Unsubscribe {\n    let set = this.listeners.get(key);\n    if (!set) {\n      set = new Set();\n      this.listeners.set(key, set);\n    }\n    const wrapper = fn as (value: unknown) => void;\n    set.add(wrapper);\n    return () => set!.delete(wrapper);\n  }\n\n  /** Listen for a key change once, then auto-unsubscribe. */\n  once<T>(key: string, fn: (value: T) => void): Unsubscribe {\n    const unsub = this.on<T>(key, (value) => {\n      unsub();\n      fn(value);\n    });\n    return unsub;\n  }\n\n  /** Clear all keys and notify listeners. */\n  clear(): void {\n    const keys = [...this.store.keys()];\n    this.log.debug('[TabSync] → clear', keys);\n    this.store.clear();\n    for (const key of keys) {\n      this.bc.postMessage({ key, value: undefined, deleted: true } satisfies SyncMessage);\n      this.emit(key, undefined);\n    }\n  }\n\n  /** Dispose — close BroadcastChannel and clear all state. */\n  dispose(): void {\n    this[Symbol.dispose]();\n  }\n\n  private emit(key: string, value: unknown): void {\n    const set = this.listeners.get(key);\n    if (set) {\n      for (const fn of set) fn(value);\n    }\n  }\n\n  [Symbol.dispose](): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.bc.close();\n    this.store.clear();\n    this.listeners.clear();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-FZIIMO67.js → chunk-IK4HLA3K.js}

@@ -295,7 +295,7 @@ var SharedSocket = class {
     this.ws.onclose = () => {
       this.stopHeartbeat();
       if (!this.disposed && this.opts.reconnect) {
-        this.reconnect();
+        this.scheduleReconnect();
       } else {
         this.setState("closed");
       }
@@ -335,10 +335,31 @@ var SharedSocket = class {
     this.onStateChangeFns.add(fn);
     return () => this.onStateChangeFns.delete(fn);
   }
+  /**
+   * Manually trigger a reconnect. Resets the retry counter and clears any
+   * scheduled backoff so the next attempt happens immediately. Use after
+   * `state === 'failed'` to let the user retry, or any time to force a
+   * fresh connection.
+   */
   reconnect() {
+    if (this.disposed) return;
+    this.clearReconnect();
+    this.reconnectAttempts = 0;
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.onmessage = null;
+      this.ws.onerror = null;
+      if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+        this.ws.close(1e3, "manual reconnect");
+      }
+      this.ws = null;
+    }
+    void this.connect();
+  }
+  scheduleReconnect() {
     this.reconnectAttempts++;
     if (this.reconnectAttempts > this.opts.reconnectMaxRetries) {
-      this.setState("closed");
+      this.setState("failed");
       return;
     }
     this.setState("reconnecting");
@@ -418,7 +439,14 @@ var WorkerSocket = class {
   get state() {
     return this._state;
   }
-  connect() {
+  async connect() {
+    let authToken;
+    if (this.options.auth) {
+      authToken = await this.options.auth();
+    } else if (this.options.authToken) {
+      authToken = this.options.authToken;
+    }
+    const connectUrl = authToken ? this.buildUrl(authToken) : this.url;
     const workerUrl = this.options.workerUrl ?? this.createWorkerBlob();
     this.worker = new Worker(workerUrl, { type: "module" });
     this.worker.onmessage = (ev) => {
@@ -442,17 +470,30 @@ var WorkerSocket = class {
     };
     this.worker.postMessage({
       type: "connect",
-      url: this.url,
+      url: connectUrl,
       protocols: this.options.protocols ?? [],
       reconnect: this.options.reconnect ?? true,
       reconnectMaxDelay: this.options.reconnectMaxDelay ?? 3e4,
+      reconnectMaxRetries: this.options.reconnectMaxRetries ?? Infinity,
       heartbeatInterval: this.options.heartbeatInterval ?? 3e4,
-      bufferSize: this.options.sendBuffer ?? 100
+      bufferSize: this.options.sendBuffer ?? 100,
+      pingPayload: this.options.pingPayload
     });
   }
+  buildUrl(token) {
+    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) {
     this.worker?.postMessage({ type: "send", data });
   }
+  /** Manually trigger reconnect: resets retry counter, attempts a fresh connection. */
+  reconnect() {
+    this.worker?.postMessage({ type: "reconnect" });
+  }
   disconnect() {
     this.worker?.postMessage({ type: "disconnect" });
     setTimeout(() => {
@@ -474,27 +515,43 @@ var WorkerSocket = class {
       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'); }
       };
     `;
@@ -634,6 +691,14 @@ var SharedWebSocket = class {
         }
       })
     );
+    this.cleanups.push(
+      this.bus.subscribe("ws:reconnect", () => {
+        if (this.coordinator.isLeader && this.socket) {
+          this.log.info("[SharedWS] manual reconnect requested by follower");
+          this.socket.reconnect();
+        }
+      })
+    );
     this.cleanups.push(
       this.bus.subscribe("ws:sync", (msg) => {
         this.syncStore.set(msg.key, msg.value);
@@ -660,6 +725,9 @@ var SharedWebSocket = class {
           case "reconnecting":
             this.subs.emit("$lifecycle:reconnecting", void 0);
             break;
+          case "reconnectFailed":
+            this.subs.emit("$lifecycle:reconnectFailed", void 0);
+            break;
           case "leader":
             this.subs.emit("$lifecycle:leader", msg.isLeader);
             break;
@@ -757,6 +825,36 @@ var SharedWebSocket = class {
   onReconnecting(fn) {
     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) {
+    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() {
+    if (this.coordinator.isLeader && this.socket) {
+      this.socket.reconnect();
+    } else {
+      this.bus.publish("ws:reconnect", void 0);
+    }
+  }
   /** Called when this tab becomes leader or loses leadership. */
   onLeaderChange(fn) {
     return this.subs.on("$lifecycle:leader", fn);
@@ -1103,7 +1201,10 @@ var SharedWebSocket = class {
     if (this.options.useWorker) {
       return new WorkerSocket(this.url, {
         ...socketOptions,
-        workerUrl: this.options.workerUrl
+        workerUrl: this.options.workerUrl,
+        auth: this.options.auth,
+        authToken: this.options.authToken,
+        authParam: this.options.authParam
       });
     }
     return new SharedSocket(this.url, {
@@ -1138,7 +1239,7 @@ var SharedWebSocket = class {
       this.bus.broadcast("ws:message", { event, data: payload });
     });
     this.socket.onStateChange((state) => {
-      this.log.info("[SharedWS]", state === "connected" ? "\u2713 connected" : state === "reconnecting" ? "\u{1F504} reconnecting" : `state: ${state}`);
+      this.log.info("[SharedWS]", state === "connected" ? "\u2713 connected" : state === "reconnecting" ? "\u{1F504} reconnecting" : state === "failed" ? "\u2717 reconnect failed" : `state: ${state}`);
       switch (state) {
         case "connected":
           this.bus.broadcast("ws:lifecycle", { type: "connect" });
@@ -1150,6 +1251,10 @@ var SharedWebSocket = class {
         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;
       }
     });
     this.cleanups.push(
@@ -1166,7 +1271,7 @@ var SharedWebSocket = class {
         });
       })
     );
-    this.socket.connect();
+    void this.socket.connect();
   }
   reAuthenticateOnReconnect() {
     if (!this._isAuthenticated || !this.socket) return;
@@ -1223,4 +1328,4 @@ export {
   SubscriptionManager,
   SharedWebSocket
 };
-//# sourceMappingURL=chunk-FZIIMO67.js.map
+//# sourceMappingURL=chunk-IK4HLA3K.js.map