@use-everywhere/core 0.4.1 → 0.6.0

package/dist/index.js

@@ -7,7 +7,13 @@ 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);
+  for (const fn of set) {
+    try {
+      fn(event);
+    } catch (error) {
+      console.error(`[use-everywhere] a bus observer for "${name}" threw`, error);
+    }
+  }
 }
 function observeBus(name, fn) {
   let set = observers.get(name);
@@ -32,12 +38,41 @@ 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;
+  if (crypto?.getRandomValues) {
+    const buf = crypto.getRandomValues(new Uint8Array(bytes));
+    let out2 = "";
+    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."
+  );
+  let out = "";
+  while (out.length < bytes * 2)
+    out += Math.floor(Math.random() * 256).toString(16).padStart(2, "0");
+  return out;
+}
 function newClientId() {
-  return Math.random().toString(36).slice(2, 8);
+  return randomHex(8);
 }
 function newMsgId() {
-  return Math.random().toString(36).slice(2, 10);
+  return randomHex(16);
 }
 
 // src/transport/broadcast-channel-transport.ts
@@ -117,12 +152,20 @@ function createBus(name, options, onShutdown) {
     options.heartbeatMs ?? 2e3
   );
   const sayBye = () => post({ v: 1, scope: "presence", type: "bye", clientId, kind });
+  const onPageShow = (event) => {
+    if (!event.persisted) return;
+    post({ v: 1, scope: "presence", type: "hello", clientId, kind });
+  };
   const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
-  if (hasWindow) addEventListener("pagehide", sayBye);
+  if (hasWindow) {
+    addEventListener("pagehide", sayBye);
+    addEventListener("pageshow", onPageShow);
+  }
   return {
     name,
     clientId,
     kind,
+    heartbeatMs: options.heartbeatMs ?? 2e3,
     post,
     subscribe(fn) {
       listeners.add(fn);
@@ -132,12 +175,16 @@ function createBus(name, options, onShutdown) {
       refs++;
     },
     release() {
+      if (closed) return;
       refs--;
       if (refs > 0) return;
       sayBye();
       closed = true;
       clearInterval(heartbeat);
-      if (hasWindow) removeEventListener("pagehide", sayBye);
+      if (hasWindow) {
+        removeEventListener("pagehide", sayBye);
+        removeEventListener("pageshow", onPageShow);
+      }
       unsubscribe();
       transport.close();
       listeners.clear();
@@ -159,6 +206,15 @@ function getBus(name, options = {}) {
   if (!bus) {
     bus = createBus(name, options, () => registry.delete(name));
     registry.set(name, bus);
+  } else {
+    if (options.heartbeatMs !== void 0 && options.heartbeatMs !== bus.heartbeatMs) {
+      devWarn(
+        `[use-everywhere] bus "${name}": heartbeatMs ignored \u2014 the first creator fixes bus options`
+      );
+    }
+    if (options.kind !== void 0 && options.kind !== bus.kind) {
+      devWarn(`[use-everywhere] bus "${name}": kind ignored \u2014 the first creator fixes bus options`);
+    }
   }
   bus.acquire();
   return bus;
@@ -175,6 +231,7 @@ function createChannel(name, options = {}) {
     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,
@@ -199,6 +256,8 @@ function createChannel(name, options = {}) {
       return () => set.delete(handler);
     },
     close() {
+      if (closed) return;
+      closed = true;
       unsubscribe();
       handlers.clear();
       bus.release();
@@ -212,25 +271,48 @@ function newer(a, b) {
 }
 
 // src/dev-freeze.ts
-var inDev = false;
+var inDev2 = false;
 try {
-  inDev = process.env.NODE_ENV !== "production";
+  inDev2 = process.env.NODE_ENV !== "production";
 } catch {
 }
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return;
+  if (ArrayBuffer.isView(value)) return;
   Object.freeze(value);
+  if (value instanceof Map) {
+    for (const [k, v] of value) {
+      deepFreeze(k);
+      deepFreeze(v);
+    }
+    return;
+  }
+  if (value instanceof Set) {
+    for (const entry of value) deepFreeze(entry);
+    return;
+  }
   for (const key of Object.keys(value)) {
     deepFreeze(value[key]);
   }
 }
 function freezeShared(value) {
-  if (inDev) deepFreeze(value);
+  if (inDev2) deepFreeze(value);
   return value;
 }
 
 // src/shared-store.ts
+var liveStores = /* @__PURE__ */ new Map();
 function createSharedStore(name, initial, options = {}) {
+  const onSharedBus = !options.transport;
+  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.`
+      );
+    }
+    liveStores.set(name, live + 1);
+  }
   const bus = getBus(name, options);
   const clientId = bus.clientId;
   const accept = options.accept;
@@ -284,18 +366,25 @@ function createSharedStore(name, initial, options = {}) {
   });
   function setKey(key, value) {
     const version = [(versions[key]?.[0] ?? 0) + 1, clientId];
+    try {
+      bus.post({
+        v: 1,
+        scope: "state",
+        type: "patch",
+        key,
+        value,
+        version,
+        clientId,
+        kind: bus.kind
+      });
+    } catch (error) {
+      throw new TypeError(
+        `use-everywhere: the value for key "${key}" cannot cross the wire (structured clone failed); the write was not applied. ${String(error)}`,
+        { cause: error }
+      );
+    }
     versions[key] = version;
     state[key] = freezeShared(value);
-    bus.post({
-      v: 1,
-      scope: "state",
-      type: "patch",
-      key,
-      value,
-      version,
-      clientId,
-      kind: bus.kind
-    });
     notify(key, value, { clientId, kind: bus.kind, self: true });
   }
   const proxy = new Proxy(state, {
@@ -358,7 +447,15 @@ function createSharedStore(name, initial, options = {}) {
       addEventListener("pagehide", flushPersist);
     }
   }
-  bus.post({ v: 1, scope: "state", type: "hello", clientId, kind: bus.kind });
+  const sayHello = () => bus.post({ v: 1, scope: "state", type: "hello", clientId, kind: bus.kind });
+  const onPageShow = (event) => {
+    if (!event.persisted) return;
+    sayHello();
+  };
+  const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
+  if (hasWindow) addEventListener("pageshow", onPageShow);
+  sayHello();
+  let storeClosed = false;
   return {
     clientId,
     state: proxy,
@@ -379,16 +476,27 @@ function createSharedStore(name, initial, options = {}) {
         keyListeners.set(key, set);
       }
       set.add(fn);
-      return () => set.delete(fn);
+      return () => {
+        set.delete(fn);
+        if (set.size === 0) keyListeners.delete(key);
+      };
     },
     registerKey(key, initialValue) {
       if (key in versions) return;
       versions[key] = [0, clientId];
-      state[key] = initialValue;
+      state[key] = freezeShared(initialValue);
       snapshot = Object.freeze({ ...state });
       versionsSnapshot = Object.freeze({ ...versions });
     },
     close() {
+      if (storeClosed) return;
+      storeClosed = true;
+      if (onSharedBus) {
+        const live = (liveStores.get(name) ?? 1) - 1;
+        if (live > 0) liveStores.set(name, live);
+        else liveStores.delete(name);
+      }
+      if (hasWindow) removeEventListener("pageshow", onPageShow);
       if (flushPersist) {
         flushPersist();
         if (typeof document !== "undefined" && typeof removeEventListener === "function") {
@@ -437,6 +545,7 @@ function createPresence(name, options = {}) {
     },
     Math.max(500, Math.floor(pruneAfterMs / 2))
   );
+  let closed = false;
   return {
     clientId: bus.clientId,
     getPeers: () => snapshot,
@@ -445,6 +554,8 @@ function createPresence(name, options = {}) {
       return () => listeners.delete(fn);
     },
     close() {
+      if (closed) return;
+      closed = true;
       clearInterval(prune);
       unsubscribe();
       listeners.clear();
@@ -533,10 +644,19 @@ function createLeader(name, options = {}) {
     bus.post({ v: 1, scope: "leader", type: "resign", term: resigning, clientId, kind: bus.kind });
     armLease(leaseMs);
   }
+  const sayHello = () => bus.post({ v: 1, scope: "leader", type: "hello", clientId, kind: bus.kind });
   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 });
+  const onPageShow = (event) => {
+    if (!event.persisted) return;
+    sayHello();
+    armLease(heartbeatMs);
+  };
+  if (hasWindow) {
+    addEventListener("pagehide", onPageHide);
+    addEventListener("pageshow", onPageShow);
+  }
+  sayHello();
   armLease(heartbeatMs);
   return {
     clientId,
@@ -556,11 +676,15 @@ function createLeader(name, options = {}) {
       if (leaderId === null) armLease(0);
     },
     close() {
+      if (closed) return;
       closed = true;
       resign();
       clearInterval(beat);
       clearTimeout(lease);
-      if (hasWindow) removeEventListener("pagehide", onPageHide);
+      if (hasWindow) {
+        removeEventListener("pagehide", onPageHide);
+        removeEventListener("pageshow", onPageShow);
+      }
       unsubscribe();
       listeners.clear();
       bus.release();
@@ -574,44 +698,54 @@ function isPersisted(value) {
   const candidate = value;
   return candidate.v === 1 && typeof candidate.state === "object" && typeof candidate.versions === "object";
 }
-function webStorageAdapter(storage, key) {
-  const resolve = () => {
+function webStorageAdapter(storage, key, options = {}) {
+  const report = (error, operation) => {
     try {
-      return typeof storage === "function" ? storage() : storage;
+      options.onError?.(error, operation);
     } catch {
+    }
+  };
+  const resolve = (operation) => {
+    try {
+      return typeof storage === "function" ? storage() : storage;
+    } catch (error) {
+      report(error, operation);
       return void 0;
     }
   };
   return {
     read() {
       try {
-        const raw = resolve()?.getItem(key);
+        const raw = resolve("read")?.getItem(key);
         if (!raw) return void 0;
         const parsed = JSON.parse(raw);
         return isPersisted(parsed) ? parsed : void 0;
-      } catch {
+      } catch (error) {
+        report(error, "read");
         return void 0;
       }
     },
     write(snapshot) {
       try {
-        resolve()?.setItem(key, JSON.stringify(snapshot));
-      } catch {
+        resolve("write")?.setItem(key, JSON.stringify(snapshot));
+      } catch (error) {
+        report(error, "write");
       }
     },
     remove() {
       try {
-        resolve()?.removeItem(key);
-      } catch {
+        resolve("remove")?.removeItem(key);
+      } catch (error) {
+        report(error, "remove");
       }
     }
   };
 }
-function localStorageAdapter(key) {
-  return webStorageAdapter(() => globalThis.localStorage, key);
+function localStorageAdapter(key, options) {
+  return webStorageAdapter(() => globalThis.localStorage, key, options);
 }
-function sessionStorageAdapter(key) {
-  return webStorageAdapter(() => globalThis.sessionStorage, key);
+function sessionStorageAdapter(key, options) {
+  return webStorageAdapter(() => globalThis.sessionStorage, key, options);
 }
 
 // src/errors/handshake-timeout-error.ts
@@ -738,6 +872,7 @@ function openWindow(url, options) {
   }, 400);
   const readyTimer = setTimeout(() => {
     if (isReady || closedSettled) return;
+    localWindow.removeEventListener("message", onMessage);
     const err = new HandshakeTimeoutError();
     rejectReady(err);
     if (!resultSettled) {
@@ -791,6 +926,7 @@ function connectToOpener(options) {
   markHandled(ready);
   const onMessage = (event) => {
     if (!allowAnyOrigin && event.origin !== peerOrigin) return;
+    if (event.source !== opener) return;
     if (!isWindowWire(event.data, cid)) return;
     const wire = event.data;
     if (wire.t === "ready-ack") {
@@ -846,64 +982,11 @@ function connectToOpener(options) {
     }
   };
 }
-
-// src/transport/memory-transport.ts
-var MemoryTransport = class {
-  constructor(hub) {
-    this.hub = hub;
-    this.listeners = /* @__PURE__ */ new Set();
-    this.closed = false;
-  }
-  post(data) {
-    if (this.closed) return;
-    this.hub.broadcast(this, data);
-  }
-  subscribe(listener) {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-  close() {
-    this.closed = true;
-    this.listeners.clear();
-    this.hub.disconnect(this);
-  }
-  /** @internal */
-  deliver(data) {
-    if (this.closed) return;
-    for (const listener of this.listeners) listener(data);
-  }
-};
-
-// src/transport/memory-hub.ts
-var MemoryHub = class {
-  constructor() {
-    this.transports = /* @__PURE__ */ new Set();
-  }
-  connect() {
-    const transport = new MemoryTransport(this);
-    this.transports.add(transport);
-    return transport;
-  }
-  /** @internal */
-  broadcast(from, data) {
-    for (const transport of this.transports) {
-      if (transport !== from) {
-        queueMicrotask(() => transport.deliver(data));
-      }
-    }
-  }
-  /** @internal */
-  disconnect(transport) {
-    this.transports.delete(transport);
-  }
-};
 export {
   BroadcastChannelTransport,
   CID_PARAM,
   DEFAULT_NAME,
   HandshakeTimeoutError,
-  MemoryHub,
-  MemoryTransport,
   NoopTransport,
   WindowClosedError,
   connectToOpener,

package/dist/testing.cjs

@@ -0,0 +1,84 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing.ts
+var testing_exports = {};
+__export(testing_exports, {
+  MemoryHub: () => MemoryHub,
+  MemoryTransport: () => MemoryTransport
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/transport/memory-transport.ts
+var MemoryTransport = class {
+  constructor(hub) {
+    this.hub = hub;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.closed = false;
+  }
+  post(data) {
+    if (this.closed) return;
+    this.hub.broadcast(this, data);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    this.closed = true;
+    this.listeners.clear();
+    this.hub.disconnect(this);
+  }
+  /** @internal */
+  deliver(data) {
+    if (this.closed) return;
+    for (const listener of this.listeners) listener(data);
+  }
+};
+
+// src/transport/memory-hub.ts
+var MemoryHub = class {
+  constructor() {
+    this.transports = /* @__PURE__ */ new Set();
+  }
+  connect() {
+    const transport = new MemoryTransport(this);
+    this.transports.add(transport);
+    return transport;
+  }
+  /** @internal */
+  broadcast(from, data) {
+    structuredClone(data);
+    for (const transport of this.transports) {
+      if (transport !== from) {
+        const copy = structuredClone(data);
+        queueMicrotask(() => transport.deliver(copy));
+      }
+    }
+  }
+  /** @internal */
+  disconnect(transport) {
+    this.transports.delete(transport);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryHub,
+  MemoryTransport
+});

package/dist/testing.d.cts

@@ -0,0 +1,30 @@
+import { T as Transport } from './transport.types-tQ1cu6Xm.cjs';
+
+/** One simulated client on a MemoryHub. Create via hub.connect(). */
+declare class MemoryTransport implements Transport {
+    private hub;
+    private listeners;
+    private closed;
+    constructor(hub: MemoryHub);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+    /** @internal */
+    deliver(data: unknown): void;
+}
+
+/**
+ * In-memory hub for tests: N transports attached to one hub, each post is
+ * delivered to every *other* transport on a microtask (mirrors BroadcastChannel's
+ * async, no-self-echo delivery).
+ */
+declare class MemoryHub {
+    private transports;
+    connect(): MemoryTransport;
+    /** @internal */
+    broadcast(from: MemoryTransport, data: unknown): void;
+    /** @internal */
+    disconnect(transport: MemoryTransport): void;
+}
+
+export { MemoryHub, MemoryTransport };

package/dist/testing.d.ts

@@ -0,0 +1,30 @@
+import { T as Transport } from './transport.types-tQ1cu6Xm.js';
+
+/** One simulated client on a MemoryHub. Create via hub.connect(). */
+declare class MemoryTransport implements Transport {
+    private hub;
+    private listeners;
+    private closed;
+    constructor(hub: MemoryHub);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+    /** @internal */
+    deliver(data: unknown): void;
+}
+
+/**
+ * In-memory hub for tests: N transports attached to one hub, each post is
+ * delivered to every *other* transport on a microtask (mirrors BroadcastChannel's
+ * async, no-self-echo delivery).
+ */
+declare class MemoryHub {
+    private transports;
+    connect(): MemoryTransport;
+    /** @internal */
+    broadcast(from: MemoryTransport, data: unknown): void;
+    /** @internal */
+    disconnect(transport: MemoryTransport): void;
+}
+
+export { MemoryHub, MemoryTransport };

package/dist/testing.js

@@ -0,0 +1,56 @@
+// src/transport/memory-transport.ts
+var MemoryTransport = class {
+  constructor(hub) {
+    this.hub = hub;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.closed = false;
+  }
+  post(data) {
+    if (this.closed) return;
+    this.hub.broadcast(this, data);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    this.closed = true;
+    this.listeners.clear();
+    this.hub.disconnect(this);
+  }
+  /** @internal */
+  deliver(data) {
+    if (this.closed) return;
+    for (const listener of this.listeners) listener(data);
+  }
+};
+
+// src/transport/memory-hub.ts
+var MemoryHub = class {
+  constructor() {
+    this.transports = /* @__PURE__ */ new Set();
+  }
+  connect() {
+    const transport = new MemoryTransport(this);
+    this.transports.add(transport);
+    return transport;
+  }
+  /** @internal */
+  broadcast(from, data) {
+    structuredClone(data);
+    for (const transport of this.transports) {
+      if (transport !== from) {
+        const copy = structuredClone(data);
+        queueMicrotask(() => transport.deliver(copy));
+      }
+    }
+  }
+  /** @internal */
+  disconnect(transport) {
+    this.transports.delete(transport);
+  }
+};
+export {
+  MemoryHub,
+  MemoryTransport
+};

package/dist/transport.types-tQ1cu6Xm.d.cts

@@ -0,0 +1,12 @@
+/**
+ * Minimal message bus. Implementations: BroadcastChannelTransport (same-origin),
+ * NoopTransport (SSR / local-only), MemoryTransport (tests). A transport never
+ * echoes a client's own posts back to it.
+ */
+interface Transport {
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+
+export type { Transport as T };

package/dist/transport.types-tQ1cu6Xm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal message bus. Implementations: BroadcastChannelTransport (same-origin),
+ * NoopTransport (SSR / local-only), MemoryTransport (tests). A transport never
+ * echoes a client's own posts back to it.
+ */
+interface Transport {
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+
+export type { Transport as T };