use-everywhere 0.4.1 → 0.5.0

package/dist/chunk-YOXUZYKA.js

@@ -0,0 +1,187 @@
+'use client';
+
+// src/registry.ts
+import {
+  createChannel,
+  createLeader,
+  createPresence,
+  createSharedStore,
+  DEFAULT_NAME,
+  NoopTransport
+} from "@use-everywhere/core";
+
+// src/dev.ts
+var inDev = false;
+try {
+  inDev = process.env.NODE_ENV !== "production";
+} catch {
+}
+var warned = /* @__PURE__ */ new Set();
+function devWarn(message) {
+  if (!inDev || warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+var seenInitials = /* @__PURE__ */ new Map();
+function warnOnInitialMismatch(storeName, key, initial) {
+  if (!inDev) return;
+  const id = `${storeName} ${key}`;
+  if (!seenInitials.has(id)) {
+    seenInitials.set(id, initial);
+    return;
+  }
+  const first = seenInitials.get(id);
+  const comparable = (v) => v === null || typeof v !== "object";
+  if (comparable(first) && comparable(initial) && !Object.is(first, initial)) {
+    devWarn(
+      `[use-everywhere] useSharedState('${key}') was called with different initial values (${String(first)} and ${String(initial)}). The first registration wins, so the second is ignored. Define the default once \u2014 defineStore, or a shared constant.`
+    );
+  }
+}
+
+// src/server-stubs.ts
+var SERVER_CLIENT_ID = "";
+var EMPTY = Object.freeze({});
+var NO_PEERS = Object.freeze([]);
+var noop = () => {
+};
+var unsubscribe = () => noop;
+var INERT = Object.freeze({
+  clientId: SERVER_CLIENT_ID,
+  // store
+  state: EMPTY,
+  getVersions: () => EMPTY,
+  set: noop,
+  subscribeKey: unsubscribe,
+  registerKey: noop,
+  // store + leader share getSnapshot; presence has getPeers
+  getSnapshot: () => EMPTY,
+  getPeers: () => NO_PEERS,
+  // leader
+  resign: noop,
+  setEligible: noop,
+  // common
+  subscribe: unsubscribe,
+  close: noop
+});
+var createServerStore = () => INERT;
+var createServerPresence = () => INERT;
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+var createServerLeader = () => ({ ...INERT, getSnapshot: () => NO_LEADER });
+var createServerChannel = (name) => ({ ...INERT, name, post: noop, on: unsubscribe });
+
+// src/registry.ts
+var stores = /* @__PURE__ */ new Map();
+var presences = /* @__PURE__ */ new Map();
+var channels = /* @__PURE__ */ new Map();
+var leaders = /* @__PURE__ */ new Map();
+var storeConfig = /* @__PURE__ */ new Map();
+var isServer = () => typeof window === "undefined";
+var scopeOptions = {
+  everywhere: {},
+  tabs: { accept: (meta) => meta.kind !== "worker" },
+  tab: { transport: () => new NoopTransport() }
+};
+function getSharedStore(name = DEFAULT_NAME, scope = "everywhere") {
+  return getStore(name, scope);
+}
+function configSignature(options) {
+  const persist = options?.persist;
+  if (!persist) return "none";
+  return `persist:${persist.keys?.join(",") ?? "*"}:${persist.debounceMs ?? "default"}`;
+}
+function configureStore(name, scope, options) {
+  const key = `${scope} ${name}`;
+  if (stores.has(key)) {
+    if (configSignature(storeConfig.get(key)) === configSignature(options)) return;
+    devWarn(
+      `[use-everywhere] defineStore('${name}') ran after that store was already created, with different options. The live store keeps the configuration it was built with. Move defineStore to module scope, before any component reads the store.`
+    );
+    return;
+  }
+  storeConfig.set(key, options);
+}
+function getStore(name, scope = "everywhere") {
+  const key = `${scope} ${name}`;
+  let store = stores.get(key);
+  if (!store) {
+    store = isServer() ? createServerStore() : createSharedStore(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
+    stores.set(key, store);
+  }
+  return store;
+}
+function getPresence(name) {
+  let presence = presences.get(name);
+  if (!presence) {
+    presence = isServer() ? createServerPresence() : createPresence(name);
+    presences.set(name, presence);
+  }
+  return presence;
+}
+function getLeader(name, options) {
+  let leader = leaders.get(name);
+  if (!leader) {
+    leader = isServer() ? createServerLeader() : createLeader(name, options);
+    leaders.set(name, leader);
+    if (options) leaderOptions.set(name, options);
+  } else if (options) {
+    warnOnLeaderOptionConflict(name, options);
+  }
+  return leader;
+}
+var leaderOptions = /* @__PURE__ */ new Map();
+function warnOnLeaderOptionConflict(name, options) {
+  const first = leaderOptions.get(name);
+  for (const key of ["heartbeatMs", "leaseMs"]) {
+    const requested = options[key];
+    if (requested !== void 0 && requested !== first?.[key]) {
+      devWarn(
+        `[use-everywhere] leader "${name}": ${key} ignored \u2014 the first useLeader/getLeader call fixes the election timings for this tab.`
+      );
+    }
+  }
+}
+function getChannel(name) {
+  let channel = channels.get(name);
+  if (!channel) {
+    channel = isServer() ? createServerChannel(name) : createChannel(name);
+    channels.set(name, channel);
+  }
+  return channel;
+}
+
+// src/use-peers.ts
+import { useCallback, useSyncExternalStore } from "react";
+var NO_PEERS2 = Object.freeze([]);
+function usePeers(options) {
+  const presence = getPresence(options?.name ?? DEFAULT_NAME);
+  return useSyncExternalStore(
+    useCallback((onChange) => presence.subscribe(onChange), [presence]),
+    () => presence.getPeers(),
+    () => NO_PEERS2
+  );
+}
+function useClientId(options) {
+  const presence = getPresence(options?.name ?? DEFAULT_NAME);
+  return useSyncExternalStore(
+    // The id never changes for the life of a presence engine, so there is
+    // nothing to subscribe to — but uSES still needs the post-hydration read,
+    // which it performs when it attaches this subscription.
+    useCallback(() => () => {
+    }, [presence]),
+    () => presence.clientId,
+    () => SERVER_CLIENT_ID
+  );
+}
+
+export {
+  warnOnInitialMismatch,
+  DEFAULT_NAME,
+  getSharedStore,
+  configureStore,
+  getStore,
+  getLeader,
+  getChannel,
+  usePeers,
+  useClientId
+};

package/dist/devtools/index.cjs

@@ -31,9 +31,41 @@ var import_core2 = require("@use-everywhere/core");
 
 // src/registry.ts
 var import_core = require("@use-everywhere/core");
+
+// src/server-stubs.ts
+var SERVER_CLIENT_ID = "";
+var EMPTY = Object.freeze({});
+var NO_PEERS = Object.freeze([]);
+var noop = () => {
+};
+var unsubscribe = () => noop;
+var INERT = Object.freeze({
+  clientId: SERVER_CLIENT_ID,
+  // store
+  state: EMPTY,
+  getVersions: () => EMPTY,
+  set: noop,
+  subscribeKey: unsubscribe,
+  registerKey: noop,
+  // store + leader share getSnapshot; presence has getPeers
+  getSnapshot: () => EMPTY,
+  getPeers: () => NO_PEERS,
+  // leader
+  resign: noop,
+  setEligible: noop,
+  // common
+  subscribe: unsubscribe,
+  close: noop
+});
+var createServerStore = () => INERT;
+var createServerPresence = () => INERT;
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+
+// src/registry.ts
 var stores = /* @__PURE__ */ new Map();
 var presences = /* @__PURE__ */ new Map();
 var storeConfig = /* @__PURE__ */ new Map();
+var isServer = () => typeof window === "undefined";
 var scopeOptions = {
   everywhere: {},
   tabs: { accept: (meta) => meta.kind !== "worker" },
@@ -46,7 +78,7 @@ function getStore(name, scope = "everywhere") {
   const key = `${scope} ${name}`;
   let store = stores.get(key);
   if (!store) {
-    store = (0, import_core.createSharedStore)(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
+    store = isServer() ? createServerStore() : (0, import_core.createSharedStore)(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
     stores.set(key, store);
   }
   return store;
@@ -54,7 +86,7 @@ function getStore(name, scope = "everywhere") {
 function getPresence(name) {
   let presence = presences.get(name);
   if (!presence) {
-    presence = (0, import_core.createPresence)(name);
+    presence = isServer() ? createServerPresence() : (0, import_core.createPresence)(name);
     presences.set(name, presence);
   }
   return presence;
@@ -62,13 +94,13 @@ function getPresence(name) {
 
 // src/use-peers.ts
 var import_react = require("react");
-var NO_PEERS = Object.freeze([]);
+var NO_PEERS2 = Object.freeze([]);
 function usePeers(options) {
   const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME);
   return (0, import_react.useSyncExternalStore)(
     (0, import_react.useCallback)((onChange) => presence.subscribe(onChange), [presence]),
     () => presence.getPeers(),
-    () => NO_PEERS
+    () => NO_PEERS2
   );
 }
 

package/dist/devtools/index.js

@@ -2,7 +2,7 @@
 import {
   getSharedStore,
   usePeers
-} from "../chunk-PNFJW7QK.js";
+} from "../chunk-YOXUZYKA.js";
 
 // src/devtools/inspector.tsx
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";

package/dist/index.cjs

@@ -43,13 +43,76 @@ module.exports = __toCommonJS(src_exports);
 // src/use-shared-state.ts
 var import_react = require("react");
 
+// src/dev.ts
+var inDev = false;
+try {
+  inDev = process.env.NODE_ENV !== "production";
+} catch {
+}
+var warned = /* @__PURE__ */ new Set();
+function devWarn(message) {
+  if (!inDev || warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+var seenInitials = /* @__PURE__ */ new Map();
+function warnOnInitialMismatch(storeName, key, initial) {
+  if (!inDev) return;
+  const id = `${storeName} ${key}`;
+  if (!seenInitials.has(id)) {
+    seenInitials.set(id, initial);
+    return;
+  }
+  const first = seenInitials.get(id);
+  const comparable = (v) => v === null || typeof v !== "object";
+  if (comparable(first) && comparable(initial) && !Object.is(first, initial)) {
+    devWarn(
+      `[use-everywhere] useSharedState('${key}') was called with different initial values (${String(first)} and ${String(initial)}). The first registration wins, so the second is ignored. Define the default once \u2014 defineStore, or a shared constant.`
+    );
+  }
+}
+
 // src/registry.ts
 var import_core = require("@use-everywhere/core");
+
+// src/server-stubs.ts
+var SERVER_CLIENT_ID = "";
+var EMPTY = Object.freeze({});
+var NO_PEERS = Object.freeze([]);
+var noop = () => {
+};
+var unsubscribe = () => noop;
+var INERT = Object.freeze({
+  clientId: SERVER_CLIENT_ID,
+  // store
+  state: EMPTY,
+  getVersions: () => EMPTY,
+  set: noop,
+  subscribeKey: unsubscribe,
+  registerKey: noop,
+  // store + leader share getSnapshot; presence has getPeers
+  getSnapshot: () => EMPTY,
+  getPeers: () => NO_PEERS,
+  // leader
+  resign: noop,
+  setEligible: noop,
+  // common
+  subscribe: unsubscribe,
+  close: noop
+});
+var createServerStore = () => INERT;
+var createServerPresence = () => INERT;
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+var createServerLeader = () => ({ ...INERT, getSnapshot: () => NO_LEADER });
+var createServerChannel = (name) => ({ ...INERT, name, post: noop, on: unsubscribe });
+
+// src/registry.ts
 var stores = /* @__PURE__ */ new Map();
 var presences = /* @__PURE__ */ new Map();
 var channels = /* @__PURE__ */ new Map();
 var leaders = /* @__PURE__ */ new Map();
 var storeConfig = /* @__PURE__ */ new Map();
+var isServer = () => typeof window === "undefined";
 var scopeOptions = {
   everywhere: {},
   tabs: { accept: (meta) => meta.kind !== "worker" },
@@ -58,12 +121,19 @@ var scopeOptions = {
 function getSharedStore(name = import_core.DEFAULT_NAME, scope = "everywhere") {
   return getStore(name, scope);
 }
+function configSignature(options) {
+  const persist = options?.persist;
+  if (!persist) return "none";
+  return `persist:${persist.keys?.join(",") ?? "*"}:${persist.debounceMs ?? "default"}`;
+}
 function configureStore(name, scope, options) {
   const key = `${scope} ${name}`;
   if (stores.has(key)) {
-    throw new Error(
-      `defineStore('${name}') ran after that store was already created. Move it to module scope \u2014 configuring a live store would silently hand you one without persistence.`
+    if (configSignature(storeConfig.get(key)) === configSignature(options)) return;
+    devWarn(
+      `[use-everywhere] defineStore('${name}') ran after that store was already created, with different options. The live store keeps the configuration it was built with. Move defineStore to module scope, before any component reads the store.`
     );
+    return;
   }
   storeConfig.set(key, options);
 }
@@ -71,7 +141,7 @@ function getStore(name, scope = "everywhere") {
   const key = `${scope} ${name}`;
   let store = stores.get(key);
   if (!store) {
-    store = (0, import_core.createSharedStore)(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
+    store = isServer() ? createServerStore() : (0, import_core.createSharedStore)(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
     stores.set(key, store);
   }
   return store;
@@ -79,7 +149,7 @@ function getStore(name, scope = "everywhere") {
 function getPresence(name) {
   let presence = presences.get(name);
   if (!presence) {
-    presence = (0, import_core.createPresence)(name);
+    presence = isServer() ? createServerPresence() : (0, import_core.createPresence)(name);
     presences.set(name, presence);
   }
   return presence;
@@ -87,15 +157,30 @@ function getPresence(name) {
 function getLeader(name, options) {
   let leader = leaders.get(name);
   if (!leader) {
-    leader = (0, import_core.createLeader)(name, options);
+    leader = isServer() ? createServerLeader() : (0, import_core.createLeader)(name, options);
     leaders.set(name, leader);
+    if (options) leaderOptions.set(name, options);
+  } else if (options) {
+    warnOnLeaderOptionConflict(name, options);
   }
   return leader;
 }
+var leaderOptions = /* @__PURE__ */ new Map();
+function warnOnLeaderOptionConflict(name, options) {
+  const first = leaderOptions.get(name);
+  for (const key of ["heartbeatMs", "leaseMs"]) {
+    const requested = options[key];
+    if (requested !== void 0 && requested !== first?.[key]) {
+      devWarn(
+        `[use-everywhere] leader "${name}": ${key} ignored \u2014 the first useLeader/getLeader call fixes the election timings for this tab.`
+      );
+    }
+  }
+}
 function getChannel(name) {
   let channel = channels.get(name);
   if (!channel) {
-    channel = (0, import_core.createChannel)(name);
+    channel = isServer() ? createServerChannel(name) : (0, import_core.createChannel)(name);
     channels.set(name, channel);
   }
   return channel;
@@ -103,8 +188,10 @@ function getChannel(name) {
 
 // src/use-shared-state.ts
 function useSharedState(key, initial, options) {
-  const store = getStore(options?.store ?? import_core.DEFAULT_NAME, options?.scope ?? "everywhere");
+  const storeName = options?.store ?? import_core.DEFAULT_NAME;
+  const store = getStore(storeName, options?.scope ?? "everywhere");
   store.registerKey(key, initial);
+  warnOnInitialMismatch(storeName, key, initial);
   const value = (0, import_react.useSyncExternalStore)(
     (0, import_react.useCallback)((onChange) => store.subscribeKey(key, onChange), [store, key]),
     () => store.getSnapshot()[key],
@@ -167,22 +254,31 @@ function defineStore(name, options = {}) {
 
 // src/use-peers.ts
 var import_react3 = require("react");
-var NO_PEERS = Object.freeze([]);
+var NO_PEERS2 = Object.freeze([]);
 function usePeers(options) {
   const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME);
   return (0, import_react3.useSyncExternalStore)(
     (0, import_react3.useCallback)((onChange) => presence.subscribe(onChange), [presence]),
     () => presence.getPeers(),
-    () => NO_PEERS
+    () => NO_PEERS2
   );
 }
 function useClientId(options) {
-  return getPresence(options?.name ?? import_core.DEFAULT_NAME).clientId;
+  const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME);
+  return (0, import_react3.useSyncExternalStore)(
+    // The id never changes for the life of a presence engine, so there is
+    // nothing to subscribe to — but uSES still needs the post-hydration read,
+    // which it performs when it attaches this subscription.
+    (0, import_react3.useCallback)(() => () => {
+    }, [presence]),
+    () => presence.clientId,
+    () => SERVER_CLIENT_ID
+  );
 }
 
 // src/use-leader.ts
 var import_react4 = require("react");
-var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+var NO_LEADER2 = Object.freeze({ leaderId: null, isLeader: false });
 function useLeader(options) {
   const leader = getLeader(options?.name ?? import_core.DEFAULT_NAME, options);
   const eligible = options?.eligible;
@@ -193,7 +289,7 @@ function useLeader(options) {
   return (0, import_react4.useSyncExternalStore)(
     (0, import_react4.useCallback)((onChange) => leader.subscribe(onChange), [leader]),
     () => leader.getSnapshot(),
-    () => NO_LEADER
+    () => NO_LEADER2
   );
 }
 function useIsLeader(options) {
@@ -214,31 +310,36 @@ function useLeaderEffect(effect, options) {
 // src/use-opened-window.ts
 var import_react5 = require("react");
 var import_core2 = require("@use-everywhere/core");
+var IDLE = Object.freeze({
+  status: "idle",
+  result: void 0,
+  error: void 0
+});
 function useOpenedWindow(factory) {
-  const [status, setStatus] = (0, import_react5.useState)("idle");
-  const [result, setResult] = (0, import_react5.useState)(void 0);
-  const [error, setError] = (0, import_react5.useState)(void 0);
+  const [state, setState] = (0, import_react5.useState)(IDLE);
   const current = (0, import_react5.useRef)(null);
   const factoryRef = (0, import_react5.useRef)(factory);
-  factoryRef.current = factory;
+  (0, import_react5.useEffect)(() => {
+    factoryRef.current = factory;
+  });
   const open = (0, import_react5.useCallback)(() => {
     current.current?.close();
     let opened;
     try {
       opened = factoryRef.current();
     } catch (err) {
-      setStatus("error");
-      setError(err);
+      setState({ status: "error", result: void 0, error: err });
       return;
     }
     current.current = opened;
-    setStatus("opening");
-    setResult(void 0);
-    setError(void 0);
+    setState({ status: "opening", result: void 0, error: void 0 });
     const fresh = () => current.current === opened;
     opened.ready.then(
       () => {
-        if (fresh()) setStatus((s) => s === "opening" ? "connected" : s);
+        if (!fresh()) return;
+        setState(
+          (s) => s.status === "opening" ? { status: "connected", result: void 0, error: void 0 } : s
+        );
       },
       () => {
       }
@@ -246,14 +347,13 @@ function useOpenedWindow(factory) {
     );
     opened.result.then(
       (value) => {
-        if (!fresh()) return;
-        setResult(value);
-        setStatus("done");
+        if (fresh()) setState({ status: "done", result: value, error: void 0 });
       },
       (err) => {
         if (!fresh()) return;
-        setError(err);
-        setStatus(err instanceof import_core2.WindowClosedError ? "closed-early" : "error");
+        setState(
+          err instanceof import_core2.WindowClosedError ? { status: "closed-early", result: void 0, error: err } : { status: "error", result: void 0, error: err }
+        );
       }
     );
   }, []);
@@ -261,7 +361,7 @@ function useOpenedWindow(factory) {
     current.current?.post(type, payload);
   }, []);
   const close = (0, import_react5.useCallback)(() => current.current?.close(), []);
-  return { open, status, result, error, post, close };
+  return { ...state, open, post, close };
 }
 
 // src/index.ts

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow } from '@use-everywhere/core';
+import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow, WindowClosedError } from '@use-everywhere/core';
 export * from '@use-everywhere/core';
 export { DEFAULT_NAME } from '@use-everywhere/core';
 
@@ -21,6 +21,12 @@ interface UseSharedStateOptions {
  * this origin. Late-joining tabs hydrate to the current value; concurrent
  * writes converge last-writer-wins. Pass options.scope to delimit how much
  * is shared ('everywhere' | 'tabs' | 'tab').
+ *
+ * Note the convergence rule is last-writer-wins per key, not per operation:
+ * two tabs running `set(n => n + 1)` at the same moment agree on one value,
+ * and one of the increments is lost. For counters and other accumulating
+ * writes, drive them from a single tab (useLeaderEffect) until an op-based
+ * primitive lands.
  */
 declare function useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
 
@@ -105,7 +111,16 @@ declare function defineStore<S extends Record<string, unknown> = Record<string,
 declare function usePeers(options?: {
     name?: string;
 }): readonly Peer[];
-/** This client's own id on the presence bus (matches patch origin ids). */
+/**
+ * This client's own id on the presence bus (matches patch origin ids).
+ *
+ * Read through useSyncExternalStore rather than returned straight from render,
+ * because the id is minted per environment: a server would render one value and
+ * the browser a different one, and any component that puts it in the DOM would
+ * mismatch on hydration. The server snapshot is a constant empty string, which
+ * React also uses for the client's hydrating render, so markup matches; the
+ * real id arrives in the commit straight after. Treat `''` as "not known yet".
+ */
 declare function useClientId(options?: {
     name?: string;
 }): string;
@@ -130,23 +145,59 @@ declare function useIsLeader(options?: UseLeaderOptions): boolean;
 declare function useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
 
 type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
-interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
+/**
+ * The flow's state as a discriminated union, so `status` narrows `result` and
+ * `error` for you. Three independent fields could not: `result` was `R |
+ * undefined` even in the 'done' branch, which is why reading it needed a
+ * non-null assertion at every call site.
+ */
+type OpenedWindowState<R> = {
+    status: 'idle';
+    result: undefined;
+    error: undefined;
+} | {
+    status: 'opening';
+    result: undefined;
+    error: undefined;
+} | {
+    status: 'connected';
+    result: undefined;
+    error: undefined;
+} | {
+    status: 'done';
+    result: R;
+    error: undefined;
+}
+/** The child window went away before calling finish(). */
+ | {
+    status: 'closed-early';
+    result: undefined;
+    error: WindowClosedError;
+}
+/** The handshake timed out, the popup was blocked, or the factory threw. */
+ | {
+    status: 'error';
+    result: undefined;
+    error: unknown;
+};
+interface OpenedWindowControls<Out extends MessageMap, In extends MessageMap, R> {
     /** Call from a click handler (popup blockers require a user gesture). */
     open: () => void;
-    status: OpenedWindowStatus;
-    /** The child's finish() value, once status is 'done'. */
-    result: R | undefined;
-    error: unknown;
     /** Post to the child; no-op while nothing is open. */
     post: OpenedWindow<Out, In, R>['post'];
     close: () => void;
 }
+type UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> = OpenedWindowState<R> & OpenedWindowControls<Out, In, R>;
 
 /**
  * Drive an openWindow() flow from a component: the factory is called on
  * open(), and the child window's lifecycle is folded into render state.
  * Reopening replaces the previous window; a stale window's outcome is ignored.
+ *
+ * The child window deliberately outlives an unmount: closing a payment page
+ * because a route changed would lose the user's in-flight transaction. Call
+ * close() if the component owns the window's lifetime.
  */
 declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
 
-export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowControls, type OpenedWindowState, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow } from '@use-everywhere/core';
+import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow, WindowClosedError } from '@use-everywhere/core';
 export * from '@use-everywhere/core';
 export { DEFAULT_NAME } from '@use-everywhere/core';
 
@@ -21,6 +21,12 @@ interface UseSharedStateOptions {
  * this origin. Late-joining tabs hydrate to the current value; concurrent
  * writes converge last-writer-wins. Pass options.scope to delimit how much
  * is shared ('everywhere' | 'tabs' | 'tab').
+ *
+ * Note the convergence rule is last-writer-wins per key, not per operation:
+ * two tabs running `set(n => n + 1)` at the same moment agree on one value,
+ * and one of the increments is lost. For counters and other accumulating
+ * writes, drive them from a single tab (useLeaderEffect) until an op-based
+ * primitive lands.
  */
 declare function useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
 
@@ -105,7 +111,16 @@ declare function defineStore<S extends Record<string, unknown> = Record<string,
 declare function usePeers(options?: {
     name?: string;
 }): readonly Peer[];
-/** This client's own id on the presence bus (matches patch origin ids). */
+/**
+ * This client's own id on the presence bus (matches patch origin ids).
+ *
+ * Read through useSyncExternalStore rather than returned straight from render,
+ * because the id is minted per environment: a server would render one value and
+ * the browser a different one, and any component that puts it in the DOM would
+ * mismatch on hydration. The server snapshot is a constant empty string, which
+ * React also uses for the client's hydrating render, so markup matches; the
+ * real id arrives in the commit straight after. Treat `''` as "not known yet".
+ */
 declare function useClientId(options?: {
     name?: string;
 }): string;
@@ -130,23 +145,59 @@ declare function useIsLeader(options?: UseLeaderOptions): boolean;
 declare function useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
 
 type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
-interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
+/**
+ * The flow's state as a discriminated union, so `status` narrows `result` and
+ * `error` for you. Three independent fields could not: `result` was `R |
+ * undefined` even in the 'done' branch, which is why reading it needed a
+ * non-null assertion at every call site.
+ */
+type OpenedWindowState<R> = {
+    status: 'idle';
+    result: undefined;
+    error: undefined;
+} | {
+    status: 'opening';
+    result: undefined;
+    error: undefined;
+} | {
+    status: 'connected';
+    result: undefined;
+    error: undefined;
+} | {
+    status: 'done';
+    result: R;
+    error: undefined;
+}
+/** The child window went away before calling finish(). */
+ | {
+    status: 'closed-early';
+    result: undefined;
+    error: WindowClosedError;
+}
+/** The handshake timed out, the popup was blocked, or the factory threw. */
+ | {
+    status: 'error';
+    result: undefined;
+    error: unknown;
+};
+interface OpenedWindowControls<Out extends MessageMap, In extends MessageMap, R> {
     /** Call from a click handler (popup blockers require a user gesture). */
     open: () => void;
-    status: OpenedWindowStatus;
-    /** The child's finish() value, once status is 'done'. */
-    result: R | undefined;
-    error: unknown;
     /** Post to the child; no-op while nothing is open. */
     post: OpenedWindow<Out, In, R>['post'];
     close: () => void;
 }
+type UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> = OpenedWindowState<R> & OpenedWindowControls<Out, In, R>;
 
 /**
  * Drive an openWindow() flow from a component: the factory is called on
  * open(), and the child window's lifecycle is folded into render state.
  * Reopening replaces the previous window; a stale window's outcome is ignored.
+ *
+ * The child window deliberately outlives an unmount: closing a payment page
+ * because a route changed would lose the user's in-flight transaction. Call
+ * close() if the component owns the window's lifetime.
  */
 declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
 
-export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowControls, type OpenedWindowState, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };

package/dist/index.js

@@ -7,14 +7,17 @@ import {
   getSharedStore,
   getStore,
   useClientId,
-  usePeers
-} from "./chunk-PNFJW7QK.js";
+  usePeers,
+  warnOnInitialMismatch
+} from "./chunk-YOXUZYKA.js";
 
 // src/use-shared-state.ts
 import { useCallback, useSyncExternalStore } from "react";
 function useSharedState(key, initial, options) {
-  const store = getStore(options?.store ?? DEFAULT_NAME, options?.scope ?? "everywhere");
+  const storeName = options?.store ?? DEFAULT_NAME;
+  const store = getStore(storeName, options?.scope ?? "everywhere");
   store.registerKey(key, initial);
+  warnOnInitialMismatch(storeName, key, initial);
   const value = useSyncExternalStore(
     useCallback((onChange) => store.subscribeKey(key, onChange), [store, key]),
     () => store.getSnapshot()[key],
@@ -107,33 +110,38 @@ function useLeaderEffect(effect, options) {
 }
 
 // src/use-opened-window.ts
-import { useCallback as useCallback3, useRef as useRef3, useState } from "react";
+import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef3, useState } from "react";
 import { WindowClosedError } from "@use-everywhere/core";
+var IDLE = Object.freeze({
+  status: "idle",
+  result: void 0,
+  error: void 0
+});
 function useOpenedWindow(factory) {
-  const [status, setStatus] = useState("idle");
-  const [result, setResult] = useState(void 0);
-  const [error, setError] = useState(void 0);
+  const [state, setState] = useState(IDLE);
   const current = useRef3(null);
   const factoryRef = useRef3(factory);
-  factoryRef.current = factory;
+  useEffect3(() => {
+    factoryRef.current = factory;
+  });
   const open = useCallback3(() => {
     current.current?.close();
     let opened;
     try {
       opened = factoryRef.current();
     } catch (err) {
-      setStatus("error");
-      setError(err);
+      setState({ status: "error", result: void 0, error: err });
       return;
     }
     current.current = opened;
-    setStatus("opening");
-    setResult(void 0);
-    setError(void 0);
+    setState({ status: "opening", result: void 0, error: void 0 });
     const fresh = () => current.current === opened;
     opened.ready.then(
       () => {
-        if (fresh()) setStatus((s) => s === "opening" ? "connected" : s);
+        if (!fresh()) return;
+        setState(
+          (s) => s.status === "opening" ? { status: "connected", result: void 0, error: void 0 } : s
+        );
       },
       () => {
       }
@@ -141,14 +149,13 @@ function useOpenedWindow(factory) {
     );
     opened.result.then(
       (value) => {
-        if (!fresh()) return;
-        setResult(value);
-        setStatus("done");
+        if (fresh()) setState({ status: "done", result: value, error: void 0 });
       },
       (err) => {
         if (!fresh()) return;
-        setError(err);
-        setStatus(err instanceof WindowClosedError ? "closed-early" : "error");
+        setState(
+          err instanceof WindowClosedError ? { status: "closed-early", result: void 0, error: err } : { status: "error", result: void 0, error: err }
+        );
       }
     );
   }, []);
@@ -156,7 +163,7 @@ function useOpenedWindow(factory) {
     current.current?.post(type, payload);
   }, []);
   const close = useCallback3(() => current.current?.close(), []);
-  return { open, status, result, error, post, close };
+  return { ...state, open, post, close };
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-everywhere",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "React hooks for state and messages shared across tabs, windows, and workers",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -59,43 +59,43 @@
       "name": "everything (import *)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "5.4 kB"
+      "limit": "6.6 kB"
     },
     {
       "name": "useSharedState",
       "path": "dist/index.js",
       "import": "{ useSharedState }",
-      "limit": "1.8 kB"
+      "limit": "2.85 kB"
     },
     {
       "name": "useChannel + useMessage + useSend",
       "path": "dist/index.js",
       "import": "{ useChannel, useMessage, useSend }",
-      "limit": "1 kB"
+      "limit": "1.6 kB"
     },
     {
       "name": "usePeers + useClientId",
       "path": "dist/index.js",
       "import": "{ usePeers, useClientId }",
-      "limit": "1.1 kB"
+      "limit": "1.7 kB"
     },
     {
       "name": "useOpenedWindow + openWindow",
       "path": "dist/index.js",
       "import": "{ useOpenedWindow, openWindow }",
-      "limit": "1.4 kB"
+      "limit": "1.5 kB"
     },
     {
       "name": "useLeader + useLeaderEffect",
       "path": "dist/index.js",
       "import": "{ useLeader, useLeaderEffect }",
-      "limit": "1.8 kB"
+      "limit": "2.15 kB"
     },
     {
       "name": "defineStore (persisted)",
       "path": "dist/index.js",
       "import": "{ defineStore, localStorageAdapter }",
-      "limit": "2.3 kB"
+      "limit": "3.3 kB"
     },
     {
       "name": "Inspector (devtools subpath)",
@@ -105,7 +105,7 @@
     }
   ],
   "dependencies": {
-    "@use-everywhere/core": "0.4.1"
+    "@use-everywhere/core": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/dist/chunk-PNFJW7QK.js

@@ -1,92 +0,0 @@
-'use client';
-
-// src/registry.ts
-import {
-  createChannel,
-  createLeader,
-  createPresence,
-  createSharedStore,
-  DEFAULT_NAME,
-  NoopTransport
-} from "@use-everywhere/core";
-var stores = /* @__PURE__ */ new Map();
-var presences = /* @__PURE__ */ new Map();
-var channels = /* @__PURE__ */ new Map();
-var leaders = /* @__PURE__ */ new Map();
-var storeConfig = /* @__PURE__ */ new Map();
-var scopeOptions = {
-  everywhere: {},
-  tabs: { accept: (meta) => meta.kind !== "worker" },
-  tab: { transport: () => new NoopTransport() }
-};
-function getSharedStore(name = DEFAULT_NAME, scope = "everywhere") {
-  return getStore(name, scope);
-}
-function configureStore(name, scope, options) {
-  const key = `${scope} ${name}`;
-  if (stores.has(key)) {
-    throw new Error(
-      `defineStore('${name}') ran after that store was already created. Move it to module scope \u2014 configuring a live store would silently hand you one without persistence.`
-    );
-  }
-  storeConfig.set(key, options);
-}
-function getStore(name, scope = "everywhere") {
-  const key = `${scope} ${name}`;
-  let store = stores.get(key);
-  if (!store) {
-    store = createSharedStore(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
-    stores.set(key, store);
-  }
-  return store;
-}
-function getPresence(name) {
-  let presence = presences.get(name);
-  if (!presence) {
-    presence = createPresence(name);
-    presences.set(name, presence);
-  }
-  return presence;
-}
-function getLeader(name, options) {
-  let leader = leaders.get(name);
-  if (!leader) {
-    leader = createLeader(name, options);
-    leaders.set(name, leader);
-  }
-  return leader;
-}
-function getChannel(name) {
-  let channel = channels.get(name);
-  if (!channel) {
-    channel = createChannel(name);
-    channels.set(name, channel);
-  }
-  return channel;
-}
-
-// src/use-peers.ts
-import { useCallback, useSyncExternalStore } from "react";
-var NO_PEERS = Object.freeze([]);
-function usePeers(options) {
-  const presence = getPresence(options?.name ?? DEFAULT_NAME);
-  return useSyncExternalStore(
-    useCallback((onChange) => presence.subscribe(onChange), [presence]),
-    () => presence.getPeers(),
-    () => NO_PEERS
-  );
-}
-function useClientId(options) {
-  return getPresence(options?.name ?? DEFAULT_NAME).clientId;
-}
-
-export {
-  DEFAULT_NAME,
-  getSharedStore,
-  configureStore,
-  getStore,
-  getLeader,
-  getChannel,
-  usePeers,
-  useClientId
-};