@gwakko/shared-websocket 0.11.1 → 0.12.0

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, 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/**\n * Reactive auth state with authenticate/deauthenticate actions.\n * Syncs across all tabs.\n *\n * @example\n * const { isAuthenticated, authenticate, deauthenticate } = useSocketAuth();\n *\n * async function login(email: string, password: string) {\n *   const { token } = await api.login(email, password);\n *   authenticate(token);\n * }\n *\n * @example\n * // In template: <button v-if=\"isAuthenticated\" @click=\"deauthenticate\">Logout</button>\n */\nexport function useSocketAuth(): {\n  isAuthenticated: Ref<boolean>;\n  authenticate: (token: string) => void;\n  deauthenticate: () => void;\n} {\n  const socket = useSharedWebSocket();\n  const isAuthenticated = ref(socket.isAuthenticated);\n\n  const unsub = socket.onAuthChange((authenticated: boolean) => {\n    isAuthenticated.value = authenticated;\n  });\n\n  onUnmounted(unsub);\n\n  return {\n    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,\n    authenticate: (token: string) => socket.authenticate(token),\n    deauthenticate: () => socket.deauthenticate(),\n  };\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  isAuthenticated: Ref<boolean>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n  const isAuthenticated = ref(socket.isAuthenticated);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n    isAuthenticated.value = socket.isAuthenticated;\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    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,\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  if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));\n  if (handlers.onInactive) unsubs.push(socket.onInactive(handlers.onInactive));\n  if (handlers.onVisibilityChange) unsubs.push(socket.onVisibilityChange(handlers.onVisibilityChange));\n  if (handlers.onAuthChange) unsubs.push(socket.onAuthChange(handlers.onAuthChange));\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, options?: { auth?: boolean }) {\n  const socket = useSharedWebSocket();\n  const channel = socket.channel(name, options);\n\n  onUnmounted(() => channel.leave());\n\n  return channel;\n}\n\n/**\n * Subscribe to server-side topics. Auto-unsubscribes on unmount.\n *\n * @example\n * useTopics(['notifications:orders', 'notifications:payments']);\n */\nexport function useTopics(topics: string[], options?: { auth?: boolean }): void {\n  const socket = useSharedWebSocket();\n\n  topics.forEach((t) => socket.subscribe(t, options));\n\n  onUnmounted(() => {\n    topics.forEach((t) => socket.unsubscribe(t));\n  });\n}\n\n/**\n * Enable browser push notifications for an event. Auto-cleanup on unmount.\n *\n * @example\n * usePush('notification', {\n *   title: (n) => n.title,\n *   body: (n) => n.body,\n *   icon: '/icon.png',\n * });\n */\nexport function usePush<T = unknown>(\n  event: string,\n  config: {\n    title: string | ((data: T) => string);\n    body?: string | ((data: T) => string);\n    icon?: string;\n    tag?: string | ((data: T) => string);\n    leaderOnly?: boolean;\n    onlyWhenHidden?: boolean;\n    onClick?: (data: T) => void;\n  },\n): void {\n  const socket = useSharedWebSocket();\n  const unsub = socket.push<T>(event, config);\n\n  onUnmounted(unsub);\n}\n"],"mappings":"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","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/**\n * Reactive auth state with authenticate/deauthenticate actions.\n * Syncs across all tabs.\n *\n * @example\n * const { isAuthenticated, authenticate, deauthenticate } = useSocketAuth();\n *\n * async function login(email: string, password: string) {\n *   const { token } = await api.login(email, password);\n *   authenticate(token);\n * }\n *\n * @example\n * // In template: <button v-if=\"isAuthenticated\" @click=\"deauthenticate\">Logout</button>\n */\nexport function useSocketAuth(): {\n  isAuthenticated: Ref<boolean>;\n  authenticate: (token: string) => void;\n  deauthenticate: () => void;\n} {\n  const socket = useSharedWebSocket();\n  const isAuthenticated = ref(socket.isAuthenticated);\n\n  const unsub = socket.onAuthChange((authenticated: boolean) => {\n    isAuthenticated.value = authenticated;\n  });\n\n  onUnmounted(unsub);\n\n  return {\n    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,\n    authenticate: (token: string) => socket.authenticate(token),\n    deauthenticate: () => socket.deauthenticate(),\n  };\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  isAuthenticated: Ref<boolean>;\n} {\n  const socket = useSharedWebSocket();\n  const connected = ref(socket.connected);\n  const tabRole = ref<TabRole>(socket.tabRole);\n  const isAuthenticated = ref(socket.isAuthenticated);\n\n  const timer = setInterval(() => {\n    connected.value = socket.connected;\n    tabRole.value = socket.tabRole;\n    isAuthenticated.value = socket.isAuthenticated;\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    isAuthenticated: readonly(isAuthenticated) as Ref<boolean>,\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  if (handlers.onActive) unsubs.push(socket.onActive(handlers.onActive));\n  if (handlers.onInactive) unsubs.push(socket.onInactive(handlers.onInactive));\n  if (handlers.onVisibilityChange) unsubs.push(socket.onVisibilityChange(handlers.onVisibilityChange));\n  if (handlers.onAuthChange) unsubs.push(socket.onAuthChange(handlers.onAuthChange));\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, options?: { auth?: boolean }) {\n  const socket = useSharedWebSocket();\n  const channel = socket.channel(name, options);\n\n  onUnmounted(() => channel.leave());\n\n  return channel;\n}\n\n/**\n * Subscribe to server-side topics. Auto-unsubscribes on unmount.\n *\n * @example\n * useTopics(['notifications:orders', 'notifications:payments']);\n */\nexport function useTopics(topics: string[], options?: { auth?: boolean }): void {\n  const socket = useSharedWebSocket();\n\n  topics.forEach((t) => socket.subscribe(t, options));\n\n  onUnmounted(() => {\n    topics.forEach((t) => socket.unsubscribe(t));\n  });\n}\n\n/**\n * Enable browser push notifications for an event. Auto-cleanup on unmount.\n *\n * @example\n * usePush('notification', {\n *   title: (n) => n.title,\n *   body: (n) => n.body,\n *   icon: '/icon.png',\n * });\n */\nexport function usePush<T = unknown>(\n  event: string,\n  config: {\n    title: string | ((data: T) => string);\n    body?: string | ((data: T) => string);\n    icon?: string;\n    tag?: string | ((data: T) => string);\n    leaderOnly?: boolean;\n    onlyWhenHidden?: boolean;\n    onClick?: (data: T) => void;\n  },\n): void {\n  const socket = useSharedWebSocket();\n  const unsub = socket.push<T>(event, config);\n\n  onUnmounted(unsub);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwakko/shared-websocket",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Share ONE WebSocket connection across browser tabs — leader election, BroadcastChannel sync, optional Web Worker",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -8,19 +8,34 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     },
     "./react": {
+      "types": "./dist/react.d.ts",
       "import": "./dist/react.js",
-      "require": "./dist/react.cjs",
-      "types": "./dist/react.d.ts"
+      "require": "./dist/react.cjs"
     },
     "./vue": {
+      "types": "./dist/vue.d.ts",
       "import": "./dist/vue.js",
-      "require": "./dist/vue.cjs",
-      "types": "./dist/vue.d.ts"
+      "require": "./dist/vue.cjs"
+    },
+    "./sync": {
+      "types": "./dist/sync.d.ts",
+      "import": "./dist/sync.js",
+      "require": "./dist/sync.cjs"
+    },
+    "./sync/react": {
+      "types": "./dist/sync-react.d.ts",
+      "import": "./dist/sync-react.js",
+      "require": "./dist/sync-react.cjs"
+    },
+    "./sync/vue": {
+      "types": "./dist/sync-vue.d.ts",
+      "import": "./dist/sync-vue.js",
+      "require": "./dist/sync-vue.cjs"
     }
   },
   "files": [
@@ -41,6 +56,8 @@
     "broadcast-channel",
     "shared",
     "tabs",
+    "tab-sync",
+    "cross-tab",
     "leader-election",
     "real-time",
     "react",
@@ -52,7 +69,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Gwakko/shared-websocket.git"
+    "url": "git+https://github.com/Gwakko/shared-websocket.git"
   },
   "homepage": "https://github.com/Gwakko/shared-websocket#readme",
   "peerDependencies": {

package/src/TabSync.ts

@@ -0,0 +1,127 @@
+import './utils/disposable';
+import type { Unsubscribe } from './types';
+
+interface SyncMessage {
+  key: string;
+  value: unknown;
+  deleted?: boolean;
+}
+
+/**
+ * Cross-tab state synchronization via BroadcastChannel.
+ * No WebSocket needed — works standalone for sharing state between browser tabs.
+ *
+ * @example
+ * const sync = new TabSync('my-app');
+ * sync.set('theme', 'dark');
+ * sync.on('theme', (theme) => applyTheme(theme));
+ */
+export class TabSync implements Disposable {
+  private store = new Map<string, unknown>();
+  private listeners = new Map<string, Set<(value: unknown) => void>>();
+  private bc: BroadcastChannel;
+  private disposed = false;
+
+  constructor(channel = 'tab-sync') {
+    this.bc = new BroadcastChannel(channel);
+    this.bc.onmessage = (ev: MessageEvent<SyncMessage>) => {
+      const { key, value, deleted } = ev.data;
+      if (deleted) {
+        this.store.delete(key);
+      } else {
+        this.store.set(key, value);
+      }
+      this.emit(key, value);
+    };
+  }
+
+  /** Set a value and broadcast to all tabs. Local listeners also fire. */
+  set<T>(key: string, value: T): void {
+    this.store.set(key, value);
+    this.bc.postMessage({ key, value } satisfies SyncMessage);
+    this.emit(key, value);
+  }
+
+  /** Get current value from local store. */
+  get<T>(key: string): T | undefined {
+    return this.store.get(key) as T | undefined;
+  }
+
+  /** Delete a key and broadcast deletion to all tabs. */
+  delete(key: string): void {
+    this.store.delete(key);
+    this.bc.postMessage({ key, value: undefined, deleted: true } satisfies SyncMessage);
+    this.emit(key, undefined);
+  }
+
+  /** Check if a key exists in the local store. */
+  has(key: string): boolean {
+    return this.store.has(key);
+  }
+
+  /** Get all keys in the local store. */
+  keys(): string[] {
+    return [...this.store.keys()];
+  }
+
+  /** Get number of entries. */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /**
+   * Listen for changes to a key. Fires when any tab (including this one) calls set().
+   *
+   * @example
+   * sync.on('cart', (cart) => updateBadge(cart.items.length));
+   */
+  on<T>(key: string, fn: (value: T) => void): Unsubscribe {
+    let set = this.listeners.get(key);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(key, set);
+    }
+    const wrapper = fn as (value: unknown) => void;
+    set.add(wrapper);
+    return () => set!.delete(wrapper);
+  }
+
+  /** Listen for a key change once, then auto-unsubscribe. */
+  once<T>(key: string, fn: (value: T) => void): Unsubscribe {
+    const unsub = this.on<T>(key, (value) => {
+      unsub();
+      fn(value);
+    });
+    return unsub;
+  }
+
+  /** Clear all keys and notify listeners. */
+  clear(): void {
+    const keys = [...this.store.keys()];
+    this.store.clear();
+    for (const key of keys) {
+      this.bc.postMessage({ key, value: undefined, deleted: true } satisfies SyncMessage);
+      this.emit(key, undefined);
+    }
+  }
+
+  /** Dispose — close BroadcastChannel and clear all state. */
+  dispose(): void {
+    this[Symbol.dispose]();
+  }
+
+  private emit(key: string, value: unknown): void {
+    const set = this.listeners.get(key);
+    if (set) {
+      for (const fn of set) fn(value);
+    }
+  }
+
+  [Symbol.dispose](): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.bc.close();
+    this.store.clear();
+    this.listeners.clear();
+  }
+}

package/src/adapters/sync-react.ts

@@ -0,0 +1,152 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useEffectEvent,
+  type ReactNode,
+  createElement,
+} from 'react';
+import { TabSync } from '../TabSync';
+
+// ─── Context ─────────────────────────────────────────────
+
+const TabSyncContext = createContext<TabSync | null>(null);
+
+/**
+ * Provider for TabSync — creates instance, auto-disposes on unmount.
+ *
+ * @example
+ * function App() {
+ *   return (
+ *     <TabSyncProvider channel="my-app">
+ *       <Dashboard />
+ *     </TabSyncProvider>
+ *   );
+ * }
+ */
+export interface TabSyncProviderProps {
+  /** BroadcastChannel name (default: "tab-sync"). */
+  channel?: string;
+  children: ReactNode;
+}
+
+export function TabSyncProvider({ channel, children }: TabSyncProviderProps) {
+  const [sync] = useState(() => new TabSync(channel));
+
+  useEffect(() => {
+    return () => sync[Symbol.dispose]();
+  }, [sync]);
+
+  return createElement(TabSyncContext.Provider, { value: sync }, children);
+}
+
+/**
+ * Access the TabSync instance from context.
+ *
+ * @example
+ * const sync = useTabSyncContext();
+ * sync.set('theme', 'dark');
+ */
+export function useTabSyncContext(): TabSync {
+  const ctx = useContext(TabSyncContext);
+  if (!ctx) {
+    throw new Error('useTabSync must be used within <TabSyncProvider>');
+  }
+  return ctx;
+}
+
+// ─── Hooks ───────────────────────────────────────────────
+
+/**
+ * Two-way state sync across browser tabs — like useState but shared.
+ * - Without callback: returns [value, setter] synced across tabs.
+ * - With callback: also calls your handler on every change (side effects).
+ *
+ * @example
+ * // Shared state — updates propagate to all tabs
+ * const [theme, setTheme] = useTabSync('theme', 'light');
+ * <button onClick={() => setTheme('dark')}>Dark mode</button>
+ *
+ * @example
+ * // With side effect callback
+ * const [cart, setCart] = useTabSync('cart', { items: [] }, (cart) => {
+ *   document.title = `Cart (${cart.items.length})`;
+ * });
+ *
+ * @example
+ * // Form state synced across tabs
+ * const [draft, setDraft] = useTabSync('email-draft', '');
+ * <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
+ */
+export function useTabSync<T>(
+  key: string,
+  initialValue: T,
+  callback?: (value: T) => void,
+): [T, (value: T) => void] {
+  const sync = useTabSyncContext();
+  const [value, setValue] = useState<T>(() => sync.get<T>(key) ?? initialValue);
+
+  const onSync = useEffectEvent((synced: T) => {
+    setValue(synced);
+    callback?.(synced);
+  });
+
+  useEffect(() => {
+    return sync.on<T>(key, onSync);
+  }, [sync, key]);
+
+  const setAndSync = useEffectEvent((newValue: T) => {
+    setValue(newValue);
+    sync.set(key, newValue);
+  });
+
+  return [value, setAndSync];
+}
+
+/**
+ * Read-only subscription to a synced key. Returns undefined until first set.
+ *
+ * @example
+ * const theme = useTabSyncValue<string>('theme');
+ * <div className={theme === 'dark' ? 'dark' : 'light'} />
+ */
+export function useTabSyncValue<T>(key: string): T | undefined {
+  const sync = useTabSyncContext();
+  const [value, setValue] = useState<T | undefined>(() => sync.get<T>(key));
+
+  const onSync = useEffectEvent((synced: T) => {
+    setValue(synced);
+  });
+
+  useEffect(() => {
+    return sync.on<T>(key, onSync);
+  }, [sync, key]);
+
+  return value;
+}
+
+/**
+ * Fire-and-forget listener for a synced key. No state, no return value.
+ *
+ * @example
+ * useTabSyncCallback<string>('theme', (theme) => {
+ *   document.documentElement.setAttribute('data-theme', theme);
+ * });
+ *
+ * @example
+ * useTabSyncCallback<Cart>('cart', (cart) => {
+ *   analytics.track('cart_updated', { count: cart.items.length });
+ * });
+ */
+export function useTabSyncCallback<T>(key: string, callback: (value: T) => void): void {
+  const sync = useTabSyncContext();
+
+  const handler = useEffectEvent((value: T) => {
+    callback(value);
+  });
+
+  useEffect(() => {
+    return sync.on<T>(key, handler);
+  }, [sync, key]);
+}

package/src/adapters/sync-vue.ts

@@ -0,0 +1,128 @@
+import {
+  ref,
+  onUnmounted,
+  inject,
+  readonly,
+  watch,
+  type Ref,
+  type InjectionKey,
+  type App,
+} from 'vue';
+import { TabSync } from '../TabSync';
+
+// ─── Plugin ──────────────────────────────────────────────
+
+export const TabSyncKey: InjectionKey<TabSync> = Symbol('TabSync');
+
+/**
+ * Vue 3 plugin for TabSync.
+ *
+ * @example
+ * const app = createApp(App);
+ * app.use(createTabSyncPlugin('my-app'));
+ */
+export function createTabSyncPlugin(channel?: string) {
+  return {
+    install(app: App) {
+      const sync = new TabSync(channel);
+      app.provide(TabSyncKey, sync);
+
+      const originalUnmount = app.unmount.bind(app);
+      app.unmount = () => {
+        sync[Symbol.dispose]();
+        originalUnmount();
+      };
+    },
+  };
+}
+
+/**
+ * Access the TabSync instance from provided context.
+ *
+ * @example
+ * const sync = useTabSyncContext();
+ * sync.set('theme', 'dark');
+ */
+export function useTabSyncContext(): TabSync {
+  const sync = inject(TabSyncKey);
+  if (!sync) {
+    throw new Error('useTabSync: TabSync not provided. Did you install the plugin?');
+  }
+  return sync;
+}
+
+// ─── Composables ─────────────────────────────────────────
+
+/**
+ * Two-way reactive state synced across tabs.
+ * Mutating the ref broadcasts the change; changes from other tabs update the ref.
+ *
+ * @example
+ * const theme = useTabSync('theme', 'light');
+ * theme.value = 'dark'; // syncs to all tabs
+ *
+ * @example
+ * // With side effect callback
+ * const cart = useTabSync('cart', { items: [] }, (cart) => {
+ *   document.title = `Cart (${cart.items.length})`;
+ * });
+ * cart.value = { items: [...cart.value.items, newItem] };
+ *
+ * @example
+ * // Form draft synced across tabs
+ * const draft = useTabSync('email-draft', '');
+ * // <textarea v-model="draft" />
+ */
+export function useTabSync<T>(key: string, initialValue: T, callback?: (value: T) => void): Ref<T> {
+  const sync = useTabSyncContext();
+  const value = ref<T>(sync.get<T>(key) ?? initialValue) as Ref<T>;
+
+  const unsub = sync.on<T>(key, (v) => {
+    value.value = v;
+    callback?.(v);
+  });
+
+  watch(
+    value,
+    (newVal) => {
+      sync.set(key, newVal);
+    },
+    { deep: true },
+  );
+
+  onUnmounted(unsub);
+  return value;
+}
+
+/**
+ * Read-only subscription to a synced key. Returns undefined until first set.
+ *
+ * @example
+ * const theme = useTabSyncValue<string>('theme');
+ * // <div :class="theme === 'dark' ? 'dark' : 'light'" />
+ */
+export function useTabSyncValue<T>(key: string): Ref<T | undefined> {
+  const sync = useTabSyncContext();
+  const value = ref<T | undefined>(sync.get<T>(key)) as Ref<T | undefined>;
+
+  const unsub = sync.on<T>(key, (v) => {
+    value.value = v;
+  });
+
+  onUnmounted(unsub);
+  return readonly(value) as Ref<T | undefined>;
+}
+
+/**
+ * Fire-and-forget listener for a synced key. No ref, no return value.
+ *
+ * @example
+ * useTabSyncCallback<string>('theme', (theme) => {
+ *   document.documentElement.setAttribute('data-theme', theme);
+ * });
+ */
+export function useTabSyncCallback<T>(key: string, callback: (value: T) => void): void {
+  const sync = useTabSyncContext();
+  const unsub = sync.on<T>(key, callback);
+  onUnmounted(unsub);
+}

package/src/index.ts

@@ -2,6 +2,9 @@
 export { SharedWebSocket } from './SharedWebSocket';
 export { withSocket } from './withSocket';
 
+// Tab Sync (standalone — no WebSocket needed)
+export { TabSync } from './TabSync';
+
 // Internal components (for advanced usage)
 export { MessageBus } from './MessageBus';
 export { TabCoordinator } from './TabCoordinator';

package/src/sync.ts

@@ -0,0 +1,2 @@
+export { TabSync } from './TabSync';
+export type { Unsubscribe } from './types';