use-everywhere 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,80 @@
+# use-everywhere
+
+React hooks for state and messages that exist in every tab, window, and worker.
+
+```bash
+npm i use-everywhere
+```
+
+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 — e.g. a payment page on another domain that must report
+  back to the checkout that opened it. Every message is validated by origin,
+  envelope brand, a per-connection nonce, and the source window.
+
+## Usage
+
+```tsx
+import {
+  useSharedState,
+  useChannel,
+  useMessage,
+  usePeers,
+  useOpenedWindow,
+  openWindow,
+} from 'use-everywhere';
+
+// useState, but the value exists in every tab/window/worker on this origin.
+const [count, setCount] = useSharedState('count', 0);
+
+// Typed fire-and-forget events between tabs.
+const channel = useChannel<{ 'cart-updated': { items: number } }>('shop');
+useMessage(channel, 'cart-updated', ({ items }) => refresh(items));
+channel.post('cart-updated', { items: 3 });
+
+// Who else is here?
+const peers = usePeers();
+
+// Open a window on ANOTHER origin and await its result.
+const pay = useOpenedWindow(() =>
+  openWindow<ToPayment, FromPayment, Receipt>('https://pay.example.com/checkout', {
+    peerOrigin: 'https://pay.example.com',
+  }),
+);
+// pay.open() from a click handler; pay.status: idle → opening → connected → done
+// pay.result is the child's finish() value; closing early yields 'closed-early'.
+```
+
+On the opened (child) page:
+
+```ts
+import { connectToOpener } from 'use-everywhere';
+
+const conn = connectToOpener<ToPayment, FromPayment, Receipt>({
+  peerOrigin: 'https://shop.example.com',
+});
+conn.on('order', (order) => render(order));
+conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's result
+```
+
+## Design notes
+
+- **Shared state never crosses origins.** Two origins are two trust domains;
+  the cross-origin channel is explicit, per-message, and typed.
+- **No Provider.** A BroadcastChannel is already global to the origin —
+  identity is the channel name, so hooks share module-level singletons.
+- Values must survive structured clone (no functions, DOM nodes, etc.).
+
+This package re-exports the full framework-agnostic surface of
+[`@use-everywhere/core`](https://www.npmjs.com/package/@use-everywhere/core),
+so you never need to install core directly.
+
+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,77 @@
+import { SharedStore, MessageMap, Channel, MessageMeta, Peer, OpenedWindow } from '@use-everywhere/core';
+export * from '@use-everywhere/core';
+
+/**
+ * How far a shared value travels:
+ * - 'everywhere' — every tab, window, and worker on this origin (default)
+ * - 'tabs'       — tabs and windows only; writes coming from workers are ignored
+ * - 'tab'        — this tab only (state is still shared between components)
+ */
+type ShareScope = 'everywhere' | 'tabs' | 'tab';
+interface UseSharedStateOptions {
+    /** Store name; keys live in a namespace per store. Default 'use-everywhere'. */
+    store?: string;
+    /** How much to share. Default 'everywhere'. */
+    scope?: ShareScope;
+}
+
+/**
+ * Like useState, but the value exists in every tab, window, and worker on
+ * this origin. Late-joining tabs hydrate to the current value; concurrent
+ * writes converge last-writer-wins. Pass options.scope to delimit how much
+ * is shared ('everywhere' | 'tabs' | 'tab').
+ */
+declare function useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
+
+/** Registry stores hold arbitrary keys — shape is decided by the hooks using them. */
+type AnyStore = SharedStore<Record<string, unknown>>;
+
+/**
+ * A BroadcastChannel is already global to the origin — identity is the name
+ * string, not the React tree — so hooks share module-level singletons per
+ * name instead of requiring a Provider. Instances live for the page lifetime.
+ */
+declare const DEFAULT_NAME = "use-everywhere";
+/** Imperative access to the store behind useSharedState (patch logs, non-React code). */
+declare function getSharedStore(name?: string, scope?: ShareScope): AnyStore;
+
+/** Get the page-wide typed channel for `name` (one instance per name). */
+declare function useChannel<M extends MessageMap>(name: string): Channel<M>;
+/**
+ * Subscribe to one message type. The handler is kept fresh without
+ * resubscribing, so it may close over render state.
+ */
+declare function useMessage<M extends MessageMap, K extends keyof M & string>(channel: Channel<M>, type: K, handler: (payload: M[K], meta: MessageMeta) => void): void;
+/** The channel's post function (stable identity per channel). */
+declare function useSend<M extends MessageMap>(channel: Channel<M>): Channel<M>['post'];
+
+/** The other tabs/windows/workers currently alive on this origin. */
+declare function usePeers(options?: {
+    name?: string;
+}): readonly Peer[];
+/** This client's own id on the presence bus (matches patch origin ids). */
+declare function useClientId(options?: {
+    name?: string;
+}): string;
+
+type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
+interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
+    /** Call from a click handler (popup blockers require a user gesture). */
+    open: () => void;
+    status: OpenedWindowStatus;
+    /** The child's finish() value, once status is 'done'. */
+    result: R | undefined;
+    error: unknown;
+    /** Post to the child; no-op while nothing is open. */
+    post: OpenedWindow<Out, In, R>['post'];
+    close: () => void;
+}
+
+/**
+ * Drive an openWindow() flow from a component: the factory is called on
+ * open(), and the child window's lifecycle is folded into render state.
+ * Reopening replaces the previous window; a stale window's outcome is ignored.
+ */
+declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
+
+export { type AnyStore, DEFAULT_NAME, type OpenedWindowStatus, type ShareScope, type UseOpenedWindow, type UseSharedStateOptions, getSharedStore, useChannel, useClientId, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };

package/dist/index.js

@@ -0,0 +1,164 @@
+// src/use-shared-state.ts
+import { useCallback, useSyncExternalStore } from "react";
+
+// src/registry.ts
+import {
+  createChannel,
+  createPresence,
+  createSharedStore,
+  NoopTransport
+} from "@use-everywhere/core";
+var DEFAULT_NAME = "use-everywhere";
+var stores = /* @__PURE__ */ new Map();
+var presences = /* @__PURE__ */ new Map();
+var channels = /* @__PURE__ */ new Map();
+var scopeOptions = {
+  everywhere: {},
+  tabs: { accept: (meta) => meta.kind !== "worker" },
+  tab: { transport: () => new NoopTransport() }
+};
+function getSharedStore(name = DEFAULT_NAME, scope = "everywhere") {
+  return getStore(name, scope);
+}
+function getStore(name, scope = "everywhere") {
+  const key = `${scope}\0${name}`;
+  let store = stores.get(key);
+  if (!store) {
+    store = createSharedStore(name, {}, scopeOptions[scope]);
+    stores.set(key, store);
+  }
+  return store;
+}
+function getPresence(name) {
+  let presence = presences.get(name);
+  if (!presence) {
+    presence = createPresence(name);
+    presences.set(name, presence);
+  }
+  return presence;
+}
+function getChannel(name) {
+  let channel = channels.get(name);
+  if (!channel) {
+    channel = createChannel(name);
+    channels.set(name, channel);
+  }
+  return channel;
+}
+
+// src/use-shared-state.ts
+function useSharedState(key, initial, options) {
+  const store = getStore(options?.store ?? DEFAULT_NAME, options?.scope ?? "everywhere");
+  store.registerKey(key, initial);
+  const value = useSyncExternalStore(
+    useCallback((onChange) => store.subscribeKey(key, onChange), [store, key]),
+    () => store.getSnapshot()[key],
+    () => initial
+  );
+  const setValue = useCallback(
+    (next) => store.set(key, next),
+    [store, key]
+  );
+  return [value, setValue];
+}
+
+// src/use-message.ts
+import { useEffect, useRef } from "react";
+function useChannel(name) {
+  return getChannel(name);
+}
+function useMessage(channel, type, handler) {
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+  useEffect(
+    () => channel.on(type, (payload, meta) => handlerRef.current(payload, meta)),
+    [channel, type]
+  );
+}
+function useSend(channel) {
+  return channel.post;
+}
+
+// src/use-peers.ts
+import { useCallback as useCallback2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+var NO_PEERS = Object.freeze([]);
+function usePeers(options) {
+  const presence = getPresence(options?.name ?? DEFAULT_NAME);
+  return useSyncExternalStore2(
+    useCallback2((onChange) => presence.subscribe(onChange), [presence]),
+    () => presence.getPeers(),
+    () => NO_PEERS
+  );
+}
+function useClientId(options) {
+  return getPresence(options?.name ?? DEFAULT_NAME).clientId;
+}
+
+// src/use-opened-window.ts
+import { useCallback as useCallback3, useRef as useRef2, useState } from "react";
+import { WindowClosedError } from "@use-everywhere/core";
+function useOpenedWindow(factory) {
+  const [status, setStatus] = useState("idle");
+  const [result, setResult] = useState(void 0);
+  const [error, setError] = useState(void 0);
+  const current = useRef2(null);
+  const factoryRef = useRef2(factory);
+  factoryRef.current = factory;
+  const open = useCallback3(() => {
+    current.current?.close();
+    let opened;
+    try {
+      opened = factoryRef.current();
+    } catch (err) {
+      setStatus("error");
+      setError(err);
+      return;
+    }
+    current.current = opened;
+    setStatus("opening");
+    setResult(void 0);
+    setError(void 0);
+    const fresh = () => current.current === opened;
+    opened.ready.then(
+      () => {
+        if (fresh()) setStatus((s) => s === "opening" ? "connected" : s);
+      },
+      () => {
+      }
+      // surfaced through result below
+    );
+    opened.result.then(
+      (value) => {
+        if (!fresh()) return;
+        setResult(value);
+        setStatus("done");
+      },
+      (err) => {
+        if (!fresh()) return;
+        setError(err);
+        setStatus(err instanceof WindowClosedError ? "closed-early" : "error");
+      }
+    );
+  }, []);
+  const post = useCallback3((type, payload) => {
+    current.current?.post(type, payload);
+  }, []);
+  const close = useCallback3(() => current.current?.close(), []);
+  return { open, status, result, error, post, close };
+}
+
+// src/index.ts
+export * from "@use-everywhere/core";
+export {
+  DEFAULT_NAME,
+  getSharedStore,
+  useChannel,
+  useClientId,
+  useMessage,
+  useOpenedWindow,
+  usePeers,
+  useSend,
+  useSharedState
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "use-everywhere",
+  "version": "0.1.0",
+  "description": "React hooks for state and messages shared across tabs, windows, and workers",
+  "license": "MIT",
+  "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rxova/use-everywhere.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/rxova/use-everywhere#readme",
+  "bugs": "https://github.com/rxova/use-everywhere/issues",
+  "keywords": [
+    "react",
+    "hooks",
+    "broadcastchannel",
+    "cross-tab",
+    "shared-state",
+    "postmessage",
+    "cross-origin",
+    "presence"
+  ],
+  "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"
+  ],
+  "dependencies": {
+    "@use-everywhere/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^4.1.10",
+    "happy-dom": "^20.10.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}