@crdt-sync/core 0.1.2 → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,233 @@
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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();
+ * ```
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+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();
+ * ```
+ */
+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;
+}
+
+export { CrdtStateProxy, type UpdateEvent, type UpdateHandler, type WasmStateStore, type WebSocketLike, WebSocketManager };

package/dist/index.d.ts

@@ -1,5 +1,233 @@
-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
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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();
+ * ```
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+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();
+ * ```
+ */
+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;
+}
+
+export { CrdtStateProxy, type UpdateEvent, type UpdateHandler, type WasmStateStore, type WebSocketLike, WebSocketManager };

package/dist/index.js

@@ -1,8 +1,222 @@
 "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; } });
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CrdtStateProxy: () => CrdtStateProxy,
+  WebSocketManager: () => WebSocketManager
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/CrdtStateProxy.ts
+var CrdtStateProxy = class {
+  /**
+   * Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.
+   *
+   * @param store - The Wasm state store instance to proxy.
+   */
+  constructor(store) {
+    this._handlers = /* @__PURE__ */ 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));
+  }
+};
+
+// src/WebSocketManager.ts
+var WebSocketManager = class {
+  /**
+   * 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;
+    this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {
+      this._pendingEnvelopes.push(envelope);
+      this._scheduleBatchFlush();
+    });
+    ws.onopen = () => {
+      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));
+      }
+    };
+    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 {
+        this._store.apply_envelope(event.data);
+      }
+    };
+    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;
+    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) {
+      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();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CrdtStateProxy,
+  WebSocketManager
+});
 //# sourceMappingURL=index.js.map