@gwakko/shared-websocket 0.2.1 → 0.6.1

package/dist/vue.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {\n *   auth: () => localStorage.getItem('token')!,\n *   useWorker: true,\n * }));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns reactive ref with latest value.\n * - With callback: calls your handler on each event.\n *\n * @example\n * // Reactive state\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const unsub = socket.on(event, (data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      value.value = data;\n    }\n  });\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events.\n * - Without callback: returns reactive array.\n * - With callback: calls your handler — manage your own state.\n *\n * @example\n * // Default accumulation\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom — keep last 50\n * const messages = ref<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   messages.value = [msg, ...messages.value].slice(0, 50);\n * });\n *\n * @example\n * // Custom — filter by type\n * const errors = ref<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') errors.value = [...errors.value, entry];\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const unsub = socket.on(event, (data: T) => {\n    if (callback) {\n      callback(data);\n    } else {\n      items.value = [...items.value, data];\n    }\n  });\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: reactive ref synced across tabs.\n * - With callback: called when any tab updates this key — side effects.\n *\n * @example\n * // Reactive two-way sync\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n *\n * @example\n * // With side effect callback\n * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated');\n * });\n */\nexport function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n    callback?.(v);\n  });\n\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Fire-and-forget event handler — no state, no ref.\n *\n * @example\n * useSocketCallback<Notification>('notification', (n) => {\n *   showToast(n.title);\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const unsub = socket.on(event, (data: T) => {\n    callback(data);\n  });\n\n  onUnmounted(unsub);\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n"],"mappings":";;;;;AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAMA,IAAM,qBAAoD,uBAAO,iBAAiB;AAYlF,SAAS,4BAA4B,KAAa,SAAkC;AACzF,SAAO;AAAA,IACL,QAAQ,KAAU;AAChB,YAAM,SAAS,IAAI,gBAAgB,KAAK,OAAO;AAC/C,aAAO,QAAQ;AACf,UAAI,QAAQ,oBAAoB,MAAM;AAEtC,YAAM,kBAAkB,IAAI,QAAQ,KAAK,GAAG;AAC5C,UAAI,UAAU,MAAM;AAClB,eAAO,OAAO,OAAO,EAAE;AACvB,wBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACF;AASO,SAAS,qBAAsC;AACpD,QAAM,SAAS,OAAO,kBAAkB;AACxC,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AACA,SAAO;AACT;AAoBO,SAAS,eAAkB,OAAe,UAAkD;AACjG,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAmB,MAAS;AAE1C,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,QAAI,UAAU;AACZ,eAAS,IAAI;AAAA,IACf,OAAO;AACL,YAAM,QAAQ;AAAA,IAChB;AAAA,EACF,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAyBO,SAAS,gBAAmB,OAAe,UAAwC;AACxF,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAS,CAAC,CAAC;AAEzB,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,QAAI,UAAU;AACZ,eAAS,IAAI;AAAA,IACf,OAAO;AACL,YAAM,QAAQ,CAAC,GAAG,MAAM,OAAO,IAAI;AAAA,IACrC;AAAA,EACF,CAAC;AAED,cAAY,KAAK;AACjB,SAAO,SAAS,KAAK;AACvB;AAmBO,SAAS,cAAiB,KAAa,cAAiB,UAAuC;AACpG,QAAM,SAAS,mBAAmB;AAClC,QAAM,QAAQ,IAAO,OAAO,QAAW,GAAG,KAAK,YAAY;AAE3D,QAAM,QAAQ,OAAO,OAAU,KAAK,CAAC,MAAM;AACzC,UAAM,QAAQ;AACd,eAAW,CAAC;AAAA,EACd,CAAC;AAED;AAAA,IACE;AAAA,IACA,CAAC,WAAW;AACV,aAAO,KAAK,KAAK,MAAM;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,KAAK;AAAA,EACf;AAEA,cAAY,KAAK;AACjB,SAAO;AACT;AAUO,SAAS,kBAAqB,OAAe,UAAmC;AACrF,QAAM,SAAS,mBAAmB;AAElC,QAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,SAAY;AAC1C,aAAS,IAAI;AAAA,EACf,CAAC;AAED,cAAY,KAAK;AACnB;AAQO,SAAS,kBAGd;AACA,QAAM,SAAS,mBAAmB;AAClC,QAAM,YAAY,IAAI,OAAO,SAAS;AACtC,QAAM,UAAU,IAAa,OAAO,OAAO;AAE3C,QAAM,QAAQ,YAAY,MAAM;AAC9B,cAAU,QAAQ,OAAO;AACzB,YAAQ,QAAQ,OAAO;AAAA,EACzB,GAAG,GAAI;AAEP,cAAY,MAAM,cAAc,KAAK,CAAC;AAEtC,SAAO;AAAA,IACL,WAAW,SAAS,SAAS;AAAA,IAC7B,SAAS,SAAS,OAAO;AAAA,EAC3B;AACF;","names":[]}
+{"version":3,"sources":["../src/adapters/vue.ts"],"sourcesContent":["import {\n  ref,\n  onUnmounted,\n  inject,\n  readonly,\n  watch,\n  type Ref,\n  type InjectionKey,\n  type App,\n} from 'vue';\nimport { SharedWebSocket } from '../SharedWebSocket';\nimport type { SharedWebSocketOptions, TabRole, SocketLifecycleHandlers } from '../types';\n\n// ─── Plugin ──────────────────────────────────────────────\n\nexport const SharedWebSocketKey: InjectionKey<SharedWebSocket> = Symbol('SharedWebSocket');\n\n/**\n * Vue 3 plugin for SharedWebSocket.\n *\n * @example\n * const app = createApp(App);\n * app.use(createSharedWebSocketPlugin('wss://api.example.com/ws', {\n *   auth: () => localStorage.getItem('token')!,\n *   useWorker: true,\n * }));\n */\nexport function createSharedWebSocketPlugin(url: string, options?: SharedWebSocketOptions) {\n  return {\n    install(app: App) {\n      const socket = new SharedWebSocket(url, options);\n      socket.connect();\n      app.provide(SharedWebSocketKey, socket);\n\n      const originalUnmount = app.unmount.bind(app);\n      app.unmount = () => {\n        socket[Symbol.dispose]();\n        originalUnmount();\n      };\n    },\n  };\n}\n\n/**\n * Access the SharedWebSocket instance from provided context.\n *\n * @example\n * const ws = useSharedWebSocket();\n * ws.send('chat.message', { text: 'Hello' });\n */\nexport function useSharedWebSocket(): SharedWebSocket {\n  const socket = inject(SharedWebSocketKey);\n  if (!socket) {\n    throw new Error('useSharedWebSocket: SharedWebSocket not provided. Did you install the plugin?');\n  }\n  return socket;\n}\n\n// ─── Composables ─────────────────────────────────────────\n\n/**\n * Subscribe to a WebSocket event.\n * - Without callback: returns reactive ref with latest value.\n * - With callback: calls your handler on each event.\n *\n * @example\n * // Reactive state\n * const order = useSocketEvent<Order>('order.created');\n *\n * @example\n * // Custom callback\n * useSocketEvent<Order>('order.created', (order) => {\n *   playSound('new-order');\n *   analytics.track('order_received', order);\n * });\n */\nexport function useSocketEvent<T>(event: string, callback?: (data: T) => void): Ref<T | undefined> {\n  const socket = useSharedWebSocket();\n  const value = ref<T | undefined>(undefined) as Ref<T | undefined>;\n\n  const handler = (data: unknown) => {\n    const typed = data as T;\n    if (callback) {\n      callback(typed);\n    } else {\n      value.value = typed;\n    }\n  };\n  const unsub = socket.on(event, handler);\n\n  onUnmounted(unsub);\n  return readonly(value) as Ref<T | undefined>;\n}\n\n/**\n * Accumulate WebSocket events.\n * - Without callback: returns reactive array.\n * - With callback: calls your handler — manage your own state.\n *\n * @example\n * // Default accumulation\n * const messages = useSocketStream<ChatMessage>('chat.message');\n *\n * @example\n * // Custom — keep last 50\n * const messages = ref<ChatMessage[]>([]);\n * useSocketStream<ChatMessage>('chat.message', (msg) => {\n *   messages.value = [msg, ...messages.value].slice(0, 50);\n * });\n *\n * @example\n * // Custom — filter by type\n * const errors = ref<LogEntry[]>([]);\n * useSocketStream<LogEntry>('log.entry', (entry) => {\n *   if (entry.level === 'error') errors.value = [...errors.value, entry];\n * });\n */\nexport function useSocketStream<T>(event: string, callback?: (data: T) => void): Ref<T[]> {\n  const socket = useSharedWebSocket();\n  const items = ref<T[]>([]) as Ref<T[]>;\n\n  const handler = (data: unknown) => {\n    const typed = data as T;\n    if (callback) {\n      callback(typed);\n    } else {\n      items.value = [...items.value, typed];\n    }\n  };\n  const unsub = socket.on(event, handler);\n\n  onUnmounted(unsub);\n  return readonly(items) as Ref<T[]>;\n}\n\n/**\n * Two-way state sync across browser tabs.\n * - Without callback: reactive ref synced across tabs.\n * - With callback: called when any tab updates this key — side effects.\n *\n * @example\n * // Reactive two-way sync\n * const cart = useSocketSync<Cart>('cart', { items: [] });\n * cart.value = { items: [1, 2, 3] }; // syncs to all tabs\n *\n * @example\n * // With side effect callback\n * const cart = useSocketSync<Cart>('cart', { items: [] }, (cart) => {\n *   document.title = `Cart (${cart.items.length})`;\n *   analytics.track('cart_updated');\n * });\n */\nexport function useSocketSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {\n  const socket = useSharedWebSocket();\n  const value = ref<T>(socket.getSync<T>(key) ?? initialValue) as Ref<T>;\n\n  const unsub = socket.onSync<T>(key, (v) => {\n    value.value = v;\n    callback?.(v);\n  });\n\n  watch(\n    value,\n    (newVal) => {\n      socket.sync(key, newVal);\n    },\n    { deep: true },\n  );\n\n  onUnmounted(unsub);\n  return value;\n}\n\n/**\n * Fire-and-forget event handler — no state, no ref.\n *\n * @example\n * useSocketCallback<Notification>('notification', (n) => {\n *   showToast(n.title);\n * });\n */\nexport function useSocketCallback<T>(event: string, callback: (data: T) => void): void {\n  const socket = useSharedWebSocket();\n\n  const unsub = socket.on(event, (data: unknown) => {\n    callback(data as T);\n  });\n\n  onUnmounted(unsub);\n}\n\n/**\n * Reactive connection status.\n *\n * @example\n * const { connected, tabRole } = useSocketStatus();\n */\nexport function useSocketStatus(): {\n  connected: Ref<boolean>;\n  tabRole: Ref<TabRole>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n  }, 1000);\n\n  onUnmounted(() => clearInterval(timer));\n\n  return {\n    connected: readonly(connected) as Ref<boolean>,\n    tabRole: readonly(tabRole) as Ref<TabRole>,\n  };\n}\n\n/**\n * Lifecycle hooks — react to connection state changes.\n *\n * @example\n * useSocketLifecycle({\n *   onConnect: () => console.log('Connected!'),\n *   onDisconnect: () => showOfflineBanner(),\n *   onReconnecting: () => showSpinner(),\n *   onLeaderChange: (isLeader) => console.log('Leader:', isLeader),\n *   onError: (err) => reportError(err),\n * });\n */\nexport function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {\n  const socket = useSharedWebSocket();\n  const unsubs: (() => void)[] = [];\n\n  if (handlers.onConnect) unsubs.push(socket.onConnect(handlers.onConnect));\n  if (handlers.onDisconnect) unsubs.push(socket.onDisconnect(handlers.onDisconnect));\n  if (handlers.onReconnecting) unsubs.push(socket.onReconnecting(handlers.onReconnecting));\n  if (handlers.onLeaderChange) unsubs.push(socket.onLeaderChange(handlers.onLeaderChange));\n  if (handlers.onError) unsubs.push(socket.onError(handlers.onError));\n\n  onUnmounted(() => unsubs.forEach((u) => u()));\n}\n\n/**\n * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.\n *\n * @example\n * const chat = useChannel('chat:room_123');\n * // Listen via useSocketEvent('chat:room_123:message')\n * // Send via chat.send('message', { text: 'Hello' })\n */\nexport function useChannel(name: string) {\n  const socket = useSharedWebSocket();\n  const channel = socket.channel(name);\n\n  onUnmounted(() => channel.leave());\n\n  return channel;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwakko/shared-websocket",
-  "version": "0.2.1",
+  "version": "0.6.1",
   "description": "Share ONE WebSocket connection across browser tabs — leader election, BroadcastChannel sync, optional Web Worker",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/SharedSocket.ts

@@ -9,6 +9,10 @@ interface SharedSocketOptions {
   heartbeatInterval?: number;
   sendBuffer?: number;
   auth?: () => string | Promise<string>;
+  authToken?: string;
+  authParam?: string;
+  /** Heartbeat payload (default: { type: "ping" }). */
+  pingPayload?: unknown;
 }
 
 export class SharedSocket implements Disposable {
@@ -22,7 +26,12 @@ export class SharedSocket implements Disposable {
   private onMessageFns = new Set<EventHandler>();
   private onStateChangeFns = new Set<(state: SocketState) => void>();
 
-  private readonly opts: Required<Omit<SharedSocketOptions, 'auth'>> & { auth?: () => string | Promise<string> };
+  private readonly opts: Required<Omit<SharedSocketOptions, 'auth' | 'authToken' | 'authParam' | 'pingPayload'>> & {
+    auth?: () => string | Promise<string>;
+    authToken?: string;
+    authParam: string;
+    pingPayload: unknown;
+  };
 
   constructor(
     private url: string,
@@ -35,6 +44,9 @@ export class SharedSocket implements Disposable {
       heartbeatInterval: options.heartbeatInterval ?? 30_000,
       sendBuffer: options.sendBuffer ?? 100,
       auth: options.auth,
+      authToken: options.authToken,
+      authParam: options.authParam ?? 'token',
+      pingPayload: options.pingPayload ?? { type: 'ping' },
     };
   }
 
@@ -47,13 +59,7 @@ export class SharedSocket implements Disposable {
 
     this.setState('connecting');
 
-    let connectUrl = this.url;
-    if (this.opts.auth) {
-      const token = await this.opts.auth();
-      const sep = connectUrl.includes('?') ? '&' : '?';
-      connectUrl = `${connectUrl}${sep}token=${encodeURIComponent(token)}`;
-    }
-
+    const connectUrl = await this.buildUrl();
     this.ws = new WebSocket(connectUrl, this.opts.protocols);
 
     this.ws.onopen = () => {
@@ -150,7 +156,7 @@ export class SharedSocket implements Disposable {
     this.stopHeartbeat();
     this.heartbeatTimer = setInterval(() => {
       if (this.ws?.readyState === WebSocket.OPEN) {
-        this.ws.send(JSON.stringify({ type: 'ping' }));
+        this.ws.send(JSON.stringify(this.opts.pingPayload));
       }
     }, this.opts.heartbeatInterval);
   }
@@ -169,6 +175,26 @@ export class SharedSocket implements Disposable {
     }
   }
 
+  private async buildUrl(): Promise<string> {
+    // Resolve token: callback > static > none
+    let token: string | undefined;
+    if (this.opts.auth) {
+      token = await this.opts.auth();
+    } else if (this.opts.authToken) {
+      token = this.opts.authToken;
+    }
+
+    if (!token) return this.url;
+
+    // WebSocket URLs (ws://, wss://) are not fully supported by URL API.
+    // Convert to http(s) for parsing, then back to ws(s).
+    const httpUrl = this.url.replace(/^ws(s?):\/\//, 'http$1://');
+    const parsed = new URL(httpUrl);
+    parsed.searchParams.set(this.opts.authParam, token);
+
+    return parsed.toString().replace(/^http(s?):\/\//, 'ws$1://');
+  }
+
   private setState(state: SocketState): void {
     this._state = state;
     for (const fn of this.onStateChangeFns) fn(state);

package/src/SharedWebSocket.ts

@@ -5,7 +5,23 @@ import { TabCoordinator } from './TabCoordinator';
 import { SharedSocket } from './SharedSocket';
 import { WorkerSocket } from './WorkerSocket';
 import { SubscriptionManager } from './SubscriptionManager';
-import type { SharedWebSocketOptions, TabRole, Unsubscribe, EventHandler } from './types';
+import type { SharedWebSocketOptions, TabRole, Unsubscribe, EventHandler, Channel, EventProtocol, EventMap, Logger, Middleware } from './types';
+
+const DEFAULT_PROTOCOL: EventProtocol = {
+  eventField: 'event',
+  dataField: 'data',
+  channelJoin: '$channel:join',
+  channelLeave: '$channel:leave',
+  ping: { type: 'ping' },
+  defaultEvent: 'message',
+};
+
+const NOOP_LOGGER: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
 
 /** Common interface for both SharedSocket and WorkerSocket. */
 interface SocketAdapter {
@@ -21,11 +37,18 @@ interface SocketAdapter {
 /**
  * SharedWebSocket — shares ONE WebSocket connection across browser tabs.
  *
- * One tab becomes the "leader" and holds the WebSocket.
- * Other tabs are "followers" receiving data via BroadcastChannel.
- * If the leader closes, a new leader is elected automatically.
+ * @typeParam TEvents - Event map for type-safe subscriptions.
+ *
+ * @example
+ * // Typed events
+ * type Events = {
+ *   'chat.message': { text: string; userId: string };
+ *   'order.created': { id: string; total: number };
+ * };
+ * const ws = new SharedWebSocket<Events>(url);
+ * ws.on('chat.message', (msg) => msg.text); // ← msg: { text, userId }
  */
-export class SharedWebSocket implements Disposable {
+export class SharedWebSocket<TEvents extends EventMap = EventMap> implements Disposable {
   private bus: MessageBus;
   private coordinator: TabCoordinator;
   private socket: SocketAdapter | null = null;
@@ -34,12 +57,19 @@ export class SharedWebSocket implements Disposable {
   private tabId: string;
   private cleanups: Unsubscribe[] = [];
   private disposed = false;
+  private readonly proto: EventProtocol;
+  private readonly log: Logger;
+  private outgoingMiddleware: Middleware[] = [];
+  private incomingMiddleware: Middleware[] = [];
 
   constructor(
     private readonly url: string,
-    private readonly options: SharedWebSocketOptions = {},
+    private readonly options: SharedWebSocketOptions<TEvents> = {} as SharedWebSocketOptions<TEvents>,
   ) {
+    this.proto = { ...DEFAULT_PROTOCOL, ...options.events };
+    this.log = options.debug ? (options.logger ?? console) : NOOP_LOGGER;
     this.tabId = generateId();
+    this.log.debug('[SharedWS] init', { tabId: this.tabId, url });
     this.bus = new MessageBus('shared-ws', this.tabId);
     this.coordinator = new TabCoordinator(this.bus, this.tabId, {
       electionTimeout: options.electionTimeout,
@@ -58,7 +88,7 @@ export class SharedWebSocket implements Disposable {
     this.cleanups.push(
       this.bus.subscribe<{ event: string; data: unknown }>('ws:send', (msg) => {
         if (this.coordinator.isLeader && this.socket) {
-          this.socket.send({ event: msg.event, data: msg.data });
+          this.socket.send({ [this.proto.eventField]: msg.event, [this.proto.dataField]: msg.data });
         }
       }),
     );
@@ -72,8 +102,37 @@ export class SharedWebSocket implements Disposable {
     );
 
     // Leader lifecycle
-    this.coordinator.onBecomeLeader(() => this.onBecomeLeader());
-    this.coordinator.onLoseLeadership(() => this.onLoseLeadership());
+    this.coordinator.onBecomeLeader(() => {
+      this.handleBecomeLeader();
+      this.bus.broadcast('ws:lifecycle', { type: 'leader', isLeader: true });
+    });
+    this.coordinator.onLoseLeadership(() => {
+      this.handleLoseLeadership();
+      this.bus.broadcast('ws:lifecycle', { type: 'leader', isLeader: false });
+    });
+
+    // Lifecycle events from bus (all tabs receive)
+    this.cleanups.push(
+      this.bus.subscribe<{ type: string; isLeader?: boolean; error?: unknown }>('ws:lifecycle', (msg) => {
+        switch (msg.type) {
+          case 'connect':
+            this.subs.emit('$lifecycle:connect', undefined);
+            break;
+          case 'disconnect':
+            this.subs.emit('$lifecycle:disconnect', undefined);
+            break;
+          case 'reconnecting':
+            this.subs.emit('$lifecycle:reconnecting', undefined);
+            break;
+          case 'leader':
+            this.subs.emit('$lifecycle:leader', msg.isLeader);
+            break;
+          case 'error':
+            this.subs.emit('$lifecycle:error', msg.error);
+            break;
+        }
+      }),
+    );
 
     // Cleanup on tab close
     if (typeof window !== 'undefined') {
@@ -96,12 +155,74 @@ export class SharedWebSocket implements Disposable {
     await this.coordinator.elect();
   }
 
-  /** Subscribe to server events (works in ALL tabs). */
-  on(event: string, handler: EventHandler): Unsubscribe {
+  // ─── Lifecycle Hooks ─────────────────────────────────
+
+  /** Called when WebSocket connection opens (broadcast to all tabs). */
+  onConnect(fn: () => void): Unsubscribe {
+    return this.subs.on('$lifecycle:connect', fn);
+  }
+
+  /** Called when WebSocket connection closes (broadcast to all tabs). */
+  onDisconnect(fn: () => void): Unsubscribe {
+    return this.subs.on('$lifecycle:disconnect', fn);
+  }
+
+  /** Called when WebSocket starts reconnecting (broadcast to all tabs). */
+  onReconnecting(fn: () => void): Unsubscribe {
+    return this.subs.on('$lifecycle:reconnecting', fn);
+  }
+
+  /** Called when this tab becomes leader or loses leadership. */
+  onLeaderChange(fn: (isLeader: boolean) => void): Unsubscribe {
+    return this.subs.on('$lifecycle:leader', fn as EventHandler);
+  }
+
+  /** Called on WebSocket or network error (broadcast to all tabs). */
+  onError(fn: (error: unknown) => void): Unsubscribe {
+    return this.subs.on('$lifecycle:error', fn as EventHandler);
+  }
+
+  // ─── Middleware ───────────────────────────────────────
+
+  /**
+   * Add middleware to transform messages before send or after receive.
+   * Return null from middleware to drop the message.
+   *
+   * @example
+   * // Add timestamp to every outgoing message
+   * ws.use('outgoing', (msg) => ({ ...msg, timestamp: Date.now() }));
+   *
+   * @example
+   * // Decrypt incoming messages
+   * ws.use('incoming', (msg) => ({ ...msg, data: decrypt(msg.data) }));
+   *
+   * @example
+   * // Drop messages from blocked users
+   * ws.use('incoming', (msg) => blockedUsers.has(msg.userId) ? null : msg);
+   */
+  use(direction: 'outgoing' | 'incoming', fn: Middleware): this {
+    if (direction === 'outgoing') {
+      this.outgoingMiddleware.push(fn);
+    } else {
+      this.incomingMiddleware.push(fn);
+    }
+    return this;
+  }
+
+  // ─── Event Subscription ──────────────────────────────
+
+  /** Subscribe to server events (works in ALL tabs). Type-safe with EventMap. */
+  on<K extends string & keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
+  on(event: string, handler: EventHandler<unknown>): Unsubscribe;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(event: string, handler: (data: any) => void): Unsubscribe {
     return this.subs.on(event, handler);
   }
 
-  once(event: string, handler: EventHandler): Unsubscribe {
+  once<K extends string & keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
+  once(event: string, handler: EventHandler<unknown>): Unsubscribe;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  once(event: string, handler: (data: any) => void): Unsubscribe {
     return this.subs.once(event, handler);
   }
 
@@ -109,15 +230,31 @@ export class SharedWebSocket implements Disposable {
     this.subs.off(event, handler);
   }
 
-  /** Async generator for consuming events. */
+  /** Async generator for consuming events. Type-safe with EventMap. */
+  stream<K extends string & keyof TEvents>(event: K, signal?: AbortSignal): AsyncGenerator<TEvents[K]>;
+  stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown>;
   stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown> {
     return this.subs.stream(event, signal);
   }
 
-  /** Send message to server (auto-routed through leader). */
+  /** Send message to server (auto-routed through leader). Type-safe with EventMap. */
+  send<K extends string & keyof TEvents>(event: K, data: TEvents[K]): void;
+  send(event: string, data: unknown): void;
   send(event: string, data: unknown): void {
+    let payload: unknown = { [this.proto.eventField]: event, [this.proto.dataField]: data };
+
+    for (const mw of this.outgoingMiddleware) {
+      payload = mw(payload);
+      if (payload === null) {
+        this.log.debug('[SharedWS] ✗ outgoing dropped by middleware', event);
+        return;
+      }
+    }
+
+    this.log.debug('[SharedWS] → send', event, data);
+
     if (this.coordinator.isLeader && this.socket) {
-      this.socket.send({ event, data });
+      this.socket.send(payload);
     } else {
       this.bus.publish('ws:send', { event, data });
     }
@@ -142,6 +279,54 @@ export class SharedWebSocket implements Disposable {
     return this.subs.on(`sync:${key}`, fn as EventHandler);
   }
 
+  /**
+   * Subscribe to a private/scoped channel. Returns a channel handle with
+   * scoped on/send/stream methods. Sends join on subscribe, leave on unsubscribe.
+   *
+   * @example
+   * const chat = ws.channel('chat:room_123');
+   * chat.on('message', (msg) => render(msg));
+   * chat.send('message', { text: 'Hello' });
+   * chat.leave(); // sends leave + unsubscribes
+   *
+   * @example
+   * // Private notifications for tenant
+   * const notifications = ws.channel(`tenant:${tenantId}:notifications`);
+   * notifications.on('alert', (alert) => showToast(alert));
+   */
+  channel(name: string): Channel {
+    // Notify server about channel subscription
+    this.send(this.proto.channelJoin, { channel: name });
+
+    const self = this;
+    const unsubs: Unsubscribe[] = [];
+
+    return {
+      name,
+      on(event: string, handler: EventHandler): Unsubscribe {
+        const unsub = self.subs.on(`${name}:${event}`, handler);
+        unsubs.push(unsub);
+        return unsub;
+      },
+      once(event: string, handler: EventHandler): Unsubscribe {
+        const unsub = self.subs.once(`${name}:${event}`, handler);
+        unsubs.push(unsub);
+        return unsub;
+      },
+      send(event: string, data: unknown): void {
+        self.send(`${name}:${event}`, data);
+      },
+      stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown> {
+        return self.subs.stream(`${name}:${event}`, signal);
+      },
+      leave(): void {
+        self.send(self.proto.channelLeave, { channel: name });
+        for (const unsub of unsubs) unsub();
+        unsubs.length = 0;
+      },
+    };
+  }
+
   disconnect(): void {
     this[Symbol.dispose]();
   }
@@ -153,6 +338,7 @@ export class SharedWebSocket implements Disposable {
       reconnectMaxDelay: this.options.reconnectMaxDelay,
       heartbeatInterval: this.options.heartbeatInterval,
       sendBuffer: this.options.sendBuffer,
+      pingPayload: this.proto.ping,
     };
 
     if (this.options.useWorker) {
@@ -167,27 +353,55 @@ export class SharedWebSocket implements Disposable {
     return new SharedSocket(this.url, {
       ...socketOptions,
       auth: this.options.auth,
+      authToken: this.options.authToken,
+      authParam: this.options.authParam,
     });
   }
 
-  private onBecomeLeader(): void {
+  private handleBecomeLeader(): void {
+    this.log.info('[SharedWS] 👑 became leader');
     this.socket = this.createSocket();
 
-    this.socket.onMessage((data: any) => {
-      const event = data?.event ?? 'message';
-      const payload = data?.data ?? data;
-      // Broadcast to ALL tabs (including self)
+    this.socket.onMessage((raw: unknown) => {
+      let data: unknown = raw;
+      for (const mw of this.incomingMiddleware) {
+        data = mw(data);
+        if (data === null) {
+          this.log.debug('[SharedWS] ✗ incoming dropped by middleware');
+          return;
+        }
+      }
+
+      const msg = data as Record<string, unknown> | null | undefined;
+      const event = (msg?.[this.proto.eventField] as string) ?? this.proto.defaultEvent;
+      const payload = msg?.[this.proto.dataField] ?? data;
+      this.log.debug('[SharedWS] ← recv', event, payload);
       this.bus.broadcast('ws:message', { event, data: payload });
     });
 
-    // Handle send requests from followers (request/response pattern)
+    this.socket.onStateChange((state: string) => {
+      this.log.info('[SharedWS]', state === 'connected' ? '✓ connected' : state === 'reconnecting' ? '🔄 reconnecting' : `state: ${state}`);
+      switch (state) {
+        case 'connected':
+          this.bus.broadcast('ws:lifecycle', { type: 'connect' });
+          break;
+        case 'closed':
+          this.bus.broadcast('ws:lifecycle', { type: 'disconnect' });
+          break;
+        case 'reconnecting':
+          this.bus.broadcast('ws:lifecycle', { type: 'reconnecting' });
+          break;
+      }
+    });
+
     this.cleanups.push(
       this.bus.respond<{ event: string; data: unknown }, unknown>('ws:request', async (req) => {
         return new Promise((resolve) => {
-          const unsub = this.socket!.onMessage((response: any) => {
-            if (response?.event === req.event || response?.requestId) {
+          const unsub = this.socket!.onMessage((response: unknown) => {
+            const res = response as Record<string, unknown> | undefined;
+            if (res?.[this.proto.eventField] === req.event || res?.requestId) {
               unsub();
-              resolve(response?.data ?? response);
+              resolve(res?.[this.proto.dataField] ?? response);
             }
           });
           this.socket!.send({ event: req.event, data: req.data });
@@ -198,7 +412,7 @@ export class SharedWebSocket implements Disposable {
     this.socket.connect();
   }
 
-  private onLoseLeadership(): void {
+  private handleLoseLeadership(): void {
     if (this.socket) {
       this.socket[Symbol.dispose]();
       this.socket = null;

package/src/adapters/react.ts

@@ -2,13 +2,14 @@ import {
   createContext,
   useContext,
   useEffect,
+  useRef,
   useState,
   useEffectEvent,
   type ReactNode,
   createElement,
 } from 'react';
 import { SharedWebSocket } from '../SharedWebSocket';
-import type { SharedWebSocketOptions, TabRole } from '../types';
+import type { SharedWebSocketOptions, TabRole, SocketLifecycleHandlers, EventHandler } from '../types';
 
 // ─── Context ─────────────────────────────────────────────
 
@@ -115,7 +116,7 @@ export function useSocketEvent<T>(event: string, callback?: (data: T) => void):
   });
 
   useEffect(() => {
-    const unsub = socket.on(event, onEvent);
+    const unsub = socket.on(event, onEvent as EventHandler);
     return unsub;
   }, [socket, event]);
 
@@ -159,7 +160,7 @@ export function useSocketStream<T>(event: string, callback?: (data: T) => void):
 
   useEffect(() => {
     if (!callback) setItems([]);
-    const unsub = socket.on(event, onEvent);
+    const unsub = socket.on(event, onEvent as EventHandler);
     return unsub;
   }, [socket, event]);
 
@@ -237,7 +238,7 @@ export function useSocketCallback<T>(event: string, callback: (data: T) => void)
   });
 
   useEffect(() => {
-    const unsub = socket.on(event, handler);
+    const unsub = socket.on(event, handler as EventHandler);
     return unsub;
   }, [socket, event]);
 }
@@ -269,3 +270,61 @@ export function useSocketStatus(): {
 
   return { connected, tabRole };
 }
+
+/**
+ * Lifecycle hooks — react to connection state changes.
+ *
+ * @example
+ * useSocketLifecycle({
+ *   onConnect: () => console.log('Connected!'),
+ *   onDisconnect: () => console.log('Disconnected'),
+ *   onReconnecting: () => showSpinner(),
+ *   onLeaderChange: (isLeader) => console.log('Leader:', isLeader),
+ *   onError: (err) => reportError(err),
+ * });
+ */
+export function useSocketLifecycle(handlers: SocketLifecycleHandlers): void {
+  const socket = useSharedWebSocket();
+
+  const onConnect = useEffectEvent(() => handlers.onConnect?.());
+  const onDisconnect = useEffectEvent(() => handlers.onDisconnect?.());
+  const onReconnecting = useEffectEvent(() => handlers.onReconnecting?.());
+  const onLeaderChange = useEffectEvent((isLeader: boolean) => handlers.onLeaderChange?.(isLeader));
+  const onError = useEffectEvent((error: unknown) => handlers.onError?.(error));
+
+  useEffect(() => {
+    const unsubs = [
+      socket.onConnect(onConnect),
+      socket.onDisconnect(onDisconnect),
+      socket.onReconnecting(onReconnecting),
+      socket.onLeaderChange(onLeaderChange),
+      socket.onError(onError),
+    ];
+    return () => unsubs.forEach((u) => u());
+  }, [socket]);
+}
+
+/**
+ * Subscribe to a private channel. Auto-joins on mount, leaves on unmount.
+ *
+ * @example
+ * const chat = useChannel('chat:room_123');
+ * const message = useSocketEvent('chat:room_123:message');
+ * chat.send('message', { text: 'Hello' });
+ *
+ * @example
+ * // Tenant notifications
+ * const notifications = useChannel(`tenant:${tenantId}:notifications`);
+ * useSocketCallback(`tenant:${tenantId}:notifications:alert`, showToast);
+ */
+export function useChannel(name: string) {
+  const socket = useSharedWebSocket();
+  const channelRef = useRef(socket.channel(name));
+
+  useEffect(() => {
+    channelRef.current = socket.channel(name);
+    return () => channelRef.current.leave();
+  }, [socket, name]);
+
+  return channelRef.current;
+}