@use-everywhere/core 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @use-everywhere/core
 
 Framework-agnostic engine for cross-tab shared state, typed events, peer
-presence, and secure cross-origin window channels.
+presence, and secure cross-origin window channels. Zero dependencies.
 
 ```bash
 npm i @use-everywhere/core
@@ -12,22 +12,158 @@ npm i @use-everywhere/core
 
 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. Every message is validated by origin, envelope brand, a
   per-connection nonce, and the source window.
 
+## Shared state
+
+One object that exists in every tab, window, and worker on your origin.
+Writes broadcast patches; replicas converge last-writer-wins; tabs opened
+later hydrate to the current value via a hello/snapshot handshake.
+
+```ts
+import { createSharedStore } from '@use-everywhere/core';
+
+const store = createSharedStore('checkout', { step: 0, payment: 'idle' });
+
+// Imperative writes through the proxy — they sync everywhere:
+store.state.step++;
+
+// Or explicit (supports functional updates):
+store.set('payment', 'processing');
+store.set('step', (prev) => prev + 1);
+
+// React to changes from any tab, worker, or this one:
+store.subscribe((key, value, meta) => {
+  console.log(`${String(key)} = ${value}`, meta.self ? '(me)' : `(peer ${meta.clientId})`);
+});
+
+// Immutable snapshot, replaced per change (useSyncExternalStore-compatible):
+store.getSnapshot(); // { step: 1, payment: 'processing' }
+```
+
+Options let you delimit what a store accepts — e.g. ignore writes coming from
+workers:
+
+```ts
+createSharedStore('ui', { theme: 'light' }, { accept: (meta) => meta.kind !== 'worker' });
+```
+
+## Typed events
+
+Fire-and-forget messages between contexts. No history: a tab that joins later
+never sees old events (use shared state for anything a late joiner must know).
+
+```ts
+import { createChannel } from '@use-everywhere/core';
+
+type AuthEvents = { 'logged-out': undefined; 'session-renewed': { expiresAt: number } };
+
+const channel = createChannel<AuthEvents>('auth');
+
+const off = channel.on('logged-out', (_payload, meta) => {
+  console.log(`tab ${meta.clientId} logged out`);
+  window.location.assign('/login');
+});
+
+channel.post('logged-out', undefined); // delivered to every OTHER context
+```
+
+## Presence
+
+Who else is on this origin right now? Heartbeat-based, with instant goodbyes
+on clean tab closes and pruning (~5s) for crashed ones.
+
+```ts
+import { createPresence } from '@use-everywhere/core';
+
+const presence = createPresence('app');
+presence.subscribe(() => {
+  console.log(presence.getPeers()); // [{ id: 'p8m1q4', kind: 'tab', lastSeen: … }]
+});
+```
+
+## Cross-origin window channel
+
+The case BroadcastChannel cannot do: a checkout on domain A opens a payment
+page on domain B, and the payment page must report back.
+
+```ts
+// On the opener (https://shop.example.com):
+import { openWindow } from '@use-everywhere/core';
+
+type ToPayment = { order: { orderId: string; amount: string } };
+type FromPayment = { progress: { step: string } };
+type Receipt = { receiptId: string; last4: string };
+
+const opened = openWindow<ToPayment, FromPayment, Receipt>(
+  'https://pay.example.com/checkout',
+  { peerOrigin: 'https://pay.example.com' }, // required — '*' throws
+);
+
+opened.post('order', { orderId: '48-291', amount: '$69.03' }); // queued until the child is ready
+opened.on('progress', ({ step }) => console.log('payment step:', step));
+
+const receipt = await opened.result; // the child's finish() value
+// rejects with WindowClosedError if the user closes the window first
+```
+
+```ts
+// On the opened page (https://pay.example.com):
+import { connectToOpener } from '@use-everywhere/core';
+
+const conn = connectToOpener<ToPayment, FromPayment, Receipt>({
+  peerOrigin: 'https://shop.example.com',
+});
+
+conn.on('order', (order) => showOrderSummary(order)); // your UI code
+conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's `result`
+conn.close();
+```
+
+The handshake retries until the (possibly slow-loading) child connects, and
+both sides queue outgoing messages until then — nothing is dropped. Every
+received message must pass four gates: exact origin, library envelope, a
+per-connection nonce carried in the child URL, and (on the opener) the source
+window itself.
+
+## Testing
+
+Every engine accepts an injected transport, so "many tabs" fits in one test —
+no browser required:
+
+```ts
+import { createSharedStore, MemoryHub } from '@use-everywhere/core';
+
+const hub = new MemoryHub();
+const tabA = createSharedStore('t', { n: 0 }, { transport: () => hub.connect() });
+const tabB = createSharedStore('t', { n: 0 }, { transport: () => hub.connect() });
+
+tabA.set('n', 1);
+await new Promise((r) => setTimeout(r, 0));
+tabB.getSnapshot().n; // 1
+```
+
+`openWindow`/`connectToOpener` take equivalent seams (`openFn`, `localWindow`,
+`opener`, `cid`) for driving window flows with fakes.
+
 ## Design notes
 
 - **Shared state never crosses origins.** Two origins are two trust domains;
   the cross-origin channel is explicit, per-message, and typed.
-- Same-origin state sync uses per-key `[counter, clientId]` clocks
-  (last-writer-wins, deterministic tie-break) and a hello/snapshot handshake so
-  late-joining tabs hydrate instantly.
-- Values must survive structured clone (no functions, DOM nodes, etc.).
+- Values must survive structured clone (no functions, DOM nodes, class
+  instances).
+- State lives exactly as long as some context holds it — nothing is persisted.
+- SSR-safe: without `BroadcastChannel`, engines fall back to a local no-op
+  transport.
 
-Full docs, demo app (including a real cross-origin payment flow), and source:
+📖 **[Documentation](https://rxova.github.io/use-everywhere/)** — mental
+model, how sync works, security model, recipes, and generated API reference.
+Source and demo app (with a real cross-origin payment flow):
 [github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
 
 ## License

package/dist/index.d.ts

@@ -42,6 +42,34 @@ interface Channel<M extends MessageMap> {
 /** Typed pub/sub over the same-origin bus. */
 declare function createChannel<M extends MessageMap>(name: string, options?: CommonOptions): Channel<M>;
 
+/**
+ * What goes to disk. The version clocks travel *with* the values — that is the
+ * whole point: a reopened tab re-enters the last-writer-wins race with its real
+ * term instead of a fresh zero, so a restored value can legitimately beat, or
+ * legitimately lose to, whatever the live tabs are holding.
+ */
+interface Persisted {
+    v: 1;
+    state: Record<string, unknown>;
+    versions: Record<string, Version>;
+}
+interface PersistAdapter {
+    /**
+     * Prefer a synchronous read. An async adapter cannot hydrate before the store
+     * is handed back, so a write made in that gap can be clobbered by the restore.
+     */
+    read(): Persisted | undefined | Promise<Persisted | undefined>;
+    write(snapshot: Persisted): void | Promise<void>;
+    remove?(): void | Promise<void>;
+}
+interface PersistOptions {
+    adapter: PersistAdapter;
+    /** Persist only these keys. Default: every key that has been written. */
+    keys?: string[];
+    /** Coalesce writes for this long. Default 100. */
+    debounceMs?: number;
+}
+
 interface SharedStoreOptions extends CommonOptions {
     /**
      * Gatekeeper for incoming remote writes (patches and snapshot merges):
@@ -49,6 +77,8 @@ interface SharedStoreOptions extends CommonOptions {
      * e.g. accept only writes from other tabs, not from workers.
      */
     accept?: (meta: MessageMeta) => boolean;
+    /** Restore this store on creation and write it back as it changes. */
+    persist?: PersistOptions;
 }
 interface SharedStore<S extends Record<string, unknown>> {
     readonly clientId: string;
@@ -56,6 +86,8 @@ interface SharedStore<S extends Record<string, unknown>> {
     readonly state: S;
     /** Immutable snapshot, replaced whenever a change is applied. Safe for useSyncExternalStore. */
     getSnapshot(): Readonly<S>;
+    /** The per-key version clocks behind the snapshot. Referentially stable, like getSnapshot. */
+    getVersions(): Readonly<Record<string, Version>>;
     set<K extends keyof S & string>(key: K, value: S[K] | ((prev: S[K]) => S[K])): void;
     subscribe(fn: (key: keyof S & string, value: unknown, meta: MessageMeta) => void): () => void;
     subscribeKey(key: keyof S & string, fn: () => void): () => void;
@@ -75,6 +107,59 @@ interface SharedStore<S extends Record<string, unknown>> {
  */
 declare function createSharedStore<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions): SharedStore<S>;
 
+/** Everything on the same-origin bus, multiplexed by scope over one BroadcastChannel per name. */
+type BusWire = {
+    v: 1;
+    scope: 'state';
+    type: 'patch';
+    key: string;
+    value: unknown;
+    version: Version;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'state';
+    type: 'hello';
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'state';
+    type: 'snapshot';
+    clientId: string;
+    kind: PeerKind;
+    state: Record<string, unknown>;
+    versions: Record<string, Version>;
+} | {
+    v: 1;
+    scope: 'presence';
+    type: 'hello' | 'ping' | 'bye';
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'leader';
+    type: 'hello';
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'leader';
+    type: 'claim' | 'heartbeat' | 'resign';
+    /** The claimant's term. Arbitrated with newer() — the same clock the store uses. */
+    term: Version;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'event';
+    type: string;
+    payload: unknown;
+    clientId: string;
+    kind: PeerKind;
+    msgId: string;
+};
 interface BusOptions extends CommonOptions {
     /** Presence heartbeat interval in ms. Default 2000. */
     heartbeatMs?: number;
@@ -99,6 +184,70 @@ interface Presence {
  */
 declare function createPresence(name: string, options?: PresenceOptions): Presence;
 
+/**
+ * Deliberately extends CommonOptions, not BusOptions: `heartbeatMs` here means
+ * the leader's re-announce interval, which is a different thing from the bus's
+ * presence ping. See the note in leader.ts about forwarding to getBus.
+ */
+interface LeaderOptions extends CommonOptions {
+    /** How often the leader re-announces itself, in ms. Default 1000. */
+    heartbeatMs?: number;
+    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. */
+    leaseMs?: number;
+    /** May this client hold the leadership? Default true. */
+    eligible?: boolean;
+}
+interface LeaderSnapshot {
+    /** The current leader's clientId, or null while the seat is empty. */
+    readonly leaderId: string | null;
+    readonly isLeader: boolean;
+}
+interface Leader {
+    readonly clientId: string;
+    /** Frozen; a new object only when the leader actually changes. */
+    getSnapshot(): LeaderSnapshot;
+    subscribe(fn: () => void): () => void;
+    /** Give up the seat now. Peers take over immediately rather than waiting for the lease. */
+    resign(): void;
+    /** Turn candidacy on or off. Eligibility is a property of the tab, not a component. */
+    setEligible(eligible: boolean): void;
+    close(): void;
+}
+
+/**
+ * Elects exactly one client on the bus to hold a seat: the tab that owns the
+ * WebSocket, polls, or refreshes the token, while the others stand by.
+ *
+ * Lease and claim, with a sticky incumbent. A leader re-announces every
+ * heartbeatMs; followers give up on it after leaseMs of silence and claim the
+ * seat with a higher term. Terms are Versions, arbitrated by the same newer()
+ * the store uses, so simultaneous claims resolve deterministically instead of
+ * flapping.
+ *
+ * Leadership is advisory. It is not a distributed lock, and a hidden tab whose
+ * timers are throttled can lose a lease it deserved to keep.
+ */
+declare function createLeader(name: string, options?: LeaderOptions): Leader;
+
+type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/**
+ * Persist to any Storage-shaped thing.
+ *
+ * `storage` may be a thunk, and that is the form the built-in adapters use:
+ * merely *reading* `globalThis.localStorage` throws SecurityError when storage
+ * is blocked (a sandboxed iframe, third-party cookies off), so evaluating it at
+ * module scope would blow up on import — before any try/catch here could help.
+ * Behind a thunk, every access happens inside one.
+ *
+ * Blocked storage, corrupt JSON, a foreign schema, or a full quota all degrade
+ * to a silent no-op. Persistence is best-effort; it must never break the store.
+ */
+declare function webStorageAdapter(storage: StorageLike | (() => StorageLike | undefined), key: string): PersistAdapter;
+/** Survives closing every tab. */
+declare function localStorageAdapter(key: string): PersistAdapter;
+/** Survives reloads, but dies with the tab. */
+declare function sessionStorageAdapter(key: string): PersistAdapter;
+
 interface MessageEventLike {
     data: unknown;
     origin: string;
@@ -197,6 +346,51 @@ declare class HandshakeTimeoutError extends Error {
 /** Is `a` newer than `b`? Last-writer-wins; equal counters break ties by clientId. */
 declare function newer(a: Version, b: Version | undefined): boolean;
 
+/**
+ * The bus name used when a caller does not pick one. A BroadcastChannel is
+ * global to the origin, so identity is the name string — everything that
+ * omits a name lands on this one bus.
+ */
+declare const DEFAULT_NAME = "use-everywhere";
+
+/** One wire crossing the bus, in either direction. */
+interface BusEvent {
+    /** The bus name the wire crossed. */
+    readonly name: string;
+    /** 'out' is posted by this client; 'in' is received from a peer. */
+    readonly direction: 'in' | 'out';
+    readonly wire: BusWire;
+}
+type BusObserver = (event: BusEvent) => void;
+interface DebugOptions {
+    /** Bus name to log. Defaults to the default store/channel name. */
+    name?: string;
+    /** Where to write. Defaults to console.log. */
+    log?: (...args: unknown[]) => void;
+}
+
+/**
+ * Watch every wire crossing the named bus, in both directions. Outbound wires
+ * are the interesting half: a post goes straight to the transport, so without
+ * this seam nothing this client says is visible to it.
+ *
+ * Works for buses that do not exist yet — observe first, create later.
+ */
+declare function observeBus(name: string, fn: BusObserver): () => void;
+/** Log every wire on a bus to the console. Returns a function to stop. */
+declare function enableDebug(options?: DebugOptions): () => void;
+
+/**
+ * Get the shared bus for `name`, creating it on first use. Callers must call
+ * bus.release() exactly once when done. When a custom transport factory is
+ * given (tests), every call creates an isolated bus — one call = one simulated client.
+ */
+/**
+ * Names of the buses currently alive on this page. Buses built with a custom
+ * transport (tests) bypass the registry, so they are not listed.
+ */
+declare function getBusNames(): string[];
+
 /** Same-origin transport over a real BroadcastChannel. */
 declare class BroadcastChannelTransport implements Transport {
     private bc;
@@ -248,4 +442,4 @@ declare class MemoryHub {
     disconnect(transport: MemoryTransport): void;
 }
 
-export { BroadcastChannelTransport, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, HandshakeTimeoutError, MemoryHub, MemoryTransport, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type Transport, type Version, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createPresence, createSharedStore, defaultTransport, isBroadcastChannelAvailable, newer, openWindow };
+export { BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type Leader, type LeaderOptions, type LeaderSnapshot, MemoryHub, MemoryTransport, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type StorageLike, type Transport, type Version, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, isBroadcastChannelAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };

package/dist/index.js

@@ -1,3 +1,37 @@
+// src/defaults.ts
+var DEFAULT_NAME = "use-everywhere";
+
+// src/debug.ts
+var observers = /* @__PURE__ */ new Map();
+function emitBusEvent(name, direction, wire) {
+  const set = observers.get(name);
+  if (!set) return;
+  const event = { name, direction, wire };
+  for (const fn of set) fn(event);
+}
+function observeBus(name, fn) {
+  let set = observers.get(name);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    observers.set(name, set);
+  }
+  set.add(fn);
+  return () => {
+    const current = observers.get(name);
+    if (!current) return;
+    current.delete(fn);
+    if (current.size === 0) observers.delete(name);
+  };
+}
+function enableDebug(options = {}) {
+  const name = options.name ?? DEFAULT_NAME;
+  const log = options.log ?? ((...args) => console.log(...args));
+  return observeBus(name, ({ direction, wire }) => {
+    const arrow = direction === "out" ? "\u2192" : "\u2190";
+    log(`[use-everywhere:${name}] ${arrow} ${wire.scope}/${wire.type}`, wire);
+  });
+}
+
 // src/ids.ts
 function newClientId() {
   return Math.random().toString(36).slice(2, 8);
@@ -64,11 +98,14 @@ function createBus(name, options, onShutdown) {
   let refs = 0;
   let closed = false;
   const post = (wire) => {
-    if (!closed) transport.post(wire);
+    if (closed) return;
+    emitBusEvent(name, "out", wire);
+    transport.post(wire);
   };
   const unsubscribe = transport.subscribe((data) => {
     if (!isBusWire(data)) return;
     if (data.clientId === clientId) return;
+    emitBusEvent(name, "in", data);
     if (data.scope === "presence" && data.type === "hello") {
       post({ v: 1, scope: "presence", type: "ping", clientId, kind });
     }
@@ -108,6 +145,9 @@ function createBus(name, options, onShutdown) {
     }
   };
 }
+function getBusNames() {
+  return [...registry.keys()];
+}
 function getBus(name, options = {}) {
   if (options.transport) {
     const bus2 = createBus(name, options, () => {
@@ -180,10 +220,12 @@ function createSharedStore(name, initial, options = {}) {
   const versions = {};
   for (const k in state) versions[k] = [0, clientId];
   let snapshot = Object.freeze({ ...state });
+  let versionsSnapshot = Object.freeze({ ...versions });
   const listeners = /* @__PURE__ */ new Set();
   const keyListeners = /* @__PURE__ */ new Map();
   function notify(key, value, meta) {
     snapshot = Object.freeze({ ...state });
+    versionsSnapshot = Object.freeze({ ...versions });
     for (const fn of listeners) fn(key, value, meta);
     const set = keyListeners.get(key);
     if (set) for (const fn of set) fn();
@@ -242,11 +284,65 @@ function createSharedStore(name, initial, options = {}) {
       return true;
     }
   });
+  const persist = options.persist;
+  let flushPersist;
+  if (persist) {
+    const { adapter, keys, debounceMs = 100 } = persist;
+    const shouldPersist = (key) => !keys || keys.includes(key);
+    const hydrate = (saved2) => {
+      if (!saved2) return;
+      for (const key in saved2.state) {
+        const version = saved2.versions[key];
+        if (!version || !shouldPersist(key)) continue;
+        applyRemote(key, saved2.state[key], version, { clientId, kind: bus.kind, self: true });
+        bus.post({
+          v: 1,
+          scope: "state",
+          type: "patch",
+          key,
+          value: saved2.state[key],
+          version,
+          clientId,
+          kind: bus.kind
+        });
+      }
+    };
+    const collect = () => {
+      const out = { v: 1, state: {}, versions: {} };
+      for (const key in versions) {
+        const version = versions[key];
+        if (!version || version[0] === 0 || !shouldPersist(key)) continue;
+        out.state[key] = state[key];
+        out.versions[key] = version;
+      }
+      return out;
+    };
+    let timer;
+    flushPersist = () => {
+      clearTimeout(timer);
+      timer = void 0;
+      void adapter.write(collect());
+    };
+    const saved = adapter.read();
+    if (saved instanceof Promise) {
+      void saved.then(hydrate);
+    } else {
+      hydrate(saved);
+    }
+    listeners.add(() => {
+      if (timer !== void 0) return;
+      timer = setTimeout(flushPersist, debounceMs);
+    });
+    if (typeof document !== "undefined" && typeof addEventListener === "function") {
+      addEventListener("pagehide", flushPersist);
+    }
+  }
   bus.post({ v: 1, scope: "state", type: "hello", clientId, kind: bus.kind });
   return {
     clientId,
     state: proxy,
     getSnapshot: () => snapshot,
+    getVersions: () => versionsSnapshot,
     set(key, value) {
       const next = typeof value === "function" ? value(state[key]) : value;
       setKey(key, next);
@@ -269,8 +365,15 @@ function createSharedStore(name, initial, options = {}) {
       versions[key] = [0, clientId];
       state[key] = initialValue;
       snapshot = Object.freeze({ ...state });
+      versionsSnapshot = Object.freeze({ ...versions });
     },
     close() {
+      if (flushPersist) {
+        flushPersist();
+        if (typeof document !== "undefined" && typeof removeEventListener === "function") {
+          removeEventListener("pagehide", flushPersist);
+        }
+      }
       unsubscribe();
       listeners.clear();
       keyListeners.clear();
@@ -329,6 +432,167 @@ function createPresence(name, options = {}) {
   };
 }
 
+// src/leader.ts
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+function createLeader(name, options = {}) {
+  const heartbeatMs = options.heartbeatMs ?? 1e3;
+  const leaseMs = options.leaseMs ?? 3e3;
+  const busOptions = {
+    ...options.transport ? { transport: options.transport } : {},
+    ...options.kind ? { kind: options.kind } : {}
+  };
+  const bus = getBus(name, busOptions);
+  const clientId = bus.clientId;
+  let eligible = options.eligible ?? true;
+  let leaderId = null;
+  let term = [0, clientId];
+  let snapshot = NO_LEADER;
+  let beat;
+  let lease;
+  let closed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function setLeader(id) {
+    if (id === leaderId) return;
+    leaderId = id;
+    snapshot = Object.freeze({ leaderId: id, isLeader: id === clientId });
+    for (const fn of listeners) fn();
+  }
+  function armLease(delay) {
+    clearTimeout(lease);
+    lease = setTimeout(onLeaseExpired, delay);
+  }
+  function onLeaseExpired() {
+    if (closed) return;
+    setLeader(null);
+    if (eligible) claim();
+  }
+  function heartbeat() {
+    bus.post({ v: 1, scope: "leader", type: "heartbeat", term, clientId, kind: bus.kind });
+  }
+  function claim() {
+    term = [term[0] + 1, clientId];
+    setLeader(clientId);
+    bus.post({ v: 1, scope: "leader", type: "claim", term, clientId, kind: bus.kind });
+    clearInterval(beat);
+    beat = setInterval(heartbeat, heartbeatMs);
+  }
+  function stepDown(next) {
+    clearInterval(beat);
+    beat = void 0;
+    setLeader(next);
+  }
+  const unsubscribe = bus.subscribe((wire) => {
+    if (wire.scope !== "leader") return;
+    if (wire.type === "hello") {
+      if (leaderId === clientId) heartbeat();
+      return;
+    }
+    if (wire.type === "resign") {
+      if (wire.clientId !== leaderId) return;
+      setLeader(null);
+      armLease(0);
+      return;
+    }
+    if (newer(wire.term, term)) {
+      term = wire.term;
+      stepDown(wire.clientId);
+      armLease(leaseMs);
+      return;
+    }
+    if (leaderId === clientId) {
+      heartbeat();
+      return;
+    }
+    if (wire.clientId === leaderId) armLease(leaseMs);
+  });
+  function resign() {
+    if (leaderId !== clientId) return;
+    const resigning = term;
+    stepDown(null);
+    bus.post({ v: 1, scope: "leader", type: "resign", term: resigning, clientId, kind: bus.kind });
+    armLease(leaseMs);
+  }
+  const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
+  const onPageHide = () => resign();
+  if (hasWindow) addEventListener("pagehide", onPageHide);
+  bus.post({ v: 1, scope: "leader", type: "hello", clientId, kind: bus.kind });
+  armLease(heartbeatMs);
+  return {
+    clientId,
+    getSnapshot: () => snapshot,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    resign,
+    setEligible(next) {
+      if (next === eligible) return;
+      eligible = next;
+      if (!next) {
+        if (leaderId === clientId) resign();
+        return;
+      }
+      if (leaderId === null) armLease(0);
+    },
+    close() {
+      closed = true;
+      resign();
+      clearInterval(beat);
+      clearTimeout(lease);
+      if (hasWindow) removeEventListener("pagehide", onPageHide);
+      unsubscribe();
+      listeners.clear();
+      bus.release();
+    }
+  };
+}
+
+// src/persist-web-storage.ts
+function isPersisted(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return candidate.v === 1 && typeof candidate.state === "object" && typeof candidate.versions === "object";
+}
+function webStorageAdapter(storage, key) {
+  const resolve = () => {
+    try {
+      return typeof storage === "function" ? storage() : storage;
+    } catch {
+      return void 0;
+    }
+  };
+  return {
+    read() {
+      try {
+        const raw = resolve()?.getItem(key);
+        if (!raw) return void 0;
+        const parsed = JSON.parse(raw);
+        return isPersisted(parsed) ? parsed : void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    write(snapshot) {
+      try {
+        resolve()?.setItem(key, JSON.stringify(snapshot));
+      } catch {
+      }
+    },
+    remove() {
+      try {
+        resolve()?.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+function localStorageAdapter(key) {
+  return webStorageAdapter(() => globalThis.localStorage, key);
+}
+function sessionStorageAdapter(key) {
+  return webStorageAdapter(() => globalThis.sessionStorage, key);
+}
+
 // src/errors/handshake-timeout-error.ts
 var HandshakeTimeoutError = class extends Error {
   constructor(message = "handshake with the other window timed out") {
@@ -615,6 +879,7 @@ var MemoryHub = class {
 export {
   BroadcastChannelTransport,
   CID_PARAM,
+  DEFAULT_NAME,
   HandshakeTimeoutError,
   MemoryHub,
   MemoryTransport,
@@ -622,10 +887,17 @@ export {
   WindowClosedError,
   connectToOpener,
   createChannel,
+  createLeader,
   createPresence,
   createSharedStore,
   defaultTransport,
+  enableDebug,
+  getBusNames,
   isBroadcastChannelAvailable,
+  localStorageAdapter,
   newer,
-  openWindow
+  observeBus,
+  openWindow,
+  sessionStorageAdapter,
+  webStorageAdapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -36,9 +36,73 @@
   "files": [
     "dist"
   ],
+  "size-limit": [
+    {
+      "name": "everything (import *)",
+      "path": "dist/index.js",
+      "import": "*",
+      "limit": "4.5 kB"
+    },
+    {
+      "name": "createLeader",
+      "path": "dist/index.js",
+      "import": "{ createLeader }",
+      "limit": "1.3 kB"
+    },
+    {
+      "name": "createSharedStore",
+      "path": "dist/index.js",
+      "import": "{ createSharedStore }",
+      "limit": "1.6 kB"
+    },
+    {
+      "name": "createChannel",
+      "path": "dist/index.js",
+      "import": "{ createChannel }",
+      "limit": "900 B"
+    },
+    {
+      "name": "createPresence",
+      "path": "dist/index.js",
+      "import": "{ createPresence }",
+      "limit": "1 kB"
+    },
+    {
+      "name": "openWindow (opener side)",
+      "path": "dist/index.js",
+      "import": "{ openWindow }",
+      "limit": "1.15 kB"
+    },
+    {
+      "name": "connectToOpener (child side)",
+      "path": "dist/index.js",
+      "import": "{ connectToOpener }",
+      "limit": "1 kB"
+    },
+    {
+      "name": "MemoryHub (test transport)",
+      "path": "dist/index.js",
+      "import": "{ MemoryHub }",
+      "limit": "300 B"
+    },
+    {
+      "name": "observeBus + enableDebug",
+      "path": "dist/index.js",
+      "import": "{ observeBus, enableDebug }",
+      "limit": "500 B"
+    },
+    {
+      "name": "localStorageAdapter",
+      "path": "dist/index.js",
+      "import": "{ localStorageAdapter }",
+      "limit": "500 B"
+    }
+  ],
   "devDependencies": {
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@vitest/coverage-v8": "^4.1.10",
     "happy-dom": "^20.10.6",
+    "size-limit": "^12.1.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.1.10"
@@ -46,6 +110,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
   }
 }