@use-everywhere/core 0.7.0 → 0.9.0

package/dist/index.js

@@ -1,6 +1,26 @@
 // src/defaults.ts
 var DEFAULT_NAME = "use-everywhere";
 
+// src/dev.ts
+var inDev = false;
+try {
+  inDev = process.env.NODE_ENV !== "production";
+} catch {
+}
+var warned = /* @__PURE__ */ new Set();
+var DOCS = "https://rxova.org/packages/use-everywhere/errors";
+function diagnostic(code, message) {
+  return `[use-everywhere] ${code}: ${message}
+  \u2192 ${DOCS}/#${code.toLowerCase()}`;
+}
+function devWarn(code, message) {
+  if (!inDev) return;
+  const line = diagnostic(code, message);
+  if (warned.has(line)) return;
+  warned.add(line);
+  console.warn(line);
+}
+
 // src/debug.ts
 var observers = /* @__PURE__ */ new Map();
 function emitBusEvent(name, direction, wire) {
@@ -11,7 +31,7 @@ function emitBusEvent(name, direction, wire) {
     try {
       fn(event);
     } catch (error) {
-      console.error(`[use-everywhere] a bus observer for "${name}" threw`, error);
+      console.error(diagnostic("UE1012", `a bus observer for "${name}" threw`), error);
     }
   }
 }
@@ -38,19 +58,6 @@ function enableDebug(options = {}) {
   });
 }
 
-// src/dev.ts
-var inDev = false;
-try {
-  inDev = process.env.NODE_ENV !== "production";
-} catch {
-}
-var warned = /* @__PURE__ */ new Set();
-function devWarn(message) {
-  if (!inDev || warned.has(message)) return;
-  warned.add(message);
-  console.warn(message);
-}
-
 // src/ids.ts
 function randomHex(bytes) {
   const crypto = globalThis.crypto;
@@ -60,9 +67,12 @@ 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(
+      "UE1006",
+      "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");
@@ -79,15 +89,19 @@ function newMsgId() {
 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) {
-    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.`
-    );
+    if (process.env.NODE_ENV !== "production") {
+      devWarn(
+        "UE1008",
+        `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() {
@@ -95,6 +109,10 @@ function busTable() {
   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 {
@@ -134,24 +152,57 @@ 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/packages/use-everywhere/guides/serialization/`
+        );
+      }
+      return forJson;
+    });
+  },
+  parse: (text) => JSON.parse(text)
+};
+
 // src/transport/storage-transport.ts
 var StorageTransport = class {
-  constructor(name, storage = globalThis.localStorage) {
+  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."
+        diagnostic(
+          "UE1011",
+          "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 = JSON.parse(event.newValue);
+        payload = this.serializer.parse(event.newValue);
       } catch {
         return;
       }
@@ -160,7 +211,7 @@ var StorageTransport = class {
     addEventListener("storage", this.onStorage);
   }
   post(data) {
-    const envelope = JSON.stringify({ seq: this.seq++, data }, rejectUnrepresentable);
+    const envelope = this.serializer.stringify({ seq: this.seq++, data });
     try {
       this.storage.setItem(this.key, envelope);
       this.storage.removeItem(this.key);
@@ -176,12 +227,6 @@ var StorageTransport = class {
     removeEventListener("storage", this.onStorage);
   }
 };
-function rejectUnrepresentable(_key, value) {
-  if (typeof value === "function" || typeof value === "symbol") {
-    throw new TypeError(`${typeof value} values cannot be shared`);
-  }
-  return value;
-}
 
 // src/transport/default-transport.ts
 function isBroadcastChannelAvailable() {
@@ -203,27 +248,61 @@ function isStorageEventAvailable() {
 function defaultTransport(name) {
   if (isBroadcastChannelAvailable()) return new BroadcastChannelTransport(name);
   if (isStorageEventAvailable()) {
+    if (process.env.NODE_ENV !== "production") {
+      devWarn(
+        "UE1009",
+        "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; using the storage-event fallback. Values serialise as JSON, not structured clone \u2014 keep them JSON-shaped."
+      "UE1010",
+      "no BroadcastChannel and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
     );
-    return new StorageTransport(name);
   }
-  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) {
   if (typeof data !== "object" || data === null) return false;
   const wire = data;
-  return wire.v === 1 && typeof wire.scope === "string" && typeof wire.type === "string" && typeof wire.clientId === "string";
+  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(
+      "UE1007",
+      `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/packages/use-everywhere/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 SHARED_WITHIN_CLIENT = /* @__PURE__ */ new Set(["state", "event"]);
+var SHARED_WITHIN_CLIENT = /* @__PURE__ */ new Set(["state", "event", "op"]);
 function createBusCore(name, options, onShutdown) {
   const transport = (options.transport ?? defaultTransport)(name);
   const clientId = newClientId();
@@ -244,6 +323,11 @@ function createBusCore(name, options, onShutdown) {
     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);
@@ -336,57 +420,172 @@ function getBus(name, options = {}) {
     table.set(name, core);
   } else {
     if (options.heartbeatMs !== void 0 && options.heartbeatMs !== core.heartbeatMs) {
-      devWarn(
-        `[use-everywhere] bus "${name}": heartbeatMs ignored \u2014 the first creator fixes bus options`
-      );
+      if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          "UE1004",
+          `bus "${name}": heartbeatMs ignored \u2014 the first creator fixes bus options`
+        );
+      }
     }
     if (options.kind !== void 0 && options.kind !== core.kind) {
-      devWarn(`[use-everywhere] bus "${name}": kind ignored \u2014 the first creator fixes bus options`);
+      if (process.env.NODE_ENV !== "production") {
+        devWarn("UE1005", `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(
+        "UE1003",
+        `${name}/${key}: ${direction}bound payload rejected by its schema \u2014 ${result.issues.join("; ")}. https://rxova.org/packages/use-everywhere/guides/validating-payloads/`
+      );
+    }
+    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("; ")}`
+        );
+      }
+    }
+  };
+}
+
 // 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();
     }
   };
@@ -437,15 +636,19 @@ 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 they stay in sync, but you are paying twice for one store's state, subscriptions, and persistence writes. Reuse one per name.`
-      );
+      if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          "UE1001",
+          `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) {
@@ -456,23 +659,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",
@@ -482,22 +723,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 {
+      return;
+    }
+    if (wire.type === "snapshot") {
       const versions2 = wire.versions;
       if (typeof versions2 !== "object" || versions2 === null) return;
-      for (const k in wire.state) {
-        const version = versions2[k];
-        if (isVersion(version)) applyRemote(k, wire.state[k], version, meta);
-      }
+      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({
@@ -529,29 +784,74 @@ 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(
+          "UE1002",
+          `${name}: persisted schema v${error.found} not restored, expected v${error.expected} (${error.reason}). https://rxova.org/packages/use-everywhere/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;
@@ -591,6 +891,7 @@ function createSharedStore(name, initial, options = {}) {
   let storeClosed = false;
   return {
     clientId,
+    hydrated,
     state: proxy,
     getSnapshot: () => snapshot,
     getVersions: () => versionsSnapshot,
@@ -598,6 +899,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);
@@ -629,6 +933,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();
@@ -644,83 +949,6 @@ function createSharedStore(name, initial, options = {}) {
   };
 }
 
-// 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 = [];
-  function notify() {
-    snapshot = Object.freeze([...peers.values()]);
-    for (const fn of listeners) fn();
-  }
-  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);
-    peers.set(wire.clientId, { id: wire.clientId, kind: wire.kind, lastSeen: Date.now() });
-    if (!existing) notify();
-  });
-  bus.post({ v: 1, scope: "presence", type: "hello", clientId: bus.clientId, kind: bus.kind });
-  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) {
-        bus.post({
-          v: 1,
-          scope: "presence",
-          type: "hello",
-          clientId: bus.clientId,
-          kind: bus.kind
-        });
-      }
-      if (changed) notify();
-    },
-    Math.max(250, Math.floor(Math.min(pruneAfterMs, probeGraceMs) / 2))
-  );
-  let closed = false;
-  return {
-    clientId: bus.clientId,
-    getPeers: () => snapshot,
-    subscribe(fn) {
-      listeners.add(fn);
-      return () => listeners.delete(fn);
-    },
-    close() {
-      if (closed) return;
-      closed = true;
-      clearInterval(prune);
-      unsubscribe();
-      listeners.clear();
-      bus.release();
-    }
-  };
-}
-
 // src/leader-web-locks.ts
 var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
 function createWebLocksLeader(name, options, locks) {
@@ -1005,6 +1233,246 @@ function createHeartbeatLeader(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;
@@ -1012,6 +1480,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);
@@ -1031,7 +1500,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");
@@ -1040,7 +1509,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");
       }
@@ -1061,6 +1530,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") {
@@ -1295,6 +1816,25 @@ 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,
@@ -1302,18 +1842,24 @@ export {
   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,