@gwakko/shared-websocket 0.13.0 → 0.14.5

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

@@ -21,7 +21,9 @@ var MessageBus = class {
   pendingRequests = /* @__PURE__ */ new Map();
   subscribe(topic, fn) {
     const wrapper = (msg) => {
-      if (msg.source !== this.tabId) fn(msg.data);
+      if (msg.type !== "publish" || msg.source !== this.tabId) {
+        fn(msg.data);
+      }
     };
     this.addListener(topic, wrapper);
     return () => this.removeListener(topic, wrapper);
@@ -245,6 +247,7 @@ var SharedSocket = class {
       reconnect: options.reconnect ?? true,
       reconnectMaxDelay: options.reconnectMaxDelay ?? 3e4,
       reconnectMaxRetries: options.reconnectMaxRetries ?? Infinity,
+      authFailureCloseCodes: new Set(options.authFailureCloseCodes ?? [1008]),
       heartbeatInterval: options.heartbeatInterval ?? 3e4,
       sendBuffer: options.sendBuffer ?? 100,
       auth: options.auth,
@@ -275,7 +278,13 @@ var SharedSocket = class {
   async connect() {
     if (this.disposed) return;
     this.setState("connecting");
-    const connectUrl = await this.buildUrl();
+    let connectUrl;
+    try {
+      connectUrl = await this.buildUrl();
+    } catch {
+      this.setState("failed");
+      return;
+    }
     this.ws = new WebSocket(connectUrl, this.opts.protocols);
     this.ws.onopen = () => {
       this.reconnectAttempts = 0;
@@ -292,8 +301,12 @@ var SharedSocket = class {
       }
       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.scheduleReconnect();
       } else {
@@ -403,6 +416,9 @@ var SharedSocket = 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;
     }
@@ -439,10 +455,23 @@ var WorkerSocket = 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 {
+        this.setState("failed");
+        return;
+      }
+      if (!authToken) {
+        this.setState("failed");
+        return;
+      }
     } else if (this.options.authToken) {
       authToken = this.options.authToken;
     }
@@ -475,6 +504,7 @@ var WorkerSocket = class {
       reconnect: this.options.reconnect ?? true,
       reconnectMaxDelay: this.options.reconnectMaxDelay ?? 3e4,
       reconnectMaxRetries: this.options.reconnectMaxRetries ?? Infinity,
+      authFailureCloseCodes: this.options.authFailureCloseCodes ?? [1008],
       heartbeatInterval: this.options.heartbeatInterval ?? 3e4,
       bufferSize: this.options.sendBuffer ?? 100,
       pingPayload: this.options.pingPayload
@@ -516,6 +546,7 @@ var WorkerSocket = 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 }); }
@@ -525,7 +556,12 @@ var WorkerSocket = 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); }
@@ -549,7 +585,7 @@ var WorkerSocket = class {
       }
       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'); }
@@ -579,9 +615,9 @@ var SubscriptionManager = class {
     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;
@@ -593,11 +629,11 @@ var SubscriptionManager = class {
       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) {
@@ -665,6 +701,7 @@ var NOOP_LOGGER = {
   error() {
   }
 };
+var CHANNEL_KEY_SEP = "";
 var SharedWebSocket = class {
   constructor(url, options = {}) {
     this.url = url;
@@ -681,16 +718,45 @@ var SharedWebSocket = 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 {
+            }
+          }
+        }
       })
     );
     this.cleanups.push(
-      this.bus.subscribe("ws:send", (msg) => {
+      this.bus.subscribe("ws:dispatch", (msg) => {
         if (this.coordinator.isLeader && this.socket) {
-          this.socket.send({ [this.proto.eventField]: msg.event, [this.proto.dataField]: msg.data });
+          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:reconnect", () => {
         if (this.coordinator.isLeader && this.socket) {
@@ -699,6 +765,22 @@ var SharedWebSocket = class {
         }
       })
     );
+    this.cleanups.push(
+      this.bus.subscribe("ws:authenticate-resume", () => {
+        if (this.coordinator.isLeader && this.socket?.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);
@@ -794,6 +876,27 @@ var SharedWebSocket = class {
   _isAuthenticated = false;
   authChannels = /* @__PURE__ */ new Map();
   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.
+   */
+  channelRefs = /* @__PURE__ */ new Map();
+  /** All topic subscriptions (auth and non-auth). Replayed on leader change. */
+  topics = /* @__PURE__ */ new Set();
+  /** Listeners for every raw incoming frame (post-deserialize, post-middleware). */
+  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.
+   */
+  pendingOutbound = /* @__PURE__ */ new Map();
+  /** Periodic refresh timer — leader only. Recreated on each leader handover. */
+  refreshTimer = null;
   get connected() {
     return this.socket?.state === "connected" || !this.coordinator.isLeader;
   }
@@ -897,9 +1000,16 @@ var SharedWebSocket = 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
@@ -914,7 +1024,7 @@ var SharedWebSocket = 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 });
@@ -1002,22 +1112,23 @@ var SharedWebSocket = 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. */
@@ -1051,33 +1162,76 @@ var SharedWebSocket = class {
    * notifications.on('alert', (alert) => showToast(alert));
    */
   channel(name, options) {
-    this.send(this.proto.channelJoin, { channel: name });
+    const matcher = this.proto.channelAckMatcher;
+    const ackTimeout = 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 {
+          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, (this.channelRefs.get(name) ?? 0) + 1);
     const self = this;
     const unsubs = [];
     const isAuth = options?.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 = 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;
+        cancelReady?.(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 = (self.channelRefs.get(name) ?? 1) - 1;
+        if (next <= 0) self.channelRefs.delete(name);
+        else self.channelRefs.set(name, next);
       }
     };
     if (isAuth) {
@@ -1096,7 +1250,8 @@ var SharedWebSocket = class {
    * ws.subscribe(`user:${userId}:mentions`);
    */
   subscribe(topic, options) {
-    this.send(this.proto.topicSubscribe, { topic });
+    this.dispatch("topic-subscribe", { topic });
+    this.topics.add(topic);
     if (options?.auth) {
       this.authTopics.add(topic);
     }
@@ -1107,7 +1262,8 @@ var SharedWebSocket = 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);
   }
@@ -1188,12 +1344,154 @@ var SharedWebSocket = 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}:${p.event ?? ""}` : 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 {
+      ...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 = 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, this.frameLabel(kind, payload));
+      return;
+    }
+    for (const mw of this.outgoingMiddleware) {
+      frame = mw(frame);
+      if (frame === null) {
+        this.log.debug("[SharedWS] \u2717 outgoing dropped by middleware", kind, this.frameLabel(kind, payload));
+        return;
+      }
+    }
+    if (kind === "auth-login") {
+      this.log.debug("[SharedWS] \u2192 send", kind, "(token redacted)");
+    } else {
+      this.log.debug("[SharedWS] \u2192 send", kind, this.frameLabel(kind, payload), { payload, frame });
+    }
+    this.socket.send(frame);
+  }
+  /**
+   * Human-readable headline for log lines — picks the most relevant field
+   * out of the structured payload so log scanners aren't reading objects:
+   *   - event       → event name
+   *   - subscribe   → channel
+   *   - topic-*     → topic
+   *   - auth-*      → '(redacted)' / ''
+   */
+  frameLabel(kind, p) {
+    switch (kind) {
+      case "event":
+        return p.event ?? "?";
+      case "subscribe":
+      case "unsubscribe":
+        return p.channel ?? "?";
+      case "topic-subscribe":
+      case "topic-unsubscribe":
+        return p.topic ?? "?";
+      case "auth-login":
+        return "(redacted)";
+      case "auth-logout":
+        return "";
+    }
+  }
   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
@@ -1219,12 +1517,13 @@ var SharedWebSocket = 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) {
         data = mw(data);
         if (data === null) {
-          this.log.debug("[SharedWS] \u2717 incoming dropped by middleware");
+          this.log.debug("[SharedWS] \u2717 incoming dropped by middleware", { raw });
           return;
         }
       }
@@ -1235,15 +1534,15 @@ var SharedWebSocket = class {
       if (eventDeserializer) {
         payload = eventDeserializer(payload);
       }
-      this.log.debug("[SharedWS] \u2190 recv", event, payload);
-      this.bus.broadcast("ws:message", { event, data: payload });
+      this.log.debug("[SharedWS] \u2190 recv", event, { data: payload, raw: data });
+      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 === "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" });
@@ -1267,44 +1566,177 @@ var SharedWebSocket = class {
               resolve(res?.[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 = 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]();
@@ -1317,6 +1749,10 @@ var SharedWebSocket = class {
     this.syncStore.clear();
     this.authChannels.clear();
     this.authTopics.clear();
+    this.channelRefs.clear();
+    this.topics.clear();
+    this.rawFrameListeners.clear();
+    this.pendingOutbound.clear();
   }
 };
 
@@ -1328,4 +1764,4 @@ export {
   SubscriptionManager,
   SharedWebSocket
 };
-//# sourceMappingURL=chunk-IK4HLA3K.js.map
+//# sourceMappingURL=chunk-N63ZMMWV.js.map