@use-everywhere/core 0.6.0 → 0.8.0

package/dist/index.js

@@ -60,9 +60,11 @@ function randomHex(bytes) {
     for (const b of buf) out2 += b.toString(16).padStart(2, "0");
     return out2;
   }
-  devWarn(
-    "[use-everywhere] crypto.getRandomValues is unavailable; falling back to Math.random for ids. Cross-origin window nonces are not cryptographically strong in this environment."
-  );
+  if (process.env.NODE_ENV !== "production") {
+    devWarn(
+      "[use-everywhere] crypto.getRandomValues is unavailable; falling back to Math.random for ids. Cross-origin window nonces are not cryptographically strong in this environment."
+    );
+  }
   let out = "";
   while (out.length < bytes * 2)
     out += Math.floor(Math.random() * 256).toString(16).padStart(2, "0");
@@ -75,9 +77,38 @@ function newMsgId() {
   return randomHex(16);
 }
 
+// src/rendezvous.ts
+var PROTOCOL = 1;
+var TABLE = /* @__PURE__ */ Symbol.for(`use-everywhere.rendezvous.${PROTOCOL}`);
+var CENSUS = /* @__PURE__ */ Symbol.for("use-everywhere.rendezvous.census");
+var SKEW = /* @__PURE__ */ Symbol.for("use-everywhere.rendezvous.skew");
+function announce() {
+  const g = globalThis;
+  const census = g[CENSUS] ?? (g[CENSUS] = { protocols: [] });
+  if (census.protocols.includes(PROTOCOL)) return;
+  census.protocols.push(PROTOCOL);
+  if (census.protocols.length > 1) {
+    if (process.env.NODE_ENV !== "production") {
+      devWarn(
+        `[use-everywhere] two incompatible versions of this library are loaded on one page (rendezvous protocols ${census.protocols.join(", ")}). They will not share a client identity: expect one presence entry per version and no synchronous delivery between them. They still sync over the bus. Align the versions to fix it.`
+      );
+    }
+  }
+}
+function busTable() {
+  announce();
+  const g = globalThis;
+  return g[TABLE] ?? (g[TABLE] = /* @__PURE__ */ new Map());
+}
+function skewLedger() {
+  const g = globalThis;
+  return g[SKEW] ?? (g[SKEW] = /* @__PURE__ */ new Map());
+}
+
 // src/transport/broadcast-channel-transport.ts
 var BroadcastChannelTransport = class {
   constructor(name) {
+    this.kind = "broadcast-channel";
     this.listeners = /* @__PURE__ */ new Set();
     this.bc = new BroadcastChannel(name);
     this.bc.onmessage = (event) => {
@@ -99,6 +130,9 @@ var BroadcastChannelTransport = class {
 
 // src/transport/noop-transport.ts
 var NoopTransport = class {
+  constructor() {
+    this.kind = "none";
+  }
   post() {
   }
   subscribe() {
@@ -109,157 +143,434 @@ var NoopTransport = class {
   }
 };
 
+// src/serializer.ts
+function lossyType(raw, value) {
+  if (value === void 0) return raw === void 0 ? "undefined" : "undefined after toJSON";
+  if (raw instanceof Date) return "Date";
+  if (raw instanceof Map) return "Map";
+  if (raw instanceof Set) return "Set";
+  if (raw instanceof RegExp) return "RegExp";
+  if (ArrayBuffer.isView(raw)) return "TypedArray";
+  const type = typeof raw;
+  return type === "function" || type === "symbol" ? type : void 0;
+}
+var jsonSerializer = {
+  stringify(value) {
+    if (value === void 0) {
+      throw new TypeError("use-everywhere: cannot serialize undefined");
+    }
+    return JSON.stringify(value, function replacer(key, forJson) {
+      const type = lossyType(this[key], forJson);
+      if (type) {
+        throw new TypeError(
+          `use-everywhere: ${key ? `"${key}" is ` : ""}${type}, which JSON cannot round-trip. https://rxova.org/guides/serialization/`
+        );
+      }
+      return forJson;
+    });
+  },
+  parse: (text) => JSON.parse(text)
+};
+
+// src/transport/storage-transport.ts
+var StorageTransport = class {
+  constructor(name, storage = globalThis.localStorage, serializer = jsonSerializer) {
+    this.kind = "storage";
+    this.listeners = /* @__PURE__ */ new Set();
+    this.seq = 0;
+    if (!storage) {
+      throw new Error(
+        "[use-everywhere] StorageTransport needs localStorage; workers have none. Use BroadcastChannel there."
+      );
+    }
+    this.serializer = serializer;
+    this.key = `use-everywhere:bus:${name}`;
+    this.storage = storage;
+    this.onStorage = (event) => {
+      if (event.key !== this.key || event.newValue === null) return;
+      let payload;
+      try {
+        payload = this.serializer.parse(event.newValue);
+      } catch {
+        return;
+      }
+      for (const listener of this.listeners) listener(payload.data);
+    };
+    addEventListener("storage", this.onStorage);
+  }
+  post(data) {
+    const envelope = this.serializer.stringify({ seq: this.seq++, data });
+    try {
+      this.storage.setItem(this.key, envelope);
+      this.storage.removeItem(this.key);
+    } catch {
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    this.listeners.clear();
+    removeEventListener("storage", this.onStorage);
+  }
+};
+
 // src/transport/default-transport.ts
 function isBroadcastChannelAvailable() {
   return typeof BroadcastChannel !== "undefined";
 }
+function isStorageEventAvailable() {
+  if (typeof addEventListener !== "function") return false;
+  try {
+    const storage = globalThis.localStorage;
+    if (!storage) return false;
+    const probe = "use-everywhere:probe";
+    storage.setItem(probe, "1");
+    storage.removeItem(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function defaultTransport(name) {
-  return isBroadcastChannelAvailable() ? new BroadcastChannelTransport(name) : new NoopTransport();
+  if (isBroadcastChannelAvailable()) return new BroadcastChannelTransport(name);
+  if (isStorageEventAvailable()) {
+    if (process.env.NODE_ENV !== "production") {
+      devWarn(
+        "[use-everywhere] no BroadcastChannel; using the storage-event fallback. Values serialise as JSON, not structured clone \u2014 keep them JSON-shaped."
+      );
+    }
+    return new StorageTransport(name);
+  }
+  if (process.env.NODE_ENV !== "production") {
+    devWarn(
+      "[use-everywhere] no BroadcastChannel and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
+    );
+  }
+  return new NoopTransport();
 }
 
-// src/bus.ts
+// src/wire.ts
+var WIRE_VERSION = 1;
+function hasEnvelopeShape(wire) {
+  return typeof wire.scope === "string" && typeof wire.type === "string" && typeof wire.clientId === "string";
+}
 function isBusWire(data) {
-  return typeof data === "object" && data !== null && data.v === 1;
+  if (typeof data !== "object" || data === null) return false;
+  const wire = data;
+  return wire.v === WIRE_VERSION && hasEnvelopeShape(wire);
+}
+function foreignWireVersion(data) {
+  if (typeof data !== "object" || data === null) return null;
+  const wire = data;
+  if (typeof wire.v !== "number" || wire.v === WIRE_VERSION) return null;
+  return hasEnvelopeShape(wire) ? wire.v : null;
 }
+function recordSkew(name, version) {
+  const seen = skewLedger();
+  const versions = seen.get(name) ?? /* @__PURE__ */ new Set();
+  seen.set(name, versions);
+  if (versions.has(version)) return;
+  versions.add(version);
+  if (process.env.NODE_ENV !== "production") {
+    devWarn(
+      `[use-everywhere] bus "${name}": a peer speaks wire protocol v${version}, this build speaks v${WIRE_VERSION} \u2014 a ${version > WIRE_VERSION ? "newer" : "older"} deploy. They cannot share state, presence, or a leader seat. https://rxova.org/under-the-hood/version-skew/`
+    );
+  }
+}
+function getWireSkew(name) {
+  return [...skewLedger().get(name) ?? []].sort((a, b) => a - b);
+}
+
+// src/bus.ts
 function defaultKind() {
   return typeof document === "undefined" ? "worker" : "tab";
 }
-var registry = /* @__PURE__ */ new Map();
-function createBus(name, options, onShutdown) {
+var SHARED_WITHIN_CLIENT = /* @__PURE__ */ new Set(["state", "event", "op"]);
+function createBusCore(name, options, onShutdown) {
   const transport = (options.transport ?? defaultTransport)(name);
   const clientId = newClientId();
   const kind = options.kind ?? defaultKind();
-  const listeners = /* @__PURE__ */ new Set();
+  const handles = /* @__PURE__ */ new Set();
   let refs = 0;
   let closed = false;
-  const post = (wire) => {
+  const deliver = (wire, from) => {
+    for (const handle of handles) {
+      if (handle === from) continue;
+      for (const fn of handle.listeners) fn(wire);
+    }
+  };
+  const post = (wire, from) => {
     if (closed) return;
     emitBusEvent(name, "out", wire);
     transport.post(wire);
+    if (SHARED_WITHIN_CLIENT.has(wire.scope)) deliver(wire, from);
   };
   const unsubscribe = transport.subscribe((data) => {
+    const foreign = foreignWireVersion(data);
+    if (foreign !== null) {
+      recordSkew(name, foreign);
+      return;
+    }
     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 });
+      post({ v: 1, scope: "presence", type: "ping", clientId, kind }, null);
     }
-    for (const fn of listeners) fn(data);
+    deliver(data, null);
   });
-  post({ v: 1, scope: "presence", type: "hello", clientId, kind });
+  post({ v: 1, scope: "presence", type: "hello", clientId, kind }, null);
   const heartbeat = setInterval(
-    () => post({ v: 1, scope: "presence", type: "ping", clientId, kind }),
+    () => post({ v: 1, scope: "presence", type: "ping", clientId, kind }, null),
     options.heartbeatMs ?? 2e3
   );
-  const sayBye = () => post({ v: 1, scope: "presence", type: "bye", clientId, kind });
+  const sayBye = () => post({ v: 1, scope: "presence", type: "bye", clientId, kind }, null);
   const onPageShow = (event) => {
     if (!event.persisted) return;
-    post({ v: 1, scope: "presence", type: "hello", clientId, kind });
+    post({ v: 1, scope: "presence", type: "hello", clientId, kind }, null);
+  };
+  const onVisible = () => {
+    if (document.visibilityState === "visible") {
+      post({ v: 1, scope: "presence", type: "hello", clientId, kind }, null);
+    }
   };
   const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
   if (hasWindow) {
     addEventListener("pagehide", sayBye);
     addEventListener("pageshow", onPageShow);
+    addEventListener("visibilitychange", onVisible);
   }
+  const shutdown = () => {
+    sayBye();
+    closed = true;
+    clearInterval(heartbeat);
+    if (hasWindow) {
+      removeEventListener("pagehide", sayBye);
+      removeEventListener("pageshow", onPageShow);
+      removeEventListener("visibilitychange", onVisible);
+    }
+    unsubscribe();
+    transport.close();
+    handles.clear();
+    onShutdown();
+  };
   return {
     name,
     clientId,
     kind,
+    transportKind: transport.kind ?? "custom",
     heartbeatMs: options.heartbeatMs ?? 2e3,
-    post,
-    subscribe(fn) {
-      listeners.add(fn);
-      return () => listeners.delete(fn);
-    },
-    acquire() {
+    connect() {
+      const handle = { listeners: /* @__PURE__ */ new Set() };
+      handles.add(handle);
       refs++;
-    },
-    release() {
-      if (closed) return;
-      refs--;
-      if (refs > 0) return;
-      sayBye();
-      closed = true;
-      clearInterval(heartbeat);
-      if (hasWindow) {
-        removeEventListener("pagehide", sayBye);
-        removeEventListener("pageshow", onPageShow);
-      }
-      unsubscribe();
-      transport.close();
-      listeners.clear();
-      onShutdown();
+      let released = false;
+      return {
+        name,
+        clientId,
+        kind,
+        transportKind: transport.kind ?? "custom",
+        post: (wire) => post(wire, handle),
+        subscribe(fn) {
+          handle.listeners.add(fn);
+          return () => handle.listeners.delete(fn);
+        },
+        release() {
+          if (released || closed) return;
+          released = true;
+          handles.delete(handle);
+          handle.listeners.clear();
+          refs--;
+          if (refs === 0) shutdown();
+        }
+      };
     }
   };
 }
 function getBusNames() {
-  return [...registry.keys()];
+  return [...busTable().keys()];
+}
+function getTransportKind(name) {
+  return busTable().get(name)?.transportKind ?? null;
 }
 function getBus(name, options = {}) {
-  if (options.transport) {
-    const bus2 = createBus(name, options, () => {
-    });
-    bus2.acquire();
-    return bus2;
-  }
-  let bus = registry.get(name);
-  if (!bus) {
-    bus = createBus(name, options, () => registry.delete(name));
-    registry.set(name, bus);
+  if (options.transport) return createBusCore(name, options, () => {
+  }).connect();
+  const table = busTable();
+  let core = table.get(name);
+  if (!core) {
+    core = createBusCore(name, options, () => table.delete(name));
+    table.set(name, core);
   } else {
-    if (options.heartbeatMs !== void 0 && options.heartbeatMs !== bus.heartbeatMs) {
+    if (options.heartbeatMs !== void 0 && options.heartbeatMs !== core.heartbeatMs) {
+      if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          `[use-everywhere] bus "${name}": heartbeatMs ignored \u2014 the first creator fixes bus options`
+        );
+      }
+    }
+    if (options.kind !== void 0 && options.kind !== core.kind) {
+      if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          `[use-everywhere] bus "${name}": kind ignored \u2014 the first creator fixes bus options`
+        );
+      }
+    }
+  }
+  return core.connect();
+}
+
+// src/schema.ts
+function validate(schema, payload) {
+  const props = schema["~standard"];
+  const result = props.validate(payload);
+  if (typeof result.then === "function") {
+    return { ok: false, issues: [`the "${props.vendor}" schema validates asynchronously`] };
+  }
+  const sync = result;
+  if (sync.issues) return { ok: false, issues: sync.issues.map((issue) => issue.message) };
+  return { ok: true, value: sync.value };
+}
+function createGate(name, schemas, onInvalid) {
+  if (!schemas) return void 0;
+  const check = (key, payload, direction) => {
+    const schema = schemas[key];
+    if (!schema) return void 0;
+    const result = validate(schema, payload);
+    if (result.ok) return void 0;
+    const info = { name, key, direction, payload, issues: result.issues };
+    if (onInvalid) onInvalid(info);
+    else if (process.env.NODE_ENV !== "production") {
       devWarn(
-        `[use-everywhere] bus "${name}": heartbeatMs ignored \u2014 the first creator fixes bus options`
+        `[use-everywhere] ${name}/${key}: ${direction}bound payload rejected by its schema \u2014 ${result.issues.join("; ")}. https://rxova.org/guides/validating-payloads/`
       );
     }
-    if (options.kind !== void 0 && options.kind !== bus.kind) {
-      devWarn(`[use-everywhere] bus "${name}": kind ignored \u2014 the first creator fixes bus options`);
+    return result.issues;
+  };
+  return {
+    accepts: (key, payload) => !check(key, payload, "in"),
+    assert(key, payload) {
+      const issues = check(key, payload, "out");
+      if (issues) {
+        throw new TypeError(
+          `use-everywhere: ${name}/${key} \u2014 the value does not match its schema, so nothing was sent or applied. ${issues.join("; ")}`
+        );
+      }
     }
-  }
-  bus.acquire();
-  return bus;
+  };
 }
 
 // src/channel.ts
 function createChannel(name, options = {}) {
   const bus = getBus(name, options);
   const handlers = /* @__PURE__ */ new Map();
+  const responders = /* @__PURE__ */ new Map();
+  const waiting = /* @__PURE__ */ new Map();
+  const gate = createGate(name, options.schema, options.onInvalid);
+  const deliver = (type, payload, meta) => {
+    const set = handlers.get(type);
+    if (!set) return;
+    for (const fn of [...set]) fn(payload, meta);
+  };
   const unsubscribe = bus.subscribe((wire) => {
     if (wire.scope !== "event") return;
-    const set = handlers.get(wire.type);
-    if (!set) return;
     const meta = { clientId: wire.clientId, kind: wire.kind, self: false };
-    for (const fn of set) fn(wire.payload, meta);
-  });
-  let closed = false;
-  return {
-    name,
-    clientId: bus.clientId,
-    post(type, payload) {
+    if (wire.replyTo !== void 0) {
+      const settle = waiting.get(wire.replyTo);
+      if (!settle) return;
+      waiting.delete(wire.replyTo);
+      settle(wire.payload);
+      return;
+    }
+    const responder = responders.get(wire.type);
+    if (responder) {
       bus.post({
         v: 1,
         scope: "event",
-        type,
-        payload,
+        type: wire.type,
+        payload: responder(wire.payload, meta),
         clientId: bus.clientId,
         kind: bus.kind,
-        msgId: newMsgId()
+        msgId: newMsgId(),
+        replyTo: wire.msgId
       });
+    }
+    if (!handlers.has(wire.type)) return;
+    if (gate && !gate.accepts(wire.type, wire.payload)) return;
+    deliver(wire.type, wire.payload, meta);
+  });
+  let closed = false;
+  const send = (type, payload, msgId) => {
+    gate?.assert(type, payload);
+    bus.post({
+      v: 1,
+      scope: "event",
+      type,
+      payload,
+      clientId: bus.clientId,
+      kind: bus.kind,
+      msgId
+    });
+  };
+  return {
+    name,
+    clientId: bus.clientId,
+    post(type, payload, options2) {
+      send(type, payload, newMsgId());
+      if (options2?.echo) {
+        deliver(type, payload, { clientId: bus.clientId, kind: bus.kind, self: true });
+      }
     },
-    on(type, handler) {
+    on(type, handler, options2) {
       let set = handlers.get(type);
       if (!set) {
         set = /* @__PURE__ */ new Set();
         handlers.set(type, set);
       }
-      set.add(handler);
-      return () => set.delete(handler);
+      const entry = options2?.once ? (payload, meta) => {
+        set.delete(entry);
+        handler(payload, meta);
+      } : handler;
+      set.add(entry);
+      return () => set.delete(entry);
+    },
+    ask(type, payload, options2) {
+      const msgId = newMsgId();
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          waiting.delete(msgId);
+          reject(
+            new Error(
+              `use-everywhere: nobody answered "${type}" on "${name}" within ${String(options2?.timeoutMs ?? 5e3)}ms`
+            )
+          );
+        }, options2?.timeoutMs ?? 5e3);
+        waiting.set(msgId, (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        });
+        try {
+          send(type, payload, msgId);
+        } catch (error) {
+          clearTimeout(timer);
+          waiting.delete(msgId);
+          throw error;
+        }
+      });
+    },
+    answer(type, responder) {
+      responders.set(type, responder);
+      return () => responders.delete(type);
     },
     close() {
       if (closed) return;
       closed = true;
       unsubscribe();
       handlers.clear();
+      responders.clear();
+      waiting.clear();
       bus.release();
     }
   };
@@ -269,6 +580,9 @@ function createChannel(name, options = {}) {
 function newer(a, b) {
   return !b || a[0] > b[0] || a[0] === b[0] && a[1] > b[1];
 }
+function isVersion(value) {
+  return Array.isArray(value) && value.length === 2 && typeof value[0] === "number" && Number.isFinite(value[0]) && typeof value[1] === "string";
+}
 
 // src/dev-freeze.ts
 var inDev2 = false;
@@ -307,15 +621,18 @@ function createSharedStore(name, initial, options = {}) {
   if (onSharedBus) {
     const live = liveStores.get(name) ?? 0;
     if (live > 0) {
-      devWarn(
-        `[use-everywhere] second shared store for "${name}" in this tab \u2014 stores on one page never hear each other and will diverge. Reuse one per name.`
-      );
+      if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          `[use-everywhere] second shared store for "${name}" in this tab \u2014 they stay in sync, but you are paying twice for one store's state, subscriptions, and persistence writes. Reuse one per name.`
+        );
+      }
     }
     liveStores.set(name, live + 1);
   }
   const bus = getBus(name, options);
   const clientId = bus.clientId;
   const accept = options.accept;
+  const gate = createGate(name, options.schema, options.onInvalid);
   const state = { ...initial };
   const versions = {};
   for (const k in state) {
@@ -326,23 +643,61 @@ function createSharedStore(name, initial, options = {}) {
   let versionsSnapshot = Object.freeze({ ...versions });
   const listeners = /* @__PURE__ */ new Set();
   const keyListeners = /* @__PURE__ */ new Map();
-  function notify(key, value, meta) {
+  let batchDepth = 0;
+  const batched = [];
+  const rebuild = () => {
     snapshot = Object.freeze({ ...state });
     versionsSnapshot = Object.freeze({ ...versions });
+  };
+  const emit = (key, value, meta) => {
     for (const fn of listeners) fn(key, value, meta);
     const set = keyListeners.get(key);
     if (set) for (const fn of set) fn();
+  };
+  function notify(key, value, meta) {
+    if (batchDepth > 0) {
+      batched.push([key, value, meta]);
+      return;
+    }
+    rebuild();
+    emit(key, value, meta);
+  }
+  function batch(fn) {
+    batchDepth++;
+    try {
+      return fn();
+    } finally {
+      batchDepth--;
+      if (batchDepth === 0 && batched.length > 0) {
+        const changes = batched.splice(0, batched.length);
+        rebuild();
+        for (const [key, value, meta] of changes) emit(key, value, meta);
+      }
+    }
   }
   function applyRemote(key, value, version, meta) {
     if (!newer(version, versions[key])) return;
+    if (gate && !gate.accepts(key, value)) return;
     versions[key] = version;
     state[key] = freezeShared(value);
     notify(key, value, meta);
   }
-  const unsubscribe = bus.subscribe((wire) => {
-    if (wire.scope !== "state") return;
-    const meta = { clientId: wire.clientId, kind: wire.kind, self: false };
-    if (wire.type === "hello") {
+  const snapshotDelayMs = options.snapshotDelayMs ?? 40;
+  let snapshotTimer;
+  const written = () => Object.keys(versions).filter((k) => (versions[k]?.[0] ?? 0) > 0);
+  const coveredBy = (theirs) => written().every((key) => {
+    const mine = versions[key];
+    return mine !== void 0 && !newer(mine, theirs[key]);
+  });
+  const cancelSnapshot = () => {
+    clearTimeout(snapshotTimer);
+    snapshotTimer = void 0;
+  };
+  const scheduleSnapshot = () => {
+    if (written().length === 0) return;
+    if (snapshotTimer !== void 0) return;
+    snapshotTimer = setTimeout(() => {
+      snapshotTimer = void 0;
       bus.post({
         v: 1,
         scope: "state",
@@ -352,19 +707,36 @@ function createSharedStore(name, initial, options = {}) {
         state: { ...state },
         versions: { ...versions }
       });
+    }, Math.random() * snapshotDelayMs);
+  };
+  const unsubscribe = bus.subscribe((wire) => {
+    if (wire.scope !== "state") return;
+    const meta = { clientId: wire.clientId, kind: wire.kind, self: false };
+    if (wire.type === "hello") {
+      scheduleSnapshot();
       return;
     }
     if (accept && !accept(meta)) return;
     if (wire.type === "patch") {
+      if (typeof wire.key !== "string" || !isVersion(wire.version)) return;
       applyRemote(wire.key, wire.value, wire.version, meta);
-    } else {
-      for (const k in wire.state) {
-        const version = wire.versions[k];
-        if (version) applyRemote(k, wire.state[k], version, meta);
-      }
+      return;
+    }
+    if (wire.type === "snapshot") {
+      const versions2 = wire.versions;
+      if (typeof versions2 !== "object" || versions2 === null) return;
+      if (coveredBy(versions2)) cancelSnapshot();
+      batch(() => {
+        for (const k in wire.state) {
+          const version = versions2[k];
+          if (isVersion(version)) applyRemote(k, wire.state[k], version, meta);
+        }
+      });
+      return;
     }
   });
   function setKey(key, value) {
+    gate?.assert(key, value);
     const version = [(versions[key]?.[0] ?? 0) + 1, clientId];
     try {
       bus.post({
@@ -396,29 +768,73 @@ function createSharedStore(name, initial, options = {}) {
   });
   const persist = options.persist;
   let flushPersist;
+  let settle = () => {
+  };
+  const hydrated = persist ? new Promise((resolve) => {
+    settle = resolve;
+  }) : Promise.resolve();
   if (persist) {
-    const { adapter, keys, debounceMs = 100 } = persist;
+    const {
+      adapter,
+      keys,
+      debounceMs = 100,
+      version: schemaVersion = 0,
+      migrate,
+      onRestoreError
+    } = 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];
+    const refuse = (error) => {
+      if (onRestoreError) onRestoreError(error);
+      else if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          `[use-everywhere] ${name}: persisted schema v${error.found} not restored, expected v${error.expected} (${error.reason}). https://rxova.org/guides/persistence/`
+        );
+      }
+    };
+    const reconcile = (saved2) => {
+      const found = saved2.schema ?? 0;
+      if (found === schemaVersion) return { state: saved2.state, migrated: false };
+      if (found > schemaVersion) {
+        refuse({ reason: "ahead", found, expected: schemaVersion });
+        return void 0;
+      }
+      if (!migrate) {
+        refuse({ reason: "no-migrate", found, expected: schemaVersion });
+        return void 0;
+      }
+      try {
+        return { state: migrate(saved2.state, found), migrated: true };
+      } catch (cause) {
+        refuse({ reason: "migrate-threw", found, expected: schemaVersion, cause });
+        return void 0;
+      }
+    };
+    const hydrate = (raw) => {
+      const reconciled = raw && reconcile(raw);
+      if (!reconciled || !raw) {
+        settle();
+        return;
+      }
+      const { state: restored, migrated } = reconciled;
+      for (const key in restored) {
+        const version = raw.versions[key] ?? (migrated ? [1, clientId] : void 0);
         if (!version || !shouldPersist(key)) continue;
-        applyRemote(key, saved2.state[key], version, { clientId, kind: bus.kind, self: true });
+        applyRemote(key, restored[key], version, { clientId, kind: bus.kind, self: true });
         bus.post({
           v: 1,
           scope: "state",
           type: "patch",
           key,
-          value: saved2.state[key],
+          value: restored[key],
           version,
           clientId,
           kind: bus.kind
         });
       }
+      settle();
     };
     const collect = () => {
-      const out = { v: 1, state: {}, versions: {} };
+      const out = { v: 1, schema: schemaVersion, state: {}, versions: {} };
       for (const key in versions) {
         const version = versions[key];
         if (!version || version[0] === 0 || !shouldPersist(key)) continue;
@@ -458,6 +874,7 @@ function createSharedStore(name, initial, options = {}) {
   let storeClosed = false;
   return {
     clientId,
+    hydrated,
     state: proxy,
     getSnapshot: () => snapshot,
     getVersions: () => versionsSnapshot,
@@ -465,6 +882,9 @@ function createSharedStore(name, initial, options = {}) {
       const next = typeof value === "function" ? value(state[key]) : value;
       setKey(key, next);
     },
+    transaction(fn) {
+      return batch(fn);
+    },
     subscribe(fn) {
       listeners.add(fn);
       return () => listeners.delete(fn);
@@ -496,6 +916,7 @@ function createSharedStore(name, initial, options = {}) {
         if (live > 0) liveStores.set(name, live);
         else liveStores.delete(name);
       }
+      cancelSnapshot();
       if (hasWindow) removeEventListener("pageshow", onPageShow);
       if (flushPersist) {
         flushPersist();
@@ -511,62 +932,149 @@ function createSharedStore(name, initial, options = {}) {
   };
 }
 
-// src/presence.ts
-function createPresence(name, options = {}) {
-  const pruneAfterMs = options.pruneAfterMs ?? 5e3;
-  const bus = getBus(name, options);
-  const peers = /* @__PURE__ */ new Map();
+// src/leader-web-locks.ts
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+function createWebLocksLeader(name, options, locks) {
+  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 snapshot = NO_LEADER;
+  let closed = false;
   const listeners = /* @__PURE__ */ new Set();
-  let snapshot = [];
-  function notify() {
-    snapshot = Object.freeze([...peers.values()]);
+  const waiters = /* @__PURE__ */ new Set();
+  let releaseHeld = null;
+  let pending = null;
+  function setLeader(id) {
+    if (id === leaderId) return;
+    leaderId = id;
+    snapshot = Object.freeze({ leaderId: id, isLeader: id === clientId });
     for (const fn of listeners) fn();
+    if (id === clientId) {
+      for (const waiter of waiters) waiter.resolve();
+      waiters.clear();
+    }
   }
+  const term = [1, clientId];
+  const announce2 = () => bus.post({ v: 1, scope: "leader", type: "heartbeat", term, clientId, kind: bus.kind });
   const unsubscribe = bus.subscribe((wire) => {
-    if (wire.scope === "presence" && wire.type === "bye") {
-      if (peers.delete(wire.clientId)) notify();
+    if (wire.scope !== "leader") return;
+    if (wire.type === "hello") {
+      if (leaderId === clientId) announce2();
       return;
     }
-    const existing = peers.get(wire.clientId);
-    peers.set(wire.clientId, { id: wire.clientId, kind: wire.kind, lastSeen: Date.now() });
-    if (!existing) notify();
+    if (wire.type === "resign") {
+      if (wire.clientId === leaderId) setLeader(null);
+      return;
+    }
+    setLeader(wire.clientId);
   });
-  const prune = setInterval(
-    () => {
-      const cutoff = Date.now() - pruneAfterMs;
-      let changed = false;
-      for (const [id, peer] of peers) {
-        if (peer.lastSeen < cutoff) {
-          peers.delete(id);
-          changed = true;
-        }
-      }
-      if (changed) notify();
-    },
-    Math.max(500, Math.floor(pruneAfterMs / 2))
-  );
-  let closed = false;
+  function joinQueue() {
+    if (closed || !eligible || releaseHeld || pending) return;
+    const controller = new AbortController();
+    pending = controller;
+    const held = new Promise((resolve) => {
+      releaseHeld = resolve;
+    });
+    void locks.request(name, { signal: controller.signal }, async () => {
+      pending = null;
+      if (closed || !eligible) return;
+      setLeader(clientId);
+      announce2();
+      await held;
+    }).catch(() => {
+    });
+  }
+  function letGo() {
+    const release = releaseHeld;
+    releaseHeld = null;
+    release?.();
+  }
+  function resign() {
+    if (leaderId !== clientId) return;
+    letGo();
+    setLeader(null);
+    bus.post({ v: 1, scope: "leader", type: "resign", term, clientId, kind: bus.kind });
+    joinQueue();
+  }
+  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 });
+  joinQueue();
   return {
-    clientId: bus.clientId,
-    getPeers: () => snapshot,
+    clientId,
+    strategy: "web-locks",
+    getSnapshot: () => snapshot,
     subscribe(fn) {
       listeners.add(fn);
       return () => listeners.delete(fn);
     },
+    waitForLeadership() {
+      if (leaderId === clientId) return Promise.resolve();
+      if (closed) return Promise.reject(new Error("leader is closed"));
+      return new Promise((resolve, reject) => {
+        waiters.add({ resolve, reject });
+      });
+    },
+    resign,
+    setEligible(next) {
+      if (next === eligible) return;
+      eligible = next;
+      if (next) {
+        joinQueue();
+        return;
+      }
+      if (leaderId === clientId) resignWithoutRequeue();
+      pending?.abort();
+      pending = null;
+    },
     close() {
       if (closed) return;
       closed = true;
-      clearInterval(prune);
+      if (leaderId === clientId) resignWithoutRequeue();
+      pending?.abort();
+      pending = null;
+      if (hasWindow) removeEventListener("pagehide", onPageHide);
+      for (const waiter of waiters) waiter.reject(new Error("leader is closed"));
+      waiters.clear();
       unsubscribe();
       listeners.clear();
       bus.release();
     }
   };
+  function resignWithoutRequeue() {
+    letGo();
+    setLeader(null);
+    bus.post({ v: 1, scope: "leader", type: "resign", term, clientId, kind: bus.kind });
+  }
 }
 
 // src/leader.ts
-var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+var NO_LEADER2 = Object.freeze({ leaderId: null, isLeader: false });
+function availableLocks(options) {
+  if (options.locks) return options.locks;
+  const locks = globalThis.navigator?.locks;
+  return typeof locks?.request === "function" ? locks : void 0;
+}
 function createLeader(name, options = {}) {
+  const strategy = options.strategy ?? "auto";
+  if (strategy !== "heartbeat") {
+    const locks = availableLocks(options);
+    if (locks) return createWebLocksLeader(name, options, locks);
+    if (strategy === "web-locks") {
+      throw new Error(
+        'strategy: "web-locks" was requested but navigator.locks is unavailable. Web Locks needs a secure context (https, or localhost) \u2014 use "auto" to fall back to the heartbeat election.'
+      );
+    }
+  }
+  return createHeartbeatLeader(name, options);
+}
+function createHeartbeatLeader(name, options) {
   const heartbeatMs = options.heartbeatMs ?? 1e3;
   const leaseMs = options.leaseMs ?? 3e3;
   const busOptions = {
@@ -578,16 +1086,21 @@ function createLeader(name, options = {}) {
   let eligible = options.eligible ?? true;
   let leaderId = null;
   let term = [0, clientId];
-  let snapshot = NO_LEADER;
+  let snapshot = NO_LEADER2;
   let beat;
   let lease;
   let closed = false;
   const listeners = /* @__PURE__ */ new Set();
+  const waiters = /* @__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();
+    if (id === clientId) {
+      for (const waiter of waiters) waiter.resolve();
+      waiters.clear();
+    }
   }
   function armLease(delay) {
     clearTimeout(lease);
@@ -625,6 +1138,7 @@ function createLeader(name, options = {}) {
       armLease(0);
       return;
     }
+    if (!isVersion(wire.term)) return;
     if (newer(wire.term, term)) {
       term = wire.term;
       stepDown(wire.clientId);
@@ -660,11 +1174,19 @@ function createLeader(name, options = {}) {
   armLease(heartbeatMs);
   return {
     clientId,
+    strategy: "heartbeat",
     getSnapshot: () => snapshot,
     subscribe(fn) {
       listeners.add(fn);
       return () => listeners.delete(fn);
     },
+    waitForLeadership() {
+      if (leaderId === clientId) return Promise.resolve();
+      if (closed) return Promise.reject(new Error("leader is closed"));
+      return new Promise((resolve, reject) => {
+        waiters.add({ resolve, reject });
+      });
+    },
     resign,
     setEligible(next) {
       if (next === eligible) return;
@@ -679,6 +1201,8 @@ function createLeader(name, options = {}) {
       if (closed) return;
       closed = true;
       resign();
+      for (const waiter of waiters) waiter.reject(new Error("leader is closed"));
+      waiters.clear();
       clearInterval(beat);
       clearTimeout(lease);
       if (hasWindow) {
@@ -692,6 +1216,246 @@ function createLeader(name, options = {}) {
   };
 }
 
+// src/shared-reducer.ts
+function createSharedReducer(name, reducer, initial, options = {}) {
+  const key = options.key ?? "default";
+  const bus = getBus(name, options);
+  const clientId = bus.clientId;
+  const leader = options.leader ?? createLeader(name, {
+    ...options.leaderOptions,
+    // Spread conditionally: `exactOptionalPropertyTypes` distinguishes an
+    // absent transport from one explicitly set to undefined, and the leader
+    // must default its own rather than be handed a hole.
+    ...options.transport ? { transport: options.transport } : {}
+  });
+  const ownsLeader = !options.leader;
+  let committed = initial;
+  let seq = 0;
+  let pending = [];
+  const early = /* @__PURE__ */ new Map();
+  let lastIssued = 0;
+  let view = committed;
+  const listeners = /* @__PURE__ */ new Set();
+  let closed = false;
+  const notify = () => {
+    const next = pending.reduce((state, op) => reducer(state, op.action), committed);
+    if (Object.is(next, view)) return;
+    view = next;
+    for (const fn of listeners) fn();
+  };
+  const askForSnapshot = () => bus.post({ v: 1, scope: "op", type: "hello", key, clientId, kind: bus.kind });
+  const receiveCommit = (at, action, opId) => {
+    if (at <= seq) return;
+    if (at > seq + 1) {
+      early.set(at, { action, opId });
+      askForSnapshot();
+      return;
+    }
+    applyCommit(at, action, opId);
+    notify();
+  };
+  const sequence = (action, opId) => {
+    lastIssued = Math.max(lastIssued, seq) + 1;
+    const at = lastIssued;
+    bus.post({
+      v: 1,
+      scope: "op",
+      type: "commit",
+      key,
+      action,
+      opId,
+      seq: at,
+      clientId,
+      kind: bus.kind
+    });
+    receiveCommit(at, action, opId);
+  };
+  const applyCommit = (at, action, opId) => {
+    committed = reducer(committed, action);
+    seq = at;
+    pending = pending.filter((op) => op.opId !== opId);
+    const next = early.get(seq + 1);
+    if (next) {
+      early.delete(seq + 1);
+      applyCommit(seq + 1, next.action, next.opId);
+    }
+  };
+  const unsubscribe = bus.subscribe((wire) => {
+    if (wire.scope !== "op" || wire.key !== key) return;
+    if (wire.type === "propose") {
+      if (!leader.getSnapshot().isLeader) return;
+      sequence(wire.action, wire.opId);
+      return;
+    }
+    if (wire.type === "commit") {
+      receiveCommit(wire.seq, wire.action, wire.opId);
+      return;
+    }
+    if (wire.type === "hello") {
+      if (seq === 0) return;
+      bus.post({
+        v: 1,
+        scope: "op",
+        type: "snapshot",
+        key,
+        state: committed,
+        seq,
+        clientId,
+        kind: bus.kind
+      });
+      return;
+    }
+    if (wire.type === "snapshot") {
+      if (wire.seq <= seq) return;
+      committed = wire.state;
+      seq = wire.seq;
+      for (const at of [...early.keys()]) if (at <= seq) early.delete(at);
+      const next = early.get(seq + 1);
+      if (next) {
+        early.delete(seq + 1);
+        applyCommit(seq + 1, next.action, next.opId);
+      }
+      notify();
+      return;
+    }
+  });
+  const dispatch = (action) => {
+    if (closed) return;
+    const opId = newMsgId();
+    pending.push({ opId, action });
+    notify();
+    if (leader.getSnapshot().isLeader) sequence(action, opId);
+    else
+      bus.post({ v: 1, scope: "op", type: "propose", key, action, opId, clientId, kind: bus.kind });
+  };
+  askForSnapshot();
+  return {
+    clientId,
+    getSnapshot: () => view,
+    dispatch,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    pendingCount: () => pending.length,
+    close() {
+      if (closed) return;
+      closed = true;
+      unsubscribe();
+      listeners.clear();
+      if (ownsLeader) leader.close();
+      bus.release();
+    }
+  };
+}
+
+// src/presence.ts
+function createPresence(name, options = {}) {
+  const pruneAfterMs = options.pruneAfterMs ?? 5e3;
+  const probeGraceMs = options.probeGraceMs ?? 1e3;
+  const bus = getBus(name, options);
+  const peers = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = [];
+  let metadata = options.metadata;
+  const same = (a, b) => {
+    if (Object.is(a, b)) return true;
+    try {
+      return JSON.stringify(a) === JSON.stringify(b);
+    } catch {
+      return false;
+    }
+  };
+  const self = () => ({
+    id: bus.clientId,
+    kind: bus.kind,
+    lastSeen: Date.now(),
+    ...metadata === void 0 ? {} : { metadata }
+  });
+  function notify() {
+    const roster = [...peers.values()];
+    snapshot = Object.freeze(options.includeSelf ? [self(), ...roster] : roster);
+    for (const fn of listeners) fn();
+  }
+  const announce2 = () => bus.post({
+    v: 1,
+    scope: "presence",
+    type: "hello",
+    clientId: bus.clientId,
+    kind: bus.kind,
+    ...metadata === void 0 ? {} : { metadata }
+  });
+  const unsubscribe = bus.subscribe((wire) => {
+    if (wire.clientId === bus.clientId) return;
+    if (wire.scope === "presence" && wire.type === "bye") {
+      if (peers.delete(wire.clientId)) notify();
+      return;
+    }
+    const existing = peers.get(wire.clientId);
+    const announced = wire.scope === "presence" ? wire.metadata : void 0;
+    const next = announced === void 0 ? existing?.metadata : announced;
+    peers.set(wire.clientId, {
+      id: wire.clientId,
+      kind: wire.kind,
+      lastSeen: Date.now(),
+      ...next === void 0 ? {} : { metadata: next }
+    });
+    if (!existing || !same(existing.metadata, next)) notify();
+  });
+  announce2();
+  if (options.includeSelf) notify();
+  const probed = /* @__PURE__ */ new Map();
+  const prune = setInterval(
+    () => {
+      const now = Date.now();
+      const silentSince = now - pruneAfterMs;
+      let changed = false;
+      let needProbe = false;
+      for (const [id, peer] of peers) {
+        if (peer.lastSeen >= silentSince) {
+          probed.delete(id);
+          continue;
+        }
+        const askedAt = probed.get(id);
+        if (askedAt === void 0) {
+          probed.set(id, now);
+          needProbe = true;
+        } else if (now - askedAt >= probeGraceMs) {
+          peers.delete(id);
+          probed.delete(id);
+          changed = true;
+        }
+      }
+      if (needProbe) announce2();
+      if (changed) notify();
+    },
+    Math.max(250, Math.floor(Math.min(pruneAfterMs, probeGraceMs) / 2))
+  );
+  let closed = false;
+  return {
+    clientId: bus.clientId,
+    getPeers: () => snapshot,
+    setMetadata(next) {
+      if (same(metadata, next)) return;
+      metadata = next;
+      announce2();
+      notify();
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      clearInterval(prune);
+      unsubscribe();
+      listeners.clear();
+      bus.release();
+    }
+  };
+}
+
 // src/persist-web-storage.ts
 function isPersisted(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -699,6 +1463,7 @@ function isPersisted(value) {
   return candidate.v === 1 && typeof candidate.state === "object" && typeof candidate.versions === "object";
 }
 function webStorageAdapter(storage, key, options = {}) {
+  const serializer = options.serializer ?? jsonSerializer;
   const report = (error, operation) => {
     try {
       options.onError?.(error, operation);
@@ -718,7 +1483,7 @@ function webStorageAdapter(storage, key, options = {}) {
       try {
         const raw = resolve("read")?.getItem(key);
         if (!raw) return void 0;
-        const parsed = JSON.parse(raw);
+        const parsed = serializer.parse(raw);
         return isPersisted(parsed) ? parsed : void 0;
       } catch (error) {
         report(error, "read");
@@ -727,7 +1492,7 @@ function webStorageAdapter(storage, key, options = {}) {
     },
     write(snapshot) {
       try {
-        resolve("write")?.setItem(key, JSON.stringify(snapshot));
+        resolve("write")?.setItem(key, serializer.stringify(snapshot));
       } catch (error) {
         report(error, "write");
       }
@@ -748,6 +1513,58 @@ function sessionStorageAdapter(key, options) {
   return webStorageAdapter(() => globalThis.sessionStorage, key, options);
 }
 
+// src/persist-indexeddb.ts
+var STORE = "state";
+var request = (req) => new Promise((resolve, reject) => {
+  req.onsuccess = () => resolve(req.result);
+  req.onerror = () => reject(req.error);
+});
+function indexedDbAdapter(key, options = {}) {
+  const database = options.database ?? "use-everywhere";
+  let open;
+  const report = (error, operation) => {
+    try {
+      options.onError?.(error, operation);
+    } catch {
+    }
+  };
+  const db = () => open ?? (open = new Promise((resolve, reject) => {
+    const req = indexedDB.open(database, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+    req.onblocked = () => reject(new Error("use-everywhere: IndexedDB upgrade blocked"));
+  }));
+  const transact = async (mode, run) => {
+    const connection = await db();
+    return request(run(connection.transaction(STORE, mode).objectStore(STORE)));
+  };
+  return {
+    async read() {
+      try {
+        return await transact("readonly", (store) => store.get(key));
+      } catch (error) {
+        report(error, "read");
+        return void 0;
+      }
+    },
+    async write(snapshot) {
+      try {
+        await transact("readwrite", (store) => store.put(snapshot, key));
+      } catch (error) {
+        report(error, "write");
+      }
+    },
+    async remove() {
+      try {
+        await transact("readwrite", (store) => store.delete(key));
+      } catch (error) {
+        report(error, "remove");
+      }
+    }
+  };
+}
+
 // src/errors/handshake-timeout-error.ts
 var HandshakeTimeoutError = class extends Error {
   constructor(message = "handshake with the other window timed out") {
@@ -982,22 +1799,50 @@ function connectToOpener(options) {
     }
   };
 }
+
+// src/namespace.ts
+var SEPARATOR = ":";
+function createNamespace(namespace) {
+  if (!namespace) {
+    throw new TypeError(
+      "use-everywhere: createNamespace() needs a non-empty name \u2014 an empty one would put every bus back on the shared defaults, which is what it exists to prevent."
+    );
+  }
+  const busName = (name = DEFAULT_NAME) => `${namespace}${SEPARATOR}${name}`;
+  return {
+    name: namespace,
+    busName,
+    createSharedStore: (name, initial, options) => createSharedStore(busName(name), initial, options),
+    createChannel: (name, options) => createChannel(busName(name), options),
+    createPresence: (name, options) => createPresence(busName(name), options),
+    createLeader: (name, options) => createLeader(busName(name), options)
+  };
+}
 export {
   BroadcastChannelTransport,
   CID_PARAM,
   DEFAULT_NAME,
   HandshakeTimeoutError,
   NoopTransport,
+  StorageTransport,
+  WIRE_VERSION,
   WindowClosedError,
   connectToOpener,
   createChannel,
   createLeader,
+  createNamespace,
   createPresence,
+  createSharedReducer,
   createSharedStore,
   defaultTransport,
   enableDebug,
   getBusNames,
+  getTransportKind,
+  getWireSkew,
+  indexedDbAdapter,
   isBroadcastChannelAvailable,
+  isStorageEventAvailable,
+  jsonSerializer,
   localStorageAdapter,
   newer,
   observeBus,