@gwakko/shared-websocket 0.12.3 → 0.14.3

package/dist/{chunk-OVKB2KLE.cjs → chunk-YZLE4TZB.cjs}

@@ -245,6 +245,7 @@ var SharedSocket = (_class3 = class {
       reconnect: _nullishCoalesce(options.reconnect, () => ( true)),
       reconnectMaxDelay: _nullishCoalesce(options.reconnectMaxDelay, () => ( 3e4)),
       reconnectMaxRetries: _nullishCoalesce(options.reconnectMaxRetries, () => ( Infinity)),
+      authFailureCloseCodes: new Set(_nullishCoalesce(options.authFailureCloseCodes, () => ( [1008]))),
       heartbeatInterval: _nullishCoalesce(options.heartbeatInterval, () => ( 3e4)),
       sendBuffer: _nullishCoalesce(options.sendBuffer, () => ( 100)),
       auth: options.auth,
@@ -275,7 +276,13 @@ var SharedSocket = (_class3 = class {
   async connect() {
     if (this.disposed) return;
     this.setState("connecting");
-    const connectUrl = await this.buildUrl();
+    let connectUrl;
+    try {
+      connectUrl = await this.buildUrl();
+    } catch (e2) {
+      this.setState("failed");
+      return;
+    }
     this.ws = new WebSocket(connectUrl, this.opts.protocols);
     this.ws.onopen = () => {
       this.reconnectAttempts = 0;
@@ -287,15 +294,19 @@ var SharedSocket = (_class3 = class {
       let data;
       try {
         data = this.opts.deserialize(ev.data);
-      } catch (e) {
+      } catch (e3) {
         data = ev.data;
       }
       for (const fn of this.onMessageFns) fn(data);
     };
-    this.ws.onclose = () => {
+    this.ws.onclose = (ev) => {
       this.stopHeartbeat();
+      if (this.opts.authFailureCloseCodes.has(ev.code)) {
+        this.setState("failed");
+        return;
+      }
       if (!this.disposed && this.opts.reconnect) {
-        this.reconnect();
+        this.scheduleReconnect();
       } else {
         this.setState("closed");
       }
@@ -335,10 +346,31 @@ var SharedSocket = (_class3 = 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");
@@ -382,6 +414,9 @@ var SharedSocket = (_class3 = class {
     let token;
     if (this.opts.auth) {
       token = await this.opts.auth();
+      if (!token) {
+        throw new Error("SharedSocket: auth() returned no token");
+      }
     } else if (this.opts.authToken) {
       token = this.opts.authToken;
     }
@@ -418,10 +453,23 @@ var WorkerSocket = (_class4 = class {
   get state() {
     return this._state;
   }
+  setState(s) {
+    this._state = s;
+    for (const fn of this.onStateChangeFns) fn(s);
+  }
   async connect() {
     let authToken;
     if (this.options.auth) {
-      authToken = await this.options.auth();
+      try {
+        authToken = await this.options.auth();
+      } catch (e4) {
+        this.setState("failed");
+        return;
+      }
+      if (!authToken) {
+        this.setState("failed");
+        return;
+      }
     } else if (this.options.authToken) {
       authToken = this.options.authToken;
     }
@@ -454,6 +502,7 @@ var WorkerSocket = (_class4 = class {
       reconnect: _nullishCoalesce(this.options.reconnect, () => ( true)),
       reconnectMaxDelay: _nullishCoalesce(this.options.reconnectMaxDelay, () => ( 3e4)),
       reconnectMaxRetries: _nullishCoalesce(this.options.reconnectMaxRetries, () => ( Infinity)),
+      authFailureCloseCodes: _nullishCoalesce(this.options.authFailureCloseCodes, () => ( [1008])),
       heartbeatInterval: _nullishCoalesce(this.options.heartbeatInterval, () => ( 3e4)),
       bufferSize: _nullishCoalesce(this.options.sendBuffer, () => ( 100)),
       pingPayload: this.options.pingPayload
@@ -469,10 +518,14 @@ var WorkerSocket = (_class4 = class {
   send(data) {
     _optionalChain([this, 'access', _10 => _10.worker, 'optionalAccess', _11 => _11.postMessage, 'call', _12 => _12({ type: "send", data })]);
   }
+  /** Manually trigger reconnect: resets retry counter, attempts a fresh connection. */
+  reconnect() {
+    _optionalChain([this, 'access', _13 => _13.worker, 'optionalAccess', _14 => _14.postMessage, 'call', _15 => _15({ type: "reconnect" })]);
+  }
   disconnect() {
-    _optionalChain([this, 'access', _13 => _13.worker, 'optionalAccess', _14 => _14.postMessage, 'call', _15 => _15({ type: "disconnect" })]);
+    _optionalChain([this, 'access', _16 => _16.worker, 'optionalAccess', _17 => _17.postMessage, 'call', _18 => _18({ type: "disconnect" })]);
     setTimeout(() => {
-      _optionalChain([this, 'access', _16 => _16.worker, 'optionalAccess', _17 => _17.terminate, 'call', _18 => _18()]);
+      _optionalChain([this, 'access', _19 => _19.worker, 'optionalAccess', _20 => _20.terminate, 'call', _21 => _21()]);
       this.worker = null;
     }, 100);
     this._state = "closed";
@@ -491,6 +544,7 @@ var WorkerSocket = (_class4 = class {
       let heartbeatTimer = null, reconnectTimer = null;
       let url = '', protocols = [], shouldReconnect = true;
       let maxDelay = 30000, maxRetries = Infinity, hbInterval = 30000, maxBuf = 100;
+      let authFailCodes = new Set([1008]);
       let delay = 1000, attempts = 0, pingPayload = '{"type":"ping"}';
 
       function setState(s) { state = s; self.postMessage({ type: 'state', state: s }); }
@@ -500,7 +554,12 @@ var WorkerSocket = (_class4 = class {
         ws = new WebSocket(url, protocols);
         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.onclose = (e) => {
+          stopHB();
+          self.postMessage({ type: 'close', code: e.code, reason: e.reason });
+          if (authFailCodes.has(e.code)) { setState('failed'); return; }
+          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); }
@@ -509,16 +568,24 @@ var WorkerSocket = (_class4 = class {
       function stopHB() { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } }
       function reconnect() {
         attempts++;
-        if (attempts > maxRetries) { setState('closed'); return; }
+        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; maxRetries = c.reconnectMaxRetries ?? Infinity; hbInterval = c.heartbeatInterval || 30000; maxBuf = c.bufferSize || 100; if (c.pingPayload) pingPayload = JSON.stringify(c.pingPayload); connect(); }
+        if (c.type === 'connect') { url = c.url; protocols = c.protocols || []; shouldReconnect = c.reconnect ?? true; maxDelay = c.reconnectMaxDelay || 30000; maxRetries = c.reconnectMaxRetries ?? Infinity; if (c.authFailureCloseCodes) authFailCodes = new Set(c.authFailureCloseCodes); 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'); }
       };
     `;
@@ -546,25 +613,25 @@ var SubscriptionManager = (_class5 = class {constructor() { _class5.prototype.__
     return () => set.delete(handler);
   }
   once(event, handler) {
-    const wrapper = (data) => {
+    const wrapper = (data, raw) => {
       unsub();
-      handler(data);
+      handler(data, raw);
     };
     const unsub = this.on(event, wrapper);
     return unsub;
   }
   off(event, handler) {
     if (handler) {
-      _optionalChain([this, 'access', _19 => _19.handlers, 'access', _20 => _20.get, 'call', _21 => _21(event), 'optionalAccess', _22 => _22.delete, 'call', _23 => _23(handler)]);
+      _optionalChain([this, 'access', _22 => _22.handlers, 'access', _23 => _23.get, 'call', _24 => _24(event), 'optionalAccess', _25 => _25.delete, 'call', _26 => _26(handler)]);
     } else {
       this.handlers.delete(event);
     }
   }
-  emit(event, data) {
+  emit(event, data, raw) {
     this.lastMessages.set(event, data);
     const set = this.handlers.get(event);
     if (set) {
-      for (const fn of set) fn(data);
+      for (const fn of set) fn(data, raw);
     }
   }
   getLastMessage(event) {
@@ -576,13 +643,13 @@ var SubscriptionManager = (_class5 = class {constructor() { _class5.prototype.__
     let done = false;
     const unsub = this.on(event, (data) => {
       queue.push(data);
-      _optionalChain([resolve, 'optionalCall', _24 => _24()]);
+      _optionalChain([resolve, 'optionalCall', _27 => _27()]);
     });
     const onAbort = () => {
       done = true;
-      _optionalChain([resolve, 'optionalCall', _25 => _25()]);
+      _optionalChain([resolve, 'optionalCall', _28 => _28()]);
     };
-    _optionalChain([signal, 'optionalAccess', _26 => _26.addEventListener, 'call', _27 => _27("abort", onAbort)]);
+    _optionalChain([signal, 'optionalAccess', _29 => _29.addEventListener, 'call', _30 => _30("abort", onAbort)]);
     try {
       while (!done) {
         if (queue.length > 0) {
@@ -596,7 +663,7 @@ var SubscriptionManager = (_class5 = class {constructor() { _class5.prototype.__
       }
     } finally {
       unsub();
-      _optionalChain([signal, 'optionalAccess', _28 => _28.removeEventListener, 'call', _29 => _29("abort", onAbort)]);
+      _optionalChain([signal, 'optionalAccess', _31 => _31.removeEventListener, 'call', _32 => _32("abort", onAbort)]);
     }
   }
   offAll() {
@@ -632,8 +699,9 @@ var NOOP_LOGGER = {
   error() {
   }
 };
+var CHANNEL_KEY_SEP = "";
 var SharedWebSocket = (_class6 = class {
-  constructor(url, options = {}) {;_class6.prototype.__init26.call(this);_class6.prototype.__init27.call(this);_class6.prototype.__init28.call(this);_class6.prototype.__init29.call(this);_class6.prototype.__init30.call(this);_class6.prototype.__init31.call(this);_class6.prototype.__init32.call(this);_class6.prototype.__init33.call(this);_class6.prototype.__init34.call(this);_class6.prototype.__init35.call(this);_class6.prototype.__init36.call(this);_class6.prototype.__init37.call(this);
+  constructor(url, options = {}) {;_class6.prototype.__init26.call(this);_class6.prototype.__init27.call(this);_class6.prototype.__init28.call(this);_class6.prototype.__init29.call(this);_class6.prototype.__init30.call(this);_class6.prototype.__init31.call(this);_class6.prototype.__init32.call(this);_class6.prototype.__init33.call(this);_class6.prototype.__init34.call(this);_class6.prototype.__init35.call(this);_class6.prototype.__init36.call(this);_class6.prototype.__init37.call(this);_class6.prototype.__init38.call(this);_class6.prototype.__init39.call(this);_class6.prototype.__init40.call(this);_class6.prototype.__init41.call(this);_class6.prototype.__init42.call(this);
     this.url = url;
     this.options = options;
     this.proto = { ...DEFAULT_PROTOCOL, ...options.events };
@@ -648,16 +716,69 @@ var SharedWebSocket = (_class6 = class {
     });
     this.cleanups.push(
       this.bus.subscribe("ws:message", (msg) => {
-        this.subs.emit(msg.event, msg.data);
+        this.subs.emit(msg.event, msg.data, msg.raw);
+        for (const channelName of this.channelRefs.keys()) {
+          const prefix = channelName + ":";
+          if (msg.event.length > prefix.length && msg.event.startsWith(prefix)) {
+            const subEvent = msg.event.slice(prefix.length);
+            this.subs.emit(`${channelName}${CHANNEL_KEY_SEP}${subEvent}`, msg.data, msg.raw);
+          }
+        }
+        if (this.rawFrameListeners.size > 0) {
+          for (const fn of this.rawFrameListeners) {
+            try {
+              fn(msg.raw);
+            } catch (e5) {
+            }
+          }
+        }
+      })
+    );
+    this.cleanups.push(
+      this.bus.subscribe("ws:dispatch", (msg) => {
+        if (this.coordinator.isLeader && this.socket) {
+          this.transmit(msg.kind, msg.payload);
+          if (msg.id) this.bus.publish("ws:dispatch-flushed", { id: msg.id });
+        }
+      })
+    );
+    this.cleanups.push(
+      this.bus.subscribe("ws:dispatch-flushed", (msg) => {
+        this.pendingOutbound.delete(msg.id);
+      })
+    );
+    this.cleanups.push(
+      this.bus.subscribe("ws:gather-pending", (req) => {
+        if (this.pendingOutbound.size === 0) return;
+        this.bus.publish(`ws:pending:${req.replyId}`, {
+          entries: [...this.pendingOutbound.values()]
+        });
       })
     );
     this.cleanups.push(
-      this.bus.subscribe("ws:send", (msg) => {
+      this.bus.subscribe("ws:reconnect", () => {
         if (this.coordinator.isLeader && this.socket) {
-          this.socket.send({ [this.proto.eventField]: msg.event, [this.proto.dataField]: msg.data });
+          this.log.info("[SharedWS] manual reconnect requested by follower");
+          this.socket.reconnect();
         }
       })
     );
+    this.cleanups.push(
+      this.bus.subscribe("ws:authenticate-resume", () => {
+        if (this.coordinator.isLeader && _optionalChain([this, 'access', _33 => _33.socket, 'optionalAccess', _34 => _34.state]) === "failed") {
+          this.log.info("[SharedWS] resume requested after auth \u2014 reconnecting failed socket");
+          this.socket.reconnect();
+        }
+      })
+    );
+    this.cleanups.push(
+      this.bus.subscribe("ws:gather-subs", (req) => {
+        this.bus.publish(`ws:subs:${req.replyId}`, {
+          channels: [...this.channelRefs.keys()],
+          topics: [...this.topics]
+        });
+      })
+    );
     this.cleanups.push(
       this.bus.subscribe("ws:sync", (msg) => {
         this.syncStore.set(msg.key, msg.value);
@@ -684,6 +805,9 @@ var SharedWebSocket = (_class6 = 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;
@@ -750,8 +874,29 @@ var SharedWebSocket = (_class6 = class {
   __init35() {this._isAuthenticated = false}
   __init36() {this.authChannels = /* @__PURE__ */ new Map()}
   __init37() {this.authTopics = /* @__PURE__ */ new Set()}
+  /**
+   * Refcount of active channel subscriptions per name. Used to route
+   * incoming events back to channel handlers via `${name}<RS>${event}`
+   * keys without colliding when names/events contain `:`, and as the
+   * source for cross-tab subscription replay on leader change.
+   */
+  __init38() {this.channelRefs = /* @__PURE__ */ new Map()}
+  /** All topic subscriptions (auth and non-auth). Replayed on leader change. */
+  __init39() {this.topics = /* @__PURE__ */ new Set()}
+  /** Listeners for every raw incoming frame (post-deserialize, post-middleware). */
+  __init40() {this.rawFrameListeners = /* @__PURE__ */ new Set()}
+  /**
+   * Local outbound buffer of follower-originated dispatches awaiting flush
+   * confirmation from the leader. Drained when the leader broadcasts
+   * `ws:dispatch-flushed` for the entry's id; replayed by the next leader
+   * after gathering across surviving tabs. Insertion order preserved
+   * (Map) so we drop oldest on overflow.
+   */
+  __init41() {this.pendingOutbound = /* @__PURE__ */ new Map()}
+  /** Periodic refresh timer — leader only. Recreated on each leader handover. */
+  __init42() {this.refreshTimer = null}
   get connected() {
-    return _optionalChain([this, 'access', _30 => _30.socket, 'optionalAccess', _31 => _31.state]) === "connected" || !this.coordinator.isLeader;
+    return _optionalChain([this, 'access', _35 => _35.socket, 'optionalAccess', _36 => _36.state]) === "connected" || !this.coordinator.isLeader;
   }
   get tabRole() {
     return this.coordinator.isLeader ? "leader" : "follower";
@@ -781,6 +926,36 @@ var SharedWebSocket = (_class6 = 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);
@@ -823,9 +998,16 @@ var SharedWebSocket = (_class6 = class {
     this._isAuthenticated = true;
     this.syncStore.set("$auth:token", token);
     this.bus.broadcast("ws:sync", { key: "$auth:token", value: token });
-    this.send(this.proto.authLogin, { token });
     this.bus.broadcast("ws:lifecycle", { type: "auth", authenticated: true });
     this.log.info("[SharedWS] authenticated");
+    if (this.coordinator.isLeader && this.socket && this.socket.state === "failed") {
+      this.reconnect();
+      return;
+    }
+    if (!this.coordinator.isLeader) {
+      this.bus.publish("ws:authenticate-resume", void 0);
+    }
+    this.dispatch("auth-login", { data: token });
   }
   /**
    * Deauthenticate — notifies server, auto-leaves all auth-required channels
@@ -840,7 +1022,7 @@ var SharedWebSocket = (_class6 = class {
     for (const topic of this.authTopics) this.unsubscribe(topic);
     this.authTopics.clear();
     this._isAuthenticated = false;
-    this.send(this.proto.authLogout, {});
+    this.dispatch("auth-logout", {});
     this.syncStore.delete("$auth:token");
     this.bus.broadcast("ws:sync", { key: "$auth:token", value: void 0 });
     this.bus.broadcast("ws:lifecycle", { type: "auth", authenticated: false });
@@ -928,22 +1110,23 @@ var SharedWebSocket = (_class6 = class {
   stream(event, signal) {
     return this.subs.stream(event, signal);
   }
-  send(event, data) {
+  send(event, data, extras) {
+    this.assertExtrasReserved(extras);
     const eventSerializer = this.serializers.get(event);
     const serializedData = eventSerializer ? eventSerializer(data) : data;
-    let payload = { [this.proto.eventField]: event, [this.proto.dataField]: serializedData };
-    for (const mw of this.outgoingMiddleware) {
-      payload = mw(payload);
-      if (payload === null) {
-        this.log.debug("[SharedWS] \u2717 outgoing dropped by middleware", event);
-        return;
-      }
+    this.dispatch("event", { event, data: serializedData, extras });
+  }
+  assertExtrasReserved(extras) {
+    if (!extras) return;
+    if (this.proto.eventField in extras) {
+      throw new Error(
+        `SharedWebSocket.send: extras cannot contain reserved key "${this.proto.eventField}" (eventField). Pass the event name as the first argument instead.`
+      );
     }
-    this.log.debug("[SharedWS] \u2192 send", event, data);
-    if (this.coordinator.isLeader && this.socket) {
-      this.socket.send(payload);
-    } else {
-      this.bus.publish("ws:send", { event, data });
+    if (this.proto.dataField in extras) {
+      throw new Error(
+        `SharedWebSocket.send: extras cannot contain reserved key "${this.proto.dataField}" (dataField). Pass the payload as the second argument instead.`
+      );
     }
   }
   /** Request/response through server via leader. */
@@ -977,33 +1160,76 @@ var SharedWebSocket = (_class6 = class {
    * notifications.on('alert', (alert) => showToast(alert));
    */
   channel(name, options) {
-    this.send(this.proto.channelJoin, { channel: name });
+    const matcher = this.proto.channelAckMatcher;
+    const ackTimeout = _nullishCoalesce(this.proto.channelAckTimeout, () => ( 5e3));
+    let cancelReady;
+    const ready = matcher ? new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (fn) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        unsubAck();
+        fn();
+      };
+      const unsubAck = this.onRawFrame((frame) => {
+        let result;
+        try {
+          result = matcher(frame, name);
+        } catch (e6) {
+          result = "reject";
+        }
+        if (result === "ok") settle(() => resolve());
+        else if (result === "reject") settle(() => reject(new Error(`SharedWebSocket: subscribe rejected for channel "${name}"`)));
+      });
+      const timer = setTimeout(
+        () => settle(() => reject(new Error(`SharedWebSocket: subscribe ack timeout for channel "${name}"`))),
+        ackTimeout
+      );
+      cancelReady = (err) => settle(() => reject(err));
+    }) : Promise.resolve();
+    if (matcher) ready.catch(() => {
+    });
+    this.dispatch("subscribe", { channel: name });
+    this.channelRefs.set(name, (_nullishCoalesce(this.channelRefs.get(name), () => ( 0))) + 1);
     const self = this;
     const unsubs = [];
-    const isAuth = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _32 => _32.auth]), () => ( false));
+    const isAuth = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _37 => _37.auth]), () => ( false));
+    let left = false;
+    const key = (event) => `${name}${CHANNEL_KEY_SEP}${event}`;
     const ch = {
       name,
+      ready,
       on(event, handler) {
-        const unsub = self.subs.on(`${name}:${event}`, handler);
+        const unsub = self.subs.on(key(event), handler);
         unsubs.push(unsub);
         return unsub;
       },
       once(event, handler) {
-        const unsub = self.subs.once(`${name}:${event}`, handler);
+        const unsub = self.subs.once(key(event), handler);
         unsubs.push(unsub);
         return unsub;
       },
       send(event, data) {
-        self.send(`${name}:${event}`, data);
+        const joined = `${name}:${event}`;
+        const eventSerializer = _nullishCoalesce(self.serializers.get(joined), () => ( self.serializers.get(event)));
+        const serializedData = eventSerializer ? eventSerializer(data) : data;
+        self.dispatch("event", { event, data: serializedData, channel: name });
       },
       stream(event, signal) {
-        return self.subs.stream(`${name}:${event}`, signal);
+        return self.subs.stream(key(event), signal);
       },
       leave() {
-        self.send(self.proto.channelLeave, { channel: name });
+        if (left) return;
+        left = true;
+        _optionalChain([cancelReady, 'optionalCall', _38 => _38(new Error(`SharedWebSocket: channel "${name}" left before ack`))]);
+        self.dispatch("unsubscribe", { channel: name });
         for (const unsub of unsubs) unsub();
         unsubs.length = 0;
         if (isAuth) self.authChannels.delete(name);
+        const next = (_nullishCoalesce(self.channelRefs.get(name), () => ( 1))) - 1;
+        if (next <= 0) self.channelRefs.delete(name);
+        else self.channelRefs.set(name, next);
       }
     };
     if (isAuth) {
@@ -1022,8 +1248,9 @@ var SharedWebSocket = (_class6 = class {
    * ws.subscribe(`user:${userId}:mentions`);
    */
   subscribe(topic, options) {
-    this.send(this.proto.topicSubscribe, { topic });
-    if (_optionalChain([options, 'optionalAccess', _33 => _33.auth])) {
+    this.dispatch("topic-subscribe", { topic });
+    this.topics.add(topic);
+    if (_optionalChain([options, 'optionalAccess', _39 => _39.auth])) {
       this.authTopics.add(topic);
     }
     this.log.debug("[SharedWS] subscribe topic", topic);
@@ -1033,7 +1260,8 @@ var SharedWebSocket = (_class6 = class {
    * Sends topicUnsubscribe event (default: "$topic:unsubscribe").
    */
   unsubscribe(topic) {
-    this.send(this.proto.topicUnsubscribe, { topic });
+    this.dispatch("topic-unsubscribe", { topic });
+    this.topics.delete(topic);
     this.authTopics.delete(topic);
     this.log.debug("[SharedWS] unsubscribe topic", topic);
   }
@@ -1114,12 +1342,126 @@ var SharedWebSocket = (_class6 = class {
   disconnect() {
     this[Symbol.dispose]();
   }
+  // ─── Frame Pipeline ─────────────────────────────────
+  //
+  // dispatch(kind, payload) is the single entry point for all outgoing
+  // frames (events, channel join/leave, topic sub/unsub, auth login/logout).
+  // - On the leader, it calls transmit() which builds the frame, runs
+  //   outgoing middleware, and writes to the socket.
+  // - On followers, it forwards { kind, payload } over BroadcastChannel;
+  //   the leader's bus subscriber re-enters transmit() so middleware
+  //   runs in exactly one place regardless of which tab originated.
+  //
+  // The actual wire shape is decided by frameBuilder (custom) or
+  // defaultFrameBuilder (legacy two-key { event, data } envelope).
+  /**
+   * Build the wire frame for a given kind. Honors custom `frameBuilder`.
+   * Return-value contract:
+   *   - any concrete value → use as the frame
+   *   - `null`             → drop the frame (intentional filter)
+   *   - `undefined`        → fall back to the default builder for this kind
+   */
+  buildFrame(kind, payload) {
+    if (this.proto.frameBuilder) {
+      const result = this.proto.frameBuilder(kind, payload);
+      if (result !== void 0) return result;
+    }
+    return this.defaultFrameBuilder(kind, payload);
+  }
+  /**
+   * Subscribe to every raw incoming frame (post-deserialize). Used by
+   * `Channel.ready`'s ack matcher. Internal — not part of the public API.
+   */
+  onRawFrame(fn) {
+    this.rawFrameListeners.add(fn);
+    return () => {
+      this.rawFrameListeners.delete(fn);
+    };
+  }
+  /** Legacy two-key builder — preserved as the default for back-compat. */
+  defaultFrameBuilder(kind, p) {
+    let eventName;
+    let dataPart;
+    switch (kind) {
+      case "event":
+        eventName = p.channel ? `${p.channel}:${_nullishCoalesce(p.event, () => ( ""))}` : _nullishCoalesce(p.event, () => ( this.proto.defaultEvent));
+        dataPart = p.data;
+        break;
+      case "subscribe":
+        eventName = this.proto.channelJoin;
+        dataPart = { channel: p.channel };
+        break;
+      case "unsubscribe":
+        eventName = this.proto.channelLeave;
+        dataPart = { channel: p.channel };
+        break;
+      case "topic-subscribe":
+        eventName = this.proto.topicSubscribe;
+        dataPart = { topic: p.topic };
+        break;
+      case "topic-unsubscribe":
+        eventName = this.proto.topicUnsubscribe;
+        dataPart = { topic: p.topic };
+        break;
+      case "auth-login":
+        eventName = this.proto.authLogin;
+        dataPart = { token: p.data };
+        break;
+      case "auth-logout":
+        eventName = this.proto.authLogout;
+        dataPart = {};
+        break;
+    }
+    return {
+      ..._nullishCoalesce(p.extras, () => ( {})),
+      [this.proto.eventField]: eventName,
+      [this.proto.dataField]: dataPart
+    };
+  }
+  /** Route a structured frame: leader transmits, followers forward via bus. */
+  dispatch(kind, payload) {
+    if (this.coordinator.isLeader && this.socket) {
+      this.transmit(kind, payload);
+      return;
+    }
+    const id = generateId();
+    this.enqueuePending(id, kind, payload);
+    this.bus.publish("ws:dispatch", { id, kind, payload });
+  }
+  enqueuePending(id, kind, payload) {
+    const max = _nullishCoalesce(this.options.outboundBufferSize, () => ( 100));
+    if (max <= 0) return;
+    if (this.pendingOutbound.size >= max) {
+      const oldestKey = this.pendingOutbound.keys().next().value;
+      if (oldestKey !== void 0) this.pendingOutbound.delete(oldestKey);
+    }
+    this.pendingOutbound.set(id, { id, kind, payload, enqueuedAt: Date.now() });
+  }
+  /** Build, run middleware, and write to the socket. Leader-only. */
+  transmit(kind, payload) {
+    if (!this.socket) return;
+    let frame = this.buildFrame(kind, payload);
+    if (frame === null) {
+      this.log.debug("[SharedWS] \u2717 frameBuilder dropped frame", kind);
+      return;
+    }
+    for (const mw of this.outgoingMiddleware) {
+      frame = mw(frame);
+      if (frame === null) {
+        this.log.debug("[SharedWS] \u2717 outgoing dropped by middleware", kind);
+        return;
+      }
+    }
+    this.log.debug("[SharedWS] \u2192 send", kind, payload);
+    this.socket.send(frame);
+  }
   createSocket() {
     const socketOptions = {
       protocols: this.options.protocols,
       reconnect: this.options.reconnect,
       reconnectMaxDelay: this.options.reconnectMaxDelay,
       reconnectMaxRetries: this.options.reconnectMaxRetries,
+      authFailureCloseCodes: this.options.authFailureCloseCodes,
       heartbeatInterval: this.options.heartbeatInterval,
       sendBuffer: this.options.sendBuffer,
       pingPayload: this.proto.ping
@@ -1145,6 +1487,7 @@ var SharedWebSocket = (_class6 = class {
   handleBecomeLeader() {
     this.log.info("[SharedWS] \u{1F451} became leader");
     this.socket = this.createSocket();
+    this.startRefreshTimer();
     this.socket.onMessage((raw) => {
       let data = raw;
       for (const mw of this.incomingMiddleware) {
@@ -1155,21 +1498,21 @@ var SharedWebSocket = (_class6 = class {
         }
       }
       const msg = data;
-      const event = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _34 => _34[this.proto.eventField]]), () => ( this.proto.defaultEvent));
-      let payload = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _35 => _35[this.proto.dataField]]), () => ( data));
+      const event = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _40 => _40[this.proto.eventField]]), () => ( this.proto.defaultEvent));
+      let payload = _nullishCoalesce(_optionalChain([msg, 'optionalAccess', _41 => _41[this.proto.dataField]]), () => ( data));
       const eventDeserializer = this.deserializers.get(event);
       if (eventDeserializer) {
         payload = eventDeserializer(payload);
       }
       this.log.debug("[SharedWS] \u2190 recv", event, payload);
-      this.bus.broadcast("ws:message", { event, data: payload });
+      this.bus.broadcast("ws:message", { event, data: payload, raw: data });
     });
     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" });
-          this.reAuthenticateOnReconnect();
+          void this.onConnected();
           break;
         case "closed":
           this.bus.broadcast("ws:lifecycle", { type: "disconnect" });
@@ -1177,6 +1520,10 @@ var SharedWebSocket = (_class6 = 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(
@@ -1184,49 +1531,182 @@ var SharedWebSocket = (_class6 = class {
         return new Promise((resolve) => {
           const unsub = this.socket.onMessage((response) => {
             const res = response;
-            if (_optionalChain([res, 'optionalAccess', _36 => _36[this.proto.eventField]]) === req.event || _optionalChain([res, 'optionalAccess', _37 => _37.requestId])) {
+            if (_optionalChain([res, 'optionalAccess', _42 => _42[this.proto.eventField]]) === req.event || _optionalChain([res, 'optionalAccess', _43 => _43.requestId])) {
               unsub();
-              resolve(_nullishCoalesce(_optionalChain([res, 'optionalAccess', _38 => _38[this.proto.dataField]]), () => ( response)));
+              resolve(_nullishCoalesce(_optionalChain([res, 'optionalAccess', _44 => _44[this.proto.dataField]]), () => ( response)));
             }
           });
-          this.socket.send({ event: req.event, data: req.data });
+          this.transmit("event", { event: req.event, data: req.data });
         });
       })
     );
     void this.socket.connect();
   }
-  reAuthenticateOnReconnect() {
-    if (!this._isAuthenticated || !this.socket) return;
-    const token = this.syncStore.get("$auth:token");
-    if (token) {
-      this.socket.send({
-        [this.proto.eventField]: this.proto.authLogin,
-        [this.proto.dataField]: { token }
-      });
-      this.log.debug("[SharedWS] re-authenticated after reconnect");
+  /**
+   * Re-establish all server-side state on the freshly connected leader socket:
+   *   1. auth-login (so server accepts subsequent joins on auth channels)
+   *   2. channel-join for the union of channels held by ALL surviving tabs
+   *   3. topic-subscribe for the union of topics held by ALL surviving tabs
+   *
+   * The union covers leader handover: when a follower with handlers is
+   * promoted, no tab's subscriptions get silently dropped. Frames are sent
+   * in FIFO order over the single WebSocket, so auth precedes the joins
+   * that depend on it.
+   */
+  /**
+   * Orchestrate post-connect recovery: replay subscriptions first (so the
+   * server is ready to route events for any channels we still care about),
+   * then drain follower-pending dispatches that didn't reach the previous
+   * leader's socket.
+   */
+  async onConnected() {
+    await this.resubscribeOnConnect();
+    await this.replayPendingDispatches();
+  }
+  async resubscribeOnConnect() {
+    if (!this.socket) return;
+    const socket = this.socket;
+    if (this._isAuthenticated) {
+      const token = this.syncStore.get("$auth:token");
+      if (token) {
+        this.transmit("auth-login", { data: token });
+        this.log.debug("[SharedWS] re-authenticated after reconnect");
+      }
     }
-    for (const name of this.authChannels.keys()) {
-      this.socket.send({
-        [this.proto.eventField]: this.proto.channelJoin,
-        [this.proto.dataField]: { channel: name }
-      });
+    const { channels, topics } = await this.gatherSubscriptions();
+    if (this.socket !== socket) return;
+    for (const name of channels) {
+      this.transmit("subscribe", { channel: name });
     }
-    for (const topic of this.authTopics) {
-      this.socket.send({
-        [this.proto.eventField]: this.proto.topicSubscribe,
-        [this.proto.dataField]: { topic }
+    for (const topic of topics) {
+      this.transmit("topic-subscribe", { topic });
+    }
+    if (channels.length || topics.length) {
+      this.log.info("[SharedWS] replayed subscriptions", {
+        channels: channels.length,
+        topics: topics.length
       });
     }
   }
+  /**
+   * Replay buffered follower dispatches over the freshly connected socket.
+   * Gathers from all tabs (including this one), de-dups by id, transmits,
+   * then signals each originator to drop its local entry. Drops own-tab
+   * entries after transmission since `bus.publish` doesn't echo to self.
+   */
+  async replayPendingDispatches() {
+    if (!this.socket) return;
+    const socket = this.socket;
+    const entries = await this.gatherPendingDispatches();
+    if (this.socket !== socket) return;
+    if (entries.length === 0) return;
+    let sent = 0;
+    for (const e of entries) {
+      this.transmit(e.kind, e.payload);
+      this.pendingOutbound.delete(e.id);
+      this.bus.publish("ws:dispatch-flushed", { id: e.id });
+      sent++;
+    }
+    this.log.info("[SharedWS] replayed pending dispatches", { count: sent });
+  }
+  /**
+   * Cross-tab pending-dispatch gather. Same shape as `gatherSubscriptions`
+   * — broadcasts a one-shot request, collects for a short window, dedups
+   * by id (so multiple tabs holding the same id don't double-replay).
+   */
+  gatherPendingDispatches(timeoutMs = 100) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const e of this.pendingOutbound.values()) {
+      seen.set(e.id, { id: e.id, kind: e.kind, payload: e.payload });
+    }
+    const replyId = generateId();
+    return new Promise((resolve) => {
+      const unsub = this.bus.subscribe(
+        `ws:pending:${replyId}`,
+        (msg) => {
+          for (const e of msg.entries) {
+            if (!seen.has(e.id)) seen.set(e.id, { id: e.id, kind: e.kind, payload: e.payload });
+          }
+        }
+      );
+      this.bus.publish("ws:gather-pending", { replyId });
+      setTimeout(() => {
+        unsub();
+        resolve([...seen.values()]);
+      }, timeoutMs);
+    });
+  }
+  /**
+   * Best-effort cross-tab gather. Broadcasts a request and collects responses
+   * for a short window. Times out gracefully — late responses are dropped.
+   * The leader's own subs are seeded into the result to avoid relying on
+   * BroadcastChannel echo to self.
+   */
+  gatherSubscriptions(timeoutMs = 150) {
+    const channels = new Set(this.channelRefs.keys());
+    const topics = new Set(this.topics);
+    const replyId = generateId();
+    return new Promise((resolve) => {
+      const unsub = this.bus.subscribe(
+        `ws:subs:${replyId}`,
+        (msg) => {
+          for (const c of msg.channels) channels.add(c);
+          for (const t of msg.topics) topics.add(t);
+        }
+      );
+      this.bus.publish("ws:gather-subs", { replyId });
+      setTimeout(() => {
+        unsub();
+        resolve({ channels: [...channels], topics: [...topics] });
+      }, timeoutMs);
+    });
+  }
   handleLoseLeadership() {
+    this.stopRefreshTimer();
     if (this.socket) {
       this.socket[Symbol.dispose]();
       this.socket = null;
     }
   }
+  /**
+   * Start a leader-only periodic refresh of the auth token. The callback
+   * is `options.refresh` (preferred) or `options.auth` (fallback). When
+   * the timer fires and the connection is currently authenticated, the
+   * returned token is fed back through `authenticate()` so subscribers
+   * stay synced and the leader's socket re-issues auth-login.
+   *
+   * Idempotent — calling start while already running is a no-op.
+   */
+  startRefreshTimer() {
+    if (this.refreshTimer) return;
+    const interval = this.options.refreshTokenInterval;
+    const refresh = _nullishCoalesce(this.options.refresh, () => ( this.options.auth));
+    if (!interval || interval <= 0 || !refresh) return;
+    if (!this.coordinator.isLeader) return;
+    this.refreshTimer = setInterval(async () => {
+      if (!this.coordinator.isLeader || !this._isAuthenticated) return;
+      try {
+        const token = await refresh();
+        if (!token) {
+          this.log.warn("[SharedWS] refresh() returned empty token \u2014 skipping");
+          return;
+        }
+        this.authenticate(token);
+      } catch (err) {
+        this.log.warn("[SharedWS] refresh() failed", err);
+      }
+    }, interval);
+  }
+  stopRefreshTimer() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
   [Symbol.dispose]() {
     if (this.disposed) return;
     this.disposed = true;
+    this.stopRefreshTimer();
     this.coordinator[Symbol.dispose]();
     if (this.socket) {
       this.socket[Symbol.dispose]();
@@ -1239,6 +1719,10 @@ var SharedWebSocket = (_class6 = class {
     this.syncStore.clear();
     this.authChannels.clear();
     this.authTopics.clear();
+    this.channelRefs.clear();
+    this.topics.clear();
+    this.rawFrameListeners.clear();
+    this.pendingOutbound.clear();
   }
 }, _class6);
 
@@ -1250,4 +1734,4 @@ var SharedWebSocket = (_class6 = class {
 
 
 exports.MessageBus = MessageBus; exports.TabCoordinator = TabCoordinator; exports.SharedSocket = SharedSocket; exports.WorkerSocket = WorkerSocket; exports.SubscriptionManager = SubscriptionManager; exports.SharedWebSocket = SharedWebSocket;
-//# sourceMappingURL=chunk-OVKB2KLE.cjs.map
+//# sourceMappingURL=chunk-YZLE4TZB.cjs.map