tab-bridge 0.1.1 → 0.3.0

package/dist/react/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkBQCNBNBT_cjs = require('../chunk-BQCNBNBT.cjs');
+var chunkTGEXRVAL_cjs = require('../chunk-TGEXRVAL.cjs');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
@@ -11,7 +11,7 @@ function TabSyncProvider({
 }) {
   const instanceRef = react.useRef(null);
   if (!instanceRef.current) {
-    instanceRef.current = chunkBQCNBNBT_cjs.createTabSync(options);
+    instanceRef.current = chunkTGEXRVAL_cjs.createTabSync(options);
   }
   react.useEffect(() => {
     return () => {
@@ -26,7 +26,7 @@ function useInstance(options) {
   const contextInstance = react.useContext(TabSyncContext);
   const [ownInstance] = react.useState(() => {
     if (!contextInstance && options) {
-      return chunkBQCNBNBT_cjs.createTabSync(options);
+      return chunkTGEXRVAL_cjs.createTabSync(options);
     }
     return null;
   });
@@ -127,14 +127,14 @@ function useTabSyncSelector(selector, isEqual) {
     initializedRef.current = true;
   }
   const subscribe = react.useCallback(
-    (onStoreChange) => instance.onChange(() => {
-      const next = selectorRef.current(instance.getAll());
-      const equal = isEqualRef.current ?? Object.is;
-      if (!equal(resultRef.current, next)) {
+    (onStoreChange) => instance.select(
+      (state) => selectorRef.current(state),
+      (next) => {
         resultRef.current = next;
         onStoreChange();
-      }
-    }),
+      },
+      { isEqual: isEqualRef.current }
+    ),
     [instance]
   );
   const getSnapshot = react.useCallback(() => resultRef.current, []);
@@ -165,10 +165,83 @@ function useIsLeader() {
   const getServerSnapshot = react.useCallback(() => SERVER_SNAPSHOT, []);
   return react.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
+var SERVER_SNAPSHOT2 = [];
+function useTabs() {
+  const instance = react.useContext(TabSyncContext);
+  if (!instance) {
+    throw new Error("useTabs must be used within a <TabSyncProvider>");
+  }
+  const tabsRef = react.useRef(instance.getTabs());
+  const subscribe = react.useCallback(
+    (onStoreChange) => instance.onTabChange((tabs) => {
+      tabsRef.current = tabs;
+      onStoreChange();
+    }),
+    [instance]
+  );
+  const getSnapshot = react.useCallback(() => tabsRef.current, []);
+  const getServerSnapshot = react.useCallback(() => SERVER_SNAPSHOT2, []);
+  return react.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useLeaderInfo() {
+  const instance = react.useContext(TabSyncContext);
+  if (!instance) {
+    throw new Error("useLeaderInfo must be used within a <TabSyncProvider>");
+  }
+  const leaderRef = react.useRef(instance.getLeader());
+  const subscribe = react.useCallback(
+    (onStoreChange) => {
+      const unsubs = [];
+      unsubs.push(
+        instance.onTabChange(() => {
+          const next = instance.getLeader();
+          if (next?.id !== leaderRef.current?.id) {
+            leaderRef.current = next;
+            onStoreChange();
+          }
+        })
+      );
+      unsubs.push(
+        instance.onLeader(() => {
+          leaderRef.current = instance.getLeader();
+          onStoreChange();
+          return () => {
+            leaderRef.current = instance.getLeader();
+            onStoreChange();
+          };
+        })
+      );
+      return () => {
+        for (const u of unsubs) u();
+      };
+    },
+    [instance]
+  );
+  const getSnapshot = react.useCallback(() => leaderRef.current, []);
+  const getServerSnapshot = react.useCallback(() => null, []);
+  return react.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useTabSyncActions() {
+  const instance = react.useContext(TabSyncContext);
+  if (!instance) {
+    throw new Error("useTabSyncActions must be used within a <TabSyncProvider>");
+  }
+  return react.useMemo(
+    () => ({
+      set: instance.set.bind(instance),
+      patch: instance.patch.bind(instance),
+      transaction: instance.transaction.bind(instance)
+    }),
+    [instance]
+  );
+}
 
 exports.TabSyncContext = TabSyncContext;
 exports.TabSyncProvider = TabSyncProvider;
 exports.useIsLeader = useIsLeader;
+exports.useLeaderInfo = useLeaderInfo;
 exports.useTabSync = useTabSync;
+exports.useTabSyncActions = useTabSyncActions;
 exports.useTabSyncSelector = useTabSyncSelector;
 exports.useTabSyncValue = useTabSyncValue;
+exports.useTabs = useTabs;

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, c as TabInfo } from '../types-BtK4ixKz.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>;
@@ -35,6 +36,9 @@ declare function useTabSyncValue<TState extends Record<string, unknown>, K exten
  * Subscribe to a **derived value** from the synced state.
  * Only re-renders when the selector's output actually changes.
  *
+ * Uses `instance.select()` internally so only changed-key
+ * evaluations trigger the selector, reducing unnecessary work.
+ *
  * ```tsx
  * const doneCount = useTabSyncSelector(
  *   (s) => s.todos.filter(t => t.done).length,
@@ -58,4 +62,46 @@ declare function useTabSyncSelector<TState extends Record<string, unknown>, TRes
  */
 declare function useIsLeader(): boolean;
 
-export { TabSyncContext, TabSyncProvider, type TabSyncProviderProps, useIsLeader, useTabSync, useTabSyncSelector, useTabSyncValue };
+/**
+ * Subscribe to the list of active tabs. Re-renders when tabs join or leave.
+ *
+ * ```tsx
+ * const tabs = useTabs();
+ * // tabs: TabInfo[]
+ * ```
+ *
+ * Must be used within a `<TabSyncProvider>`.
+ */
+declare function useTabs(): TabInfo[];
+
+/**
+ * Subscribe to the current leader's full `TabInfo`.
+ * Returns `null` if no leader has been elected yet.
+ *
+ * ```tsx
+ * const leader = useLeaderInfo();
+ * // leader: TabInfo | null
+ * ```
+ *
+ * Must be used within a `<TabSyncProvider>`.
+ */
+declare function useLeaderInfo(): TabInfo | null;
+
+interface TabSyncActions<TState extends Record<string, unknown>> {
+    set: TabSyncInstance<TState>['set'];
+    patch: TabSyncInstance<TState>['patch'];
+    transaction: TabSyncInstance<TState>['transaction'];
+}
+/**
+ * Returns `set`, `patch`, and `transaction` without subscribing to state.
+ * Components using only this hook never re-render due to state changes.
+ *
+ * ```tsx
+ * const { set, patch, transaction } = useTabSyncActions();
+ * ```
+ *
+ * Must be used within a `<TabSyncProvider>`.
+ */
+declare function useTabSyncActions<TState extends Record<string, unknown> = Record<string, unknown>>(): TabSyncActions<TState>;
+
+export { type TabSyncActions, TabSyncContext, TabSyncProvider, type TabSyncProviderProps, useIsLeader, useLeaderInfo, useTabSync, useTabSyncActions, useTabSyncSelector, useTabSyncValue, useTabs };

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, c as TabInfo } from '../types-BtK4ixKz.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>;
@@ -35,6 +36,9 @@ declare function useTabSyncValue<TState extends Record<string, unknown>, K exten
  * Subscribe to a **derived value** from the synced state.
  * Only re-renders when the selector's output actually changes.
  *
+ * Uses `instance.select()` internally so only changed-key
+ * evaluations trigger the selector, reducing unnecessary work.
+ *
  * ```tsx
  * const doneCount = useTabSyncSelector(
  *   (s) => s.todos.filter(t => t.done).length,
@@ -58,4 +62,46 @@ declare function useTabSyncSelector<TState extends Record<string, unknown>, TRes
  */
 declare function useIsLeader(): boolean;
 
-export { TabSyncContext, TabSyncProvider, type TabSyncProviderProps, useIsLeader, useTabSync, useTabSyncSelector, useTabSyncValue };
+/**
+ * Subscribe to the list of active tabs. Re-renders when tabs join or leave.
+ *
+ * ```tsx
+ * const tabs = useTabs();
+ * // tabs: TabInfo[]
+ * ```
+ *
+ * Must be used within a `<TabSyncProvider>`.
+ */
+declare function useTabs(): TabInfo[];
+
+/**
+ * Subscribe to the current leader's full `TabInfo`.
+ * Returns `null` if no leader has been elected yet.
+ *
+ * ```tsx
+ * const leader = useLeaderInfo();
+ * // leader: TabInfo | null
+ * ```
+ *
+ * Must be used within a `<TabSyncProvider>`.
+ */
+declare function useLeaderInfo(): TabInfo | null;
+
+interface TabSyncActions<TState extends Record<string, unknown>> {
+    set: TabSyncInstance<TState>['set'];
+    patch: TabSyncInstance<TState>['patch'];
+    transaction: TabSyncInstance<TState>['transaction'];
+}
+/**
+ * Returns `set`, `patch`, and `transaction` without subscribing to state.
+ * Components using only this hook never re-render due to state changes.
+ *
+ * ```tsx
+ * const { set, patch, transaction } = useTabSyncActions();
+ * ```
+ *
+ * Must be used within a `<TabSyncProvider>`.
+ */
+declare function useTabSyncActions<TState extends Record<string, unknown> = Record<string, unknown>>(): TabSyncActions<TState>;
+
+export { type TabSyncActions, TabSyncContext, TabSyncProvider, type TabSyncProviderProps, useIsLeader, useLeaderInfo, useTabSync, useTabSyncActions, useTabSyncSelector, useTabSyncValue, useTabs };

package/dist/react/index.js

@@ -1,5 +1,5 @@
-import { createTabSync } from '../chunk-42VOZR6E.js';
-import { createContext, useRef, useEffect, useCallback, useSyncExternalStore, useContext, useState } from 'react';
+import { createTabSync } from '../chunk-4JDWAUYM.js';
+import { createContext, useRef, useEffect, useCallback, useSyncExternalStore, useContext, useMemo, useState } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 var TabSyncContext = createContext(null);
@@ -125,14 +125,14 @@ function useTabSyncSelector(selector, isEqual) {
     initializedRef.current = true;
   }
   const subscribe = useCallback(
-    (onStoreChange) => instance.onChange(() => {
-      const next = selectorRef.current(instance.getAll());
-      const equal = isEqualRef.current ?? Object.is;
-      if (!equal(resultRef.current, next)) {
+    (onStoreChange) => instance.select(
+      (state) => selectorRef.current(state),
+      (next) => {
         resultRef.current = next;
         onStoreChange();
-      }
-    }),
+      },
+      { isEqual: isEqualRef.current }
+    ),
     [instance]
   );
   const getSnapshot = useCallback(() => resultRef.current, []);
@@ -163,5 +163,75 @@ function useIsLeader() {
   const getServerSnapshot = useCallback(() => SERVER_SNAPSHOT, []);
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
+var SERVER_SNAPSHOT2 = [];
+function useTabs() {
+  const instance = useContext(TabSyncContext);
+  if (!instance) {
+    throw new Error("useTabs must be used within a <TabSyncProvider>");
+  }
+  const tabsRef = useRef(instance.getTabs());
+  const subscribe = useCallback(
+    (onStoreChange) => instance.onTabChange((tabs) => {
+      tabsRef.current = tabs;
+      onStoreChange();
+    }),
+    [instance]
+  );
+  const getSnapshot = useCallback(() => tabsRef.current, []);
+  const getServerSnapshot = useCallback(() => SERVER_SNAPSHOT2, []);
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useLeaderInfo() {
+  const instance = useContext(TabSyncContext);
+  if (!instance) {
+    throw new Error("useLeaderInfo must be used within a <TabSyncProvider>");
+  }
+  const leaderRef = useRef(instance.getLeader());
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      const unsubs = [];
+      unsubs.push(
+        instance.onTabChange(() => {
+          const next = instance.getLeader();
+          if (next?.id !== leaderRef.current?.id) {
+            leaderRef.current = next;
+            onStoreChange();
+          }
+        })
+      );
+      unsubs.push(
+        instance.onLeader(() => {
+          leaderRef.current = instance.getLeader();
+          onStoreChange();
+          return () => {
+            leaderRef.current = instance.getLeader();
+            onStoreChange();
+          };
+        })
+      );
+      return () => {
+        for (const u of unsubs) u();
+      };
+    },
+    [instance]
+  );
+  const getSnapshot = useCallback(() => leaderRef.current, []);
+  const getServerSnapshot = useCallback(() => null, []);
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useTabSyncActions() {
+  const instance = useContext(TabSyncContext);
+  if (!instance) {
+    throw new Error("useTabSyncActions must be used within a <TabSyncProvider>");
+  }
+  return useMemo(
+    () => ({
+      set: instance.set.bind(instance),
+      patch: instance.patch.bind(instance),
+      transaction: instance.transaction.bind(instance)
+    }),
+    [instance]
+  );
+}
 
-export { TabSyncContext, TabSyncProvider, useIsLeader, useTabSync, useTabSyncSelector, useTabSyncValue };
+export { TabSyncContext, TabSyncProvider, useIsLeader, useLeaderInfo, useTabSync, useTabSyncActions, useTabSyncSelector, useTabSyncValue, useTabs };

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 };