@use-everywhere/core 0.8.0 → 0.10.0

package/README.md

@@ -161,7 +161,7 @@ tabB.getSnapshot().n; // 1
 - SSR-safe: without `BroadcastChannel`, engines fall back to a local no-op
   transport.
 
-📖 **[Documentation](https://rxova.github.io/use-everywhere/)** — mental
+📖 **[Documentation](https://rxova.org/packages/use-everywhere/)** — mental
 model, how sync works, security model, recipes, and generated API reference.
 Source and demo app (with a real cross-origin payment flow):
 [github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(src_exports, {
   DEFAULT_NAME: () => DEFAULT_NAME,
   HandshakeTimeoutError: () => HandshakeTimeoutError,
   NoopTransport: () => NoopTransport,
+  SharedWorkerTransport: () => SharedWorkerTransport,
   StorageTransport: () => StorageTransport,
   WIRE_VERSION: () => WIRE_VERSION,
   WindowClosedError: () => WindowClosedError,
@@ -42,6 +43,7 @@ __export(src_exports, {
   getWireSkew: () => getWireSkew,
   indexedDbAdapter: () => indexedDbAdapter,
   isBroadcastChannelAvailable: () => isBroadcastChannelAvailable,
+  isSharedWorkerAvailable: () => isSharedWorkerAvailable,
   isStorageEventAvailable: () => isStorageEventAvailable,
   jsonSerializer: () => jsonSerializer,
   localStorageAdapter: () => localStorageAdapter,
@@ -56,6 +58,26 @@ module.exports = __toCommonJS(src_exports);
 // 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) {
@@ -66,7 +88,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);
     }
   }
 }
@@ -93,19 +115,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;
@@ -117,7 +126,8 @@ function randomHex(bytes) {
   }
   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."
+      "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 = "";
@@ -145,7 +155,8 @@ function announce() {
   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.`
+        "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.`
       );
     }
   }
@@ -218,7 +229,7 @@ var jsonSerializer = {
       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/`
+          `use-everywhere: ${key ? `"${key}" is ` : ""}${type}, which JSON cannot round-trip. https://rxova.org/packages/use-everywhere/guides/serialization/`
         );
       }
       return forJson;
@@ -235,7 +246,10 @@ var StorageTransport = class {
     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;
@@ -293,14 +307,16 @@ function defaultTransport(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."
+        "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 and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
+      "UE1010",
+      "no BroadcastChannel and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
     );
   }
   return new NoopTransport();
@@ -330,7 +346,8 @@ function recordSkew(name, version) {
   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/`
+      "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/`
     );
   }
 }
@@ -462,15 +479,14 @@ function getBus(name, options = {}) {
     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`
+          "UE1004",
+          `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`
-        );
+        devWarn("UE1005", `bus "${name}": kind ignored \u2014 the first creator fixes bus options`);
       }
     }
   }
@@ -499,7 +515,8 @@ function createGate(name, schemas, onInvalid) {
     if (onInvalid) onInvalid(info);
     else if (process.env.NODE_ENV !== "production") {
       devWarn(
-        `[use-everywhere] ${name}/${key}: ${direction}bound payload rejected by its schema \u2014 ${result.issues.join("; ")}. https://rxova.org/guides/validating-payloads/`
+        "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;
@@ -678,7 +695,8 @@ function createSharedStore(name, initial, options = {}) {
     if (live > 0) {
       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.`
+          "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.`
         );
       }
     }
@@ -842,7 +860,8 @@ function createSharedStore(name, initial, options = {}) {
       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/`
+          "UE1002",
+          `${name}: persisted schema v${error.found} not restored, expected v${error.expected} (${error.reason}). https://rxova.org/packages/use-everywhere/guides/persistence/`
         );
       }
     };
@@ -1873,6 +1892,42 @@ function createNamespace(namespace) {
     createLeader: (name, options) => createLeader(busName(name), options)
   };
 }
+
+// src/transport/shared-worker-transport.ts
+var SharedWorkerTransport = class {
+  constructor(options) {
+    this.kind = "shared-worker";
+    this.listeners = /* @__PURE__ */ new Set();
+    this.closed = false;
+    const name = options.name ?? "use-everywhere";
+    const factory = options.factory ?? ((url, workerName) => new SharedWorker(url, { name: workerName }));
+    const worker = factory(String(options.url), name);
+    this.port = worker.port;
+    this.onMessage = (event) => {
+      for (const listener of this.listeners) listener(event.data);
+    };
+    this.port.addEventListener("message", this.onMessage);
+    this.port.start?.();
+  }
+  post(data) {
+    if (this.closed) return;
+    this.port.postMessage(data);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.port.removeEventListener("message", this.onMessage);
+    this.port.close();
+  }
+};
+function isSharedWorkerAvailable() {
+  return typeof SharedWorker !== "undefined";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BroadcastChannelTransport,
@@ -1880,6 +1935,7 @@ function createNamespace(namespace) {
   DEFAULT_NAME,
   HandshakeTimeoutError,
   NoopTransport,
+  SharedWorkerTransport,
   StorageTransport,
   WIRE_VERSION,
   WindowClosedError,
@@ -1897,6 +1953,7 @@ function createNamespace(namespace) {
   getWireSkew,
   indexedDbAdapter,
   isBroadcastChannelAvailable,
+  isSharedWorkerAvailable,
   isStorageEventAvailable,
   jsonSerializer,
   localStorageAdapter,

package/dist/index.d.cts

@@ -349,7 +349,13 @@ interface LeaderOptions extends CommonOptions {
     eligible?: boolean;
     /** How to arbitrate the seat. Default 'auto'. */
     strategy?: LeaderStrategy;
-    /** @internal Test seam for the Web Locks manager. Defaults to navigator.locks. */
+    /**
+     * The Web Locks manager to elect on. Defaults to `navigator.locks`.
+     *
+     * A test seam: `@use-everywhere/test-utils` passes a `FakeLockManager` here
+     * so several simulated tabs can queue on one seat — and so a crashed tab's
+     * lock is reclaimed — in a plain test process.
+     */
     locks?: LockManagerLike;
 }
 /** The slice of the Web Locks API this library uses. */
@@ -1084,6 +1090,98 @@ declare class StorageTransport implements Transport {
     close(): void;
 }
 
+/**
+ * The subset of `SharedWorker` this transport uses. Narrower than the DOM type
+ * on purpose: tests supply a fake, and a fake that has to implement
+ * `EventTarget` to be accepted is a fake nobody writes.
+ */
+interface SharedWorkerLike {
+    readonly port: MessagePortLike;
+}
+interface MessagePortLike {
+    postMessage(data: unknown): void;
+    start?: () => void;
+    close(): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+interface SharedWorkerTransportOptions {
+    /**
+     * The relay script. A `URL` rather than a string in the common case, because
+     * `new URL('./relay.js', import.meta.url)` is what survives a bundler.
+     *
+     * It must be a *stable* URL, and that is the whole reason this option exists
+     * rather than the library inlining a worker from a Blob the way it could for
+     * a dedicated one: a SharedWorker's identity is its script URL plus its name,
+     * and every tab that builds its own Blob URL gets its own worker. Inlining
+     * would produce N private workers that share nothing — the failure this
+     * transport exists to prevent, wearing the costume of a fix.
+     */
+    url: string | URL;
+    /**
+     * Distinguishes workers loaded from the same script. Defaults to the bus
+     * name, which is what makes two buses on one origin independent.
+     */
+    name?: string;
+    /**
+     * Constructs the worker. Only tests should pass this; the default is
+     * `globalThis.SharedWorker`.
+     */
+    factory?: (url: string, name: string) => SharedWorkerLike;
+}
+/**
+ * Cross-tab delivery through one SharedWorker per origin.
+ *
+ * BroadcastChannel is the better default for pure fan-out and stays the
+ * default. This transport buys something else: a single place that is not a
+ * tab. The relay outlives any individual tab, so the thing every "the leader
+ * owns the socket" design actually wants — one connection, held somewhere no
+ * user can close mid-flight — becomes possible without electing a leader at
+ * all.
+ *
+ * What it does not buy: durability. The worker is torn down when the last port
+ * closes, exactly like a BroadcastChannel with no listeners. State still lives
+ * in the tabs; this moves the *wire*, not the source of truth.
+ *
+ * The relay script is three lines and ships with the library:
+ *
+ * ```js
+ * // sw-relay.js — your app hosts this file
+ * import 'use-everywhere/shared-worker';
+ * ```
+ *
+ * ```ts
+ * createSharedStore('cart', {
+ *   transport: new SharedWorkerTransport({
+ *     url: new URL('./sw-relay.js', import.meta.url),
+ *   }),
+ * });
+ * ```
+ */
+declare class SharedWorkerTransport implements Transport {
+    readonly kind: TransportKind;
+    private port;
+    private listeners;
+    private onMessage;
+    private closed;
+    constructor(options: SharedWorkerTransportOptions);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+/**
+ * Whether this context can construct a SharedWorker at all.
+ *
+ * Notably false in every dedicated worker (they cannot nest a SharedWorker) and
+ * in Chrome on Android. Worth checking before choosing this transport, since
+ * the constructor throws rather than degrading.
+ */
+declare function isSharedWorkerAvailable(): boolean;
+
 declare function isBroadcastChannelAvailable(): boolean;
 /**
  * Can we hear other tabs through the `storage` event?
@@ -1105,4 +1203,4 @@ declare function isStorageEventAvailable(): boolean;
  */
 declare function defaultTransport(name: string): Transport;
 
-export { type AskOptions, BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type ChannelOptions, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type IndexedDbAdapterOptions, type InvalidPayload, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type MessageEventLike, type MessageMap, type MessageMeta, type Namespace, NoopTransport, type OnInvalid, type OnOptions, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type PostOptions, type Presence, type PresenceOptions, type ReplyMap, type RestoreError, type SchemaMap, type SchemaOptions, type Serializer, type SharedReducer, type SharedReducerOptions, type SharedStore, type SharedStoreOptions, type StandardSchemaV1, type StorageLike, StorageTransport, Transport, TransportKind, type Version, WIRE_VERSION, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createNamespace, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };
+export { type AskOptions, BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type ChannelOptions, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type IndexedDbAdapterOptions, type InvalidPayload, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type LockManagerLike, type MessageEventLike, type MessageMap, type MessageMeta, type MessagePortLike, type Namespace, NoopTransport, type OnInvalid, type OnOptions, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type PostOptions, type Presence, type PresenceOptions, type ReplyMap, type RestoreError, type SchemaMap, type SchemaOptions, type Serializer, type SharedReducer, type SharedReducerOptions, type SharedStore, type SharedStoreOptions, type SharedWorkerLike, SharedWorkerTransport, type SharedWorkerTransportOptions, type StandardSchemaV1, type StorageLike, StorageTransport, Transport, TransportKind, type Version, WIRE_VERSION, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createNamespace, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isSharedWorkerAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };

package/dist/index.d.ts

@@ -349,7 +349,13 @@ interface LeaderOptions extends CommonOptions {
     eligible?: boolean;
     /** How to arbitrate the seat. Default 'auto'. */
     strategy?: LeaderStrategy;
-    /** @internal Test seam for the Web Locks manager. Defaults to navigator.locks. */
+    /**
+     * The Web Locks manager to elect on. Defaults to `navigator.locks`.
+     *
+     * A test seam: `@use-everywhere/test-utils` passes a `FakeLockManager` here
+     * so several simulated tabs can queue on one seat — and so a crashed tab's
+     * lock is reclaimed — in a plain test process.
+     */
     locks?: LockManagerLike;
 }
 /** The slice of the Web Locks API this library uses. */
@@ -1084,6 +1090,98 @@ declare class StorageTransport implements Transport {
     close(): void;
 }
 
+/**
+ * The subset of `SharedWorker` this transport uses. Narrower than the DOM type
+ * on purpose: tests supply a fake, and a fake that has to implement
+ * `EventTarget` to be accepted is a fake nobody writes.
+ */
+interface SharedWorkerLike {
+    readonly port: MessagePortLike;
+}
+interface MessagePortLike {
+    postMessage(data: unknown): void;
+    start?: () => void;
+    close(): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+interface SharedWorkerTransportOptions {
+    /**
+     * The relay script. A `URL` rather than a string in the common case, because
+     * `new URL('./relay.js', import.meta.url)` is what survives a bundler.
+     *
+     * It must be a *stable* URL, and that is the whole reason this option exists
+     * rather than the library inlining a worker from a Blob the way it could for
+     * a dedicated one: a SharedWorker's identity is its script URL plus its name,
+     * and every tab that builds its own Blob URL gets its own worker. Inlining
+     * would produce N private workers that share nothing — the failure this
+     * transport exists to prevent, wearing the costume of a fix.
+     */
+    url: string | URL;
+    /**
+     * Distinguishes workers loaded from the same script. Defaults to the bus
+     * name, which is what makes two buses on one origin independent.
+     */
+    name?: string;
+    /**
+     * Constructs the worker. Only tests should pass this; the default is
+     * `globalThis.SharedWorker`.
+     */
+    factory?: (url: string, name: string) => SharedWorkerLike;
+}
+/**
+ * Cross-tab delivery through one SharedWorker per origin.
+ *
+ * BroadcastChannel is the better default for pure fan-out and stays the
+ * default. This transport buys something else: a single place that is not a
+ * tab. The relay outlives any individual tab, so the thing every "the leader
+ * owns the socket" design actually wants — one connection, held somewhere no
+ * user can close mid-flight — becomes possible without electing a leader at
+ * all.
+ *
+ * What it does not buy: durability. The worker is torn down when the last port
+ * closes, exactly like a BroadcastChannel with no listeners. State still lives
+ * in the tabs; this moves the *wire*, not the source of truth.
+ *
+ * The relay script is three lines and ships with the library:
+ *
+ * ```js
+ * // sw-relay.js — your app hosts this file
+ * import 'use-everywhere/shared-worker';
+ * ```
+ *
+ * ```ts
+ * createSharedStore('cart', {
+ *   transport: new SharedWorkerTransport({
+ *     url: new URL('./sw-relay.js', import.meta.url),
+ *   }),
+ * });
+ * ```
+ */
+declare class SharedWorkerTransport implements Transport {
+    readonly kind: TransportKind;
+    private port;
+    private listeners;
+    private onMessage;
+    private closed;
+    constructor(options: SharedWorkerTransportOptions);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+/**
+ * Whether this context can construct a SharedWorker at all.
+ *
+ * Notably false in every dedicated worker (they cannot nest a SharedWorker) and
+ * in Chrome on Android. Worth checking before choosing this transport, since
+ * the constructor throws rather than degrading.
+ */
+declare function isSharedWorkerAvailable(): boolean;
+
 declare function isBroadcastChannelAvailable(): boolean;
 /**
  * Can we hear other tabs through the `storage` event?
@@ -1105,4 +1203,4 @@ declare function isStorageEventAvailable(): boolean;
  */
 declare function defaultTransport(name: string): Transport;
 
-export { type AskOptions, BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type ChannelOptions, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type IndexedDbAdapterOptions, type InvalidPayload, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type MessageEventLike, type MessageMap, type MessageMeta, type Namespace, NoopTransport, type OnInvalid, type OnOptions, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type PostOptions, type Presence, type PresenceOptions, type ReplyMap, type RestoreError, type SchemaMap, type SchemaOptions, type Serializer, type SharedReducer, type SharedReducerOptions, type SharedStore, type SharedStoreOptions, type StandardSchemaV1, type StorageLike, StorageTransport, Transport, TransportKind, type Version, WIRE_VERSION, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createNamespace, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };
+export { type AskOptions, BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type ChannelOptions, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type IndexedDbAdapterOptions, type InvalidPayload, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type LockManagerLike, type MessageEventLike, type MessageMap, type MessageMeta, type MessagePortLike, type Namespace, NoopTransport, type OnInvalid, type OnOptions, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type PostOptions, type Presence, type PresenceOptions, type ReplyMap, type RestoreError, type SchemaMap, type SchemaOptions, type Serializer, type SharedReducer, type SharedReducerOptions, type SharedStore, type SharedStoreOptions, type SharedWorkerLike, SharedWorkerTransport, type SharedWorkerTransportOptions, type StandardSchemaV1, type StorageLike, StorageTransport, Transport, TransportKind, type Version, WIRE_VERSION, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createNamespace, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isSharedWorkerAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };

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;
@@ -62,7 +69,8 @@ function randomHex(bytes) {
   }
   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."
+      "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 = "";
@@ -90,7 +98,8 @@ function announce() {
   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.`
+        "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.`
       );
     }
   }
@@ -163,7 +172,7 @@ var jsonSerializer = {
       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/`
+          `use-everywhere: ${key ? `"${key}" is ` : ""}${type}, which JSON cannot round-trip. https://rxova.org/packages/use-everywhere/guides/serialization/`
         );
       }
       return forJson;
@@ -180,7 +189,10 @@ var StorageTransport = class {
     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;
@@ -238,14 +250,16 @@ function defaultTransport(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."
+        "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 and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
+      "UE1010",
+      "no BroadcastChannel and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
     );
   }
   return new NoopTransport();
@@ -275,7 +289,8 @@ function recordSkew(name, version) {
   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/`
+      "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/`
     );
   }
 }
@@ -407,15 +422,14 @@ function getBus(name, options = {}) {
     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`
+          "UE1004",
+          `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`
-        );
+        devWarn("UE1005", `bus "${name}": kind ignored \u2014 the first creator fixes bus options`);
       }
     }
   }
@@ -444,7 +458,8 @@ function createGate(name, schemas, onInvalid) {
     if (onInvalid) onInvalid(info);
     else if (process.env.NODE_ENV !== "production") {
       devWarn(
-        `[use-everywhere] ${name}/${key}: ${direction}bound payload rejected by its schema \u2014 ${result.issues.join("; ")}. https://rxova.org/guides/validating-payloads/`
+        "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;
@@ -623,7 +638,8 @@ function createSharedStore(name, initial, options = {}) {
     if (live > 0) {
       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.`
+          "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.`
         );
       }
     }
@@ -787,7 +803,8 @@ function createSharedStore(name, initial, options = {}) {
       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/`
+          "UE1002",
+          `${name}: persisted schema v${error.found} not restored, expected v${error.expected} (${error.reason}). https://rxova.org/packages/use-everywhere/guides/persistence/`
         );
       }
     };
@@ -1818,12 +1835,49 @@ function createNamespace(namespace) {
     createLeader: (name, options) => createLeader(busName(name), options)
   };
 }
+
+// src/transport/shared-worker-transport.ts
+var SharedWorkerTransport = class {
+  constructor(options) {
+    this.kind = "shared-worker";
+    this.listeners = /* @__PURE__ */ new Set();
+    this.closed = false;
+    const name = options.name ?? "use-everywhere";
+    const factory = options.factory ?? ((url, workerName) => new SharedWorker(url, { name: workerName }));
+    const worker = factory(String(options.url), name);
+    this.port = worker.port;
+    this.onMessage = (event) => {
+      for (const listener of this.listeners) listener(event.data);
+    };
+    this.port.addEventListener("message", this.onMessage);
+    this.port.start?.();
+  }
+  post(data) {
+    if (this.closed) return;
+    this.port.postMessage(data);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.port.removeEventListener("message", this.onMessage);
+    this.port.close();
+  }
+};
+function isSharedWorkerAvailable() {
+  return typeof SharedWorker !== "undefined";
+}
 export {
   BroadcastChannelTransport,
   CID_PARAM,
   DEFAULT_NAME,
   HandshakeTimeoutError,
   NoopTransport,
+  SharedWorkerTransport,
   StorageTransport,
   WIRE_VERSION,
   WindowClosedError,
@@ -1841,6 +1895,7 @@ export {
   getWireSkew,
   indexedDbAdapter,
   isBroadcastChannelAvailable,
+  isSharedWorkerAvailable,
   isStorageEventAvailable,
   jsonSerializer,
   localStorageAdapter,

package/dist/shared-worker.cjs

@@ -0,0 +1,53 @@
+"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/shared-worker.ts
+var shared_worker_exports = {};
+__export(shared_worker_exports, {
+  startRelay: () => startRelay
+});
+module.exports = __toCommonJS(shared_worker_exports);
+function startRelay(scope) {
+  const ports = /* @__PURE__ */ new Set();
+  scope.onconnect = (event) => {
+    const port = event.ports[0];
+    if (!port) return;
+    ports.add(port);
+    port.addEventListener("message", (message) => {
+      const dead = [];
+      for (const peer of ports) {
+        if (peer === port) continue;
+        try {
+          peer.postMessage(message.data);
+        } catch {
+          dead.push(peer);
+        }
+      }
+      for (const corpse of dead) ports.delete(corpse);
+    });
+    port.start?.();
+  };
+}
+if (typeof self !== "undefined" && "onconnect" in self) {
+  startRelay(self);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  startRelay
+});

package/dist/shared-worker.d.cts

@@ -0,0 +1,46 @@
+/**
+ * The relay that runs *inside* a SharedWorker. Host a one-line module and point
+ * `SharedWorkerTransport` at it:
+ *
+ * ```js
+ * // sw-relay.js
+ * import '@use-everywhere/core/shared-worker';
+ * ```
+ *
+ * Importing this module installs the `connect` handler, which is why the entry
+ * point is a side effect rather than a function you call: a SharedWorker script
+ * has one job, and making the caller remember to invoke it adds a way to get a
+ * worker that accepts connections and forwards nothing.
+ *
+ * `startRelay` is exported anyway, for a worker that also does other work — an
+ * app whose relay owns the WebSocket, say — and for tests, which cannot install
+ * a global `onconnect`.
+ */
+interface RelayPort {
+    postMessage(data: unknown): void;
+    start?: () => void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+interface RelayScope {
+    onconnect: ((event: {
+        ports: readonly RelayPort[];
+    }) => void) | null;
+}
+/**
+ * Fan every message out to the other connected ports.
+ *
+ * Two properties the buses above this depend on:
+ *
+ * 1. **No self-echo.** A sender never receives its own message, matching
+ *    BroadcastChannel exactly. Without it every store would apply its own
+ *    writes twice and every presence roster would count each tab as two.
+ * 2. **A dead port is dropped, not thrown over.** A tab that goes away without
+ *    closing its port leaves an entangled port whose `postMessage` throws; one
+ *    of those must not stop delivery to the tabs still listening, so the send
+ *    loop is individually guarded and the corpse is pruned.
+ */
+declare function startRelay(scope: RelayScope): void;
+
+export { type RelayPort, type RelayScope, startRelay };

package/dist/shared-worker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The relay that runs *inside* a SharedWorker. Host a one-line module and point
+ * `SharedWorkerTransport` at it:
+ *
+ * ```js
+ * // sw-relay.js
+ * import '@use-everywhere/core/shared-worker';
+ * ```
+ *
+ * Importing this module installs the `connect` handler, which is why the entry
+ * point is a side effect rather than a function you call: a SharedWorker script
+ * has one job, and making the caller remember to invoke it adds a way to get a
+ * worker that accepts connections and forwards nothing.
+ *
+ * `startRelay` is exported anyway, for a worker that also does other work — an
+ * app whose relay owns the WebSocket, say — and for tests, which cannot install
+ * a global `onconnect`.
+ */
+interface RelayPort {
+    postMessage(data: unknown): void;
+    start?: () => void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+interface RelayScope {
+    onconnect: ((event: {
+        ports: readonly RelayPort[];
+    }) => void) | null;
+}
+/**
+ * Fan every message out to the other connected ports.
+ *
+ * Two properties the buses above this depend on:
+ *
+ * 1. **No self-echo.** A sender never receives its own message, matching
+ *    BroadcastChannel exactly. Without it every store would apply its own
+ *    writes twice and every presence roster would count each tab as two.
+ * 2. **A dead port is dropped, not thrown over.** A tab that goes away without
+ *    closing its port leaves an entangled port whose `postMessage` throws; one
+ *    of those must not stop delivery to the tabs still listening, so the send
+ *    loop is individually guarded and the corpse is pruned.
+ */
+declare function startRelay(scope: RelayScope): void;
+
+export { type RelayPort, type RelayScope, startRelay };

package/dist/shared-worker.js

@@ -0,0 +1,28 @@
+// src/shared-worker.ts
+function startRelay(scope) {
+  const ports = /* @__PURE__ */ new Set();
+  scope.onconnect = (event) => {
+    const port = event.ports[0];
+    if (!port) return;
+    ports.add(port);
+    port.addEventListener("message", (message) => {
+      const dead = [];
+      for (const peer of ports) {
+        if (peer === port) continue;
+        try {
+          peer.postMessage(message.data);
+        } catch {
+          dead.push(peer);
+        }
+      }
+      for (const corpse of dead) ports.delete(corpse);
+    });
+    port.start?.();
+  };
+}
+if (typeof self !== "undefined" && "onconnect" in self) {
+  startRelay(self);
+}
+export {
+  startRelay
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -24,7 +24,10 @@
     "access": "public"
   },
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/shared-worker.js",
+    "./dist/shared-worker.cjs"
+  ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,6 +42,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./shared-worker": {
+      "import": {
+        "types": "./dist/shared-worker.d.ts",
+        "default": "./dist/shared-worker.js"
+      },
+      "require": {
+        "types": "./dist/shared-worker.d.cts",
+        "default": "./dist/shared-worker.cjs"
+      }
+    },
     "./testing": {
       "import": {
         "types": "./dist/testing.d.ts",
@@ -120,6 +133,18 @@
       "import": "{ indexedDbAdapter }",
       "limit": "447 B"
     },
+    {
+      "name": "SharedWorkerTransport",
+      "path": "dist/index.js",
+      "import": "{ SharedWorkerTransport }",
+      "limit": "380 B"
+    },
+    {
+      "name": "SharedWorker relay (shared-worker subpath)",
+      "path": "dist/shared-worker.js",
+      "import": "*",
+      "limit": "280 B"
+    },
     {
       "name": "MemoryHub (testing subpath)",
       "path": "dist/testing.js",
@@ -145,6 +170,9 @@
   },
   "typesVersions": {
     "*": {
+      "shared-worker": [
+        "./dist/shared-worker.d.ts"
+      ],
       "testing": [
         "./dist/testing.d.ts"
       ]