@crdt-sync/core 0.1.0

package/dist/CrdtStateProxy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.
+ *
+ * In production, import the real `WasmStateStore` from the compiled Wasm
+ * package (e.g. `import { WasmStateStore } from './crdt_sync.js'`).
+ * In tests the interface can be satisfied by any mock object.
+ */
+export interface WasmStateStore {
+    /** Write a JSON-encoded value to the named LWW register. Returns the Envelope JSON. */
+    set_register(key: string, value_json: string): string;
+    /** Read the current value of a named LWW register as a JSON string, or `undefined`. */
+    get_register(key: string): string | undefined;
+    /** Apply a remote Envelope (serialised as JSON) to this store. */
+    apply_envelope(envelope_json: string): void;
+}
+/**
+ * Payload delivered to every `onUpdate` listener when a property is written
+ * through the proxy.
+ */
+export interface UpdateEvent {
+    /** Dot-separated key path that was updated (e.g. `"robot.speed"`). */
+    key: string;
+    /** The new JavaScript value. */
+    value: unknown;
+    /**
+     * The CRDT Envelope returned by `WasmStateStore.set_register`, serialised
+     * as a JSON string.  Broadcast this to peer nodes via `apply_envelope`.
+     */
+    envelope: string;
+}
+/** Callback type for `onUpdate` listeners. */
+export type UpdateHandler = (event: UpdateEvent) => void;
+/**
+ * A TypeScript proxy wrapper around `WasmStateStore` that gives frontend
+ * developers a **magical, object-oriented** experience.
+ *
+ * ## How it works
+ *
+ * 1. **JS `Proxy` interception** – accessing a nested path on `state` returns
+ *    another `Proxy`.  Assigning a value anywhere in the tree intercepts the
+ *    write and forwards it to the underlying Wasm store via
+ *    `set_register(dotPath, JSON.stringify(value))`.
+ *
+ * 2. **Wasm call** – the interceptor immediately calls
+ *    `WasmStateStore.set_register()` so the CRDT operation is recorded and
+ *    returns an `Envelope` JSON string ready for broadcasting.
+ *
+ * 3. **Event emitter** – every write fires all `onUpdate` listeners with the
+ *    full `UpdateEvent` (key, value, envelope), enabling React / Vue and other
+ *    UI frameworks to react to state changes.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import init, { WasmStateStore } from './crdt_sync.js';
+ * import { CrdtStateProxy } from './CrdtStateProxy.js';
+ *
+ * await init();
+ * const store = new WasmStateStore('node-1');
+ * const proxy = new CrdtStateProxy(store);
+ *
+ * // Register a listener (e.g. trigger a React re-render).
+ * const unsubscribe = proxy.onUpdate(({ key, value, envelope }) => {
+ *   console.log(`${key} =`, value);
+ *   broadcast(envelope); // send to peers
+ * });
+ *
+ * // Write through the proxy — the interceptor handles everything.
+ * proxy.state.speed = 100;
+ * proxy.state.robot.x = 42;
+ *
+ * // Clean up when done.
+ * unsubscribe();
+ * ```
+ */
+export declare class CrdtStateProxy {
+    private readonly _store;
+    private readonly _handlers;
+    private readonly _state;
+    /**
+     * Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.
+     *
+     * @param store - The Wasm state store instance to proxy.
+     */
+    constructor(store: WasmStateStore);
+    /**
+     * The proxied state object.
+     *
+     * Assigning any property (or nested property) on this object will
+     * automatically call `WasmStateStore.set_register` and fire `onUpdate`
+     * listeners.
+     *
+     * ```ts
+     * proxy.state.speed = 100;       // key: "speed"
+     * proxy.state.robot.speed = 100; // key: "robot.speed"
+     * ```
+     */
+    get state(): Record<string, unknown>;
+    /**
+     * Register a listener that is called whenever a property is written through
+     * `proxy.state`.
+     *
+     * @param handler - Callback receiving an `UpdateEvent`.
+     * @returns An unsubscribe function — call it to remove the listener.
+     */
+    onUpdate(handler: UpdateHandler): () => void;
+    /**
+     * Recursively build a `Proxy` for the given dot-path `prefix`.
+     *
+     * - **`get` trap**: returns a child proxy for the nested path so that deep
+     *   assignments like `proxy.state.robot.speed = 100` work correctly.
+     * - **`set` trap**: serialises the value, calls `set_register`, and fires
+     *   all `onUpdate` listeners.
+     */
+    private _makeProxy;
+    /** Dispatch an `UpdateEvent` to all registered handlers. */
+    private _emit;
+}
+//# sourceMappingURL=CrdtStateProxy.d.ts.map

package/dist/CrdtStateProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CrdtStateProxy.d.ts","sourceRoot":"","sources":["../src/CrdtStateProxy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IACtD,uFAAuF;IACvF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,kEAAkE;IAClE,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IAEjD;;;;OAIG;gBACS,KAAK,EAAE,cAAc;IAOjC;;;;;;;;;;;OAWG;IACH,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,IAAI;IAS5C;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAqBlB,4DAA4D;IAC5D,OAAO,CAAC,KAAK;CAGd"}

package/dist/CrdtStateProxy.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrdtStateProxy = void 0;
+/**
+ * A TypeScript proxy wrapper around `WasmStateStore` that gives frontend
+ * developers a **magical, object-oriented** experience.
+ *
+ * ## How it works
+ *
+ * 1. **JS `Proxy` interception** – accessing a nested path on `state` returns
+ *    another `Proxy`.  Assigning a value anywhere in the tree intercepts the
+ *    write and forwards it to the underlying Wasm store via
+ *    `set_register(dotPath, JSON.stringify(value))`.
+ *
+ * 2. **Wasm call** – the interceptor immediately calls
+ *    `WasmStateStore.set_register()` so the CRDT operation is recorded and
+ *    returns an `Envelope` JSON string ready for broadcasting.
+ *
+ * 3. **Event emitter** – every write fires all `onUpdate` listeners with the
+ *    full `UpdateEvent` (key, value, envelope), enabling React / Vue and other
+ *    UI frameworks to react to state changes.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import init, { WasmStateStore } from './crdt_sync.js';
+ * import { CrdtStateProxy } from './CrdtStateProxy.js';
+ *
+ * await init();
+ * const store = new WasmStateStore('node-1');
+ * const proxy = new CrdtStateProxy(store);
+ *
+ * // Register a listener (e.g. trigger a React re-render).
+ * const unsubscribe = proxy.onUpdate(({ key, value, envelope }) => {
+ *   console.log(`${key} =`, value);
+ *   broadcast(envelope); // send to peers
+ * });
+ *
+ * // Write through the proxy — the interceptor handles everything.
+ * proxy.state.speed = 100;
+ * proxy.state.robot.x = 42;
+ *
+ * // Clean up when done.
+ * unsubscribe();
+ * ```
+ */
+class CrdtStateProxy {
+    /**
+     * Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.
+     *
+     * @param store - The Wasm state store instance to proxy.
+     */
+    constructor(store) {
+        this._handlers = new Set();
+        this._store = store;
+        this._state = this._makeProxy('');
+    }
+    // ── Public API ────────────────────────────────────────────────────────
+    /**
+     * The proxied state object.
+     *
+     * Assigning any property (or nested property) on this object will
+     * automatically call `WasmStateStore.set_register` and fire `onUpdate`
+     * listeners.
+     *
+     * ```ts
+     * proxy.state.speed = 100;       // key: "speed"
+     * proxy.state.robot.speed = 100; // key: "robot.speed"
+     * ```
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Register a listener that is called whenever a property is written through
+     * `proxy.state`.
+     *
+     * @param handler - Callback receiving an `UpdateEvent`.
+     * @returns An unsubscribe function — call it to remove the listener.
+     */
+    onUpdate(handler) {
+        this._handlers.add(handler);
+        return () => {
+            this._handlers.delete(handler);
+        };
+    }
+    // ── Internal helpers ──────────────────────────────────────────────────
+    /**
+     * Recursively build a `Proxy` for the given dot-path `prefix`.
+     *
+     * - **`get` trap**: returns a child proxy for the nested path so that deep
+     *   assignments like `proxy.state.robot.speed = 100` work correctly.
+     * - **`set` trap**: serialises the value, calls `set_register`, and fires
+     *   all `onUpdate` listeners.
+     */
+    _makeProxy(prefix) {
+        const children = {};
+        return new Proxy({}, {
+            get: (_target, prop) => {
+                const key = prefix ? `${prefix}.${prop}` : prop;
+                if (!(prop in children)) {
+                    children[prop] = this._makeProxy(key);
+                }
+                return children[prop];
+            },
+            set: (_target, prop, value) => {
+                const key = prefix ? `${prefix}.${prop}` : prop;
+                const envelope = this._store.set_register(key, JSON.stringify(value));
+                this._emit({ key, value, envelope });
+                return true;
+            },
+        });
+    }
+    /** Dispatch an `UpdateEvent` to all registered handlers. */
+    _emit(event) {
+        this._handlers.forEach((handler) => handler(event));
+    }
+}
+exports.CrdtStateProxy = CrdtStateProxy;
+//# sourceMappingURL=CrdtStateProxy.js.map

package/dist/CrdtStateProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CrdtStateProxy.js","sourceRoot":"","sources":["../src/CrdtStateProxy.ts"],"names":[],"mappings":";;;AAmCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAa,cAAc;IAKzB;;;;OAIG;IACH,YAAY,KAAqB;QARhB,cAAS,GAAuB,IAAI,GAAG,EAAE,CAAC;QASzD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,yEAAyE;IAEzE;;;;;;;;;;;OAWG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAsB;QAC7B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC,CAAC;IACJ,CAAC;IAED,yEAAyE;IAEzE;;;;;;;OAOG;IACK,UAAU,CAAC,MAAc;QAC/B,MAAM,QAAQ,GAA4C,EAAE,CAAC;QAE7D,OAAO,IAAI,KAAK,CAAC,EAA6B,EAAE;YAC9C,GAAG,EAAE,CAAC,OAAO,EAAE,IAAY,EAAE,EAAE;gBAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBAChD,IAAI,CAAC,CAAC,IAAI,IAAI,QAAQ,CAAC,EAAE,CAAC;oBACxB,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBACxC,CAAC;gBACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;YAED,GAAG,EAAE,CAAC,OAAO,EAAE,IAAY,EAAE,KAAc,EAAE,EAAE;gBAC7C,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;gBACtE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;gBACrC,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IACpD,KAAK,CAAC,KAAkB;QAC9B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC;CACF;AAlFD,wCAkFC"}

package/dist/WebSocketManager.d.ts

@@ -0,0 +1,115 @@
+import { CrdtStateProxy } from './CrdtStateProxy.js';
+import type { WasmStateStore } from './CrdtStateProxy.js';
+/**
+ * Minimal subset of the browser `WebSocket` API used by `WebSocketManager`.
+ *
+ * The real browser `WebSocket` satisfies this interface out-of-the-box.
+ * In tests, a plain mock object can be used instead.
+ */
+export interface WebSocketLike {
+    /** Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). */
+    readonly readyState: number;
+    /** Send a UTF-8 string frame to the server. */
+    send(data: string): void;
+    /** Initiate the closing handshake. */
+    close(): void;
+    /** Fired when a message frame is received. */
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    /** Fired when the connection is established. */
+    onopen: ((event: unknown) => void) | null;
+    /** Fired when the connection is closed. */
+    onclose: ((event: unknown) => void) | null;
+    /** Fired when an error occurs. */
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT
+ * operation produced locally is broadcast to peers, and every envelope
+ * received from a peer is applied to the local store.
+ *
+ * ## Data flow
+ *
+ * ```
+ * Local write
+ *   → CrdtStateProxy.onUpdate  (envelope collected in _pendingEnvelopes)
+ *   → requestAnimationFrame / setTimeout schedules a batch flush
+ *   → WebSocket.send(JSON.stringify(envelopes))   // one payload per frame
+ *
+ * Incoming message (single envelope or JSON array of envelopes)
+ *   → WebSocket.onmessage
+ *   → WasmStateStore.apply_envelope()    // merge into local store
+ * ```
+ *
+ * ## Throttling / batching
+ *
+ * Multiple proxy writes that occur within the same JavaScript task (e.g. a
+ * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single
+ * JSON array payload on the next animation frame (browser) or the next
+ * `setTimeout(fn, 0)` tick (Node.js / non-browser environments).  This keeps
+ * network traffic proportional to frame rate rather than to the raw mutation
+ * rate.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import init, { WasmStateStore } from './crdt_sync.js';
+ * import { CrdtStateProxy, WebSocketManager } from './index.js';
+ *
+ * await init();
+ * const store = new WasmStateStore('node-1');
+ * const proxy = new CrdtStateProxy(store);
+ * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));
+ *
+ * // Writes are automatically batched and broadcast to peers.
+ * proxy.state.robot = { x: 10, y: 20 };
+ *
+ * // Clean up.
+ * manager.disconnect();
+ * ```
+ */
+export declare class WebSocketManager {
+    private readonly _store;
+    private readonly _proxy;
+    private readonly _ws;
+    private _unsubscribe;
+    /** Envelopes collected in the current frame, waiting for the batch flush. */
+    private _pendingEnvelopes;
+    /** Cancels the currently scheduled batch flush (rAF or setTimeout handle). */
+    private _cancelFlush;
+    /** Envelopes queued while the socket is not open, flushed on reconnection. */
+    private _offlineQueue;
+    /**
+     * Create a `WebSocketManager` and attach it to the given WebSocket.
+     *
+     * @param store - The Wasm state store. Incoming peer envelopes will be
+     *   applied to this store via `apply_envelope`.
+     * @param proxy - The CRDT state proxy. Outgoing envelopes produced by
+     *   `set_register` calls will be read from the proxy's `onUpdate` events.
+     * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).
+     */
+    constructor(store: WasmStateStore, proxy: CrdtStateProxy, ws: WebSocketLike);
+    private _attach;
+    /**
+     * Schedule a single batch flush for the current frame.  Subsequent calls
+     * before the flush fires are no-ops (only one flush is ever outstanding).
+     *
+     * Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),
+     * falling back to `setTimeout(fn, 0)` in non-browser environments.
+     */
+    private _scheduleBatchFlush;
+    /**
+     * Send all pending envelopes as a single JSON-array payload, or move them
+     * to the offline queue if the socket is not currently open.
+     */
+    private _flushBatch;
+    /**
+     * Unsubscribe from proxy updates, discard any buffered envelopes, and close
+     * the WebSocket connection.
+     *
+     * Safe to call more than once.
+     */
+    disconnect(): void;
+}
+//# sourceMappingURL=WebSocketManager.d.ts.map

package/dist/WebSocketManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketManager.d.ts","sourceRoot":"","sources":["../src/WebSocketManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACtD,gDAAgD;IAChD,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,2CAA2C;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,kCAAkC;IAClC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,YAAY,CAA6B;IACjD,6EAA6E;IAC7E,OAAO,CAAC,iBAAiB,CAAgB;IACzC,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA6B;IACjD,8EAA8E;IAC9E,OAAO,CAAC,aAAa,CAAgB;IAErC;;;;;;;;OAQG;gBACS,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,aAAa;IAS3E,OAAO,CAAC,OAAO;IAoDf;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;OAKG;IACH,UAAU,IAAI,IAAI;CASnB"}

package/dist/WebSocketManager.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketManager = void 0;
+/**
+ * Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT
+ * operation produced locally is broadcast to peers, and every envelope
+ * received from a peer is applied to the local store.
+ *
+ * ## Data flow
+ *
+ * ```
+ * Local write
+ *   → CrdtStateProxy.onUpdate  (envelope collected in _pendingEnvelopes)
+ *   → requestAnimationFrame / setTimeout schedules a batch flush
+ *   → WebSocket.send(JSON.stringify(envelopes))   // one payload per frame
+ *
+ * Incoming message (single envelope or JSON array of envelopes)
+ *   → WebSocket.onmessage
+ *   → WasmStateStore.apply_envelope()    // merge into local store
+ * ```
+ *
+ * ## Throttling / batching
+ *
+ * Multiple proxy writes that occur within the same JavaScript task (e.g. a
+ * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single
+ * JSON array payload on the next animation frame (browser) or the next
+ * `setTimeout(fn, 0)` tick (Node.js / non-browser environments).  This keeps
+ * network traffic proportional to frame rate rather than to the raw mutation
+ * rate.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import init, { WasmStateStore } from './crdt_sync.js';
+ * import { CrdtStateProxy, WebSocketManager } from './index.js';
+ *
+ * await init();
+ * const store = new WasmStateStore('node-1');
+ * const proxy = new CrdtStateProxy(store);
+ * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));
+ *
+ * // Writes are automatically batched and broadcast to peers.
+ * proxy.state.robot = { x: 10, y: 20 };
+ *
+ * // Clean up.
+ * manager.disconnect();
+ * ```
+ */
+class WebSocketManager {
+    /**
+     * Create a `WebSocketManager` and attach it to the given WebSocket.
+     *
+     * @param store - The Wasm state store. Incoming peer envelopes will be
+     *   applied to this store via `apply_envelope`.
+     * @param proxy - The CRDT state proxy. Outgoing envelopes produced by
+     *   `set_register` calls will be read from the proxy's `onUpdate` events.
+     * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).
+     */
+    constructor(store, proxy, ws) {
+        this._unsubscribe = null;
+        /** Envelopes collected in the current frame, waiting for the batch flush. */
+        this._pendingEnvelopes = [];
+        /** Cancels the currently scheduled batch flush (rAF or setTimeout handle). */
+        this._cancelFlush = null;
+        /** Envelopes queued while the socket is not open, flushed on reconnection. */
+        this._offlineQueue = [];
+        this._store = store;
+        this._proxy = proxy;
+        this._ws = ws;
+        this._attach();
+    }
+    // ── Internal setup ────────────────────────────────────────────────────
+    _attach() {
+        const ws = this._ws;
+        // Collect envelopes and schedule a batch flush once per frame so that
+        // multiple synchronous writes (e.g. a 60 FPS game loop) are coalesced
+        // into a single network payload instead of one message per mutation.
+        this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {
+            this._pendingEnvelopes.push(envelope);
+            this._scheduleBatchFlush();
+        });
+        // On (re)connection, immediately flush pending envelopes together with any
+        // envelopes that were queued while the socket was offline.
+        ws.onopen = () => {
+            // Cancel any scheduled flush — we will drain everything right now.
+            this._cancelFlush?.();
+            this._cancelFlush = null;
+            const offline = this._offlineQueue;
+            const pending = this._pendingEnvelopes;
+            this._offlineQueue = [];
+            this._pendingEnvelopes = [];
+            const batch = [...offline, ...pending];
+            if (batch.length > 0) {
+                ws.send(JSON.stringify(batch));
+            }
+        };
+        // Apply envelopes received from peers.  Peers may send either a single
+        // envelope JSON string or a JSON array of envelope strings (batch format).
+        ws.onmessage = (event) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(event.data);
+            }
+            catch {
+                parsed = null;
+            }
+            if (Array.isArray(parsed)) {
+                for (const env of parsed) {
+                    this._store.apply_envelope(env);
+                }
+            }
+            else {
+                // Fallback: treat the raw frame data as a single envelope string.
+                this._store.apply_envelope(event.data);
+            }
+        };
+        // On close or error the subscription stays active so that writes made
+        // while offline are buffered and flushed when the socket reconnects.
+        ws.onclose = () => { };
+        ws.onerror = () => { };
+    }
+    /**
+     * Schedule a single batch flush for the current frame.  Subsequent calls
+     * before the flush fires are no-ops (only one flush is ever outstanding).
+     *
+     * Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),
+     * falling back to `setTimeout(fn, 0)` in non-browser environments.
+     */
+    _scheduleBatchFlush() {
+        if (this._cancelFlush !== null)
+            return; // already scheduled
+        const doFlush = () => {
+            this._cancelFlush = null;
+            this._flushBatch();
+        };
+        if (typeof requestAnimationFrame === 'function') {
+            const id = requestAnimationFrame(doFlush);
+            this._cancelFlush = () => cancelAnimationFrame(id);
+        }
+        else {
+            const id = setTimeout(doFlush, 0);
+            this._cancelFlush = () => clearTimeout(id);
+        }
+    }
+    /**
+     * Send all pending envelopes as a single JSON-array payload, or move them
+     * to the offline queue if the socket is not currently open.
+     */
+    _flushBatch() {
+        const envelopes = this._pendingEnvelopes.splice(0);
+        if (envelopes.length === 0)
+            return;
+        const ws = this._ws;
+        if (ws.readyState === 1 /* OPEN */) {
+            ws.send(JSON.stringify(envelopes));
+        }
+        else {
+            this._offlineQueue.push(...envelopes);
+        }
+    }
+    // ── Public API ────────────────────────────────────────────────────────
+    /**
+     * Unsubscribe from proxy updates, discard any buffered envelopes, and close
+     * the WebSocket connection.
+     *
+     * Safe to call more than once.
+     */
+    disconnect() {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+        this._cancelFlush?.();
+        this._cancelFlush = null;
+        this._pendingEnvelopes = [];
+        this._offlineQueue = [];
+        this._ws.close();
+    }
+}
+exports.WebSocketManager = WebSocketManager;
+//# sourceMappingURL=WebSocketManager.js.map

package/dist/WebSocketManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketManager.js","sourceRoot":"","sources":["../src/WebSocketManager.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CrdtStateProxy } from './CrdtStateProxy.js';
+export type { WasmStateStore, UpdateEvent, UpdateHandler } from './CrdtStateProxy.js';
+export { WebSocketManager } from './WebSocketManager.js';
+export type { WebSocketLike } from './WebSocketManager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketManager = exports.CrdtStateProxy = void 0;
+var CrdtStateProxy_js_1 = require("./CrdtStateProxy.js");
+Object.defineProperty(exports, "CrdtStateProxy", { enumerable: true, get: function () { return CrdtStateProxy_js_1.CrdtStateProxy; } });
+var WebSocketManager_js_1 = require("./WebSocketManager.js");
+Object.defineProperty(exports, "WebSocketManager", { enumerable: true, get: function () { return WebSocketManager_js_1.WebSocketManager; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AAEvB,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@crdt-sync/core",
+  "version": "0.1.0",
+  "description": "TypeScript proxy wrapper for the crdt-sync Wasm StateStore",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "pkg"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:wasm:bundler": "wasm-pack build ../.. --target bundler --out-dir packages/core/pkg/bundler",
+    "build:wasm:web": "wasm-pack build ../.. --target web --out-dir packages/core/pkg/web",
+    "build:wasm": "npm run build:wasm:bundler && npm run build:wasm:web",
+    "test": "jest",
+    "lint": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.4",
+    "typescript": "^5.4.5"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/__tests__/**/*.test.ts"
+    ]
+  }
+}