@peterddod/phop 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# phop
+
+Peer-to-peer state management for React using WebRTC. Share and sync state across browsers in real time — no backend required.
+
+> ⚠️ **Early Development** — P2P synchronization features are under active development
+
+## Installation
+
+```bash
+npm install @peterddod/phop
+```
+
+## Usage
+
+Wrap your app in a `<Room>` provider and connect to a signaling server:
+
+```tsx
+import { Room, useRoom, useSharedState } from '@peterddod/phop';
+
+function App() {
+  return (
+    <Room signallingServerUrl="wss://your-signalling-server" roomId="my-room">
+      <Counter />
+    </Room>
+  );
+}
+
+function Counter() {
+  const [count, setCount] = useSharedState('count', 0);
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+State updates in `useSharedState` are automatically broadcast to all peers in the room and merged using a configurable conflict resolution strategy.
+
+## API
+
+### `<Room>`
+
+Establishes a WebRTC mesh with all peers in the given room.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `signallingServerUrl` | `string` | WebSocket URL of the signaling server |
+| `roomId` | `string` | Room identifier — peers sharing a room ID connect to each other |
+
+### `useSharedState(key, initialValue, options?)`
+
+Shared state hook — works like `useState` but syncs across all peers in the room.
+
+```ts
+const [value, setValue] = useSharedState<T>(key: string, initialValue: T, options?: {
+  mergeStrategy?: MergeStrategy; // default: lastWriteWins
+})
+```
+
+### `useRoom()`
+
+Access room metadata and low-level messaging.
+
+```ts
+const { peerId, peers, isConnected, broadcast, onMessage } = useRoom();
+```
+
+## Signaling Server
+
+phop requires a lightweight signaling server to coordinate the initial WebRTC handshake. Once peers are connected, all state sync happens directly between browsers.
+
+A production-ready server is available as a Docker image:
+
+```bash
+docker run -p 8080:8080 ghcr.io/peterddod/phop/signalling-server:latest
+```
+
+Source and self-hosting instructions: [`packages/signalling-server`](../signalling-server)
+
+## License
+
+MIT © [Peter Dodd](https://github.com/peterddod)

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+
+type JSONSerializable = string | number | boolean | null | undefined | JSONSerializable[] | {
+    [key: string]: JSONSerializable;
+};
+type Message<TData extends JSONSerializable = JSONSerializable> = {
+    /** The peer ID of the sender */
+    senderId: string;
+    /** The data of the message */
+    data: TData;
+    /** The timestamp of when the message was sent */
+    timestamp: number;
+};
+type MessageHandler<TData extends JSONSerializable = JSONSerializable> = (message: Message<TData>) => void;
+
+interface RoomContextValue {
+    roomId: string;
+    peerId: string;
+    peers: string[];
+    isConnected: boolean;
+    broadcast: <TData extends JSONSerializable = JSONSerializable>(message: Message<TData>) => void;
+    sendToPeer: <TData extends JSONSerializable = JSONSerializable>(peerId: string, message: Message<TData>) => void;
+    onMessage: <TData extends JSONSerializable = JSONSerializable>(handler: MessageHandler<TData>) => () => void;
+    onPeerConnected: (handler: (remotePeerId: string) => void) => () => void;
+}
+declare const RoomContext: react.Context<RoomContextValue | null>;
+interface RoomProps extends React.PropsWithChildren {
+    signallingServerUrl: string;
+    roomId: string;
+}
+declare function Room({ children, signallingServerUrl, roomId }: RoomProps): react_jsx_runtime.JSX.Element;
+
+type MergeMeta = Record<string, JSONSerializable>;
+interface MergeStrategy<TState extends JSONSerializable = JSONSerializable, TMeta extends MergeMeta = MergeMeta> {
+    /** Initial metadata before any sync or update. */
+    initialMeta: TMeta;
+    /** Produce meta when this peer sets state (e.g. timestamp, version). */
+    createMeta(): TMeta;
+    /**
+     * Decide how to merge incoming state with current.
+     * Return new { state, meta } to apply, or null to keep current.
+     */
+    merge(currentState: TState | null, currentMeta: TMeta, incomingState: TState | null, incomingMeta: TMeta, senderId: string): {
+        state: TState | null;
+        meta: TMeta;
+    } | null;
+}
+
+/**
+ * Metadata carried by the Lamport clock strategy.
+ * `clock` is a monotonically increasing logical counter; `tiebreaker` is the
+ * writing peer's ID, used to deterministically resolve equal-clock conflicts.
+ */
+type LamportMeta = {
+    clock: number;
+    tiebreaker: string;
+};
+/**
+ * Creates a Lamport logical-clock merge strategy.
+ *
+ * Unlike wall-clock timestamps, Lamport clocks do not rely on peers having
+ * synchronised system clocks. The clock advances monotonically: it increments
+ * on every local write and is fast-forwarded to `max(local, incoming)` on
+ * every receive, so causal ordering is preserved across all peers.
+ *
+ * Concurrent writes (same clock value) are broken deterministically by
+ * comparing the writing peer's ID as a string, so every peer reaches the same
+ * result independently.
+ *
+ * @param getPeerId - A function that returns the local peer's ID at call time.
+ *   Pass a ref-backed getter so the strategy stays stable even before the
+ *   signalling handshake completes.
+ */
+declare function createLamportStrategy(getPeerId: () => string): MergeStrategy<JSONSerializable, LamportMeta>;
+
+/**
+ * Metadata carried by the Last Write Wins strategy.
+ * `timestamp` is a wall-clock time in milliseconds; `tiebreaker` is the
+ * writing peer's ID, used to deterministically resolve same-millisecond conflicts.
+ */
+type LastWriteWinsMeta = {
+    timestamp: number;
+    tiebreaker: string;
+};
+/**
+ * Creates a Last Write Wins merge strategy.
+ *
+ * Accepts the incoming state whenever its wall-clock timestamp is strictly
+ * greater than the current one. Ties (same millisecond) are broken
+ * deterministically by comparing peer ID strings, so every peer converges to
+ * the same result independently without coordination.
+ *
+ * Note: this strategy relies on peers having reasonably synchronised system
+ * clocks. It is appropriate for use cases where approximate recency is
+ * sufficient (e.g. presence indicators, cursor positions, UI state), but
+ * should not be used where causal ordering must be guaranteed — prefer
+ * `createLamportStrategy` in that case.
+ *
+ * @param getPeerId - A function that returns the local peer's ID at call time.
+ *   Pass a ref-backed getter so the strategy stays stable even before the
+ *   signalling handshake completes.
+ */
+declare function createLastWriteWinsStrategy(getPeerId: () => string): MergeStrategy<JSONSerializable, LastWriteWinsMeta>;
+
+declare function useRoom(): RoomContextValue;
+
+/**
+ * A hook that allows you to share state between multiple peers.
+ *
+ * Works hostlessly by:
+ *
+ * - Broadcasting updates to all peers under the given key; everyone keeps the
+ *   causally latest state according to a Lamport logical clock.
+ * - Late joiners: when a data channel opens to a new peer, both sides push
+ *   their current state to each other; the merge strategy keeps the winner.
+ *
+ * @param key - A string key that namespaces this shared state slice. Multiple calls with the same key share state; different keys are independent.
+ * @param initialState - The initial state of the shared state (used only before any sync or update).
+ * @returns A tuple containing the current state and a function to update the state.
+ */
+declare function useSharedState<TState extends JSONSerializable>(key: string, initialState: TState | null): [state: TState | null, setState: (next: TState | null) => void];
+/**
+ * A hook that allows you to share state between multiple peers with a custom merge strategy.
+ *
+ * @param key - A string key that namespaces this shared state slice.
+ * @param initialState - The initial state (used only before any sync or update).
+ * @param strategy - A merge strategy controlling how incoming state is reconciled.
+ * @returns A tuple containing the current state and a function to update the state.
+ */
+declare function useSharedState<TState extends JSONSerializable, TMeta extends MergeMeta>(key: string, initialState: TState | null, strategy: MergeStrategy<TState, TMeta>): [state: TState | null, setState: (next: TState | null) => void];
+
+export { type JSONSerializable, type LamportMeta, type LastWriteWinsMeta, type MergeMeta, type MergeStrategy, type Message, type MessageHandler, Room, RoomContext, type RoomContextValue, createLamportStrategy, createLastWriteWinsStrategy, useRoom, useSharedState };

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+
+type JSONSerializable = string | number | boolean | null | undefined | JSONSerializable[] | {
+    [key: string]: JSONSerializable;
+};
+type Message<TData extends JSONSerializable = JSONSerializable> = {
+    /** The peer ID of the sender */
+    senderId: string;
+    /** The data of the message */
+    data: TData;
+    /** The timestamp of when the message was sent */
+    timestamp: number;
+};
+type MessageHandler<TData extends JSONSerializable = JSONSerializable> = (message: Message<TData>) => void;
+
+interface RoomContextValue {
+    roomId: string;
+    peerId: string;
+    peers: string[];
+    isConnected: boolean;
+    broadcast: <TData extends JSONSerializable = JSONSerializable>(message: Message<TData>) => void;
+    sendToPeer: <TData extends JSONSerializable = JSONSerializable>(peerId: string, message: Message<TData>) => void;
+    onMessage: <TData extends JSONSerializable = JSONSerializable>(handler: MessageHandler<TData>) => () => void;
+    onPeerConnected: (handler: (remotePeerId: string) => void) => () => void;
+}
+declare const RoomContext: react.Context<RoomContextValue | null>;
+interface RoomProps extends React.PropsWithChildren {
+    signallingServerUrl: string;
+    roomId: string;
+}
+declare function Room({ children, signallingServerUrl, roomId }: RoomProps): react_jsx_runtime.JSX.Element;
+
+type MergeMeta = Record<string, JSONSerializable>;
+interface MergeStrategy<TState extends JSONSerializable = JSONSerializable, TMeta extends MergeMeta = MergeMeta> {
+    /** Initial metadata before any sync or update. */
+    initialMeta: TMeta;
+    /** Produce meta when this peer sets state (e.g. timestamp, version). */
+    createMeta(): TMeta;
+    /**
+     * Decide how to merge incoming state with current.
+     * Return new { state, meta } to apply, or null to keep current.
+     */
+    merge(currentState: TState | null, currentMeta: TMeta, incomingState: TState | null, incomingMeta: TMeta, senderId: string): {
+        state: TState | null;
+        meta: TMeta;
+    } | null;
+}
+
+/**
+ * Metadata carried by the Lamport clock strategy.
+ * `clock` is a monotonically increasing logical counter; `tiebreaker` is the
+ * writing peer's ID, used to deterministically resolve equal-clock conflicts.
+ */
+type LamportMeta = {
+    clock: number;
+    tiebreaker: string;
+};
+/**
+ * Creates a Lamport logical-clock merge strategy.
+ *
+ * Unlike wall-clock timestamps, Lamport clocks do not rely on peers having
+ * synchronised system clocks. The clock advances monotonically: it increments
+ * on every local write and is fast-forwarded to `max(local, incoming)` on
+ * every receive, so causal ordering is preserved across all peers.
+ *
+ * Concurrent writes (same clock value) are broken deterministically by
+ * comparing the writing peer's ID as a string, so every peer reaches the same
+ * result independently.
+ *
+ * @param getPeerId - A function that returns the local peer's ID at call time.
+ *   Pass a ref-backed getter so the strategy stays stable even before the
+ *   signalling handshake completes.
+ */
+declare function createLamportStrategy(getPeerId: () => string): MergeStrategy<JSONSerializable, LamportMeta>;
+
+/**
+ * Metadata carried by the Last Write Wins strategy.
+ * `timestamp` is a wall-clock time in milliseconds; `tiebreaker` is the
+ * writing peer's ID, used to deterministically resolve same-millisecond conflicts.
+ */
+type LastWriteWinsMeta = {
+    timestamp: number;
+    tiebreaker: string;
+};
+/**
+ * Creates a Last Write Wins merge strategy.
+ *
+ * Accepts the incoming state whenever its wall-clock timestamp is strictly
+ * greater than the current one. Ties (same millisecond) are broken
+ * deterministically by comparing peer ID strings, so every peer converges to
+ * the same result independently without coordination.
+ *
+ * Note: this strategy relies on peers having reasonably synchronised system
+ * clocks. It is appropriate for use cases where approximate recency is
+ * sufficient (e.g. presence indicators, cursor positions, UI state), but
+ * should not be used where causal ordering must be guaranteed — prefer
+ * `createLamportStrategy` in that case.
+ *
+ * @param getPeerId - A function that returns the local peer's ID at call time.
+ *   Pass a ref-backed getter so the strategy stays stable even before the
+ *   signalling handshake completes.
+ */
+declare function createLastWriteWinsStrategy(getPeerId: () => string): MergeStrategy<JSONSerializable, LastWriteWinsMeta>;
+
+declare function useRoom(): RoomContextValue;
+
+/**
+ * A hook that allows you to share state between multiple peers.
+ *
+ * Works hostlessly by:
+ *
+ * - Broadcasting updates to all peers under the given key; everyone keeps the
+ *   causally latest state according to a Lamport logical clock.
+ * - Late joiners: when a data channel opens to a new peer, both sides push
+ *   their current state to each other; the merge strategy keeps the winner.
+ *
+ * @param key - A string key that namespaces this shared state slice. Multiple calls with the same key share state; different keys are independent.
+ * @param initialState - The initial state of the shared state (used only before any sync or update).
+ * @returns A tuple containing the current state and a function to update the state.
+ */
+declare function useSharedState<TState extends JSONSerializable>(key: string, initialState: TState | null): [state: TState | null, setState: (next: TState | null) => void];
+/**
+ * A hook that allows you to share state between multiple peers with a custom merge strategy.
+ *
+ * @param key - A string key that namespaces this shared state slice.
+ * @param initialState - The initial state (used only before any sync or update).
+ * @param strategy - A merge strategy controlling how incoming state is reconciled.
+ * @returns A tuple containing the current state and a function to update the state.
+ */
+declare function useSharedState<TState extends JSONSerializable, TMeta extends MergeMeta>(key: string, initialState: TState | null, strategy: MergeStrategy<TState, TMeta>): [state: TState | null, setState: (next: TState | null) => void];
+
+export { type JSONSerializable, type LamportMeta, type LastWriteWinsMeta, type MergeMeta, type MergeStrategy, type Message, type MessageHandler, Room, RoomContext, type RoomContextValue, createLamportStrategy, createLastWriteWinsStrategy, useRoom, useSharedState };