@gwakko/shared-websocket 0.12.3 → 0.14.3

package/src/SubscriptionManager.ts

@@ -16,9 +16,9 @@ export class SubscriptionManager implements Disposable {
   }
 
   once(event: string, handler: EventHandler): Unsubscribe {
-    const wrapper: EventHandler = (data) => {
+    const wrapper: EventHandler = (data, raw) => {
       unsub();
-      handler(data);
+      handler(data, raw);
     };
     const unsub = this.on(event, wrapper);
     return unsub;
@@ -32,11 +32,11 @@ export class SubscriptionManager implements Disposable {
     }
   }
 
-  emit(event: string, data: unknown): void {
+  emit(event: string, data: unknown, raw?: unknown): void {
     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);
     }
   }
 

package/src/WorkerSocket.ts

@@ -31,6 +31,7 @@ export class WorkerSocket implements Disposable {
       reconnect?: boolean;
       reconnectMaxDelay?: number;
       reconnectMaxRetries?: number;
+      authFailureCloseCodes?: number[];
       heartbeatInterval?: number;
       sendBuffer?: number;
       workerUrl?: string | URL;
@@ -45,11 +46,27 @@ export class WorkerSocket implements Disposable {
     return this._state;
   }
 
+  private setState(s: SocketState): void {
+    this._state = s;
+    for (const fn of this.onStateChangeFns) fn(s);
+  }
+
   async connect(): Promise<void> {
     // Resolve auth token before sending to worker (functions can't cross worker boundary)
     let authToken: string | undefined;
     if (this.options.auth) {
-      authToken = await this.options.auth();
+      try {
+        authToken = await this.options.auth();
+      } catch {
+        // auth() threw — pause reconnect until user provides fresh creds.
+        this.setState('failed');
+        return;
+      }
+      if (!authToken) {
+        // Configured auth callback returned nothing — same fail-closed behavior.
+        this.setState('failed');
+        return;
+      }
     } else if (this.options.authToken) {
       authToken = this.options.authToken;
     }
@@ -95,6 +112,7 @@ export class WorkerSocket implements Disposable {
       reconnect: this.options.reconnect ?? true,
       reconnectMaxDelay: this.options.reconnectMaxDelay ?? 30_000,
       reconnectMaxRetries: this.options.reconnectMaxRetries ?? Infinity,
+      authFailureCloseCodes: this.options.authFailureCloseCodes ?? [1008],
       heartbeatInterval: this.options.heartbeatInterval ?? 30_000,
       bufferSize: this.options.sendBuffer ?? 100,
       pingPayload: this.options.pingPayload,
@@ -113,6 +131,11 @@ export class WorkerSocket implements Disposable {
     this.worker?.postMessage({ type: 'send', data });
   }
 
+  /** Manually trigger reconnect: resets retry counter, attempts a fresh connection. */
+  reconnect(): void {
+    this.worker?.postMessage({ type: 'reconnect' });
+  }
+
   disconnect(): void {
     this.worker?.postMessage({ type: 'disconnect' });
     setTimeout(() => {
@@ -140,6 +163,7 @@ export class WorkerSocket implements Disposable {
       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 }); }
@@ -149,7 +173,12 @@ export class WorkerSocket implements Disposable {
         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); }
@@ -158,16 +187,24 @@ export class WorkerSocket implements Disposable {
       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'); }
       };
     `;

package/src/adapters/react.ts

@@ -149,13 +149,13 @@ export function useSocketAuth(): {
  *   setOrders(prev => [order, ...prev].slice(0, 50)); // keep last 50
  * });
  */
-export function useSocketEvent<T>(event: string, callback?: (data: T) => void): T | undefined {
+export function useSocketEvent<T>(event: string, callback?: (data: T, raw?: unknown) => void): T | undefined {
   const socket = useSharedWebSocket();
   const [value, setValue] = useState<T | undefined>(undefined);
 
-  const onEvent = useEffectEvent((data: T) => {
+  const onEvent = useEffectEvent((data: T, raw?: unknown) => {
     if (callback) {
-      callback(data);
+      callback(data, raw);
     } else {
       setValue(data);
     }
@@ -192,13 +192,13 @@ export function useSocketEvent<T>(event: string, callback?: (data: T) => void):
  *   if (entry.level === 'error') setErrors(prev => [...prev, entry]);
  * });
  */
-export function useSocketStream<T>(event: string, callback?: (data: T) => void): T[] {
+export function useSocketStream<T>(event: string, callback?: (data: T, raw?: unknown) => void): T[] {
   const socket = useSharedWebSocket();
   const [items, setItems] = useState<T[]>([]);
 
-  const onEvent = useEffectEvent((data: T) => {
+  const onEvent = useEffectEvent((data: T, raw?: unknown) => {
     if (callback) {
-      callback(data);
+      callback(data, raw);
     } else {
       setItems((prev) => [...prev, data]);
     }
@@ -276,11 +276,11 @@ export function useSocketSync<T>(
  *   }
  * });
  */
-export function useSocketCallback<T>(event: string, callback: (data: T) => void): void {
+export function useSocketCallback<T>(event: string, callback: (data: T, raw?: unknown) => void): void {
   const socket = useSharedWebSocket();
 
-  const handler = useEffectEvent((data: T) => {
-    callback(data);
+  const handler = useEffectEvent((data: T, raw?: unknown) => {
+    callback(data, raw);
   });
 
   useEffect(() => {
@@ -338,6 +338,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   const onConnect = useEffectEvent(() => handlers.onConnect?.());
   const onDisconnect = useEffectEvent(() => handlers.onDisconnect?.());
   const onReconnecting = useEffectEvent(() => handlers.onReconnecting?.());
+  const onReconnectFailed = useEffectEvent(() => handlers.onReconnectFailed?.());
   const onLeaderChange = useEffectEvent((isLeader: boolean) => handlers.onLeaderChange?.(isLeader));
   const onError = useEffectEvent((error: unknown) => handlers.onError?.(error));
   const onActive = useEffectEvent(() => handlers.onActive?.());
@@ -350,6 +351,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
       socket.onConnect(onConnect),
       socket.onDisconnect(onDisconnect),
       socket.onReconnecting(onReconnecting),
+      socket.onReconnectFailed(onReconnectFailed),
       socket.onLeaderChange(onLeaderChange),
       socket.onError(onError),
       socket.onActive(onActive),
@@ -361,6 +363,51 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   }, [socket]);
 }
 
+/**
+ * Reactive reconnect state with a manual `reconnect` action. Use this to
+ * power a "Reconnect" snackbar/banner after auto-reconnect gives up.
+ *
+ * `hasFailed` is `true` after `reconnectMaxRetries` are exhausted. It resets
+ * to `false` once the connection succeeds again or the user calls `reconnect()`.
+ *
+ * @example
+ * function ConnectionBanner() {
+ *   const { hasFailed, reconnect } = useSocketReconnect();
+ *   if (!hasFailed) return null;
+ *   return (
+ *     <div className="snackbar">
+ *       Connection lost.
+ *       <button onClick={reconnect}>Reconnect</button>
+ *     </div>
+ *   );
+ * }
+ */
+export function useSocketReconnect(): {
+  hasFailed: boolean;
+  reconnect: () => void;
+} {
+  const socket = useSharedWebSocket();
+  const [hasFailed, setHasFailed] = useState(false);
+
+  const onFailed = useEffectEvent(() => setHasFailed(true));
+  const onConnected = useEffectEvent(() => setHasFailed(false));
+
+  useEffect(() => {
+    const unsubs = [
+      socket.onReconnectFailed(onFailed),
+      socket.onConnect(onConnected),
+    ];
+    return () => unsubs.forEach((u) => u());
+  }, [socket]);
+
+  const reconnect = useEffectEvent(() => {
+    setHasFailed(false);
+    socket.reconnect();
+  });
+
+  return { hasFailed, reconnect };
+}
+
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/src/adapters/vue.ts

@@ -110,14 +110,14 @@ export function useSocketAuth(): {
  *   analytics.track('order_received', order);
  * });
  */
-export function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {
+export function useSocketEvent<T>(event: string, callback?: (data: T, raw?: unknown) => void): Ref<T | undefined> {
   const socket = useSharedWebSocket();
   const value = ref<T | undefined>(undefined) as Ref<T | undefined>;
 
-  const handler = (data: unknown) => {
+  const handler = (data: unknown, raw?: unknown) => {
     const typed = data as T;
     if (callback) {
-      callback(typed);
+      callback(typed, raw);
     } else {
       value.value = typed;
     }
@@ -151,14 +151,14 @@ export function useSocketEvent<T>(event: string, callback?: (data: T) => void):
  *   if (entry.level === 'error') errors.value = [...errors.value, entry];
  * });
  */
-export function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {
+export function useSocketStream<T>(event: string, callback?: (data: T, raw?: unknown) => void): Ref<T[]> {
   const socket = useSharedWebSocket();
   const items = ref<T[]>([]) as Ref<T[]>;
 
-  const handler = (data: unknown) => {
+  const handler = (data: unknown, raw?: unknown) => {
     const typed = data as T;
     if (callback) {
-      callback(typed);
+      callback(typed, raw);
     } else {
       items.value = [...items.value, typed];
     }
@@ -215,11 +215,11 @@ export function useSocketSync<T>(key: string, initialValue: T, callback?: (value
  *   showToast(n.title);
  * });
  */
-export function useSocketCallback<T>(event: string, callback: (data: T) => void): void {
+export function useSocketCallback<T>(event: string, callback: (data: T, raw?: unknown) => void): void {
   const socket = useSharedWebSocket();
 
-  const unsub = socket.on(event, (data: unknown) => {
-    callback(data as T);
+  const unsub = socket.on(event, (data: unknown, raw?: unknown) => {
+    callback(data as T, raw);
   });
 
   onUnmounted(unsub);
@@ -275,6 +275,7 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   if (handlers.onConnect) unsubs.push(socket.onConnect(handlers.onConnect));
   if (handlers.onDisconnect) unsubs.push(socket.onDisconnect(handlers.onDisconnect));
   if (handlers.onReconnecting) unsubs.push(socket.onReconnecting(handlers.onReconnecting));
+  if (handlers.onReconnectFailed) unsubs.push(socket.onReconnectFailed(handlers.onReconnectFailed));
   if (handlers.onLeaderChange) unsubs.push(socket.onLeaderChange(handlers.onLeaderChange));
   if (handlers.onError) unsubs.push(socket.onError(handlers.onError));
   if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));
@@ -285,6 +286,52 @@ export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
   onUnmounted(() => unsubs.forEach((u) => u()));
 }
 
+/**
+ * Reactive reconnect state with a manual `reconnect` action. Use this to
+ * power a "Reconnect" snackbar/banner after auto-reconnect gives up.
+ *
+ * `hasFailed` flips to `true` once `reconnectMaxRetries` are exhausted, and
+ * back to `false` once the connection succeeds or the user calls `reconnect()`.
+ *
+ * @example
+ * <script setup>
+ * const { hasFailed, reconnect } = useSocketReconnect();
+ * </script>
+ *
+ * <template>
+ *   <div v-if="hasFailed" class="snackbar">
+ *     Connection lost.
+ *     <button @click="reconnect">Reconnect</button>
+ *   </div>
+ * </template>
+ */
+export function useSocketReconnect(): {
+  hasFailed: Ref<boolean>;
+  reconnect: () => void;
+} {
+  const socket = useSharedWebSocket();
+  const hasFailed = ref(false);
+
+  const unsubs = [
+    socket.onReconnectFailed(() => {
+      hasFailed.value = true;
+    }),
+    socket.onConnect(() => {
+      hasFailed.value = false;
+    }),
+  ];
+
+  onUnmounted(() => unsubs.forEach((u) => u()));
+
+  return {
+    hasFailed: readonly(hasFailed) as Ref<boolean>,
+    reconnect: () => {
+      hasFailed.value = false;
+      socket.reconnect();
+    },
+  };
+}
+
 /**
  * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
  *

package/src/index.ts

@@ -29,4 +29,7 @@ export type {
   Middleware,
   PushNotificationOptions,
   Codec,
+  FrameKind,
+  FramePayload,
+  ChannelAckResult,
 } from './types';

package/src/types.ts

@@ -1,7 +1,12 @@
-export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'failed';
 export type TabRole = 'leader' | 'follower';
 export type Unsubscribe = () => void;
-export type EventHandler<T = unknown> = (data: T) => void;
+/**
+ * Event handler. Receives the extracted `data` (per `dataField`) plus the
+ * full raw envelope as a second argument. Use `raw` to access top-level
+ * fields outside `dataField` (e.g. `id`, `kind`, `channel`, `type`).
+ */
+export type EventHandler<T = unknown> = (data: T, raw?: unknown) => void;
 
 /** Type-safe event map. Keys are event names, values are payload types. */
 export type EventMap = Record<string, unknown>;
@@ -48,12 +53,61 @@ export interface Logger {
 /** Middleware function — transform or inspect messages. Return null to drop. */
 export type Middleware<T = unknown> = (message: T) => T | null;
 
+/**
+ * Kinds of frames the library emits. Lets `EventProtocol.frameBuilder`
+ * take full control over the wire shape per kind — e.g. produce flat
+ * `{ type, channel, event, data }` envelopes for Pusher/Reverb/custom
+ * servers instead of the default `{ event, data }` two-key wrapper.
+ */
+export type FrameKind =
+  | 'event'              // user payload via ws.send / Channel.send
+  | 'subscribe'          // channel join
+  | 'unsubscribe'        // channel leave
+  | 'topic-subscribe'    // topic subscribe
+  | 'topic-unsubscribe'  // topic unsubscribe
+  | 'auth-login'         // authenticate(token)
+  | 'auth-logout';       // deauthenticate()
+
+/**
+ * Structured payload passed to `frameBuilder`. Fields are populated
+ * based on `kind`:
+ *
+ *   - `event`              → `{ event, data, channel?, extras? }`
+ *                            `channel` is set when sent via `Channel.send`.
+ *   - `subscribe`/`unsubscribe`        → `{ channel, extras? }`
+ *   - `topic-subscribe`/`topic-unsubscribe` → `{ topic, extras? }`
+ *   - `auth-login`         → `{ data: token, extras? }` (`data` is the raw token)
+ *   - `auth-logout`        → `{ extras? }`
+ */
+export interface FramePayload {
+  /** Channel name. Set for subscribe/unsubscribe and channel-scoped events. */
+  channel?: string;
+  /** Topic name. Set for topic-subscribe/topic-unsubscribe. */
+  topic?: string;
+  /** Bare event name (without channel prefix). Set for `kind: 'event'`. */
+  event?: string;
+  /** Payload — user data, auth token, etc. */
+  data?: unknown;
+  /** Extra top-level fields to merge into the wire envelope. */
+  extras?: Record<string, unknown>;
+}
+
 export interface SharedWebSocketOptions<TEvents extends EventMap = EventMap> {
   protocols?: string[];
   reconnect?: boolean;
   reconnectMaxDelay?: number;
   /** Max reconnect attempts before giving up (default: Infinity — retry forever). */
   reconnectMaxRetries?: number;
+  /**
+   * WebSocket close codes that indicate "auth failed — don't retry."
+   * On these codes the library sets state to 'failed' and stops auto-reconnect
+   * instead of looping with the same expired credentials. Default: `[1008]`
+   * (PolicyViolation). Add 4xxx app-specific codes if your server uses them.
+   *
+   * To recover, call `ws.authenticate(newToken)` (auto-reconnects when
+   * the local tab is the leader) or `ws.reconnect()` directly.
+   */
+  authFailureCloseCodes?: number[];
   heartbeatInterval?: number;
   electionTimeout?: number;
   leaderHeartbeat?: number;
@@ -65,6 +119,42 @@ export interface SharedWebSocketOptions<TEvents extends EventMap = EventMap> {
   authToken?: string;
   /** Query parameter name for the token (default: "token"). */
   authParam?: string;
+  /**
+   * Optional. Periodic token refresh — runs on the leader tab only via
+   * `setInterval(refresh, refreshTokenInterval)`. When the timer fires
+   * and the connection is currently authenticated, the returned token
+   * is passed to `authenticate()` so the server sees the new credentials
+   * before the old one expires. Falls back to `auth` if unset.
+   *
+   * Use this for long-running tabs where the server would otherwise
+   * close with an auth-failure code mid-session. Pair with a sensible
+   * interval — typically ~80% of your token TTL (e.g. 48 minutes for a
+   * 60-minute token).
+   *
+   * If the callback throws, the failure is logged at `warn` and the
+   * timer keeps running for the next interval; the server will still
+   * close on its own when the token expires, at which point
+   * `authFailureCloseCodes` and `ws.authenticate(...)` handle recovery.
+   */
+  refresh?: () => string | Promise<string>;
+  /**
+   * Refresh interval in milliseconds. Disabled when unset or `<= 0`.
+   * No default — opt-in.
+   */
+  refreshTokenInterval?: number;
+  /**
+   * Max number of follower-routed dispatches each tab buffers locally for
+   * replay across leader handover. When the leader dies between receiving
+   * a follower's dispatch and writing it to the socket, the new leader
+   * gathers pending entries from all tabs and replays them. Cap protects
+   * memory; oldest entries are dropped on overflow. Set to `0` to disable
+   * the buffer entirely. Default: 100.
+   *
+   * Note: the replay is at-least-once — a leader that dies AFTER socket
+   * write but BEFORE broadcasting "flushed" will cause a duplicate. Make
+   * server-side handlers idempotent if duplicates would matter.
+   */
+  outboundBufferSize?: number;
   /** Run WebSocket inside a Web Worker (offloads JSON parsing, heartbeat from main thread). */
   useWorker?: boolean;
   /** Custom worker URL (if useWorker is true and you want to provide your own worker file). */
@@ -117,6 +207,56 @@ export interface EventProtocol {
   authLogout: string;
   /** Event name server sends to revoke auth (default: "$auth:revoked"). */
   authRevoked: string;
+  /**
+   * Optional. Takes full control of outgoing frame shape per `FrameKind`.
+   * If unset, the default builder reproduces the legacy two-key envelope:
+   *   `{ ...extras, [eventField]: <event-name>, [dataField]: <data> }`
+   * using `channelJoin` / `channelLeave` / `topicSubscribe` / etc. for
+   * control-frame event names.
+   *
+   * Return-value contract:
+   *   - any concrete value → use as the wire frame
+   *   - `null`              → drop the frame (intentional filter / no-op)
+   *   - `undefined`         → fall back to the library default for this kind
+   *
+   * @example Flat envelope (Pusher / Reverb / custom Go server)
+   * frameBuilder: (kind, p) => {
+   *   switch (kind) {
+   *     case 'subscribe':    return { type: 'subscribe',   channel: p.channel };
+   *     case 'unsubscribe':  return { type: 'unsubscribe', channel: p.channel };
+   *     case 'auth-login':   return { type: 'auth',        token: p.data };
+   *     case 'auth-logout':  return { type: 'logout' };
+   *     case 'event':
+   *       return p.channel
+   *         ? { type: 'event', channel: p.channel, event: p.event, data: p.data, ...p.extras }
+   *         : { type: 'event', event: p.event, data: p.data, ...p.extras };
+   *     default: return undefined; // unknown kind → library default
+   *   }
+   * }
+   */
+  frameBuilder?: (kind: FrameKind, payload: FramePayload) => unknown;
+  /**
+   * Optional. If provided, `channel(name).ready` waits for an incoming
+   * frame this matcher classifies as `'ok'` before resolving. Returns:
+   *   - `'ok'`       → resolve.
+   *   - `'reject'`   → reject with a "subscribe rejected" error.
+   *   - `'pending'`  → keep watching subsequent frames.
+   *
+   * Without a matcher, `Channel.ready` resolves immediately after the
+   * subscribe frame is dispatched — appropriate for fire-and-forget
+   * servers that don't send subscribe acks.
+   *
+   * @example Phoenix `phx_reply`
+   * channelAckMatcher: (frame, channel) => {
+   *   const f = frame as { topic: string; event: string; payload: { status: 'ok' | 'error' } };
+   *   if (f.topic !== channel) return 'pending';
+   *   if (f.event !== 'phx_reply') return 'pending';
+   *   return f.payload.status === 'ok' ? 'ok' : 'reject';
+   * }
+   */
+  channelAckMatcher?: (frame: unknown, channel: string) => ChannelAckResult;
+  /** Timeout in ms for `Channel.ready` when `channelAckMatcher` is set. Default: 5000. */
+  channelAckTimeout?: number;
 }
 
 /** Push notification options. */
@@ -136,6 +276,8 @@ export interface SocketLifecycleHandlers {
   onConnect?: () => void;
   onDisconnect?: () => void;
   onReconnecting?: () => void;
+  /** Called when auto-reconnect gives up after exhausting reconnectMaxRetries. */
+  onReconnectFailed?: () => void;
   onLeaderChange?: (isLeader: boolean) => void;
   onError?: (error: unknown) => void;
   /** Called when this tab becomes visible/focused. */
@@ -148,9 +290,30 @@ export interface SocketLifecycleHandlers {
   onAuthChange?: (authenticated: boolean) => void;
 }
 
+/**
+ * Result returned by `EventProtocol.channelAckMatcher` for each
+ * incoming frame while a `Channel` is awaiting its subscribe ack.
+ *
+ *   - `'ok'`      → resolve `Channel.ready`, stop watching.
+ *   - `'reject'`  → reject `Channel.ready` with a "subscribe rejected"
+ *                   error, stop watching.
+ *   - `'pending'` → keep watching for subsequent frames.
+ */
+export type ChannelAckResult = 'ok' | 'reject' | 'pending';
+
 /** Scoped channel handle for private/topic-based subscriptions. */
 export interface Channel {
   readonly name: string;
+  /**
+   * Resolves once the server has accepted the subscription. By default
+   * (no `channelAckMatcher` configured) this resolves immediately after
+   * the subscribe frame is dispatched — fire-and-forget servers don't
+   * send acks. Configure `EventProtocol.channelAckMatcher` to wait for
+   * a real ack frame; the promise then rejects on a matched
+   * "rejected" frame, on `channelAckTimeout`, or if `.leave()` is
+   * called before the ack arrives.
+   */
+  readonly ready: Promise<void>;
   on(event: string, handler: EventHandler): Unsubscribe;
   once(event: string, handler: EventHandler): Unsubscribe;
   send(event: string, data: unknown): void;