tab-bridge 0.2.0 → 0.3.0

package/README.md

@@ -26,7 +26,7 @@
 
 <br />
 
-[**Getting Started**](#-getting-started) · [**API**](#-api-reference) · [**React**](#%EF%B8%8F-react) · [**Architecture**](#-architecture) · [**Examples**](#-examples) · [**Live Demo**](https://serbi2012.github.io/tab-bridge/)
+[**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>
 
@@ -76,6 +76,9 @@ Intercept, validate, and transform state changes before they're applied
 #### 💾 State Persistence
 Survive page reloads with key whitelisting and custom storage backends
 
+#### 🐻 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
 
@@ -513,6 +516,180 @@ Components using only `useTabSyncActions` **never re-render** due to state chang
 
 <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 />
+
+---
+
+<br />
+
 ## 🚨 Error Handling
 
 Structured errors with error codes for precise `catch` handling:
@@ -641,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>
 

package/dist/index.d.cts

@@ -1,5 +1,7 @@
-import { R as RPCMap, T as TabSyncOptions, a as TabSyncInstance, C as ChangeMeta, b as TabInfo, c as RPCCallAllResult, M as Middleware, d as MiddlewareContext, P as PersistOptions } from './instance-5LIItazN.cjs';
-export { L as LeaderOptions, e as MiddlewareResult, f as RPCArgs, g as RPCResult } from './instance-5LIItazN.cjs';
+import { R as RPCMap, T as TabSyncInstance, C as ChangeMeta, a as TabInfo, b as RPCCallAllResult } from './instance-hvEUHx6i.cjs';
+export { c as RPCArgs, d as RPCResult } from './instance-hvEUHx6i.cjs';
+import { T as TabSyncOptions, M as Middleware, a as MiddlewareContext, P as PersistOptions } from './options-DmHyGTL0.cjs';
+export { L as LeaderOptions, b as MiddlewareResult } from './options-DmHyGTL0.cjs';
 
 declare const PROTOCOL_VERSION = 1;
 interface StateUpdatePayload {

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { R as RPCMap, T as TabSyncOptions, a as TabSyncInstance, C as ChangeMeta, b as TabInfo, c as RPCCallAllResult, M as Middleware, d as MiddlewareContext, P as PersistOptions } from './instance-5LIItazN.js';
-export { L as LeaderOptions, e as MiddlewareResult, f as RPCArgs, g as RPCResult } from './instance-5LIItazN.js';
+import { R as RPCMap, T as TabSyncInstance, C as ChangeMeta, a as TabInfo, b as RPCCallAllResult } from './instance-hvEUHx6i.js';
+export { c as RPCArgs, d as RPCResult } from './instance-hvEUHx6i.js';
+import { T as TabSyncOptions, M as Middleware, a as MiddlewareContext, P as PersistOptions } from './options-iN7Rnvwj.js';
+export { L as LeaderOptions, b as MiddlewareResult } from './options-iN7Rnvwj.js';
 
 declare const PROTOCOL_VERSION = 1;
 interface StateUpdatePayload {

package/dist/{instance-5LIItazN.d.cts → instance-hvEUHx6i.d.cts}

@@ -13,65 +13,6 @@ interface ChangeMeta {
     readonly timestamp: number;
 }
 
-interface MiddlewareContext<TState extends Record<string, unknown>> {
-    readonly key: keyof TState;
-    readonly value: unknown;
-    readonly previousValue: unknown;
-    readonly meta: ChangeMeta;
-}
-/**
- * Return `false` to reject the change, `{ value }` to transform it,
- * or `void`/`undefined` to pass through unchanged.
- */
-type MiddlewareResult = {
-    value: unknown;
-} | false;
-interface Middleware<TState extends Record<string, unknown> = Record<string, unknown>> {
-    readonly name: string;
-    /** Intercept local `set` / `patch` calls before they are applied. */
-    onSet?: (ctx: MiddlewareContext<TState>) => MiddlewareResult | void;
-    /** Called after any state change (local or remote) has been committed. */
-    afterChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
-    /** Cleanup when the instance is destroyed. */
-    onDestroy?: () => void;
-}
-
-interface PersistOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
-    /** Storage key. Default: `'tab-sync:state'` */
-    key?: string;
-    /** Only persist these keys (whitelist). */
-    include?: (keyof TState)[];
-    /** Exclude these keys from persistence (blacklist). */
-    exclude?: (keyof TState)[];
-    /** Custom serializer. Default: `JSON.stringify` */
-    serialize?: (state: Partial<TState>) => string;
-    /** Custom deserializer. Default: `JSON.parse` */
-    deserialize?: (raw: string) => Partial<TState>;
-    /** Debounce persistence writes in ms. Default: `100` */
-    debounce?: number;
-    /** Custom storage backend. Default: `localStorage` */
-    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
-    /**
-     * Schema version for state migration. When the persisted version
-     * differs from this value, `migrate` is called.
-     */
-    version?: number;
-    /**
-     * Migration function called when persisted version differs from current.
-     *
-     * ```ts
-     * persist: {
-     *   version: 2,
-     *   migrate: (oldState, oldVersion) => ({
-     *     ...oldState,
-     *     newField: oldVersion < 2 ? 'default' : oldState.newField,
-     *   }),
-     * }
-     * ```
-     */
-    migrate?: (oldState: Partial<TState>, oldVersion: number) => Partial<TState>;
-}
-
 /**
  * Define your RPC contract for full type inference:
  *
@@ -99,37 +40,6 @@ type RPCArgs<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMa
 /** Resolve result type for a method. Falls back to `unknown` for unregistered methods. */
 type RPCResult<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMap[M]['result'] : unknown;
 
-interface LeaderOptions {
-    /** Heartbeat interval in ms. Default: `2000` */
-    heartbeatInterval?: number;
-    /** Leader timeout in ms. Default: `6000` */
-    leaderTimeout?: number;
-}
-interface TabSyncOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
-    /** Initial state used before sync completes. */
-    initial?: TState;
-    /** Channel name — only tabs sharing the same name communicate. Default: `'tab-sync'` */
-    channel?: string;
-    /** Force a specific transport layer. Default: auto-detect. */
-    transport?: 'broadcast-channel' | 'local-storage';
-    /** Custom merge function for LWW conflict resolution. */
-    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
-    /** Enable leader election. Default: `true` */
-    leader?: boolean | LeaderOptions;
-    /** Heartbeat interval in ms. Default: `2000` */
-    heartbeatInterval?: number;
-    /** Leader timeout in ms. Default: `6000` */
-    leaderTimeout?: number;
-    /** Enable debug logging. Default: `false` */
-    debug?: boolean;
-    /** Persist state across page reloads. `true` uses defaults, or pass options. */
-    persist?: PersistOptions<TState> | boolean;
-    /** Middleware pipeline for intercepting state changes. */
-    middlewares?: Middleware<TState>[];
-    /** Error callback for non-fatal errors (storage, channel, etc.). */
-    onError?: (error: Error) => void;
-}
-
 interface TabSyncInstance<TState extends Record<string, unknown>, TRPCMap extends RPCMap = RPCMap> {
     /** Read a single value by key. */
     get<K extends keyof TState>(key: K): TState[K];
@@ -281,4 +191,4 @@ interface TabSyncInstance<TState extends Record<string, unknown>, TRPCMap extend
     readonly ready: boolean;
 }
 
-export type { ChangeMeta as C, LeaderOptions as L, Middleware as M, PersistOptions as P, RPCMap as R, TabSyncOptions as T, TabSyncInstance as a, TabInfo as b, RPCCallAllResult as c, MiddlewareContext as d, MiddlewareResult as e, RPCArgs as f, RPCResult as g };
+export type { ChangeMeta as C, RPCMap as R, TabSyncInstance as T, TabInfo as a, RPCCallAllResult as b, RPCArgs as c, RPCResult as d };

package/dist/{instance-5LIItazN.d.ts → instance-hvEUHx6i.d.ts}

@@ -13,65 +13,6 @@ interface ChangeMeta {
     readonly timestamp: number;
 }
 
-interface MiddlewareContext<TState extends Record<string, unknown>> {
-    readonly key: keyof TState;
-    readonly value: unknown;
-    readonly previousValue: unknown;
-    readonly meta: ChangeMeta;
-}
-/**
- * Return `false` to reject the change, `{ value }` to transform it,
- * or `void`/`undefined` to pass through unchanged.
- */
-type MiddlewareResult = {
-    value: unknown;
-} | false;
-interface Middleware<TState extends Record<string, unknown> = Record<string, unknown>> {
-    readonly name: string;
-    /** Intercept local `set` / `patch` calls before they are applied. */
-    onSet?: (ctx: MiddlewareContext<TState>) => MiddlewareResult | void;
-    /** Called after any state change (local or remote) has been committed. */
-    afterChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
-    /** Cleanup when the instance is destroyed. */
-    onDestroy?: () => void;
-}
-
-interface PersistOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
-    /** Storage key. Default: `'tab-sync:state'` */
-    key?: string;
-    /** Only persist these keys (whitelist). */
-    include?: (keyof TState)[];
-    /** Exclude these keys from persistence (blacklist). */
-    exclude?: (keyof TState)[];
-    /** Custom serializer. Default: `JSON.stringify` */
-    serialize?: (state: Partial<TState>) => string;
-    /** Custom deserializer. Default: `JSON.parse` */
-    deserialize?: (raw: string) => Partial<TState>;
-    /** Debounce persistence writes in ms. Default: `100` */
-    debounce?: number;
-    /** Custom storage backend. Default: `localStorage` */
-    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
-    /**
-     * Schema version for state migration. When the persisted version
-     * differs from this value, `migrate` is called.
-     */
-    version?: number;
-    /**
-     * Migration function called when persisted version differs from current.
-     *
-     * ```ts
-     * persist: {
-     *   version: 2,
-     *   migrate: (oldState, oldVersion) => ({
-     *     ...oldState,
-     *     newField: oldVersion < 2 ? 'default' : oldState.newField,
-     *   }),
-     * }
-     * ```
-     */
-    migrate?: (oldState: Partial<TState>, oldVersion: number) => Partial<TState>;
-}
-
 /**
  * Define your RPC contract for full type inference:
  *
@@ -99,37 +40,6 @@ type RPCArgs<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMa
 /** Resolve result type for a method. Falls back to `unknown` for unregistered methods. */
 type RPCResult<TMap extends RPCMap, M extends string> = M extends keyof TMap ? TMap[M]['result'] : unknown;
 
-interface LeaderOptions {
-    /** Heartbeat interval in ms. Default: `2000` */
-    heartbeatInterval?: number;
-    /** Leader timeout in ms. Default: `6000` */
-    leaderTimeout?: number;
-}
-interface TabSyncOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
-    /** Initial state used before sync completes. */
-    initial?: TState;
-    /** Channel name — only tabs sharing the same name communicate. Default: `'tab-sync'` */
-    channel?: string;
-    /** Force a specific transport layer. Default: auto-detect. */
-    transport?: 'broadcast-channel' | 'local-storage';
-    /** Custom merge function for LWW conflict resolution. */
-    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
-    /** Enable leader election. Default: `true` */
-    leader?: boolean | LeaderOptions;
-    /** Heartbeat interval in ms. Default: `2000` */
-    heartbeatInterval?: number;
-    /** Leader timeout in ms. Default: `6000` */
-    leaderTimeout?: number;
-    /** Enable debug logging. Default: `false` */
-    debug?: boolean;
-    /** Persist state across page reloads. `true` uses defaults, or pass options. */
-    persist?: PersistOptions<TState> | boolean;
-    /** Middleware pipeline for intercepting state changes. */
-    middlewares?: Middleware<TState>[];
-    /** Error callback for non-fatal errors (storage, channel, etc.). */
-    onError?: (error: Error) => void;
-}
-
 interface TabSyncInstance<TState extends Record<string, unknown>, TRPCMap extends RPCMap = RPCMap> {
     /** Read a single value by key. */
     get<K extends keyof TState>(key: K): TState[K];
@@ -281,4 +191,4 @@ interface TabSyncInstance<TState extends Record<string, unknown>, TRPCMap extend
     readonly ready: boolean;
 }
 
-export type { ChangeMeta as C, LeaderOptions as L, Middleware as M, PersistOptions as P, RPCMap as R, TabSyncOptions as T, TabSyncInstance as a, TabInfo as b, RPCCallAllResult as c, MiddlewareContext as d, MiddlewareResult as e, RPCArgs as f, RPCResult as g };
+export type { ChangeMeta as C, RPCMap as R, TabSyncInstance as T, TabInfo as a, RPCCallAllResult as b, RPCArgs as c, RPCResult as d };

package/dist/options-DmHyGTL0.d.cts

@@ -0,0 +1,93 @@
+import { C as ChangeMeta } from './instance-hvEUHx6i.cjs';
+
+interface MiddlewareContext<TState extends Record<string, unknown>> {
+    readonly key: keyof TState;
+    readonly value: unknown;
+    readonly previousValue: unknown;
+    readonly meta: ChangeMeta;
+}
+/**
+ * Return `false` to reject the change, `{ value }` to transform it,
+ * or `void`/`undefined` to pass through unchanged.
+ */
+type MiddlewareResult = {
+    value: unknown;
+} | false;
+interface Middleware<TState extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    /** Intercept local `set` / `patch` calls before they are applied. */
+    onSet?: (ctx: MiddlewareContext<TState>) => MiddlewareResult | void;
+    /** Called after any state change (local or remote) has been committed. */
+    afterChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
+    /** Cleanup when the instance is destroyed. */
+    onDestroy?: () => void;
+}
+
+interface PersistOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Storage key. Default: `'tab-sync:state'` */
+    key?: string;
+    /** Only persist these keys (whitelist). */
+    include?: (keyof TState)[];
+    /** Exclude these keys from persistence (blacklist). */
+    exclude?: (keyof TState)[];
+    /** Custom serializer. Default: `JSON.stringify` */
+    serialize?: (state: Partial<TState>) => string;
+    /** Custom deserializer. Default: `JSON.parse` */
+    deserialize?: (raw: string) => Partial<TState>;
+    /** Debounce persistence writes in ms. Default: `100` */
+    debounce?: number;
+    /** Custom storage backend. Default: `localStorage` */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+    /**
+     * Schema version for state migration. When the persisted version
+     * differs from this value, `migrate` is called.
+     */
+    version?: number;
+    /**
+     * Migration function called when persisted version differs from current.
+     *
+     * ```ts
+     * persist: {
+     *   version: 2,
+     *   migrate: (oldState, oldVersion) => ({
+     *     ...oldState,
+     *     newField: oldVersion < 2 ? 'default' : oldState.newField,
+     *   }),
+     * }
+     * ```
+     */
+    migrate?: (oldState: Partial<TState>, oldVersion: number) => Partial<TState>;
+}
+
+interface LeaderOptions {
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+}
+interface TabSyncOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Initial state used before sync completes. */
+    initial?: TState;
+    /** Channel name — only tabs sharing the same name communicate. Default: `'tab-sync'` */
+    channel?: string;
+    /** Force a specific transport layer. Default: auto-detect. */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Custom merge function for LWW conflict resolution. */
+    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
+    /** Enable leader election. Default: `true` */
+    leader?: boolean | LeaderOptions;
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+    /** Enable debug logging. Default: `false` */
+    debug?: boolean;
+    /** Persist state across page reloads. `true` uses defaults, or pass options. */
+    persist?: PersistOptions<TState> | boolean;
+    /** Middleware pipeline for intercepting state changes. */
+    middlewares?: Middleware<TState>[];
+    /** Error callback for non-fatal errors (storage, channel, etc.). */
+    onError?: (error: Error) => void;
+}
+
+export type { LeaderOptions as L, Middleware as M, PersistOptions as P, TabSyncOptions as T, MiddlewareContext as a, MiddlewareResult as b };

package/dist/options-iN7Rnvwj.d.ts

@@ -0,0 +1,93 @@
+import { C as ChangeMeta } from './instance-hvEUHx6i.js';
+
+interface MiddlewareContext<TState extends Record<string, unknown>> {
+    readonly key: keyof TState;
+    readonly value: unknown;
+    readonly previousValue: unknown;
+    readonly meta: ChangeMeta;
+}
+/**
+ * Return `false` to reject the change, `{ value }` to transform it,
+ * or `void`/`undefined` to pass through unchanged.
+ */
+type MiddlewareResult = {
+    value: unknown;
+} | false;
+interface Middleware<TState extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    /** Intercept local `set` / `patch` calls before they are applied. */
+    onSet?: (ctx: MiddlewareContext<TState>) => MiddlewareResult | void;
+    /** Called after any state change (local or remote) has been committed. */
+    afterChange?: (key: keyof TState, value: unknown, meta: ChangeMeta) => void;
+    /** Cleanup when the instance is destroyed. */
+    onDestroy?: () => void;
+}
+
+interface PersistOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Storage key. Default: `'tab-sync:state'` */
+    key?: string;
+    /** Only persist these keys (whitelist). */
+    include?: (keyof TState)[];
+    /** Exclude these keys from persistence (blacklist). */
+    exclude?: (keyof TState)[];
+    /** Custom serializer. Default: `JSON.stringify` */
+    serialize?: (state: Partial<TState>) => string;
+    /** Custom deserializer. Default: `JSON.parse` */
+    deserialize?: (raw: string) => Partial<TState>;
+    /** Debounce persistence writes in ms. Default: `100` */
+    debounce?: number;
+    /** Custom storage backend. Default: `localStorage` */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+    /**
+     * Schema version for state migration. When the persisted version
+     * differs from this value, `migrate` is called.
+     */
+    version?: number;
+    /**
+     * Migration function called when persisted version differs from current.
+     *
+     * ```ts
+     * persist: {
+     *   version: 2,
+     *   migrate: (oldState, oldVersion) => ({
+     *     ...oldState,
+     *     newField: oldVersion < 2 ? 'default' : oldState.newField,
+     *   }),
+     * }
+     * ```
+     */
+    migrate?: (oldState: Partial<TState>, oldVersion: number) => Partial<TState>;
+}
+
+interface LeaderOptions {
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+}
+interface TabSyncOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Initial state used before sync completes. */
+    initial?: TState;
+    /** Channel name — only tabs sharing the same name communicate. Default: `'tab-sync'` */
+    channel?: string;
+    /** Force a specific transport layer. Default: auto-detect. */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Custom merge function for LWW conflict resolution. */
+    merge?: (localValue: unknown, remoteValue: unknown, key: keyof TState) => unknown;
+    /** Enable leader election. Default: `true` */
+    leader?: boolean | LeaderOptions;
+    /** Heartbeat interval in ms. Default: `2000` */
+    heartbeatInterval?: number;
+    /** Leader timeout in ms. Default: `6000` */
+    leaderTimeout?: number;
+    /** Enable debug logging. Default: `false` */
+    debug?: boolean;
+    /** Persist state across page reloads. `true` uses defaults, or pass options. */
+    persist?: PersistOptions<TState> | boolean;
+    /** Middleware pipeline for intercepting state changes. */
+    middlewares?: Middleware<TState>[];
+    /** Error callback for non-fatal errors (storage, channel, etc.). */
+    onError?: (error: Error) => void;
+}
+
+export type { LeaderOptions as L, Middleware as M, PersistOptions as P, TabSyncOptions as T, MiddlewareContext as a, MiddlewareResult as b };

package/dist/react/index.d.cts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { T as TabSyncOptions, a as TabSyncInstance, R as RPCMap, b as TabInfo } from '../instance-5LIItazN.cjs';
+import { T as TabSyncOptions } from '../options-DmHyGTL0.cjs';
+import { T as TabSyncInstance, R as RPCMap, a as TabInfo } from '../instance-hvEUHx6i.cjs';
 
 interface TabSyncProviderProps<TState extends Record<string, unknown>> {
     options: TabSyncOptions<TState>;

package/dist/react/index.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { T as TabSyncOptions, a as TabSyncInstance, R as RPCMap, b as TabInfo } from '../instance-5LIItazN.js';
+import { T as TabSyncOptions } from '../options-iN7Rnvwj.js';
+import { T as TabSyncInstance, R as RPCMap, a as TabInfo } from '../instance-hvEUHx6i.js';
 
 interface TabSyncProviderProps<TState extends Record<string, unknown>> {
     options: TabSyncOptions<TState>;

package/dist/zustand/index.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+var chunkTGEXRVAL_cjs = require('../chunk-TGEXRVAL.cjs');
+
+// src/zustand/middleware.ts
+function shouldSyncKey(key, value, options) {
+  if (typeof value === "function") return false;
+  if (options?.include) return options.include.includes(key);
+  if (options?.exclude) return !options.exclude.includes(key);
+  return true;
+}
+function extractSyncableState(state, options) {
+  const result = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (shouldSyncKey(key, value, options)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function validateOptions(options) {
+  if (options?.include && options?.exclude) {
+    throw new Error(
+      "[tab-bridge/zustand] `include` and `exclude` are mutually exclusive"
+    );
+  }
+}
+var tabSyncImpl = (initializer, options) => (set, get, api) => {
+  validateOptions(options);
+  let sync_instance = null;
+  let is_remote_update = false;
+  const initial_state = initializer(set, get, api);
+  const syncable_initial = extractSyncableState(initial_state, options);
+  sync_instance = chunkTGEXRVAL_cjs.createTabSync({
+    initial: syncable_initial,
+    channel: options?.channel ?? "tab-sync-zustand",
+    debug: options?.debug,
+    transport: options?.transport,
+    merge: options?.merge,
+    onError: options?.onError
+  });
+  api.subscribe((next_state, prev_state) => {
+    if (is_remote_update || !sync_instance) return;
+    const next = next_state;
+    const prev = prev_state;
+    const diff = {};
+    let has_diff = false;
+    for (const key of Object.keys(next)) {
+      if (shouldSyncKey(key, next[key], options) && !Object.is(prev[key], next[key])) {
+        diff[key] = next[key];
+        has_diff = true;
+      }
+    }
+    if (has_diff) {
+      sync_instance.patch(diff);
+    }
+  });
+  sync_instance.onChange((remote_state, changed_keys, meta) => {
+    if (meta.isLocal) return;
+    is_remote_update = true;
+    try {
+      const patch = {};
+      let has_patch = false;
+      for (const key of changed_keys) {
+        patch[key] = remote_state[key];
+        has_patch = true;
+      }
+      if (has_patch) {
+        api.setState(patch);
+      }
+    } finally {
+      is_remote_update = false;
+    }
+  });
+  options?.onSyncReady?.(sync_instance);
+  return initial_state;
+};
+var tabSync = tabSyncImpl;
+
+exports.tabSync = tabSync;

package/dist/zustand/index.d.cts

@@ -0,0 +1,87 @@
+import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.cjs';
+
+/**
+ * Options for the `tabSync` Zustand middleware.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app', exclude: ['localOnly'] }
+ *   )
+ * );
+ * ```
+ */
+interface TabSyncZustandOptions<T = Record<string, unknown>> {
+    /** Channel name for cross-tab communication. @default 'tab-sync-zustand' */
+    channel?: string;
+    /**
+     * Only sync these keys. Functions are always excluded.
+     * Mutually exclusive with `exclude`.
+     */
+    include?: readonly (keyof T & string)[];
+    /**
+     * Exclude these keys from syncing. Functions are always excluded.
+     * Mutually exclusive with `include`.
+     */
+    exclude?: readonly (keyof T & string)[];
+    /**
+     * Custom conflict resolution.
+     * Called when the same key is updated on two tabs simultaneously.
+     * @default Last-write-wins (LWW)
+     */
+    merge?: (localValue: unknown, remoteValue: unknown, key: string) => unknown;
+    /** Force a specific transport layer. @default auto-detect */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+    /** Error callback for non-fatal errors (channel failures, etc.). */
+    onError?: (error: Error) => void;
+    /**
+     * Callback invoked when the underlying `TabSyncInstance` is ready.
+     * Use this to access advanced features (RPC, leader election, etc.)
+     * or to store a reference for manual cleanup via `instance.destroy()`.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type TabSyncMiddleware = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: TabSyncZustandOptions<T>) => StateCreator<T, Mps, Mcs>;
+/**
+ * Zustand middleware that synchronizes store state across browser tabs
+ * via tab-bridge's BroadcastChannel/localStorage transport.
+ *
+ * Functions (actions) are automatically excluded from synchronization.
+ * Use `include` or `exclude` options to further filter which keys are synced.
+ *
+ * @param initializer - Zustand StateCreator function.
+ * @param options - Synchronization options.
+ * @returns A wrapped StateCreator that synchronizes state across tabs.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app' }
+ *   )
+ * );
+ * // All tabs sharing channel 'my-app' will have synchronized state.
+ * ```
+ */
+declare const tabSync: TabSyncMiddleware;
+
+export { type TabSyncZustandOptions, tabSync };

package/dist/zustand/index.d.ts

@@ -0,0 +1,87 @@
+import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.js';
+
+/**
+ * Options for the `tabSync` Zustand middleware.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app', exclude: ['localOnly'] }
+ *   )
+ * );
+ * ```
+ */
+interface TabSyncZustandOptions<T = Record<string, unknown>> {
+    /** Channel name for cross-tab communication. @default 'tab-sync-zustand' */
+    channel?: string;
+    /**
+     * Only sync these keys. Functions are always excluded.
+     * Mutually exclusive with `exclude`.
+     */
+    include?: readonly (keyof T & string)[];
+    /**
+     * Exclude these keys from syncing. Functions are always excluded.
+     * Mutually exclusive with `include`.
+     */
+    exclude?: readonly (keyof T & string)[];
+    /**
+     * Custom conflict resolution.
+     * Called when the same key is updated on two tabs simultaneously.
+     * @default Last-write-wins (LWW)
+     */
+    merge?: (localValue: unknown, remoteValue: unknown, key: string) => unknown;
+    /** Force a specific transport layer. @default auto-detect */
+    transport?: 'broadcast-channel' | 'local-storage';
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+    /** Error callback for non-fatal errors (channel failures, etc.). */
+    onError?: (error: Error) => void;
+    /**
+     * Callback invoked when the underlying `TabSyncInstance` is ready.
+     * Use this to access advanced features (RPC, leader election, etc.)
+     * or to store a reference for manual cleanup via `instance.destroy()`.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type TabSyncMiddleware = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: TabSyncZustandOptions<T>) => StateCreator<T, Mps, Mcs>;
+/**
+ * Zustand middleware that synchronizes store state across browser tabs
+ * via tab-bridge's BroadcastChannel/localStorage transport.
+ *
+ * Functions (actions) are automatically excluded from synchronization.
+ * Use `include` or `exclude` options to further filter which keys are synced.
+ *
+ * @param initializer - Zustand StateCreator function.
+ * @param options - Synchronization options.
+ * @returns A wrapped StateCreator that synchronizes state across tabs.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'zustand';
+ * import { tabSync } from 'tab-bridge/zustand';
+ *
+ * const useStore = create(
+ *   tabSync(
+ *     (set) => ({
+ *       count: 0,
+ *       inc: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { channel: 'my-app' }
+ *   )
+ * );
+ * // All tabs sharing channel 'my-app' will have synchronized state.
+ * ```
+ */
+declare const tabSync: TabSyncMiddleware;
+
+export { type TabSyncZustandOptions, tabSync };

package/dist/zustand/index.js

@@ -0,0 +1,78 @@
+import { createTabSync } from '../chunk-4JDWAUYM.js';
+
+// src/zustand/middleware.ts
+function shouldSyncKey(key, value, options) {
+  if (typeof value === "function") return false;
+  if (options?.include) return options.include.includes(key);
+  if (options?.exclude) return !options.exclude.includes(key);
+  return true;
+}
+function extractSyncableState(state, options) {
+  const result = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (shouldSyncKey(key, value, options)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function validateOptions(options) {
+  if (options?.include && options?.exclude) {
+    throw new Error(
+      "[tab-bridge/zustand] `include` and `exclude` are mutually exclusive"
+    );
+  }
+}
+var tabSyncImpl = (initializer, options) => (set, get, api) => {
+  validateOptions(options);
+  let sync_instance = null;
+  let is_remote_update = false;
+  const initial_state = initializer(set, get, api);
+  const syncable_initial = extractSyncableState(initial_state, options);
+  sync_instance = createTabSync({
+    initial: syncable_initial,
+    channel: options?.channel ?? "tab-sync-zustand",
+    debug: options?.debug,
+    transport: options?.transport,
+    merge: options?.merge,
+    onError: options?.onError
+  });
+  api.subscribe((next_state, prev_state) => {
+    if (is_remote_update || !sync_instance) return;
+    const next = next_state;
+    const prev = prev_state;
+    const diff = {};
+    let has_diff = false;
+    for (const key of Object.keys(next)) {
+      if (shouldSyncKey(key, next[key], options) && !Object.is(prev[key], next[key])) {
+        diff[key] = next[key];
+        has_diff = true;
+      }
+    }
+    if (has_diff) {
+      sync_instance.patch(diff);
+    }
+  });
+  sync_instance.onChange((remote_state, changed_keys, meta) => {
+    if (meta.isLocal) return;
+    is_remote_update = true;
+    try {
+      const patch = {};
+      let has_patch = false;
+      for (const key of changed_keys) {
+        patch[key] = remote_state[key];
+        has_patch = true;
+      }
+      if (has_patch) {
+        api.setState(patch);
+      }
+    } finally {
+      is_remote_update = false;
+    }
+  });
+  options?.onSyncReady?.(sync_instance);
+  return initial_state;
+};
+var tabSync = tabSyncImpl;
+
+export { tabSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tab-bridge",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Zero-dependency TypeScript library for real-time state synchronization across browser tabs, with leader election and cross-tab RPC",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,6 +26,16 @@
         "types": "./dist/react/index.d.cts",
         "default": "./dist/react/index.cjs"
       }
+    },
+    "./zustand": {
+      "import": {
+        "types": "./dist/zustand/index.d.ts",
+        "default": "./dist/zustand/index.js"
+      },
+      "require": {
+        "types": "./dist/zustand/index.d.cts",
+        "default": "./dist/zustand/index.cjs"
+      }
     }
   },
   "files": [
@@ -70,11 +80,15 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "react": ">=18.0.0"
+    "react": ">=18.0.0",
+    "zustand": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "zustand": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -86,6 +100,7 @@
     "react-dom": "^19.2.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "zustand": "^5.0.11"
   }
 }