use-everywhere 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # use-everywhere
 
-React hooks for state and messages that exist in every tab, window, and worker.
+React hooks for state and messages that exist in every tab, window, and
+worker — plus a secure channel to windows on other origins.
 
 ```bash
 npm i use-everywhere
@@ -8,72 +9,148 @@ npm i use-everywhere
 
 Two transports behind one library:
 
-- **BroadcastChannel** (same-origin): shared state with last-writer-wins version
-  clocks and a late-joiner handshake, typed pub/sub events, and peer presence.
+- **BroadcastChannel** (same-origin): shared state with last-writer-wins
+  version clocks and a late-joiner handshake, typed pub/sub events, and peer
+  presence.
 - **window.opener / postMessage** (cross-origin): a secure 1:1 channel to a
   window you opened — e.g. a payment page on another domain that must report
-  back to the checkout that opened it. Every message is validated by origin,
-  envelope brand, a per-connection nonce, and the source window.
+  back to the checkout that opened it.
 
-## Usage
+## Shared state: `useSharedState`
+
+`useState`, but the value exists in every tab on your origin. Late-joining
+tabs hydrate to the current value; concurrent writes converge to one winner.
+
+```tsx
+import { useSharedState } from 'use-everywhere';
+
+function Counter() {
+  const [count, setCount] = useSharedState('count', 0);
+  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
+}
+```
+
+The third argument delimits how far a value travels:
 
 ```tsx
-import {
-  useSharedState,
-  useChannel,
-  useMessage,
-  usePeers,
-  useOpenedWindow,
-  openWindow,
-} from 'use-everywhere';
-
-// useState, but the value exists in every tab/window/worker on this origin.
-const [count, setCount] = useSharedState('count', 0);
-
-// Typed fire-and-forget events between tabs.
-const channel = useChannel<{ 'cart-updated': { items: number } }>('shop');
-useMessage(channel, 'cart-updated', ({ items }) => refresh(items));
-channel.post('cart-updated', { items: 3 });
-
-// Who else is here?
-const peers = usePeers();
-
-// Open a window on ANOTHER origin and await its result.
-const pay = useOpenedWindow(() =>
-  openWindow<ToPayment, FromPayment, Receipt>('https://pay.example.com/checkout', {
-    peerOrigin: 'https://pay.example.com',
-  }),
-);
-// pay.open() from a click handler; pay.status: idle → opening → connected → done
-// pay.result is the child's finish() value; closing early yields 'closed-early'.
+useSharedState('draft', '', { scope: 'everywhere' }); // tabs + windows + workers (default)
+useSharedState('draft', '', { scope: 'tabs' }); // ignore writes from workers
+useSharedState('draft', '', { scope: 'tab' }); // this tab only
 ```
 
-On the opened (child) page:
+## Events: `defineChannel`
+
+Typed fire-and-forget messages for things that _happen_ (state is for things
+that _are_). Not echoed to the sender; no history for late joiners. Bind the
+channel's name and message map once at module level; every component gets
+fully typed hooks with nothing to repeat:
+
+```tsx
+import { defineChannel } from 'use-everywhere';
+import { useState } from 'react';
+
+type ShopEvents = { 'cart-updated': { items: number } };
+const shop = defineChannel<ShopEvents>('shop');
+
+function CartBadge() {
+  const [items, setItems] = useState(0);
+  const send = shop.useSend();
+
+  // Fires when any OTHER tab posts 'cart-updated'.
+  shop.useMessage('cart-updated', (payload) => setItems(payload.items));
+
+  const addToCart = () => {
+    setItems(items + 1); // this tab
+    send('cart-updated', { items: items + 1 }); // every other tab
+  };
+
+  return <button onClick={addToCart}>Cart ({items})</button>;
+}
+```
 
-```ts
+The standalone hooks — `useChannel(name)`, `useMessage(channel, type,
+handler)`, `useSend(channel)` — are the same machinery without the
+module-level binding, for one-off use.
+
+## Presence: `usePeers`
+
+```tsx
+import { usePeers } from 'use-everywhere';
+
+function DuplicateTabWarning() {
+  const peers = usePeers();
+  if (peers.length === 0) return null;
+  return <p>⚠ This page is open in {peers.length} other tab(s).</p>;
+}
+```
+
+## Cross-origin windows: `useOpenedWindow`
+
+Open a window on another domain, exchange typed messages, and await its
+result — the whole lifecycle folded into render state.
+
+```tsx
+import { openWindow, useOpenedWindow } from 'use-everywhere';
+
+type ToPayment = { order: { orderId: string; amount: string } };
+type FromPayment = { progress: { step: string } };
+type Receipt = { receiptId: string; last4: string };
+
+function PayButton() {
+  const pay = useOpenedWindow<ToPayment, FromPayment, Receipt>(() =>
+    openWindow('https://pay.example.com/checkout', {
+      peerOrigin: 'https://pay.example.com', // required — '*' throws
+    }),
+  );
+
+  if (pay.status === 'done') return <p>Paid — receipt {pay.result!.receiptId}</p>;
+  if (pay.status === 'closed-early') return <p>Payment window was closed.</p>;
+
+  return (
+    <button onClick={pay.open} disabled={pay.status !== 'idle'}>
+      {pay.status === 'idle' ? 'Pay in secure window' : 'Waiting for payment…'}
+    </button>
+  );
+}
+```
+
+On the opened page (the other domain), use the core API:
+
+```tsx
 import { connectToOpener } from 'use-everywhere';
 
 const conn = connectToOpener<ToPayment, FromPayment, Receipt>({
   peerOrigin: 'https://shop.example.com',
 });
-conn.on('order', (order) => render(order));
-conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's result
+conn.on('order', (order) => setOrder(order)); // e.g. a useState setter
+conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's pay.result
 ```
 
+Messages sent before the (possibly slow-loading) child connects are queued,
+never dropped, and every received message is validated by origin, envelope,
+per-connection nonce, and source window.
+
 ## Design notes
 
 - **Shared state never crosses origins.** Two origins are two trust domains;
   the cross-origin channel is explicit, per-message, and typed.
 - **No Provider.** A BroadcastChannel is already global to the origin —
   identity is the channel name, so hooks share module-level singletons.
-- Values must survive structured clone (no functions, DOM nodes, etc.).
+  Imperative access to the same stores: `getSharedStore(name)`.
+- SSR-safe: hooks render initial values on the server via
+  `getServerSnapshot`; no `BroadcastChannel` needed there.
+- Values must survive structured clone (no functions, DOM nodes); state lives
+  as long as at least one context holds it — nothing is persisted.
+- Testing is first-class: inject a `MemoryHub` transport to simulate many tabs
+  in one test. See the [testing guide](https://rxova.github.io/use-everywhere/guides/testing).
 
 This package re-exports the full framework-agnostic surface of
 [`@use-everywhere/core`](https://www.npmjs.com/package/@use-everywhere/core),
 so you never need to install core directly.
 
-Full docs, demo app (including a real cross-origin payment flow), and source:
-[github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
+📖 **[Documentation](https://rxova.github.io/use-everywhere/)** — mental
+model, how sync works, security model, recipes, and generated API reference.
+Source and demo app: [github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
 
 ## License
 

package/dist/chunk-Y67BCTU6.js

@@ -0,0 +1,90 @@
+// 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
+};

package/dist/devtools/index.d.ts

@@ -0,0 +1,35 @@
+import * as react from 'react';
+
+interface InspectorProps {
+    /** Which bus to watch. Defaults to the shared default name. */
+    name?: string;
+    /** Corner to dock in. Default 'bottom-right'. */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** How many wires to keep in the log. Default 50. */
+    limit?: number;
+    /** Start expanded. Default false. */
+    defaultOpen?: boolean;
+    /**
+     * How long a leader wire keeps the crown before it is treated as stale.
+     * Should match the Leader's leaseMs. Default 3000.
+     */
+    leaseMs?: number;
+}
+
+/**
+ * A floating panel showing what this tab is saying and hearing on the bus:
+ * peers, the leader, store keys with their version clocks, and a live wire log
+ * in both directions.
+ *
+ * It deliberately does **not** create a Leader. Under dynamic eligibility,
+ * mounting one with `eligible: false` would disable candidacy for the whole
+ * tab, and mounting a plain one would enrol a tab that never asked to be a
+ * candidate — a devtool must not change what it measures. Instead it reads the
+ * crown out of the wire log, which it already sees in both directions.
+ *
+ * Presence is fine to use: the bus heartbeats regardless of whether anything
+ * created a Presence, so usePeers observes rather than perturbs.
+ */
+declare function Inspector({ name, position, limit, defaultOpen, leaseMs, }?: InspectorProps): react.JSX.Element;
+
+export { Inspector, type InspectorProps };

package/dist/devtools/index.js

@@ -0,0 +1,216 @@
+import {
+  getSharedStore,
+  usePeers
+} from "../chunk-Y67BCTU6.js";
+
+// src/devtools/inspector.tsx
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { DEFAULT_NAME, observeBus } from "@use-everywhere/core";
+
+// src/devtools/styles.ts
+var STYLES = `
+.ue-ins {
+  position: fixed;
+  z-index: 2147483000;
+  font: 12px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: #e6edf3;
+  background: #0d1117;
+  border: 1px solid #30363d;
+  border-radius: 8px;
+  box-shadow: 0 8px 32px rgb(0 0 0 / 0.4);
+  max-width: min(420px, calc(100vw - 24px));
+  overflow: hidden;
+}
+.ue-ins--bottom-right { bottom: 12px; right: 12px; }
+.ue-ins--bottom-left  { bottom: 12px; left: 12px; }
+.ue-ins--top-right    { top: 12px; right: 12px; }
+.ue-ins--top-left     { top: 12px; left: 12px; }
+
+.ue-ins__bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 7px 10px;
+  background: #161b22;
+  border: 0;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  text-align: left;
+}
+.ue-ins__dot { width: 7px; height: 7px; border-radius: 50%; background: #3fb950; flex: none; }
+.ue-ins__title { font-weight: 600; }
+.ue-ins__muted { color: #8b949e; }
+.ue-ins__crown { margin-left: auto; color: #d29922; }
+
+.ue-ins__body { max-height: 60vh; overflow-y: auto; }
+.ue-ins__section { border-top: 1px solid #21262d; padding: 8px 10px; }
+.ue-ins__h {
+  color: #8b949e;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 10px;
+  margin-bottom: 5px;
+}
+.ue-ins__row { display: flex; gap: 8px; padding: 1px 0; }
+.ue-ins__k { color: #79c0ff; flex: none; }
+.ue-ins__v { color: #e6edf3; overflow-wrap: anywhere; }
+.ue-ins__ver { color: #6e7681; margin-left: auto; flex: none; }
+.ue-ins__empty { color: #6e7681; }
+
+.ue-ins__log { display: flex; flex-direction: column-reverse; max-height: 190px; overflow-y: auto; }
+.ue-ins__wire { display: flex; gap: 7px; padding: 1px 0; white-space: nowrap; }
+.ue-ins__dir { flex: none; width: 9px; }
+.ue-ins__dir--out { color: #d29922; }
+.ue-ins__dir--in { color: #3fb950; }
+.ue-ins__scope { color: #e6edf3; }
+.ue-ins__from { color: #6e7681; margin-left: auto; }
+`;
+
+// src/devtools/inspector.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var short = (id) => id.slice(0, 6);
+function wireLabel(wire) {
+  return `${wire.scope}/${wire.type}`;
+}
+function Inspector({
+  name = DEFAULT_NAME,
+  position = "bottom-right",
+  limit = 50,
+  defaultOpen = false,
+  leaseMs = 3e3
+} = {}) {
+  const [open, setOpen] = useState(defaultOpen);
+  const [wires, setWires] = useState([]);
+  const [crown, setCrown] = useState(null);
+  const nextId = useRef(0);
+  const crownAt = useRef(0);
+  const peers = usePeers({ name });
+  const store = getSharedStore(name);
+  const subscribe = useCallback((onChange) => store.subscribe(onChange), [store]);
+  const snapshot = useSyncExternalStore(
+    subscribe,
+    () => store.getSnapshot(),
+    () => store.getSnapshot()
+  );
+  const versions = useSyncExternalStore(
+    subscribe,
+    () => store.getVersions(),
+    () => store.getVersions()
+  );
+  useEffect(() => {
+    return observeBus(name, (event) => {
+      const { wire, direction } = event;
+      if (wire.scope === "leader") {
+        if (wire.type === "resign") {
+          setCrown(null);
+          crownAt.current = 0;
+        } else if (wire.type === "claim" || wire.type === "heartbeat") {
+          setCrown(wire.clientId);
+          crownAt.current = Date.now();
+        }
+      }
+      setWires(
+        (prev) => [
+          ...prev.slice(-(limit - 1)),
+          {
+            id: nextId.current++,
+            direction,
+            label: wireLabel(wire),
+            from: short(wire.clientId)
+          }
+        ].slice(-limit)
+      );
+    });
+  }, [name, limit]);
+  useEffect(() => {
+    const timer = setInterval(
+      () => {
+        if (crownAt.current && Date.now() - crownAt.current > leaseMs) {
+          setCrown(null);
+          crownAt.current = 0;
+        }
+      },
+      // Quarter of the lease, so a vacated crown clears well within it. The
+      // floor is low enough that a short lease still works rather than being
+      // silently rounded up to something coarser than the lease itself.
+      Math.max(50, Math.floor(leaseMs / 4))
+    );
+    return () => clearInterval(timer);
+  }, [leaseMs]);
+  const selfId = store.clientId;
+  const entries = Object.entries(versions);
+  return /* @__PURE__ */ jsxs("div", { className: `ue-ins ue-ins--${position}`, "data-testid": "ue-inspector", children: [
+    /* @__PURE__ */ jsx("style", { children: STYLES }),
+    /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        className: "ue-ins__bar",
+        onClick: () => setOpen((v) => !v),
+        "aria-expanded": open,
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__dot" }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__title", children: "use-everywhere" }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__muted", children: name }),
+          crown ? /* @__PURE__ */ jsxs("span", { className: "ue-ins__crown", "data-testid": "ue-crown", children: [
+            "\u2654 ",
+            crown === selfId ? "this tab" : short(crown)
+          ] }) : null
+        ]
+      }
+    ),
+    open ? /* @__PURE__ */ jsxs("div", { className: "ue-ins__body", children: [
+      /* @__PURE__ */ jsxs("div", { className: "ue-ins__section", children: [
+        /* @__PURE__ */ jsx("div", { className: "ue-ins__h", children: "This tab" }),
+        /* @__PURE__ */ jsxs("div", { className: "ue-ins__row", children: [
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__k", children: short(selfId) }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__v", children: crown === selfId ? "leader" : crown ? "follower" : "no leader" })
+        ] })
+      ] }),
+      /* @__PURE__ */ jsxs("div", { className: "ue-ins__section", children: [
+        /* @__PURE__ */ jsxs("div", { className: "ue-ins__h", children: [
+          "Peers (",
+          peers.length,
+          ")"
+        ] }),
+        peers.length === 0 ? /* @__PURE__ */ jsx("div", { className: "ue-ins__empty", children: "nobody else here" }) : peers.map((peer) => /* @__PURE__ */ jsxs("div", { className: "ue-ins__row", children: [
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__k", children: short(peer.id) }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__v", children: peer.kind })
+        ] }, peer.id))
+      ] }),
+      /* @__PURE__ */ jsxs("div", { className: "ue-ins__section", children: [
+        /* @__PURE__ */ jsxs("div", { className: "ue-ins__h", children: [
+          "State (",
+          entries.length,
+          ")"
+        ] }),
+        entries.length === 0 ? /* @__PURE__ */ jsx("div", { className: "ue-ins__empty", children: "no keys yet" }) : entries.map(([key, version]) => /* @__PURE__ */ jsxs("div", { className: "ue-ins__row", children: [
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__k", children: key }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__v", children: JSON.stringify(snapshot[key]) }),
+          /* @__PURE__ */ jsxs("span", { className: "ue-ins__ver", children: [
+            version[0],
+            "\xB7",
+            short(version[1])
+          ] })
+        ] }, key))
+      ] }),
+      /* @__PURE__ */ jsxs("div", { className: "ue-ins__section", children: [
+        /* @__PURE__ */ jsxs("div", { className: "ue-ins__h", children: [
+          "Wires (",
+          wires.length,
+          ")"
+        ] }),
+        wires.length === 0 ? /* @__PURE__ */ jsx("div", { className: "ue-ins__empty", children: "nothing yet" }) : /* @__PURE__ */ jsx("div", { className: "ue-ins__log", children: wires.map((wire) => /* @__PURE__ */ jsxs("div", { className: "ue-ins__wire", children: [
+          /* @__PURE__ */ jsx("span", { className: `ue-ins__dir ue-ins__dir--${wire.direction}`, children: wire.direction === "out" ? "\u2192" : "\u2190" }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__scope", children: wire.label }),
+          /* @__PURE__ */ jsx("span", { className: "ue-ins__from", children: wire.from })
+        ] }, wire.id)) })
+      ] })
+    ] }) : null
+  ] });
+}
+export {
+  Inspector
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { SharedStore, MessageMap, Channel, MessageMeta, Peer, OpenedWindow } from '@use-everywhere/core';
+import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow } from '@use-everywhere/core';
 export * from '@use-everywhere/core';
+export { DEFAULT_NAME } from '@use-everywhere/core';
 
 /**
  * How far a shared value travels:
@@ -26,14 +27,15 @@ declare function useSharedState<T>(key: string, initial: T, options?: UseSharedS
 /** Registry stores hold arbitrary keys — shape is decided by the hooks using them. */
 type AnyStore = SharedStore<Record<string, unknown>>;
 
-/**
- * A BroadcastChannel is already global to the origin — identity is the name
- * string, not the React tree — so hooks share module-level singletons per
- * name instead of requiring a Provider. Instances live for the page lifetime.
- */
-declare const DEFAULT_NAME = "use-everywhere";
 /** Imperative access to the store behind useSharedState (patch logs, non-React code). */
 declare function getSharedStore(name?: string, scope?: ShareScope): AnyStore;
+/**
+ * One Leader per name per tab. Eligibility is deliberately *not* part of the
+ * key: two Leaders on one name would share a bus and a clientId, and since a
+ * post never loops back locally, neither would ever see the other's claims.
+ * Timing options are first-wins, like every other engine here.
+ */
+declare function getLeader(name: string, options?: LeaderOptions): Leader;
 
 /** Get the page-wide typed channel for `name` (one instance per name). */
 declare function useChannel<M extends MessageMap>(name: string): Channel<M>;
@@ -45,6 +47,60 @@ declare function useMessage<M extends MessageMap, K extends keyof M & string>(ch
 /** The channel's post function (stable identity per channel). */
 declare function useSend<M extends MessageMap>(channel: Channel<M>): Channel<M>['post'];
 
+/** A channel bound to a name and message map: typed hooks with no per-call generics. */
+interface ChannelHooks<M extends MessageMap> {
+    /** The underlying channel instance (the same one the hooks use) — for non-React code. */
+    get: () => Channel<M>;
+    /** The channel's post function (stable identity). */
+    useSend: () => Channel<M>['post'];
+    /**
+     * Subscribe to one message type. Same contract as the standalone
+     * `useMessage`: the handler is kept fresh without resubscribing.
+     */
+    useMessage: <K extends keyof M & string>(type: K, handler: (payload: M[K], meta: MessageMeta) => void) => void;
+}
+
+/**
+ * Bind a channel name and message map once, at module level, and get fully
+ * typed hooks back. Sugar over useChannel/useMessage/useSend — the same
+ * page-wide channel singleton is shared, so mixing bound and standalone
+ * hooks for one name is safe.
+ */
+declare function defineChannel<M extends MessageMap>(name: string): ChannelHooks<M>;
+
+interface DefineStoreOptions {
+    /** Restore this store from disk on first use, and write it back as it changes. */
+    persist?: PersistAdapter;
+    /** Persist only these keys. Default: every key that has been written. */
+    persistKeys?: string[];
+    /** Coalesce disk writes for this long. Default 100. */
+    persistDebounceMs?: number;
+    /** How far this store is shared. Default 'everywhere'. */
+    scope?: ShareScope;
+}
+/** A store bound to a name and a shape: typed hooks with no per-call generics. */
+interface StoreHooks<S extends Record<string, unknown>> {
+    /** The underlying store instance (the same one the hooks use) — for non-React code. */
+    get: () => AnyStore;
+    useSharedState: <K extends keyof S & string>(key: K, initial: S[K]) => [S[K], (next: S[K] | ((prev: S[K]) => S[K])) => void];
+}
+
+/**
+ * Bind a store name — and optionally persistence — once, at module level.
+ *
+ * Like defineChannel, this does not construct anything: it registers the
+ * options the registry will use when the store is first needed, so importing
+ * the module has no side effect. The store stays a singleton per name, so
+ * `defineStore('settings', { persist })` and a bare
+ * `useSharedState('theme', 'dark', { store: 'settings' })` elsewhere resolve to
+ * the same store, and both get persistence.
+ *
+ * Must run before that store exists. Module evaluation always precedes render,
+ * so intended usage is automatic; if it does run late it throws rather than
+ * quietly handing back a store with no persistence.
+ */
+declare function defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
+
 /** The other tabs/windows/workers currently alive on this origin. */
 declare function usePeers(options?: {
     name?: string;
@@ -54,6 +110,25 @@ declare function useClientId(options?: {
     name?: string;
 }): string;
 
+interface UseLeaderOptions extends LeaderOptions {
+    /** Which bus to elect on. Defaults to the shared default name. */
+    name?: string;
+}
+
+/**
+ * Who currently holds the seat on this bus, and whether it is us. Exactly one
+ * tab leads; opening another does not steal it, and closing the leader hands it
+ * over at once.
+ */
+declare function useLeader(options?: UseLeaderOptions): LeaderSnapshot;
+/** Is this tab the leader? */
+declare function useIsLeader(options?: UseLeaderOptions): boolean;
+/**
+ * Run an effect only in the tab that holds the seat, and tear it down when the
+ * seat moves. The one place to put "exactly one tab owns the socket".
+ */
+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> {
     /** Call from a click handler (popup blockers require a user gesture). */
@@ -74,4 +149,4 @@ interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
  */
 declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
 
-export { type AnyStore, DEFAULT_NAME, type OpenedWindowStatus, type ShareScope, type UseOpenedWindow, type UseSharedStateOptions, getSharedStore, useChannel, useClientId, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+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 };

package/dist/index.js

@@ -1,52 +1,16 @@
-// src/use-shared-state.ts
-import { useCallback, useSyncExternalStore } from "react";
-
-// src/registry.ts
 import {
-  createChannel,
-  createPresence,
-  createSharedStore,
-  NoopTransport
-} from "@use-everywhere/core";
-var DEFAULT_NAME = "use-everywhere";
-var stores = /* @__PURE__ */ new Map();
-var presences = /* @__PURE__ */ new Map();
-var channels = /* @__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 getStore(name, scope = "everywhere") {
-  const key = `${scope}\0${name}`;
-  let store = stores.get(key);
-  if (!store) {
-    store = createSharedStore(name, {}, scopeOptions[scope]);
-    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 getChannel(name) {
-  let channel = channels.get(name);
-  if (!channel) {
-    channel = createChannel(name);
-    channels.set(name, channel);
-  }
-  return channel;
-}
+  DEFAULT_NAME,
+  configureStore,
+  getChannel,
+  getLeader,
+  getSharedStore,
+  getStore,
+  useClientId,
+  usePeers
+} from "./chunk-Y67BCTU6.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");
   store.registerKey(key, initial);
@@ -81,30 +45,75 @@ function useSend(channel) {
   return channel.post;
 }
 
-// src/use-peers.ts
-import { useCallback as useCallback2, useSyncExternalStore as useSyncExternalStore2 } from "react";
-var NO_PEERS = Object.freeze([]);
-function usePeers(options) {
-  const presence = getPresence(options?.name ?? DEFAULT_NAME);
+// src/define-channel.ts
+function defineChannel(name) {
+  const useBoundSend = () => useSend(useChannel(name));
+  const useBoundMessage = (type, handler) => useMessage(useChannel(name), type, handler);
+  return {
+    get: () => getChannel(name),
+    useSend: useBoundSend,
+    useMessage: useBoundMessage
+  };
+}
+
+// src/define-store.ts
+function defineStore(name, options = {}) {
+  const scope = options.scope ?? "everywhere";
+  if (options.persist) {
+    configureStore(name, scope, {
+      persist: {
+        adapter: options.persist,
+        ...options.persistKeys ? { keys: options.persistKeys } : {},
+        ...options.persistDebounceMs === void 0 ? {} : { debounceMs: options.persistDebounceMs }
+      }
+    });
+  }
+  return {
+    get: () => getStore(name, scope),
+    useSharedState: (key, initial) => useSharedState(key, initial, { store: name, scope })
+  };
+}
+
+// src/use-leader.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+function useLeader(options) {
+  const leader = getLeader(options?.name ?? DEFAULT_NAME, options);
+  const eligible = options?.eligible;
+  useEffect2(() => {
+    if (eligible === void 0) return;
+    leader.setEligible(eligible);
+  }, [leader, eligible]);
   return useSyncExternalStore2(
-    useCallback2((onChange) => presence.subscribe(onChange), [presence]),
-    () => presence.getPeers(),
-    () => NO_PEERS
+    useCallback2((onChange) => leader.subscribe(onChange), [leader]),
+    () => leader.getSnapshot(),
+    () => NO_LEADER
   );
 }
-function useClientId(options) {
-  return getPresence(options?.name ?? DEFAULT_NAME).clientId;
+function useIsLeader(options) {
+  return useLeader(options).isLeader;
+}
+function useLeaderEffect(effect, options) {
+  const { isLeader } = useLeader(options);
+  const effectRef = useRef2(effect);
+  useEffect2(() => {
+    effectRef.current = effect;
+  });
+  useEffect2(() => {
+    if (!isLeader) return;
+    return effectRef.current();
+  }, [isLeader]);
 }
 
 // src/use-opened-window.ts
-import { useCallback as useCallback3, useRef as useRef2, useState } from "react";
+import { useCallback as useCallback3, useRef as useRef3, useState } from "react";
 import { WindowClosedError } from "@use-everywhere/core";
 function useOpenedWindow(factory) {
   const [status, setStatus] = useState("idle");
   const [result, setResult] = useState(void 0);
   const [error, setError] = useState(void 0);
-  const current = useRef2(null);
-  const factoryRef = useRef2(factory);
+  const current = useRef3(null);
+  const factoryRef = useRef3(factory);
   factoryRef.current = factory;
   const open = useCallback3(() => {
     current.current?.close();
@@ -153,9 +162,15 @@ function useOpenedWindow(factory) {
 export * from "@use-everywhere/core";
 export {
   DEFAULT_NAME,
+  defineChannel,
+  defineStore,
+  getLeader,
   getSharedStore,
   useChannel,
   useClientId,
+  useIsLeader,
+  useLeader,
+  useLeaderEffect,
   useMessage,
   useOpenedWindow,
   usePeers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-everywhere",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "React hooks for state and messages shared across tabs, windows, and workers",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -32,18 +32,73 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./devtools": {
+      "types": "./dist/devtools/index.d.ts",
+      "import": "./dist/devtools/index.js"
     }
   },
   "files": [
     "dist"
   ],
+  "size-limit": [
+    {
+      "name": "everything (import *)",
+      "path": "dist/index.js",
+      "import": "*",
+      "limit": "5.4 kB"
+    },
+    {
+      "name": "useSharedState",
+      "path": "dist/index.js",
+      "import": "{ useSharedState }",
+      "limit": "1.8 kB"
+    },
+    {
+      "name": "useChannel + useMessage + useSend",
+      "path": "dist/index.js",
+      "import": "{ useChannel, useMessage, useSend }",
+      "limit": "1 kB"
+    },
+    {
+      "name": "usePeers + useClientId",
+      "path": "dist/index.js",
+      "import": "{ usePeers, useClientId }",
+      "limit": "1.1 kB"
+    },
+    {
+      "name": "useOpenedWindow + openWindow",
+      "path": "dist/index.js",
+      "import": "{ useOpenedWindow, openWindow }",
+      "limit": "1.4 kB"
+    },
+    {
+      "name": "useLeader + useLeaderEffect",
+      "path": "dist/index.js",
+      "import": "{ useLeader, useLeaderEffect }",
+      "limit": "1.8 kB"
+    },
+    {
+      "name": "defineStore (persisted)",
+      "path": "dist/index.js",
+      "import": "{ defineStore, localStorageAdapter }",
+      "limit": "2.3 kB"
+    },
+    {
+      "name": "Inspector (devtools subpath)",
+      "path": "dist/devtools/index.js",
+      "import": "{ Inspector }",
+      "limit": "5 kB"
+    }
+  ],
   "dependencies": {
-    "@use-everywhere/core": "0.1.0"
+    "@use-everywhere/core": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.2.3",
@@ -51,13 +106,22 @@
     "happy-dom": "^20.10.6",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "size-limit": "^12.1.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.1.10"
   },
+  "typesVersions": {
+    "*": {
+      "devtools": [
+        "./dist/devtools/index.d.ts"
+      ]
+    }
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
   }
 }