shared-state-bridge 1.0.0

package/README.md

@@ -0,0 +1,1968 @@
+# shared-state-bridge
+
+Lightweight shared state bridge for monorepo apps. Sync state across packages in Turborepo / Nx with TypeScript-first API, React hooks, optional persistence, and real-time WebSocket sync across apps.
+
+- **Zero-config cross-package sharing** — named bridges resolve via global registry
+- **React 18+ hooks** — `useSyncExternalStore` with selector-based re-render optimization
+- **Optional persistence** — localStorage, AsyncStorage, or custom adapters
+- **Real-time sync** — WebSocket-based state sync across different apps (Next.js + React Native)
+- **Tiny** — core ~1.2KB gzipped, no dependencies
+- **TypeScript-first** — full type inference and safety
+- **Plugin system** — extend with persistence, sync, logging, or your own plugins
+
+---
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [Creating a Bridge](#creating-a-bridge)
+  - [Reading and Updating State](#reading-and-updating-state)
+  - [Subscribing to Changes](#subscribing-to-changes)
+  - [Destroying a Bridge](#destroying-a-bridge)
+- [Cross-Package Sharing](#cross-package-sharing)
+  - [How It Works (Architecture)](#how-it-works-architecture)
+- [React Integration](#react-integration)
+  - [BridgeProvider](#bridgeprovider)
+  - [useBridgeState](#usebridgestate)
+  - [useBridge](#usebridge)
+  - [Preventing Unnecessary Re-renders](#preventing-unnecessary-re-renders)
+  - [Server-Side Rendering (Next.js)](#server-side-rendering-nextjs)
+- [Persistence](#persistence)
+  - [Web — localStorage](#web--localstorage)
+  - [React Native — AsyncStorage](#react-native--asyncstorage)
+  - [Custom Adapter](#custom-adapter)
+  - [Persistence Options Reference](#persistence-options-reference)
+  - [Schema Migrations](#schema-migrations)
+  - [Testing with memoryAdapter](#testing-with-memoryadapter)
+- [Real-Time Sync (WebSocket)](#real-time-sync-websocket)
+  - [Basic Usage](#basic-usage)
+  - [How It Works](#how-it-works)
+  - [Selective Sync (pick / omit)](#selective-sync-pick--omit)
+  - [Custom Conflict Resolution](#custom-conflict-resolution)
+  - [Reconnection](#reconnection)
+  - [Callbacks](#callbacks)
+  - [Sync Options Reference](#sync-options-reference)
+  - [Wire Protocol](#wire-protocol)
+  - [Example WebSocket Server (Node.js)](#example-websocket-server-nodejs)
+- [Plugins](#plugins)
+  - [Plugin Lifecycle](#plugin-lifecycle)
+  - [Writing a Custom Plugin](#writing-a-custom-plugin)
+- [TypeScript](#typescript)
+- [Monorepo Setup (Turborepo / Nx)](#monorepo-setup-turborepo--nx)
+- [API Reference](#api-reference)
+  - [Core API](#core-api)
+  - [BridgeApi Instance Methods](#bridgeapi-instance-methods)
+  - [React API](#react-api)
+  - [Persist API](#persist-api)
+  - [Sync API](#sync-api)
+  - [Types](#types)
+- [Architecture Deep Dive](#architecture-deep-dive)
+  - [State Update Flow](#state-update-flow)
+  - [Selector Re-render Optimization](#selector-re-render-optimization)
+  - [Global Registry Internals](#global-registry-internals)
+  - [Persistence Flow](#persistence-flow)
+  - [Sync Flow](#sync-flow)
+- [Gotchas and Common Pitfalls](#gotchas-and-common-pitfalls)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [Support](#support)
+- [License](#license)
+
+---
+
+## Install
+
+```bash
+# npm
+npm install shared-state-bridge
+
+# yarn
+yarn add shared-state-bridge
+
+# pnpm
+pnpm add shared-state-bridge
+```
+
+> **Note:** React is an optional peer dependency. If you only use the core API (no hooks), React is not required.
+
+---
+
+## Quick Start
+
+```typescript
+import { createBridge } from 'shared-state-bridge'
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { count: 0, theme: 'light' },
+})
+
+// Read state
+bridge.getState() // { count: 0, theme: 'light' }
+
+// Update state (partial merge)
+bridge.setState({ count: 1 })
+
+// Update with updater function
+bridge.setState(prev => ({ count: prev.count + 1 }))
+
+// Subscribe to changes
+const unsub = bridge.subscribe((state, prev) => {
+  console.log('Changed:', state)
+})
+
+// Unsubscribe when done
+unsub()
+```
+
+### With React
+
+```tsx
+import { BridgeProvider, useBridgeState, useBridge } from 'shared-state-bridge/react'
+
+function App() {
+  return (
+    <BridgeProvider bridge={bridge}>
+      <Counter />
+    </BridgeProvider>
+  )
+}
+
+function Counter() {
+  const count = useBridgeState<AppState, number>(s => s.count)
+  const bridge = useBridge<AppState>()
+
+  return (
+    <button onClick={() => bridge.setState(s => ({ count: s.count + 1 }))}>
+      Count: {count}
+    </button>
+  )
+}
+```
+
+### With Persistence
+
+```typescript
+import { createBridge } from 'shared-state-bridge'
+import { persist, localStorageAdapter } from 'shared-state-bridge/persist'
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light', count: 0 },
+  plugins: [
+    persist({
+      adapter: localStorageAdapter,
+      key: 'app-state',
+      pick: ['theme'], // only persist theme
+    }),
+  ],
+})
+```
+
+---
+
+## Core Concepts
+
+### Creating a Bridge
+
+Every bridge has a unique **name** that registers it in a global registry. This name is how other packages in your monorepo can access the same bridge instance.
+
+```typescript
+import { createBridge } from 'shared-state-bridge'
+
+interface AppState {
+  user: { name: string; email: string } | null
+  theme: 'light' | 'dark'
+  notifications: number
+}
+
+const appBridge = createBridge<AppState>({
+  name: 'app',                              // unique identifier
+  initialState: {                           // required initial state
+    user: null,
+    theme: 'light',
+    notifications: 0,
+  },
+  plugins: [],                              // optional plugins array
+})
+```
+
+**Key rules:**
+- The `name` must be unique across your entire application. Attempting to create two bridges with the same name throws an error.
+- `initialState` must be a plain object (not an array, not a primitive).
+- The bridge is immediately registered in the global registry upon creation.
+
+### Reading and Updating State
+
+#### `getState()`
+
+Returns the current state snapshot. This is a synchronous read.
+
+```typescript
+const state = appBridge.getState()
+console.log(state.theme) // 'light'
+```
+
+#### `setState(partial)` — Partial Merge
+
+By default, `setState` performs a **shallow merge** with the current state (like React's `useState` with objects). Only the keys you provide are updated; other keys are preserved.
+
+```typescript
+appBridge.setState({ theme: 'dark' })
+// State is now: { user: null, theme: 'dark', notifications: 0 }
+//                                    ^^^^^  changed
+//                              rest preserved
+```
+
+#### `setState(updater)` — Updater Function
+
+Pass a function to compute the next state based on the current state. Useful when the new value depends on the old one.
+
+```typescript
+appBridge.setState(prev => ({
+  notifications: prev.notifications + 1,
+}))
+```
+
+#### `setState(state, true)` — Full Replacement
+
+Pass `true` as the second argument to **replace** the entire state instead of merging.
+
+```typescript
+appBridge.setState(
+  { user: null, theme: 'light', notifications: 0 },
+  true // replaces entirely — no merge
+)
+```
+
+> **Important:** After replacement, any keys not included in the new state are gone. Use this carefully.
+
+#### `getInitialState()`
+
+Returns the original initial state that was passed to `createBridge`. This never changes, even after `setState` calls.
+
+```typescript
+appBridge.setState({ notifications: 99 })
+appBridge.getInitialState() // { user: null, theme: 'light', notifications: 0 }
+appBridge.getState()        // { user: null, theme: 'light', notifications: 99 }
+```
+
+### Subscribing to Changes
+
+#### Full State Subscription
+
+Listen to every state change:
+
+```typescript
+const unsub = appBridge.subscribe((state, previousState) => {
+  console.log('State changed:', state)
+  console.log('Previous:', previousState)
+})
+
+// Later: stop listening
+unsub()
+```
+
+**Behavior:**
+- The listener is called **synchronously** after each `setState` that produces a new state reference.
+- If `setState` is called but the state reference doesn't change (e.g., replacing with the same object via `setState(sameRef, true)`), listeners are **not** called.
+- Multiple listeners fire in the order they were subscribed.
+
+#### Selector-Based Subscription
+
+Listen only when a specific slice of state changes:
+
+```typescript
+const unsub = appBridge.subscribe(
+  state => state.theme,                    // selector
+  (theme, previousTheme) => {              // only called when theme changes
+    console.log(`Theme: ${previousTheme} -> ${theme}`)
+  }
+)
+
+appBridge.setState({ notifications: 5 })   // listener NOT called (theme unchanged)
+appBridge.setState({ theme: 'dark' })      // listener called: 'light' -> 'dark'
+```
+
+#### Subscription Options
+
+```typescript
+appBridge.subscribe(
+  state => state.notifications,
+  (count, prevCount) => updateBadge(count),
+  {
+    // Fire the listener immediately with the current value
+    fireImmediately: true,
+
+    // Custom equality function (default: Object.is)
+    equalityFn: (a, b) => Math.abs(a - b) < 5,
+  }
+)
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fireImmediately` | `boolean` | `false` | Call the listener once immediately with the current value |
+| `equalityFn` | `(a, b) => boolean` | `Object.is` | Custom comparison to determine if the slice changed |
+
+### Destroying a Bridge
+
+```typescript
+appBridge.destroy()
+```
+
+**What `destroy()` does:**
+1. Removes the bridge from the global registry (it can no longer be found via `getBridge`)
+2. Calls `onDestroy` on all plugins
+3. Clears all listeners (no more notifications)
+4. Marks the bridge as destroyed — subsequent `setState`/`subscribe` calls are silent no-ops
+
+**When to use it:**
+- In tests, to clean up between test cases
+- When unmounting a micro-frontend
+- Before re-creating a bridge with the same name
+
+```typescript
+// Re-creating a bridge after destroy
+appBridge.destroy()
+const newBridge = createBridge({ name: 'app', initialState: { ... } }) // OK
+```
+
+---
+
+## Cross-Package Sharing
+
+This is the **key feature** of `shared-state-bridge`. In a monorepo, all packages are bundled into the same application and share the same JavaScript runtime. Bridges leverage this by storing instances in a global registry that any package can access.
+
+### Package A — Creates the Bridge
+
+```typescript
+// packages/shared/src/bridges.ts
+import { createBridge } from 'shared-state-bridge'
+
+export interface AuthState {
+  user: { id: string; name: string } | null
+  token: string | null
+}
+
+export const authBridge = createBridge<AuthState>({
+  name: 'auth',
+  initialState: { user: null, token: null },
+})
+```
+
+### Package B — Accesses the Bridge by Name
+
+```typescript
+// packages/dashboard/src/auth.ts
+import { getBridge } from 'shared-state-bridge'
+import type { AuthState } from '@myorg/shared'
+
+// Returns the EXACT same instance created in Package A
+const authBridge = getBridge<AuthState>('auth')
+
+authBridge.subscribe(
+  state => state.user,
+  (user) => {
+    if (!user) redirectToLogin()
+  }
+)
+```
+
+### Registry Utilities
+
+```typescript
+import { getBridge, hasBridge, listBridges } from 'shared-state-bridge'
+
+// Check existence without throwing
+if (hasBridge('auth')) {
+  const auth = getBridge('auth')
+}
+
+// List all registered bridges (useful for debugging)
+console.log(listBridges()) // ['auth', 'app', 'ui']
+```
+
+### How It Works (Architecture)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    JavaScript Runtime                        │
+│                                                             │
+│   globalThis[Symbol.for('shared-state-bridge.registry')]    │
+│   ┌───────────────────────────────────────────────────┐     │
+│   │              Map<string, BridgeApi>                │     │
+│   │                                                   │     │
+│   │   'auth'  -> BridgeApi { state, listeners, ... }  │     │
+│   │   'app'   -> BridgeApi { state, listeners, ... }  │     │
+│   │   'ui'    -> BridgeApi { state, listeners, ... }  │     │
+│   └───────────────────────────────────────────────────┘     │
+│                  ^                    ^                       │
+│                  |                    |                       │
+│   ┌──────────────┴──┐    ┌──────────┴───────────┐           │
+│   │   Package A     │    │     Package B        │           │
+│   │                 │    │                      │           │
+│   │ createBridge()  │    │   getBridge('auth')  │           │
+│   │ registers here  │    │   reads from here    │           │
+│   └─────────────────┘    └──────────────────────┘           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The registry uses `Symbol.for('shared-state-bridge.registry')` as the key on `globalThis`. Why `Symbol.for()` instead of a plain string?
+
+- `Symbol.for('x')` returns the **same symbol** across all modules, all files, and even across multiple copies of the package
+- Even if your monorepo accidentally has two versions of `shared-state-bridge` in `node_modules` (a common pitfall), both versions use the same `Symbol.for()` key and access the same `Map`
+- A plain string key like `globalThis.__shared_state_bridge__` could collide with other libraries; symbols cannot
+
+---
+
+## React Integration
+
+The React bindings are imported separately from `shared-state-bridge/react` and have React 18+ as an optional peer dependency.
+
+### BridgeProvider
+
+Provides a bridge instance to the React component tree via context.
+
+```tsx
+import { createBridge } from 'shared-state-bridge'
+import { BridgeProvider } from 'shared-state-bridge/react'
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { count: 0, theme: 'light' },
+})
+
+function App() {
+  return (
+    <BridgeProvider bridge={bridge}>
+      <YourApp />
+    </BridgeProvider>
+  )
+}
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `bridge` | `BridgeApi<T>` | The bridge instance to provide |
+| `children` | `React.ReactNode` | Child components |
+
+> **Note:** `BridgeProvider` is optional. You can pass bridges directly to hooks if you prefer.
+
+### useBridgeState
+
+The primary hook for reading bridge state in React components. Uses `useSyncExternalStore` internally for tear-free, concurrent-safe reads.
+
+#### Signature 1: From Context
+
+```tsx
+function useBridgeState<T extends State, U>(
+  selector: (state: T) => U,
+  options?: { shallow?: boolean }
+): U
+```
+
+Requires a `BridgeProvider` ancestor:
+
+```tsx
+function ThemeToggle() {
+  const theme = useBridgeState<AppState, string>(s => s.theme)
+  // Only re-renders when theme changes
+}
+```
+
+#### Signature 2: Direct Bridge Reference
+
+```tsx
+function useBridgeState<T extends State, U>(
+  bridge: BridgeApi<T>,
+  selector: (state: T) => U,
+  options?: { shallow?: boolean }
+): U
+```
+
+No provider needed:
+
+```tsx
+function Counter() {
+  const count = useBridgeState(bridge, s => s.count)
+  // Only re-renders when count changes
+}
+```
+
+#### Signature 3: Full State (No Selector)
+
+```tsx
+function useBridgeState<T extends State>(
+  bridge: BridgeApi<T>
+): T
+```
+
+Returns the entire state object:
+
+```tsx
+function Debug() {
+  const state = useBridgeState(bridge)
+  // Re-renders on EVERY state change
+  return <pre>{JSON.stringify(state, null, 2)}</pre>
+}
+```
+
+### useBridge
+
+Returns the bridge instance from the nearest `BridgeProvider`. Use this for imperative operations like `setState`.
+
+```tsx
+import { useBridge } from 'shared-state-bridge/react'
+
+function LogoutButton() {
+  const bridge = useBridge<AuthState>()
+
+  return (
+    <button onClick={() => bridge.setState({ user: null, token: null })}>
+      Log Out
+    </button>
+  )
+}
+```
+
+Throws if used outside a `BridgeProvider`.
+
+### Preventing Unnecessary Re-renders
+
+#### Primitive Selectors (No Problem)
+
+Selectors that return primitives (strings, numbers, booleans) work perfectly with the default `Object.is` comparison:
+
+```tsx
+const count = useBridgeState(bridge, s => s.count)    // number
+const theme = useBridgeState(bridge, s => s.theme)    // string
+// These only re-render when the VALUE actually changes
+```
+
+#### Object Selectors (Use `{ shallow: true }`)
+
+Selectors that return **new objects** create a new reference on every call, causing unnecessary re-renders:
+
+```tsx
+// BAD: Creates a new object every render -> re-renders on EVERY state change
+const user = useBridgeState(bridge, s => ({
+  name: s.user?.name,
+  email: s.user?.email,
+}))
+
+// GOOD: Shallow comparison prevents re-render when values haven't changed
+const user = useBridgeState(
+  bridge,
+  s => ({ name: s.user?.name, email: s.user?.email }),
+  { shallow: true }
+)
+```
+
+**How `{ shallow: true }` works internally:**
+
+1. The hook computes the new selector result
+2. It compares each key/value with the previous result using `Object.is`
+3. If all keys and values match, it returns the **previous object reference**
+4. React's `useSyncExternalStore` sees the same reference and skips re-rendering
+
+#### Alternative: Select Primitives Individually
+
+If you only need a few values, separate selectors can be simpler:
+
+```tsx
+// Each hook only re-renders when its specific value changes
+const name = useBridgeState(bridge, s => s.user?.name)
+const email = useBridgeState(bridge, s => s.user?.email)
+```
+
+### Server-Side Rendering (Next.js)
+
+`useBridgeState` is SSR-safe. During server rendering, it uses `getInitialState()` as the server snapshot, preventing hydration mismatches.
+
+```tsx
+// This works in Next.js App Router and Pages Router
+function ThemeSwitcher() {
+  const theme = useBridgeState(bridge, s => s.theme)
+  // Server: returns initial state ('light')
+  // Client: returns current state (may differ after hydration)
+}
+```
+
+**Caveat:** On the server in development mode, `globalThis` persists across requests due to hot module reload. For production this is not an issue since each request gets a fresh runtime. If you encounter stale state in dev, ensure bridges are created in module scope or call `destroy()` in cleanup.
+
+---
+
+## Persistence
+
+Persistence is opt-in via the `persist` plugin from `shared-state-bridge/persist`. State is serialized and written to a storage adapter on every change (throttled). On initialization, persisted state is hydrated back into the bridge.
+
+### Web — localStorage
+
+```typescript
+import { createBridge } from 'shared-state-bridge'
+import { persist, localStorageAdapter } from 'shared-state-bridge/persist'
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light', count: 0 },
+  plugins: [
+    persist({
+      adapter: localStorageAdapter,
+      key: 'app-state',
+      pick: ['theme'],      // only persist theme, not count
+    }),
+  ],
+})
+```
+
+The `localStorageAdapter` is safe to use in SSR environments — it silently returns `null` when `localStorage` is unavailable.
+
+### React Native — AsyncStorage
+
+The `asyncStorageAdapter` is a **factory function** that accepts an AsyncStorage instance. This avoids a hard dependency on `@react-native-async-storage/async-storage`.
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { createBridge } from 'shared-state-bridge'
+import { persist, asyncStorageAdapter } from 'shared-state-bridge/persist'
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light' },
+  plugins: [
+    persist({
+      adapter: asyncStorageAdapter(AsyncStorage),
+      key: 'app-state',
+    }),
+  ],
+})
+```
+
+### Custom Adapter
+
+Implement the `PersistAdapter` interface with 3 methods. Each method can return a value synchronously or a `Promise`:
+
+```typescript
+import type { PersistAdapter } from 'shared-state-bridge'
+
+const customAdapter: PersistAdapter = {
+  getItem: (key: string) => string | null | Promise<string | null>
+  setItem: (key: string, value: string) => void | Promise<void>
+  removeItem: (key: string) => void | Promise<void>
+}
+```
+
+**Example — IndexedDB adapter:**
+
+```typescript
+const idbAdapter: PersistAdapter = {
+  getItem: async (key) => {
+    const db = await openDB()
+    return db.get('state-store', key)
+  },
+  setItem: async (key, value) => {
+    const db = await openDB()
+    await db.put('state-store', value, key)
+  },
+  removeItem: async (key) => {
+    const db = await openDB()
+    await db.delete('state-store', key)
+  },
+}
+```
+
+### Persistence Options Reference
+
+```typescript
+persist({
+  // REQUIRED
+  adapter: PersistAdapter,        // Storage backend
+  key: string,                    // Storage key name
+
+  // FILTERING (pick one or neither)
+  pick?: (keyof T)[],             // Only persist these keys
+  omit?: (keyof T)[],             // Exclude these keys
+
+  // PERFORMANCE
+  throttleMs?: number,            // Throttle writes (default: 100ms)
+
+  // SERIALIZATION
+  serialize?: (state) => string,  // Custom serializer (default: JSON.stringify)
+  deserialize?: (raw) => unknown, // Custom deserializer (default: JSON.parse)
+
+  // VERSIONING
+  version?: number,               // Schema version (default: 0)
+  migrate?: (persisted, oldVersion) => Partial<T>,  // Migration function
+})
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `adapter` | `PersistAdapter` | *required* | The storage backend to use |
+| `key` | `string` | *required* | Key under which state is stored |
+| `pick` | `(keyof T)[]` | `undefined` | Whitelist: only persist these state keys |
+| `omit` | `(keyof T)[]` | `undefined` | Blacklist: exclude these state keys from persistence |
+| `throttleMs` | `number` | `100` | Minimum interval between writes (ms). Prevents excessive writes during rapid state changes. Trailing writes are guaranteed. |
+| `serialize` | `(state) => string` | `JSON.stringify` | Custom serialization function |
+| `deserialize` | `(raw) => unknown` | `JSON.parse` | Custom deserialization function |
+| `version` | `number` | `0` | Schema version number, stored alongside persisted state |
+| `migrate` | `(persisted, oldVersion) => Partial<T>` | `undefined` | Called when persisted version differs from current version |
+
+### Schema Migrations
+
+When your state shape changes between app versions, use `version` and `migrate` to handle the transition:
+
+```typescript
+// Version 1 state: { theme: 'light' }
+// Version 2 state: { theme: 'light', locale: 'en' }
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light', locale: 'en' },
+  plugins: [
+    persist({
+      adapter: localStorageAdapter,
+      key: 'app-state',
+      version: 2,
+      migrate: (persisted, oldVersion) => {
+        if (oldVersion === 1) {
+          // Add the new 'locale' field with a default value
+          return { ...(persisted as object), locale: 'en' } as Partial<AppState>
+        }
+        return persisted as Partial<AppState>
+      },
+    }),
+  ],
+})
+```
+
+**Migration behavior:**
+- If persisted version matches current version: hydrate normally
+- If versions differ AND `migrate` is provided: call `migrate(persisted, oldVersion)` and use the result
+- If versions differ AND `migrate` is NOT provided: discard persisted data entirely and start fresh
+
+### Storage Envelope Format
+
+The persist plugin stores data in this format:
+
+```json
+{
+  "state": { "theme": "dark", "locale": "en" },
+  "version": 2
+}
+```
+
+### Testing with memoryAdapter
+
+The `memoryAdapter()` factory creates an in-memory storage backend. Perfect for tests and SSR:
+
+```typescript
+import { memoryAdapter } from 'shared-state-bridge/persist'
+
+// Each call creates a fresh, isolated store
+const adapter = memoryAdapter()
+
+const bridge = createBridge({
+  name: 'test',
+  initialState: { count: 0 },
+  plugins: [persist({ adapter, key: 'test' })],
+})
+```
+
+---
+
+## Real-Time Sync (WebSocket)
+
+The `sync` plugin enables real-time state synchronization between **different apps** over WebSocket. Connect your Next.js web app, React Native mobile app, and any other client to the same channel — state changes propagate instantly.
+
+> **Important:** This is a client-side plugin only. You provide your own WebSocket server URL. A minimal example server is included below.
+
+### Basic Usage
+
+```typescript
+import { createBridge } from 'shared-state-bridge'
+import { sync } from 'shared-state-bridge/sync'
+
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light', count: 0, localDraft: '' },
+  plugins: [
+    sync({
+      url: 'wss://your-server.com/sync',
+      channel: 'room-123',
+    }),
+  ],
+})
+
+// State changes are now synced across all connected clients
+bridge.setState({ theme: 'dark' }) // -> sent to all other clients in room-123
+```
+
+### How It Works
+
+```
+  App A (Next.js)              WebSocket Server             App B (React Native)
+  ─────────────────          ──────────────────            ─────────────────────
+  bridge.setState()
+       │
+       ├─ onStateChange()
+       │   ├─ isApplyingRemote? skip (echo guard)
+       │   └─ filterState() ──► send({ type: "state" }) ──► broadcast to channel
+       │                              │                           │
+       │                              │                    ◄──────┘
+       │                              │                    onMessage()
+       │                              │                      ├─ same clientId? skip
+       │                              │                      ├─ resolve(local, remote)
+       │                              │                      └─ bridge.setState(merged)
+       │                              │                           └─ isApplyingRemote = true
+       │                              │                              (prevents re-broadcast)
+```
+
+Each client gets a unique `clientId`. Messages are tagged with this ID so clients ignore their own echoes. An `isApplyingRemote` flag prevents re-broadcasting state updates received from the server.
+
+### Selective Sync (pick / omit)
+
+Same as persistence — only sync the keys you need:
+
+```typescript
+sync({
+  url: 'wss://your-server.com/sync',
+  channel: 'room-1',
+  pick: ['theme', 'count'],  // only sync these keys
+})
+
+// OR
+
+sync({
+  url: 'wss://your-server.com/sync',
+  channel: 'room-1',
+  omit: ['localDraft'],  // sync everything except these
+})
+```
+
+### Custom Conflict Resolution
+
+By default, incoming remote state is merged directly (last-write-wins). You can provide a custom `resolve` function:
+
+```typescript
+sync({
+  url: 'wss://your-server.com/sync',
+  channel: 'room-1',
+  resolve: (localState, remoteState) => {
+    // Custom logic: take the higher count, but always accept remote theme
+    return {
+      count: Math.max(localState.count, remoteState.count ?? 0),
+      theme: remoteState.theme ?? localState.theme,
+    }
+  },
+})
+```
+
+The `resolve` function receives the full local state and the incoming remote partial state, and should return the partial state to apply.
+
+### Reconnection
+
+Auto-reconnect is enabled by default with exponential backoff:
+
+```typescript
+sync({
+  url: 'wss://your-server.com/sync',
+  channel: 'room-1',
+  reconnect: true,                // default: true
+  reconnectInterval: 1000,        // base interval in ms (default: 1000)
+  maxReconnectInterval: 30000,    // cap in ms (default: 30000)
+  maxReconnectAttempts: Infinity,  // default: Infinity
+})
+```
+
+The backoff sequence is: 1s, 2s, 4s, 8s, 16s, 30s, 30s, 30s... The counter resets on every successful connection. Messages sent while disconnected are buffered and flushed on reconnect.
+
+### Callbacks
+
+```typescript
+sync({
+  url: 'wss://your-server.com/sync',
+  channel: 'room-1',
+  onConnect: () => console.log('Connected to sync server'),
+  onDisconnect: () => console.log('Disconnected from sync server'),
+  onError: (error) => console.error('Sync error:', error),
+})
+```
+
+### Sync Options Reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | *required* | WebSocket server URL (`wss://...`) |
+| `channel` | `string` | *required* | Channel/room name to join |
+| `pick` | `(keyof T)[]` | — | Only sync these keys |
+| `omit` | `(keyof T)[]` | — | Exclude these keys from sync |
+| `throttleMs` | `number` | `50` | Throttle outbound messages (ms) |
+| `reconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `reconnectInterval` | `number` | `1000` | Base reconnect interval (ms) |
+| `maxReconnectInterval` | `number` | `30000` | Max reconnect interval cap (ms) |
+| `maxReconnectAttempts` | `number` | `Infinity` | Max reconnect attempts |
+| `onConnect` | `() => void` | — | Called on successful connection |
+| `onDisconnect` | `() => void` | — | Called on disconnection |
+| `onError` | `(error) => void` | — | Called on WebSocket error |
+| `resolve` | `(local, remote) => Partial<T>` | — | Custom conflict resolver |
+
+### Wire Protocol
+
+All messages are JSON over WebSocket. The protocol is simple and easy to implement on any server.
+
+**Client -> Server:**
+
+```typescript
+// Join a channel
+{ type: "join", channel: "room-1", clientId: "abc123" }
+
+// Send state update
+{ type: "state", channel: "room-1", clientId: "abc123", state: { count: 5 }, timestamp: 1700000000000 }
+```
+
+**Server -> Client:**
+
+```typescript
+// Relay state from another client
+{ type: "state", channel: "room-1", clientId: "other456", state: { count: 5 }, timestamp: 1700000000000 }
+
+// Send full state (e.g., on initial join for late-joiners)
+{ type: "full_state", channel: "room-1", state: { count: 5, theme: "dark" }, timestamp: 1700000000000 }
+```
+
+### Example WebSocket Server (Node.js)
+
+A minimal relay server that broadcasts state to all clients in a channel:
+
+```javascript
+import { WebSocketServer } from 'ws'
+
+const wss = new WebSocketServer({ port: 8080 })
+
+// channel -> Set<WebSocket>
+const channels = new Map()
+
+wss.on('connection', (ws) => {
+  let clientChannel = null
+
+  ws.on('message', (raw) => {
+    const msg = JSON.parse(raw)
+
+    if (msg.type === 'join') {
+      clientChannel = msg.channel
+      if (!channels.has(clientChannel)) {
+        channels.set(clientChannel, new Set())
+      }
+      channels.get(clientChannel).add(ws)
+      return
+    }
+
+    if (msg.type === 'state' && clientChannel) {
+      // Broadcast to all OTHER clients in the same channel
+      for (const client of channels.get(clientChannel) || []) {
+        if (client !== ws && client.readyState === 1) {
+          client.send(JSON.stringify(msg))
+        }
+      }
+    }
+  })
+
+  ws.on('close', () => {
+    if (clientChannel && channels.has(clientChannel)) {
+      channels.get(clientChannel).delete(ws)
+      if (channels.get(clientChannel).size === 0) {
+        channels.delete(clientChannel)
+      }
+    }
+  })
+})
+
+console.log('Sync server running on ws://localhost:8080')
+```
+
+> **Production tip:** For production, consider using a library like `ws` with `uWebSockets.js` for better performance, adding authentication (verify tokens in the `connection` event), and using Redis pub/sub if you need to scale across multiple server instances.
+
+---
+
+## Plugins
+
+Bridges support a plugin system via lifecycle hooks. The `persist` and `sync` plugins are the built-in examples, but you can write your own.
+
+### Plugin Lifecycle
+
+```
+createBridge() called
+    │
+    ├── 1. State initialized from initialState
+    ├── 2. Bridge registered in global registry
+    ├── 3. plugin.onInit(bridgeApi)          <-- Bridge is fully constructed
+    │
+    ▼
+bridge.setState() called
+    │
+    ├── 4. State updated (merge or replace)
+    ├── 5. Listeners notified
+    ├── 6. plugin.onStateChange(state, prev) <-- After listeners
+    │
+    ▼
+bridge.destroy() called
+    │
+    ├── 7. Bridge removed from registry
+    ├── 8. plugin.onDestroy()                <-- Cleanup
+    └── 9. All listeners cleared
+```
+
+### Plugin Interface
+
+```typescript
+interface BridgePlugin<T extends State> {
+  /** Unique plugin name (for debugging) */
+  name: string
+
+  /** Called once after the bridge is fully initialized and registered */
+  onInit?: (bridge: BridgeApi<T>) => void
+
+  /** Called after every state change, after listeners are notified */
+  onStateChange?: (state: T, previousState: T) => void
+
+  /** Called when bridge.destroy() is invoked, before listeners are cleared */
+  onDestroy?: () => void
+}
+```
+
+### Writing a Custom Plugin
+
+**Example — Logger Plugin:**
+
+```typescript
+import type { BridgePlugin } from 'shared-state-bridge'
+
+function createLoggerPlugin<T extends State>(options?: {
+  collapsed?: boolean
+}): BridgePlugin<T> {
+  return {
+    name: 'logger',
+    onInit: (bridge) => {
+      console.log(`[logger] Bridge "${bridge.getName()}" initialized with:`, bridge.getState())
+    },
+    onStateChange: (state, previousState) => {
+      const method = options?.collapsed ? console.groupCollapsed : console.group
+      method('[logger] State change')
+      console.log('Previous:', previousState)
+      console.log('Current:', state)
+      console.groupEnd()
+    },
+    onDestroy: () => {
+      console.log('[logger] Bridge destroyed')
+    },
+  }
+}
+
+// Usage
+const bridge = createBridge({
+  name: 'app',
+  initialState: { count: 0 },
+  plugins: [createLoggerPlugin({ collapsed: true })],
+})
+```
+
+**Example — Validation Plugin:**
+
+```typescript
+function createValidationPlugin<T extends State>(
+  validate: (state: T) => boolean,
+  errorMessage?: string
+): BridgePlugin<T> {
+  return {
+    name: 'validation',
+    onStateChange: (state) => {
+      if (!validate(state)) {
+        console.error(errorMessage ?? '[validation] Invalid state:', state)
+      }
+    },
+  }
+}
+
+// Usage
+const bridge = createBridge({
+  name: 'counter',
+  initialState: { count: 0 },
+  plugins: [
+    createValidationPlugin(
+      (s) => s.count >= 0,
+      'Count cannot be negative!'
+    ),
+  ],
+})
+```
+
+**Combining multiple plugins:**
+
+```typescript
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light', count: 0 },
+  plugins: [
+    persist({ adapter: localStorageAdapter, key: 'app', pick: ['theme'] }),
+    createLoggerPlugin(),
+    createValidationPlugin((s) => typeof s.count === 'number'),
+  ],
+})
+```
+
+Plugins execute in array order — `onInit` and `onStateChange` are called on plugin 1, then plugin 2, then plugin 3.
+
+---
+
+## TypeScript
+
+Full type inference throughout the API:
+
+```typescript
+interface AppState {
+  count: number
+  theme: 'light' | 'dark'
+  user: { name: string } | null
+}
+
+// createBridge infers T from initialState (or use explicit generic)
+const bridge = createBridge<AppState>({
+  name: 'app',
+  initialState: { count: 0, theme: 'light', user: null },
+})
+
+// setState is fully typed
+bridge.setState({ count: 1 })            // OK
+bridge.setState({ count: 'string' })     // Type error: string is not number
+bridge.setState({ unknown: true })       // Type error: unknown key
+
+// Updater function receives correctly typed state
+bridge.setState(prev => ({
+  count: prev.count + 1,                 // prev is AppState
+}))
+
+// Selectors infer return type
+const count = useBridgeState(bridge, s => s.count)
+//    ^? number
+
+const theme = useBridgeState(bridge, s => s.theme)
+//    ^? 'light' | 'dark'
+
+// getBridge with type parameter
+const b = getBridge<AppState>('app')
+b.getState().theme    // 'light' | 'dark'
+b.getState().unknown  // Type error
+
+// Subscribe selector is typed
+bridge.subscribe(
+  s => s.user,                          // selector returns { name: string } | null
+  (user, prevUser) => {                 // user and prevUser are { name: string } | null
+    console.log(user?.name)
+  }
+)
+```
+
+### Type Exports
+
+All types are exported for use in your own code:
+
+```typescript
+import type {
+  State,              // Record<string, unknown>
+  BridgeApi,          // Bridge instance type
+  BridgeConfig,       // createBridge config
+  BridgePlugin,       // Plugin interface
+  PersistAdapter,     // Storage adapter interface
+  PersistOptions,     // persist() config
+  SetState,           // setState signature
+  Subscribe,          // subscribe signature
+  Listener,           // Full-state listener type
+  SelectorListener,   // Selector listener type
+  Selector,           // Selector function type
+  EqualityFn,         // Equality function type
+} from 'shared-state-bridge'
+```
+
+---
+
+## Monorepo Setup (Turborepo / Nx)
+
+### 1. Add as a Shared Dependency
+
+Add `shared-state-bridge` to a shared/common package in your monorepo:
+
+```jsonc
+// packages/shared/package.json
+{
+  "name": "@myorg/shared",
+  "dependencies": {
+    "shared-state-bridge": "^1.0.0"
+  }
+}
+```
+
+### 2. Define Bridges in the Shared Package
+
+```typescript
+// packages/shared/src/bridges.ts
+import { createBridge } from 'shared-state-bridge'
+
+// --- Auth Bridge ---
+export interface AuthState {
+  user: { id: string; name: string; email: string } | null
+  token: string | null
+  isLoading: boolean
+}
+
+export const authBridge = createBridge<AuthState>({
+  name: 'auth',
+  initialState: { user: null, token: null, isLoading: false },
+})
+
+// --- UI Bridge ---
+export interface UIState {
+  sidebarOpen: boolean
+  modal: string | null
+  toasts: Array<{ id: string; message: string }>
+}
+
+export const uiBridge = createBridge<UIState>({
+  name: 'ui',
+  initialState: { sidebarOpen: false, modal: null, toasts: [] },
+})
+```
+
+### 3. Use from Any Package
+
+**Web (Next.js):**
+
+```tsx
+// packages/web/src/components/Header.tsx
+import { useBridgeState } from 'shared-state-bridge/react'
+import { getBridge } from 'shared-state-bridge'
+import type { AuthState } from '@myorg/shared'
+
+const auth = getBridge<AuthState>('auth')
+
+function Header() {
+  const user = useBridgeState(auth, s => s.user)
+
+  return (
+    <header>
+      <span>{user?.name ?? 'Guest'}</span>
+    </header>
+  )
+}
+```
+
+**Mobile (React Native):**
+
+```tsx
+// packages/mobile/src/screens/Profile.tsx
+import { useBridgeState } from 'shared-state-bridge/react'
+import { getBridge } from 'shared-state-bridge'
+import type { AuthState } from '@myorg/shared'
+
+const auth = getBridge<AuthState>('auth')
+
+function ProfileScreen() {
+  const user = useBridgeState(auth, s => s.user)
+
+  return (
+    <View>
+      <Text>{user?.name}</Text>
+      <Text>{user?.email}</Text>
+    </View>
+  )
+}
+```
+
+**Service Package (No React):**
+
+```typescript
+// packages/analytics/src/tracker.ts
+import { getBridge } from 'shared-state-bridge'
+import type { AuthState } from '@myorg/shared'
+
+const auth = getBridge<AuthState>('auth')
+
+auth.subscribe(
+  s => s.user,
+  (user) => {
+    if (user) {
+      analytics.identify(user.id, { name: user.name })
+    }
+  }
+)
+```
+
+### Project Structure Example
+
+```
+my-monorepo/
+├── packages/
+│   ├── shared/           # Bridge definitions + types
+│   │   └── src/bridges.ts
+│   ├── web/              # Next.js app
+│   │   └── src/components/Header.tsx
+│   ├── mobile/           # React Native app
+│   │   └── src/screens/Profile.tsx
+│   └── analytics/        # Service package (no React)
+│       └── src/tracker.ts
+├── turbo.json / nx.json
+└── package.json
+```
+
+---
+
+## API Reference
+
+### Core API
+
+#### `createBridge<T>(config): BridgeApi<T>`
+
+Creates and registers a new bridge store.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `config.name` | `string` | Unique name for the global registry |
+| `config.initialState` | `T` | Initial state object |
+| `config.plugins` | `BridgePlugin<T>[]` | Optional plugins array |
+
+**Returns:** `BridgeApi<T>` instance
+
+**Throws:** If a bridge with the same name already exists
+
+---
+
+#### `getBridge<T>(name): BridgeApi<T>`
+
+Retrieves an existing bridge from the global registry.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `name` | `string` | The bridge name |
+
+**Returns:** `BridgeApi<T>` — the exact same instance that was created
+
+**Throws:** If no bridge with that name exists
+
+---
+
+#### `hasBridge(name): boolean`
+
+Checks if a bridge exists in the registry without throwing.
+
+---
+
+#### `listBridges(): string[]`
+
+Returns an array of all registered bridge names.
+
+---
+
+### BridgeApi Instance Methods
+
+These are the methods available on the object returned by `createBridge()`.
+
+#### `bridge.getState(): T`
+
+Returns the current state snapshot. Synchronous.
+
+---
+
+#### `bridge.setState(partial): void`
+
+Updates state by shallow-merging `partial` into current state.
+
+```typescript
+// Object form
+bridge.setState({ count: 1 })
+
+// Updater function form
+bridge.setState(prev => ({ count: prev.count + 1 }))
+```
+
+---
+
+#### `bridge.setState(state, true): void`
+
+Replaces the entire state (no merge).
+
+```typescript
+bridge.setState({ count: 0, theme: 'light' }, true)
+```
+
+---
+
+#### `bridge.subscribe(listener): () => void`
+
+Subscribes to all state changes. Returns an unsubscribe function.
+
+```typescript
+const unsub = bridge.subscribe((state, previousState) => { ... })
+unsub() // stop listening
+```
+
+---
+
+#### `bridge.subscribe(selector, listener, options?): () => void`
+
+Subscribes with a selector. Listener only fires when the selected value changes.
+
+```typescript
+const unsub = bridge.subscribe(
+  s => s.count,
+  (count, prevCount) => { ... },
+  { equalityFn: Object.is, fireImmediately: false }
+)
+```
+
+---
+
+#### `bridge.getInitialState(): T`
+
+Returns the original initial state (never changes).
+
+---
+
+#### `bridge.getName(): string`
+
+Returns the bridge's registered name.
+
+---
+
+#### `bridge.destroy(): void`
+
+Removes from registry, calls plugin `onDestroy`, clears listeners. Idempotent.
+
+---
+
+### React API
+
+Import from `shared-state-bridge/react`.
+
+#### `<BridgeProvider bridge={bridge}>`
+
+Context provider. Makes `bridge` available to `useBridge()` and `useBridgeState(selector)`.
+
+---
+
+#### `useBridge<T>(): BridgeApi<T>`
+
+Returns bridge from context. Throws outside `BridgeProvider`.
+
+---
+
+#### `useBridgeState(selector, options?): U`
+
+Subscribes to state from context bridge.
+
+#### `useBridgeState(bridge, selector, options?): U`
+
+Subscribes to state from a direct bridge reference.
+
+#### `useBridgeState(bridge): T`
+
+Subscribes to the full state.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `shallow` | `boolean` | `false` | Use shallow equality to prevent re-renders from object selectors |
+
+---
+
+### Persist API
+
+Import from `shared-state-bridge/persist`.
+
+#### `persist<T>(options): BridgePlugin<T>`
+
+Creates a persistence plugin. See [Persistence Options Reference](#persistence-options-reference) for full options.
+
+---
+
+#### `localStorageAdapter: PersistAdapter`
+
+Pre-built adapter for `window.localStorage`. Safe in SSR (returns `null`).
+
+---
+
+#### `asyncStorageAdapter(storage): PersistAdapter`
+
+Factory that wraps a React Native `AsyncStorage` instance.
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage'
+const adapter = asyncStorageAdapter(AsyncStorage)
+```
+
+---
+
+#### `memoryAdapter(): PersistAdapter`
+
+Creates an in-memory storage backend. Each call returns a fresh, isolated store.
+
+---
+
+### Sync API
+
+#### `sync<T>(options: SyncOptions<T>): BridgePlugin<T>`
+
+Creates a WebSocket sync plugin. Pass it in the `plugins` array of `createBridge()`.
+
+```typescript
+import { sync } from 'shared-state-bridge/sync'
+
+sync({
+  url: 'wss://your-server.com/sync',
+  channel: 'room-1',
+  pick: ['theme'],
+  throttleMs: 50,
+  onConnect: () => console.log('connected'),
+})
+```
+
+See [Sync Options Reference](#sync-options-reference) for all available options.
+
+#### `SyncConnection`
+
+Low-level WebSocket connection manager with auto-reconnect, message buffering, and exponential backoff. Used internally by the `sync` plugin, but exported for advanced use cases.
+
+```typescript
+import { SyncConnection } from 'shared-state-bridge/sync'
+
+const conn = new SyncConnection({
+  url: 'wss://your-server.com/sync',
+  reconnect: true,
+  maxReconnectAttempts: 10,
+  reconnectInterval: 1000,
+  maxReconnectInterval: 30000,
+  onConnect: () => {},
+  onDisconnect: () => {},
+  onMessage: (msg) => {},
+  onError: (err) => {},
+})
+
+conn.connect()
+conn.send({ type: 'state', channel: 'room-1', clientId: 'abc', state: {}, timestamp: Date.now() })
+conn.destroy()
+```
+
+---
+
+### Types
+
+All types are exported from the main entry point:
+
+| Type | Description |
+|---|---|
+| `State` | Base state constraint: `Record<string, unknown>` |
+| `BridgeApi<T>` | Bridge instance interface with all methods |
+| `BridgeConfig<T>` | Configuration object for `createBridge` |
+| `BridgePlugin<T>` | Plugin interface with lifecycle hooks |
+| `PersistAdapter` | Storage adapter interface (3 methods) |
+| `PersistOptions<T>` | Full configuration for the `persist` plugin |
+| `SetState<T>` | Type signature for `bridge.setState` |
+| `Subscribe<T>` | Type signature for `bridge.subscribe` |
+| `Listener<T>` | `(state: T, previousState: T) => void` |
+| `SelectorListener<T, U>` | `(slice: U, previousSlice: U) => void` |
+| `SubscribeOptions<U>` | Options for selector-based subscribe |
+| `Selector<T, U>` | `(state: T) => U` |
+| `EqualityFn<U>` | `(a: U, b: U) => boolean` |
+| `SyncOptions<T>` | Configuration for the `sync` plugin |
+| `JoinMessage` | `{ type: "join", channel, clientId }` |
+| `StateMessage` | `{ type: "state", channel, clientId, state, timestamp }` |
+| `FullStateMessage` | `{ type: "full_state", channel, state, timestamp }` |
+| `OutboundMessage` | `JoinMessage \| StateMessage` |
+| `InboundMessage` | `StateMessage \| FullStateMessage` |
+
+---
+
+## Architecture Deep Dive
+
+### State Update Flow
+
+```
+bridge.setState({ count: 1 })
+    │
+    ├── 1. Resolve partial: if function, call with current state
+    │      nextPartial = isFunction(partial) ? partial(state) : partial
+    │
+    ├── 2. Apply update:
+    │      if (replace) state = nextPartial
+    │      else state = Object.assign({}, state, nextPartial)  // new reference
+    │
+    ├── 3. Check: Object.is(state, previousState)?
+    │      YES → return (no notifications)
+    │      NO  → continue
+    │
+    ├── 4. Notify listeners (Set, insertion order):
+    │      listeners.forEach(fn => fn(state, previousState))
+    │
+    └── 5. Notify plugins:
+           plugins.forEach(p => p.onStateChange?.(state, previousState))
+```
+
+Key detail: `Object.assign({}, state, nextPartial)` always creates a **new object reference**. This means even `setState({})` with an empty object will create a new reference and trigger listeners. However, `setState(sameRef, true)` with the exact same reference will be caught by the `Object.is` check and skip notifications.
+
+### Selector Re-render Optimization
+
+```
+State update: { count: 1, theme: 'dark' } -> { count: 2, theme: 'dark' }
+
+Component A: useBridgeState(bridge, s => s.count)
+  -> getSnapshot() returns 2 (was 1)
+  -> Object.is(1, 2) === false
+  -> RE-RENDERS (correct: count changed)
+
+Component B: useBridgeState(bridge, s => s.theme)
+  -> getSnapshot() returns 'dark' (was 'dark')
+  -> Object.is('dark', 'dark') === true
+  -> SKIPS RE-RENDER (correct: theme unchanged)
+
+Component C: useBridgeState(bridge, s => ({ count: s.count, theme: s.theme }))
+  -> getSnapshot() returns NEW object { count: 2, theme: 'dark' }
+  -> Object.is(prevObj, newObj) === false (different references!)
+  -> RE-RENDERS (unnecessary: theme didn't change)
+
+Component D: useBridgeState(bridge, s => ({ count: s.count, theme: s.theme }), { shallow: true })
+  -> getSnapshot() returns { count: 2, theme: 'dark' }
+  -> shallowEqual check: count changed (1 !== 2)
+  -> Returns NEW reference
+  -> RE-RENDERS (correct: count changed)
+
+Component E (same selector, theme unchanged):
+  -> getSnapshot() returns { count: 2, theme: 'dark' }
+  -> shallowEqual check: all values same
+  -> Returns PREVIOUS reference (same object)
+  -> Object.is(prevRef, prevRef) === true
+  -> SKIPS RE-RENDER (correct!)
+```
+
+### Global Registry Internals
+
+```typescript
+// The registry is a Map stored on globalThis with a Symbol.for key:
+
+const REGISTRY_KEY = Symbol.for('shared-state-bridge.registry')
+
+// globalThis[REGISTRY_KEY] = Map {
+//   'auth'  => BridgeApi { ... },
+//   'app'   => BridgeApi { ... },
+//   'ui'    => BridgeApi { ... },
+// }
+
+// Why Symbol.for() is critical:
+//
+// Module A:  Symbol.for('shared-state-bridge.registry')  → Symbol(123)
+// Module B:  Symbol.for('shared-state-bridge.registry')  → Symbol(123)  (SAME!)
+// Duplicate package: Symbol.for('shared-state-bridge.registry') → Symbol(123) (SAME!)
+//
+// Plain string would also work, but Symbols avoid collisions with other
+// libraries that might use globalThis.
+```
+
+### Persistence Flow
+
+```
+createBridge({ plugins: [persist({ adapter, key, version: 2 })] })
+    │
+    ├── Bridge initialized with initialState
+    ├── Bridge registered in global registry
+    │
+    └── persist.onInit(bridge):
+        │
+        ├── Set up throttled writer function
+        │
+        └── Hydrate (async):
+            │
+            ├── raw = await adapter.getItem(key)
+            │
+            ├── if null → skip (first run, nothing persisted)
+            │
+            ├── envelope = deserialize(raw)  // { state, version }
+            │
+            ├── if envelope.version === current version:
+            │   └── bridge.setState(envelope.state)  // merge persisted state
+            │
+            ├── if version mismatch + migrate function:
+            │   ├── migrated = migrate(envelope.state, envelope.version)
+            │   └── bridge.setState(migrated)
+            │
+            └── if version mismatch + NO migrate:
+                └── adapter.removeItem(key)  // discard stale data
+
+
+On every bridge.setState():
+    │
+    └── persist.onStateChange(state):
+        │
+        ├── filtered = filterState(state)  // apply pick/omit
+        ├── envelope = { state: filtered, version }
+        ├── serialized = serialize(envelope)
+        └── adapter.setItem(key, serialized)  // throttled
+```
+
+### Sync Flow
+
+```
+bridge.setState({ count: 5 })          // local update
+    │
+    ├── plugins.forEach(p => p.onStateChange(state, prev))
+    │       │
+    │       └── sync.onStateChange(state)
+    │            ├── isApplyingRemote? return (echo guard)
+    │            └── sendState(state)  // throttled
+    │                 ├── filtered = filterState(state)  // apply pick/omit
+    │                 └── connection.send({ type: "state", channel, clientId, state: filtered })
+    │                      ├── ws.readyState === OPEN? ws.send(data)
+    │                      └── else: buffer.push(data)  // flush on reconnect
+    │
+    ▼ (incoming from server)
+    ws.onmessage(data)
+    │
+    ├── parse JSON
+    ├── message.clientId === ownClientId? skip (echo prevention)
+    ├── resolve? stateToApply = resolve(local, remote)
+    │       else: stateToApply = remoteState (last-write-wins)
+    ├── isApplyingRemote = true  // prevent re-broadcast
+    ├── bridge.setState(stateToApply)
+    └── isApplyingRemote = false
+```
+
+---
+
+## Gotchas and Common Pitfalls
+
+### 1. Bridge Name Collisions
+
+```typescript
+createBridge({ name: 'app', initialState: {} })
+createBridge({ name: 'app', initialState: {} })
+// Error: A bridge named "app" already exists.
+```
+
+**Fix:** Use unique names, or check with `hasBridge('app')` first, or `destroy()` the old bridge.
+
+### 2. getBridge Before createBridge
+
+```typescript
+const bridge = getBridge('auth')
+// Error: No bridge named "auth" found.
+```
+
+**Fix:** Ensure the package that calls `createBridge` is imported/executed before any `getBridge` calls. In a monorepo, the shared package with bridge definitions should be imported at app startup.
+
+### 3. Object Selectors Without Shallow
+
+```tsx
+// This causes re-renders on EVERY state change
+const data = useBridgeState(bridge, s => ({
+  a: s.a,
+  b: s.b,
+}))
+```
+
+**Fix:** Add `{ shallow: true }` or use separate primitive selectors.
+
+### 4. Stale Closures in Updaters
+
+```typescript
+// WRONG: count is captured once
+const count = bridge.getState().count
+bridge.setState({ count: count + 1 })
+bridge.setState({ count: count + 1 }) // Both set count to the same value!
+
+// CORRECT: use updater function for sequential updates
+bridge.setState(s => ({ count: s.count + 1 }))
+bridge.setState(s => ({ count: s.count + 1 })) // Correctly increments twice
+```
+
+### 5. Async Hydration Timing
+
+Hydration from async adapters (AsyncStorage) happens asynchronously. State may briefly hold `initialState` before the persisted state loads:
+
+```typescript
+const bridge = createBridge({
+  name: 'app',
+  initialState: { theme: 'light' },
+  plugins: [persist({ adapter: asyncStorageAdapter(AsyncStorage), key: 'app' })],
+})
+
+bridge.getState() // { theme: 'light' } (initial, not yet hydrated)
+
+// After microtask:
+// bridge.getState() // { theme: 'dark' } (hydrated from storage)
+```
+
+**Fix:** Design your UI to handle the initial state gracefully, or use a loading flag.
+
+### 6. Mutating State Directly
+
+```typescript
+// WRONG: mutation won't trigger listeners
+const state = bridge.getState()
+state.count = 5
+
+// CORRECT: use setState
+bridge.setState({ count: 5 })
+```
+
+### 7. Subscribing in useEffect Without Cleanup
+
+```tsx
+// WRONG: leaks a listener on every render
+useEffect(() => {
+  bridge.subscribe(listener)
+})
+
+// CORRECT: return the unsubscribe function
+useEffect(() => {
+  return bridge.subscribe(listener)
+}, [])
+
+// BEST: use useBridgeState hook instead
+const value = useBridgeState(bridge, selector)
+```
+
+---
+
+## FAQ
+
+**How does cross-package sharing work?**
+Bridges are stored in a `Map` on `globalThis` using `Symbol.for()` as the key. Since `Symbol.for()` returns the same symbol across all modules (even duplicated packages), all packages in your monorepo access the same registry. See [Architecture Deep Dive](#architecture-deep-dive) for details.
+
+**Can I use this without React?**
+Yes. The core (`shared-state-bridge`) has zero dependencies and works in any JS environment — Node.js, browsers, React Native, Deno, Bun. The React hooks are a separate, optional entry point (`shared-state-bridge/react`).
+
+**Does it work with SSR / Next.js?**
+Yes. `useBridgeState` uses `useSyncExternalStore` with a `getServerSnapshot` that returns `getInitialState()`, which is SSR-safe. See [Server-Side Rendering](#server-side-rendering-nextjs).
+
+**How does this compare to Zustand?**
+Zustand is a general-purpose state manager. `shared-state-bridge` is specifically designed for cross-package state sharing in monorepos. The core API is similar (event-emitter store + `useSyncExternalStore`), but the global registry and named bridges are unique to this library. If you only need state within a single package, Zustand is great. If you need to share state *across* packages in a monorepo, `shared-state-bridge` is purpose-built for that.
+
+**What happens if two packages create a bridge with the same name?**
+An error is thrown: `A bridge named "x" already exists`. This prevents silent overwrites. Use `getBridge()` to access existing bridges, or call `destroy()` first to remove the old one.
+
+**Does it support React Native?**
+Yes. The core and React hooks work identically in React Native. For persistence, use `asyncStorageAdapter()` with `@react-native-async-storage/async-storage`.
+
+**What's the bundle size?**
+- Core: ~1.2 KB gzipped
+- React hooks: ~1.1 KB gzipped
+- Persist plugin: ~1.0 KB gzipped
+- Sync plugin: ~1.8 KB gzipped
+- All four combined: ~5.1 KB gzipped
+
+Each entry point is independently tree-shakeable. If you only use the core, React, persist, and sync code is never included.
+
+**Can I have multiple BridgeProviders?**
+Yes. Each `BridgeProvider` provides its own bridge to its subtree. Components use the nearest provider. You can nest providers for different bridges.
+
+**Is it concurrent-safe (React 18)?**
+Yes. `useBridgeState` uses `useSyncExternalStore`, which is React's official API for integrating external stores with concurrent features like `useTransition` and `Suspense`.
+
+**Can I use this in a non-monorepo project?**
+Absolutely. The core API works anywhere. The cross-package registry feature just happens to shine in monorepos, but a single-package app can use `createBridge` + React hooks perfectly fine as a lightweight state manager.
+
+**Does the sync plugin actually sync between different apps (Next.js + React Native)?**
+Yes! The `sync` plugin connects to a WebSocket server and broadcasts state changes to all clients in the same channel. Unlike the core bridge (which shares within the same JS runtime), the sync plugin enables true cross-app real-time state synchronization. You need to provide your own WebSocket server — a minimal example is included in the docs.
+
+**Can I use both persist and sync together?**
+Yes. They are independent plugins that compose naturally:
+
+```typescript
+createBridge({
+  name: 'app',
+  initialState: { theme: 'light', count: 0 },
+  plugins: [
+    persist({ adapter: localStorageAdapter, key: 'app' }),
+    sync({ url: 'wss://server.com/sync', channel: 'room-1' }),
+  ],
+})
+```
+
+State persists locally AND syncs in real-time with other connected apps.
+
+---
+
+## Contributing
+
+Contributions are welcome! Here's how to get started:
+
+```bash
+# Clone the repo
+git clone https://github.com/your-username/shared-state-bridge.git
+cd shared-state-bridge
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Core entry point
+├── core/
+│   ├── types.ts          # All TypeScript type definitions
+│   ├── utils.ts          # shallowEqual, throttle, isFunction
+│   ├── registry.ts       # Global bridge registry
+│   └── bridge.ts         # createBridge + Bridge store logic
+├── react/
+│   ├── index.ts          # React entry point
+│   ├── context.ts        # React context
+│   ├── provider.tsx      # BridgeProvider component
+│   └── hooks.ts          # useBridgeState, useBridge
+├── persist/
+│   ├── index.ts          # Persist entry point
+│   ├── plugin.ts         # Persistence plugin
+│   └── adapters.ts       # Storage adapters
+└── sync/
+    ├── index.ts          # Sync entry point
+    ├── types.ts          # SyncOptions, wire protocol types
+    ├── connection.ts     # WebSocket manager (reconnect, buffer)
+    └── plugin.ts         # sync() plugin factory
+```
+
+### Guidelines
+
+- Keep the core dependency-free
+- Maintain 100% TypeScript strict mode compliance
+- Write tests for all new features
+- Keep bundle sizes minimal — every byte counts
+
+---
+
+## Support
+
+If you find this package useful, consider buying me a coffee!
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?style=flat&logo=buy-me-a-coffee)](https://buymeacoffee.com/aemadeldin)
+
+---
+
+## License
+
+MIT