@use-everywhere/core 0.10.1 → 0.11.1

package/dist/shared-worker.cjs

@@ -20,34 +20,80 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/shared-worker.ts
 var shared_worker_exports = {};
 __export(shared_worker_exports, {
+  relay: () => relay,
   startRelay: () => startRelay
 });
 module.exports = __toCommonJS(shared_worker_exports);
 function startRelay(scope) {
   const ports = /* @__PURE__ */ new Set();
+  const local = /* @__PURE__ */ new Set();
+  const fanOut = (from, data) => {
+    const dead = [];
+    for (const peer of ports) {
+      if (peer === from) continue;
+      try {
+        peer.postMessage(data);
+      } catch {
+        dead.push(peer);
+      }
+    }
+    for (const corpse of dead) {
+      ports.delete(corpse);
+      local.delete(corpse);
+    }
+  };
   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.addEventListener("message", (message) => fanOut(port, message.data));
     port.start?.();
   };
+  return {
+    broadcast: (data) => fanOut(null, data),
+    get size() {
+      return ports.size - local.size;
+    },
+    connect() {
+      const listeners = /* @__PURE__ */ new Set();
+      let closed = false;
+      const seat = {
+        // Asynchronous on purpose. `fanOut` runs inside a port's message
+        // listener, and delivering synchronously from there produces the
+        // re-entrancy a real MessagePort never could. Nothing is cloned: every
+        // value reaching this seat already crossed a port boundary and was
+        // structured-cloned there, so there is no live reference to leak.
+        postMessage: (data) => {
+          queueMicrotask(() => {
+            for (const listener of listeners) listener(data);
+          });
+        }
+      };
+      ports.add(seat);
+      local.add(seat);
+      return {
+        kind: "shared-worker",
+        post: (data) => {
+          if (!closed) fanOut(seat, data);
+        },
+        subscribe: (listener) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        close: () => {
+          if (closed) return;
+          closed = true;
+          listeners.clear();
+          ports.delete(seat);
+          local.delete(seat);
+        }
+      };
+    }
+  };
 }
-if (typeof self !== "undefined" && "onconnect" in self) {
-  startRelay(self);
-}
+var relay = typeof self !== "undefined" && "onconnect" in self ? startRelay(self) : void 0;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  relay,
   startRelay
 });

package/dist/shared-worker.d.cts

@@ -1,3 +1,5 @@
+import { T as Transport } from './transport.types-CV1WZOhy.cjs';
+
 /**
  * The relay that runs *inside* a SharedWorker. Host a one-line module and point
  * `SharedWorkerTransport` at it:
@@ -12,10 +14,25 @@
  * 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`.
+ * For a worker that also does other work — one that owns the WebSocket, say —
+ * import {@link relay} and join the bus through it:
+ *
+ * ```js
+ * // socket-worker.js
+ * import { relay } from '@use-everywhere/core/shared-worker';
+ * import { createSharedStore } from '@use-everywhere/core';
+ *
+ * const store = createSharedStore('feed', { tick: null }, { transport: () => relay.connect() });
+ * new WebSocket('wss://example.com/feed').onmessage = (e) => store.set('tick', JSON.parse(e.data));
+ * ```
+ *
+ * `startRelay` is exported for tests, which cannot install a global `onconnect`,
+ * and for a scope this module cannot detect. Prefer {@link relay} inside a real
+ * worker: calling `startRelay(self)` there installs a *second* relay over the
+ * one this module already installed, and the first one's ports are then held by
+ * a handler nothing will ever call again.
  */
+
 interface RelayPort {
     postMessage(data: unknown): void;
     start?: () => void;
@@ -28,10 +45,36 @@ interface RelayScope {
         ports: readonly RelayPort[];
     }) => void) | null;
 }
+/** A running relay: the ports it holds, and the worker's own seat on the bus. */
+interface Relay {
+    /**
+     * Join the relay from inside the worker, as one more peer.
+     *
+     * Returns a `Transport`, so worker-side code uses `createSharedStore` and the
+     * rest of the library exactly as a tab does. That is the point: the wire
+     * format stays the engines' business, and a worker that wants to publish
+     * never has to hand-assemble an envelope the protocol might redefine.
+     */
+    connect(): Transport;
+    /**
+     * Fan raw data out to every connected port.
+     *
+     * The escape hatch, for a worker speaking some protocol of its own. Anything
+     * the library's engines will read should go through {@link connect} instead —
+     * this bypasses them entirely.
+     */
+    broadcast(data: unknown): void;
+    /**
+     * How many ports are attached. A live count of the contexts that opened this
+     * worker, which is what you want in order to idle a socket while nobody is
+     * looking. `connect()` seats are not counted: the worker is not its own tab.
+     */
+    readonly size: number;
+}
 /**
- * Fan every message out to the other connected ports.
+ * Fan every message out to the other connected peers.
  *
- * Two properties the buses above this depend on:
+ * Three 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
@@ -40,7 +83,17 @@ interface RelayScope {
  *    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.
+ * 3. **The worker is a peer, not a special case.** A local seat from
+ *    {@link Relay.connect} is held in the same set as the ports, so both rules
+ *    above apply to it without a second code path to keep in agreement.
+ */
+declare function startRelay(scope: RelayScope): Relay;
+/**
+ * The relay this module installed on import — present only when the module is
+ * running in a SharedWorker, and `undefined` anywhere else, so that importing
+ * it from a bundler tracing entry points, a test runner, or a server render is
+ * inert rather than a `ReferenceError`.
  */
-declare function startRelay(scope: RelayScope): void;
+declare const relay: Relay | undefined;
 
-export { type RelayPort, type RelayScope, startRelay };
+export { type Relay, type RelayPort, type RelayScope, relay, startRelay };

package/dist/shared-worker.d.ts

@@ -1,3 +1,5 @@
+import { T as Transport } from './transport.types-CV1WZOhy.js';
+
 /**
  * The relay that runs *inside* a SharedWorker. Host a one-line module and point
  * `SharedWorkerTransport` at it:
@@ -12,10 +14,25 @@
  * 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`.
+ * For a worker that also does other work — one that owns the WebSocket, say —
+ * import {@link relay} and join the bus through it:
+ *
+ * ```js
+ * // socket-worker.js
+ * import { relay } from '@use-everywhere/core/shared-worker';
+ * import { createSharedStore } from '@use-everywhere/core';
+ *
+ * const store = createSharedStore('feed', { tick: null }, { transport: () => relay.connect() });
+ * new WebSocket('wss://example.com/feed').onmessage = (e) => store.set('tick', JSON.parse(e.data));
+ * ```
+ *
+ * `startRelay` is exported for tests, which cannot install a global `onconnect`,
+ * and for a scope this module cannot detect. Prefer {@link relay} inside a real
+ * worker: calling `startRelay(self)` there installs a *second* relay over the
+ * one this module already installed, and the first one's ports are then held by
+ * a handler nothing will ever call again.
  */
+
 interface RelayPort {
     postMessage(data: unknown): void;
     start?: () => void;
@@ -28,10 +45,36 @@ interface RelayScope {
         ports: readonly RelayPort[];
     }) => void) | null;
 }
+/** A running relay: the ports it holds, and the worker's own seat on the bus. */
+interface Relay {
+    /**
+     * Join the relay from inside the worker, as one more peer.
+     *
+     * Returns a `Transport`, so worker-side code uses `createSharedStore` and the
+     * rest of the library exactly as a tab does. That is the point: the wire
+     * format stays the engines' business, and a worker that wants to publish
+     * never has to hand-assemble an envelope the protocol might redefine.
+     */
+    connect(): Transport;
+    /**
+     * Fan raw data out to every connected port.
+     *
+     * The escape hatch, for a worker speaking some protocol of its own. Anything
+     * the library's engines will read should go through {@link connect} instead —
+     * this bypasses them entirely.
+     */
+    broadcast(data: unknown): void;
+    /**
+     * How many ports are attached. A live count of the contexts that opened this
+     * worker, which is what you want in order to idle a socket while nobody is
+     * looking. `connect()` seats are not counted: the worker is not its own tab.
+     */
+    readonly size: number;
+}
 /**
- * Fan every message out to the other connected ports.
+ * Fan every message out to the other connected peers.
  *
- * Two properties the buses above this depend on:
+ * Three 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
@@ -40,7 +83,17 @@ interface RelayScope {
  *    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.
+ * 3. **The worker is a peer, not a special case.** A local seat from
+ *    {@link Relay.connect} is held in the same set as the ports, so both rules
+ *    above apply to it without a second code path to keep in agreement.
+ */
+declare function startRelay(scope: RelayScope): Relay;
+/**
+ * The relay this module installed on import — present only when the module is
+ * running in a SharedWorker, and `undefined` anywhere else, so that importing
+ * it from a bundler tracing entry points, a test runner, or a server render is
+ * inert rather than a `ReferenceError`.
  */
-declare function startRelay(scope: RelayScope): void;
+declare const relay: Relay | undefined;
 
-export { type RelayPort, type RelayScope, startRelay };
+export { type Relay, type RelayPort, type RelayScope, relay, startRelay };

package/dist/shared-worker.js

@@ -1,28 +1,73 @@
 // src/shared-worker.ts
 function startRelay(scope) {
   const ports = /* @__PURE__ */ new Set();
+  const local = /* @__PURE__ */ new Set();
+  const fanOut = (from, data) => {
+    const dead = [];
+    for (const peer of ports) {
+      if (peer === from) continue;
+      try {
+        peer.postMessage(data);
+      } catch {
+        dead.push(peer);
+      }
+    }
+    for (const corpse of dead) {
+      ports.delete(corpse);
+      local.delete(corpse);
+    }
+  };
   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.addEventListener("message", (message) => fanOut(port, message.data));
     port.start?.();
   };
+  return {
+    broadcast: (data) => fanOut(null, data),
+    get size() {
+      return ports.size - local.size;
+    },
+    connect() {
+      const listeners = /* @__PURE__ */ new Set();
+      let closed = false;
+      const seat = {
+        // Asynchronous on purpose. `fanOut` runs inside a port's message
+        // listener, and delivering synchronously from there produces the
+        // re-entrancy a real MessagePort never could. Nothing is cloned: every
+        // value reaching this seat already crossed a port boundary and was
+        // structured-cloned there, so there is no live reference to leak.
+        postMessage: (data) => {
+          queueMicrotask(() => {
+            for (const listener of listeners) listener(data);
+          });
+        }
+      };
+      ports.add(seat);
+      local.add(seat);
+      return {
+        kind: "shared-worker",
+        post: (data) => {
+          if (!closed) fanOut(seat, data);
+        },
+        subscribe: (listener) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        close: () => {
+          if (closed) return;
+          closed = true;
+          listeners.clear();
+          ports.delete(seat);
+          local.delete(seat);
+        }
+      };
+    }
+  };
 }
-if (typeof self !== "undefined" && "onconnect" in self) {
-  startRelay(self);
-}
+var relay = typeof self !== "undefined" && "onconnect" in self ? startRelay(self) : void 0;
 export {
+  relay,
   startRelay
 };

package/llms.txt

@@ -0,0 +1,84 @@
+# @use-everywhere/core
+
+> The framework-free engine behind `use-everywhere`: shared state, typed
+> messages, presence, leader election and a cross-origin window channel, for any
+> tab, window or worker on an origin. No React, no framework, no server. If you
+> are using React, install `use-everywhere` instead — it re-exports all of this
+> plus the hooks, so importing both is redundant. Ships ESM and CommonJS.
+
+## Install
+
+    npm install @use-everywhere/core
+
+No runtime dependencies and no peers. Use this package directly only when you
+are NOT using React.
+
+## Minimal working example
+
+```ts
+import { createSharedStore } from '@use-everywhere/core';
+
+const store = createSharedStore({ name: 'settings' }, { theme: 'light' });
+
+// Fires whenever any tab on the origin writes.
+store.subscribe(() => console.log(store.get()));
+
+store.set({ theme: 'dark' });
+```
+
+## API
+
+| Export | Kind | What it does |
+| --- | --- | --- |
+| `createSharedStore` | factory | Shared state, last-writer-wins per key |
+| `createSharedReducer` | factory | The same, dispatch-shaped |
+| `createChannel` | factory | Typed fire-and-forget pub/sub between tabs |
+| `createPresence` | factory | Who else is open, with heartbeat and pruning |
+| `createLeader` | factory | Lease-and-claim election with a sticky incumbent |
+| `createNamespace` | factory | Prefix every bus name, for micro-frontends |
+| `openWindow` | function | Open a cross-origin window on a typed 1:1 channel |
+| `connectToOpener` | function | The other half, called by the opened page |
+| `newer` | function | The version clock every conflict is settled by |
+| `observeBus` | function | Every wire crossing a bus, in both directions |
+| `enableDebug` | function | Turn on development diagnostics |
+| `getBusNames` | function | Which buses exist right now |
+| `getTransportKind` | function | Which transport a bus resolved to |
+| `getWireSkew` | function | Version skew between this tab and its peers |
+| `BroadcastChannelTransport` | class | The same-origin default |
+| `StorageTransport` | class | `storage`-event fallback |
+| `SharedWorkerTransport` | class | One worker instead of N tabs |
+| `NoopTransport` | class | Does nothing; for SSR and tests |
+| `WindowClosedError` | class | The opened window went away mid-flow |
+| `HandshakeTimeoutError` | class | The cross-origin handshake never completed |
+| `webStorageAdapter` | function | Persist to `localStorage` / `sessionStorage` |
+| `indexedDbAdapter` | function | Persist to IndexedDB |
+| `jsonSerializer` | function | The default serializer for the text paths |
+
+## Gotchas
+
+- **Shared state never crosses origins.** That is deliberate — two origins are
+  two trust domains. Use `openWindow` / `connectToOpener` for that, which is
+  explicit, typed, per-message and validated by origin, envelope brand,
+  per-connection nonce and source window.
+- **The wire is structured clone.** Functions, class instances, DOM nodes and
+  symbols do not survive. Dates, Maps, Sets and typed arrays do. The text
+  transports (`StorageTransport`, persistence) go through a serializer instead,
+  which is narrower still — see the serialization guide.
+- **Last-writer-wins, per key**, with a `[counter, clientId]` tie-break. It is a
+  deterministic resolution, not a merge; use `createSharedReducer` when the
+  operations need to compose.
+- **The name is the identity.** A bus name is global to the origin. Two
+  independently-written features picking `'store'` are one store. Use
+  `createNamespace` to keep them apart.
+- **Call the factories once, at module scope.** They register singletons keyed by
+  name; calling one per render or per request builds a new bus each time.
+
+## Docs
+
+- Full documentation: https://rxova.org/packages/use-everywhere/
+- Agent-facing index: https://rxova.org/packages/use-everywhere/llms.txt
+- Every page as raw markdown: add `.md` to any docs URL
+- Core section: https://rxova.org/packages/use-everywhere/core/overview.md
+- Generated reference: https://rxova.org/packages/use-everywhere/api/core/readme.md
+- Error codes: https://rxova.org/packages/use-everywhere/errors.md
+- Source: https://github.com/rxova/use-everywhere

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -9,15 +9,23 @@
     "url": "git+https://github.com/rxova/use-everywhere.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/rxova/use-everywhere#readme",
+  "homepage": "https://rxova.org/packages/use-everywhere/core/overview/",
   "bugs": "https://github.com/rxova/use-everywhere/issues",
   "keywords": [
     "broadcastchannel",
+    "broadcast-channel",
     "cross-tab",
+    "multi-tab",
+    "tabs",
+    "tab-sync",
+    "sync",
     "shared-state",
+    "state-management",
     "postmessage",
     "cross-origin",
+    "cross-window",
     "presence",
+    "leader-election",
     "pubsub"
   ],
   "publishConfig": {
@@ -64,7 +72,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "size-limit": [
     {
@@ -143,7 +152,7 @@
       "name": "SharedWorker relay (shared-worker subpath)",
       "path": "dist/shared-worker.js",
       "import": "*",
-      "limit": "280 B"
+      "limit": "410 B"
     },
     {
       "name": "MemoryHub (testing subpath)",