tab-bridge 0.1.0 → 0.2.0

package/README.md

@@ -17,25 +17,16 @@
 [![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 />
 
-```mermaid
-graph LR
-    A["<b>Tab A</b><br/>👑 Leader"] <-->|"realtime sync"| B["<b>Tab B</b><br/>Follower"]
-    B <-->|"realtime sync"| C["<b>Tab C</b><br/>Follower"]
-    A <-->|"realtime sync"| C
-
-    style A fill:#4f46e5,stroke:#4338ca,color:#fff,stroke-width:2px
-    style B fill:#6366f1,stroke:#4f46e5,color:#fff,stroke-width:2px
-    style C fill:#6366f1,stroke:#4f46e5,color:#fff,stroke-width:2px
-```
+<img src="https://mermaid.ink/img/Z3JhcGggTFIKICAgIEFbIlRhYiBBXG7wn5GRIExlYWRlciJdIDwtLT58InJlYWx0aW1lIHN5bmMifCBCWyJUYWIgQlxuRm9sbG93ZXIiXQogICAgQiA8LS0-fCJyZWFsdGltZSBzeW5jInwgQ1siVGFiIENcbkZvbGxvd2VyIl0KICAgIEEgPC0tPnwicmVhbHRpbWUgc3luYyJ8IEMKICAgIHN0eWxlIEEgZmlsbDojNGY0NmU1LHN0cm9rZTojNDMzOGNhLGNvbG9yOiNmZmYsc3Ryb2tlLXdpZHRoOjJweAogICAgc3R5bGUgQiBmaWxsOiM2MzY2ZjEsc3Ryb2tlOiM0ZjQ2ZTUsY29sb3I6I2ZmZixzdHJva2Utd2lkdGg6MnB4CiAgICBzdHlsZSBDIGZpbGw6IzYzNjZmMSxzdHJva2U6IzRmNDZlNSxjb2xvcjojZmZmLHN0cm9rZS13aWR0aDoycHg?theme=dark&bgColor=0d1117" alt="tab-bridge sync diagram" />
 
 <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) · [**Architecture**](#-architecture) · [**Examples**](#-examples) · [**Live Demo**](https://serbi2012.github.io/tab-bridge/)
 
 </div>
 
@@ -68,23 +59,23 @@ 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
-
 #### 📦 Zero Dependencies
 Native browser APIs only, ~4KB gzipped, fully tree-shakable
 
@@ -184,6 +175,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>
@@ -205,6 +202,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>
@@ -257,6 +261,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>
@@ -328,19 +336,7 @@ const sync = createTabSync({
 });
 ```
 
-```mermaid
-graph LR
-    A["set('age', -5)"] --> B{Middleware<br/>Pipeline}
-    B -->|"age < 0 → reject"| C["❌ Blocked"]
-    D["set('name', '  Alice  ')"] --> B
-    B -->|"trim()"| E["✅ 'Alice'"]
-
-    style A fill:#f59e0b,stroke:#d97706,color:#fff
-    style D fill:#f59e0b,stroke:#d97706,color:#fff
-    style B fill:#6366f1,stroke:#4f46e5,color:#fff
-    style C fill:#ef4444,stroke:#dc2626,color:#fff
-    style E fill:#22c55e,stroke:#16a34a,color:#fff
-```
+<img src="https://mermaid.ink/img/Z3JhcGggTFIKICAgIEFbInNldChhZ2UsIC01KSJdIC0tPiBCe01pZGRsZXdhcmUgUGlwZWxpbmV9CiAgICBCIC0tPnwiYWdlIDwgMCByZWplY3QifCBDWyJCbG9ja2VkIl0KICAgIERbInNldChuYW1lLCBBbGljZSkiXSAtLT4gQgogICAgQiAtLT58InRyaW0ifCBFWyJBbGljZSJdCiAgICBzdHlsZSBBIGZpbGw6I2Y1OWUwYixzdHJva2U6I2Q5NzcwNixjb2xvcjojZmZmCiAgICBzdHlsZSBEIGZpbGw6I2Y1OWUwYixzdHJva2U6I2Q5NzcwNixjb2xvcjojZmZmCiAgICBzdHlsZSBCIGZpbGw6IzYzNjZmMSxzdHJva2U6IzRmNDZlNSxjb2xvcjojZmZmCiAgICBzdHlsZSBDIGZpbGw6I2VmNDQ0NCxzdHJva2U6I2RjMjYyNixjb2xvcjojZmZmCiAgICBzdHlsZSBFIGZpbGw6IzIyYzU1ZSxzdHJva2U6IzE2YTM0YSxjb2xvcjojZmZm?theme=dark&bgColor=0d1117" alt="middleware pipeline diagram" />
 
 <br />
 
@@ -380,7 +376,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';
 ```
 
@@ -465,6 +462,51 @@ 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 />
 
 ---
@@ -505,42 +547,7 @@ createTabSync({ onError: (err) => Sentry.captureException(err) });
 
 <div align="center">
 
-```mermaid
-graph TB
-    subgraph API["🔌 Public API — createTabSync()"]
-        SM["📊 State Manager<br/><i>get / set / patch / subscribe</i>"]
-        LE["👑 Leader Election<br/><i>heartbeat / failover / resign</i>"]
-        RPC["📡 RPC Handler<br/><i>call / handle / timeout</i>"]
-    end
-
-    subgraph CORE["⚙️ Core Layer"]
-        TR["📋 Tab Registry<br/><i>tracks all active tabs</i>"]
-        MW["🛡️ Middleware Pipeline<br/><i>intercept → validate → transform → apply</i>"]
-    end
-
-    subgraph TRANSPORT["📡 Transport Layer — auto-detect"]
-        BC["⚡ BroadcastChannel<br/><i>primary, fast</i>"]
-        LS["💾 localStorage<br/><i>fallback</i>"]
-    end
-
-    SM --> TR
-    LE --> TR
-    RPC --> TR
-    TR --> MW
-    MW --> BC
-    MW --> LS
-
-    style API fill:#4f46e5,stroke:#4338ca,color:#fff,stroke-width:2px
-    style CORE fill:#7c3aed,stroke:#6d28d9,color:#fff,stroke-width:2px
-    style TRANSPORT fill:#2563eb,stroke:#1d4ed8,color:#fff,stroke-width:2px
-    style SM fill:#6366f1,stroke:#4f46e5,color:#fff
-    style LE fill:#6366f1,stroke:#4f46e5,color:#fff
-    style RPC fill:#6366f1,stroke:#4f46e5,color:#fff
-    style TR fill:#8b5cf6,stroke:#7c3aed,color:#fff
-    style MW fill:#8b5cf6,stroke:#7c3aed,color:#fff
-    style BC fill:#3b82f6,stroke:#2563eb,color:#fff
-    style LS fill:#3b82f6,stroke:#2563eb,color:#fff
-```
+<img src="https://mermaid.ink/img/Z3JhcGggVEIKICAgIHN1YmdyYXBoIEFQSVsiUHVibGljIEFQSSAtIGNyZWF0ZVRhYlN5bmMiXQogICAgICAgIFNNWyJTdGF0ZSBNYW5hZ2VyIl0KICAgICAgICBMRVsiTGVhZGVyIEVsZWN0aW9uIl0KICAgICAgICBSUENbIlJQQyBIYW5kbGVyIl0KICAgIGVuZAogICAgc3ViZ3JhcGggQ09SRVsiQ29yZSBMYXllciJdCiAgICAgICAgVFJbIlRhYiBSZWdpc3RyeSJdCiAgICAgICAgTVdbIk1pZGRsZXdhcmUgUGlwZWxpbmUiXQogICAgZW5kCiAgICBzdWJncmFwaCBUUkFOU1BPUlRbIlRyYW5zcG9ydCBMYXllciJdCiAgICAgICAgQkNbIkJyb2FkY2FzdENoYW5uZWwiXQogICAgICAgIExTWyJsb2NhbFN0b3JhZ2UiXQogICAgZW5kCiAgICBTTSAtLT4gVFIKICAgIExFIC0tPiBUUgogICAgUlBDIC0tPiBUUgogICAgVFIgLS0-IE1XCiAgICBNVyAtLT4gQkMKICAgIE1XIC0tPiBMUwogICAgc3R5bGUgQVBJIGZpbGw6IzRmNDZlNSxzdHJva2U6IzQzMzhjYSxjb2xvcjojZmZmLHN0cm9rZS13aWR0aDoycHgKICAgIHN0eWxlIENPUkUgZmlsbDojN2MzYWVkLHN0cm9rZTojNmQyOGQ5LGNvbG9yOiNmZmYsc3Ryb2tlLXdpZHRoOjJweAogICAgc3R5bGUgVFJBTlNQT1JUIGZpbGw6IzI1NjNlYixzdHJva2U6IzFkNGVkOCxjb2xvcjojZmZmLHN0cm9rZS13aWR0aDoycHg?theme=dark&bgColor=0d1117" alt="architecture diagram" />
 
 </div>
 
@@ -548,40 +555,11 @@ graph TB
 
 ### How State Sync Works
 
-```mermaid
-sequenceDiagram
-    participant A as Tab A (Leader 👑)
-    participant BC as BroadcastChannel
-    participant B as Tab B
-    participant C as Tab C
-
-    A->>A: set('theme', 'dark')
-    Note over A: Local state updated instantly
-    A->>BC: STATE_UPDATE { theme: 'dark' }
-    BC-->>B: 
-    BC-->>C: 
-    B->>B: Apply state + notify subscribers
-    C->>C: Apply state + notify subscribers
-```
+<img src="https://mermaid.ink/img/c2VxdWVuY2VEaWFncmFtCiAgICBwYXJ0aWNpcGFudCBBIGFzIFRhYiBBIExlYWRlcgogICAgcGFydGljaXBhbnQgQkMgYXMgQnJvYWRjYXN0Q2hhbm5lbAogICAgcGFydGljaXBhbnQgQiBhcyBUYWIgQgogICAgcGFydGljaXBhbnQgQyBhcyBUYWIgQwogICAgQS0-PkE6IHNldCB0aGVtZSBkYXJrCiAgICBOb3RlIG92ZXIgQTogTG9jYWwgc3RhdGUgdXBkYXRlZAogICAgQS0-PkJDOiBTVEFURV9VUERBVEUKICAgIEJDLS0-PkI6IG1lc3NhZ2UKICAgIEJDLS0-PkM6IG1lc3NhZ2UKICAgIEItPj5COiBBcHBseSArIG5vdGlmeQogICAgQy0-PkM6IEFwcGx5ICsgbm90aWZ5?theme=dark&bgColor=0d1117" alt="state sync sequence diagram" />
 
 ### How Leader Election Works
 
-```mermaid
-sequenceDiagram
-    participant A as Tab A (oldest)
-    participant B as Tab B
-    participant C as Tab C (newest)
-
-    Note over A,C: Leader (Tab A) closes...
-    A--xB: ❌ Heartbeat stops
-    B->>B: 3 missed heartbeats → leader dead
-    B->>C: LEADER_CLAIM
-    C->>C: Tab B is older → yield
-    Note over B: Waits 300ms for higher-priority claims
-    B->>C: LEADER_ACK
-    Note over B: 👑 Tab B is now leader
-    B->>C: LEADER_HEARTBEAT (every 2s)
-```
+<img src="https://mermaid.ink/img/c2VxdWVuY2VEaWFncmFtCiAgICBwYXJ0aWNpcGFudCBBIGFzIFRhYiBBIG9sZGVzdAogICAgcGFydGljaXBhbnQgQiBhcyBUYWIgQgogICAgcGFydGljaXBhbnQgQyBhcyBUYWIgQyBuZXdlc3QKICAgIE5vdGUgb3ZlciBBLEM6IExlYWRlciBUYWIgQSBjbG9zZXMKICAgIEItPj5COiAzIG1pc3NlZCBoZWFydGJlYXRzCiAgICBCLT4-QzogTEVBREVSX0NMQUlNCiAgICBDLT4-QzogVGFiIEIgaXMgb2xkZXIgeWllbGQKICAgIE5vdGUgb3ZlciBCOiBXYWl0IDMwMG1zCiAgICBCLT4-QzogTEVBREVSX0FDSwogICAgTm90ZSBvdmVyIEI6IFRhYiBCIGlzIG5vdyBsZWFkZXIKICAgIEItPj5DOiBMRUFERVJfSEVBUlRCRUFU?theme=dark&bgColor=0d1117" alt="leader election sequence diagram" />
 
 <br />
 
@@ -692,17 +670,7 @@ function logout() {
 
 <br />
 
-```mermaid
-graph LR
-    Server["🖥️ Server"] <-->|WebSocket| A["Tab A<br/>👑 Leader"]
-    A -->|"state sync"| B["Tab B"]
-    A -->|"state sync"| C["Tab C"]
-
-    style Server fill:#059669,stroke:#047857,color:#fff
-    style A fill:#4f46e5,stroke:#4338ca,color:#fff
-    style B fill:#6366f1,stroke:#4f46e5,color:#fff
-    style C fill:#6366f1,stroke:#4f46e5,color:#fff
-```
+<img src="https://mermaid.ink/img/Z3JhcGggTFIKICAgIFNlcnZlclsiU2VydmVyIl0gPC0tPnxXZWJTb2NrZXR8IEFbIlRhYiBBIExlYWRlciJdCiAgICBBIC0tPnxzdGF0ZSBzeW5jfCBCWyJUYWIgQiJdCiAgICBBIC0tPnxzdGF0ZSBzeW5jfCBDWyJUYWIgQyJdCiAgICBzdHlsZSBTZXJ2ZXIgZmlsbDojMDU5NjY5LHN0cm9rZTojMDQ3ODU3LGNvbG9yOiNmZmYKICAgIHN0eWxlIEEgZmlsbDojNGY0NmU1LHN0cm9rZTojNDMzOGNhLGNvbG9yOiNmZmYKICAgIHN0eWxlIEIgZmlsbDojNjM2NmYxLHN0cm9rZTojNGY0NmU1LGNvbG9yOiNmZmYKICAgIHN0eWxlIEMgZmlsbDojNjM2NmYxLHN0cm9rZTojNGY0NmU1LGNvbG9yOiNmZmY?theme=dark&bgColor=0d1117" alt="websocket leader pattern diagram" />
 
 ```ts
 const sync = createTabSync({
@@ -820,7 +788,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;