tab-bridge 0.3.0 → 0.4.0

package/README.md

@@ -26,7 +26,7 @@
 
 <br />
 
-[**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/)
+[**Getting Started**](#-getting-started) · [**API**](#-api-reference) · [**React**](#%EF%B8%8F-react) · [**Zustand**](#-zustand) · [**Jotai**](#-jotai) · [**Redux**](#-redux) · [**DevTools**](#-devtools) · [**Next.js**](#-nextjs) · [**Architecture**](#-architecture) · [**Examples**](#-examples) · [**Live Demo**](https://serbi2012.github.io/tab-bridge/)
 
 </div>
 
@@ -76,8 +76,11 @@ 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
+#### 🐻 Zustand / Jotai / Redux
+First-class integrations — `tabSync`, `atomWithTabSync`, `tabSyncEnhancer`
+
+#### 🔧 DevTools Panel
+Floating `<TabSyncDevTools />` with state inspection, tab list, and event log
 
 #### 📦 Zero Dependencies
 Native browser APIs only, ~4KB gzipped, fully tree-shakable
@@ -650,6 +653,152 @@ const useStore = create(
 
 <br />
 
+## 🧪 Jotai
+
+Synchronize individual [Jotai](https://jotai.org) atoms across browser tabs with zero boilerplate.
+
+```bash
+npm install tab-bridge jotai
+```
+
+### Quick Start
+
+```ts
+import { atomWithTabSync } from 'tab-bridge/jotai';
+
+const countAtom = atomWithTabSync('count', 0, { channel: 'my-app' });
+const themeAtom = atomWithTabSync('theme', 'light', { channel: 'my-app' });
+```
+
+Use them like regular atoms — `useAtom(countAtom)` works as expected. Changes are automatically synced to all tabs.
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `channel` | `string` | `'tab-sync-jotai'` | Channel name for cross-tab communication |
+| `transport` | `'broadcast-channel' \| 'local-storage'` | auto-detect | Force a specific transport |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `onError` | `(error: Error) => void` | — | Error callback |
+| `onSyncReady` | `(instance: TabSyncInstance) => void` | — | Access underlying instance |
+
+### How It Works
+
+Each atom creates its own `createTabSync` instance scoped to `${channel}:${key}`. The instance is created when the atom is first subscribed to and destroyed when the last subscriber unmounts.
+
+### Derived Atoms
+
+Derived atoms work out of the box:
+
+```ts
+import { atom } from 'jotai';
+
+const doubledAtom = atom((get) => get(countAtom) * 2);
+// Automatically updates when countAtom syncs from another tab
+```
+
+<br />
+
+---
+
+<br />
+
+## 🏪 Redux
+
+Synchronize your Redux (or Redux Toolkit) store across browser tabs via a **store enhancer**.
+
+```bash
+npm install tab-bridge redux       # or @reduxjs/toolkit
+```
+
+### Quick Start
+
+```ts
+import { configureStore } from '@reduxjs/toolkit';
+import { tabSyncEnhancer } from 'tab-bridge/redux';
+
+const store = configureStore({
+  reducer: { counter: counterReducer, theme: themeReducer },
+  enhancers: (getDefault) =>
+    getDefault().concat(tabSyncEnhancer({ channel: 'my-app' })),
+});
+```
+
+Every dispatch that changes state is automatically synced. Remote changes are merged via an internal `@@tab-bridge/MERGE` action — no reducer changes needed.
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `channel` | `string` | `'tab-sync-redux'` | Channel name |
+| `include` | `string[]` | — | Only sync these top-level keys (slice names) |
+| `exclude` | `string[]` | — | Exclude these top-level keys |
+| `merge` | `(local, remote, key) => unknown` | LWW | Custom conflict resolution |
+| `transport` | `'broadcast-channel' \| 'local-storage'` | auto-detect | Force transport |
+| `debug` | `boolean` | `false` | Debug logging |
+| `onError` | `(error: Error) => void` | — | Error callback |
+| `onSyncReady` | `(instance: TabSyncInstance) => void` | — | Access underlying instance |
+
+### Selective Sync
+
+```ts
+tabSyncEnhancer({
+  channel: 'my-app',
+  include: ['counter', 'settings'],  // only sync these slices
+  // exclude: ['auth'],              // or exclude specific slices
+})
+```
+
+### Design Decision: State-Based Sync
+
+The enhancer diffs top-level state keys after each dispatch rather than replaying actions. This guarantees consistency regardless of reducer purity and works with any middleware stack.
+
+<br />
+
+---
+
+<br />
+
+## 🔧 DevTools
+
+A floating development panel for inspecting tab-bridge state, tabs, and events in real time.
+
+```tsx
+import { TabSyncDevTools } from 'tab-bridge/react';
+
+function App() {
+  return (
+    <TabSyncProvider options={{ initial: { count: 0 }, channel: 'app' }}>
+      <MyApp />
+      {process.env.NODE_ENV === 'development' && <TabSyncDevTools />}
+    </TabSyncProvider>
+  );
+}
+```
+
+### Features
+
+| Tab | Description |
+|---|---|
+| **State** | Live JSON view of current state + manual editing (textarea → Apply) |
+| **Tabs** | Active tab list with leader badge and "you" indicator |
+| **Log** | Real-time event stream — state changes, tab joins/leaves |
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Panel position |
+| `defaultOpen` | `boolean` | `false` | Start expanded |
+
+**Tree-shakeable** — if you never import `TabSyncDevTools`, it won't appear in your production bundle.
+
+<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.

package/dist/jotai/index.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+var chunkTGEXRVAL_cjs = require('../chunk-TGEXRVAL.cjs');
+var vanilla = require('jotai/vanilla');
+
+function atomWithTabSync(key, initialValue, options) {
+  const base_channel = options?.channel ?? "tab-sync-jotai";
+  const instance_channel = `${base_channel}:${key}`;
+  let sync_instance = null;
+  const base_atom = vanilla.atom(initialValue);
+  base_atom.onMount = (setAtom) => {
+    if (!chunkTGEXRVAL_cjs.isBrowser) return;
+    const instance = chunkTGEXRVAL_cjs.createTabSync({
+      channel: instance_channel,
+      initial: { value: initialValue },
+      transport: options?.transport,
+      debug: options?.debug,
+      onError: options?.onError
+    });
+    sync_instance = instance;
+    options?.onSyncReady?.(instance);
+    const unsub = instance.on("value", (remote_value, meta) => {
+      if (!meta.isLocal) {
+        setAtom(remote_value);
+      }
+    });
+    return () => {
+      unsub();
+      instance.destroy();
+      sync_instance = null;
+    };
+  };
+  const sync_atom = vanilla.atom(
+    (get) => get(base_atom),
+    (get, set, update) => {
+      const next_value = typeof update === "function" ? update(get(base_atom)) : update;
+      set(base_atom, next_value);
+      sync_instance?.set("value", next_value);
+    }
+  );
+  return sync_atom;
+}
+
+exports.atomWithTabSync = atomWithTabSync;

package/dist/jotai/index.d.cts

@@ -0,0 +1,68 @@
+import { WritableAtom } from 'jotai/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.cjs';
+
+/**
+ * Options for `atomWithTabSync`.
+ *
+ * All atoms sharing the same `channel` reuse a single `createTabSync`
+ * instance internally. Channel-level options (`transport`, `debug`,
+ * `onError`) are taken from the **first** atom that creates the
+ * instance on that channel.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, {
+ *   channel: 'my-app',
+ *   debug: true,
+ * });
+ * ```
+ */
+interface AtomWithTabSyncOptions {
+    /** Channel name for cross-tab communication. @default 'tab-sync-jotai' */
+    channel?: string;
+    /** 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.
+     * Useful for accessing advanced features (RPC, leader election, etc.).
+     * Called once per shared instance — only the first atom to trigger
+     * instance creation will have its callback invoked.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type SetStateAction<T> = T | ((prev: T) => T);
+/**
+ * Creates a Jotai atom whose value is automatically synchronised across
+ * browser tabs via `tab-bridge`.
+ *
+ * Each atom creates its own `createTabSync` instance scoped to the channel
+ * `${channel}:${key}`. The instance is created when the atom is first
+ * subscribed to (React component mount / `store.sub`) and destroyed on
+ * the last unsubscription (unmount).
+ *
+ * The atom behaves like a normal writable atom — use `useAtom` in React
+ * or `store.get` / `store.set` with Jotai's vanilla store.
+ *
+ * @param key - Unique key identifying this piece of state within the channel.
+ * @param initialValue - Default value used when no synced state exists yet.
+ * @param options - Channel and transport configuration.
+ * @returns A writable Jotai atom.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, { channel: 'my-app' });
+ * const themeAtom = atomWithTabSync('theme', 'light', { channel: 'my-app' });
+ * ```
+ */
+declare function atomWithTabSync<T>(key: string, initialValue: T, options?: AtomWithTabSyncOptions): WritableAtom<T, [SetStateAction<T>], void>;
+
+export { type AtomWithTabSyncOptions, atomWithTabSync };

package/dist/jotai/index.d.ts

@@ -0,0 +1,68 @@
+import { WritableAtom } from 'jotai/vanilla';
+import { T as TabSyncInstance } from '../instance-hvEUHx6i.js';
+
+/**
+ * Options for `atomWithTabSync`.
+ *
+ * All atoms sharing the same `channel` reuse a single `createTabSync`
+ * instance internally. Channel-level options (`transport`, `debug`,
+ * `onError`) are taken from the **first** atom that creates the
+ * instance on that channel.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, {
+ *   channel: 'my-app',
+ *   debug: true,
+ * });
+ * ```
+ */
+interface AtomWithTabSyncOptions {
+    /** Channel name for cross-tab communication. @default 'tab-sync-jotai' */
+    channel?: string;
+    /** 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.
+     * Useful for accessing advanced features (RPC, leader election, etc.).
+     * Called once per shared instance — only the first atom to trigger
+     * instance creation will have its callback invoked.
+     */
+    onSyncReady?: (instance: TabSyncInstance<Record<string, unknown>>) => void;
+}
+
+type SetStateAction<T> = T | ((prev: T) => T);
+/**
+ * Creates a Jotai atom whose value is automatically synchronised across
+ * browser tabs via `tab-bridge`.
+ *
+ * Each atom creates its own `createTabSync` instance scoped to the channel
+ * `${channel}:${key}`. The instance is created when the atom is first
+ * subscribed to (React component mount / `store.sub`) and destroyed on
+ * the last unsubscription (unmount).
+ *
+ * The atom behaves like a normal writable atom — use `useAtom` in React
+ * or `store.get` / `store.set` with Jotai's vanilla store.
+ *
+ * @param key - Unique key identifying this piece of state within the channel.
+ * @param initialValue - Default value used when no synced state exists yet.
+ * @param options - Channel and transport configuration.
+ * @returns A writable Jotai atom.
+ *
+ * @example
+ * ```ts
+ * import { atomWithTabSync } from 'tab-bridge/jotai';
+ *
+ * const countAtom = atomWithTabSync('count', 0, { channel: 'my-app' });
+ * const themeAtom = atomWithTabSync('theme', 'light', { channel: 'my-app' });
+ * ```
+ */
+declare function atomWithTabSync<T>(key: string, initialValue: T, options?: AtomWithTabSyncOptions): WritableAtom<T, [SetStateAction<T>], void>;
+
+export { type AtomWithTabSyncOptions, atomWithTabSync };

package/dist/jotai/index.js

@@ -0,0 +1,42 @@
+import { isBrowser, createTabSync } from '../chunk-4JDWAUYM.js';
+import { atom } from 'jotai/vanilla';
+
+function atomWithTabSync(key, initialValue, options) {
+  const base_channel = options?.channel ?? "tab-sync-jotai";
+  const instance_channel = `${base_channel}:${key}`;
+  let sync_instance = null;
+  const base_atom = atom(initialValue);
+  base_atom.onMount = (setAtom) => {
+    if (!isBrowser) return;
+    const instance = createTabSync({
+      channel: instance_channel,
+      initial: { value: initialValue },
+      transport: options?.transport,
+      debug: options?.debug,
+      onError: options?.onError
+    });
+    sync_instance = instance;
+    options?.onSyncReady?.(instance);
+    const unsub = instance.on("value", (remote_value, meta) => {
+      if (!meta.isLocal) {
+        setAtom(remote_value);
+      }
+    });
+    return () => {
+      unsub();
+      instance.destroy();
+      sync_instance = null;
+    };
+  };
+  const sync_atom = atom(
+    (get) => get(base_atom),
+    (get, set, update) => {
+      const next_value = typeof update === "function" ? update(get(base_atom)) : update;
+      set(base_atom, next_value);
+      sync_instance?.set("value", next_value);
+    }
+  );
+  return sync_atom;
+}
+
+export { atomWithTabSync };