@gwakko/shared-websocket 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 gwakko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,381 @@
+# Shared WebSocket
+
+Share ONE WebSocket connection across multiple browser tabs. Zero dependencies. React and Vue adapters included.
+
+## Problem
+
+5 tabs open = 5 WebSocket connections = 5x server resources for the same user.
+
+## Solution
+
+One tab becomes the **leader** (holds the WebSocket). Other tabs are **followers** (receive data via BroadcastChannel). If the leader closes — automatic election picks a new leader. Zero downtime.
+
+```
+Tab 1 (Leader)        Tab 2 (Follower)      Tab 3 (Follower)
+┌──────────┐          ┌──────────┐          ┌──────────┐
+│ WebSocket│          │          │          │          │
+│    ↕     │          │          │          │          │
+│  Server  │          │          │          │          │
+└────┬─────┘          └─────┬────┘          └─────┬────┘
+     └────── BroadcastChannel ──────────────────────┘
+```
+
+## Installation
+
+### From npm
+
+```bash
+npm install shared-websocket
+```
+
+### From GitHub (latest source)
+
+```bash
+npm install github:Gwakko/shared-websocket
+```
+
+### Manual (copy into your project)
+
+```bash
+# Clone and copy src/ into your project
+git clone https://github.com/Gwakko/shared-websocket.git
+cp -r shared-websocket/src ./your-project/shared-websocket
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/Gwakko/shared-websocket.git
+cd shared-websocket
+npm install
+npm run build   # outputs ESM + CJS + types to dist/
+```
+
+## Usage — Vanilla TypeScript
+
+```typescript
+import { SharedWebSocket } from 'shared-websocket';
+
+const ws = new SharedWebSocket('wss://api.example.com/ws', {
+  auth: () => localStorage.getItem('token')!,
+  useWorker: true,  // optional: run WebSocket in Web Worker (offloads main thread)
+});
+
+await ws.connect();
+
+// Subscribe to events (works in ALL tabs)
+ws.on('order.created', (order) => {
+  console.log('New order:', order);
+});
+
+// Send message (auto-routed through leader tab)
+ws.send('chat.message', { text: 'Hello!' });
+
+// Generator streaming
+for await (const msg of ws.stream('chat.messages')) {
+  console.log(msg);
+}
+
+// Sync state across tabs (no server roundtrip)
+ws.sync('cart', { items: [1, 2, 3] });
+ws.onSync('cart', (cart) => console.log('Cart updated:', cart));
+
+// Cleanup
+ws.disconnect();
+```
+
+### Scoped Lifecycle — `withSocket()`
+
+Auto-creates, connects, and disposes. Guarantees cleanup even on errors.
+
+```typescript
+import { withSocket } from 'shared-websocket';
+
+// Basic
+await withSocket('wss://api.example.com/ws', async ({ ws }) => {
+  ws.on('order.created', (order) => console.log(order));
+  await longRunningWork();
+}); // auto-disposed here
+
+// With auth
+await withSocket('wss://api.example.com/ws', {
+  auth: () => localStorage.getItem('token')!,
+}, async ({ ws, signal }) => {
+  for await (const msg of ws.stream('chat.messages', signal)) {
+    renderMessage(msg);
+  }
+});
+
+// Tab-to-tab sync via BroadcastChannel (no server roundtrip)
+await withSocket('wss://api.example.com/ws', async ({ ws }) => {
+  // Send state to ALL tabs instantly
+  ws.sync('cart', { items: [1, 2, 3] });
+  ws.sync('theme', 'dark');
+  ws.sync('locale', 'en');
+
+  // Read synced state from other tabs
+  const cart = ws.getSync<Cart>('cart');  // { items: [1, 2, 3] }
+
+  // React to changes from other tabs
+  ws.onSync('cart', (cart) => {
+    updateCartBadge(cart.items.length);
+  });
+
+  ws.onSync('theme', (theme) => {
+    document.documentElement.setAttribute('data-theme', theme);
+  });
+});
+
+// Combine: server events + tab sync
+await withSocket('wss://api.example.com/ws', {
+  auth: () => localStorage.getItem('token')!,
+}, async ({ ws, signal }) => {
+  // Server events → update state → sync to all tabs
+  ws.on('order.status', (order) => {
+    ws.sync('activeOrder', order);  // all tabs see the update
+  });
+
+  // One tab adds to cart → all tabs update
+  ws.onSync('cart', (cart) => renderCart(cart));
+
+  // Stream server messages with auto-cleanup
+  for await (const msg of ws.stream('chat.messages', signal)) {
+    renderMessage(msg);
+  }
+});
+
+// With external cancellation (AbortController)
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30_000);
+
+await withSocket('wss://api.example.com/ws', {
+  signal: controller.signal,
+}, async ({ ws, signal }) => {
+  ws.on('notifications', showToast);
+  await new Promise((_, reject) => signal.addEventListener('abort', reject));
+});
+```
+
+## Usage — React
+
+```tsx
+import {
+  SharedWebSocketProvider,
+  useSharedWebSocket,
+  useSocketEvent,
+  useSocketStream,
+  useSocketSync,
+  useSocketStatus,
+} from 'shared-websocket/adapters/react';
+
+// Provider accepts url and options as props
+function App() {
+  return (
+    <SharedWebSocketProvider
+      url="wss://api.example.com/ws"
+      options={{
+        auth: () => localStorage.getItem('token')!,
+        useWorker: true,
+      }}
+    >
+      <Dashboard />
+    </SharedWebSocketProvider>
+  );
+}
+
+function Dashboard() {
+  const ws = useSharedWebSocket();
+
+  // Latest event value (reactive) — no need to pass ws, uses context
+  const order = useSocketEvent<Order>('order.created');
+
+  // Accumulated stream
+  const messages = useSocketStream<Message>('chat.message');
+
+  // Synced across tabs (no server roundtrip)
+  const [cart, setCart] = useSocketSync('cart', { items: [] });
+
+  // Connection status
+  const { connected, tabRole } = useSocketStatus();
+
+  return (
+    <div>
+      <p>Status: {connected ? 'Online' : 'Offline'} ({tabRole})</p>
+      {order && <p>Latest order: #{order.id}</p>}
+      <button onClick={() => ws.send('ping', {})}>Ping</button>
+      <button onClick={() => setCart({ items: [...cart.items, Date.now()] })}>
+        Add to cart ({cart.items.length})
+      </button>
+    </div>
+  );
+}
+```
+
+## Usage — Vue 3
+
+```vue
+<!-- main.ts -->
+<script setup>
+import { createApp } from 'vue';
+import { createSharedWebSocketPlugin } from 'shared-websocket/adapters/vue';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(createSharedWebSocketPlugin('wss://api.example.com/ws'));
+app.mount('#app');
+</script>
+```
+
+```vue
+<!-- Dashboard.vue -->
+<script setup lang="ts">
+import {
+  useSharedWebSocket,
+  useSocketEvent,
+  useSocketStream,
+  useSocketSync,
+  useSocketStatus,
+} from 'shared-websocket/adapters/vue';
+
+const ws = useSharedWebSocket();
+
+const order = useSocketEvent<Order>('order.created');
+const messages = useSocketStream<Message>('chat.message');
+const cart = useSocketSync('cart', { items: [] });
+const { connected, tabRole } = useSocketStatus();
+
+function addToCart() {
+  cart.value = { items: [...cart.value.items, Date.now()] };
+}
+</script>
+
+<template>
+  <p>Status: {{ connected ? 'Online' : 'Offline' }} ({{ tabRole }})</p>
+  <p v-if="order">Latest order: #{{ order.id }}</p>
+  <button @click="ws.send('ping', {})">Ping</button>
+  <button @click="addToCart">Add to cart ({{ cart.items.length }})</button>
+</template>
+```
+
+## API Reference
+
+### SharedWebSocket
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Start leader election and connect |
+| `on(event, handler)` | Subscribe to server events (all tabs) |
+| `once(event, handler)` | Subscribe once |
+| `off(event, handler?)` | Unsubscribe |
+| `stream(event, signal?)` | AsyncGenerator for consuming events |
+| `send(event, data)` | Send to server (routed through leader) |
+| `request(event, data, timeout?)` | Request/response via server |
+| `sync(key, value)` | Sync state across tabs |
+| `getSync(key)` | Get synced value |
+| `onSync(key, fn)` | Listen for sync changes |
+| `disconnect()` | Close connection and cleanup |
+| `[Symbol.dispose]()` | Cleanup (also called by `disconnect`) |
+
+### withSocket()
+
+| Signature | Description |
+|-----------|-------------|
+| `withSocket(url, callback)` | Scoped lifecycle, auto-dispose |
+| `withSocket(url, options, callback)` | With auth, signal, etc. |
+
+Callback receives `{ ws, signal }` — destructure what you need. Signal aborts when scope exits.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `protocols` | `string[]` | `[]` | WebSocket subprotocols |
+| `reconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `reconnectMaxDelay` | `number` | `30000` | Max reconnect backoff (ms) |
+| `heartbeatInterval` | `number` | `30000` | Ping interval (ms) |
+| `sendBuffer` | `number` | `100` | Max buffered messages during reconnect |
+| `auth` | `() => string` | — | JWT token provider |
+| **`useWorker`** | **`boolean`** | **`false`** | **Run WebSocket in Web Worker** |
+| `workerUrl` | `string \| URL` | — | Custom worker URL (if useWorker) |
+| `electionTimeout` | `number` | `200` | Leader election timeout (ms) |
+| `leaderHeartbeat` | `number` | `2000` | Leader heartbeat interval (ms) |
+| `leaderTimeout` | `number` | `5000` | Leader absence timeout (ms) |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | Connection status |
+| `tabRole` | `'leader' \| 'follower'` | Current tab's role |
+
+### React Hooks (React 19, uses `useEffectEvent` for stable refs)
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useSharedWebSocket()` | `SharedWebSocket` | Access instance from context |
+| `useSocketEvent<T>(event)` | `T \| undefined` | Latest event value |
+| `useSocketStream<T>(event)` | `T[]` | Accumulated events |
+| `useSocketSync<T>(key, init)` | `[T, setter]` | Cross-tab synced state |
+| `useSocketStatus()` | `{ connected, tabRole }` | Connection status |
+
+All hooks use context internally — no need to pass `ws` as argument.
+
+### Vue Composables
+
+| Composable | Returns | Description |
+|-----------|---------|-------------|
+| `useSocketEvent<T>(event)` | `Ref<T>` | Latest event value |
+| `useSocketStream<T>(event)` | `Ref<T[]>` | Accumulated events |
+| `useSocketSync<T>(key, init)` | `Ref<T>` | Cross-tab synced state (two-way) |
+| `useSocketStatus()` | `{ connected, tabRole }` | Reactive connection status |
+
+## How It Works
+
+1. **Leader Election** — new tab broadcasts election request via BroadcastChannel. If no rejection in 200ms → becomes leader. Leader sends heartbeat every 2s. No heartbeat for 5s → new election.
+
+2. **Message Flow** — follower calls `send()` → message goes to BroadcastChannel → leader picks it up → forwards to WebSocket → server response → leader broadcasts to all tabs.
+
+3. **Failover** — leader tab closes → `beforeunload` fires `abdicate` → followers detect missing heartbeat → election → new leader connects WebSocket → zero data loss (buffered messages replayed).
+
+4. **Resource Safety** — `withSocket()` for scoped lifecycle, `Symbol.dispose` support. All timers, listeners, and channels properly cleaned up.
+
+5. **Worker Mode** (optional) — `useWorker: true` runs WebSocket inside a Web Worker. JSON parsing, heartbeat timers, and reconnection logic run off main thread. UI stays responsive even at high message rates.
+
+## When to Use `useWorker: true`
+
+| Scenario | useWorker | Why |
+|----------|-----------|-----|
+| Chat (10-50 msgs/sec) | `false` | Low overhead, not worth Worker complexity |
+| Simple notifications | `false` | Few messages, main thread handles fine |
+| Live trading feed (100+ msgs/sec) | **`true`** | JSON parsing 100+ msgs/sec blocks rendering |
+| Real-time dashboard (50+ metrics/sec) | **`true`** | Continuous data stream, UI must stay smooth |
+| Heavy payload (>100KB per message) | **`true`** | Parsing large JSON blocks main thread |
+| Complex UI (React with 10k+ rows) | **`true`** | Main thread already busy, any extra work causes jank |
+| Mobile / low-end devices | **`true`** | Less CPU available, offloading helps |
+| Simple landing page | `false` | Minimal UI, no rendering pressure |
+| SSR / Node.js | `false` | Workers are browser-only |
+| Debugging | `false` | Worker DevTools is less convenient |
+
+**Rule of thumb:** If your app drops frames when WebSocket messages arrive — add `useWorker: true`.
+
+```typescript
+// Without worker (default) — WebSocket in main thread
+const ws = new SharedWebSocket(url);
+
+// With worker — WebSocket in Web Worker
+const ws = new SharedWebSocket(url, { useWorker: true });
+
+// API is identical — only internal transport changes
+```
+
+## Browser Support
+
+| API | Chrome | Firefox | Safari | Edge |
+|-----|--------|---------|--------|------|
+| BroadcastChannel | 54+ | 38+ | 15.4+ | 79+ |
+| Web Worker | ✅ | ✅ | ✅ | ✅ |
+| AsyncGenerator | 63+ | 57+ | 12+ | 79+ |
+
+## License
+
+MIT

package/dist/MessageBus.d.ts

@@ -0,0 +1,20 @@
+import './utils/disposable';
+import type { Unsubscribe } from './types';
+export declare class MessageBus implements Disposable {
+    private readonly tabId;
+    private channel;
+    private listeners;
+    private pendingRequests;
+    constructor(channelName: string, tabId: string);
+    subscribe<T>(topic: string, fn: (data: T) => void): Unsubscribe;
+    publish<T>(topic: string, data: T): void;
+    broadcast<T>(topic: string, data: T): void;
+    request<T, R>(topic: string, data: T, timeout?: number): Promise<R>;
+    respond<T, R>(topic: string, fn: (data: T) => R | Promise<R>): Unsubscribe;
+    private handleMessage;
+    private postMessage;
+    private createMessage;
+    private addListener;
+    private removeListener;
+    [Symbol.dispose](): void;
+}

package/dist/SharedSocket.d.ts

@@ -0,0 +1,37 @@
+import './utils/disposable';
+import type { SocketState, Unsubscribe, EventHandler } from './types';
+interface SharedSocketOptions {
+    protocols?: string[];
+    reconnect?: boolean;
+    reconnectMaxDelay?: number;
+    heartbeatInterval?: number;
+    sendBuffer?: number;
+    auth?: () => string | Promise<string>;
+}
+export declare class SharedSocket implements Disposable {
+    private url;
+    private ws;
+    private _state;
+    private buffer;
+    private disposed;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private onMessageFns;
+    private onStateChangeFns;
+    private readonly opts;
+    constructor(url: string, options?: SharedSocketOptions);
+    get state(): SocketState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    send(data: unknown): void;
+    onMessage(fn: EventHandler): Unsubscribe;
+    onStateChange(fn: (state: SocketState) => void): Unsubscribe;
+    private reconnect;
+    private flushBuffer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private clearReconnect;
+    private setState;
+    [Symbol.dispose](): void;
+}
+export {};

package/dist/SharedWebSocket.d.ts

@@ -0,0 +1,45 @@
+import './utils/disposable';
+import type { SharedWebSocketOptions, TabRole, Unsubscribe, EventHandler } from './types';
+/**
+ * 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.
+ */
+export declare class SharedWebSocket implements Disposable {
+    private readonly url;
+    private readonly options;
+    private bus;
+    private coordinator;
+    private socket;
+    private subs;
+    private syncStore;
+    private tabId;
+    private cleanups;
+    private disposed;
+    constructor(url: string, options?: SharedWebSocketOptions);
+    get connected(): boolean;
+    get tabRole(): TabRole;
+    /** Start leader election and connect. */
+    connect(): Promise<void>;
+    /** Subscribe to server events (works in ALL tabs). */
+    on(event: string, handler: EventHandler): Unsubscribe;
+    once(event: string, handler: EventHandler): Unsubscribe;
+    off(event: string, handler?: EventHandler): void;
+    /** Async generator for consuming events. */
+    stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown>;
+    /** Send message to server (auto-routed through leader). */
+    send(event: string, data: unknown): void;
+    /** Request/response through server via leader. */
+    request<T>(event: string, data: unknown, timeout?: number): Promise<T>;
+    /** Sync state across tabs (no server roundtrip). */
+    sync<T>(key: string, value: T): void;
+    getSync<T>(key: string): T | undefined;
+    onSync<T>(key: string, fn: (value: T) => void): Unsubscribe;
+    disconnect(): void;
+    private createSocket;
+    private onBecomeLeader;
+    private onLoseLeadership;
+    [Symbol.dispose](): void;
+}

package/dist/SubscriptionManager.d.ts

@@ -0,0 +1,14 @@
+import './utils/disposable';
+import type { EventHandler, Unsubscribe } from './types';
+export declare class SubscriptionManager implements Disposable {
+    private handlers;
+    private lastMessages;
+    on(event: string, handler: EventHandler): Unsubscribe;
+    once(event: string, handler: EventHandler): Unsubscribe;
+    off(event: string, handler?: EventHandler): void;
+    emit(event: string, data: unknown): void;
+    getLastMessage(event: string): unknown | undefined;
+    stream(event: string, signal?: AbortSignal): AsyncGenerator<unknown>;
+    offAll(): void;
+    [Symbol.dispose](): void;
+}

package/dist/TabCoordinator.d.ts

@@ -0,0 +1,36 @@
+import './utils/disposable';
+import { MessageBus } from './MessageBus';
+import type { Unsubscribe } from './types';
+interface CoordinatorOptions {
+    electionTimeout?: number;
+    heartbeatInterval?: number;
+    leaderTimeout?: number;
+}
+export declare class TabCoordinator implements Disposable {
+    private readonly bus;
+    private readonly tabId;
+    private _isLeader;
+    private heartbeatTimer;
+    private leaderCheckTimer;
+    private lastHeartbeat;
+    private disposed;
+    private onBecomeLeaderFns;
+    private onLoseLeadershipFns;
+    private cleanups;
+    private readonly electionTimeout;
+    private readonly heartbeatInterval;
+    private readonly leaderTimeout;
+    constructor(bus: MessageBus, tabId: string, options?: CoordinatorOptions);
+    get isLeader(): boolean;
+    elect(): Promise<void>;
+    abdicate(): void;
+    onBecomeLeader(fn: () => void): Unsubscribe;
+    onLoseLeadership(fn: () => void): Unsubscribe;
+    private becomeLeader;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private startLeaderCheck;
+    private stopLeaderCheck;
+    [Symbol.dispose](): void;
+}
+export {};

package/dist/WorkerSocket.d.ts

@@ -0,0 +1,42 @@
+import './utils/disposable';
+import type { SocketState, Unsubscribe, EventHandler } from './types';
+/**
+ * WorkerSocket — WebSocket running inside a Web Worker.
+ *
+ * Same interface as SharedSocket, but WebSocket lives off main thread.
+ * Benefits: heartbeat timers and JSON parsing don't block UI rendering.
+ *
+ * Use when:
+ * - High message rate (50+ msgs/sec)
+ * - Heavy JSON payloads
+ * - UI does complex rendering that could block main thread
+ *
+ * Don't use when:
+ * - Low message rate (simple chat, notifications)
+ * - Bundle size matters (adds worker file)
+ * - Debugging (Worker DevTools is less convenient)
+ */
+export declare class WorkerSocket implements Disposable {
+    private url;
+    private options;
+    private worker;
+    private _state;
+    private onMessageFns;
+    private onStateChangeFns;
+    constructor(url: string, options?: {
+        protocols?: string[];
+        reconnect?: boolean;
+        reconnectMaxDelay?: number;
+        heartbeatInterval?: number;
+        sendBuffer?: number;
+        workerUrl?: string | URL;
+    });
+    get state(): SocketState;
+    connect(): void;
+    send(data: unknown): void;
+    disconnect(): void;
+    onMessage(fn: EventHandler): Unsubscribe;
+    onStateChange(fn: (state: SocketState) => void): Unsubscribe;
+    private createWorkerBlob;
+    [Symbol.dispose](): void;
+}

package/dist/adapters/react.d.ts

@@ -0,0 +1,79 @@
+import { type ReactNode } from 'react';
+import { SharedWebSocket } from '../SharedWebSocket';
+import type { SharedWebSocketOptions, TabRole } from '../types';
+/**
+ * Provider props — pass URL and options as props for flexibility.
+ *
+ * @example
+ * <SharedWebSocketProvider url="wss://api.example.com/ws" options={{ auth: getToken }}>
+ *   <App />
+ * </SharedWebSocketProvider>
+ */
+export interface SharedWebSocketProviderProps {
+    url: string;
+    options?: SharedWebSocketOptions;
+    children: ReactNode;
+}
+/**
+ * Provider component — creates SharedWebSocket from props, auto-disposes on unmount.
+ *
+ * @example
+ * function App() {
+ *   return (
+ *     <SharedWebSocketProvider
+ *       url="wss://api.example.com/ws"
+ *       options={{
+ *         auth: () => localStorage.getItem('token')!,
+ *         useWorker: true,
+ *       }}
+ *     >
+ *       <Dashboard />
+ *     </SharedWebSocketProvider>
+ *   );
+ * }
+ */
+export declare function SharedWebSocketProvider({ url, options, children }: SharedWebSocketProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SharedWebSocket | null>>;
+/**
+ * Access the SharedWebSocket instance from context.
+ *
+ * @example
+ * const ws = useSharedWebSocket();
+ * ws.send('chat.message', { text: 'Hello' });
+ */
+export declare function useSharedWebSocket(): SharedWebSocket;
+/**
+ * Subscribe to a WebSocket event. Returns the latest received value.
+ * Uses useEffectEvent for a stable callback ref — no stale closures.
+ *
+ * @example
+ * const order = useSocketEvent<Order>('order.created');
+ */
+export declare function useSocketEvent<T>(event: string): T | undefined;
+/**
+ * Accumulate WebSocket events into an array.
+ * Uses useEffectEvent — handler always sees latest state without re-subscribing.
+ *
+ * @example
+ * const messages = useSocketStream<ChatMessage>('chat.message');
+ */
+export declare function useSocketStream<T>(event: string): T[];
+/**
+ * Two-way state sync across browser tabs.
+ * Uses useEffectEvent for stable sync callback.
+ *
+ * @example
+ * const [cart, setCart] = useSocketSync<Cart>('cart', { items: [] });
+ * // setCart in one tab → updates all tabs instantly
+ */
+export declare function useSocketSync<T>(key: string, initialValue: T): [T, (value: T) => void];
+/**
+ * Reactive connection status.
+ * Uses useEffectEvent to avoid re-creating interval on state change.
+ *
+ * @example
+ * const { connected, tabRole } = useSocketStatus();
+ */
+export declare function useSocketStatus(): {
+    connected: boolean;
+    tabRole: TabRole;
+};