tab-bridge 0.1.1 → 0.3.0

package/README.md

@@ -17,8 +17,8 @@
 [![npm version](https://img.shields.io/npm/v/tab-bridge?style=for-the-badge&color=cb3837&label=npm&logo=npm&logoColor=white)](https://www.npmjs.com/package/tab-bridge)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/tab-bridge?style=for-the-badge&color=6ead0a&label=size&logo=webpack&logoColor=white)](https://bundlephobia.com/package/tab-bridge)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178c6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![license](https://img.shields.io/github/license/serbi2012/tab-sync?style=for-the-badge&color=blue&logo=open-source-initiative&logoColor=white)](./LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/serbi2012/tab-sync?style=for-the-badge&color=yellow&logo=github&logoColor=white)](https://github.com/serbi2012/tab-sync)
+[![license](https://img.shields.io/github/license/serbi2012/tab-bridge?style=for-the-badge&color=blue&logo=open-source-initiative&logoColor=white)](./LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/serbi2012/tab-bridge?style=for-the-badge&color=yellow&logo=github&logoColor=white)](https://github.com/serbi2012/tab-bridge)
 
 <br />
 
@@ -26,7 +26,7 @@
 
 <br />
 
-[**Getting Started**](#-getting-started) · [**API**](#-api-reference) · [**React**](#%EF%B8%8F-react) · [**Architecture**](#-architecture) · [**Examples**](#-examples)
+[**Getting Started**](#-getting-started) · [**API**](#-api-reference) · [**React**](#%EF%B8%8F-react) · [**Zustand**](#-zustand) · [**Next.js**](#-nextjs) · [**Architecture**](#-architecture) · [**Examples**](#-examples) · [**Live Demo**](https://serbi2012.github.io/tab-bridge/)
 
 </div>
 
@@ -59,22 +59,25 @@ LWW conflict resolution with batched broadcasts and custom merge strategies
 Bully algorithm with heartbeat monitoring and automatic failover
 
 #### 📡 Cross-Tab RPC
-Fully typed arguments, Promise-based calls with timeout handling
+Fully typed arguments, Promise-based calls with `callAll` broadcast support
 
-#### ⚛️ React Hooks
-Built on `useSyncExternalStore` for zero-tear concurrent rendering
+#### 🔄 Atomic Transactions
+`transaction()` for safe multi-key updates with abort support
 
 </td>
 <td width="50%" valign="top">
 
+#### ⚛️ React Hooks
+7 hooks built on `useSyncExternalStore` — zero-tear concurrent rendering
+
 #### 🛡️ Middleware Pipeline
 Intercept, validate, and transform state changes before they're applied
 
 #### 💾 State Persistence
 Survive page reloads with key whitelisting and custom storage backends
 
-#### 🔒 End-to-End Type Safety
-Discriminated unions, full type inference, and generic constraints
+#### 🐻 Zustand Middleware
+One-line integration — `tabSync()` wraps any Zustand store for cross-tab sync
 
 #### 📦 Zero Dependencies
 Native browser APIs only, ~4KB gzipped, fully tree-shakable
@@ -175,6 +178,12 @@ sync.get('theme')                       // Read single key
 sync.getAll()                           // Read full state (stable reference)
 sync.set('theme', 'dark')              // Write single key → broadcasts to all tabs
 sync.patch({ theme: 'dark', count: 5 }) // Write multiple keys in one broadcast
+
+// Atomic multi-key update — return null to abort
+sync.transaction((state) => {
+  if (state.count >= 100) return null;  // abort
+  return { count: state.count + 1, lastUpdated: Date.now() };
+});
 ```
 
 </details>
@@ -196,6 +205,13 @@ sync.select(
   (state) => state.items.filter(i => i.done).length,
   (doneCount) => updateBadge(doneCount),
 );
+
+// Debounced derived state — callback fires at most once per 200ms
+sync.select(
+  (state) => state.items.length,
+  (count) => analytics.track('item_count', count),
+  { debounce: 200 },
+);
 ```
 
 </details>
@@ -248,6 +264,10 @@ sync.handle('getServerTime', () => ({
 
 const { iso } = await sync.call('leader', 'getServerTime');
 const result  = await sync.call(tabId, 'compute', payload, 10_000);
+
+// Broadcast RPC to ALL other tabs and collect responses
+const results = await sync.callAll('getStatus');
+// results: Array<{ tabId: string; result?: T; error?: string }>
 ```
 
 </details>
@@ -359,7 +379,8 @@ First-class React integration built on `useSyncExternalStore` for **zero-tear co
 
 ```tsx
 import {
-  TabSyncProvider, useTabSync, useTabSyncValue, useTabSyncSelector, useIsLeader,
+  TabSyncProvider, useTabSync, useTabSyncValue, useTabSyncSelector,
+  useIsLeader, useTabs, useLeaderInfo, useTabSyncActions,
 } from 'tab-bridge/react';
 ```
 
@@ -444,6 +465,225 @@ function LeaderIndicator() {
 
 </details>
 
+<details open>
+<summary><b><code>useTabs()</code> — Active tab list</b></summary>
+
+<br />
+
+```tsx
+function TabList() {
+  const tabs = useTabs();
+  return <p>{tabs.length} tab(s) open</p>;
+}
+```
+
+</details>
+
+<details open>
+<summary><b><code>useLeaderInfo()</code> — Leader tab info</b></summary>
+
+<br />
+
+```tsx
+function LeaderDisplay() {
+  const leader = useLeaderInfo();
+  if (!leader) return <p>No leader yet</p>;
+  return <p>Leader: {leader.id}</p>;
+}
+```
+
+</details>
+
+<details open>
+<summary><b><code>useTabSyncActions()</code> — Write-only (no re-renders)</b></summary>
+
+<br />
+
+```tsx
+function IncrementButton() {
+  const { set, patch, transaction } = useTabSyncActions<MyState>();
+  return <button onClick={() => set('count', prev => prev + 1)}>+1</button>;
+}
+```
+
+Components using only `useTabSyncActions` **never re-render** due to state changes — perfect for write-only controls.
+
+</details>
+
+<br />
+
+---
+
+<br />
+
+## 🐻 Zustand
+
+One-line integration for [Zustand](https://github.com/pmndrs/zustand) stores — all tabs stay in sync automatically.
+
+```bash
+npm install zustand
+```
+
+```ts
+import { create } from 'zustand';
+import { tabSync } from 'tab-bridge/zustand';
+
+const useStore = create(
+  tabSync(
+    (set) => ({
+      count: 0,
+      theme: 'light',
+      inc: () => set((s) => ({ count: s.count + 1 })),
+      setTheme: (t: string) => set({ theme: t }),
+    }),
+    { channel: 'my-app' }
+  )
+);
+
+// That's it — all tabs now share the same state.
+// Functions (actions) are never synced, only data.
+```
+
+<details open>
+<summary><b>📋 Middleware Options</b></summary>
+
+<br />
+
+| Option | Type | Default | Description |
+|:-------|:-----|:--------|:------------|
+| `channel` | `string` | `'tab-sync-zustand'` | Channel name for cross-tab communication |
+| `include` | `string[]` | — | Only sync these keys (mutually exclusive with `exclude`) |
+| `exclude` | `string[]` | — | Exclude these keys from syncing (mutually exclusive with `include`) |
+| `merge` | `(local, remote, key) => value` | LWW | Custom conflict resolution |
+| `transport` | `'broadcast-channel'` \| `'local-storage'` | auto | Force a specific transport |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `onError` | `(error) => void` | — | Error callback |
+| `onSyncReady` | `(instance) => void` | — | Access the underlying `TabSyncInstance` for RPC/leader features |
+
+</details>
+
+<details>
+<summary><b>🔑 Selective Key Sync</b></summary>
+
+<br />
+
+```ts
+const useStore = create(
+  tabSync(
+    (set) => ({
+      count: 0,
+      theme: 'light',
+      localDraft: '',       // won't be synced
+      inc: () => set((s) => ({ count: s.count + 1 })),
+    }),
+    {
+      channel: 'my-app',
+      exclude: ['localDraft'],   // keep this key local-only
+    }
+  )
+);
+```
+
+</details>
+
+<details>
+<summary><b>🤝 Works with Zustand <code>persist</code></b></summary>
+
+<br />
+
+Compose with Zustand's `persist` middleware — order doesn't matter:
+
+```ts
+import { persist } from 'zustand/middleware';
+
+const useStore = create(
+  persist(
+    tabSync(
+      (set) => ({
+        count: 0,
+        inc: () => set((s) => ({ count: s.count + 1 })),
+      }),
+      { channel: 'my-app' }
+    ),
+    { name: 'my-store' }
+  )
+);
+```
+
+</details>
+
+<details>
+<summary><b>🚀 Advanced: Access tab-bridge Instance</b></summary>
+
+<br />
+
+Use `onSyncReady` to access the underlying `TabSyncInstance` for RPC, leader election, and other advanced features:
+
+```ts
+let syncInstance: TabSyncInstance | null = null;
+
+const useStore = create(
+  tabSync(
+    (set) => ({ count: 0 }),
+    {
+      channel: 'my-app',
+      onSyncReady: (instance) => {
+        syncInstance = instance;
+
+        instance.handle('getCount', () => useStore.getState().count);
+
+        instance.onLeader(() => {
+          console.log('This tab is now the leader');
+          return () => console.log('Leadership lost');
+        });
+      },
+    }
+  )
+);
+```
+
+</details>
+
+<br />
+
+---
+
+<br />
+
+## 📘 Next.js
+
+Using tab-bridge with **Next.js App Router**? Since tab-bridge relies on browser APIs, all usage must be in Client Components.
+
+```tsx
+// app/providers/tab-sync-provider.tsx
+'use client';
+
+import { TabSyncProvider } from 'tab-bridge/react';
+
+export function AppTabSyncProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <TabSyncProvider options={{ initial: { count: 0 }, channel: 'my-app' }}>
+      {children}
+    </TabSyncProvider>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx
+import { AppTabSyncProvider } from './providers/tab-sync-provider';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html><body>
+      <AppTabSyncProvider>{children}</AppTabSyncProvider>
+    </body></html>
+  );
+}
+```
+
+> **Full guide**: See [`docs/NEXTJS.md`](./docs/NEXTJS.md) for SSR safety patterns, hydration mismatch prevention, `useEffect` initialization, and Zustand integration with Next.js.
+
 <br />
 
 ---
@@ -578,6 +818,19 @@ import {
 
 ## 💡 Examples
 
+### 🎯 Interactive Demos
+
+Try these demos live — open multiple tabs to see real-time synchronization in action:
+
+| Demo | Description | Features |
+|:-----|:-----------|:---------|
+| [**Collaborative Editor**](https://serbi2012.github.io/tab-bridge/collaborative-editor.html) | Multi-tab real-time text editing | State Sync, Typing Indicators |
+| [**Shopping Cart**](https://serbi2012.github.io/tab-bridge/shopping-cart.html) | Cart synced across all tabs + persistent | State Sync, Persistence |
+| [**Leader Dashboard**](https://serbi2012.github.io/tab-bridge/leader-dashboard.html) | Only leader fetches data, followers use RPC | Leader Election, RPC, callAll |
+| [**Full Feature Demo**](https://serbi2012.github.io/tab-bridge/) | All features in one page | Everything |
+
+### Code Examples
+
 <details>
 <summary><b>🔐 Shared Authentication State</b></summary>
 
@@ -725,7 +978,7 @@ MIT © [serbi2012](https://github.com/serbi2012)
 
 <br />
 
-<a href="https://github.com/serbi2012/tab-sync">
+<a href="https://github.com/serbi2012/tab-bridge">
   <img src="https://img.shields.io/badge/GitHub-tab--bridge-4f46e5?style=for-the-badge&logo=github&logoColor=white" alt="GitHub" />
 </a>
 &nbsp;