@use-everywhere/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonatan Kruszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @use-everywhere/core
+
+Framework-agnostic engine for cross-tab shared state, typed events, peer
+presence, and secure cross-origin window channels.
+
+```bash
+npm i @use-everywhere/core
+```
+
+> Using React? Install [`use-everywhere`](https://www.npmjs.com/package/use-everywhere)
+> instead — it provides hooks and re-exports this entire package.
+
+Two transports behind one library:
+
+- **BroadcastChannel** (same-origin): shared state with last-writer-wins version
+  clocks and a late-joiner handshake, typed pub/sub events, and peer presence.
+- **window.opener / postMessage** (cross-origin): a secure 1:1 channel to a
+  window you opened. Every message is validated by origin, envelope brand, a
+  per-connection nonce, and the source window.
+
+## Design notes
+
+- **Shared state never crosses origins.** Two origins are two trust domains;
+  the cross-origin channel is explicit, per-message, and typed.
+- Same-origin state sync uses per-key `[counter, clientId]` clocks
+  (last-writer-wins, deterministic tie-break) and a hello/snapshot handshake so
+  late-joining tabs hydrate instantly.
+- Values must survive structured clone (no functions, DOM nodes, etc.).
+
+Full docs, demo app (including a real cross-origin payment flow), and source:
+[github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+/**
+ * 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;
+}
+
+type MessageMap = Record<string, unknown>;
+type PeerKind = 'tab' | 'worker' | (string & {});
+/** Per-key logical clock: [counter, clientId]. Ties break by clientId. */
+type Version = readonly [counter: number, clientId: string];
+interface Peer {
+    id: string;
+    kind: PeerKind;
+    lastSeen: number;
+}
+interface MessageMeta {
+    clientId: string;
+    kind: PeerKind;
+    self: boolean;
+}
+interface CommonOptions {
+    /** Transport factory, mainly for tests. Defaults to defaultTransport. */
+    transport?: (name: string) => Transport;
+    /** What this client announces itself as. Defaults to 'worker' when there is no document, else 'tab'. */
+    kind?: PeerKind;
+}
+
+interface Channel<M extends MessageMap> {
+    readonly name: string;
+    readonly clientId: string;
+    /** Fire-and-forget to every other tab/window/worker on this origin. Not echoed to self. */
+    post<K extends keyof M & string>(type: K, payload: M[K]): void;
+    on<K extends keyof M & string>(type: K, handler: (payload: M[K], meta: MessageMeta) => void): () => void;
+    close(): void;
+}
+
+/** Typed pub/sub over the same-origin bus. */
+declare function createChannel<M extends MessageMap>(name: string, options?: CommonOptions): Channel<M>;
+
+interface SharedStoreOptions extends CommonOptions {
+    /**
+     * Gatekeeper for incoming remote writes (patches and snapshot merges):
+     * return false to ignore them. Lets callers delimit how much is shared —
+     * e.g. accept only writes from other tabs, not from workers.
+     */
+    accept?: (meta: MessageMeta) => boolean;
+}
+interface SharedStore<S extends Record<string, unknown>> {
+    readonly clientId: string;
+    /** Live proxy for imperative use: `store.state.count++` syncs everywhere. */
+    readonly state: S;
+    /** Immutable snapshot, replaced whenever a change is applied. Safe for useSyncExternalStore. */
+    getSnapshot(): Readonly<S>;
+    set<K extends keyof S & string>(key: K, value: S[K] | ((prev: S[K]) => S[K])): void;
+    subscribe(fn: (key: keyof S & string, value: unknown, meta: MessageMeta) => void): () => void;
+    subscribeKey(key: keyof S & string, fn: () => void): () => void;
+    /**
+     * Register a key lazily at version [0, clientId] — any patch or snapshot a
+     * peer has already made for it wins over the initial value. No-op if the
+     * key already exists.
+     */
+    registerKey<K extends keyof S & string>(key: K, initial: S[K]): void;
+    close(): void;
+}
+
+/**
+ * State synced across every same-origin tab/window/worker: per-key
+ * last-writer-wins version clocks and a hello/snapshot late-joiner handshake.
+ * Create at most one store per name per tab (the React package memoizes).
+ */
+declare function createSharedStore<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions): SharedStore<S>;
+
+interface BusOptions extends CommonOptions {
+    /** Presence heartbeat interval in ms. Default 2000. */
+    heartbeatMs?: number;
+}
+
+interface PresenceOptions extends BusOptions {
+    /** Peers silent for longer than this are dropped. Default 5000ms. */
+    pruneAfterMs?: number;
+}
+interface Presence {
+    readonly clientId: string;
+    /** Stable array snapshot (replaced on change) — safe for useSyncExternalStore. */
+    getPeers(): readonly Peer[];
+    subscribe(fn: () => void): () => void;
+    close(): void;
+}
+
+/**
+ * Tracks the other tabs/windows/workers on this bus. Any message from a peer
+ * counts as a liveness signal (state patches, events, and presence pings all
+ * piggyback); explicit 'bye' or silence past pruneAfterMs removes them.
+ */
+declare function createPresence(name: string, options?: PresenceOptions): Presence;
+
+interface MessageEventLike {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}
+/** The subset of Window we post to (the other side). */
+interface WindowLike {
+    postMessage(data: unknown, targetOrigin: string): void;
+    closed?: boolean;
+    close?(): void;
+}
+/** The subset of Window we listen on (our side). */
+interface WindowEventTarget {
+    addEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+    removeEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+}
+interface OpenWindowOptions {
+    /** Exact origin of the page being opened, e.g. 'https://pay.example.com'. Required. */
+    peerOrigin: string;
+    /** window.open feature string, e.g. 'popup,width=480,height=640'. */
+    features?: string;
+    /** Give up on the ready handshake after this long. Default 15000ms. */
+    readyTimeoutMs?: number;
+    /** Dev only: accept messages from any origin and post with targetOrigin '*'. */
+    allowAnyOrigin?: boolean;
+    /** Test seam. Defaults to window.open. */
+    openFn?: (url: string, target: string, features?: string) => WindowLike | null;
+    /** Test seam. Defaults to the global window. */
+    localWindow?: WindowEventTarget;
+}
+interface OpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
+    /** The opened window, or null if the popup was blocked. */
+    readonly window: WindowLike | null;
+    /** Resolves once the child completes the ready handshake. */
+    readonly ready: Promise<void>;
+    /** Queued until the handshake completes — nothing is dropped while the child loads. */
+    post<K extends keyof Out & string>(type: K, payload: Out[K]): void;
+    on<K extends keyof In & string>(type: K, handler: (payload: In[K]) => void): () => void;
+    /** The child's finish() value. Rejects WindowClosedError / HandshakeTimeoutError. */
+    readonly result: Promise<R>;
+    /** Resolves when the child window is gone (with or without a result). */
+    readonly closed: Promise<void>;
+    /** Close the child window. */
+    close(): void;
+}
+interface ConnectToOpenerOptions {
+    /** Exact origin of the page that opened this window. Required. */
+    peerOrigin: string;
+    /** Give up on the ready handshake after this long. Default 15000ms. */
+    readyTimeoutMs?: number;
+    /** Dev only: accept messages from any origin and post with targetOrigin '*'. */
+    allowAnyOrigin?: boolean;
+    /** Test seam. Defaults to window.opener. */
+    opener?: WindowLike | null;
+    /** Test seam. Defaults to the global window. */
+    localWindow?: WindowEventTarget;
+    /** Test seam. Defaults to the ue-cid query parameter. */
+    cid?: string;
+}
+interface OpenerConnection<In extends MessageMap, Out extends MessageMap, R> {
+    /** Resolves once the opener acknowledges the ready handshake. */
+    readonly ready: Promise<void>;
+    /** Queued until the handshake completes. */
+    post<K extends keyof Out & string>(type: K, payload: Out[K]): void;
+    on<K extends keyof In & string>(type: K, handler: (payload: In[K]) => void): () => void;
+    /** Deliver the terminal result to the opener. Does not close the window. */
+    finish(result: R): void;
+    /** Tell the opener we're going away, then close this window. */
+    close(): void;
+}
+
+declare const CID_PARAM = "ue-cid";
+/**
+ * Open a window (possibly on another origin) and get a typed 1:1 channel to it.
+ * The child must call connectToOpener(). Every received message is validated:
+ * event.origin, envelope brand, per-connection nonce, and event.source.
+ */
+declare function openWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(url: string | URL, options: OpenWindowOptions): OpenedWindow<Out, In, R>;
+/**
+ * Call from the opened (child) window to connect back to its opener.
+ * Throws synchronously when there is no opener or no ue-cid parameter —
+ * i.e. the page was not opened via openWindow().
+ */
+declare function connectToOpener<In extends MessageMap, Out extends MessageMap, R = unknown>(options: ConnectToOpenerOptions): OpenerConnection<In, Out, R>;
+
+/** The opened window closed before delivering a result. */
+declare class WindowClosedError extends Error {
+    constructor(message?: string);
+}
+
+/** The ready/ready-ack handshake never completed. */
+declare class HandshakeTimeoutError extends Error {
+    constructor(message?: string);
+}
+
+/** Is `a` newer than `b`? Last-writer-wins; equal counters break ties by clientId. */
+declare function newer(a: Version, b: Version | undefined): boolean;
+
+/** Same-origin transport over a real BroadcastChannel. */
+declare class BroadcastChannelTransport implements Transport {
+    private bc;
+    private listeners;
+    constructor(name: string);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+
+/**
+ * Silent local transport: nothing leaves this context, nothing arrives.
+ * Used for SSR and for state scoped to a single tab.
+ */
+declare class NoopTransport implements Transport {
+    post(): void;
+    subscribe(): () => void;
+    close(): void;
+}
+
+declare function isBroadcastChannelAvailable(): boolean;
+/** Default factory: real BroadcastChannel when available, otherwise a local no-op. */
+declare function defaultTransport(name: string): Transport;
+
+/** 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 { BroadcastChannelTransport, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, HandshakeTimeoutError, MemoryHub, MemoryTransport, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type Transport, type Version, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createPresence, createSharedStore, defaultTransport, isBroadcastChannelAvailable, newer, openWindow };

package/dist/index.js

@@ -0,0 +1,631 @@
+// src/ids.ts
+function newClientId() {
+  return Math.random().toString(36).slice(2, 8);
+}
+function newMsgId() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+// src/transport/broadcast-channel-transport.ts
+var BroadcastChannelTransport = class {
+  constructor(name) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.bc = new BroadcastChannel(name);
+    this.bc.onmessage = (event) => {
+      for (const listener of this.listeners) listener(event.data);
+    };
+  }
+  post(data) {
+    this.bc.postMessage(data);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    this.listeners.clear();
+    this.bc.close();
+  }
+};
+
+// src/transport/noop-transport.ts
+var NoopTransport = class {
+  post() {
+  }
+  subscribe() {
+    return () => {
+    };
+  }
+  close() {
+  }
+};
+
+// src/transport/default-transport.ts
+function isBroadcastChannelAvailable() {
+  return typeof BroadcastChannel !== "undefined";
+}
+function defaultTransport(name) {
+  return isBroadcastChannelAvailable() ? new BroadcastChannelTransport(name) : new NoopTransport();
+}
+
+// src/bus.ts
+function isBusWire(data) {
+  return typeof data === "object" && data !== null && data.v === 1;
+}
+function defaultKind() {
+  return typeof document === "undefined" ? "worker" : "tab";
+}
+var registry = /* @__PURE__ */ new Map();
+function createBus(name, options, onShutdown) {
+  const transport = (options.transport ?? defaultTransport)(name);
+  const clientId = newClientId();
+  const kind = options.kind ?? defaultKind();
+  const listeners = /* @__PURE__ */ new Set();
+  let refs = 0;
+  let closed = false;
+  const post = (wire) => {
+    if (!closed) transport.post(wire);
+  };
+  const unsubscribe = transport.subscribe((data) => {
+    if (!isBusWire(data)) return;
+    if (data.clientId === clientId) return;
+    if (data.scope === "presence" && data.type === "hello") {
+      post({ v: 1, scope: "presence", type: "ping", clientId, kind });
+    }
+    for (const fn of listeners) fn(data);
+  });
+  post({ v: 1, scope: "presence", type: "hello", clientId, kind });
+  const heartbeat = setInterval(
+    () => post({ v: 1, scope: "presence", type: "ping", clientId, kind }),
+    options.heartbeatMs ?? 2e3
+  );
+  const sayBye = () => post({ v: 1, scope: "presence", type: "bye", clientId, kind });
+  const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
+  if (hasWindow) addEventListener("pagehide", sayBye);
+  return {
+    name,
+    clientId,
+    kind,
+    post,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    acquire() {
+      refs++;
+    },
+    release() {
+      refs--;
+      if (refs > 0) return;
+      sayBye();
+      closed = true;
+      clearInterval(heartbeat);
+      if (hasWindow) removeEventListener("pagehide", sayBye);
+      unsubscribe();
+      transport.close();
+      listeners.clear();
+      onShutdown();
+    }
+  };
+}
+function getBus(name, options = {}) {
+  if (options.transport) {
+    const bus2 = createBus(name, options, () => {
+    });
+    bus2.acquire();
+    return bus2;
+  }
+  let bus = registry.get(name);
+  if (!bus) {
+    bus = createBus(name, options, () => registry.delete(name));
+    registry.set(name, bus);
+  }
+  bus.acquire();
+  return bus;
+}
+
+// src/channel.ts
+function createChannel(name, options = {}) {
+  const bus = getBus(name, options);
+  const handlers = /* @__PURE__ */ new Map();
+  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);
+  });
+  return {
+    name,
+    clientId: bus.clientId,
+    post(type, payload) {
+      bus.post({
+        v: 1,
+        scope: "event",
+        type,
+        payload,
+        clientId: bus.clientId,
+        kind: bus.kind,
+        msgId: newMsgId()
+      });
+    },
+    on(type, handler) {
+      let set = handlers.get(type);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        handlers.set(type, set);
+      }
+      set.add(handler);
+      return () => set.delete(handler);
+    },
+    close() {
+      unsubscribe();
+      handlers.clear();
+      bus.release();
+    }
+  };
+}
+
+// src/clock.ts
+function newer(a, b) {
+  return !b || a[0] > b[0] || a[0] === b[0] && a[1] > b[1];
+}
+
+// src/shared-store.ts
+function createSharedStore(name, initial, options = {}) {
+  const bus = getBus(name, options);
+  const clientId = bus.clientId;
+  const accept = options.accept;
+  const state = { ...initial };
+  const versions = {};
+  for (const k in state) versions[k] = [0, clientId];
+  let snapshot = Object.freeze({ ...state });
+  const listeners = /* @__PURE__ */ new Set();
+  const keyListeners = /* @__PURE__ */ new Map();
+  function notify(key, value, meta) {
+    snapshot = Object.freeze({ ...state });
+    for (const fn of listeners) fn(key, value, meta);
+    const set = keyListeners.get(key);
+    if (set) for (const fn of set) fn();
+  }
+  function applyRemote(key, value, version, meta) {
+    if (!newer(version, versions[key])) return;
+    versions[key] = version;
+    state[key] = 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") {
+      bus.post({
+        v: 1,
+        scope: "state",
+        type: "snapshot",
+        clientId,
+        kind: bus.kind,
+        state: { ...state },
+        versions: { ...versions }
+      });
+      return;
+    }
+    if (accept && !accept(meta)) return;
+    if (wire.type === "patch") {
+      applyRemote(wire.key, wire.value, wire.version, meta);
+    } else {
+      for (const k in wire.state) {
+        const version = wire.versions[k];
+        if (version) applyRemote(k, wire.state[k], version, meta);
+      }
+    }
+  });
+  function setKey(key, value) {
+    const version = [(versions[key]?.[0] ?? 0) + 1, clientId];
+    versions[key] = version;
+    state[key] = 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, {
+    set(_target, key, value) {
+      if (typeof key !== "string") return false;
+      setKey(key, value);
+      return true;
+    }
+  });
+  bus.post({ v: 1, scope: "state", type: "hello", clientId, kind: bus.kind });
+  return {
+    clientId,
+    state: proxy,
+    getSnapshot: () => snapshot,
+    set(key, value) {
+      const next = typeof value === "function" ? value(state[key]) : value;
+      setKey(key, next);
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    subscribeKey(key, fn) {
+      let set = keyListeners.get(key);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        keyListeners.set(key, set);
+      }
+      set.add(fn);
+      return () => set.delete(fn);
+    },
+    registerKey(key, initialValue) {
+      if (key in versions) return;
+      versions[key] = [0, clientId];
+      state[key] = initialValue;
+      snapshot = Object.freeze({ ...state });
+    },
+    close() {
+      unsubscribe();
+      listeners.clear();
+      keyListeners.clear();
+      bus.release();
+    }
+  };
+}
+
+// src/presence.ts
+function createPresence(name, options = {}) {
+  const pruneAfterMs = options.pruneAfterMs ?? 5e3;
+  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.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();
+  });
+  const prune = setInterval(
+    () => {
+      const cutoff = Date.now() - pruneAfterMs;
+      let changed = false;
+      for (const [id, peer] of peers) {
+        if (peer.lastSeen < cutoff) {
+          peers.delete(id);
+          changed = true;
+        }
+      }
+      if (changed) notify();
+    },
+    Math.max(500, Math.floor(pruneAfterMs / 2))
+  );
+  return {
+    clientId: bus.clientId,
+    getPeers: () => snapshot,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    close() {
+      clearInterval(prune);
+      unsubscribe();
+      listeners.clear();
+      bus.release();
+    }
+  };
+}
+
+// src/errors/handshake-timeout-error.ts
+var HandshakeTimeoutError = class extends Error {
+  constructor(message = "handshake with the other window timed out") {
+    super(message);
+    this.name = "HandshakeTimeoutError";
+  }
+};
+
+// src/errors/window-closed-error.ts
+var WindowClosedError = class extends Error {
+  constructor(message = "window closed before a result was delivered") {
+    super(message);
+    this.name = "WindowClosedError";
+  }
+};
+
+// src/window-channel.ts
+var CID_PARAM = "ue-cid";
+function isWindowWire(data, cid) {
+  return typeof data === "object" && data !== null && data.__ue === 1 && data.cid === cid;
+}
+function validatePeerOrigin(peerOrigin, allowAnyOrigin) {
+  if (peerOrigin === "*" && !allowAnyOrigin) {
+    throw new Error(
+      "peerOrigin '*' is unsafe: any page could read your messages. Pass the exact origin, or set allowAnyOrigin: true (dev only)."
+    );
+  }
+}
+function markHandled(promise) {
+  promise.catch(() => {
+  });
+}
+function openWindow(url, options) {
+  const { peerOrigin, allowAnyOrigin } = options;
+  validatePeerOrigin(peerOrigin, allowAnyOrigin);
+  const base = typeof location !== "undefined" ? location.href : void 0;
+  const resolved = new URL(url, base);
+  if (!allowAnyOrigin && resolved.origin !== peerOrigin) {
+    throw new Error(`url origin ${resolved.origin} does not match peerOrigin ${peerOrigin}`);
+  }
+  const cid = newMsgId();
+  resolved.searchParams.set(CID_PARAM, cid);
+  const localWindow = options.localWindow ?? window;
+  const openFn = options.openFn ?? ((u, target, features) => window.open(u, target, features));
+  const targetOrigin = allowAnyOrigin ? "*" : peerOrigin;
+  const handlers = /* @__PURE__ */ new Map();
+  const outQueue = [];
+  let isReady = false;
+  let resultSettled = false;
+  let closedSettled = false;
+  let resolveReady;
+  let rejectReady;
+  const ready = new Promise((res, rej) => (resolveReady = res, rejectReady = rej));
+  let resolveResult;
+  let rejectResult;
+  const result = new Promise((res, rej) => (resolveResult = res, rejectResult = rej));
+  let resolveClosed;
+  const closed = new Promise((res) => resolveClosed = res);
+  markHandled(ready);
+  markHandled(result);
+  const onMessage = (event) => {
+    if (!allowAnyOrigin && event.origin !== peerOrigin) return;
+    if (!isWindowWire(event.data, cid)) return;
+    if (childWindow && event.source !== childWindow) return;
+    const wire = event.data;
+    if (wire.t === "ready") {
+      childWindow?.postMessage({ __ue: 1, cid, t: "ready-ack" }, targetOrigin);
+      if (!isReady) {
+        isReady = true;
+        clearTimeout(readyTimer);
+        for (const queued of outQueue.splice(0)) childWindow?.postMessage(queued, targetOrigin);
+        resolveReady();
+      }
+    } else if (wire.t === "msg") {
+      const set = handlers.get(wire.type);
+      if (set) for (const fn of set) fn(wire.payload);
+    } else if (wire.t === "result") {
+      if (!resultSettled) {
+        resultSettled = true;
+        resolveResult(wire.payload);
+      }
+    } else if (wire.t === "close") {
+      settleClosed();
+    }
+  };
+  localWindow.addEventListener("message", onMessage);
+  function settleClosed() {
+    if (closedSettled) return;
+    closedSettled = true;
+    clearInterval(closePoller);
+    clearTimeout(readyTimer);
+    localWindow.removeEventListener("message", onMessage);
+    if (!resultSettled) {
+      resultSettled = true;
+      rejectResult(new WindowClosedError());
+    }
+    if (!isReady) rejectReady(new WindowClosedError());
+    resolveClosed();
+  }
+  const childWindow = openFn(resolved.toString(), "_blank", options.features);
+  if (!childWindow) {
+    const err = new Error("popup blocked: window.open returned null");
+    localWindow.removeEventListener("message", onMessage);
+    rejectReady(err);
+    resultSettled = true;
+    rejectResult(err);
+    return {
+      window: null,
+      ready,
+      post: () => {
+      },
+      on: () => () => {
+      },
+      result,
+      closed,
+      close: () => {
+      }
+    };
+  }
+  const closePoller = setInterval(() => {
+    if (childWindow.closed) settleClosed();
+  }, 400);
+  const readyTimer = setTimeout(() => {
+    if (isReady || closedSettled) return;
+    const err = new HandshakeTimeoutError();
+    rejectReady(err);
+    if (!resultSettled) {
+      resultSettled = true;
+      rejectResult(err);
+    }
+  }, options.readyTimeoutMs ?? 15e3);
+  return {
+    window: childWindow,
+    ready,
+    result,
+    closed,
+    post(type, payload) {
+      const wire = { __ue: 1, cid, t: "msg", type, payload, msgId: newMsgId() };
+      if (isReady) childWindow.postMessage(wire, targetOrigin);
+      else outQueue.push(wire);
+    },
+    on(type, handler) {
+      let set = handlers.get(type);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        handlers.set(type, set);
+      }
+      set.add(handler);
+      return () => set.delete(handler);
+    },
+    close() {
+      childWindow.close?.();
+    }
+  };
+}
+function connectToOpener(options) {
+  const { peerOrigin, allowAnyOrigin } = options;
+  validatePeerOrigin(peerOrigin, allowAnyOrigin);
+  const opener = options.opener !== void 0 ? options.opener : window.opener ?? null;
+  if (!opener) {
+    throw new Error("no window.opener \u2014 this page was not opened via openWindow()");
+  }
+  const cid = options.cid ?? (typeof location !== "undefined" ? new URLSearchParams(location.search).get(CID_PARAM) : null);
+  if (!cid) {
+    throw new Error(`missing ${CID_PARAM} parameter \u2014 this page was not opened via openWindow()`);
+  }
+  const localWindow = options.localWindow ?? window;
+  const targetOrigin = allowAnyOrigin ? "*" : peerOrigin;
+  const handlers = /* @__PURE__ */ new Map();
+  const outQueue = [];
+  let isReady = false;
+  let resolveReady;
+  let rejectReady;
+  const ready = new Promise((res, rej) => (resolveReady = res, rejectReady = rej));
+  markHandled(ready);
+  const onMessage = (event) => {
+    if (!allowAnyOrigin && event.origin !== peerOrigin) return;
+    if (!isWindowWire(event.data, cid)) return;
+    const wire = event.data;
+    if (wire.t === "ready-ack") {
+      if (!isReady) {
+        isReady = true;
+        clearInterval(retryTimer);
+        clearTimeout(giveUpTimer);
+        for (const queued of outQueue.splice(0)) opener.postMessage(queued, targetOrigin);
+        resolveReady();
+      }
+    } else if (wire.t === "msg") {
+      const set = handlers.get(wire.type);
+      if (set) for (const fn of set) fn(wire.payload);
+    }
+  };
+  localWindow.addEventListener("message", onMessage);
+  const sayReady = () => opener.postMessage({ __ue: 1, cid, t: "ready" }, targetOrigin);
+  sayReady();
+  const retryTimer = setInterval(sayReady, 250);
+  const giveUpTimer = setTimeout(() => {
+    clearInterval(retryTimer);
+    localWindow.removeEventListener("message", onMessage);
+    rejectReady(new HandshakeTimeoutError());
+  }, options.readyTimeoutMs ?? 15e3);
+  const sendOrQueue = (wire) => {
+    if (isReady) opener.postMessage(wire, targetOrigin);
+    else outQueue.push(wire);
+  };
+  const sayClose = () => opener.postMessage({ __ue: 1, cid, t: "close" }, targetOrigin);
+  localWindow.addEventListener("pagehide", sayClose);
+  return {
+    ready,
+    post(type, payload) {
+      sendOrQueue({ __ue: 1, cid, t: "msg", type, payload, msgId: newMsgId() });
+    },
+    on(type, handler) {
+      let set = handlers.get(type);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        handlers.set(type, set);
+      }
+      set.add(handler);
+      return () => set.delete(handler);
+    },
+    finish(value) {
+      sendOrQueue({ __ue: 1, cid, t: "result", payload: value });
+    },
+    close() {
+      sayClose();
+      localWindow.removeEventListener("message", onMessage);
+      localWindow.removeEventListener("pagehide", sayClose);
+      if (typeof window !== "undefined" && options.localWindow === void 0) window.close();
+    }
+  };
+}
+
+// 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,
+  HandshakeTimeoutError,
+  MemoryHub,
+  MemoryTransport,
+  NoopTransport,
+  WindowClosedError,
+  connectToOpener,
+  createChannel,
+  createPresence,
+  createSharedStore,
+  defaultTransport,
+  isBroadcastChannelAvailable,
+  newer,
+  openWindow
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@use-everywhere/core",
+  "version": "0.1.0",
+  "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
+  "license": "MIT",
+  "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rxova/use-everywhere.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/rxova/use-everywhere#readme",
+  "bugs": "https://github.com/rxova/use-everywhere/issues",
+  "keywords": [
+    "broadcastchannel",
+    "cross-tab",
+    "shared-state",
+    "postmessage",
+    "cross-origin",
+    "presence",
+    "pubsub"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
+    "happy-dom": "^20.10.6",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}